@specship/specship 0.11.0

package/commands/ss-behaviour.md

@@ -0,0 +1,116 @@
+---
+description: Author end-to-end tests for a requirement from its acceptance criteria — a Playwright UI test and/or a backend/batch API test per criterion — preview and confirm before writing, link each test to its .A<N> criterion, then run them and record pass/fail into the spec→test→verify chain.
+argument-hint: <REQ-ID>
+allowed-tools: Read, Edit, Write, Bash, mcp__specship__specship_spec, mcp__specship__specship_explore, mcp__specship__specship_search, mcp__specship__specship_node, mcp__specship__specship_link_assert, mcp__specship__specship_link_verify
+---
+
+# SpecShip Behaviour: `$ARGUMENTS`
+
+Turn a requirement's **acceptance criteria** into runnable **end-to-end tests** —
+a Playwright UI journey and/or a backend/batch API test for each criterion — and
+feed the results into the spec→test→verify chain that `specship check` gates on.
+
+You author and run the tests; SpecShip supplies the flow map and records the
+verification state; **the human gates the write**. This is distinct from
+`/ss-implement` (which writes the *feature* code) — `/ss-behaviour` writes the
+*tests* that prove the requirement behaves.
+
+**Governing principle — propose, never auto-apply.** Test files reach disk ONLY
+after explicit human confirmation (step 4). Running them afterwards is
+non-destructive and proceeds automatically. If the human does not confirm, you
+write **nothing**.
+
+If `$ARGUMENTS` is empty, ask which requirement to test (or use `specship_spec`
+with a `query` to find it).
+
+## 1. Load the requirement + its criteria
+
+Call `mcp__specship__specship_spec` with the `spec_id`. Read the requirement and
+its **acceptance criteria** (the `.A<N>` children) — each criterion is one
+behaviour to test (REQ-BEHAVIOUR-002.A1).
+
+## 2. Get the behaviour surface
+
+Call `mcp__specship__specship_spec` with the `spec_id` **and
+`behaviour_surface: true`**. It returns the requirement's linked code plus the
+surrounding routes / components / handlers, grouped into:
+
+- a **UI tier** — Playwright targets, and
+- a **backend / batch tier** — API / job test targets.
+
+An empty UI tier means the project (or this requirement) has no UI surface — you
+will author backend/batch tests only (REQ-BEHAVIOUR-002.A4). Use
+`specship_explore` / `specship_node` on any surface element whose flow you need
+to understand before writing the test.
+
+## 3. Detect the project's test conventions
+
+Before writing anything, ground in how this repo already tests, and **mirror it**
+(REQ-BEHAVIOUR-002.A3) — never impose a stack:
+
+- UI: look for a Playwright config / an `e2e/` dir and its file naming.
+- Backend: find the runner in use (vitest / jest / pytest / go test / …) and the
+  test file layout.
+
+Use `specship_explore` on existing test files (e.g. `*.spec.ts`, `*.test.*`,
+`e2e/`) and read a couple to match their style, fixtures, and import paths.
+
+## 4. Plan, preview, confirm — then write + link
+
+For **each acceptance criterion**, plan the end-to-end test(s)
+(REQ-BEHAVIOUR-002.A1 / A2):
+
+- If the criterion touches a **UI flow** → a Playwright test exercising it.
+- If it touches a **backend/batch path** → an API/batch test.
+- If it touches **both** → one of each.
+
+Each test's title and file must name the `.A<N>` criterion it covers, so a
+failure is traceable to a criterion.
+
+**Preview the exact test files** (path + full contents) you will create and ask
+for explicit confirmation, offering `confirm` / `edit` / `cancel`
+(REQ-BEHAVIOUR-003.A1). **Write nothing until confirmed.**
+
+On confirmation:
+1. Write the test files (mirroring the detected conventions). A re-run of
+   `/ss-behaviour` on the same requirement **refreshes** existing tests rather
+   than duplicating them (REQ-BEHAVIOUR-003.A3).
+2. For each test, call `mcp__specship__specship_link_assert` with
+   `kind: "tests"`, targeting the **`.A<N>` criterion** it covers
+   (REQ-BEHAVIOUR-003.A2). Keep the returned `link_id` for step 5.
+3. Run `specship sync` and confirm the criteria + links index cleanly
+   (REQ-BEHAVIOUR-003.A4).
+
+## 5. Run the tests, record the outcome
+
+Run the relevant suite(s) with the project's runner (via `Bash`), then record
+each result through `mcp__specship__specship_link_verify` (REQ-BEHAVIOUR-004):
+
+- a test that **runs and passes** → `result: "pass"` (link → `verified`),
+- a test that **runs and fails** → `result: "fail"` with the failure in `reason`
+  (link → `broken`),
+- a suite that **could not be executed** (missing dependency, no dev server,
+  wrong environment) → **report it as unrun and do NOT call link_verify** for
+  those tests — leaving the link state unchanged. A test that didn't run is never
+  recorded as `broken` (REQ-BEHAVIOUR-004.A2).
+
+## 6. Hand off
+
+Summarize: which criteria now have `verified` / `broken` / unrun tests, and the
+behaviour-gate status. The links now feed `specship check`'s behaviour gate
+unchanged (REQ-BEHAVIOUR-004.A3): a `broken` link fails the gate when behaviour
+gating is on; a requirement with no `verified` test is reported as unverified.
+For a failing behaviour, fix the feature with `/ss-implement`, then re-run
+`/ss-behaviour` (or just re-run the test and `specship_link_verify`).
+
+## Anti-patterns
+
+- **Writing test files before confirmation** — the one hard rule (step 4).
+- **Marking a test `broken` when it never ran** — that false-fails the CI gate
+  (step 5).
+- **Imposing a test stack** the repo doesn't use — mirror the existing
+  conventions (step 3).
+- **Writing feature code** — that's `/ss-implement`. `/ss-behaviour` writes
+  tests, runs them, and records the result.
+- **Generating Playwright tests when there's no UI** — the UI tier will be empty;
+  author backend/batch tests only.

package/commands/ss-check.md

@@ -0,0 +1,43 @@
+---
+description: Gate & health door — run the enforcement gate, review the drift queue, repair a drifted/broken/orphaned link, or see code-health. No arg = the gate; `drifted`/`fix`/`relink`/`health` run the matching flow.
+argument-hint: "(no arg = gate) | drifted | fix <SPEC_ID> | relink <SPEC_ID> | health"
+allowed-tools: Bash, mcp__specship__specship_drifted, mcp__specship__specship_spec, mcp__specship__specship_link_verify
+---
+
+# SpecShip Check: `$ARGUMENTS`
+
+The **gate & health door** — verify intent against code and keep the spec↔code
+links honest. Route on the first token of `$ARGUMENTS`.
+
+## Dispatch
+
+- **(no argument)** → run the enforcement gate:
+  ```bash
+  specship check
+  ```
+  Composes spec↔code drift, architecture fitness, maintainability, and the
+  spec→test→verify behaviour chain. Strictly opt-in gating — with no `enforce`
+  config it only advises and exits 0. Summarize the gated failures, if any.
+- **`drifted`** → the review queue: call `mcp__specship__specship_drifted`
+  (optional `state` filter) for links that are drifted (spec or code changed),
+  broken (verification failed), or orphaned (target symbol gone).
+- **`fix <SPEC_ID>`** → repair a drifted/broken link via the bundled workflow:
+  ```bash
+  specship workflow run spec-fix --input SPEC_ID=<ID>
+  ```
+  Diagnoses (spec hash vs code signature vs failing test) → approve → apply →
+  `specship_link_verify` back to `verified`.
+- **`relink <SPEC_ID>`** → for an **orphaned** link (the target symbol no longer
+  exists): re-point it at the symbol's new location/name, then re-assert.
+- **`health`** → graph-derived code health:
+  ```bash
+  specship maintainability
+  ```
+  Shows the high-precision findings (oversized symbols, god files, dependency
+  cycles), ranked and capped. Add `--deep` for the lower-confidence dead-code and
+  coupling findings; `--json` for the full tagged set (CI).
+
+## After running tests against a spec link
+
+Report the outcome with `mcp__specship__specship_link_verify`
+(`result: "pass" | "fail"`) so the link moves to `verified` (or `broken`).

package/commands/ss-design-implement.md

@@ -0,0 +1,84 @@
+---
+description: Import a Claude Design (or Figma) file, snapshot it for zero-loss reference, draft a SpecShip spec, and hand off to /ss-spec implement.
+argument-hint: <Claude-Design-URL> [SLUG]
+allowed-tools: Read, Write, Edit, Bash, mcp__specship__specship_explore, mcp__specship__specship_search, mcp__specship__specship_node, mcp__specship__specship_spec, mcp__specship__specship_files
+---
+
+# SpecShip Design → Spec → Implement: `$ARGUMENTS`
+
+> **Already settled on a design?** This command imports it by URL. If you instead want to *run
+> the taste loop first* — iterate variants with the human via the `designer` MCP and only then
+> spec the chosen one — use **`/ss-design-loop`**, which drives the loop and hands the resulting
+> bundle to this same workflow via its `HANDOFF_DIR` input.
+
+Run the bundled `claude-design-implement` workflow against the Claude Design URL in `$ARGUMENTS`. The workflow:
+
+1. **Snapshots** the design source byte-for-byte into `specs/<slug>/snapshot.html` (zero-loss fidelity layer).
+2. **Records the import** in `specs/<slug>/source.md` (audit trail — URL, project ID, date, original prompt verbatim).
+3. **Extracts design tokens** into `specs/<slug>/tokens.css`, mapped onto your project's existing token system where possible.
+4. **Drafts a spec** at `specs/<slug>.md` covering behavioural contract, accessibility, responsive, interaction states, and data shape — **without** pixel values or hex colors (those stay in the snapshot + tokens).
+5. **Pauses at an approval gate** for you to walk the `[needs review]` markers and gap-fill questions.
+6. **Writes the spec** and `specship sync`s it into the graph.
+7. **Hands off** with the next command: `/ss-spec implement <first REQ ID>`.
+
+## How to invoke
+
+Parse `$ARGUMENTS`. The first token must be a Claude Design URL of the form:
+
+```
+https://claude.ai/design/p/<project-id>/?file=<File+Name>.html
+```
+
+Optional second token is the slug (kebab-case directory name). If omitted, derive from the `file=` query param (e.g. `Data+Flow.html` → `data-flow`).
+
+Then run:
+
+```bash
+specship workflow run claude-design-implement \
+  --input CONNECTOR_URL="<URL>" \
+  --input FILE_LABEL="<File Name>" \
+  --input SLUG="<slug>"
+```
+
+(Add `--input OWNER="<team>"` and `--input PRIORITY="high|medium|low"` if you want them populated in the spec frontmatter; otherwise they're marked `[needs review]` and surfaced in the gap-fill step.)
+
+## Why the four-file pattern
+
+The workflow produces four files in `specs/<slug>/` rather than a single spec. This is deliberate:
+
+| File | Role | Drift-tracked? |
+|---|---|---|
+| `snapshot.html` | Byte-for-byte design capture | No (frozen reference) |
+| `source.md` | Import audit record | No (metadata) |
+| `tokens.css` | Design tokens — CSS variables | No (reference data) |
+| `specs/<slug>.md` | Contract: REQs, acceptance criteria | **Yes — drift gate on this** |
+
+Specs that name pixel values flag drift on every theme tweak; specs that name token symbols (`MUST use --error`) survive token-value changes silently. The split keeps the drift queue meaningful.
+
+## After the workflow finishes
+
+You get a hand-off message listing the REQs. Run:
+
+```
+/ss-spec implement <REQ-XXX-001>
+```
+
+The implementation phase reads:
+- `specs/<slug>.md` for what to build
+- `specs/<slug>/snapshot.html` for how it should look
+- `specs/<slug>/tokens.css` for which design tokens to wire up
+
+This is what preserves visual fidelity — the snapshot is on disk and the implementer reads it directly. The spec layer enforces contract; the snapshot layer guarantees fidelity.
+
+## When the designer iterates
+
+Re-run `/ss-design-implement` with the same URL. The workflow re-snapshots, re-drafts, re-prompts for approval — keeping existing REQ IDs stable so any in-flight implementation work survives the iteration. `git diff` on the snapshot tells you exactly what changed visually; `git diff` on `specs/<slug>.md` tells you what changed contractually.
+
+## Anti-patterns
+
+- **Don't put hex codes in the spec.** Reference tokens by name. The values live in `tokens.css`.
+- **Don't delete the snapshot after implementation.** It's the durable reference if the Claude Design URL ever goes 404.
+- **Don't paraphrase the snapshot.** Save byte-for-byte. Summarising loses detail that the implementation step would otherwise have used.
+- **Don't skip the approval gate.** The workflow's value is the gap-fill questions surfaced there — answering them is what closes the "no details lost" gap on the things a static design can't show (failure modes, real-time updates, keyboard order).
+
+If `$ARGUMENTS` is empty or doesn't look like a Claude Design URL, ask the user for the URL before running the workflow.

package/commands/ss-design-loop.md

@@ -0,0 +1,125 @@
+---
+description: Run the full design→code loop — taste a claude.ai/design with the human via the designer MCP, then snapshot → spec → review → hand off to /ss-spec implement. Two human gates.
+argument-hint: [intent — what you want to design]
+allowed-tools: Read, Write, Edit, Bash, mcp__specship__designer_session, mcp__specship__designer_prompt, mcp__specship__designer_ask, mcp__specship__designer_list, mcp__specship__designer_snapshot, mcp__specship__designer_handoff, mcp__specship__specship_explore, mcp__specship__specship_search, mcp__specship__specship_node, mcp__specship__specship_spec, mcp__specship__specship_files
+---
+
+# SpecShip Design Loop: `$ARGUMENTS`
+
+One continuous pipeline: **intent → taste → design → handoff → spec → `/ss-spec implement`**.
+You (the orchestrator) drive `claude.ai/design` through the `designer` MCP while the
+**human tastes** the variants, then promote the chosen design into a SpecShip spec via the
+bundled `claude-design-implement` workflow. Two human gates:
+
+- **Gate 1 (aesthetic):** the human says *"that's it"* in the taste loop. Driven here, conversationally.
+- **Gate 2 (contract):** the human walks the spec's `[needs review]` markers at the workflow's approval gate.
+
+This is the deeper companion to `/ss-design-implement` — that command imports a design you've
+*already* settled on (by URL); this one runs the taste loop first, then hands the resulting
+bundle to the same workflow. `$ARGUMENTS` is the human's opening intent (optional).
+
+## Preflight
+
+1. **Designer runtime ready?** The designer tools are part of SpecShip's MCP now
+   (`mcp__specship__designer_*`), so they're always present. Probe the *runtime* with
+   `designer_session({ action: "status" })`: a clean status means you're ready. If it errors
+   with "CDP not up" or "Not signed in", the one-time Chrome setup hasn't run — tell the human to
+   run `designer setup` (creates the debug-Chrome profile + login) and stop. Do NOT fall back to a
+   blind fetch; the taste loop needs the live browser.
+2. **SpecShip initialized?** `specship status` should succeed. If not, `specship init -i` first.
+
+## Phase A — Taste loop (Gate 1)
+
+Follow the **`designer-loop` skill** (`~/.claude/skills/designer-loop/SKILL.md`) — it is the
+authority on this loop. The condensed version, if the skill isn't installed:
+
+> The human is the designer; Claude Design has taste; you are translation + plumbing. Don't
+> propose your own variants, don't interview about aesthetics — scope questions only.
+
+1. **Read the room — capabilities drive the design.** Before relaying any intent, survey the
+   target repo for what it actually *does* and feed that into the prompt verbatim. Use
+   `specship_explore` / `specship_search` to pull: entities + their fields, operations /
+   endpoints, states (loading / empty / error / success), failure modes, hard constraints
+   (auth, rate limits), and existing design tokens. The human's intent tells Claude *how*; the
+   codebase tells it *what*. Transfer capability facts unabridged — summarizing is filtering.
+2. **Create / resume the session.** `designer_session({ key: "<slug>", action: "create",
+   name: "<seed intent>", fidelity: "highfi" })`. Reuse a stable `key` derived from the intent
+   so parallel loops don't collide.
+3. **Relay a minimal, faithful prompt.** `designer_prompt({ key, prompt })` — intent +
+   capability facts; let Claude's taste make the aesthetic calls. Ask for the variant shape you
+   want ("3 full-page files", "states as toggles") and lock any hard brand tokens explicitly.
+4. **Hand the human the URL** returned in `url`. That live surface has working tweak sliders and
+   the variant switcher — it is the default taste path. Ask *"what do you think?"*, not
+   "accept or reject?".
+5. **Interpret + iterate.** Translate each reaction into the next `designer_prompt` (or a cheap
+   `designer_ask` to consult Claude on a small adjustment). Repeat 3–4 until the human says
+   **"that's it."** Capture their final reaction verbatim — it goes in the record.
+
+Stay in the loop until Gate 1 is explicitly passed. "Almost" is not "yes."
+
+## Bridge — promote the chosen design
+
+1. `designer_handoff({ key, openFile: "<chosen variant>.html" })`. This fetches the project
+   export zip into `./artifacts/<key>/handoff-<ts>/` — `project/*` (all variants + assets) plus
+   `decision-record.md` (the verbatim transcript + the human's final reaction). Note the
+   **absolute path** of that `handoff-<ts>/` directory and the **chosen variant filename**.
+2. Derive `FILE_LABEL` (human label) and `SLUG` (kebab-case) from the chosen file / intent. If
+   the slug is ambiguous, ask the human — one scope question, not an interview.
+
+## Phase B — Spec pipeline (Gate 2)
+
+Run the bundled workflow against the bundle on disk (no re-fetch, no CDP):
+
+```bash
+specship workflow run claude-design-implement \
+  --input HANDOFF_DIR="<absolute path to handoff-<ts>/>" \
+  --input CHOSEN_FILE="<chosen variant>.html" \
+  --input FILE_LABEL="<File Label>" \
+  --input SLUG="<slug>" \
+  --json
+```
+
+(Add `--input OWNER="<team>"` / `--input PRIORITY="high|medium|low"` to populate frontmatter;
+otherwise they default to empty and surface as `[needs review]`.)
+
+The workflow runs headless to its approval gate, then **pauses** (status `paused`). It:
+snapshots `project/<chosen>.html` byte-for-byte into `specs/<slug>/snapshot.html`, folds
+`decision-record.md` into `specs/<slug>/source.md`, extracts `specs/<slug>/tokens.css`, and
+drafts the spec.
+
+**At the pause (Gate 2):** read the run's approval message / the drafted spec artifact, present
+it to the human, and walk the `[needs review]` markers + gap-fill questions together. Then:
+
+- **Approve:** `specship workflow approve <runId> --comment "<gap-fill answers>"` then
+  `specship workflow resume <runId>`. The answers are captured into the spec.
+- **Needs changes:** collect the feedback and re-run the workflow (a reject cancels the run;
+  existing REQ IDs are preserved across re-imports, so in-flight work survives).
+
+## Phase C — Hand off to implementation
+
+When the workflow completes it prints the bridge message. Relay it to the human:
+- the spec path `specs/<slug>.md` and its REQ IDs,
+- the reference files (`snapshot.html`, `tokens.css`, `source.md`),
+- the exact next step: **`/ss-spec implement <first REQ ID>`**.
+
+Remind them: the implementer reads `snapshot.html` for visual fidelity — the spec is
+contract-only.
+
+## Anti-patterns
+
+- **Skipping the capability survey.** Designing before reading what the repo *does* produces
+  designs that look good and don't fit. Phase A step 1 is load-bearing.
+- **Proposing your own variants / interviewing about taste.** Claude Design proposes; you relay.
+  Scope questions only.
+- **Auto-promoting.** Don't `designer_handoff` on every iteration — only once Gate 1 passes.
+- **Re-fetching in the workflow.** Always pass `HANDOFF_DIR` (the bundle you just fetched), never
+  `CONNECTOR_URL` — that re-drives Chrome from a headless subprocess and is fragile. The URL path
+  is what `/ss-design-implement` is for.
+- **Putting hex/pixels in the spec.** Reference tokens by name; values live in `tokens.css`.
+- **Skipping Gate 2.** The gap-fill questions are where the static design's blind spots (failure
+  modes, real-time updates, keyboard order) get closed.
+
+If `designer_session` errors with a CDP / sign-in problem, stop and route the human to
+`designer setup` (debug-Chrome profile + login) — this command cannot run the taste loop without
+the live browser. To import a design you've already settled on by URL, use
+`/ss-design-implement <url>` instead.

package/commands/ss-explore.md

@@ -0,0 +1,43 @@
+---
+description: Reads door — explore a codebase region, trace a flow, or get a change's blast radius. Name the symbols you care about; for a flow name both ends; for impact ask "what breaks if I change X".
+argument-hint: <symbols | flow from→to | "impact of X">
+allowed-tools: mcp__specship__specship_explore, mcp__specship__specship_node, mcp__specship__specship_search, mcp__specship__specship_callers, mcp__specship__specship_callees, mcp__specship__specship_impact
+---
+
+# SpecShip Explore: `$ARGUMENTS`
+
+The **reads door** — one entry for every "understand the code" question. Pick the
+behaviour from what `$ARGUMENTS` describes; you do not need a separate command.
+
+## With no arguments — a flow worth trying first
+
+When `$ARGUMENTS` is empty, first run `specship starter-prompt`. If it prints a
+line, surface it to the user as **"A flow worth trying in this repo: `<line>`"** —
+a concrete starter question they can ask to see retrieval in action — then show
+the guidance below. If it prints nothing, just show the guidance below. (It
+deliberately prints nothing once you've already used retrieval this session.)
+
+## Explore an area / "how does X work" (default)
+
+Call `mcp__specship__specship_explore` with `$ARGUMENTS` as a bag of symbol names
+(include `Class.method` qualified forms when given). It returns the relevant
+symbols' source grouped by file, plus any flow it can synthesize between them.
+Treat the returned source as already Read — do NOT re-Read files. If a god-file
+truncates, run `specship_explore` again with a tighter symbol bag rather than
+reaching for Read. For one symbol's full body (or an overloaded name), call
+`mcp__specship__specship_node` — it returns every overload in one call.
+
+## Trace a flow — "how does X reach Y / the path from X to Y"
+
+Call `specship_explore` naming the symbols that span the flow (e.g.
+`mutateElement renderScene`). It surfaces the call path among them, riding
+dynamic-dispatch hops (callbacks, React re-render, JSX children) that grep can't
+follow. Use `specship_search` first if you only have a partial name.
+
+## Blast radius — "what breaks if I change X"
+
+`mcp__specship__specship_impact` on the symbol for the transitive dependents;
+`specship_callers` / `specship_callees` for one hop in either direction.
+
+The index is kept fresh automatically; force a re-index with the `specship sync`
+CLI if a recent edit isn't reflected yet.

package/commands/ss-spec.md

@@ -0,0 +1,118 @@
+---
+description: Intent door — view, author, fast-path, implement, review, or extend a spec. No arg = the spec funnel; a SPEC_ID = that spec's detail; `new`/`fast`/`implement`/`review`/`triage`/`behaviour`/`domain` run the matching flow.
+argument-hint: "<SPEC_ID> | new <desc> | fast <desc> | implement <ID> | review <ID> | triage <prompt> | behaviour <ID> | domain"
+allowed-tools: Read, Edit, Write, Bash, mcp__specship__specship_spec, mcp__specship__specship_node, mcp__specship__specship_explore, mcp__specship__specship_search, mcp__specship__specship_link_assert, mcp__specship__specship_link_verify
+---
+
+# SpecShip Spec: `$ARGUMENTS`
+
+The **intent door** — one entry for the whole spec lifecycle. Route on the first
+token of `$ARGUMENTS`; everything the old `ss-spec*` / `ss-implement` / `ss-triage`
+/ `ss-behaviour` / `ss-domain` commands did is reachable here, with no capability
+lost.
+
+## Dispatch
+
+- **(no argument)** → call `mcp__specship__specship_spec` with no `spec_id`: the
+  project's spec lifecycle funnel (brainstormed ideas → specs → implemented).
+- **a bare `SPEC_ID`** (e.g. `REQ-AUTH-005`) → call `specship_spec` with that
+  `spec_id`: the body, parent/siblings, and linked code with state. Use this
+  before Read-ing the spec file. Jump into linked code via `specship_node`; if
+  nothing is linked yet, `specship_explore` on terms from the spec's title.
+- **`new <description>`** → the full, gated authoring loop (see *Author* below).
+  Use when the design isn't settled.
+- **`fast <description>`** → the **fast-path** (see below).
+- **`implement <SPEC_ID>`** → run the bundled workflow:
+  `specship workflow run spec-implement --input SPEC_ID=<ID>` (plan → approve →
+  implement → verify → link, in an isolated worktree).
+- **`review <SPEC_ID>`** → a read-only rubric pass (see *Review* below); no edits.
+- **`triage <prompt>`** → the triage flow (route a bug / error / one-line
+  enhancement to the existing spec it belongs to and append to it): see below.
+- **`behaviour <SPEC_ID>`** → author + run E2E tests from the requirement's
+  acceptance criteria; see below.
+- **`domain`** → capture a human-confirmed domain fact; see below.
+
+## Author (`new <description>`)
+
+The gated authoring loop, run conversationally — diverge, then formalize. Write
+NOTHING to disk until the human explicitly confirms.
+
+1. **Scope + ground.** Confirm it's one feature area (refuse "spec the whole
+   app"). Call `specship_explore` on terms from the description to find where
+   similar features live and which files the work will touch.
+2. **Diverge.** Propose 2–3 distinct approaches with trade-offs, lead with a
+   recommendation, and clarify the things the graph can't tell you (UX, edge
+   cases, non-goals) **one question at a time**. Iterate until the direction is
+   settled.
+3. **Draft + write.** On confirmation, `Write` `specs/<slug>.md` in the
+   `spec-author` format: frontmatter (id/title/owner/priority), `<!-- id: -->`
+   markers above every heading, an RFC-2119 keyword per requirement title, one
+   concern per requirement, `## Acceptance` with `.A<N>` bullets (happy +
+   failure). Mark genuinely-unknowable points `[needs review]`.
+4. **Hand off:** `specship sync`, then `/ss-spec review <ID>` and
+   `/ss-spec implement <ID>`.
+
+(If a richer authoring skill — e.g. `spec-author` — is available in this
+environment, prefer it; this inline flow is the always-present fallback.)
+
+## Review (`review <SPEC_ID>`)
+
+Read-only — do NOT modify the file. Fetch the spec (`specship_spec`), verify each
+`implementations:` path exists (`specship_node`), then walk the rubric and output
+a numbered findings list grouped **STRUCTURAL** (embedded id markers, no stranded
+ids, unique ids, valid frontmatter, valid `implementations:`), **QUALITY**
+(RFC-2119 keywords, no weasel words, no implementation leak, testable acceptance,
+one concern per REQ, failure-path coverage), **HYGIENE** (owner/priority set, no
+stale `[needs review]`/TODO). End with a one-line verdict.
+
+## Fast-path (`fast <description>`)
+
+For a solo dev who wants to record intent and move, **without** the brainstorm /
+gap-question interview (REQ-DOORS-002):
+
+1. Ground briefly with `specship_explore` on terms from the description (one call).
+2. Draft a complete spec in memory following the `spec-author` format — frontmatter
+   (id/title/owner/priority), `<!-- id: -->` markers above every heading, an
+   RFC-2119 keyword per requirement, `## Acceptance` with `.A<N>` bullets (happy +
+   failure). Pick sensible defaults instead of asking; mark only genuinely
+   unknowable points `[needs review]`.
+3. `Write` it to `specs/<slug>.md` and tell the user the path.
+4. Hand off: `specship sync`, then `/ss-spec implement <ID>` when ready.
+
+The fast-path still produces a well-formed spec that indexes cleanly and is ready
+for implementation + linking — it trades the interview for speed, not correctness.
+
+## Triage (`triage <prompt>`)
+
+Classify the input (bug / error log / enhancement). Retrieve candidates: prose →
+`specship_spec` with a `query`; an error log → parse the `file:line`/symbol →
+`specship_explore`/`specship_node` → the owning requirement. Present the ranked
+match + recommended target. **Preview the exact diff → confirm** (offer edit /
+new-spec / cancel), then append a new requirement (new concern) or a new `.A<N>`
+acceptance criterion (a regression an existing requirement should have covered),
+auto-deriving the next collision-checked id, and `specship_link_assert` it. When
+nothing clears the match floor, say so and offer `/ss-spec new` instead — never
+auto-create. Write nothing until confirmed.
+
+## Behaviour tests (`behaviour <SPEC_ID>`)
+
+Pull the requirement's acceptance criteria and its behaviour surface
+(`specship_spec` with `spec_id` + `behaviour_surface: true` → UI tier / backend
+tier). For **each** acceptance criterion, author a Playwright test when a UI
+exists and/or a backend test, mirroring the repo's existing test conventions.
+**Preview the files → confirm → write**, then `specship_link_assert … kind:tests`
+at the `.A<N>`, run the suite, and `specship_link_verify` each (pass→verified,
+fail→broken; a suite that can't run is reported unrun, never marked broken).
+
+## Domain fact (`domain`)
+
+Run `specship domain-gaps --json` for the real undocumented entities/specs, ask
+targeted per-type questions, and **only on explicit confirmation** `Write` a
+`domain`-kind fact under `specs/domain/` (frontmatter `id: DOM-<AREA>-NNN`,
+`type:` one of term/rule/decision/constraint, linked via `depends_on`/`parent_id`).
+Then `specship sync`.
+
+## After editing code for a spec
+
+Call `mcp__specship__specship_link_assert` before reporting done — idempotent, and
+it supersedes the `// @implements REQ-X` comment backstop.

package/dist/activation/starter-prompt.d.ts

@@ -0,0 +1,57 @@
+/**
+ * First-run starter-prompt generation (ACTIVATION-DOC).
+ *
+ * Manufactures one perceivable retrieval moment: a concrete flow/impact question
+ * naming real symbols from THIS repo, derived from a flow verified to connect in
+ * the graph. A botched first impression is worse than none, so generation never
+ * emits a flow whose endpoints don't connect and never sources a flow from a
+ * god-file's fan-out; when no good flow exists it falls back to an impact
+ * question (which needs only one real symbol and can't fail to connect).
+ *
+ * Graph access is behind `GraphProbe` so the selection policy is unit-testable;
+ * `generateStarterPrompt` wires the real probe over a live `SpecShip` graph.
+ */
+import type { SpecShip } from '../index';
+export interface StarterPrompt {
+    kind: 'flow' | 'impact';
+    /** The ready-to-ask prompt naming real symbols. */
+    prompt: string;
+    from: string;
+    to?: string;
+}
+export interface GraphProbe {
+    /** Entry points worth tracing from (routes / high-fan-in), god-files excluded. */
+    entryCandidates(): Array<{
+        name: string;
+        file: string;
+    }>;
+    /** Trace an entry to a reachable leaf; null if it reaches nothing useful. */
+    traceFlow(entry: {
+        name: string;
+        file: string;
+    }): {
+        to: string;
+        hops: number;
+        files: string[];
+        synthesized: boolean;
+    } | null;
+    /** Highest-fan-in non-god-file symbol, for the impact fallback. */
+    topFanInSymbol(): {
+        name: string;
+        file: string;
+    } | null;
+}
+/**
+ * Choose the starter prompt. Pure: a flow across ≥2 files over a multi-hop path
+ * wins; otherwise an impact question on the busiest symbol; otherwise null.
+ */
+export declare function selectStarterPrompt(probe: GraphProbe): StarterPrompt | null;
+/** A short or generic name that would make an unconvincing starter prompt. */
+export declare function isNoiseName(name: string): boolean;
+/** Test/fixture/build files — never the source or sink of the manufactured moment. */
+export declare function isUninterestingFile(file: string): boolean;
+/** Build a `GraphProbe` over a live SpecShip graph. */
+export declare function realProbe(cg: SpecShip): GraphProbe;
+/** Generate the starter prompt for a live project, or null if none fits. */
+export declare function generateStarterPrompt(cg: SpecShip): StarterPrompt | null;
+//# sourceMappingURL=starter-prompt.d.ts.map

package/dist/activation/starter-prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"starter-prompt.d.ts","sourceRoot":"","sources":["../../src/activation/starter-prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAGzC,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,GAAG,QAAQ,CAAC;IACxB,mDAAmD;IACnD,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,UAAU;IACzB,kFAAkF;IAClF,eAAe,IAAI,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACzD,6EAA6E;IAC7E,SAAS,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG;QAChD,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,EAAE,MAAM,EAAE,CAAC;QAChB,WAAW,EAAE,OAAO,CAAC;KACtB,GAAG,IAAI,CAAC;IACT,mEAAmE;IACnE,cAAc,IAAI;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CACzD;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,UAAU,GAAG,aAAa,GAAG,IAAI,CAiB3E;AAiBD,8EAA8E;AAC9E,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEjD;AAED,sFAAsF;AACtF,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAKzD;AAcD,uDAAuD;AACvD,wBAAgB,SAAS,CAAC,EAAE,EAAE,QAAQ,GAAG,UAAU,CAqFlD;AAED,4EAA4E;AAC5E,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,QAAQ,GAAG,aAAa,GAAG,IAAI,CAExE"}