--- name: spur-dev description: 'The thin orchestration spine for the planning→execution lifecycle: intake, feature-check/batch-create gates, the execution pipeline (precheck→implement→test→review→verify→record→done), HITL gating. Dispatches competency skills; never inlines them. Triggers: "run the pipeline", "drive this task", "plan a feature end to end", "continue the pipeline run", or operating the full lifecycle.' license: Apache-2.0 metadata: author: spur version: "1.1" platforms: "claude-code,codex,openclaw,opencode,antigravity" interactions: - pipeline halves: - planning - execution planning_steps: - intake - feature-create - ac-generation - feature-check-gate - decomposition - batch-create-gate - design-doc - refine execution_steps: - precheck - implement - test - review - approve - verify - record - done openclaw: emoji: "🔄" --- # Spur Dev — The Orchestration Spine `sp:spur-dev` is the **thin orchestration spine** that drives the full planning→execution lifecycle. It converts vague intent into shipped work by _orchestrating_, not by doing the work itself: it runs the gates (feature-check, batch-create) and the execution pipeline with human-in-the-loop control, and **dispatches deep competency skills** for each unit of work — it never inlines them. Every write to the corpus goes through a CLI verb that validates before writing — the spine knows _how to drive the lifecycle_; the competency skills know _how to do each job_; the CLI knows _what is valid_. The skill was decomposed **by function** (ADR-028): design, decomposition, implementation, testing, and verification each became a standalone competency skill, leaving this spine to orchestrate them. **Ownership (ADR-054).** This spine owns multi-step lifecycle orchestration — intake, gates, decomposition, pipeline runs, HITL pauses. CLI noun/verb/flag semantics, including status-transition verbs, are the facade's (`sp:spur-cli`), never this skill's. **The competencies the spine dispatches:** | Unit of work | Competency skill | | ------------------------------------ | ----------------------------------------------------------------------- | | Design / ADR judgment (shape a task) | `sp:sys-architecture` | | Feature/spec → task batch | `sp:spec-decomposition` | | Implement to spec | `sp:code-implementation` | | Coverage / test extension | `sp:code-testing` | | Review (multi-dimensional) | `sp:code-verification` + `sp:functional-review` + `sp:code-improvement` | | Test-first discipline (composed in) | `sp:test-driven-development` | CLI verb usage for any `spur` noun lives in the `sp:spur-cli` facade. This spine owns only the lifecycle, the gates, and the section-write contract (`cross-cutting.md`). ## The two halves at a glance **Planning half** — vague description → validated, decomposed feature: ``` vague description → intake (clarify scope, constraints — prompt work) → spur feature create … ; AC authored/generated (spur agent run, bdd templates) → GATE: spur feature check (BDD validator; loop until clean) → decomposition (prompt work) → task-batch JSON → GATE: task-batch.schema.json + spur task batch-create (atomic: all-or-nothing) → design doc (conditional: seam heuristic; opt out with --skip-design) → docs/design/.md + 04 index → refine (per task, just-in-time, before execution) ``` Full procedure: **[references/planning-workflow.md](references/planning-workflow.md)**. **Execution half** — one task through the pipeline: ``` pick task (spur task list --json) → interactive omit/inline: read task-pipeline.yaml → drive actions + guards in host session → explicit/headless executor: spur workflow run task-pipeline.yaml --vars '{"wbs":""}' → on HITL pause: surface to operator; resume the selected driver from the paused state ``` The pipeline (`kind: state-machine`) runs the work loop: ``` precheck → implement → test → review → approve(HITL) → verify → record → done ``` Full procedure: **[references/execution-workflow.md](references/execution-workflow.md)**. Host-session procedure: **[references/inline-pipeline-driver.md](references/inline-pipeline-driver.md)**. ## Step routing Each step delegates to a CLI verb and is documented in exactly one reference file. Read the reference for the half you're operating; do not duplicate its content here. | Step | Half | CLI gate | Reference | | -------------------------- | --------- | ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | Intake | planning | — (prompt work) | [planning-workflow.md](references/planning-workflow.md) · [product-planning.md](references/product-planning.md) | | Feature create + AC | planning | `spur feature create` | [planning-workflow.md](references/planning-workflow.md) · [ac-style-guide.md](references/ac-style-guide.md) | | Feature check gate | planning | `spur feature check` | [planning-workflow.md](references/planning-workflow.md) | | Decomposition (dispatch) | planning | `task-batch.schema.json` | `sp:spec-decomposition` competency — the spine dispatches, does not inline | | Batch-create gate | planning | `spur task batch-create` | [planning-workflow.md](references/planning-workflow.md) | | Design doc | planning | — (prompt work; §4.5/T9) | [planning-workflow.md](references/planning-workflow.md) | | Refine | planning | `spur task update --section` | [planning-workflow.md](references/planning-workflow.md) | | Batch refine | planning | `sp:dev-refineall` → per-task `refine` | [dev-operations.md](references/dev-operations.md) § refineall · [planning-workflow.md](references/planning-workflow.md) | | Task selection | execution | `spur task list` | [execution-workflow.md](references/execution-workflow.md) | | Pipeline run | execution | inline YAML driver or `spur workflow run` | [execution-workflow.md](references/execution-workflow.md) · [inline-pipeline-driver.md](references/inline-pipeline-driver.md) | | Implement (dispatch) | execution | `sp:code-implementation` | competency skill — the spine dispatches, does not inline | | Test (dispatch) | execution | `sp:code-testing` | competency skill — the spine dispatches, does not inline | | Review / verify (dispatch) | execution | `sp:dev-review` → `sp:code-verification` + `sp:functional-review` + `sp:code-improvement` | competency skills — the spine dispatches, does not inline | | Operation catalog | execution | `sp:dev-*` operations | [dev-operations.md](references/dev-operations.md) (spine dispatch table) | | Continue | execution | `spur feature update` / `refresh` | [execution-workflow.md](references/execution-workflow.md) | | Batch run | execution | `sp:super-planner` + `spur workflow run` | [execution-batch.md](references/execution-batch.md) | | Parallel fan-out | execution | `sp:parallel-execution` decision framework | [execution-batch.md](references/execution-batch.md) | | All writes (both halves) | — | CLI-gated section editing | [cross-cutting.md](references/cross-cutting.md) · [section-batching.md](references/section-batching.md) (one-writer protocol, F92 0593) | ## When to use Use this skill for: - **Planning a feature** — a description arrives; produce a feature file with AC and decomposed tasks. - **Product-shaped planning** — prioritize roadmap candidates, choose a strategy profile, or produce PRD-shaped guidance without adding a separate PM command surface. - **Running a task** — pick a task, run it through the pipeline, handle HITL gates. - **Continuing interrupted work** — resume a paused pipeline run. - **Batch task creation** — decompose a feature into tasks and land them atomically. Do **not** use this skill for: - Looking up task/feature/rule/workflow verbs or conventions — use the `sp:spur-cli` facade (one reference per noun). - Gate-level constraint checking — use `sp:spur-cli` (rule noun). - Workflow authoring/tuning — use `sp:spur-cli` (workflow noun). - Documentation maintenance — use `sp:doc-evolve`. ## Behavior This skill behaves as a **pipeline** operator: it converts intent into CLI-validated artifacts, gates every write, and drives execution workflows. It owns the full planning→done lifecycle but delegates every deterministic step to CLI verbs. It does not validate — the CLI does. ## Gotchas ### Bounded execution and recovery (0777) - During planning/refinement of corpus-scale work, record an execution budget, persisted-artifact paths and requireDiff guidance in the task Design. For classification-only work, declare `mutationPolicy: none`; its task/evidence change is the deliverable, not invented source edits. Preserve partial artifacts at the budget boundary; resume only against the current task contract. - Before accepting a child/watcher result, compare its run ID with the dispatched run ID and check current trace state through Spur. If using a run log as evidence, require its mtime to be at least the dispatch time. A mismatch or stale timestamp is not completion evidence. Do not scrape terminals. Bound each watch invocation to 10 minutes or 20 polls, whichever comes first; persist the last confirmed identity/state and report a checkpoint before continuing. A watcher timeout does not cancel the owned run or authorize launching a replacement. - Mark superseded scratch with `SUPERSEDED` and a pointer to the authoritative task Design. Never let a scratch instruction override the live task, even when its old run is still readable. - Checker-policy changes require one explicit unsuppressed audit (T10); ordinary corpus commit prep checks affected documents and linked evidence (T11), not the corpus. No acceptance snapshots. 1. **Never skip a gate.** A clean `feature check` is the only proof the AC is valid; a passing `batch-create` is the only proof the decomposition is well-formed. Skip either and you ship corrupted corpus. 2. **One writer per evidence section (F92 0593 R1).** `## Solution` is authored by the implement step; `## Review` by the review coordinator (`/sp:dev-review`); `## Testing` by the deterministic `record` step from the verdict artifact (`record` backfills `## Review` only when bare — fallback-only, never an overwrite). During execution, do not hand-edit another stage's section. 3. **Resolve task IDs through the CLI.** Read a known WBS with `spur task show --json`; it returns metadata, full content, and `filePath` across configured task folders. Use `spur task path --json` only when another tool needs the absolute path. Never search `docs/tasks*` or guess `--folder`; reuse the first `show` response throughout the run. 4. **Check before every write.** Run `spur task check --json` to know what sections the task needs at its current status. Guessing produces matrix violations. 5. **AC titles are identity keys.** Renaming a scenario after tasks are created breaks traceability edges. If you must rename, update the task's scenario references too. 6. **Batch-create is atomic.** A single schema violation rejects the entire batch. Validate locally against `task-batch.schema.json` before invoking the CLI. 7. **Two-halves seam.** The planning and execution halves share this skill today but are designed to split cleanly. Keep new logic in one half or the other — never straddle the seam with cross-half dependencies. ## Additional Resources **Every reference file and its step is listed once, in [Step routing](#step-routing) above — this section adds what that table has no room for: per-file content summaries and items with no single step (glossary, config companions).** Read Step routing to find "which file for step X"; read below for "what's actually in file Y" or for resources that sit outside the step sequence. - [references/glossary.md](references/glossary.md) — sp's own vocabulary: spine, competency, facade, corpus, gate, verdict, noun/verb, half, HITL, WBS, section-write contract — canonical term + Avoid list. Owns term definitions only; `cross-cutting.md` owns the process rules that use them. - [references/flag-glossary.md](references/flag-glossary.md) — the shared-flag glossary (one canonical entry per flag used by two or more `/sp:dev-*` commands) and the `--next` chain contract. Moved verbatim from `dev-operations.md` (task 0408) so command files can deep-link flag entries while this spine reads the operation catalog linearly. - [references/gate-checklists.md](references/gate-checklists.md) — checkbox checklists for the five gates (feature-check, batch-create, precheck, review, verify). Each checklist is a `- [ ]` list of prerequisites an agent verifies before entering the gate. - [references/section-batching.md](references/section-batching.md) — the evidence-section **one-writer protocol** (F92 0593 R1/R2): implement owns `Solution`, the review coordinator owns `Review`, deterministic `record` owns `Testing`; skills query `spur task sections` / `spur task check` instead of static section tables. - [references/ac-style-guide.md](references/ac-style-guide.md) — BDD scenario authoring: R-numbering, the two AC tiers, scenario-title stability, Gherkin template usage. - [references/feature-link-helper.md](references/feature-link-helper.md) — opt-in, strictness-triggered helper to resolve a deferred `feature_id` edge: LLM-judge match against existing features (prefer existing; create only as last resort; confirm before apply); single-task mode + batch-sweep mode. Invoke only when the operator opts into `--strict` rigor or explicitly asks to link a task to a feature — NEVER gate-time, NEVER automatic. **Competency skills the spine dispatches to** (what each owns beyond the Step-routing row): - **`sp:code-implementation`** owns `implementation-patterns.md`, `debugging.md`. - **`sp:code-testing`** owns `unit-testing.md` and the per-stack adapters (`stacks/`). - **`sp:spec-decomposition`** owns the granularity standard (scenario→task sizing). - **`sp:functional-review`** owns requirements traceability (R{n} → file:line evidence, per-requirement MET/PARTIAL/UNMET, FunctionalVerdict artifact). Phase 8b gate. - **`sp:code-improvement`** owns architectural deepening (5 signals: shallow module, tight coupling, wrong seam, weak locality, poor test surface; severity blocker/major/minor/advisory). - **`sp:test-driven-development`** — the test-first discipline `code-implementation` and `code-testing` compose with. **Config & companions (no single pipeline step owns these):** - `plugins/sp/references/roles.md` — the Layer-1 role→tier table (`scribe` / `coder` / `reviewer` / `planner`, one per tier); the role vocabulary this spine's operations route under. - `task-pipeline.yaml` — the execution pipeline definition. - `idea-pipeline.yaml` — the front-half state machine (absorbed the retired planning-pipeline in D5-K; `/sp:dev-plan` routes here, ADR-072). - `templates/bdd/gherkin.md` — the BDD scenario template. ## Platform Notes ### Claude Code `spur` CLI via the Bash tool. The `sp:dev-*` slash commands are the primary entry points; invoke the skill directly via `Skill(skill="sp:spur-dev", args="plan ")` for planning, `args="run "` for execution, `args="unit "` for test generation, or `args="refine "` for task refinement, or `args="refineall --feature --auto"` for batch refine under a feature (add `--depth ready` for implement-ready freeze). Use `spur agent run` for isolated LLM invocations within pipeline steps. **Argument parsing.** Split `$ARGUMENTS` into target + flags before dispatching. Unknown flags are not silently dropped: note them in the plan line, or stop (rule imported from `next-router`, task 0701 R3 — e.g. `--worktree` on `dev-refine` is undeclared, so it must be surfaced, never discarded). ### Codex / OpenClaw / OpenCode / Antigravity Run `spur` CLI via the Bash tool; parse `--json` output. Invoke this skill directly for the workflow logic — the skill is the SSOT; commands and subagents are thin wrappers.