Skip to content

Latest commit

 

History

History
243 lines (202 loc) · 20.1 KB

config.md

File metadata and controls

243 lines (202 loc) · 20.1 KB

planning: settings

The key contract for the planning plugin. Every key is optional: with nothing set, each skill runs on the defaults below.

Layers

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.

Keys

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" }

Convention-home keys

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: the plan-reviewer agent and /planning:devils-advocate in plan-review mode when Step 3b's blast radius is MEDIUM or higher or a trigger matches; the plan-reviewer agent also when the user asks for a review. A LOW plan with no trigger runs neither.
  • reviewer: the plan-reviewer agent only, whatever the blast radius.
  • devils-advocate: /planning:devils-advocate only, 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.

Probe topics

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.

Interview page keys

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".

Shared-session keys

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.