@gobing-ai/spur 0.3.41 → 0.3.42

package/plugins/sp/skills/spur-cli/references/features/verbs.md

@@ -0,0 +1,122 @@
+---
+name: feature-verbs
+description: Per-verb flag detail, JSON shapes, and the four check layers for spur feature.
+see_also:
+  - spur-cli
+---
+
+# `spur feature` — verb detail
+
+Ground truth for every `spur feature` verb. The CLI is the source of behavior; this mirrors it. If
+a flag isn't listed, it doesn't exist.
+
+## `create <name>`
+
+Allocate a feature with a hierarchical ID (DD-14) under the create-lock (serialized allocation;
+fail-loud).
+
+| Flag | Effect |
+| ---- | ------ |
+| `--parent <id>` | Child gets the next free digit 1–9 under `<id>`. Omit for a top-level letter ID. |
+| `--folder <path>` | Target a non-default features folder. |
+| `--json` | Emit `{ ref: { id, filePath } }`. |
+
+## `show <id>` / `list`
+
+- `show <id>` prints frontmatter + body.
+- `list` filters by `--status <s>` and/or `--priority <p>`. `--json` emits an array.
+
+## `update <id> [status] | --field <key> --value <v> | --section <name> --from-file <path>`
+
+Multi-mode. At least one of status, field pair, or section pair is required (exit `2` otherwise).
+
+- **Status** (positional): legal transition over `backlog → active → verifying → blocked → done →
+  cancelled`. `verifying` is the AC-traceability gate. **One active goal** corpus-wide (enforced by
+  `check`).
+- **Field** (`--field` requires `--value`): set a single frontmatter scalar, e.g.
+  `--field priority --value P1`.
+- **Section** (`--section` **requires** `--from-file`): replace the entire named section body from a
+  file (same file-wins contract as `spur task update --section`).
+
+## `advance <id>`
+
+Walk the legal **forward** lifecycle path hop-by-hop until a target status.
+
+| Flag | Effect |
+| ---- | ------ |
+| `--to <status>` | Target status (default `done`). Forward path: `backlog → active → verifying → done`. |
+| `--folder <path>` | Custom features folder. |
+| `--json` | Emit `{ id, status, hops: [{ from, to }, …] }`. |
+
+No-op (success) when already at the target. Exit `1` if the feature is missing or a hop is illegal.
+
+## `move <id>`
+
+Re-parent a subtree. `--parent <new>` cascade-renames `<id>` and **every descendant** to the new
+position; omit `--parent` to lift the subtree to a top-level group. Use this for any structural
+change — never hand-edit an ID, which would orphan descendants and break edges.
+
+| Flag | Effect |
+| ---- | ------ |
+| `--parent <id>` | New parent (omit → top-level group). |
+| `--dry-run` | Show old→new ID map + affected tasks without writing. |
+| `--folder` / `--json` | Standard. |
+
+## `refresh`
+
+Rebuild **derived docs only**: `INDEX.md` and each feature's `## Tasks` auto-gen region from task
+`feature_id` edges (WBS / title / status). **Files win** for that region; Goal/Scope/AC and feature
+`status` are untouched. Run after task create/link/done or hand-edits that leave the roster stale.
+
+| Flag | Effect |
+| ---- | ------ |
+| `--feature <id>` | Rewrite only that feature's `## Tasks` (INDEX.md still fully regenerated). |
+| `--folder` / `--json` | Standard. |
+
+**vs `sync`:** `refresh` never changes lifecycle status and never runs transition guards.
+
+## `sync [id]`
+
+Align a feature's **frontmatter status** with linked task states. Derives a proposal and, unless
+`--dry-run`, applies legal lifecycle hops (e.g. all tasks terminal → toward `done`; reopened work →
+reopen). Real transitions — gates (dogfood for self-referential workflow features, one-active-goal,
+L4 readiness) may deny a hop.
+
+| Flag | Effect |
+| ---- | ------ |
+| `[id]` / `--all` | One feature, or every feature that has linked tasks (one required). |
+| `--dry-run` | Report proposal only; no write. |
+| `--force` | Apply a *reopen* (backward) proposal without interactive confirmation. |
+| `--folder` / `--json` | Standard. JSON: `{ proposal, applied, appliedHops[] }`. |
+
+**vs `refresh`:** `sync` never rewrites INDEX.md or `## Tasks` tables.
+
+## `check [id]`
+
+The four-layer validator. Bare = whole tree; with an ID = one feature. `--strict` elevates warnings
+to failures. `--json` emits per-feature findings.
+
+| Layer | Checks | Severity |
+| ----- | ------ | -------- |
+| **L1** | Zod frontmatter schema | hard error |
+| **L2** | Section-Status-Matrix presence (required sections per status) | warning-first; `gate:true` sections are hard |
+| **L3** | Format rules — BDD AC syntax, one-active-goal, children-limit (≤ 9, corpus-derived) | mixed |
+| **L4** | Traceability — incoming `feature_id` edges, orphan scenarios, coverage orphans, `verifying` readiness | warning-first |
+
+A finding carries `{ layer: 'L1'|'L2'|'L3'|'L4', section, severity, message }`. Parse the JSON to
+answer "is H2 ready for `verifying`?" or "which scenarios have no task?" — the rules are CLI code,
+not prose to restate. This is the gate `sp:spur-dev`'s planning half loops on.
+
+## Command surface (quick)
+
+```
+spur feature create  <name> [--parent <id>] [--folder] [--json]
+spur feature show    <id> [--folder] [--json]
+spur feature update  <id> [status] [--field <k> --value <v>] [--section <n> --from-file <p>] [--folder] [--json]
+spur feature advance <id> [--to <status>] [--folder] [--json]
+spur feature list    [--status <s>] [--priority <p>] [--folder] [--json]
+spur feature move    <id> [--parent <id>] [--dry-run] [--folder] [--json]
+spur feature refresh [--feature <id>] [--folder] [--json]
+spur feature sync    [id] | --all [--dry-run] [--force] [--folder] [--json]
+spur feature check   [id] [--strict] [--folder] [--json]
+```

package/plugins/sp/skills/spur-cli/references/features.md

@@ -0,0 +1,234 @@
+---
+name: spur-cli-features
+description: "spur-cli noun reference: operate `spur feature` as the project's feature CLI — author features with hierarchical IDs (DD-14), write acceptance criteria the validator and decomposition both read, drive the feature lifecycle, move subtrees, and keep traceability honest. The intent-and-AC side of the planning layer that the spine orchestrates against."
+see_also:
+  - spur-cli
+---
+
+# spur feature — the feature CLI
+
+`spur feature` is the CLI for the **feature tree** — the markdown feature files that capture intent
+(`Goal` / `Scope`) and acceptance criteria, organized by hierarchical IDs (DD-14). Features are the
+*why* and *what-done-looks-like*; tasks (see `spur task`) are the *how*.
+
+This is a **companion reference**, not an orchestrator. It documents *what each verb is* and *how
+to author features and AC well*. The end-to-end loop that turns a vague intake into a feature, AC,
+and a decomposed task batch lives in **`sp:spur-dev`** — do not reimplement that loop here (R3).
+When you need to *drive* planning, reach for `sp:spur-dev`; when you need to know *which verb does
+what* or *how to write a scenario*, this skill.
+
+## Verb map
+
+| Verb | Purpose | Key flags |
+| ---- | ------- | --------- |
+| `create <name>` | Allocate a feature; assigns a hierarchical ID under the create-lock | `--parent <id>` `--folder` `--json` |
+| `show <id>` | Print one feature's frontmatter + body | `--folder` `--json` |
+| `update <id> [status]` | Lifecycle transition, scalar field set, **or** section replace | `--field <k> --value <v>` `--section <n> --from-file <p>` `--folder` `--json` |
+| `advance <id>` | Walk forward along the legal lifecycle path to a target status | `--to <status>` (default `done`) `--folder` `--json` |
+| `list` | List features, filtered | `--status <s>` `--priority <p>` `--folder` `--json` |
+| `move <id>` | Re-parent a subtree (cascade-rename of descendants) | `--parent <id>` `--dry-run` `--folder` `--json` |
+| `refresh` | Rebuild INDEX + each feature `## Tasks` table from task edges (**docs only**; no status change) | `--feature <id>` `--folder` `--json` |
+| `check [id]` | Validate one feature / the tree; the 4-layer gate | `--strict` `--folder` `--json` |
+| `sync [id]` | Align feature **lifecycle status** with linked task states (real transitions + guards) | `--all` `--dry-run` `--force` `--folder` `--json` |
+
+**`refresh` vs `sync` (do not conflate):**
+
+| Need | Verb |
+| ---- | ---- |
+| Stale `## Tasks` roster / INDEX after tasks finished or linked | `refresh` |
+| Feature frontmatter `status` should follow task statuses | `sync` (preview with `--dry-run`) |
+
+`refresh` never runs lifecycle gates. `sync` never rewrites the Tasks table — run both when you need both.
+
+All verbs accept `--json` and `--folder <path>`.
+
+## Hierarchical IDs (DD-14)
+
+Feature IDs are positional: a top-level feature is a letter (`H`), a child appends one digit per
+level (`H1`, `H2`, then `H21`, `H22`). Rules the CLI enforces — you don't restate them, you let
+`create` and `check` apply them:
+
+- One digit per level; **≤ 9 children** per parent (the corpus-derived limit `check` flags as L3).
+- The parent of an ID is that ID with its **last character dropped** (`H21` → `H2` → `H`).
+- `create --parent H2` takes the **next free digit 1–9** under `H2`; allocation is serialized by
+  the create-lock so concurrent creates never collide.
+
+```bash
+spur feature create "Planning layer" --parent H      # → H<n>
+spur feature create "Task CLI" --parent H1            # → H1<n>
+```
+
+To restructure, use `move` — never hand-edit an ID. `move <id> --parent <new>` re-parents the
+subtree and **cascade-renames** every descendant; omit `--parent` to lift it to a top-level group.
+
+**Before create or restructure (judgment, not CLI):** load
+[features/hierarchy-mece.md](features/hierarchy-mece.md) — MECE sibling sets, **sparse cautious
+roots**, extend-vs-create decision procedure, merge vs reparent, depth/width limits. `/sp:dev-plan`,
+`/sp:dev-idea`, and `/sp:dev-featurechange` must follow that checklist so new work prefers an
+existing parent over a new letter.
+
+## Editing a feature: status, fields, and sections
+
+`update` is multi-mode (status, field, and/or section — not all require mutual exclusion, but each
+mode needs its own required args).
+
+**Lifecycle transition** (positional status):
+
+```bash
+spur feature update H2 active
+```
+
+Valid statuses: `backlog → active → verifying → blocked → done → cancelled`. The lifecycle engine
+enforces legal transitions; `verifying` is the gate where AC traceability must hold (L4).
+**One active goal** at a time is enforced by `check` (a corpus invariant).
+
+**Scalar field set:**
+
+```bash
+spur feature update H2 --field priority --value P1
+```
+
+`--field` requires `--value`. This sets a single frontmatter scalar (e.g. `priority`).
+
+**Section replace** (file-wins, same contract as `spur task update --section`):
+
+```bash
+spur feature update H2 --section "Acceptance Criteria" --from-file /tmp/ac.md
+```
+
+`--section` **requires** `--from-file` (exit `2` otherwise). Replaces the whole named section body.
+The `## Tasks` block is still rebuilt by `refresh` (files win for that region).
+
+**Advance** (multi-hop forward walk):
+
+```bash
+spur feature advance H2              # walk forward until done (default)
+spur feature advance H2 --to verifying
+```
+
+Walks the legal forward path (`backlog → active → verifying → done`) hop-by-hop until `--to`
+(default `done`). No-op when already at the target.
+
+## Acceptance criteria conventions
+
+AC is the contract `check` validates and decomposition maps tasks against. Author scenarios in the
+feature's `## Acceptance Criteria` as Gherkin.
+
+### R-numbering
+
+Every scenario carries an `R1, R2, …` prefix in its title:
+
+```gherkin
+Scenario: R1 — User can create a task with required fields
+Scenario: R2 — Task creation fails gracefully on missing title
+```
+
+- **Sequential within a feature** — start at R1 per feature.
+- **Stable forever** — never renumber after tasks are created; a new scenario takes the next free
+  number. (Tasks reference AC by *scenario title*, normalized — the R-prefix is stripped on match —
+  so a renumber silently breaks coverage.)
+- **One R-number = one scenario** — never split a requirement across scenarios under one R-number,
+  never merge two requirements into one scenario.
+
+### Two tiers (authoring convention)
+
+Tag scenarios `@core` (must ship; maps to a task in decomposition) or `@edge` (advisory error/edge
+paths; may be deferred). This is a **planning convention** (DD-06), not a `check` gating feature
+today — the validator currently treats all scenarios uniformly — but tagging lets decomposition and
+future tiered gating tell them apart. Full rationale: `sp:spur-dev`'s AC style guide.
+
+See [features/acceptance-criteria.md](features/acceptance-criteria.md) for the Gherkin template
+and the checklist-vs-Gherkin two-format note.
+
+## Traceability habits
+
+The L4 layer of `check` reads the **task → feature** edges (`feature-id` in task frontmatter) and
+the AC coverage map. Habits that keep it green:
+
+- **Create tasks with `--feature <id>`** so the incoming edge exists (`spur task create … --feature H2`).
+- **Match a task to AC by scenario title**, not R-number — coverage is computed on normalized
+  titles, so keep titles stable even as you renumber-around them.
+- **Before `verifying`**, run `spur feature check <id> --json` and clear: orphan scenarios (AC with
+  no task), coverage orphans (tasks claiming AC that doesn't exist), and broken edges.
+- **Run `refresh` after hand-edits or task status changes** so the `## Tasks` block and tree reflect
+  the files (files win). This is **not** `sync` — it does not change feature status.
+- **Scope `refresh` to one feature** with `--feature <id>` when only one feature's task links changed
+  (INDEX.md is still regenerated for the whole tree): `spur feature refresh --feature H2`.
+
+## Roadmap and priority habits
+
+Use feature hierarchy for user-facing capabilities and roadmap themes; keep technical-module mapping
+as prose or notes unless the product surface is developer infrastructure. Priority is a scalar field
+(`spur feature update <id> --field priority --value P1`), while status is lifecycle state
+(`backlog → active → verifying → blocked → done → cancelled`). Do not conflate the two.
+
+**Structure first:** [features/hierarchy-mece.md](features/hierarchy-mece.md) (MECE roots, when to
+extend vs create). **Then priority:** [features/roadmap-priority.md](features/roadmap-priority.md).
+
+For roadmap adjustment, apply the RICE/MoSCoW and strategy guidance from `sp:spur-dev`'s product
+planning reference, then apply accepted deterministic changes through `spur feature update`,
+`spur feature move`, `spur feature refresh`, and `spur feature check`.
+
+## The gate — `check --json`
+
+```bash
+spur feature check H2 --json        # one feature
+spur feature check --json           # whole tree
+spur feature check --strict --json  # warnings → failures
+```
+
+The 4-layer validator (frontmatter, AC syntax, children-limit/structure, L4 traceability) emits its
+verdict and findings as JSON. **Query this, don't re-derive it** — the rules live in the CLI, never
+restated as prose here. This is what `sp:spur-dev`'s feature-check gate loop runs.
+
+## Status sync - `sync`
+
+`spur feature sync` keeps a feature's **lifecycle status** honest against the states of its linked
+tasks — if all tasks are `done`, the feature should advance to `done`; if tasks reopen, the feature
+reopens. It computes a proposal (`from → to` with a `reason`) and, unless `--dry-run`, applies it
+via real lifecycle transitions (dogfood / one-active-goal / L4 gates may deny a hop).
+
+**Not for roster tables.** A stale `## Tasks` line (e.g. task still listed `todo` after it is `done`)
+is fixed with `spur feature refresh`, not `sync`. Use `sync --dry-run` first when you only want to
+see the proposed status hop.
+
+```bash
+spur feature sync H2 --json                    # one feature
+spur feature sync H2 --dry-run --json          # propose only, no write
+spur feature sync --all --json                 # every feature with linked tasks
+spur feature sync H2 --force                   # apply a reopen proposal without confirmation
+spur feature sync H2 --folder docs/custom-tasks --json   # non-default tasks folder
+```
+
+- **`[id]`** syncs one feature; **`--all`** syncs every feature with linked tasks. One of the two is
+  required - exit `2` if neither is given.
+- **`--dry-run`** reports proposed transitions without applying. **`--force`** applies a *reopen*
+  proposal (status moving backward) without interactive confirmation.
+- **`--json`** single-feature emits `{ proposal, applied, appliedHops[] }`; `--all` emits
+  `{ totalFeatures, evaluated, updatedCount, results[] }` where each result is the single-feature
+  shape. `proposal` is
+  `{ featureId, from, to, reason, requiresConfirm?, gateBlocked?, gateFindings?, hops? }`.
+- **Exit codes:** `0` success (including NOOP), `1` error, `2` invalid usage (no id and no `--all`).
+
+## What this skill is NOT
+
+- **Not the planning loop.** Intake → create → AC generation → check-loop → decomposition →
+  batch-create is `sp:spur-dev`'s planning half (R3).
+- **Not validation logic.** This skill says *run `check`*; the layers it enforces are CLI code.
+- **Not tasks.** Task verbs, the WBS lifecycle, and section editing live in **`spur task` (see [tasks.md](tasks.md))**.
+
+## References
+
+| Reference | Covers |
+| --------- | ------ |
+| [features/verbs.md](features/verbs.md) | Per-verb flag detail, JSON shapes, the 4 check layers |
+| [features/acceptance-criteria.md](features/acceptance-criteria.md) | Gherkin template, R-numbering, `@core`/`@edge`, traceability mechanics |
+| [features/hierarchy-mece.md](features/hierarchy-mece.md) | MECE roots, create/extend/reparent/merge rules, root gate, depth limits |
+| [features/roadmap-priority.md](features/roadmap-priority.md) | Roadmap hierarchy, priority/status conventions, and feature-tree adjustment workflow |
+
+## See also
+
+- **`sp:spur-dev`** — orchestrates these verbs into the planning + execution loop. Use it to
+  *drive* planning; use this skill to *look up a verb* or *author AC*.
+- **`spur task` (see [tasks.md](tasks.md))** — the companion for `spur task` (WBS lifecycle, section editing, the
+  readiness matrix).

package/plugins/sp/skills/spur-cli/references/init.md

@@ -0,0 +1,119 @@
+---
+name: init
+description: "spur-cli noun reference for `spur init` and `spur status`: CLI verbs (init scaffold with --name/--force/--minimal, status with --json) plus post-scaffold init validation for /sp:spur-init - Phase 1.5 functional-validation probes and Phase 1.6 rule-glob adaptation."
+see_also:
+  - spur-cli
+---
+
+# spur init / spur status - CLI verbs and post-scaffold validation
+
+## CLI verbs
+
+| Verb | Purpose | Key flags |
+| ---- | ------- | --------- |
+| `init` | Scaffold a new Spur project in the current directory | `--name <name>` `--force` `--minimal` `--json` |
+| `status [path]` | Show project and git status for a Spur project | `--json` |
+
+### `spur init` - scaffold a Spur project
+
+```bash
+spur init                            # interactive: prompt for project name
+spur init --name my-project          # non-interactive
+spur init --name my-project --force  # overwrite existing .spur/ files
+spur init --minimal                  # skip optional scaffolding (rules, workflows)
+spur init --json                     # machine-readable
+```
+
+Materializes the `.spur/` directory tree with config, docs, rules, and workflow templates. The
+post-scaffold validation probes (Phase 1.5 / 1.6, below) run immediately after this verb completes.
+
+#### Flags
+
+| Flag | Purpose |
+|------|---------|
+| `--name <name>` | Project name (skips interactive prompt). |
+| `--force` | Overwrite existing `.spur/` files. Without it, existing files are preserved. |
+| `--minimal` | Skip optional scaffolding (rules presets, workflow templates). Core config + docs only. |
+| `--json` | Output machine-readable JSON instead of interactive summary. |
+
+### `spur status [path]` - project and git status
+
+```bash
+spur status                          # current directory
+spur status /path/to/project         # specific project
+spur status --json                   # machine-readable
+```
+
+Reports the project's Spur configuration state (init status, feature/task counts, rule preset
+health) and git working-tree status. Optional `[path]` argument targets a different project
+directory.
+
+## Post-scaffold validation
+
+Two probes sit between the deterministic scaffold (`spur init`) and the non-deterministic doc
+customization: Phase 1.5 (functional validation) confirms the fresh tree is immediately functional;
+Phase 1.6 (rule glob adaptation) rewrites layout-dependent rule globs so `recommended-pre-check`
+runs clean on this project's layout. The executing agent owns content *adaptation* only — `spur
+init` owns *file materialization* (`04_DESIGN.md` §1.1 "Init ownership contract").
+
+### Phase 1.5 — Functional validation probe
+
+Before any customization, confirm the fresh scaffold is immediately functional. If any probe
+fails, STOP and report the gap rather than papering over it with customization:
+
+```
+spur status
+spur task create "__probe__" --template standard   # confirms task template + matrix resolve
+spur workflow validate .spur/workflows/task-pipeline.yaml
+```
+
+### Phase 1.6 — Rule glob adaptation (LLM-as-judge)
+
+The bundled `recommended-pre-check` preset ships globs calibrated to Spur's own monorepo
+(`apps/**/*.ts`, `packages/**/*.ts`, `scripts/**/*.ts`). On any other layout these match zero
+files, and `rg` exits 2 ("No files were searched") — surfacing as `kind: "error"` findings that
+obscure real violations. Rather than ship a broken probe, **you (the executing agent) ARE the
+LLM-as-judge**: inspect the project tree and rewrite layout-dependent globs to match reality.
+
+**You are NOT creating scaffold files.** Adapted rule files under `.spur/rules/<category>/` are
+customization overlays — the local layer shadows the bundled layer (first-layer-wins by relative
+path, `04_DESIGN.md` §1.1). This is content adaptation of rule globs, exactly analogous to the
+doc edits in Phase 2, not file materialization.
+
+Steps:
+
+1. **Detect layout.** Inspect top-level dirs + manifest files to classify the project:
+   - Monorepo (Bun workspaces / npm workspaces / pnpm): `apps/` + `packages/` present, or
+     `package.json` has a non-empty `workspaces` field.
+   - Single-package TS/JS: `src/`, `test/` or `tests/`, single `package.json`, no workspaces.
+   - Flat script repo: `.ts`/`.js` files at root or one shallow dir, no `src/`.
+   - Polyglot / non-TS (Python/Go/Rust primary): primary source lives under non-TS globs;
+     TS rules become correct no-ops and need no adaptation (skip to step 5).
+
+2. **Read the resolved preset.** `spur rule list --preset recommended-pre-check --json` returns
+   the category → rule-file map with resolved paths (bundled vs. global vs. local).
+
+3. **For each category** (`typescript`, `structure`, `boundary`, `surface`, `ui`), read the
+   resolved rule file and identify layout-dependent `include` globs. The Spur-monorepo anchors
+   that almost always need rewriting:
+   - `apps/**/*.ts`, `packages/**/*.ts`, `scripts/**/*.ts` → project's actual TS source roots
+   - `apps/**/*.test.ts`, `packages/**/*.test.ts` → project's actual test roots
+   - `apps/*/package.json`, `packages/*/package.json` → workspace manifests (or root `package.json`)
+   - `apps/web/src/**`, `apps/server/src/**` → single web/server entry roots
+
+4. **Write adapted overrides.** For each rule file with layout-dependent globs, copy the bundled
+   content to `.spur/rules/<category>/<rule-file>.yaml`, then rewrite only the layout-dependent
+   globs to match the detected roots. Preserve all non-layout globs (`**/*.ts`, `**/node_modules/**`,
+   `.spur/rules/**`), rule `id`s, evaluators, and severities verbatim. Write via the `Write` tool.
+
+5. **Verify the adaptation.** Re-run the probe that motivated this phase:
+   ```
+   spur rule run --preset recommended-pre-check --json
+   ```
+   Acceptance: **zero findings with `kind: "error"`**. Genuine violations surface as
+   `kind: "violation"` and are expected on a real codebase — they are NOT adaptation failures.
+   If `kind: "error"` findings remain, their globs still mismatch; re-read those rule files and
+   widen the adapted globs. Idempotency: if `.spur/rules/<category>/` already holds hand-tuned
+   overrides for a rule (differs from the bundled content), skip re-adapting that rule.
+
+Phase 2 customization proceeds only after this probe is clean.

package/plugins/sp/skills/spur-cli/references/message.md

@@ -0,0 +1,98 @@
+---
+name: spur-cli-message
+description: "spur-cli noun reference: operate `spur message` as the durable inter-agent messaging surface - send, inbox, reply, and watch. The inbox that `spur agent run --drain` and `spur agent loop` consume."
+see_also:
+  - spur-cli
+---
+
+# spur message - durable inter-agent messaging
+
+`spur message` is the CLI for **durable inter-agent messages**. Messages are persisted (not
+ephemeral), so an agent can drain its inbox on the next `run --drain` or `loop` iteration even if it
+was offline when the message was sent. This is the inbox surface that `spur agent run --drain` and
+`spur agent loop` consume.
+
+This is a **companion reference**, not an orchestrator. It documents *what each verb is and how to
+use it well*.
+
+## Verb map
+
+| Verb | Purpose | Key flags |
+| ---- | ------- | --------- |
+| `send <body>` | Enqueue a message for an agent | `--to <id>` `--from <id>` `--json` |
+| `inbox` | List messages addressed to an agent | `--agent <id>` `--json` |
+| `reply <msg-id> <body>` | Thread a reply to a message | `--json` |
+| `watch` | Follow an agent inbox - surface new messages as they arrive | `--agent <id>` `--interval <ms>` `--json` |
+
+All verbs accept `--json` for machine consumption. **Exit codes:** `0` success, `1` error, `2`
+invalid usage.
+
+## `send` - enqueue a message
+
+```bash
+spur message send "Please review PR 42" --to reviewer
+spur message send "Task 0040 is blocked" --to worker-1 --from operator
+spur message send "Done" --to planner --json
+```
+
+Enqueues a durable message addressed to `--to <id>`. The recipient drains it on its next `agent run
+--drain` or `agent loop` iteration. `--from` defaults to `operator`.
+
+### Flags
+
+| Flag | Purpose |
+|------|---------|
+| `--to <id>` | **Required.** Recipient agent id. |
+| `--from <id>` | Sender id (default: `operator`). |
+| `--json` | Output machine-readable JSON. |
+
+## `inbox` - list addressed messages
+
+```bash
+spur message inbox --agent worker-1
+spur message inbox --agent worker-1 --json
+```
+
+Lists messages addressed to `--agent <id>`, oldest first. The body is truncated in plain-text output;
+`--json` returns the full body.
+
+## `reply` - thread a reply
+
+```bash
+spur message reply msg-003 "Acknowledged - starting now"
+spur message reply msg-003 "Done" --json
+```
+
+Threads a reply to a specific message id. The reply is addressable to the original sender's inbox.
+
+## `watch` - follow an inbox live
+
+```bash
+spur message watch --agent worker-1
+spur message watch --agent worker-1 --interval 1000 --json
+```
+
+Polls the inbox and surfaces each **new** message exactly once as it arrives. `Ctrl-C` to exit. With
+`--json`, emits one JSON object per new message (machine-consumable); without it, prints plain-text
+lines.
+
+### Flags
+
+| Flag | Purpose |
+|------|---------|
+| `--agent <id>` | **Required.** Agent id to watch. |
+| `--interval <ms>` | Poll interval in milliseconds (default: `2000`). Must be a positive integer; exit `2` otherwise. |
+| `--json` | Output one JSON object per new message. |
+
+## What this skill is NOT
+
+- **Not the agent runner.** `spur agent run --drain` and `spur agent loop` consume the inbox; this
+  reference documents the verbs that *populate* it. See **[agent.md](agent.md)**.
+- **Not real-time transport.** Messages are durable and polled, not pushed. `watch` simulates
+  real-time by polling on an interval.
+
+## See also
+
+- **`spur agent` (see [agent.md](agent.md))** - `run --drain` and `loop` consume the inbox.
+- **`spur team` (see [team.md](team.md))** - team lifecycle that assigns agents to tasks.
+- **`sp:spur-cli`** SKILL.md - the facade that routes to this reference.