Skip to content
groundworkDocs

The loop

8 skills, installed by kit init. 5 steps run in order around every feature; 5 more run when something goes wrong.

The feature folder

Every step writes into one folder, so the next step and the next session start from files, not from the conversation.

context/features/NN-slug/
  • spec.md
  • plan.md
  • log.md
  • review.md
  • handoff.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.

In order

Each description is the skill's own, read from its SKILL.md.

  1. 1

    Open the work

    Open and close the loop around a piece of work. start creates the branch, the feature folder and the spec; finish refuses to close while any "done when" criterion lacks evidence, then opens the PR. Use at the beginning and end of every feature.

    /feature start NN

    Writes spec.md

  2. 2

    Decide before building

    Think through what you are about to build like a senior engineer before writing any code. Surfaces the decisions that change the implementation and writes plan.md into the feature folder. Use before any non-trivial feature.

    /architect

    Writes plan.md

  3. 3

    Build it

    Decisions and evidence, written as they happen.

    Writes log.md

  4. 4

    Check it with fresh eyes

    Verify a finished feature against its spec and the project's rules, with fresh eyes. Runs the cheap automated checks first, then reviews in a subagent that sees only the spec, plan, diff and rules, and writes review.md. Use before /feature finish.

    /review

    Writes review.md

  5. 5

    Close it, or don't

    Refuse to close on anything unfinished. The point of this half is that it's harder to skip than remembering would be.

    /feature finish

Without slash commands

The commands are Claude Code's way in. The loop itself is files and a branch, so any agent can run it by reading the skills.

In a harness with no slash commands the skills are still installed in .claude/skills/ — they are instructions, not code. Point the agent at the skill for each step and ask it to follow that file:

  1. 1

    Open the feature

    “Follow .claude/skills/feature/SKILL.md, the start section, for feature 03.” It cuts feat/03-slug and writes context/features/03-slug/spec.md.

  2. 2

    Decide before building

    “Follow .claude/skills/architect/SKILL.md for feature 03.” It writes plan.md and waits for your confirmation.

  3. 3

    Build, logging evidence

    Build against the plan, writing decisions and how each done-when criterion was checked into log.md as it happens.

  4. 4

    Review with fresh eyes

    “Follow .claude/skills/review/SKILL.md.” If the harness can't start a subagent, start a new session that is given only the spec, plan, diff and rules.

  5. 5

    Close it, or don't

    “Follow the finish section of .claude/skills/feature/SKILL.md.” It still refuses a criterion with no evidence line.

When needed

Not part of the sequence. Each one exists because a specific thing kept going wrong.

  • Across sessions

    /remember

    Save session state to the active feature's handoff.md at the end of a session, or restore it at the start of the next one. Use when a feature spans more than one session.

  • When a fix doesn't take

    /recover

    When something goes wrong during a build, diagnose what type of failure it is before deciding how to respond. Targeted fix, hard reset, or full rethink — the right response depends on the right diagnosis. Use when a problem persists after one corrective attempt.

  • So it's only paid for once

    /harvest

    Promote something learned the hard way into knowledge/, tagged project, stack or universal, so the next project doesn't pay for it twice. Use when a tool behaved differently than documented, or at /feature finish.

  • Keep composition consistent

    /imprint

    After building a UI section, capture how registry primitives were composed — or how a custom component chose among contract tokens — and save it to ui-registry.md, so the next one matches. Use after building any UI, not just once at the end.

  • How app screens look and behave

    app-ui

    How a groundwork app's signed-in screens look and behave — the sidebar shell, instant navigation with loading skeletons, fixed-height paged tables, row actions in an icon menu, CRUD in modals, stat strips and panels. Read before building or reviewing any admin, dashboard, portal or other app screen.

The rule with teeth

/feature finish will not close a feature while any done when criterion lacks a line in log.md saying how it was checked: browser, SQL, script or test.

Not verified is an answer. Silence is not.

A line that says not verified, because the staging data has no failed payment yet closes the criterion. A blank one stops the close.