@gobing-ai/spur 0.3.41 → 0.3.42

package/plugins/sp/skills/spur-cli/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: spur-cli
+description: "The CLI facade for the `spur` command surface - one reference per noun (task/feature/rule/workflow/agent/message/team/init/status/serve): verbs, flags, `--json` shapes, exit codes, the CLI-gated write contract. NOT for driving the lifecycle (that is the spine, sp:spur-dev). Triggers: \"spur task\", \"spur feature\", \"spur rule\", \"spur workflow\", \"spur agent\", \"spur message\", \"spur team\", \"spur status\", \"spur init\", \"spur serve\", \"create a task\", \"task check\", \"batch-create\", or looking up any spur CLI verb or convention."
+license: Apache-2.0
+metadata:
+  author: spur
+  version: "1.0"
+  platforms: "claude-code,codex,openclaw,opencode,antigravity"
+  interactions:
+    - reference
+    - companion
+  nouns:
+    - task
+    - feature
+    - rule
+    - workflow
+    - agent
+    - message
+    - team
+    - status
+    - init
+    - serve
+  openclaw:
+    emoji: "🧰"
+---
+
+# spur-cli — the CLI facade for the Spur command surface
+
+`spur-cli` is the single reference for operating the **`spur` command-line surface**. Each `spur`
+noun (`task`, `feature`, `rule`, `workflow`, `agent`, `message`, `team`, `init`, `status`, `serve`) has one reference file that documents *what each verb
+is, how to use it well, its flags, `--json` shapes, and exit codes*. This skill is a **facade /
+dispatch reference** — it tells you which verb does what and routes you to the noun's detail. It is
+**not** an orchestrator and contains **no competency logic**: the skill knows *how to invoke*; the
+CLI knows *what is valid*; the **spine** (`sp:spur-dev`) knows *how to drive the lifecycle*.
+
+## Noun routing
+
+Pick the noun, read its reference. Each Tier A and Tier B reference owns that noun's full verb catalog and conventions.
+
+| Tier | Noun | Operate | Reference |
+|------|------|---------|-----------|
+| **Tier A** | **task** | Task corpus: create (variants), `deps` mutation, canonical `sections` (`init`/`add`/`list`), status lifecycle, `record`/`verdict` artifacts, `run-link`, `check --json` matrix | [references/tasks.md](references/tasks.md) |
+| **Tier A** | **feature** | Feature tree: author with hierarchical IDs (DD-14), acceptance criteria (Gherkin), status lifecycle, move subtrees, `check --json` | [references/features.md](references/features.md) |
+| **Tier A** | **rule** | Constraint quality gate: run presets, author rules, fine-tune, validate rule files/presets, extend engine | [references/rules.md](references/rules.md) |
+| **Tier A** | **workflow** | Dual-mode workflow runtime: author state-machine / transition-flow workflows, validate, run, read traces | [references/workflows.md](references/workflows.md) |
+| **Tier B** | **agent** | Coding-agent execution surface: run prompts via detected/named agents, manage team agent specs, persistent self-draining loop, readiness check | [references/agent.md](references/agent.md) |
+| **Tier B** | **message** | Durable inter-agent messaging: send, inbox, reply, watch | [references/message.md](references/message.md) |
+| **Tier B** | **team** | Team coordination and supervision: assign, status, up/down rosters, start/stop supervised processes | [references/team.md](references/team.md) |
+| **Tier B** | **init** / **status** | Project scaffolding (`init`) + status overview; post-scaffold init validation probes & layout classification | [references/init.md](references/init.md) |
+| **Tier B** | **serve** | Local web server fallback: Task Kanban + team supervisor API | [references/serve.md](references/serve.md) |
+| **Tier C** | **history** / **migrate** / **projects** / **help** | Excluded while immature (see exclusion reasons below). Read `spur <noun> --help` as last resort | Last-resort `--help` |
+
+**Execute-First Contract:** Load `sp:spur-cli` references first to execute Tier A and Tier B commands directly without calling `spur --help`. Use `spur <noun> --help` only as a last resort for Tier C nouns, version skew, unlisted long-tail flags, or parity assertion failures.
+
+### Tier C exclusion reasons
+
+These nouns are intentionally undocumented - each has a concrete immaturity reason, not an oversight:
+
+| Noun | Reason |
+|------|--------|
+| `history` | `report` verb is a TODO stub (`spur history report` prints a marker); surface is still converging. |
+| `migrate` | Zero verbs - bare `spur migrate --json` runs schema migrations. No verb catalog to document. |
+| `projects` | Multi-project management surface (`add`/`remove`/`list`/`start`/`stop`); still evolving and not yet stable enough for a reference. |
+| `help` | Auto-generated by Commander.js; not a real noun. |
+
+Each noun's per-topic detail lives one level deeper under `references/<noun>/` (e.g.
+`references/tasks/verbs.md`, `references/tasks/section-editing.md`, `references/features/acceptance-criteria.md`,
+`references/rules/operations.md`, `references/workflows/authoring-workflows.md`).
+
+## When to use
+
+Use this skill to:
+
+- **Look up a `spur` verb** — what it does, its flags, its `--json` shape, its exit codes.
+- **Operate the corpus directly** — create/edit/list tasks and features, run a rule preset, validate
+  or run a workflow, from the command line.
+- **Author within a noun** — write a rule, author a workflow, write acceptance criteria — following
+  the noun reference's conventions.
+
+Do **not** use this skill for:
+
+- **Driving the planning→execution lifecycle** — intake → feature → decomposition → batch-create →
+  pipeline run is the spine, **`sp:spur-dev`**. This facade documents the verbs that spine dispatches.
+- **Gate-level constraint *design* across the catalog** — that lives in the `rule` reference's
+  authoring/fine-tuning topics, reached through this facade.
+
+## Convention — extending the facade
+
+Every `spur` noun is reachable here and nowhere else. **Adding a new noun adds exactly one reference
+file** (`references/<noun>.md`), plus an optional `references/<noun>/` subdir for its per-topic
+detail, plus one row in the Noun-routing table above. Do not create a separate `spur-<noun>` skill —
+the whole point of this facade is that the CLI surface has a single, scalable home.
+
+## What this skill is NOT
+
+- **Not the spine.** Driving a task through `task-pipeline.yaml`, HITL surfacing, decomposition, and
+  the planning loop is `sp:spur-dev` (the spine). This facade is the verb reference the
+  spine and the operator both consult.
+- **Not validation logic.** This skill says *run `check` / `validate`*; the rules those verbs enforce
+  live in the CLI (`task check`, `feature check`, `rule run`, `workflow validate`), never restated as
+  prose checks here.
+- **Not a competency.** Design, implementation, testing, and review are competency skills, not CLI
+  verbs — they are not documented here.
+
+## See also
+
+- **[references/agent.md](references/agent.md)** - coding-agent execution surface (`run`, `loop`,
+  spec management). Cross-references the
+  [dispatch-surface rule](../parallel-execution/references/dispatch-surface.md).
+- **[references/message.md](references/message.md)** - durable inter-agent messaging (`send`,
+  `inbox`, `reply`, `watch`).
+- **[references/team.md](references/team.md)** - team coordination and supervision (`assign`,
+  `status`, `up`/`down`, `start`/`stop`).
+- **[references/serve.md](references/serve.md)** - local web server fallback (Task Kanban + team
+  supervisor API).
+- **[references/init.md](references/init.md)** - `spur init` / `spur status` CLI verbs and
+  post-scaffold init validation (Phase 1.5/1.6 probes).
+- **`sp:spur-dev`** - the spine that dispatches these verbs into the planning +
+  execution lifecycle. Use it to *drive* work; use this facade to *look up or operate a verb*.
+- **`sp:expert-spur`** — the subagent that loads this facade for multi-step, multi-noun corpus work
+  in its own context window.
+
+## Platform Notes
+
+### Claude Code
+
+`spur` CLI via the Bash tool; every verb supports `--json` for machine consumption. Invoke this skill
+directly via `Skill(skill="sp:spur-cli", args="<noun> <verb> …")` to look up or operate a verb.
+
+### Codex / OpenClaw / OpenCode / Antigravity
+
+Run the `spur` CLI via the Bash tool and parse `--json` output. This facade is the SSOT for the verb
+surface; commands and subagents are thin wrappers over it.

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

@@ -0,0 +1,179 @@
+---
+name: spur-cli-agent
+description: "spur-cli noun reference: operate `spur agent` as the coding-agent execution surface - run prompts via detected or named agents, manage team agent specs, run the persistent self-draining loop, and check agent readiness. The concrete levers (--model, --agent) behind the dispatch-surface escalation rule."
+see_also:
+  - spur-cli
+---
+
+# spur agent - the coding-agent execution surface
+
+`spur agent` is the CLI for **running and inspecting coding agents**. It wraps the agents the
+operator already has installed (Claude Code, Codex, omp, OpenCode, Antigravity, etc.) behind a
+uniform `run` / `loop` / `spec` surface, so the rest of the harness can dispatch work without
+hard-coding a specific agent.
+
+This is a **companion reference**, not an orchestrator. It documents *what each verb is and how to
+use it well*. The decision of *when* to escalate from a native subagent to `spur agent run` is owned
+by the **[dispatch-surface rule](../../parallel-execution/references/dispatch-surface.md)** - read
+that before using `run` for fan-out dispatch.
+
+## Verb map
+
+| Verb | Purpose | Key flags |
+| ---- | ------- | --------- |
+| `run <prompt>` | Execute a prompt or slash command via a coding agent | `--agent <name>` `--model <name>` `--mode <mode>` `--continue` `--cwd <path>` `--drain` `--json` |
+| `loop` | Persistent self-draining inbox loop for a team member (supervisor-managed) | `--agent <id>` `--poll <ms>` |
+| `list` | List detected coding agents, or team agent specs with `--specs` | `--specs` `--json` |
+| `doctor [agent]` | Check agent readiness | `--json` |
+| `create <id>` | Write a team agent spec to `.spur/agents/<id>.yaml` | `--type` `--tags` `--model` `--autonomy` `--system-prompt` `--name` `--workspace` `--purpose` `--auto-start` `--no-identity-preamble` `--json` |
+| `edit <id>` | Open an agent spec in `$EDITOR`, or print its path | - |
+| `delete <id>` | Remove an agent spec | `--force` |
+
+All verbs accept `--json` for machine consumption. **Exit codes:** `0` success, `1` error, `2`
+invalid usage.
+
+## `run` - execute a prompt via a coding agent
+
+```bash
+spur agent run "Fix the login bug in src/auth/" --agent claude
+spur agent run "verify on o3" --agent codex --model o3
+spur agent run "/sp:dev-verify 0040" --agent omp --drain
+```
+
+`run` is the verb the **dispatch-surface rule** escalates to. It executes a prompt (or slash command)
+through a coding agent as an external process, producing a persisted run record under `.spur/run/`.
+
+### Flags
+
+| Flag | Purpose |
+|------|---------|
+| `--agent <name>` | Agent name or `auto`. Selects which installed coding agent executes the prompt. |
+| `--model <name>` | Agent model argument (e.g. `o3`, `sonnet`). Passed through to the agent's model flag. |
+| `--mode <mode>` | Agent output mode: `text` or `json`. |
+| `--continue` | Resume the previous agent session instead of starting fresh. |
+| `--cwd <path>` | Working directory for agent execution (default: current directory). |
+| `--drain` | Prepend pending inbox messages addressed to `--agent <id>` before the prompt. |
+| `--json` | Output machine-readable JSON where supported. |
+
+### Dispatch-surface cross-reference
+
+`--agent` and `--model` are the **concrete levers** behind dispatch-surface trigger 1 ("Different
+model or coding agent required"). When a step needs a model or coding agent the host session cannot
+provide, `spur agent run --agent <name> --model <name>` is the escalation path. See
+**[dispatch-surface.md](../../parallel-execution/references/dispatch-surface.md)** for the full
+trigger table and the naming requirement (state which trigger applied).
+
+**Default:** use the native subagent (`Skill()` / `Task()`) when the host platform provides one.
+`spur agent run` is the exception, not the default - it is justified only by one of the four
+observable triggers (different model/agent, headless step, durable audit record, workspace
+isolation).
+
+### Sandbox reliability note
+
+`spur agent run` spawns the target agent as an external process. Under a sandboxed Bash session it
+can fail when the external agent writes its own storage outside the sandbox's allowlist (e.g. omp's
+`AgentStorage` SQLite DB). This is not a reason to abandon `spur agent run` - triggers 1-4 still
+justify it - but ensure the run executes in a context that can write the target agent's storage.
+
+## `loop` - persistent self-draining wrapper
+
+```bash
+spur agent loop --agent worker-1 --poll 2000
+```
+
+`loop` is the **persistent self-draining wrapper** used by the team supervisor. It polls the
+addressed agent's inbox, drains each pending message into an `agent run` invocation, and idles
+between drains. It is not typically invoked directly by the operator - `spur team start` launches it
+under supervision.
+
+### Flags
+
+| Flag | Purpose |
+|------|---------|
+| `--agent <id>` | **Required.** Agent spec id / message recipient. |
+| `--poll <ms>` | Idle poll interval in milliseconds (default: `2000`). |
+
+The loop runs until `SIGINT` / `SIGTERM`. Each iteration: check inbox -> if messages, drain each
+into `run` with `--drain` -> else sleep for `--poll` ms.
+
+## `list` - detected agents and team specs
+
+```bash
+spur agent list              # detected coding agents on this machine
+spur agent list --specs      # team agent specs under .spur/agents/
+spur agent list --json       # machine-readable
+```
+
+Without `--specs`, lists coding agents detected on the host (by binary on `PATH`). With `--specs`,
+lists team agent specs (`.spur/agents/*.yaml`).
+
+## `doctor` - readiness check
+
+```bash
+spur agent doctor            # all detected agents
+spur agent doctor claude     # one agent
+spur agent doctor --json     # machine-readable
+```
+
+Checks whether each agent is installed and ready to run. Returns exit `1` if any checked agent is
+not ready.
+
+## `create` - author a team agent spec
+
+```bash
+spur agent create worker-1 --type claude --tags team:alpha --model sonnet
+spur agent create reviewer --type codex --autonomy review --auto-start
+```
+
+Writes a team agent spec to `.spur/agents/<id>.yaml`. The spec captures the agent's identity
+(type, model, autonomy, system prompt, tags) so `spur team up` can materialize a roster and `spur
+agent loop` can self-drain its inbox.
+
+### Flags
+
+| Flag | Purpose |
+|------|---------|
+| `--type <agent-type>` | Agent spec type (e.g. `claude`, `codex`, `omp`). |
+| `--tags <a,b>` | Comma-separated team identity tags (e.g. `team:alpha,role:worker`). |
+| `--model <name>` | Agent model argument. |
+| `--autonomy <level>` | Autonomy level (e.g. `full`, `review`). |
+| `--system-prompt <text>` | Team identity system prompt. |
+| `--name <name>` | Agent display name. |
+| `--workspace <path>` | Workspace path for this agent. |
+| `--purpose <text>` | Team identity purpose. |
+| `--auto-start` | Auto-start flag (start on `team up` without manual `team start`). |
+| `--no-identity-preamble` | Disable the identity preamble prepended to prompts. |
+| `--json` | Output machine-readable JSON. |
+
+## `edit` - open a spec in `$EDITOR`
+
+```bash
+spur agent edit worker-1
+```
+
+Opens `.spur/agents/<id>.yaml` in `$EDITOR`. If `$EDITOR` is unset, prints the spec path instead.
+
+## `delete` - remove a spec
+
+```bash
+spur agent delete worker-1 --force
+```
+
+`--force` is required (guards against accidental deletion). Removes `.spur/agents/<id>.yaml`.
+
+## What this skill is NOT
+
+- **Not the dispatch decision.** *When* to use `spur agent run` vs a native subagent is the
+  **[dispatch-surface rule](../../parallel-execution/references/dispatch-surface.md)**, not this
+  reference. This reference documents the verbs; that rule decides which surface carries a dispatch.
+- **Not the team orchestrator.** `spur team up` / `spur team start` drive the supervisor lifecycle;
+  `spur agent` provides the execution primitives they compose.
+
+## See also
+
+- **[dispatch-surface.md](../../parallel-execution/references/dispatch-surface.md)** - native
+  subagent vs `spur agent run` decision rule. `--model` and `--agent` are its escalation levers.
+- **`spur team` (see [team.md](team.md))** - team lifecycle that launches `agent loop` under
+  supervision.
+- **`spur message` (see [message.md](message.md))** - the inbox `--drain` reads from.
+- **`sp:spur-cli`** SKILL.md - the facade that routes to this reference.

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

@@ -0,0 +1,82 @@
+---
+name: feature-acceptance-criteria
+description: Gherkin template, R-numbering, @core/@edge tiers, and traceability mechanics for feature acceptance criteria.
+see_also:
+  - spur-cli
+---
+
+# Authoring acceptance criteria
+
+AC lives in a feature's `## Acceptance Criteria` section. It is the contract `spur feature check`
+validates (L3 syntax + L4 traceability) and the surface task decomposition maps against. Two
+formats are accepted.
+
+## Gherkin (the default)
+
+```gherkin
+Feature: Planning layer
+
+  @core
+  Scenario: R1 — User can create a task with required fields
+    Given a project with a tasks folder
+    When the user runs `spur task create "Add validation"`
+    Then a task file is written with a fresh WBS
+
+  @edge
+  Scenario: R2 — Task creation fails gracefully on a missing title
+    Given a project with a tasks folder
+    When the user runs `spur task create` with no title
+    Then the CLI exits non-zero with a clear message
+```
+
+## Checklist (lightweight alternative)
+
+For features that don't warrant full Gherkin, a checklist is accepted:
+
+```markdown
+- [ ] R1 — User can create a task with required fields
+- [ ] R2 — Task creation fails gracefully on a missing title
+```
+
+`check` validates whichever format is present. Prefer Gherkin once scenarios have concrete
+given-when-then values; a checklist is fine for early, coarse AC.
+
+## R-numbering
+
+Every scenario/item carries an `R1, R2, …` prefix:
+
+- **Sequential within a feature**, starting at R1.
+- **Stable forever.** Never renumber once tasks exist — tasks match AC by **normalized scenario
+  title** (the `R<n> —` prefix is stripped on comparison), so renumbering around a title is safe
+  but *rewording* a title breaks the coverage edge.
+- **One R-number = one scenario.** Don't split one requirement across scenarios under a single
+  R-number; don't merge two requirements into one scenario.
+
+## Two tiers — `@core` / `@edge`
+
+A planning convention (DD-06 "permissive start"), **not** a `check` gating feature today — the
+validator treats all scenarios uniformly (syntax + traceability). Tags exist so decomposition and
+future tiered gating can tell them apart:
+
+- **`@core`** — must ship; covers a committed `## Scope (in)` item; maps to ≥ 1 task in decomposition.
+- **`@edge`** — advisory error/boundary/degraded paths; may be deferred; need not map to a task
+  initially.
+
+Full rationale and the relationship to decomposition live in `sp:spur-dev`'s AC style guide — this
+reference is the *authoring* surface; that one is the *planning* surface.
+
+## Traceability mechanics (L4)
+
+`check`'s L4 layer reads two things:
+
+1. **Incoming edges** — tasks whose frontmatter `feature-id` points at this feature. Create tasks
+   with `spur task create … --feature <id>` so the edge exists.
+2. **Coverage** — which scenarios are claimed by a task (matched on normalized title).
+
+L4 flags:
+
+- **Orphan scenarios** — AC with no covering task (a gap in decomposition).
+- **Coverage orphans** — a task claims a scenario title that no longer exists (usually a reworded AC).
+- **`verifying` readiness** — moving a feature to `verifying` requires its core AC to be covered.
+
+Run `spur feature check <id> --json` before transitioning to `verifying` and clear these.

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

@@ -0,0 +1,177 @@
+---
+name: feature-hierarchy-mece
+description: >-
+  Explicit rules for creating new feature nodes or extending existing ones —
+  MECE roots, cautious root creation, reparent vs merge, depth limits.
+  Consumed by spur feature authoring, /sp:dev-plan, /sp:dev-idea, and
+  /sp:dev-featurechange.
+see_also:
+  - spur-cli
+  - feature-verbs
+  - feature-roadmap-priority
+  - product-planning
+---
+
+# Feature hierarchy: MECE roots and extension rules
+
+This is the **normative checklist** before `spur feature create` or any restructure
+(`/sp:dev-featurechange`, `spur feature move`). CLI enforces ID shape (DD-14) and
+≤9 children; **judgment** here keeps the tree neat for humans and agents.
+
+## Goals of a good tree
+
+| Goal | Meaning |
+| --- | --- |
+| **MECE at each sibling set** | Mutually Exclusive, Collectively Exhaustive *for the parent’s Goal* — siblings don’t overlap, and together they cover the parent without a “misc” catch-all as a peer of real capabilities. |
+| **Sparse roots** | Top-level letters (A, B, …) are **product capabilities or roadmap themes**, not every workstream. Prefer a child under an existing root over a new letter. |
+| **Stable IDs** | Never hand-edit IDs. Use `spur feature create --parent` and `spur feature move`. |
+| **Tasks hang on leaves (or near-leaves)** | Implementation work is `spur task` with `feature_id`; features stay *why / what-done-looks-like*. |
+
+---
+
+## Decision procedure: new work arrives
+
+Run **in order**. Stop at the first yes.
+
+```text
+1. Does an existing feature Goal already own this outcome?
+     YES → extend that node (Scope / AC / tasks). Do NOT create a sibling root.
+2. Is this a deliverable slice of an existing capability?
+     YES → spur feature create "…" --parent <existing-id>
+3. Is this a UX/API/schema slice of an existing board or module feature?
+     YES → child (or grandchild) of that feature — never a new root letter.
+4. Is this only a technical package/endpoint/folder rename?
+     YES → prose in Notes / Architecture docs — NOT a feature node.
+5. Is this a new product capability or roadmap theme with no home?
+     YES → new root (letter) — only after the root gate below passes.
+```
+
+**Default bias:** extend or reparent under an existing node. New roots are the exception.
+
+---
+
+## Root gate (new top-level letter)
+
+A new root is allowed only if **all** hold:
+
+1. **Capability, not project.** Names a durable product surface or theme (e.g. Planning, Rules), not a sprint slogan or one PR.
+2. **No parent fits.** No existing root’s Goal can absorb it without lying about Scope.
+3. **MECE with peers.** It does not restate an existing root under a synonym (e.g. “Agent execution” vs “Agent integration” need *distinct* Goals, not two roots for “agents”).
+4. **Expected children.** You can name ≥1 real child slice or a clear multi-release arc; one-off work is a **task** or a **child**, not a root.
+5. **Operator confirm** when unsure — prefer AskUserQuestion / decision brief over inventing a letter.
+
+If any check fails → **child of best parent** or **task under existing feature**.
+
+---
+
+## MECE rules (siblings under one parent)
+
+| Rule | Do | Don’t |
+| --- | --- | --- |
+| **Mutually exclusive** | Sibling Goals partition the parent; overlap goes to one sibling or a shared parent Note. | Two siblings that both “own” the same board tab, CLI noun, or event stream. |
+| **Collectively exhaustive** | Parent Scope is covered by children **or** parent-level AC/tasks when no further split is needed. | Parent with one child that is a full copy of the parent Goal. |
+| **Same grain** | Siblings at one level are comparable slices (all “CLI surfaces”, all “board modules”). | Mixing “foundation epic”, “one CSS tweak”, and “whole platform” as siblings. |
+| **No synonym roots** | One capability → one root; clarify with rename, not a second letter. | `Observability` + `Observabilities board` + `System Events redesign` as three roots. |
+| **Done children stay** | Keep `done`/`cancelled` nodes for history; don’t promote their UX polish to new roots. | Spawning a new root for “table redesign of X” when X already has a feature. |
+
+**Smell test:** If two root Goals can be true in the same sentence without “and also”, they may be the same capability.
+
+---
+
+## Extend vs create vs reparent vs merge
+
+| Move | When | How |
+| --- | --- | --- |
+| **Extend in place** | Scope/AC grows; same Goal | Edit sections; add tasks with `--feature <id>` |
+| **Create child** | New deliverable under clear parent | `spur feature create "…" --parent <id>` |
+| **Reparent / move** | Node lives under wrong parent; Goal still valid | `spur feature move <id> --parent <new>` (cascade rename) |
+| **Rename-only** | Goal OK; title misleading | Prefer `update --field name` if supported, or document + move only if ID depth must change |
+| **Merge (absorb)** | Two nodes share one Goal; bodies should be one | Prefer: move children under survivor → fold Scope/AC into survivor → cancel or archive source. **Not** a casual `move`. Use mapping + `/sp:dev-featurechange` when batching. |
+| **Archive** | Capability retired | `cancelled` or leave `done`; do not delete history |
+
+---
+
+## Depth and width limits
+
+| Constraint | Guidance |
+| --- | --- |
+| **DD-14** | Letter root; one digit per level; ≤9 children per parent (`feature check` L3). |
+| **Prefer depth ≤ 3** | Root → capability slice → delivery slice (e.g. `F` → `F8` → `F81`). Deeper only when each level has a distinct Goal. |
+| **Prefer width ≤ 7** at a level | If you need 8–9 siblings, split themes or introduce an intermediate group feature. |
+| **Group tags ≠ hierarchy** | `tags: [group]` marks a theme container; still use real parents for deliverables. Don’t invent roots only to “hold tags”. |
+
+---
+
+## Naming
+
+- **Root:** short capability noun/phrase (`Planning`, `Rules`, `History`).
+- **Child:** verb-able outcome under parent (`Feature management CLI`, `Task Kanban web parity`).
+- **Avoid:** implementation nouns alone (`packages/app`, `drizzle migration`) unless the product *is* that infrastructure.
+- **Avoid:** duplicate “agent / observability / plugin” stems across roots without a written boundary in each Goal.
+
+---
+
+## Positive and negative examples (Spur monorepo)
+
+| Pattern | Example | Verdict |
+| --- | --- | --- |
+| Board module + UX slice as child | `F8` Features board → `F81` detail action group | **Good** — same product surface, finer grain |
+| Restructure tooling under Feature CLI | `F3` Feature management CLI → `F31` restructure kit | **Good** — not a new root letter (was root `S`, moved) |
+| Runner vs plugin integration | `B` Agent execution (`spur agent`) vs `H` Agent integration (`plugins/sp`) | **Keep separate** — Goals at `B_agent-execution.md:14` vs `H_agent-integration.md:14`; **reject merge on “agent” alone** |
+| Observability UX as sibling roots | `J` board + `K` System Events table redesign + `L` payload enrichment | **Reparent K,L under J** — not body-merge; not peer roots (audit 0356) |
+| Plugin epics as new letters | `N` dev-next UX, `O` token architecture as roots beside `H` | **Reparent under H** — same plugin plane, finer grain |
+| Workflow observability as board root | `P` workflow run observability as peer of `D` Workflows | **Reparent under D** — object is `spur workflow run`, not board J |
+| Planning validation as root | `Q` AC-verifiable gates as peer of `F` Planning | **Reparent under F** |
+| Status feedback as root | `R` feature status loop as peer of `F` | **Reparent under F** (corpus status is planning) |
+| CLI backbone vs board product | `G` Collaboration (message/team CLI) vs `M` Teams board | **Keep both** — different surfaces; do not merge |
+| One-off polish as root | New letter for “fix button loading” | **Bad** — task under existing feature |
+| Done historical epic as root | `I` sp plugin hands-off ready (`done`) | **Keep** as historical root OK; optional later neatness under H |
+
+### Audit 0356 snapshot (A–R dispositions)
+
+Authoritative seed for restructure mapping lives in task 0356 Solution and
+`docs/plans/feature-tree-restructure-map.md` (when written). Summary:
+
+| Disposition | Roots |
+| --- | --- |
+| **keep** | A B C D E F G H I J M |
+| **reparent-under:J** | K L |
+| **reparent-under:H** | N O |
+| **reparent-under:D** | P |
+| **reparent-under:F** | Q (→F9; only free F digit) |
+| **reparent-under:F8** | R (→F82; F full at 8/9 children — cannot place both Q and R under F) |
+| **merge-into** | *(none)* |
+
+**Rejected merges:** B∪H (name-only overlap); J∪K body-merge (use reparent for K/L).
+
+---
+
+## Checklist: before `spur feature create`
+
+- [ ] Searched `spur feature list` / INDEX for an existing owner Goal.
+- [ ] Chose **parent id** (or passed root gate with operator confirm).
+- [ ] Sibling set stays MECE at that parent.
+- [ ] Name is capability/outcome, not a package path.
+- [ ] Will attach tasks with `--feature <new-id>` (or parent if intentionally epic-only).
+- [ ] After create: `spur feature refresh` if INDEX must update; `spur feature check <id>`.
+
+## Checklist: before restructure / `/sp:dev-featurechange`
+
+- [ ] Mapping file lists disposition per node (`keep` / `reparent-under` / `merge-into` / `rename-only` / `archive`).
+- [ ] False merges rejected (name overlap ≠ one Goal).
+- [ ] Apply via CLI (`spur feature move`, `spur task update --feature`), not raw ID edits.
+- [ ] Dry-run reviewed; doc rewrites limited to agreed surface (e.g. root `docs/*.md`).
+- [ ] `spur feature refresh` + `spur feature check` after apply.
+
+---
+
+## Where this is enforced
+
+| Layer | Role |
+| --- | --- |
+| **This reference** | Agent/human judgment — MECE, root gate, merge vs reparent |
+| **`spur feature create/move/check`** | Deterministic DD-14, children limit, lifecycle |
+| **`/sp:dev-plan` / `/sp:dev-idea`** | Must run the decision procedure before allocate |
+| **`/sp:dev-featurechange`** | Batch restructure against a mapping; must not invent roots |
+
+Agents authoring features **must load this file** (via `sp:spur-cli` features references) before creating a root or proposing merges.

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

@@ -0,0 +1,84 @@
+---
+name: feature-roadmap-priority
+description: Roadmap hierarchy, priority/status conventions, and feature-tree adjustment guidance for spur feature.
+see_also:
+  - spur-cli
+  - feature-verbs
+  - product-planning
+---
+
+# Roadmap, Priority, And Status
+
+`spur feature` is the feature-tree surface for roadmap structure. Use it to represent capability
+hierarchy, lifecycle state, and priority. Keep PM scoring as prose or frontmatter scalar fields
+until a deterministic schema is introduced.
+
+## Hierarchy
+
+Feature hierarchy should be user-facing first:
+
+- Top-level features are product capabilities or roadmap themes.
+- Children are deliverable slices under that capability.
+- Technical modules, package names, and endpoints belong in prose or notes, not as the primary tree
+  shape unless the product itself is developer-facing infrastructure.
+
+**Normative create/extend rules (MECE, root gate, merge vs reparent):** see
+[hierarchy-mece.md](hierarchy-mece.md). Load that file before `spur feature create` of a new root or
+any bulk restructure. This section only states the product-facing intent; hierarchy-mece is the
+checklist.
+
+Use `spur feature move <id> --parent <id>` to restructure. Never hand-edit IDs; `move` cascade-renames
+descendants and preserves the tree invariant.
+
+## Priority
+
+Use the existing scalar field path for priority:
+
+```bash
+spur feature update <id> --field priority --value P1
+```
+
+Recommended meaning:
+
+| Priority | Meaning |
+| --- | --- |
+| `P0` | Stop-the-line; current release or production health depends on it. |
+| `P1` | High-value committed work. |
+| `P2` | Important backlog item; sequence after committed work. |
+| `P3` | Opportunistic or exploratory. |
+
+When prioritizing many candidates, use the RICE or MoSCoW guidance from `sp:spur-dev`'s product
+planning reference, then write only the chosen scalar priority/status through `spur feature update`.
+Keep the scoring rationale in the feature body or linked planning notes; do not invent hidden
+metadata fields.
+
+## Status
+
+Feature statuses are lifecycle states, not priority buckets:
+
+| Status | Use for |
+| --- | --- |
+| `backlog` | Accepted idea, not actively being built. |
+| `active` | Current work target; `check` enforces one active goal. |
+| `verifying` | Implementation is believed complete and AC traceability is being checked. |
+| `blocked` | Progress stopped by an explicit dependency or decision. |
+| `done` | Acceptance criteria are satisfied and verified. |
+| `cancelled` | Explicitly cut; keep the record for traceability. |
+
+Move status with `spur feature update <id> <status>` and let the lifecycle engine reject illegal
+transitions.
+
+## Roadmap Adjustments
+
+For roadmap adjustment work:
+
+1. List the candidate scope with `spur feature list --json` or a specific subtree with
+   `spur feature show <id> --json`.
+2. Apply the product-planning prioritization rubric in-session.
+3. Present the proposed moves/status/priority changes before mutating if the blast radius spans
+   multiple features.
+4. Apply each accepted deterministic change through `spur feature update` or `spur feature move`.
+5. Run `spur feature refresh` and `spur feature check --json`.
+
+Do not add `/sp:prd-adjust` for this. The current CLI already has the deterministic primitives; the
+PM value is the ranking and tradeoff judgment.