@gobing-ai/spur 0.3.41 → 0.3.43

package/plugins/sp/commands/dev-run.md

@@ -0,0 +1,63 @@
+---
+description: Run a task — full pipeline (precheck→implement→test→review→approve→verify→record→done) or single-step (implement)
+argument-hint: "<wbs> [--mode <full|implement>] [--agent <inline|auto|name>] [--auto] [--next] [--wrap] [--continue]"
+allowed-tools: ["Bash", "Read", "Write", "Edit", "Skill"]
+---
+
+# Dev Run
+
+Wraps the **sp:spur-dev** and **sp:code-implementation** skills.
+
+## Argument Flags
+
+| Flag | Description | Default |
+| --- | --- | --- |
+| `<wbs>` | Task WBS to run. | required |
+| `--mode` `<full\|implement>` | Full pipeline or single implement step. | full |
+| `--agent` `<inline\|auto\|name>` | Who runs the model-bearing stages. In an interactive session, omit/`inline` keeps the controller in the host session (non-subprocess); eligible full-mode `agent.run` stages may dispatch once to a native subagent, with host fallback (task 0508). `auto` or a name keeps subprocess dispatch. | inline |
+| `--auto` | Skip objective HITL confirmations. | off |
+| `--next` | Chain-to-completion via the next-router. | off |
+| `--wrap` | Run the wrap hop after the main step. The `--agent` selector is preserved into the `/sp:dev-wrap <wbs>` handoff when supplied; omission remains omission. The wrap hop is workflow-backed and reports its trigger-3 subprocess override. | off |
+| `--continue` | Resume an interrupted task from its checkpoint. | off |
+
+For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag-glossary.md).
+
+## Usage
+
+/sp:dev-run <wbs> [--mode <full|implement>] [--agent <inline|auto|name>] [--auto] [--next] [--wrap] [--continue]
+
+## Implementation
+
+- Apply the [inline-default execution-surface contract](../skills/spur-dev/references/cross-cutting.md#inline-default-execution-surface).
+- Full pipeline (default `--mode full`): interactive omit/`--agent inline` uses the
+  [inline pipeline driver](../skills/spur-dev/references/inline-pipeline-driver.md) via
+  `Skill(skill="sp:spur-dev", args="run-inline $ARGUMENTS")`; `--agent auto` or a named executor
+  uses `Skill(skill="sp:spur-dev", args="run $ARGUMENTS")` and the workflow subprocess path.
+- Implement step only (`--mode implement`): `Skill(skill="sp:code-implementation", args="$ARGUMENTS")`
+
+**Flags:**
+
+- `--auto` | `--agent <inline|auto|name>` — Skip objective HITL confirmations (taste/irreversible gates still pause). `--agent` names who does the model-bearing work. Interactive omit/`inline` keeps the controller and implement-only stages in this session; full mode reads `task-pipeline.yaml` as the SSOT and interprets its actions/guards through the inline driver, where eligible `agent.run` stages may dispatch once to a native subagent and otherwise run in the host (task 0508). It records `stage <id> executed inline in session <session-id>` or `stage <id> executed via subagent <agent-id> (host session <session-id>)` in the run log. `auto` or a name is merged into `vars.agent` and `vars.implementAgent` and keeps the existing subprocess workflow. Headless `spur workflow run` / `spur agent run` is unchanged. See the [execution-surface contract](../skills/spur-dev/references/cross-cutting.md#inline-default-execution-surface).
+
+**Mode split (load-bearing — bug-742)**
+
+| Mode | What runs | Must not do |
+| --- | --- | --- |
+| `--mode full` (default) | Interactive omit/inline: host-session driver over `task-pipeline.yaml`; explicit/headless executor: workflow subprocess | — |
+| `--mode implement` | Single implement competency via `sp:code-implementation` | Re-launch the full pipeline, `spur workflow run …task-pipeline…`, or `/sp:dev-run` **without** `--mode implement` |
+
+The pipeline's `implement` step invokes this command **only** as:
+
+```text
+/sp:dev-run --mode implement <wbs> --auto
+```
+
+That pure slash form is intentional (ADR-043): workflow `agent.run` `input` is a command pointer, not an inline essay. Anti-recursion, scope, and Solution authorship live in this command + `sp:code-implementation`, not in YAML prose bolted onto the slash line.
+
+**When `--mode implement` is active (including as a pipeline subprocess):** work only in the current working tree on `<wbs>`. **NEVER invoke** `spur workflow run` for the task pipeline, and **NEVER invoke** `/sp:dev-run` without an explicit `--mode implement` — this step *is* the pipeline's implement stage; re-entering full mode recurses (bug-742).
+
+> **⚠ Redefinition (feature H8, 2026-07-31).** `--next` previously selected implement-only mode on
+> this command. It no longer does — use `--mode implement`. The replacement already existed and is
+> what `routing-table.md` row A5 dispatches, which is evidence the overload was accidental. This
+> warning is marked for removal after one release (these are prompt files; leaving it is permanent
+> noise). See ADR-039. **was: `--next` selected implement-only mode.**

package/plugins/sp/commands/dev-runall.md

@@ -0,0 +1,83 @@
+---
+description: Run a batch of tasks through their pipelines in dependency-correct order — resolve a set, topo-sort, run each via task-pipeline.yaml, emit a batch report
+argument-hint: "--tasks <selector> [--feature <id>] [--mode <sequential|parallel>] [--keep-going] [--auto] [--agent <inline|auto|name>] [--json] [--wrap] [--next] [--continue] [--worktree [<name>]]"
+allowed-tools: ["Bash", "Read", "Skill"]
+---
+
+# Dev Runall
+
+Wraps the **sp:spur-dev** skill.
+
+## Argument Flags
+
+| Flag | Description | Default |
+| --- | --- | --- |
+| `--tasks` `<selector>` | Task selector to run. | required |
+| `--feature` `<id>` | Restrict to a feature. | omitted |
+| `--mode` `<sequential\|parallel>` | Batch execution order. | sequential |
+| `--keep-going` | Continue past per-task failures. | off |
+| `--auto` | Skip objective HITL gates. | off |
+| `--agent` `<inline\|auto\|name>` | Who runs each task's pipeline stages. Interactive sequential omit/`inline` uses the host-session driver — host-controlled, eligible `agent.run` stages may use a native subagent (task 0508); `auto`, a name, parallel mode, and headless invocation use subprocesses. | inline |
+| `--json` | Emit structured JSON. | off |
+| `--wrap` | Run the wrap hop per task. The `--agent` selector is preserved into each `/sp:dev-wrap <wbs>` handoff when supplied; omission remains omission. | off |
+| `--next` | Chain-to-completion via the next-router. | off |
+| `--continue` | Resume an interrupted batch. | off |
+| `--worktree` `[<name>]` | Run the batch in an isolated git worktree; FF-merge on success, retain on failure. Bare `--worktree` creates a fresh tree; `--worktree <name>` adopts an existing worktree by name/path/branch. | off |
+
+For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag-glossary.md).
+
+## Usage
+
+```
+/sp:dev-runall --tasks <selector> [--feature <id>] [--mode <sequential|parallel>] [--keep-going] [--auto] [--agent <inline|auto|name>] [--json] [--wrap] [--next] [--continue] [--worktree [<name>]]
+```
+
+Flags: `--tasks <selector>` (required — explicit WBS list, status pseudo-list, `feature:<id>`,
+or `ready`), `--feature <id>` (sugar for `feature:<id>`; when the effective selector is
+feature-derived, `dev-runall` runs `spur feature check <id> --strict --json` **once** before
+resolving tasks — a non-zero strict check aborts the batch with verdict `aborted` and the
+structured findings, before any task pipeline action, task 0510 R2), `--mode`
+`<sequential|parallel>` (default `sequential`; `parallel` fans out a proven-independent subset —
+see `execution-batch.md` § Parallel Execution), `--keep-going`
+(batch failure policy — skip a failed task's in-batch dependents, continue independents; default
+halts on first failure), `--auto`
+(sets `profile=auto` on each per-task run, skipping the HITL approve gate), `--agent <inline|auto|name>`
+(names who runs the pipeline's stages — interactive sequential omit/`inline` uses the host driver;
+`auto` or a name is merged into each per-task `vars.agent` and `vars.implementAgent`; parallel mode
+retains isolated subprocesses, ADR-047), `--json` (emit the
+report as JSON), `--wrap` (trigger
+`wrapup-pipeline.yaml` after the batch completes), `--next`
+(chain each task to terminal status, then run the wrap hop **once for the batch** — see below),
+`--worktree` `[<name>]` (run the batch in an isolated git worktree —
+FF-merge onto the base ref on full success, retain intact on any failure/halt/non-FF; bare form
+creates a fresh tree, `<name>` form adopts an existing worktree by name/path/branch; see
+`execution-batch.md` § Worktree isolation).
+
+**`--worktree` is sequential-only.** `--worktree --mode parallel` is **rejected**. This flag gives
+the batch *one* worktree for the whole run; per-task worktrees and parallel isolation remain task
+0142 Slice A. Run parallel batches without `--worktree`, or run them sequentially with it.
+
+**`--worktree` corpus visibility.** While the batch runs in a worktree, corpus writes (task
+statuses, kanban) land in the worktree copy; your main tree still shows pre-run statuses until the
+FF-merge on success. This is expected, not a bug.
+
+**`--next` (batch-once wrap).** `--next`
+is chain-to-completion with propagation. On `dev-runall`, each task in the batch runs its
+`task-pipeline.yaml` to terminal status (the pipeline already drives precheck → implement → test →
+review → approve → verify → record → done); when the batch is complete, the wrap hop runs **once
+for the batch** — mirroring the batch-once shippable gate `dev-verifyall` uses — rather than once
+per task. Without `--next`, `--wrap` is wrap-without-chaining (the single batch wraps without
+advancing the feature lifecycle). **was: `--next` deliberately omitted; the old no-`--next` rationale argued against the old per-task-transition meaning and does not carry.**
+
+**Three orthogonal axes** (do not confuse): `--keep-going`
+= batch failure policy (does a failure halt the batch or skip dependents?);
+`--continue` = resume from
+checkpoint (pick up an interrupted batch); `--next`
+= chain each task to terminal status + batch-once wrap. See `dev-operations.md` § runall for the
+full distinction.
+
+## Implementation
+
+- Apply the [inline-default execution-surface contract](../skills/spur-dev/references/cross-cutting.md#inline-default-execution-surface). Interactive sequential omit/`inline` keeps the orchestrator in the host session through the [inline pipeline driver](../skills/spur-dev/references/inline-pipeline-driver.md); eligible `agent.run` stages may dispatch once to a native subagent with host fallback (task 0508). `--agent auto`, a name, or parallel mode retains the isolated per-task workflow boundary.
+- Interactive sequential omit/inline: `Skill(skill="sp:spur-dev", args="runall-inline $ARGUMENTS")`.
+- Explicit executor or parallel mode: `Skill(skill="sp:spur-dev", args="runall $ARGUMENTS")` → `sp:super-planner` agent.

package/plugins/sp/commands/dev-simplify.md

@@ -0,0 +1,39 @@
+---
+description: Simplify code for clarity without changing behavior — reduce complexity in recent changes (or a given scope), preserving behavior exactly
+argument-hint: "[<path-or-scope>] [--scope <recent|all|path>] [--check <cmd>] [--agent <inline|auto|name>] [--auto]"
+allowed-tools: ["Bash", "Read", "Edit", "Skill"]
+---
+
+# Dev Simplify
+
+Wraps the **sp:code-simplification** skill.
+
+## Argument Flags
+
+| Flag | Description | Default |
+| --- | --- | --- |
+| `[<path-or-scope>]` | Path or scope to simplify. | recent |
+| `--scope` `<recent\|all\|path>` | Scope of the simplification pass. | recent |
+| `--check` `<cmd>` | Validation command to iterate against. | project gate |
+| `--agent` `<inline\|auto\|name>` | Who runs the model-bearing simplification. | inline |
+| `--auto` | Skip objective HITL gates (taste gates: over-engineering removal & cross-file utility extraction still require approval). | off |
+
+For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag-glossary.md).
+
+## Usage
+
+/sp:dev-simplify [<path-or-scope>] [--scope <recent|all|path>] [--check <cmd>] [--agent <inline|auto|name>] [--auto]
+
+## Implementation
+
+- Apply the [inline-default execution-surface contract](../skills/spur-dev/references/cross-cutting.md#inline-default-execution-surface).
+- `Skill(skill="sp:code-simplification", args="$ARGUMENTS")`
+- **Interaction & Confirmation Model**:
+  - **Over-Engineering Removal**: Classify abstractions as Accidental LLM Over-engineering vs Intentional Reserved Patterns. Present target, reason, pros, cons, and recommendation with rationale before removing indirection.
+  - **Common Pattern Consolidation**: Follow the 5-stage lifecycle:
+    1. Identify repeating operations across scope.
+    2. Confirm proposed shared helper/utility signature and module location with operator.
+    3. Implement shared helper in isolation with unit tests.
+    4. Refactor call-sites incrementally.
+    5. Run regression verification suite (`--check <cmd>`).
+

package/plugins/sp/commands/dev-unit.md

@@ -0,0 +1,29 @@
+---
+description: Generate or extend tests until the unit target is met
+argument-hint: "<target> [--coverage <n>] [--agent <inline|auto|name>] [--auto]"
+allowed-tools: ["Bash", "Read", "Write", "Edit", "Skill"]
+---
+
+# Dev Unit
+
+Wraps the **sp:code-testing** skill.
+
+## Argument Flags
+
+| Flag | Description | Default |
+| --- | --- | --- |
+| `<target>` | File / module / path to generate tests for. | required |
+| `--coverage` `<n>` | Coverage percentage target. | configured |
+| `--agent` `<inline\|auto\|name>` | Who runs the model-bearing test work. | inline |
+| `--auto` | Skip objective HITL gates. | off |
+
+For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag-glossary.md).
+
+## Usage
+
+/sp:dev-unit <target> [--coverage <n>] [--agent <inline|auto|name>] [--auto]
+
+## Implementation
+
+- Apply the [inline-default execution-surface contract](../skills/spur-dev/references/cross-cutting.md#inline-default-execution-surface).
+- `Skill(skill="sp:code-testing", args="$ARGUMENTS")`

package/plugins/sp/commands/dev-verify.md

@@ -0,0 +1,48 @@
+---
+description: Verify a task against its requirements and Acceptance Criteria — traceability check producing a PASS/PARTIAL/FAIL verdict with evidence
+argument-hint: "<wbs> [--agent <inline|auto|name>] [--fix <none|blockers-first|all>] [--focus <lens>] [--bdd] [--auto] [--force] [--next] [--skip-shippable]"
+allowed-tools: ["Bash", "Read", "Skill"]
+---
+
+# Dev Verify
+
+Wraps the **sp:code-verification** skill.
+
+## Argument Flags
+
+| Flag | Description | Default |
+| --- | --- | --- |
+| `<wbs>` | Task WBS to verify. | required |
+| `--agent` `<inline\|auto\|name>` | Who runs the model-bearing verification. | inline |
+| `--fix` `<none\|blockers-first\|all>` | Auto-fix policy on findings. | none |
+| `--focus` `<lens>` | Verification lens. | omitted |
+| `--bdd` | Run BDD scenarios. | off |
+| `--auto` | Skip objective HITL gates. | off |
+| `--force` | Re-run even if already verified. | off |
+| `--next` | Hand off to the next-router on success. | off |
+| `--skip-shippable` | Compatibility alias for --skip-shipable; skip the shippable gate. | off |
+
+For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag-glossary.md).
+
+## Usage
+
+```
+/sp:dev-verify <wbs> [--agent <inline|auto|name>] [--fix <none|blockers-first|all>] [--focus <lens>] [--bdd] [--auto] [--force] [--next] [--skip-shippable]
+```
+
+**Shippable readiness** (feature-level): when `--fix all` and the task has a `feature_id`, the
+skill runs `spur feature check <id>` after the per-task verdict and emits `Shippable: PASS|FAIL|N/A`.
+Default **on** with `--fix all`. Opt out only with **`--skip-shippable`** (alias `--skip-shipable`).
+See `sp:code-verification` § Shippable readiness gate.
+
+## Implementation
+
+- Apply the [inline-default execution-surface contract](../skills/spur-dev/references/cross-cutting.md#inline-default-execution-surface).
+- `Skill(skill="sp:code-verification", args="verify $ARGUMENTS")`
+
+**Flags:**
+
+`--next`: chain-to-completion with
+propagation — on a PASS verdict, hand the task back to `sp:next-router` to advance and re-invoke
+until done or a gate stops it. The `testing → done` transition is the chain's first hop. A PARTIAL
+or FAIL verdict halts the chain (task stays `testing` as review-pending). **was: `--next` chain-ish (undefined formally).**

package/plugins/sp/commands/dev-verifyall.md

@@ -0,0 +1,72 @@
+---
+description: Verify a batch of tasks against their requirements and Acceptance Criteria — batch traceability check producing per-task verdicts and a summary report
+argument-hint: "--tasks <selector> [--feature <id>] [--agent <inline|auto|name>] [--fix <none|blockers-first|all>] [--focus <lens>] [--bdd] [--auto] [--force] [--next] [--json] [--skip-shippable] [--worktree [<name>]]"
+allowed-tools: ["Bash", "Read", "Skill"]
+---
+
+# Dev Verifyall
+
+Wraps the **sp:spur-dev** and **sp:code-verification** skills.
+
+## Argument Flags
+
+| Flag | Description | Default |
+| --- | --- | --- |
+| `--tasks` `<selector>` | Task selector to verify. | required |
+| `--feature` `<id>` | Restrict to a feature. | omitted |
+| `--agent` `<inline\|auto\|name>` | Who runs each verification. | inline |
+| `--fix` `<none\|blockers-first\|all>` | Auto-fix policy on findings. | none |
+| `--focus` `<lens>` | Verification lens. | omitted |
+| `--bdd` | Run BDD scenarios. | off |
+| `--auto` | Skip objective HITL gates. | off |
+| `--force` | Re-run even if already verified. | off |
+| `--next` | Hand off to the next-router on success. | off |
+| `--json` | Emit structured JSON. | off |
+| `--skip-shippable` | Compatibility alias for --skip-shipable; skip the shippable gate. | off |
+| `--worktree` `[<name>]` | Run the batch in an isolated git worktree; FF-merge on success, retain on failure. Bare `--worktree` creates a fresh tree; `--worktree <name>` adopts an existing worktree by name/path/branch. | off |
+
+For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag-glossary.md).
+
+## Usage
+
+```
+/sp:dev-verifyall --tasks <selector> [--feature <id>] [--agent <inline|auto|name>] [--fix <none|blockers-first|all>] [--focus <lens>] [--bdd] [--auto] [--force] [--next] [--json] [--skip-shippable] [--worktree [<name>]]
+```
+
+Flags: `--tasks <selector>` (required unless `--feature`), `--feature <id>` (sugar for
+`feature:<id>`), shared verify flags (`--agent`, `--fix`,
+`--focus`, `--bdd`,
+`--auto`, `--force`),
+`--next` (per-task lifecycle chaining — see below),
+`--json`, `--skip-shippable`, `--worktree` `[<name>]` (run the batch in an isolated git worktree — FF-merge
+onto the base ref on full success, retain intact on any failure/halt/non-FF; bare form creates a
+fresh tree, `<name>` form adopts an existing worktree by name/path/branch; see
+`execution-batch.md` § Worktree isolation).
+**`--worktree` corpus visibility.** While the batch runs in a worktree, corpus writes (task
+statuses, verdicts) land in the worktree copy; your main tree still shows pre-run statuses until
+the FF-merge on success. Expected, not a bug.
+
+**`--next` (per-task lifecycle chaining):** `--next`
+is chain-to-completion with propagation. For each task whose verdict is **PASS**, the chain's first
+hop transitions `testing → done` through the FSM with the `--strict-core` Review L3 guard honored;
+a task whose verdict is **PARTIAL** or **FAIL** does **not** transition (it stays `testing` as
+review-pending) — that task's chain halts, reporting the verdict. One task's non-PASS never blocks
+another task's transition — each task's verdict is its own, and each task's chain is independent.
+Transitions run **before** the shippable gate (R3), so `spur feature check` observes the final
+statuses. Do not confuse with `--keep-going`
+(batch failure policy, dev-runall) or `--continue`
+(resume from checkpoint) — see the glossary. **was: `--next` chain-ish (per-task transition, undefined formally).**
+
+**Shippable readiness** (feature-level): when `--fix all` and a feature context exists
+(`--feature` or a unique shared `feature_id` across the set), after all per-task verifies the
+orchestrator runs **one** `spur feature check <id>` and emits `Shippable: PASS|FAIL|N/A`.
+A FAIL means the batch is **not clean** (rollup at least PARTIAL) even if every task AC PASSed.
+Default **on** with `--fix all`. Opt out only with **`--skip-shippable`** (alias `--skip-shipable`).
+Without `--fix all`, shippable is not evaluated (optional note: use `--fix all` for ship gate).
+
+## Implementation
+
+- Apply the [inline-default execution-surface contract](../skills/spur-dev/references/cross-cutting.md#inline-default-execution-surface).
+- Batch orchestration: `Skill(skill="sp:spur-dev", args="verifyall $ARGUMENTS")`
+- Per-task verification (inner): `Skill(skill="sp:code-verification", args="verify <wbs> $SHARED_FLAGS")`
+- Shippable gate: once after the batch (same skill § Shippable readiness gate)

package/plugins/sp/commands/dev-wrap.md

@@ -0,0 +1,48 @@
+---
+description: Wrap up a single completed task — learnings, metrics, doc-sync, optional feature transition and branch cleanup
+argument-hint: "<wbs> [--agent <inline|auto|name>] [--auto] [--merge] [--dry-run]"
+allowed-tools: ["Bash", "Read", "AskUserQuestion"]
+---
+
+# Dev Wrap
+
+Wraps the **wrapup-pipeline.yaml** workflow.
+
+## Argument Flags
+
+| Flag | Description | Default |
+| --- | --- | --- |
+| `<wbs>` | Task WBS to wrap. | required |
+| `--agent` `<inline\|auto\|name>` | Who runs the wrap's model-bearing steps. Wrap is workflow-backed: omit/`inline` resolves to `agent.default` (objective trigger 3 — durable auditable run record required); `auto` tier-resolves an executor; a name pins that executor into `vars.agent`. | agent.default |
+| `--auto` | Skip objective HITL gates. | off |
+| `--merge` | Merge the wrap branch. | off |
+| `--dry-run` | Render the wrap without writing. | off |
+
+For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag-glossary.md).
+
+## Usage
+
+/sp:dev-wrap <wbs> [--agent <inline|auto|name>] [--auto] [--merge] [--dry-run]
+
+## Implementation
+
+- Apply the [inline-default execution-surface contract](../skills/spur-dev/references/cross-cutting.md#inline-default-execution-surface).
+- Wrap stays **workflow-backed** — `spur workflow run .spur/workflows/wrapup-pipeline.yaml` is the only implementation; there is no inline wrap driver.
+- Resolve the executor **before** launching the workflow:
+  - `--agent <name>` → pass the name unchanged into `vars.agent`.
+  - `--agent auto` → tier-resolve a concrete executor first, then merge it into `vars.agent`.
+  - omit/`--agent inline` → resolve to `agent.default` (the documented headless resolution of `inline`).
+- Emit a pre-dispatch notice naming the override before `spur workflow run`, exactly:
+  `execution surface: subprocess`, `reason: trigger 3 — durable auditable run record required`, `requested agent: inline|auto|<name>`, `executor: agent.default|<resolved-name>`.
+- The wrap workflow still creates its durable run record (task_run_links / trace) — the notice reports the override, it does not change the workflow.
+
+```bash
+AGENT=… # resolved above: agent.default for inline/omitted, tier-resolved for auto, unchanged for <name>
+echo "execution surface: subprocess; reason: trigger 3 — durable auditable run record required; requested agent: <inline|auto|name>; executor: $AGENT"
+VARS=$(jq -nc --arg tasks "[\"$WBS\"]" --arg agent "$AGENT" --arg profile "$PROFILE" --arg merge "$MERGE" \
+  '{tasks:$tasks, agent:$agent, profile:$profile, merge:$merge}')
+spur workflow run .spur/workflows/wrapup-pipeline.yaml --vars "$VARS" [--dry-run]
+```
+
+The executor resolution is described in the bullets above; the snippet's `AGENT` variable carries
+the resolved name (`agent.default` for omit/`inline`).

package/plugins/sp/commands/dev-wrapall.md

@@ -0,0 +1,51 @@
+---
+description: Wrap up a batch of completed tasks — learnings, metrics, doc-sync, feature transition, optional branch cleanup
+argument-hint: "[--since <iso-date>] [--feature <id>] [--status <s>] [--agent <inline|auto|name>] [--auto] [--merge] [--dry-run]"
+allowed-tools: ["Bash", "Read", "AskUserQuestion"]
+---
+
+# Dev Wrapall
+
+Wraps the **wrapup-pipeline.yaml** workflow.
+
+## Argument Flags
+
+| Flag | Description | Default |
+| --- | --- | --- |
+| `--since` `<iso-date>` | Wrap tasks completed since a date. | configured |
+| `--feature` `<id>` | Wrap tasks in a feature. | omitted |
+| `--status` `<s>` | Only wrap tasks in a status. | done |
+| `--agent` `<inline\|auto\|name>` | Who runs the wrap's model-bearing steps. Wrap is workflow-backed: omit/`inline` resolves to `agent.default` (objective trigger 3 — durable auditable run record required); `auto` tier-resolves an executor; a name pins that executor into `vars.agent`. | agent.default |
+| `--auto` | Skip objective HITL gates. | off |
+| `--merge` | Merge wrap branches. | off |
+| `--dry-run` | Render wraps without writing. | off |
+
+For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag-glossary.md).
+
+## Usage
+
+/sp:dev-wrapall [--since <iso-date>] [--feature <id>] [--status <s>] [--agent <inline|auto|name>] [--auto] [--merge] [--dry-run]
+
+## Implementation
+
+- Apply the [inline-default execution-surface contract](../skills/spur-dev/references/cross-cutting.md#inline-default-execution-surface).
+- Wrap stays **workflow-backed** — `spur workflow run .spur/workflows/wrapup-pipeline.yaml` is the only implementation; there is no inline wrap driver.
+- Resolve the executor **before** launching the workflow:
+  - `--agent <name>` → pass the name unchanged into `vars.agent`.
+  - `--agent auto` → tier-resolve a concrete executor first, then merge it into `vars.agent`.
+  - omit/`--agent inline` → resolve to `agent.default` (the documented headless resolution of `inline`).
+- Emit a pre-dispatch notice naming the override before `spur workflow run`, exactly:
+  `execution surface: subprocess`, `reason: trigger 3 — durable auditable run record required`, `requested agent: inline|auto|<name>`, `executor: agent.default|<resolved-name>`.
+- The wrap workflow still creates its durable run record — the notice reports the override, it does not change the workflow.
+
+```bash
+AGENT=… # resolved above: agent.default for inline/omitted, tier-resolved for auto, unchanged for <name>
+echo "execution surface: subprocess; reason: trigger 3 — durable auditable run record required; requested agent: <inline|auto|name>; executor: $AGENT"
+VARS=$(jq -nc --arg tasks "$TASKS" --arg feature "$FEATURE" --arg agent "$AGENT" --arg profile "$PROFILE" --arg merge "$MERGE" \
+  '{tasks:$tasks, feature:$feature, agent:$agent, profile:$profile, merge:$merge}')
+spur workflow run .spur/workflows/wrapup-pipeline.yaml --vars "$VARS" [--dry-run]
+```
+
+The executor resolution is described in the bullets above; the snippet's `AGENT` variable carries
+the resolved name (`agent.default` for omit/`inline`).
+

package/plugins/sp/commands/rule-add.md

@@ -0,0 +1,18 @@
+---
+description: Author a validated, smoke-tested constraint rule
+argument-hint: "\"<description>\" [--file <path>] [--preset <target>]"
+allowed-tools: ["Bash", "Read", "Write", "Skill"]
+---
+
+# Rule Add
+
+Wraps the **sp:spur-cli** skill.
+
+## Usage
+
+/sp:rule-add "<description>" [--file <path>] [--preset <target>]
+
+## Implementation
+
+- `Skill(skill="sp:spur-cli", args="rule add $ARGUMENTS")`
+

package/plugins/sp/commands/rule-refine.md

@@ -0,0 +1,18 @@
+---
+description: Refine a constraint rule or preset, then re-verify it
+argument-hint: "<rule-file-or-preset> [--intent \"<goal>\"] [--severity <sev>] [--scope <glob>] [--exempt <path>] [--disable <id>] [--override <id>] [--dry-run]"
+allowed-tools: ["Bash", "Read", "Edit", "Skill"]
+---
+
+# Rule Refine
+
+Wraps the **sp:spur-cli** skill.
+
+## Usage
+
+/sp:rule-refine <rule-file-or-preset> [--intent "<goal>"] [--severity <sev>] [--scope <glob>] [--exempt <path>] [--disable <id>] [--override <id>] [--dry-run]
+
+## Implementation
+
+- `Skill(skill="sp:spur-cli", args="rule refine $ARGUMENTS")`
+

package/plugins/sp/commands/rule-scan.md

@@ -0,0 +1,18 @@
+---
+description: Discover recurring anti-patterns worth codifying as rules
+argument-hint: "[<path-or-glob>]"
+allowed-tools: ["Bash", "Read", "Grep", "Glob", "Skill"]
+---
+
+# Rule Scan
+
+Wraps the **sp:spur-cli** skill.
+
+## Usage
+
+/sp:rule-scan [<path-or-glob>]
+
+## Implementation
+
+- `Skill(skill="sp:spur-cli", args="rule scan $ARGUMENTS")`
+

package/plugins/sp/commands/spur-init.md

@@ -0,0 +1,22 @@
+---
+description: Initialize a new Spur project — scaffold config + docs, then customize for this project's stack and scope
+argument-hint: "[--name <name>] [--minimal] [--force]"
+allowed-tools: ["Bash", "Read", "Write", "Skill"]
+---
+
+# Spur Init
+
+Wraps **spur init** (deterministic scaffold) + **sp:doc-evolve** (project customization).
+
+## Usage
+
+/sp:spur-init [--name <name>] [--minimal] [--force]
+
+## Implementation
+
+```bash
+spur init --json $ARGUMENTS
+```
+- Parse the JSON envelope once and retain it as `scaffoldResult`; summarize its created/skipped files in one block.
+- Customize (Phase 2): `Skill(skill="sp:doc-evolve", args="customize --project <scaffoldResult.project>")`.
+  Reuse the retained project value; do not rerun init or replay its create/exists transcript.

package/plugins/sp/commands/workflow-add.md

@@ -0,0 +1,18 @@
+---
+description: Author a validated, dry-run-verified workflow in the right execution mode
+argument-hint: "\"<description>\" [--kind <state-machine|transition-flow>] [--file <path>]"
+allowed-tools: ["Bash", "Read", "Write", "Skill"]
+---
+
+# Workflow Add
+
+Wraps the **sp:spur-cli** skill.
+
+## Usage
+
+/sp:workflow-add "<description>" [--kind <state-machine|transition-flow>] [--file <path>]
+
+## Implementation
+
+- `Skill(skill="sp:spur-cli", args="workflow add $ARGUMENTS")`
+

package/plugins/sp/commands/workflow-refine.md

@@ -0,0 +1,18 @@
+---
+description: Refine an existing workflow, then re-validate and re-dry-run it
+argument-hint: "<workflow-file> [--intent \"<goal>\"] [--dry-run]"
+allowed-tools: ["Bash", "Read", "Edit", "Skill"]
+---
+
+# Workflow Refine
+
+Wraps the **sp:spur-cli** skill.
+
+## Usage
+
+/sp:workflow-refine <workflow-file> [--intent "<goal>"] [--dry-run]
+
+## Implementation
+
+- `Skill(skill="sp:spur-cli", args="workflow refine $ARGUMENTS")`
+

package/plugins/sp/hooks/agent-hint.ts

@@ -0,0 +1,60 @@
+/**
+ * Shared host-agent identification helpers — the **only** host-agent detection path
+ * in the sp plugin hooks.
+ *
+ * Why this file exists (task 0480 R4): `resolveAgentHint()` previously existed in two
+ * places — `context-session-start.ts` (4-candidate chain, `undefined` fallback) and
+ * `pi/guard-extension.ts` (3-candidate chain missing `CLAUDE_CODE_ENTRYPOINT` and
+ * `CLAUDE_MODEL`, `'pi'` fallback). The divergence let the two layers reach opposite
+ * conclusions about whether the calling agent is identifiable. Consolidating here
+ * guarantees both hooks use the same candidate list and cannot silently diverge again.
+ *
+ * **Do not duplicate this candidate chain elsewhere.** New host-agent signals are
+ * added to the arrays below, not to per-hook copies.
+ */
+
+/**
+ * Best-effort agent name from env (never required).
+ *
+ * Candidate chain (checked in order, first non-empty string wins):
+ * 1. `SPUR_AGENT` — explicit override
+ * 2. `CLAUDE_CODE_ENTRYPOINT` — Claude Code sets this to its entrypoint path
+ * 3. `TERM_PROGRAM` — terminal identifier (e.g. `claude`, `ghostty`)
+ * 4. `SPUR_DEFAULT_AGENT` — configured default agent
+ *
+ * @param env - environment record (defaults to `process.env`)
+ * @param fallback - value returned when no candidate matches (defaults to `undefined`)
+ */
+export function resolveAgentHint(
+    env: NodeJS.ProcessEnv = process.env,
+    fallback: string | undefined = undefined,
+): string | undefined {
+    const candidates = [env.SPUR_AGENT, env.CLAUDE_CODE_ENTRYPOINT, env.TERM_PROGRAM, env.SPUR_DEFAULT_AGENT];
+    for (const c of candidates) {
+        if (typeof c === 'string' && c.trim()) return c.trim();
+    }
+    return fallback;
+}
+
+/**
+ * Best-effort model id from env (never required).
+ *
+ * Candidate chain (checked in order, first non-empty string wins):
+ * 1. `SPUR_MODEL` — explicit override
+ * 2. `ANTHROPIC_MODEL` — Anthropic API model
+ * 3. `OPENAI_MODEL` — OpenAI API model
+ * 4. `CLAUDE_MODEL` — Claude Code model setting
+ *
+ * @param env - environment record (defaults to `process.env`)
+ * @param fallback - value returned when no candidate matches (defaults to `undefined`)
+ */
+export function resolveModelHint(
+    env: NodeJS.ProcessEnv = process.env,
+    fallback: string | undefined = undefined,
+): string | undefined {
+    const candidates = [env.SPUR_MODEL, env.ANTHROPIC_MODEL, env.OPENAI_MODEL, env.CLAUDE_MODEL];
+    for (const c of candidates) {
+        if (typeof c === 'string' && c.trim()) return c.trim();
+    }
+    return fallback;
+}