plan

Files (1)

• SKILL.md

SKILL.md (first lines)

# /archcore:plan

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 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`

## Entry

Apply in this order:

| Signal | Action |
|---|---|
| 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` 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
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 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 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. Select

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 the ceiling of 5 questions per
invocation: `skills/_shared/elicitation-contract.md`.

### 4. Execute the selection

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

From archcore-ai/archcore, Apache-2.0.

More from archcore-ai/archcore