Eliminating Document Rot with Augment Intent Living Specs

The Master Gift List That Writes Itself 🎄

Willem van Heemstra introduces Augment Intent, a system where Markdown specifications evolve automatically as AI agents commit code. This architecture addresses ‘document rot’ by ensuring the specification remains a living source of truth rather than a static, outdated file.

Why This Matters

Traditional specifications in Confluence or Notion drift immediately upon the first code commit, a phenomenon Fred Brooks called ‘document rot.’ In multi-agent environments, this drift causes integration collapse; Augment Intent transforms the specification from passive documentation into active infrastructure that coordinates specialist agents through shared, versioned interfaces.

Key Insights

• Document rot occurs when static specifications fail to reflect the actual codebase after the first line of code is committed.
• Living Specs in Augment Intent provide Specialist Agents with versioned briefings instead of vague chat histories or summaries.
• The Coordinator Agent drafts initial requirements and success criteria, which are then updated automatically as Specialist Agents complete tasks.
• Constraint propagation ensures that mid-flight changes to the spec trigger immediate re-briefing of all affected agents.
• Machine-executable requirements include explicit success criteria, such as the 200ms route calculation threshold for delivery optimization.

Working Examples

An example of a machine-executable Living Spec used by Augment Intent agents.

## Gift Delivery Optimisation — Living Spec
### Goal
Reduce average per-route delivery time by 20% vs Christmas 2024.
### Success Criteria
- [ ] Route calculation completes in < 200ms
- [ ] Zero missed deliveries in smoke test (1,000 houses)
- [ ] Sleigh fuel consumption unchanged or reduced
### Constraints
- Must work with existing reindeer harness API (v3.2)
- No changes to the chimney-descent module (frozen until Jan)
### Tasks
- [x] Profile current route-calculation bottleneck — Dasher Agent
- [ ] Implement A* pathfinding — Prancer Agent (in progress)
- [ ] Integration test against 2024 route dataset — Blitzen Agent
- [ ] Update delivery manifest schema — Rudolph Agent
### Decisions
- 2025-12-03: Chose A* over Dijkstra for weighted graph support
- 2025-12-05: Excluded Antarctic routes from v1 scope

Practical Applications

• Use Case: Gift Delivery Optimization using A* pathfinding agents to reduce route time while adhering to legacy API constraints. Pitfall: Providing vague goals like ‘make it faster’ leads to misaligned agent execution and integration failure.
• Use Case: Parallel Specialist Agent development where the Living Spec serves as the primary coordination mechanism for shared interfaces. Pitfall: Treating specifications as mere process rather than infrastructure results in conflicting voltages or mismatched power connectors during final assembly.

References:

• https://dev.to/the-software-s-journey/santa-augmentcode-intent-ep2-3fac