The Feature-Docs Hierarchy

Why a Hierarchy, Not Just a Folder

Most "docs live next to the code" setups start well and rot fast: a docs/ folder that nobody updates, a spec that drifts from what actually shipped, a status field nobody trusts because three different people update it three different ways.

The feature-docs hierarchy is an attempt to make that rot structurally hard. Every planning artifact — references, specs, implementation reports — lives under feature-docs/ at the repo root, organized into four tiers that mirror how long a decision stays true, one Git branch per shippable increment, and a status model split into two fields that are never allowed to be conflated.

It's implemented as a set of Claude Code skills (/feature-docs-hierarchy, /scaffold-implementation-docs, /grill-me, /spec-creator, /tdd, /pr-merged, /pr-rejected) that read and write a canonical CLAUDE.md section, addressed by §anchor rather than by paragraph number — so the process itself is diffable and versionable, the same way the code is.

The Gate Before Anything Runs

Before /feature-docs-hierarchy does anything — bootstrap a fresh project or upgrade an existing one — it checks four preconditions. All four must hold, or it names the failure and stops. It never fixes one on its own; each is a deliberate human action.

1. Repo initialized. .git exists. Absent → the human runs git init and makes a first commit.
2. Working tree clean. git status --porcelain is empty. A dirty tree aborts with the specific reason, telling the human to stash or commit first. HEAD can be on any branch — as of v8 this no longer requires already being on main.
3. Remote configured and reachable. origin is set and git ls-remote origin succeeds — merging only ever happens via pull request, which needs a remote to mean anything.
4. Baseline .gitignore exists. Created if absent, but only in bootstrap mode — upgrade mode checks, never invents one for an established project.

The trunk requirement used to be stricter: HEAD had to already be on main before the skill would run at all. That turned out to be pure friction with no matching safety benefit — so as of v8 the skill handles trunk itself. It fetches, checks out main, applies the template update, commits it there locally (never pushes — that's still the human's call), and checks back out whatever branch you started on. The one thing that still has to hold is a clean tree, because an uncommitted diff silently riding along into a trunk-side commit is a real risk the branch requirement never actually prevented.

Upgrades Are Version-Gated

feature-docs/README.md carries a Changelog/Versioning section: a single integer template version. Upgrade mode reads it first, before touching anything else in the tree.

The section is skill-managed, the same way the Features table is — nobody hand-edits either. As of v8, the structural update pass also locates any pre-v8 shared/ folder still sitting around and migrates its contents automatically — see below.

Four Tiers, One Folder Each

Every document lives at the tier where it stops being true. Through v7 this was a shared/ wrapper directory split into references/, documentation/, scripts/, and fixes/ subfolders at each tier. As of v8 that split is gone: each tier is one explicitly-named folder, and everything that used to be scattered across those four subfolders goes into it.

feature-docs/
  README.md                    # root signpost — Features table + Changelog/Versioning
  references-root/             # root tier — true regardless of feature
  <feature-name>/
    README.md                  # feature signpost
    references-feat/           # true for every implementation of this feature — auto
    <implementation-name>/     # ↔ branch impl/<feature>/<implementation>
      README.md                # implementation signpost
      ITERATIONS.md             # implementation status + per-iteration rows
      references-impl/          # true for every iteration of this implementation
      iter-1/                   # ↔ commit(s) + tag iter-1-done
        references-iter/  specs/  implementation-reports/
      iter-2/  ...

Choosing the right tier for a reference document is a recursive test, applied outward:

All three of root-, feature-, and implementation-tier are auto-scaffolded. Root-tier feature-docs/references-root/ is created by /feature-docs-hierarchy in both bootstrap and upgrade mode. Feature-tier <feature>/references-feat/ and implementation-tier <feature>/<impl>/references-impl/ are created by /scaffold-implementation-docs at scaffold time, and backfilled by /feature-docs-hierarchy's upgrade mode for any pre-existing feature or implementation whose folder is entirely missing (folder creation only — an already-existing folder, even partially populated, is never touched). In every case, files placed inside a reference folder are project data — the skills only ever manage the folders' existence, never their contents.

One Branch Per Implementation

The implementation folder and its branch, impl/<feature>/<implementation>, are created together by /scaffold-implementation-docs — never one without the other. An iteration is not a branch: it's a commit closed out with an annotated tag, iter-N-done, on that same branch.

All iterations on one branch surface as a single PR — review is QA-style over the whole implementation, not diff-style per iteration.

There's exactly one carve-out from "no skill pushes to trunk": /feature-docs-hierarchy committing its own governance files — feature-docs/README.md, the CLAUDE.md section, the installed skill files — directly to local main, per the gate section above. It still never pushes, and it never touches feature code. Everything else stays PR-only.

Two Layers of Status, Never Conflated

Iteration status is local and informational. Implementation status is what actually drives the feature rollup. Keeping them as two separate fields — rather than inferring one from the other — is what makes the rollup trustworthy.

Note there's no fourth "rejected" state — rejection isn't terminal, it's just this implementation still being unfinished. /pr-rejected logs the QA feedback and automatically starts the next iteration on the same branch.

The Rollup Reads Implementation Status Only

feature = AND( impl-status₁, impl-status₂, … impl-statusₙ )

All implementations ✅ complete → the feature reads ✅ complete. One holdout, anywhere, and the feature reads 🔄 in-progress — recomputed by /pr-merged every time it fires, never copied forward.

The Cycle, End to End

1. Create the feature folder by hand. mkdir -p feature-docs/<feature> — manual, on purpose, after the git gate holds.
2. Scaffold — /scaffold-implementation-docs creates the implementation folder and the impl/<feature>/<implementation> branch together. Implementation status starts 🔄 in-progress. Recomputes the root Features table.
3. Sync from main, every time — fetch and merge origin/main before anything else this iteration, even on iteration 1.
4. Reference doc — capture findings in iter-N/references-iter/<topic>.md.
5. Grill — /grill-me, mandatory. Never fires on its own; must be invoked explicitly, every iteration, before a spec gets written.
6. Spec — /spec-creator writes to iter-N/specs/spec.md, self-reviews with senior-code-review.
7. Implement — /tdd works from the reviewed spec; final act tags iter-N-done and writes the report. Does not open a PR, does not touch implementation status.
8. Repeat 3–7 for as many iterations as the implementation needs, all on the same branch.
9. Open the PR — when iterations look implementation-ready: push the branch, open the PR, set implementation status to 👀 in-review with the PR link recorded.
10. QA, then record the outcome. QA happens outside this hierarchy. Merged → /pr-merged <branch>. Rejected → /pr-rejected <branch>, which auto-starts the next iteration on the same branch.

Signposts, Not Copies

The process lives in exactly one place — the ## Feature Documentation Workflow section of CLAUDE.md, addressed by §anchor. Every README in the tree is a signpost, not a copy: where you are, current status, the one next action, and a link to the specific anchor that governs this moment.

Skills Catalogue

The hierarchy doesn't try to automate the parts that are genuinely a human's call — opening a PR, confirming what happened to it. It automates everything reversible in between, and gets out of the way at every boundary that isn't.