---
name: spur-cli
description: "Reference and operate the complete `spur` CLI surface: task, feature, rule, workflow, builder, agent, message, self, history, and projects. Use for verb or flag lookup, machine-readable output and exit contracts, or CLI-gated corpus writes. Triggers: \"spur task\", \"spur history\", \"spur projects\", \"create a task\", \"task check\", and any Spur CLI convention. Not for planning or execution lifecycle orchestration (`sp:spur-dev`)."
license: Apache-2.0
metadata:
  author: spur
  version: "1.0"
  platforms: "claude-code,codex,openclaw,opencode,antigravity"
  interactions:
    - reference
    - companion
  nouns:
    - task
    - feature
    - rule
    - workflow
    - builder
    - agent
    - message
    - self
    - history
    - projects
  openclaw:
    emoji: "🧰"
---

# spur-cli — the CLI facade for the Spur command surface

`spur-cli` is the single reference for operating the **`spur` command-line surface**. Each visible
noun has one reference file that documents *what each verb is, how to use it well, its flags,
machine-readable output, and material exit semantics*. This skill is a **facade /
dispatch reference** — it tells you which verb does what and routes you to the noun's detail. It is
**not** an orchestrator and contains **no competency logic**: the skill knows *how to invoke*; the
CLI knows *what is valid*; the **spine** (`sp:spur-dev`) knows *how to drive the lifecycle*.

## Noun routing

Pick the noun, read its reference. Each Tier A and Tier B reference owns that noun's full verb catalog and conventions.

| Tier | Noun | Operate | Reference |
| ------ | ------ | --------- | ----------- |
| **Tier A** | **task** | Task corpus: create (variants), `deps` mutation, canonical `sections` (`init`/`add`/`list`), status lifecycle, `record`/`verdict` artifacts, `run-link`, `check --json` matrix | [references/tasks.md](references/tasks.md) |
| **Tier A** | **feature** | Feature tree: author with hierarchical IDs (DD-14), acceptance criteria (Gherkin), status lifecycle, move subtrees, `check --json` | [references/features.md](references/features.md) |
| **Tier A** | **rule** | Constraint quality gate: run presets, author rules, fine-tune, validate rule files/presets, extend engine | [references/rules.md](references/rules.md) |
| **Tier A** | **workflow** | Dual-mode workflow runtime: author state-machine / transition-flow workflows, validate, run, read traces | [references/workflows.md](references/workflows.md) |
| **Tier A** | **builder** | Release plumbing: bump a package (or the `workspace:`-pinned set) with `bump-ver`, delete release tags with `drop-tags`, commit + tag + optional push | [references/builder.md](references/builder.md) |
| **Tier B** | **agent** | Coding-agent execution surface: run prompts via detected/named agents, list agent specs, start/stop supervised processes, readiness check | [references/agent.md](references/agent.md) |
| **Tier B** | **message** | Durable inter-agent messaging: send, inbox, reply, watch | [references/message.md](references/message.md) |
| **Tier B** | **self** | Self-management verbs: scaffold (`init`), schema migrations (`migrate`), local web server (`serve`), status overview (`status`); `self init` runs post-scaffold validation probes & layout classification | [references/self.md](references/self.md) |
| **Tier B** | **history** | Import agent histories, aggregate forensic artifacts, render reports, and run the checkpoint-resumed daily pipeline | [references/history.md](references/history.md) |
| **Tier B** | **projects** | Manage the local multi-project registry and start/stop project servers | [references/projects.md](references/projects.md) |
| **Tier C** | **help** | Commander-generated help command; not a Spur noun | Generated `--help` |

**Execute-First Contract:** Load the noun reference first and execute Tier A or Tier B commands
without calling `spur --help`. Use the source-local `spur <noun> [verb] --help` only for version
skew, unlisted long-tail flags, or a parity assertion failure.

### Tier C exclusion reasons

The only exclusion is generated by Commander and is not a product noun:

| Noun | Reason |
| ------ | -------- |
| `help` | Auto-generated by Commander.js; not a real noun. |

Each noun's per-topic detail lives one level deeper under `references/<noun>/` (e.g.
`references/tasks/verbs.md`, `references/tasks/section-editing.md`, `references/features/acceptance-criteria.md`,
`references/rules/operations.md`, `references/workflows/authoring-workflows.md`).

## When to use

Use this skill to:

- **Look up a `spur` verb** — what it does, its flags, its `--json` shape, its exit codes.
- **Operate the corpus directly** — create/edit/list tasks and features, run a rule preset, validate
  or run a workflow, from the command line.
- **Author within a noun** — write a rule, author a workflow, write acceptance criteria — following
  the noun reference's conventions.
- **Operate local analytics and project management** — import/analyze/report history or manage the
  multi-project registry through their references.

Do **not** use this skill for:

- **Driving the planning→execution lifecycle** — intake → feature → decomposition → batch-create →
  pipeline run is the spine, **`sp:spur-dev`**. This facade documents the verbs that spine dispatches.
- **Gate-level constraint *design* across the catalog** — that lives in the `rule` reference's
  authoring/fine-tuning topics, reached through this facade.

## Convention — extending the facade

Every `spur` noun is reachable here and nowhere else. **Adding a new noun adds exactly one reference
file** (`references/<noun>.md`), plus an optional `references/<noun>/` subdir for its per-topic
detail, plus one row in the Noun-routing table above. Do not create a separate `spur-<noun>` skill —
the whole point of this facade is that the CLI surface has a single, scalable home.

## Source and machine-output contract

The implementation authority is `apps/cli/src/index.ts` plus the noun registration module under
`apps/cli/src/commands/`; application-service output types remain authoritative for payload fields.
When a reference and the source-local CLI disagree, stop, cite the source symbol, and repair the
reference in the same change. The live parity gate is
`plugins/sp/tests/cli-surface-parity.test.ts`.

Do not assume every verb supports JSON. When `<noun> <verb> --help` advertises `--json`, parse
stdout as one JSON document (or one document per row for documented streams). When it also
advertises `--json-envelope`, raw JSON remains the default; the opt-in shape is
`{ ok: true, data }` / `{ ok: false, error }`, with paginated list metadata where applicable.
`SPUR_JSON_ENVELOPE=1` enables the same seam unless an explicit flag overrides it. The guarded
inventory and deliberate raw exceptions live in `docs/04_DESIGN.md` §4.1 and
`apps/cli/tests/json-envelope-inventory.test.ts`; do not duplicate that inventory here.

## What this skill is NOT

- **Not the spine.** Driving a task through `task-pipeline.yaml`, HITL surfacing, decomposition, and
  the planning loop is `sp:spur-dev` (the spine). This facade is the verb reference the
  spine and the operator both consult.
- **Not validation logic.** This skill says *run `check` / `validate`*; the rules those verbs enforce
  live in the CLI (`task check`, `feature check`, `rule run`, `workflow validate`), never restated as
  prose checks here.
- **Not a competency.** Design, implementation, testing, and review are competency skills, not CLI
  verbs — they are not documented here.
- **Not the orchestration owner.** The ADR-054 boundary: this facade owns CLI noun/verb/flag
  semantics — including task and feature status-transition verbs — while multi-step lifecycle
  orchestration belongs to `sp:spur-dev`.

## Shared option registry (0618)

Options shared by two or more command modules are declared once in
`apps/cli/src/commands/shared-options.ts` and spread at every call site
(`.option(...SHARED_OPTIONS.<key>)` — parser/default/collector args append after the spread). One
registry entry per **(flag, description) pair**: semantic homonyms (`--json`,
`--cwd`) keep separate keys with their distinct texts. When editing a command module, never
re-declare a shared flag inline — `apps/cli/tests/shared-option-parity.test.ts` fails on any literal
declaration of a flag string in `SHARED_OPTION_FLAGS`. Add a new shared option by adding the entry
and spreading it; full contract in `docs/04_DESIGN.md` §1.0.1.

## See also

- **[references/agent.md](references/agent.md)** - coding-agent execution surface (`run`, `wait`,
  `list --specs`, `start`/`stop`). Cross-references the
  [dispatch-surface rule](../parallel-execution/references/dispatch-surface.md).
- **[references/message.md](references/message.md)** - durable inter-agent messaging (`send`,
  `inbox`, `reply`, `watch`).
- **[references/self.md](references/self.md)** - `spur self init|migrate|serve|status` CLI verbs
  (the four legacy top-level nouns remain hidden aliases). `self init` runs post-scaffold init
  validation (Phase 1.5/1.6 probes).
- **[references/history.md](references/history.md)** - history import, forensic artifact analysis,
  pure report rendering, and the daily pipeline.
- **[references/projects.md](references/projects.md)** - local multi-project registry and server
  lifecycle.
- **`sp:spur-dev`** - the spine that dispatches these verbs into the planning +
  execution lifecycle. Use it to *drive* work; use this facade to *look up or operate a verb*.
- **`plugins/sp/references/roles.md`** — the Layer-1 role→tier table (`scribe` / `coder` /
  `reviewer` / `planner`, one per tier). The facade's nouns/verbs serve those roles; the table is
  the role vocabulary, the operator config maps tiers to executors.

## Platform Notes

### Claude Code

Run the `spur` CLI via the Bash tool. Use `--json` only where the selected verb advertises it. Invoke
this skill directly via `Skill(skill="sp:spur-cli", args="<noun> <verb> …")` to look up or operate
a verb.

### Codex / OpenClaw / OpenCode / Antigravity

Run the `spur` CLI via the Bash tool and parse `--json` output. This facade is the SSOT for the verb
surface; commands and subagents are thin wrappers over it.