Skip to content
groundworkDocs

Context

A project's architecture, written down before there is code to describe. It is what an agent reads before it touches anything.

The shape

A few files at the top, then one folder per numbered feature. The number matches the branch and the build plan entry.

your-project/context/
  • features/
    • 01-slug/
      • spec.md
    • README.md
  • architecture.md
  • build-plan.md
  • code-standards.md
  • library-docs.md
  • progress.md
  • project-overview.md
  • ui-registry.md
  • ui-rules.md
Use the arrow keys to move. Right expands a folder, left collapses it or climbs to its parent. Home and End jump to the ends, and typing a letter jumps to the next name starting with it.

A new project gets its house style from kit init and its project-overview.md, architecture.md and build-plan.md from the kickoff prompts. Groundwork's own folder is the one these docs are written from.

A folder per feature

Work used to leave a plan in chat, decisions in a tracker, and evidence nowhere. The tracker reached 450 lines and stopped being read.

One folder per feature gives every decision somewhere to live, so progress.md can go back to a status block and a checklist. When the feature merges, its folder merges with it.

Writing criteria

A spec's done when list is the part with teeth, so it is the part worth getting right. Write each one so someone who wasn't there could check it.

Can't be checked by anyone else

Filtering works.

Can

Selecting a status narrows the table and the count updates.