plan · diff
git:20261009.29a0515 to git:20261016.6aafe90
52 added, 52 removed. Audit A to A.
---
name: plan
- argument-hint: "[sdd|sources|iso|research] [topic]"
- description: "Plan a feature or initiative through a computed route: the conductor derives the canon delta and assembles the document package — from a zero-document null route for small fixes to an umbrella PRD with one spec per capability for large initiatives. Modes, named as the first word: sdd (full package), sources (MRD → BRD → URD) for market research, customer discovery, and business or user requirements, iso (BRS → StRS → SyRS → SRS) for ISO 29148 and regulated work, research for a technical investigation — never market research — that the research instrument closes either by scope coverage (a research document) or by a recommendation (an rnd). Explicit form: plan research <topic>. Use for 'plan the X redesign', 'create a roadmap', 'plan a new feature', 'I need market research before we plan', 'we're regulated — start the ISO requirements cascade', 'investigate X before we plan', 'compare the alternatives for Y' — a new investigation, not a finished report already in hand. Not for recording a decision or documenting existing code — use /archcore:document. Not for checking docs against code — use /archcore:review."
+ argument-hint: "[topic]"
+ description: "Plan future work, investigate before building, research a topic, or compare the alternatives for a choice. Takes optional free text. The skill reads the request, open drafts, accepted canon, branch, and code, then creates only the documents a later reader needs — none for a small fix. Use for 'plan the X redesign', 'create a roadmap', 'plan a new feature', 'plan the onboarding journey', 'investigate X before we plan', 'compare the alternatives for Y', 'REST or a queue? two teams disagree', 'I need market research before we plan', 'we are regulated — trace the requirements'. With no arguments it resumes an open planning draft or offers what to plan next. Not for recording a decision or documenting existing code — use /archcore:document. Not for checking docs against code — use /archcore:review."
---
# /archcore:plan
- Plan a feature or initiative through a computed route. The conductor
- (`skills/_shared/delta-routing.md`) derives the canon delta Δ, the gap profile
- Π, the zone maturity M, and the risk flags R, then assembles the document
- package; instruments produce the documents. Vision types are the primary
- output. Reads cover all three categories: vision supplies intent and
+ Plan future work from the project context. Context resolution
+ (`skills/_shared/gate-contract.md`, section Context resolution) records the
+ claims, unknowns, hazards, and authority; the conductor
+ (`skills/_shared/delta-routing.md`) selects the documents a later reader needs;
+ instruments produce them. Vision types are the primary output. Reads cover all three categories: vision supplies intent and
resumption targets, knowledge supplies constraints, experience supplies
precedent.
## When to use
- - "Plan the auth redesign" → computed route — typically `capability`: one spec plus one plan
- - "Create a roadmap for the API migration" → computed route
- - "Plan a new feature for CSV export" → computed route
- - "Plan the notifications platform" → computed route — typically `umbrella`: prd, one spec per capability, one plan
- - "I need market research before we plan" → acquisition instrument (`sources` mode)
- - "We're regulated — start the ISO requirements cascade" → iso links (`iso` mode)
- - "Investigate X before we plan" → research instrument, `research`; "Compare the alternatives for Y" → research instrument, `rnd` — a named pending decision or candidate set selects `rnd`, otherwise `research`
- - `plan research <topic>` → research instrument; the instrument selects `research` (closed by scope coverage) or `rnd` (closed by a recommendation) by its closing test
+ - "Plan a new feature for CSV export" → typically one `spec` and one `plan`
+ - "Upgrade the HTTP client across three services with a coordinated rollout" → a `plan` alone
+ - "Plan the notifications platform" → a `prd`, one `spec` per capability, one `plan`
+ - "Fix the typo in the onboarding copy" → no document; implement directly
+ - "I need market research before we plan" → acquisition instrument
+ - "We must trace these requirements for the auditor" → only the requirement levels that obligation names
+ - "Investigate X before we plan" → `research`; "Compare the alternatives for Y" → `rnd`
+ - "REST or a queue for SAP? Two teams disagree", with the facts of both options recorded → `rfc`
+ - `research <topic>` as the first word → the type `research`
**Not plan:**
- Recording a decision → `/archcore:document`
- Documenting existing code → `/archcore:document`
- Codifying a team standard → `/archcore:document`
- Checking documents against code → `/archcore:review`
- ## Route computation
+ ## Entry
Apply in this order:
- | Signal | Route |
+ | Signal | Action |
|---|---|
- | No arguments | Ground per step 1; WHEN a draft carries a state block that this command resumes, resume it — several such drafts follow resume rule 10 in `skills/_shared/gate-contract.md`; otherwise ask one question — what to plan — with a recommendation drawn from the branch changes |
- | The first word is a mode (`sdd`, `sources`, `iso`, `research`) | The mapped instrument per the mode map in `skills/_shared/delta-routing.md`, without route computation |
- | Any other request | Compute Δ, Π, M, and R per the Derivation section of `skills/_shared/delta-routing.md`; its route table decides the package |
+ | No arguments, one draft with a state block this command resumes | Resume it at its earliest incomplete gate |
+ | No arguments, several such drafts | Resume rule 10 in `skills/_shared/gate-contract.md` |
+ | No arguments, a clear request in the session or one unfinished plan | Offer a start menu of at most four items, each with the evidence that names it, the recommended item first |
+ | No arguments and no reliable signal | Ask one question — what outcome to plan; a dirty branch alone is not a target |
+ | The first word is a type slug | The explicit type request per `explicit-type-request-wins.adr`; a leading `research` requests the type `research` |
+ | Any other request | Context resolution, then Selection per `skills/_shared/delta-routing.md` |
| A decision surfaces at a gate | Record the `adr` through the decision instrument (`skills/_shared/tracks/decision.md`), then return to the open gate |
Research boundary: discovery feeding an `mrd` → `brd` → `urd` requirements
chain belongs to acquisition. A request naming a pending decision or a set of
- candidates to choose between produces `rnd`; any other investigation produces
- `research`. The path name `research` selects the instrument, not the type; the
- same test applies. Neither `rnd` nor `evidence` is an entry on this command: an
- `rnd` comes only from that test, the spike, or the compatibility fallback, and a
- standalone material is filed through `/archcore:document research`. A request proposing a specific
- target for team acceptance ("should we switch to Y", "let's adopt Y") belongs
- to `/archcore:document`'s decision instrument.
+ candidates to choose between produces `rnd` only when the evidence to choose
+ is missing; any other investigation produces `research`. WHEN the deciding facts
+ are already recorded and the open part is whose weights win — two owners
+ disagree, or the owner has not chosen — the decision instrument records an
+ `rfc`, and no `rnd` is created. A standalone external material is filed through
+ `/archcore:document`. A request proposing a specific target for team review
+ ("let's adopt Y", "draft an RFC for Y") belongs to `/archcore:document`'s
+ decision instrument; a lone "should we switch to Y" with the evidence to choose
+ missing stays here as `rnd`.
## Execution
### 1. Ground
Complete this step before asking the user any question. The research
vocabulary probe (`skills/_shared/research-compatibility.md`) runs only under
its own condition 1 — a request or type naming `research` or `evidence`, a
- route engaging the research instrument, or a grounding result of either type.
+ selection engaging the research instrument, or a grounding result of either type.
Add `research` and `evidence` to the planning-moment filter below only when
the probe returns `yes`; a topic search without a type filter finds documents
of both types on every engine. If this skill has no shell tool, use the probe
result the host supplied; if none was supplied, report `needs-vocabulary-probe`
with the helper path and stop before the first MCP call that names either type.
The actor-subject probe (`skills/_shared/actor-subject-compatibility.md`) runs
- under its own condition 1 — a request naming `scenario` or `journey`, a route
+ under its own condition 1 — a request naming `scenario` or `journey`, a selection
engaging the illustrate instrument, or a grounding result of either type — and
adds both types to the filter below only when it returns `yes`. The same
no-shell rule applies: report `needs-vocabulary-probe` and stop before the first
MCP call that names either type.
1. Search `.archcore/` with `mcp__archcore__search_documents` and `mcp__archcore__list_documents` across all three categories. Pass a planning-moment type filter — for example `types=["idea", "prd", "plan", "spec", "rnd", "rfc", "adr", "rule", "task-type", "cpat"]` — and add `"scenario"`, `"journey"` when the actor-subject probe returned `yes` — instead of relying on the global type ranking. Do not exclude a category from reads.
2. WHEN a found document carries `implements`, `depends_on`, or `related` relations, pull the linked documents one hop via `mcp__archcore__list_relations` and `mcp__archcore__get_document`.
3. WHEN a found draft on the topic carries an `archcore:track` state block, resume it per the resume rules in `skills/_shared/gate-contract.md` and `skills/_shared/delta-routing.md` instead of opening a new track.
- 4. Read git state — current branch, recent commits, working tree — and the code areas the topic names. Record the concrete files and modules for Step 5, and note zone documents whose referenced paths changed after them — the staleness input to Derivation.
+ 4. Read git state — current branch, recent commits, working tree — and the code areas the topic names. Record the concrete files and modules for Step 5, and note owner documents whose referenced paths changed after them — the staleness input to Selection.
5. IF `.archcore/` exists but contains no documents, THEN proceed on outer-context grounding (git state and the codebase) and report that zero documents were found.
6. IF `.archcore/` does not exist, THEN announce initialization in one line and call `mcp__archcore__init_project` without asking a question.
**Global sources.** If a `list_documents` / `search_documents` result has
`global: true` / `read_only: true` / `source_kind: "global"`, load
`skills/_shared/globals.md`. Also load it when a `search_documents` response's
`coverage` names a source other than `"local"` — even when `results` is empty:
the empty page is exactly where that file's retry ladder applies. Never modify
a global document and never target one with `add_relation`. Absent any global
match, proceed as usual.
- ### 2. Route
+ ### 2. Select
- Compute the route per the Derivation section of
- `skills/_shared/delta-routing.md` and report the route announcement. WHEN the
- first word is a mode, execute its mapped instrument without route computation.
- A route name or a document type name as the first word is topic text; the
- conductor computes the route. Never ask the user to choose a route or a size label.
+ Build the context record per `skills/_shared/gate-contract.md`, section Context
+ resolution, then run Selection per `skills/_shared/delta-routing.md` and report
+ its selection line. Never ask the user to choose an instrument.
### 3. Budget
- Interview mechanics, question form, and ceilings:
- `skills/_shared/elicitation-contract.md`. Auto mode draws every question from
- the shared per-invocation ceiling; a mode entry raises per-gate
- budgets to the maxima the track file declares.
+ Interview mechanics, question form, and the ceiling of 5 questions per
+ invocation: `skills/_shared/elicitation-contract.md`.
- ### 4. Execute the package
+ ### 4. Execute the selection
- Invoke each instrument the route names, in conductor order, per the instrument
+ Invoke each selected instrument, in conductor order, per the instrument
registry and sequencing rules in `skills/_shared/delta-routing.md`. Run each
instrument's gates per `skills/_shared/gate-contract.md`: evaluate `skip_when`
first at every gate, keep track state only in the `archcore:track` block
- inside the draft artifact (with the `route:` and `delta:` fields this command
- adds), persist each gate close in one `mcp__archcore__update_document` call,
+ inside the draft artifact (with the `claims:` field this command adds), persist each gate close in one `mcp__archcore__update_document` call,
and follow the resume rules on re-entry. Gate bodies, per-gate questions, and
relation wiring live in the track files — do not restate them.
Before delegating research or evidence work, pass the current vocabulary probe
result and absolute plugin root to the assistant. If the assistant returns
`needs-vocabulary-probe`, run the helper and resume the same task.
Before delegating any other document write or relation work, pass the absolute
plugin root to the assistant. The assistant reads
`skills/_shared/relation-authoring.md` under that root.
### 5. Map tasks to files
- WHEN the package produced a `plan` document:
+ WHEN the selection produced a `plan` document:
1. Annotate each task in the plan's Tasks section with the concrete files or modules that grounding surfaced for it, using `@path/to/file` notation, in one `mcp__archcore__update_document` call.
2. WHEN grounding surfaced no file or module for a task, state that no target was found for that task. Do not guess a path.
3. Confirm the plan carries its `## Declared Delta` section per sequencing rule 9 of `skills/_shared/delta-routing.md`.
- WHEN the package produced no `plan` document (the `null`, `decision`, and
- `amendment` routes, the acquisition and research paths), skip to Result — the
- exit gate or the announcement names the follow-ups.
+ WHEN the selection produced no `plan` document, skip to Result — the exit gate
+ or the selection line names the follow-ups.
### 6. Implement fork
- WHEN a blocking exit check stopped the route, skip this step and go to Result.
+ WHEN a blocking exit check stopped the selection, skip this step and go to Result.
Otherwise, offer exactly two exits and let the user choose:
- **Implement now** — start on the mapped task list, first phase first, against the files mapped in Step 5.
- **Stop here** — the draft documents and relations stay in `.archcore/`; a later `/archcore:plan` invocation resumes any draft that still carries a state block.
## Result
Report:
- - The route announcement — route, size label, and the Δ, Π, M, R values that produced them.
+ - The selection line, and the inferred scope when no argument set it.
- Produced documents grouped by category — vision, knowledge, experience — with each document's path and status.
- Relations created, plus candidate `mcp__archcore__add_relation` targets among existing documents, or a statement that none match.
- - `retires` entries reported for closeout discharge, when any exist.
- - Next actions, naming only v2 commands: `/archcore:plan` to continue a package, `/archcore:document decision` to record a decision or `/archcore:document code` to document code touched during implementation, `/archcore:review closeout` to check the implementation against the recorded plan and reconcile the declared Δ.
+ - `retire` claims reported for closeout discharge, when any exist.
+ - Next actions, naming only v2 commands: `/archcore:plan` to continue the selection, `/archcore:document <subject>` to record a decision or document code touched during implementation, `/archcore:review` to check the implementation against the recorded plan and reconcile its Declared Delta.
- WHEN contract drafting remains open on a material user-owned choice, name the draft `spec`, the unanswered choice, and the behavior it changes. Do not offer implementation until that check passes. Name the three ways to continue — answer the choice, delegate it ("you decide"), or proceed anyway — and the resume command `/archcore:plan <spec title>`.
- Name instruments and stages in plain words; do not print a gate address of the form `<track>.<stage>`.