Progressive Disclosure
The loading strategy that keeps harness context usable
Progressive disclosure routes context from root to leaf.
The harness uses markdown indexes and scoped guidance to move vertically through the repository until the agent reaches the leaf that owns the work.
That vertical path keeps context usable. The agent should not start with every possible rule, note, source file, and workflow. It follows the tree, then activates the skills and evidence needed at that leaf.
Progressive disclosure enables granular context: the leanest useful context set for the current task, with the best performance tradeoff the harness can provide.
This is correctness work, not just ergonomics. Root-to-leaf loading keeps broad policy available while letting local ownership override it where the repo is more specific. Late activation means a skill, package source, memory note, or runbook enters the run when it can change a decision, which reduces token pressure and stale assumptions.
Root To Leaf Path
The agent follows this default path:
- Start at shared or root guidance.
- Follow indexes or scoped
AGENTS.mdfiles toward the owning repo area. - Activate the skills named by that scope or task.
- Read the source and evidence needed for the current decision.
- Add memory notes or external source only when they change the decision.
- Stop when the next action is clear and verifiable.
When To Load More
The agent loads additional context when:
- the scoped guidance names mandatory skills
- the task crosses ownership boundaries
- a page or runbook claims a behavior that source does not confirm
- a dependency API or framework convention could change the implementation
- the user references prior decisions, backlog state, or memory
- validation fails and the failure has multiple possible causes
It should not load more just because material exists. It loads more when the next decision would otherwise rely on assumption.
The tradeoff is deliberate: load too little and the agent guesses; load too much and the model must sort current signal from old or irrelevant rules. Progressive disclosure gives the run a repeatable reason for crossing that boundary.
Phase Routing
Phase wrappers follow the same rule. A wrapper such as delivery-phase may name the expected lifecycle, but it should load only the router module at entry, then one selected phase module. Existing fresh specs and plans are verified and reused before creation skills are loaded.
Completion of a phase writes resumable handoff state. A later invocation can resume from that state instead of replaying earlier phases.