Concepts

A groundwork plan is a folder of numbered, living documents. You give the skill a goal; it scaffolds the spine; then each action fills and maintains it in place.

The spine

plans/my-feature/
├── .groundwork.json        ← identity + state anchor (read by every action)
├── 00-README.md            ← what's here + read order
├── 01-plan.md              ← the authoritative spec
├── 02-research-external.md ← cited outside research
├── 03-research-internal.md ← cited inside-the-project research (path:line)
├── 04-discussion.md        ← newest-first "Round N" decision log
├── 05-tracking.md          ← work packages + dependencies + status
├── 09-orchestration.md     ← multi-agent kickoff (generated by orchestrate)
└── artifact/
    ├── index.html          ← living spec (opens in any browser)
    └── board.html          ← the plan board (generated by refresh-board)

Focused sub-plans (NN-*.md, numbered ≥ 06) can be scaffolded for a hard piece — a diff plan for a critical PR, a decision doc, or a bug postmortem. See Actions → subplan.

Living, not write-once

The folder is a living spec, not a one-shot prose dump. Edits land as the work converges: research is augmented in place, the discussion log gets a new Round per review, tracking checkboxes flip as work lands. Crucially, everything you hand-write is sacred — every action writes only inside marked regions, never your prose.

Generated-region fences

The one mechanism by which an action modifies an existing file:

Hand-written introduction — never touched.

<!-- groundwork:auto:start research-summary -->
(generated content — an action owns this block)
<!-- groundwork:auto:end research-summary -->

Hand-written follow-up — never touched.

Outside the fences is yours. Inside is owned by exactly one action, which recomputes the block, hashes it, and rewrites only if it changed. That’s what makes “augment, never overwrite” a property of the tool rather than a behaviour you hope the model remembers — see State model.