@gobing-ai/spur 0.3.46 → 0.3.48

package/plugins/sp/commands/dev-find-issue.md

@@ -1,13 +1,15 @@
 ---
-description: "Review agent session logs, identify performance bottlenecks and behavioral anti-patterns, and generate a structured task file with proposed fixes. Triggers: post-mortem, performance analysis, session review, find issues, identify bottlenecks"
-argument-hint: "[<topic>] [--sessions <glob>] [--source <auto|omp|claude|codex|gemini|opencode|antigravity|openclaw|pi>] [--feature <id>] [--template <meta|issue|standard>] [--priority <P0|P1|P2|P3>] [--severity <S0|S1|S2>] [--category <list>] [--since <iso>] [--until <iso>] [--top <n>] [--min-cost <duration>] [--strict-topic] [--use-history] [--no-task] [--agent <inline|auto|name>] [--json]"
+description: "Render the session-forensics report from imported history data (8 CLI-derivable sections plus 6 model-authored), identify bottlenecks and behavioral anti-patterns, and optionally create a structured fix task behind --create-task. Triggers: post-mortem, performance analysis, session review, find issues, identify bottlenecks"
+role: reviewer
+argument-hint: "[<topic>] [--sessions <glob>] [--source <auto|omp|claude|codex|gemini|opencode|antigravity|openclaw|pi>] [--feature <id>] [--template <meta|issue|standard>] [--priority <P0|P1|P2|P3>] [--severity <S0|S1|S2>] [--category <list>] [--since <iso>] [--until <iso>] [--top <n>] [--min-cost <duration>] [--strict-topic] [--create-task] [--agent <inline|auto|name>] [--json]"
 allowed-tools: ["Bash", "Read", "Write", "Grep", "Glob", "Skill"]
 ---
 
 # Dev Find Issue
 
-Wraps the **sp:issue-finding** skill — forensic session log analysis that identifies performance
-bottlenecks, ranks root causes by time cost, proposes targeted fixes, and generates a structured
+Wraps the **sp:issue-finding** skill — report-first session forensics over the history data plane.
+The CLI renders the 8 derivable report sections (`spur history report --mode forensics`); the skill
+identifies bottlenecks, proposes fixes, and — only with `--create-task` — generates a structured
 task file via `spur task create`.
 
 ## Argument Flags
@@ -15,21 +17,20 @@ task file via `spur task create`.
 | Flag                                                                                 | Description                          | Default    |
 | ------------------------------------------------------------------------------------ | ------------------------------------ | ---------- |
 | `[<topic>]`                                                                          | Narrow the analysis to a topic.      | omitted    |
-| `--sessions` `<glob>`                                                                | Session log glob to scan.            | recent     |
+| `--sessions` `<glob>`                                                                | Session log glob (fallback input).   | recent     |
 | `--source` `<auto\|omp\|claude\|codex\|gemini\|opencode\|antigravity\|openclaw\|pi>` | Agent source to scan.                | auto       |
-| `--feature` `<id>`                                                                   | Attach findings to a feature.        | omitted    |
-| `--template` `<meta\|issue\|standard>`                                               | Output template shape.               | standard   |
-| `--priority` `<P0\|P1\|P2\|P3>`                                                      | Filter / assign priority.            | omitted    |
-| `--severity` `<S0\|S1\|S2>`                                                          | Filter / assign severity.            | omitted    |
+| `--feature` `<id>`                                                                   | Attach the generated task to a feature. | omitted |
+| `--template` `<meta\|issue\|standard>`                                               | Task template shape (`--create-task` only). | standard |
+| `--priority` `<P0\|P1\|P2\|P3>`                                                      | Filter / assign task priority.       | P2         |
+| `--severity` `<S0\|S1\|S2>`                                                          | Filter / assign severity.            | all        |
 | `--category` `<list>`                                                                | Comma list of categories to keep.    | all        |
 | `--since` `<iso>`                                                                    | Start of the scan window.            | configured |
 | `--until` `<iso>`                                                                    | End of the scan window.              | now        |
 | `--top` `<n>`                                                                        | Limit to top N findings.             | omitted    |
 | `--min-cost` `<duration>`                                                            | Minimum wasted duration to report.   | omitted    |
 | `--strict-topic`                                                                     | Drop findings off-topic.             | off        |
-| `--use-history`                                                                      | Incorporate indexed history.         | off        |
-| `--no-task`                                                                          | Do not create a task for findings.   | off        |
-| `--agent` `<inline\|auto\|name>`                                                     | Who runs the model-bearing analysis. | inline     |
+| `--create-task`                                                                      | Generate a fix task for findings.    | off        |
+| `--agent` `<inline\|auto\|name>`                                                     | Who runs the model-bearing analysis. | omit       |
 | `--json`                                                                             | Emit structured JSON.                | off        |
 
 For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag-glossary.md).
@@ -41,28 +42,15 @@ For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag
 /sp:dev-find-issue "test-loop spinning"
 /sp:dev-find-issue --sessions "~/.omp/agent/sessions/-xprojects-spur-new/2026-07-29T*"
 /sp:dev-find-issue "L3 guard format discovery" --feature H51 --priority P1 --severity S1
-/sp:dev-find-issue --category test-loop,guard --min-cost 30m --no-task
-/sp:dev-find-issue --source claude --since 2026-07-28 --json
-/sp:dev-find-issue --sessions plugins/sp/skills/issue-finding/examples/session-test-loop.jsonl --no-task
+/sp:dev-find-issue --category test-loop,guard --min-cost 30m
+/sp:dev-find-issue --source claude --since 2026-07-28 --create-task --json
 ```
 
-| Argument                      | Description                                                                              | Default                         |
-| ----------------------------- | ---------------------------------------------------------------------------------------- | ------------------------------- |
-| `[topic]`                     | Optional focus text or smart positional (path/glob → sessions; category phrase → filter) | (full taxonomy)                 |
-| `--sessions <glob>`           | Session JSONL file(s) or directory                                                       | most recent for resolved source |
-| `--source <name>`             | `auto`, `omp`, `claude`, `codex`, `gemini`, `opencode`, `antigravity`, `openclaw`, `pi`  | `auto`                          |
-| `--feature <id>`              | Feature ID to link the generated task to                                                 | (none)                          |
-| `--template <name>`           | `meta` (umbrella), `issue` (single), or `standard`                                       | `meta`                          |
-| `--priority <P0\|P1\|P2\|P3>` | Task frontmatter priority (not bottleneck severity)                                      | `P2`                            |
-| `--severity <S0\|S1\|S2>`     | Minimum bottleneck severity to keep                                                      | (all)                           |
-| `--category <list>`           | Comma-separated category ids (`test-loop`, `guard`, …)                                   | `all`                           |
-| `--since` / `--until`         | Session start time bounds                                                                | (none)                          |
-| `--top <n>`                   | Cap number of fixes/requirements                                                         | (no cap)                        |
-| `--min-cost <duration>`       | Drop findings under this waste floor (`30m`, `2h`)                                       | (none)                          |
-| `--strict-topic`              | Drop off-topic findings even if severe                                                   | off                             |
-| `--use-history`               | Optional `spur history` import/analyze for cost aggregates                               | off                             |
-| `--no-task`                   | Markdown report only                                                                     | off                             |
-| `--json`                      | JSON findings only (no task)                                                             | off                             |
+**Report-first (task 0556).** Default output is the markdown report to stdout; no task file is
+written. Task creation moved behind `--create-task`. `--use-history` and `--no-task` are removed:
+the history data plane is now the primary source (no flag needed), and the old report-only behavior
+is the new default. Raw JSONL remains a fallback under the three conditions documented in
+`sp:issue-finding`.
 
 **See also:** skill `sp:issue-finding` (SSOT), `/sp:dev-runall`, `/sp:dev-dogfood`,
 `sp:daily-summary`, `sp:reverse-engineering`.

package/plugins/sp/commands/dev-find-next.md

@@ -1,5 +1,6 @@
 ---
 description: "Prompt-first feature frontier prioritizer — answers 'which feature should we work on now?' with a ranked, evidence-carrying frontier, and emits rank-distorting tree defects as proposals /sp:dev-featurechange consumes. Triggers: find next, which feature, feature ranking, frontier priority, what should I work on."
+role: planner
 argument-hint: "[--task [<feature-id>]] [--agent <inline|auto|name>] [--auto] [--json]"
 allowed-tools: ["Bash", "Read", "Write", "Grep", "Glob", "Skill"]
 ---
@@ -19,7 +20,7 @@ Answers *"which X"* — the question `/sp:dev-next` deliberately does not (next-
 | Flag | Description | Default |
 | --- | --- | --- |
 | `--task` `[<feature-id>]` | After the report, confirm one target and dispatch the planning half to produce implement-ready tasks. | omitted |
-| `--agent` `<inline\|auto\|name>` | Who runs the model-bearing analysis. | inline |
+| `--agent` `<inline\|auto\|name>` | Who runs the model-bearing analysis. | omit |
 | `--auto` | Skip the `--task` confirm (accept the offered target) and forward into dispatched children. | off |
 | `--json` | Emit the ranked frontier, gated list, and proposals as a JSON envelope. | off |
 

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

@@ -1,5 +1,6 @@
 ---
 description: Fix all lint, type, and test errors systematically across the working tree
+role: coder
 argument-hint: "[<validation-command>] [--max-retry <n>] [--scope <path>] [--gate-log <path>] [--findings <anchors>]"
 allowed-tools: ["Bash", "Read", "Write", "Edit", "Grep", "Glob"]
 ---

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

@@ -1,5 +1,6 @@
 ---
 description: Generate conventional commit message(s) from staged changes via per-file summarization, optionally commit
+role: scribe
 argument-hint: "[--commit] [--squash] [--scope <path>]"
 allowed-tools: ["Bash", "Read"]
 ---

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

@@ -1,5 +1,6 @@
 ---
 description: Get things done — quality gate → fix → act CI simulation → commit → push → gh verify in one flow
+role: coder
 argument-hint: "[<quality-gate-command>] [--dry-run] [--skip-act] [--no-push] [--no-verify] [--scope <path>] [--max-retry <n>]"
 allowed-tools: ["Bash", "Read", "Write", "Edit", "Grep", "Glob"]
 ---

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

@@ -1,5 +1,6 @@
 ---
 description: Generate a structured handover document when blocked — captures goal, progress, blocker, rejected approaches, and next steps
+role: scribe
 argument-hint: "\"<blocker description>\""
 allowed-tools: ["Bash", "Read", "Write"]
 ---

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

@@ -1,5 +1,6 @@
 ---
 description: Turn a vague idea into a feature with AC and a decomposed task batch — discovery, idea-eval, feature-create, AC, feature-check, system-design, decompose, batch-create (Design by default), handoff
+role: planner
 argument-hint: "\"<idea>\" [--auto] [--skip-design] [--approve-taste]"
 allowed-tools: ["Bash", "Read", "AskUserQuestion"]
 ---

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

@@ -1,5 +1,6 @@
 ---
 description: Status-aware router — pick and run the next best /sp:dev-* step for a task or feature frontier
+role: planner
 argument-hint: "[<wbs|feature-id>] [--dry-run] [--once] [--auto] [--agent <inline|auto|name>] [--full]"
 allowed-tools: ["Bash", "Read", "Skill", "AskUserQuestion"]
 ---
@@ -16,7 +17,7 @@ Wraps the **sp:next-router** skill.
 | `--dry-run` | Resolve and print the next step without executing. | off |
 | `--once` | Resolve exactly one step and stop. | off |
 | `--auto` | Skip objective HITL gates in the dispatched step. | off |
-| `--agent` `<inline\|auto\|name>` | Who runs the dispatched model-bearing step. | inline |
+| `--agent` `<inline\|auto\|name>` | Who runs the dispatched model-bearing step. | omit |
 | `--full` | When the primary route is `dev-run … --next`, substitute `dev-run <wbs> --mode full` (no `--next`). No effect on other routes (warning W-FULL). | off |
 
 For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag-glossary.md).

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

@@ -1,5 +1,6 @@
 ---
 description: Fan out independent tasks or investigations in parallel via subagents — choose the right pattern and synthesize results
+role: planner
 argument-hint: "--tasks <selector> [--feature <id>] [--mode <fan-out|review-panel|investigation>] [--agent <inline|auto|name>] [--json]"
 allowed-tools: ["Bash", "Read", "Skill"]
 ---
@@ -15,7 +16,7 @@ Wraps the **sp:parallel-execution** skill.
 | `--tasks` `<selector>` | Task selector to fan out. | required |
 | `--feature` `<id>` | Restrict the selector to a feature. | omitted |
 | `--mode` `<fan-out\|review-panel\|investigation>` | Fan-out pattern. | fan-out |
-| `--agent` `<inline\|auto\|name>` | Who runs each dispatched slice. | inline |
+| `--agent` `<inline\|auto\|name>` | Who runs each dispatched slice. Parallel fan-out is dispatch, so explicit `--agent inline` runs the batch **sequentially in the host session** with a printed notice (zero dispatch); omit keeps the default fan-out semantics; `auto` tier-resolves an executor; a name pins that executor. | omit |
 | `--json` | Emit structured JSON. | off |
 
 For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag-glossary.md).

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

@@ -1,5 +1,6 @@
 ---
 description: Plan a feature from a description — intake → feature create → AC generation → feature check gate → decomposition → batch-create (Design by default)
+role: planner
 argument-hint: "\"<description>\" [--feature <id>] [--parent <feature-id>] [--agent <inline|auto|name>] [--skip-design] [--auto] [--approve-taste]"
 allowed-tools: ["Bash", "Read", "Skill", "AskUserQuestion"]
 ---
@@ -15,7 +16,7 @@ Wraps the **sp:spur-dev** skill.
 | `"<description>"` | Feature description to plan. | required |
 | `--feature` `<id>` | Attach to an existing feature. | omitted |
 | `--parent` `<feature-id>` | Create under a parent feature. | omitted |
-| `--agent` `<inline\|auto\|name>` | Who runs the model-bearing planning. The planning pipeline's `agent.run` stages always dispatch a subprocess; `inline` is accepted there as a synonym for omit, resolving to `agent.default` (ADR-047). `auto` tier-resolves an executor; a name pins that executor. | agent.default |
+| `--agent` `<inline\|auto\|name>` | Who runs the model-bearing planning. The planning pipeline's `agent.run` stages are headless — they always dispatch a subprocess. Explicit `--agent inline` is rejected there with the stable special error (exit 2): a headless surface cannot host a session — no dispatch, no `agent.default` fallback. Use `omit` (resolves to `agent.default`), `auto` (tier-resolves an executor), or a name (pins that executor). | agent.default |
 | `--skip-design` | Omit the system-design hop. | off |
 | `--auto` | Skip objective HITL gates. | off |
 | `--approve-taste` | With --auto: skip design-approval pause. | off |

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

@@ -1,5 +1,6 @@
 ---
 description: Refine task requirements via structured Q&A — clarify scope, elicit missing details, tighten acceptance criteria; optional implement-ready depth
+role: planner
 argument-hint: "<wbs> [--focus <mode>] [--description <text>] [--depth <standard|ready>] [--agent <inline|auto|name>] [--auto] [--next]"
 allowed-tools: ["Bash", "Read", "Skill", "AskUserQuestion"]
 ---
@@ -18,7 +19,7 @@ agent will implement and L3-clean is not enough (frozen APIs, anti-patterns, fil
 | `--focus` `<mode>` | Refinement focus mode. | omitted |
 | `--description` `<text>` | Override the task description. | omitted |
 | `--depth` `<standard\|ready>` | Spec depth bar (see flag glossary). | `standard` |
-| `--agent` `<inline\|auto\|name>` | Who runs the model-bearing refinement. | inline |
+| `--agent` `<inline\|auto\|name>` | Who runs the model-bearing refinement. | omit |
 | `--auto` | Skip objective HITL gates. | off |
 | `--next` | Hand off to the next-router on success. | off |
 
@@ -34,8 +35,9 @@ Under `--auto` with **`--depth standard`** (default), SKIP only when target sect
 findings: Background, Requirements, Acceptance Criteria, Design, Plan. Solution is not a refine
 target. Under **`--depth ready`**, do **not** SKIP on L3-clean alone — run the implement-ready
 checklist (dev-operations § refine) and rewrite Design/Requirements/Plan until another agent can
-implement without inventing design. Stage floor: `standard` (fallback `capable-2`); ready synthesis
-may use a higher tier when the task spans packages/seams.
+implement without inventing design. Stage floor: the `planner` role per
+[`roles.md`](../references/roles.md) — this command names roles, never tiers (0538 R4);
+ready synthesis may use a higher tier when the task spans packages/seams.
 
 ## Implementation
 

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

@@ -1,5 +1,6 @@
 ---
 description: Refine a batch of tasks via structured Q&A — resolve a set (feature or selector), refine each in dependency-correct order, emit a batch report; optional implement-ready depth
+role: planner
 argument-hint: "--feature <id> | --tasks <selector> [--focus <mode>] [--description <text>] [--depth <standard|ready>] [--agent <inline|auto|name>] [--auto] [--keep-going] [--status <s>] [--json] [--worktree [<name>]]"
 allowed-tools: ["Bash", "Read", "Skill", "AskUserQuestion"]
 ---
@@ -19,7 +20,7 @@ operation, applied to a resolved set (typically every task under a feature). Pas
 | `--focus` `<mode>` | Refinement focus mode. | omitted |
 | `--description` `<text>` | Override description for each task. | omitted |
 | `--depth` `<standard\|ready>` | Spec depth bar (see flag glossary). | `standard` |
-| `--agent` `<inline\|auto\|name>` | Who runs the model-bearing refinement. | inline |
+| `--agent` `<inline\|auto\|name>` | Who runs the model-bearing refinement. | omit |
 | `--auto` | Skip objective HITL gates. | off |
 | `--keep-going` | Continue past per-task failures. | off |
 | `--status` `<s>` | Only refine tasks in a status. | backlog,todo |

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

@@ -1,5 +1,6 @@
 ---
 description: Refresh feature status by feature ID, task WBS, or batch sweep via spur feature sync
+role: scribe
 argument-hint: "[<feature-id|wbs>] [--all] [--auto] [--agent <inline|auto|name>]"
 allowed-tools: ["Bash", "Read", "Skill"]
 ---
@@ -15,7 +16,7 @@ Wraps the **sp:spur-dev** skill.
 | `[<feature-id\|wbs>]` | Feature id or task WBS to refresh. | active |
 | `--all` | Refresh every feature. | off |
 | `--auto` | Skip objective HITL gates. | off |
-| `--agent` `<inline\|auto\|name>` | Who runs the model-bearing refresh. | inline |
+| `--agent` `<inline\|auto\|name>` | Who runs the model-bearing refresh. | omit |
 
 For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag-glossary.md).
 

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

@@ -1,5 +1,6 @@
 ---
 description: Reverse engineer a codebase with selectable depth, focus, and output format
+role: coder
 argument-hint: "[<path>] [--mode <briefing|structure|architecture|design|full>] [--focus <all|stack|dependencies|data|flows|api|security|quality|performance>] [--format <markdown|json|both>] [--output <file>] [--agent <inline|auto|name>]"
 allowed-tools: ["Read", "Write", "Edit", "Grep", "Glob", "Bash", "Skill"]
 ---
@@ -17,7 +18,7 @@ Wraps the **sp:reverse-engineering** skill.
 | `--focus` `<all\|stack\|dependencies\|data\|flows\|api\|security\|quality\|performance>` | Analysis lens. | all |
 | `--format` `<markdown\|json\|both>` | Output format. | markdown |
 | `--output` `<file>` | Write to a file instead of stdout. | stdout |
-| `--agent` `<inline\|auto\|name>` | Who runs the model-bearing analysis. | inline |
+| `--agent` `<inline\|auto\|name>` | Who runs the model-bearing analysis. | omit |
 
 For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag-glossary.md).
 

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

@@ -1,5 +1,6 @@
 ---
 description: "Review code for a task or path — multi-dimensional review across functional traceability, SECUA quality, and architectural depth. Triggers: \"review this\", \"check the code\", \"SECUA review\", \"dev review\", \"audit this\"."
+role: reviewer
 argument-hint: "[<wbs|path>] [--agent <inline|auto|name>] [--focus <dims>] [--fix (deprecated)]"
 allowed-tools: ["Bash", "Read", "Skill"]
 ---
@@ -13,7 +14,7 @@ Wraps the **sp:functional-review**, **sp:code-verification**, and **sp:code-impr
 | Flag | Description | Default |
 | --- | --- | --- |
 | `[<wbs\|path>]` | Task WBS or source path to review. | cwd |
-| `--agent` `<inline\|auto\|name>` | Who runs the model-bearing review. | inline |
+| `--agent` `<inline\|auto\|name>` | Who runs the model-bearing review. | omit |
 | `--focus` `<dims>` | Review dimensions (functional / SECUA / architecture). | all |
 | `--fix` | Deprecated no-op + warning; route remediation to /sp:dev-verify --fix. | off |
 

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

@@ -1,5 +1,6 @@
 ---
 description: Run a task — full pipeline (precheck→implement→test→review→approve→verify→record→done) or single-step (implement)
+role: coder
 argument-hint: "<wbs> [--mode <full|implement>] [--agent <inline|auto|name>] [--auto] [--next] [--wrap] [--continue]"
 allowed-tools: ["Bash", "Read", "Write", "Edit", "Skill"]
 ---
@@ -14,7 +15,7 @@ Wraps the **sp:spur-dev** and **sp:code-implementation** skills.
 | --- | --- | --- |
 | `<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 |
+| `--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) — **omit**'s eligible full-mode `agent.run` stages may dispatch once to a native subagent, with host fallback (task 0508); explicit `--agent inline` is the zero-dispatch carve-out (every stage executes in the invoking session, never a native subagent). `auto` or a name keeps subprocess dispatch. | omit |
 | `--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 |
@@ -37,7 +38,7 @@ For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag
 
 **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).
+- `--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 **omitted** `--agent`'s eligible `agent.run` stages may dispatch once to a native subagent and otherwise run in the host (task 0508); explicit `--agent inline` is the zero-dispatch carve-out — every stage executes in the invoking session. 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)**
 

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

@@ -1,5 +1,6 @@
 ---
 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
+role: planner
 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"]
 ---
@@ -17,7 +18,7 @@ Wraps the **sp:spur-dev** skill.
 | `--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 |
+| `--agent` `<inline\|auto\|name>` | Who runs each task's pipeline stages. Interactive sequential omit/`inline` uses the host-session driver — host-controlled; **omit**'s eligible `agent.run` stages may use a native subagent (task 0508); explicit `--agent inline` is the zero-dispatch carve-out (every stage executes in the invoking session). `auto`, a name, parallel mode, and headless invocation use subprocesses. | omit |
 | `--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 |
@@ -80,6 +81,6 @@ 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.
+- 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); **omitted** `--agent`'s eligible `agent.run` stages may dispatch once to a native subagent with host fallback (task 0508); explicit `--agent inline` is the zero-dispatch carve-out. `--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

@@ -1,5 +1,6 @@
 ---
 description: Simplify code for clarity without changing behavior — reduce complexity in recent changes (or a given scope), preserving behavior exactly
+role: coder
 argument-hint: "[<path-or-scope>] [--scope <recent|all|path>] [--check <cmd>] [--agent <inline|auto|name>] [--auto]"
 allowed-tools: ["Bash", "Read", "Edit", "Skill"]
 ---
@@ -15,7 +16,7 @@ Wraps the **sp:code-simplification** skill.
 | `[<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 |
+| `--agent` `<inline\|auto\|name>` | Who runs the model-bearing simplification. | omit |
 | `--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).

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

@@ -1,5 +1,6 @@
 ---
 description: Generate or extend tests until the unit target is met
+role: coder
 argument-hint: "<target> [--coverage <n>] [--agent <inline|auto|name>] [--auto]"
 allowed-tools: ["Bash", "Read", "Write", "Edit", "Skill"]
 ---
@@ -14,7 +15,7 @@ Wraps the **sp:code-testing** skill.
 | --- | --- | --- |
 | `<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 |
+| `--agent` `<inline\|auto\|name>` | Who runs the model-bearing test work. | omit |
 | `--auto` | Skip objective HITL gates. | off |
 
 For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag-glossary.md).

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

@@ -1,5 +1,6 @@
 ---
 description: Verify a task against its requirements and Acceptance Criteria — traceability check producing a PASS/PARTIAL/FAIL verdict with evidence
+role: reviewer
 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"]
 ---
@@ -13,7 +14,7 @@ Wraps the **sp:code-verification** skill.
 | Flag | Description | Default |
 | --- | --- | --- |
 | `<wbs>` | Task WBS to verify. | required |
-| `--agent` `<inline\|auto\|name>` | Who runs the model-bearing verification. | inline |
+| `--agent` `<inline\|auto\|name>` | Who runs the model-bearing verification. | omit |
 | `--fix` `<none\|blockers-first\|all>` | Auto-fix policy on findings. | none |
 | `--focus` `<lens>` | Verification lens. | omitted |
 | `--bdd` | Run BDD scenarios. | off |

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

@@ -1,5 +1,6 @@
 ---
 description: Verify a batch of tasks against their requirements and Acceptance Criteria — batch traceability check producing per-task verdicts and a summary report
+role: reviewer
 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"]
 ---
@@ -14,7 +15,7 @@ Wraps the **sp:spur-dev** and **sp:code-verification** skills.
 | --- | --- | --- |
 | `--tasks` `<selector>` | Task selector to verify. | required |
 | `--feature` `<id>` | Restrict to a feature. | omitted |
-| `--agent` `<inline\|auto\|name>` | Who runs each verification. | inline |
+| `--agent` `<inline\|auto\|name>` | Who runs each verification. | omit |
 | `--fix` `<none\|blockers-first\|all>` | Auto-fix policy on findings. | none |
 | `--focus` `<lens>` | Verification lens. | omitted |
 | `--bdd` | Run BDD scenarios. | off |

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

@@ -1,5 +1,6 @@
 ---
 description: Wrap up a single completed task — learnings, metrics, doc-sync, optional feature transition and branch cleanup
+role: coder
 argument-hint: "<wbs> [--agent <inline|auto|name>] [--auto] [--merge] [--dry-run]"
 allowed-tools: ["Bash", "Read", "AskUserQuestion"]
 ---
@@ -13,7 +14,7 @@ Wraps the **wrapup-pipeline.yaml** workflow.
 | 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 |
+| `--agent` `<inline\|auto\|name>` | Who runs the wrap's model-bearing steps. Wrap is workflow-backed (headless): `omit` resolves to `agent.default` (objective trigger 3 — durable auditable run record required); explicit `--agent inline` is rejected with the stable special error — a headless workflow surface cannot host a session; `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 |
@@ -31,13 +32,13 @@ For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag
 - 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`).
+  - omit → resolve to `agent.default`; explicit `--agent inline` → rejected with the stable special error (headless surface — no dispatch, no `agent.default` fallback).
 - 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>`.
+  `execution surface: subprocess`, `reason: trigger 3 — durable auditable run record required`, `requested agent: inline|auto|<name>` (explicit `inline` rejects before dispatch — no executor resolves), `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>
+AGENT=… # resolved above: agent.default for omitted, tier-resolved for auto, unchanged for <name>; explicit inline errors (headless)
 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}')
@@ -45,4 +46,5 @@ 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`).
+the resolved name (`agent.default` for omitted `--agent`; explicit `--agent inline` is rejected
+before dispatch).

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

@@ -1,5 +1,6 @@
 ---
 description: Wrap up a batch of completed tasks — learnings, metrics, doc-sync, feature transition, optional branch cleanup
+role: coder
 argument-hint: "[--since <iso-date>] [--feature <id>] [--status <s>] [--agent <inline|auto|name>] [--auto] [--merge] [--dry-run]"
 allowed-tools: ["Bash", "Read", "AskUserQuestion"]
 ---
@@ -15,7 +16,7 @@ Wraps the **wrapup-pipeline.yaml** workflow.
 | `--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 |
+| `--agent` `<inline\|auto\|name>` | Who runs the wrap's model-bearing steps. Wrap is workflow-backed (headless): `omit` resolves to `agent.default` (objective trigger 3 — durable auditable run record required); explicit `--agent inline` is rejected with the stable special error — a headless workflow surface cannot host a session; `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 |
@@ -33,13 +34,13 @@ For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag
 - 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`).
+  - omit → resolve to `agent.default`; explicit `--agent inline` → rejected with the stable special error (headless surface — no dispatch, no `agent.default` fallback).
 - 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>`.
+  `execution surface: subprocess`, `reason: trigger 3 — durable auditable run record required`, `requested agent: inline|auto|<name>` (explicit `inline` rejects before dispatch — no executor resolves), `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>
+AGENT=… # resolved above: agent.default for omitted, tier-resolved for auto, unchanged for <name>; explicit inline errors (headless)
 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}')
@@ -47,5 +48,6 @@ 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`).
+the resolved name (`agent.default` for omitted `--agent`; explicit `--agent inline` is rejected
+before dispatch).
 

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

@@ -1,5 +1,6 @@
 ---
 description: Author a validated, smoke-tested constraint rule
+role: scribe
 argument-hint: "\"<description>\" [--file <path>] [--preset <target>]"
 allowed-tools: ["Bash", "Read", "Write", "Skill"]
 ---

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

@@ -1,5 +1,6 @@
 ---
 description: Refine a constraint rule or preset, then re-verify it
+role: scribe
 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"]
 ---

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

@@ -1,5 +1,6 @@
 ---
 description: Discover recurring anti-patterns worth codifying as rules
+role: reviewer
 argument-hint: "[<path-or-glob>]"
 allowed-tools: ["Bash", "Read", "Grep", "Glob", "Skill"]
 ---

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

@@ -1,5 +1,6 @@
 ---
 description: Initialize a new Spur project — scaffold config + docs, then customize for this project's stack and scope
+role: scribe
 argument-hint: "[--name <name>] [--minimal] [--force]"
 allowed-tools: ["Bash", "Read", "Write", "Skill"]
 ---

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

@@ -1,5 +1,6 @@
 ---
 description: Author a validated, dry-run-verified workflow in the right execution mode
+role: scribe
 argument-hint: "\"<description>\" [--kind <state-machine|transition-flow>] [--file <path>]"
 allowed-tools: ["Bash", "Read", "Write", "Skill"]
 ---

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

@@ -1,5 +1,6 @@
 ---
 description: Refine an existing workflow, then re-validate and re-dry-run it
+role: scribe
 argument-hint: "<workflow-file> [--intent \"<goal>\"] [--dry-run]"
 allowed-tools: ["Bash", "Read", "Edit", "Skill"]
 ---