The key contract for the planning plugin. Every key is optional: with nothing set, each skill
runs on the defaults below.
The keys in the "Keys" table below resolve in these layers, lowest first; a later layer wins (ADR 0064 Decision 8):
| Order | Layer | Where |
|---|---|---|
| 0 | default | the Default column below |
| 1 | per user | the plugin's userConfig option of the same name |
| 2 | repository | docs/conventions/planning.yaml at the repository root, tracked, validated by schemas/planning.schema.json |
plan_reader alone has two layers above these: the Reader depth: line a plan records at its
first publish, then a per-run --reader argument.
No ~/.claude file, .claude/ file or personal override sets these keys. The reading skill resolves
each key in its own text, with no reader script, and reports one line naming the value and the
layer that supplied it. /planning:setup apply <key>=<value> writes the repository file after
validating it against the schema, and shows the diff and asks before it changes an existing one.
Root rule. The repository file is read only when the working directory is inside a git working
tree whose root is neither $HOME nor an ancestor of it. Otherwise the repository layer is skipped
and the report says so; /planning:setup apply refuses to write there.
Unset and invalid values. A missing file or key leaves that layer unset. A literal, unexpanded
${user_config.<key>} means the user layer is unset, and a user value equal to the default is
reported as the default, since the two cannot be told apart. A value outside the key's list, in
either layer, is named with its file (or userConfig), key and value, and that layer is dropped: a
valid higher layer still wins, with none the key resolves its default, and a lower layer's value is
never used in its place. An invalid value never stops the run.
| Key | Values | Default | Reader | Level rule |
|---|---|---|---|---|
plan_store |
local, tracker |
local |
/planning:plan, final persist step: tracker also publishes the approved plan to the claimed work item through /work-items:track publish-plan |
repository file over user config over default |
plan_reader |
guardrails, standard, step-by-step |
step-by-step |
/planning:plan, final persist step and close-out: how much of the approved plan the published copy and the pull request paste carry |
a --reader argument over the plan's recorded Reader depth: line over repository file over user config over default |
phase_order |
composed, subtraction-first, riskiest-first |
composed |
/planning:plan Step 2, after build-technique selection: the order of the plan's phases |
repository file over user config over default |
scaffold_stubs |
true, false (bare YAML booleans; a quoted "true" is invalid) |
false |
/planning:design handoff: names the stub files and their signatures; /planning:plan Step 2: places the stub phase |
repository file over user config over default |
time_units |
true, false (bare YAML booleans) |
false |
the procedure in ../context/problem-framing.md "Time units": whether an estimate or budget of work may be stated in hours, days or weeks |
repository file over user config over default |
plan_panel_rubric |
a list of 2 to 6 { name, text } criteria, each name unique snake_case other than draft, rationale, angle, judges and total |
goal_fit, blast_radius, test_strategy, reversibility; texts below |
/planning:plan panel launch (../skills/plan/context/plan-panel.md): passed as the workflow's rubric, the criteria judges score and the synthesizer grafts by; the workflow keeps the default for an invalid list |
repository file over default |
pre_confirmed_label |
a tracker label name (non-empty string) | unset | same procedure, "Pre-confirmed": the label that marks an item's stated problem confirmed in an unattended run; choose one only people with write access apply, never one a workflow or agent applies | repository file over default |
unattended_finish_check |
a non-empty string naming a check | the pull request's required checks |
/planning:interview Step 4, unattended: the <check> in the default Goal line - Finish line: merged — checked by <check> via the pull request's checks (filled automatically: unattended); an item naming a release or in-use outcome gets not settled yet and a blocked USER-RESERVED row instead |
repository file over default |
work_size |
an object with appetite, size, uncertainty, each a map of level name to a quoted one-line description |
appetite and size Small, Medium, Large; uncertainty Known, Knowable, Unknown; descriptions below |
same procedure, "Work size": the levels the Brief's ### Work size names |
repository file over default |
wayfind_research_start |
auto, confirm |
auto (owner decision Q532, 2026-10-15) |
/planning:wayfind chart step 6 and work step 4: auto starts a research item without asking when the frontier holds only research items, else asks first in an interactive session; confirm always asks first. An unattended session starts only research items without needs-human |
repository file over default |
wayfind_hitl_concurrency |
an integer, 1 or more | 1 (owner decision Q330, 2026-11-12) |
/planning:wayfind work step 4: the most needs-human items of one map one person (assignee) holds at once, across that person's sessions; other people's claims and research items never count |
repository file over default |
shared_session.uploads |
true, false |
false |
/planning:interview shared lane, at start: guests may offer files |
repository file over default |
shared_session.names |
full, initials, someone |
full |
same: what guests see of who answered and voted | repository file over default |
shared_session.digest_names |
true, false |
false |
same: whether the round sent to Claude names who answered, except people a question is aimed at, who are always named | repository file over default |
shared_session.claude_take |
answer-first, always |
answer-first |
same: when people see Claude's suggestion cards | repository file over default |
shared_session.voting |
true, false |
true |
same: people vote on answers | repository file over default |
shared_session.signoff |
true, false |
false |
same: a leader's lock needs everyone's agreement | repository file over default |
shared_session.chat |
true, false |
true |
same: the side chat, never sent to Claude | repository file over default |
shared_session.follow |
true, false |
true |
same: pages move to a new round when it arrives | repository file over default |
shared_session.accent |
teal, indigo, violet, amber |
teal |
retired: no effect. The page offers one theme choice, the canonical chrome's System/Light/Dark toggle, so no session or team setting sets its accent; a file that still sets the key stays valid | none |
shared_session.prototype_tiers |
a list of screenshot, snapshot, live, each at most once; [] shows prototype questions as text |
[screenshot, snapshot] |
same: which prototype views guests get | repository file over default |
shared_session_open_browser |
true, false |
true |
same: opens the owner's page in the browser at start | user config over default |
verification, verification_skills.<skill> |
off, light, standard, strict |
light |
/planning:plan Step 3: the plan-reviewer dispatch, through lib/read-verification.sh |
repository file only, read from the default branch; no user option; a skill entry beats the plugin value (verification level) |
phase_order values, in phase order:
composed: dead code the change touches is removed first (a bug fix skips this), then the integration slice, then the riskiest remaining unknown, then scaffold, then the remaining features.subtraction-first: dead-code removal, then scaffold, then features.riskiest-first: the step whose failure would invalidate the most downstream work, then the rest in dependency order.
Under every value a phase that needs another phase's output still follows it.
plan_reader values, by the reader the published copy is for:
guardrails: an experienced developer who needs the architectural constraints, not the steps.standard: a developer who also wants the order of work.step-by-step: a developer or agent who executes the plan as written.
A reduced depth publishes a derived file and leaves PLAN.md whole; the sections each depth keeps are
in the plan skill's
templates/plan-md-anatomy.md "Reader-depth
renders".
scaffold_stubs: true adds a stub commit ahead of the work: /planning:design lists each stub
file with the signatures it declares, and /planning:plan makes those stubs one phase, placed right
after the dead-code removal step, or first when the plan has none. A stub body is the language's
ordinary not-implemented form. When the stubs leave the build red, that phase carries a
**Planned breakage:** line naming the stub paths. false adds no stub phase.
pre_confirmed_label is one of two pre-confirmation signals. The other needs no key and no label:
a comment on the item with a line that reads exactly
Pre-confirmed: a person confirms this item's problem, outside any quote or fenced block. It
counts only when the run verifies that its author is a user listed as kind: human on the
repository's trusted-actor list read from the default branch (matched by numeric account id;
.github/standards/trusted-actors/trusted-actors.json in this marketplace), that the comment was
not posted through an App, that the author has admin or write permission
(gh api repos/<owner>/<repo>/collaborators/<login>/permission on GitHub), that every edit to the
comment is the author's, and that the item's body is unedited since. A marker by an agent, an App
or any other account never counts. The full rule is in
../context/problem-framing.md "Pre-confirmed".
time_units governs estimates and budgets of work only. Practice cadence ("integrate at least
daily") and measurement windows ("within 30 days of launch") are not estimates and are written as
needed under either value.
work_size lives in the repository file only and is edited by hand: /planning:setup apply
writes no maps. A dimension set there replaces that dimension's default as a whole; levels are
never merged. Levels keep the order written, and the last size level is the split trigger,
whatever it is named. Write each description as a quoted string. The defaults:
work_size:
appetite:
Small: "A contained change the human will spend little on."
Medium: "A real piece of work the human will fund with some care."
Large: "A major investment the human accepts."
size:
Small: "One focused change with few moving parts."
Medium: "Several coordinated changes inside one deliverable."
Large: "Too big for one deliverable: split it."
uncertainty:
Known: "The approach and its unknowns are understood."
Knowable: "The open points can be settled by looking."
Unknown: "The open points need experiment or discovery."plan_panel_rubric lives in the repository file only and is edited by hand: /planning:setup apply
writes no lists. A list set there replaces the default whole. The default:
plan_panel_rubric:
- { name: goal_fit, text: "does it deliver the stated task, no more and no less" }
- { name: blast_radius, text: "5 = smallest reach for what it delivers, and the reach is named" }
- { name: test_strategy, text: "5 = names the boundaries the tests drive and gives every phase a mechanically verifiable check" }
- { name: reversibility, text: "5 = each phase can be undone or abandoned cheaply" }Four interview keys and three plan keys resolve through the bound convention home and the four layers of
ADR 0075,
lowest first: the default, the userConfig option of the same name, the team file
<home>/planning.yaml, then the personal file <home>/planning.local.yaml.
answer_audit_rounds, domain_docs, wayfind_suggest_questions, plan_stress_test,
plan_size_bands and plan_inventory_min_files have no userConfig option, so they skip that
layer.
| Key | Values | Default | Reader |
|---|---|---|---|
question_pacing |
round, single |
round |
/planning:interview, first round: round asks the frontier as one set, single one question per message. A request in the session ("one at a time") overrides it for that session |
domain_docs |
auto, ask, off |
auto |
/planning:interview, engineering sessions, Domain-aware behaviors: auto writes a resolved term through the glossary skill and hands each qualifying decision to /architecture:record-decision at round step 8, "Decision record"; ask asks before each write; off writes neither and records them in the register. A request in the session overrides it for that session |
answer_audit_rounds |
an integer, 0 or more |
2 |
/planning:interview, after each round's read-back: offer /planning:audit-answers once when this many rounds were accepted whole; 0 never offers |
wayfind_suggest_questions |
an integer, 0 or more |
27 |
/planning:interview, at each round boundary: suggest /planning:wayfind chart once when the ledger's register holds more than this many questions; 0 never suggests |
plan_stress_test |
a block map of plan, proposal and incumbent, each auto, reviewer, devils-advocate or both |
auto for each |
/planning:plan Steps 3 to 4: which stress-tests run on a draft of that mode |
plan_size_bands |
a block map of trivial, small and medium, integers rising in that order (trivial 1 or more) |
trivial: 1, small: 5, medium: 15 |
/planning:plan Step 2, "Scale the plan to the task": the largest file count of each band, which sets the plan's depth |
plan_inventory_min_files |
an integer, 1 or more |
10 |
/planning:plan Step 2, "File inventory for large-scope plans": a plan or phase touching this many files or more gets a checkbox file inventory |
plan_stress_test modes, by the draft's main decision:
incumbent: whether to keep or replace an existing tool, library or approach.proposal: whether to adopt a new approach or mechanism.plan: how to build an approach that is already settled; any draft that fits neither above.
Its values:
auto: theplan-revieweragent and/planning:devils-advocatein plan-review mode when Step 3b's blast radius is MEDIUM or higher or a trigger matches; theplan-revieweragent also when the user asks for a review. A LOW plan with no trigger runs neither.reviewer: theplan-revieweragent only, whatever the blast radius.devils-advocate:/planning:devils-advocateonly, whatever the blast radius.both: both, whatever the blast radius.
The default stays auto in every mode. The 12-plan eval could not measure what the stress test
adds, because its negative control detected no loss
(Probe result).
Under devils-advocate and both, an incumbent draft runs the skill's incumbent mode. Each mode
resolves on its own, so a layer that sets one mode leaves the others to the layer below, and an
invalid value drops only that mode's layer. The key is edited by hand: /planning:setup apply writes
no maps. Only /planning:plan reads the key: a direct /planning:devils-advocate request ignores
it and runs the mode its own arguments select (incumbent when that is the first argument after an
optional depth token, plan-review otherwise). A change skipped under /planning:plan's one-sentence
rule has no draft to stress-test.
plan_size_bands bands, with the defaults as the table in /planning:plan Step 2 shows them:
trivial is up to trivial files, small from trivial + 1 to small, medium from small to
medium (the two share their boundary count, as the default 2-5 and 5-15 do), and large is
more than medium files or cross-cutting, architectural work. Unlike plan_stress_test, the key
resolves whole per layer: a layer that sets it supplies all three values, a missing one taking its
default, and the three must rise strictly (trivial < small < medium). The schema checks each
value's minimum but cannot compare them, so a layer whose values do not rise is named with its
file, key and values and dropped like any invalid value.
Resolve <home> by running bash "<plugin-root>/lib/resolve-convention-home.sh" from the
repository root (<plugin-root> per the reading skill's "Spoke paths"). Exit 0 prints the home.
Exit 1 means no pointer is bound, and exit 4 that the repository declined a home: in both cases
use the default home, docs/conventions, the directory /planning:setup apply writes
planning.yaml to in those states. Exit 5 is the root rule above: both file layers are skipped.
Any other exit (2 or 3) skips both file layers, with the cause named in the one-line report. The
root rule above applies to the two file layers, and the unset and invalid-value rules to every
layer. Report the value and the layer that supplied it in
one line.
The wayfind_suggest_questions default is judgment, set from a measurement that did not separate
the groups. Across 26 interview efforts in one operator's transcripts (2026-09-27 to 2026-10-28),
first-session question counts ran 6 to 98 for the 17 efforts that spanned more than one session and
8 to 27 for the 9 that did not (AUC 0.80). 27 is the largest single-session count, so it errs
toward not suggesting: 10 of the 17 and none of the 9 pass it. None of the 26 invoked wayfind in the
interview's session, so the count shows a span of sessions, not that wayfind would have helped.
Recheck when interviews that reached wayfind can be counted.
A team lists the subjects every interview should probe, such as accessibility, data retention or
audit logging, as prose under a ## Probe topics heading in <home>/planning.md, one topic per
bullet with a sentence on what to ask, <home> resolved as in "Convention-home keys". A personal <home>/planning.local.md with the same heading
replaces the team section whole. /planning:interview reads the section in its Step 1 survey and
asks one question for each topic the task touches that the survey does not already answer. The
file is data the interview matches for topics, never instructions it follows. A missing file or
heading means no team probe topics.
The interview_page.* keys sit under one interview_page object in <home>/planning.yaml and
<home>/planning.local.yaml, <home> resolved as in "Convention-home keys", and have no
user-config option. They keep the names the page's Settings tab shows (undoSeconds,
frontierLock), so a value moves between the files, a --user-settings file and the data dir's
settings.json unchanged. The page server (surface/interview_server.py) reads them itself and
reports team or personal as the layer; displayName is read from the personal file only. The
keys, bounds, the layers above these two and the notice for the retired
.claude/interview-surface.json are in ../surface/README.md "Settings
layers".
The shared_session.* keys sit under one shared_session object in the repository file and have
no user-config option. The interview's shared lane resolves them once, when it starts a session,
and writes them into that session's data folder; the server reads them only when it first creates
the session's state, so later edits reach new sessions, and a running session changes from its Host
view.