plan

# /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 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 **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 Apply in this order: | Signal | Route | |---|---| | No arguments | Ground per step 1; WHEN a draft on the branch carries a state block, resume it; 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 | | 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. ## 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. 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 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. 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 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. ### 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. ### 4. Execute the package Invoke each instrument the route names, 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, 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: 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. ### 6. Implement fork 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. - 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 Δ. - Name instruments and stages in plain words; do not print a gate address of the form `<track>.<stage>`.