PlanningWhat should we build, before any code exists?

01What is loaded, and when it is paid for

A skill arrives in three stages and each costs something different. Almost every design rule in this repository follows from that asymmetry rather than from taste.

02The 9 skills

Each owns one kind of work and states it in its own Owns section. The tags under it are the facets recorded in planning-registry/capabilities.yaml, which is also what the fixtures route against.

03Where a skill stops

Boundaries live in one file and never in a description. A description that named its neighbours would spend listing budget advertising them, and adding a skill would mean editing every other one — so the cost of an addition would stop being O(1).

04Chains that recur

A chain of names expresses linear work only. Where a stage repeats until a condition holds, the entry carries the condition, the judge, and a hard cycle limit — without all three, “until it looks right” has no stopping rule and the loop ends when somebody gets tired.

05The mechanism this set has and its siblings do not

Seven sets share one validator and one contract shape. Each declares exactly one signature mechanism, and that declaration is the whole difference — which is what keeps 7 copies of the same rules from becoming 7 dialects.

06What counts as done

Reporting completion without meeting this is reporting a wish. The vocabulary is fixed in planning-registry/harness.yaml and defined in _planning/CONTRACT.md; the validator checks the contract actually defines every word it declares.

07Permission classes

A class is declared once in the registry and the validator checks each SKILL.md front matter matches it exactly. Where a CLI does not enforce tool grants, the Never lines are discipline and nothing more — that limit is stated rather than papered over.

08Budgets, and the rules that decide them

Every threshold is declared in one place and read from there by planning-tools/validate.py. A number written twice is a number that drifts. Raising a limit is the last resort — merging, deleting, compressing and relocating come first.

09Installing it

Each planning-* directory is symlinked individually, so a skills directory keeps whatever else it already carries and a name already taken by a real directory is skipped rather than overwritten.

make link                       # into ~/.claude/skills
make link CLAUDE_DIR=.claude/skills

make check                      # the rules, then proof the rules still fire
make render                     # after editing a delivered block
make hooks                      # run the rules on every commit

• Selection happens on the description alone. Every word that selects a skill appears literally in its description, and a rule checks the registry and the description still agree.
• Contracts are delivered, not referenced. A rule kept only in _planning/ is read on a minority of launches, so the operative part is copied verbatim into every skill and a rule fails if any copy has drifted.
• Knowledge is split by whether it rots. Playbooks hold judgement and are budgeted; reference holds what goes stale, carries no line budget, and states what re-checks it instead of a bare date.
• The fixtures do not model how a model chooses. They catch a missing or duplicated signal. Passing them is not evidence that nothing will be misrouted.