@gobing-ai/spur 0.3.40 → 0.3.42

package/plugins/sp/skills/spur-dev/references/product-planning.md

@@ -0,0 +1,206 @@
+---
+name: product-planning
+description: Product-management judgment for the sp planning path: intake, prioritization, strategy profiles, PRD-shaped output, and handoff rules without adding a PM command surface.
+see_also:
+  - spur-dev
+  - planning-workflow
+  - decomposition
+  - spur-cli
+  - doc-evolve
+---
+
+# Product Planning Guidance
+
+This reference captures product-management judgment for the Spur planning path without adding old
+feature-tree, PRD command, or PM-agent surfaces. `sp:spur-dev` remains the planning orchestrator.
+Product planning is a lens applied during intake, feature authoring, prioritization, decomposition,
+and doc handoff; deterministic writes still go through `spur feature`, `spur task`,
+`spur workflow`, and `sp:doc-evolve`.
+
+## Routing Rule
+
+Use this reference when the request is PM-shaped:
+
+- prioritizing a backlog or roadmap,
+- turning a vague idea into a feature with measurable outcomes,
+- deciding whether to create a feature, task, or doc update,
+- choosing a decomposition strategy (`simplify`, `mvp`, `standard`, `mature`),
+- producing PRD-shaped thinking without creating a PRD command family.
+
+Do not create a standalone `sp:product-management` skill, `sp:super-pm` agent, or `/sp:prd-*`
+command for this workflow unless a later task proves a stable, distinct routing value.
+
+## Intake Questions
+
+Ask only for missing information. A senior, specific request can proceed directly to feature
+creation.
+
+| Dimension | Question |
+| --- | --- |
+| Outcome | What user or business result changes if this ships? |
+| User | Which persona, workflow, or operator role benefits first? |
+| Scope | What is explicitly in and out for this iteration? |
+| Success | Which observable metric, behavior, or acceptance signal proves it worked? |
+| Constraints | What timeline, risk, compliance, migration, or compatibility limits shape the plan? |
+| Opportunity cost | What current or planned work should lose priority if this wins? |
+
+Expertise calibration:
+
+- **Sparse idea:** ask foundational outcome/scope/success questions.
+- **Problem + rough scope:** ask boundary, metric, and dependency questions.
+- **Problem + personas + metrics:** ask tradeoff and opportunity-cost questions; do not over-elicit.
+
+## Elicitation Question Taxonomy
+
+Four dimensions frame every elicitation. Ask only what is missing — a senior, specific request may
+answer all four in its first sentence and proceed directly to feature creation. This taxonomy
+deepens the intake table above with the question *form* and the expertise-adaptive depth rule.
+
+| Dimension | Core question | What "answered" looks like |
+| --- | --- | --- |
+| Purpose | What user or business result changes if this ships? | A named outcome the operator will observe. |
+| Scope | What is explicitly in and out for this iteration? | A boundary testable against proposed tasks. |
+| Constraints | What timeline, risk, compliance, migration, or compatibility limits shape the plan? | A list of non-negotiables the plan must respect. |
+| Success criteria | Which observable metric, behavior, or acceptance signal proves it worked? | A signal encodable as an acceptance scenario. |
+
+### Expertise-adaptive questioning
+
+Calibrate depth to the input. Over-elicit and you waste the operator's time; under-elicit and you
+ship ambiguity into the corpus.
+
+| Input shape | Ask |
+| --- | --- |
+| Sparse idea (one sentence, no scope) | Purpose + Scope + Success — foundational framing only. |
+| Problem + rough scope | Constraints + Success — boundary and metric. |
+| Problem + personas + metrics | Opportunity cost + Constraints — tradeoff surface only. Do not re-elicit what is already stated. |
+| Senior, fully-specified request | Nothing. Proceed to `spur feature create`. |
+
+### Question form
+
+One question at a time, always with a recommended default. Never ask "what are your constraints?"
+open-ended; offer "I see X and Y as the likely constraints — am I missing one?" The recommendation
+trains the elicitation; the operator's override trains future elicitation.
+
+## Prioritization
+
+Use prioritization to decide ordering, not to replace operator judgment.
+
+### RICE
+
+Use RICE when comparing multiple candidates with enough estimates to rank them.
+
+```
+score = (reach * impact * confidence) / effort
+```
+
+| Field | Guidance |
+| --- | --- |
+| Reach | A count over a defined period, e.g. users/quarter or runs/month. |
+| Impact | `3` massive, `2` high, `1` medium, `0.5` low, `0.25` minimal. |
+| Confidence | `1.0` high, `0.8` medium, `0.5` low. Penalize guesses. |
+| Effort | Person-months or equivalent relative effort; keep the unit consistent. |
+
+Flag outliers: if one score is more than 10x the median, review the inputs before using the rank.
+
+### MoSCoW
+
+Use MoSCoW when shaping a release boundary.
+
+| Bucket | Meaning |
+| --- | --- |
+| Must | Release fails without it; critical path or blocking dependency. |
+| Should | Important and high-value, but can slip one release. |
+| Could | Useful if capacity remains. |
+| Won't | Explicitly out of scope for this release; document for future. |
+
+The Must set should be sufficient to satisfy the release goal. If it is not, the release goal or the
+bucket assignment is wrong.
+
+## Strategy Profiles
+
+Strategy profiles tune planning ceremony and decomposition scope. They are judgment aids, not new
+CLI flags unless a command explicitly supports them.
+
+| Profile | Use when | Scope | Tests/docs expectation |
+| --- | --- | --- | --- |
+| `simplify` | Low-risk request, operator wants speed, or a tiny workflow change. | Minimum useful deliverable; skip non-blocking edge cases. | Smoke/manual evidence and concise task prose. |
+| `mvp` | Need to validate demand or unblock learning quickly. | Core happy path; defer nice-to-haves. | Basic automated happy-path checks where cheap. |
+| `standard` | Normal validated work. | Balanced core + known edge cases. | Unit/integration coverage and normal docs. |
+| `mature` | Production-critical, regulated, security-sensitive, or high-reliability work. | Complete path including migration, failure modes, observability, and rollback. | Unit + integration + e2e/perf/security evidence as relevant. |
+
+Auto-selection heuristics:
+
+- Sparse request + explicit speed/minimal ceremony -> `simplify`.
+- Uncertain demand or missing success metric -> `mvp`.
+- Clear problem, scope, and acceptance signals -> `standard`.
+- Compliance, money movement, data loss, auth, migration, or reliability keywords -> `mature`.
+
+## Decomposition Decision Rules
+
+Each strategy profile implies a decomposition shape. Use these rules when the `sp:spec-decomposition`
+competency produces the task batch — the profile constrains granularity, edge-case coverage, and
+the acceptable task count.
+
+| Profile | Granularity | Edge cases | Target task count | Template variant |
+| --- | --- | --- | --- | --- |
+| `simplify` | One task if possible; split only when a single change spans two unrelated files. | Skip non-blocking. | 1-2 | `feature-impl` or `issue` |
+| `mvp` | Core happy path as one task; split only when a separate concern blocks the happy path. | Defer to a follow-up task noted in `## Background`. | 1-3 | `feature-impl` |
+| `standard` | One task per cohesive unit of work (a feature slice, a module, a cross-cutting change). | Include known edge cases in the same task or a sibling task. | 3-8 | `feature-impl` (mix with `review`/`meta` as needed) |
+| `mature` | One task per failure mode, migration step, rollback path, and observability surface — in addition to the core. | All failure modes, migration, rollback, and observability are first-class tasks, not afterthoughts. | 6-15 | `feature-impl` + `review` + `meta` mix |
+
+### Decision order
+
+1. Pick the profile (auto-select heuristics above, or operator override).
+2. Apply the granularity rule to each cohesive unit.
+3. Apply the edge-case rule to decide what stays in-task vs. splits out.
+4. Sanity-check the target count — if you are 2x over, the profile is wrong or the scope is two features.
+
+### When to split a feature
+
+If decomposition produces more than ~12 tasks under `mature` or ~8 under `standard`, the feature is
+probably two features. Split along the natural seam (subsystem, release boundary, team ownership)
+and create a second `spur feature create`. A single feature with 20 tasks is a decomposition smell,
+not a plan.
+
+## Feature, Task, Or Doc
+
+Choose the smallest durable artifact that preserves traceability.
+
+| Need | Artifact |
+| --- | --- |
+| New user-facing capability, roadmap item, or acceptance criteria surface | `spur feature create` |
+| Concrete implementation work with a bounded code change | `spur task create` or `spur task batch-create` |
+| Existing canonical docs drift or a PRD-style decision record | `sp:doc-evolve` |
+| Repeatable, stable multi-step PM process | `spur workflow` YAML, only after the steps stabilize |
+
+Default to one feature and one task until the decomposition rubric proves a split. A PRD-shaped
+document is useful for stakeholder alignment, scope negotiation, or cross-team handoff; it is not a
+reason to add `/sp:prd-doc`.
+
+## PRD-Shaped Output
+
+When the operator asks for a PRD, product brief, or requirements doc, produce the needed shape in the
+current planning artifact or route to `sp:doc-evolve` for canonical docs. Use the template size that
+matches the decision:
+
+| Shape | Sections | Use when |
+| --- | --- | --- |
+| Brief | Problem, users, success, scope, next decision | Exploration or a one-week spike. |
+| One-page PRD | Problem, solution, scope, success metrics | Simple feature, one team, two to four weeks. |
+| Standard PRD | Problem, goals, users, scope in/out, AC, metrics, risks, rollout, open questions | Complex feature, multiple stakeholders, or six-plus weeks. |
+
+Always include an Out of Scope section when the output is PRD-shaped. That is the part that prevents
+scope creep.
+
+## Handoff Rules
+
+- Feature writes: use `spur feature create`, `spur feature update`, and direct feature-body edits
+  followed by `spur feature check`.
+- Task writes: use `spur task create`, `spur task batch-create`, or
+  `spur task update --section --from-file`.
+- Documentation synchronization: invoke `sp:doc-evolve` and follow the constitution.
+- Repeatable orchestration: author `spur workflow` YAML only when the process has become mechanical
+  enough to validate and rerun.
+
+Rejected surfaces for now: `sp:super-pm`, `/sp:prd-run`, `/sp:prd-doc`, `/sp:prd-adjust`,
+`/sp:prd-init`, and a standalone `sp:product-management` skill.

package/plugins/sp/skills/spur-dev/references/section-batching.md

@@ -0,0 +1,24 @@
+---
+name: section-batching
+description: Stage pipeline task sections together, apply them through Spur, and validate once per coherent batch.
+see_also:
+  - spur-dev
+  - spur-cli
+---
+
+# Section batching protocol
+
+Use this protocol when an in-session operation must author multiple pipeline sections. A workflow
+`record` step should still prefer `spur task record` for verdict-derived `Testing` and `Review`.
+
+1. Read `spur-cli/references/tasks/l3-guard-cheatsheet.md`.
+2. Run `spur task sections <wbs> list --json` to learn which sections the current matrix permits.
+3. Stage complete, body-only `Solution`, `Testing`, and `Review` files before the first task check.
+4. Run `spur task check <wbs> --json` once, then apply every permitted staged section with
+   `spur task update <wbs> --section <name> --from-file <path>`.
+5. Run `spur task check <wbs> --json` once after the coherent write batch.
+6. If the post-write check fails, group all findings by section, repair all affected staged bodies, re-apply them, and
+   check once more.
+
+Budget: no more than two section writes per section and two task checks per task unless a new
+external failure changes the evidence. Do not use a write→check loop for each section.

package/plugins/sp/skills/sys-architecture/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: sys-architecture
+description: "The architecture competency — decide and record system design before code: module boundaries, data flow, build-vs-extend, transport/storage/auth tradeoffs, ADR routing. Triggers: \"what's the right approach\", \"design this\", \"architecture\", \"should this be an ADR\", \"module boundary\", \"build vs extend\"."
+license: Apache-2.0
+metadata:
+  author: spur
+  version: "1.0"
+  platforms: "claude-code,codex,openclaw,opencode,antigravity"
+  interactions:
+    - technique
+  competency: architecture
+  operations:
+    - survey
+  openclaw:
+    emoji: "📐"
+---
+
+# sys-architecture — the architecture competency
+
+Decide and record the *shape* of a change before it is implemented: where boundaries go, how data
+flows, what to build vs. extend, and which cross-cutting choices warrant a recorded decision. This is
+a deep competency the spine (`sp:spur-dev`) consults when a task's design is unsettled —
+it owns *deciding the shape*, distinct from `sp:code-implementation` which *builds the decided shape*.
+
+The split mirrors the project's own doc map: this skill produces **decisions with one-line reasons**
+(which belong in `docs/00_ADR.md`) and **mechanism/rationale** (which belongs in
+`docs/03_ARCHITECTURE.md`); it does not write feature code.
+
+## When to use
+
+- **Choose an approach** — two or three viable designs exist; pick one with an explicit tradeoff.
+- **Place a boundary** — decide which module/seam/package owns a responsibility.
+- **Build vs. extend** — decide whether to add to an existing seam or introduce a new one.
+- **ADR judgment** — decide whether a choice is cross-cutting enough to need a recorded ADR entry,
+  and draft it.
+- **Pre-implementation design** — fill a task's `## Design` section with the decided shape so
+  `sp:code-implementation` can execute it.
+
+Do **not** use this skill for:
+
+- **Writing the code** — that is `sp:code-implementation`.
+- **Coverage / testing** — that is `sp:code-testing`.
+- **Review of already-written code** — that is `sp:code-verification`.
+- **Driving the lifecycle / decomposition** — that is the spine, `sp:spur-dev`.
+
+## Behavior
+
+This skill behaves as a **technique**: given a problem and the codebase, it surfaces 2–3 candidate
+designs, weighs them on the dimensions that matter (coupling, blast radius, scalability, cost,
+reversibility), recommends one with a one-line reason, and routes the result:
+
+- A **cross-cutting decision** (new app/package, transport swap, auth boundary, storage swap, a new
+  shared convention) → a dated **ADR** entry in `docs/00_ADR.md`, with mechanism detail in
+  `docs/03_ARCHITECTURE.md`.
+- A **task-local design** → the task's `## Design` section (written via `spur task update`).
+
+Full procedure: **[references/decision-method.md](references/decision-method.md)** — candidate
+generation, the tradeoff dimensions, the deep-module vocabulary (module/interface/depth/seam/adapter/
+leverage/locality, the deletion test, design-it-twice), and the ADR-or-not gate.
+
+## The ADR-or-not gate
+
+Record an ADR when the choice is **cross-cutting and hard to reverse**: it changes a module boundary,
+introduces or swaps a dependency/transport/store, alters an auth surface, or sets a convention other
+code must follow. A task-local, easily-reversed choice stays in the task's `## Design`. When in
+doubt, prefer recording — a cheap ADR entry beats an undocumented divergence (the project conflict
+rule forbids diverging from an unrecorded decision).
+
+## Survey operation — architecture upkeep
+
+A standing **upkeep audit**, distinct from the per-decision design flow above: scan the whole
+codebase (or a named module tree) for **shallow modules and deepening opportunities**, and surface
+them as candidates for the planning half. This is a *generator*, not a fixer — it never refactors;
+it produces a ranked candidate report an operator can turn into a task.
+
+**Not `/sp:dev-review`.** `/sp:dev-review` is a per-task DIFF review (a WBS, forward, findings written
+to the task's `## Review`, backed by `sp:code-verification`). The survey has no WBS and no diff — it
+audits the standing codebase and feeds the planning half. Folding it into `dev-review` would overload
+that verb and pollute `code-verification` with a codebase scanner; it earns its own operation here.
+
+**Method (reuse, do not restate).** The survey applies the deep-module vocabulary already defined in
+[references/decision-method.md](references/decision-method.md) — module / interface / depth / seam /
+adapter / leverage / locality, and the **deletion test** — to flag shallow modules, pass-through
+wrappers, and leaky seams. The full procedure and the MARKDOWN candidate-report template live in
+[references/upkeep-survey.md](references/upkeep-survey.md).
+
+**Output: a MARKDOWN candidate report, never HTML.** Each candidate names the files, the problem
+(which depth/seam smell), the proposed deepening, a before/after in prose, and a recommendation
+strength — as markdown an operator can read and paste, never a rendered HTML report.
+
+**Route: candidate → grilling-to-design.** The operator picks a candidate; it enters the existing
+grilling-to-design flow (the planning half — `/sp:dev-idea` / `/sp:dev-plan`) as a generated idea,
+where it is stress-tested and shaped into a task. The survey stops at surfacing candidates; it never
+auto-refactors — upkeep framing, not a refactor bot.
+
+## Arguments
+
+When invoked via `/sp:dev-arch`, the command forwards `survey $ARGUMENTS` to this skill:
+
+| Argument | Description | Default |
+|----------|-------------|---------|
+| `[<module-path>]` | Module path to scope the architecture survey. | omitted (whole repo) |
+| `--scope <all\|path>` | Limit the survey to a path or expand to the whole repo. | all |
+| `--json` | Emit structured JSON instead of the MARKDOWN candidate report. | off |
+
+`--agent <inline|auto|name>` is consumed by the `dev-arch` wrapper (execution-surface selection) and is not forwarded as a survey argument.
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "One option is obviously right — no need to compare." | Evaluating a single option is rationalization, not a decision. Weigh at least two; the second reveals the first's cost. |
+| "Add a layer now for future flexibility." | A layer with one implementation is a shallow module that adds indirection, not depth. Add the seam when a second case is real. |
+| "We'll refactor the shortcut later." | "Later" rarely comes; the shortcut becomes load-bearing. Decide the boundary now, or record the debt explicitly. |
+| "This decision is small — skip the ADR." | Cross-cutting choices (a new package, a transport swap, an auth boundary) are exactly what the ADR captures. Small-looking seams calcify. |
+| "More abstraction is more robust." | Depth is interface-simplicity over capability, not layer count. The deletion test: if removing the module simplifies the system, it was shallow. |
+
+## Red Flags
+
+- A design presented with exactly one option and no alternative considered.
+- A new module/layer whose interface is as complex as what it wraps (a pass-through).
+- A cross-cutting decision made with no ADR entry and no recorded reason.
+- Abstraction justified only by hypothetical future requirements.
+- A boundary that fails the deletion test — the system is simpler without it.
+
+## Gotchas
+
+1. **Decide, then hand off.** This skill ends at a recorded decision + a filled `## Design`; the
+   spine dispatches `sp:code-implementation` to build it. Do not write feature code here.
+2. **One-line reason is mandatory.** A decision without its reason is not a decision — `docs/00_ADR.md`
+   exists precisely to carry the *why*.
+3. **Prefer extending a seam over adding one.** A new boundary is justified only when it removes real
+   complexity or gives a second concrete caller/adapter.
+4. **Route to the owning doc.** Decision + reason → `00`; mechanism/rationale in depth → `03`;
+   command/config/schema shapes → `04`. Do not restate a fact across docs.
+
+## See also
+
+- **`sp:spur-dev`** — the spine that consults this competency when a task's design is unsettled.
+- **`sp:code-implementation`** — builds the shape this skill decides.
+- **`docs/00_ADR.md` / `docs/03_ARCHITECTURE.md`** — the homes for the decisions and rationale this
+  skill produces.
+
+## Platform Notes
+
+### Claude Code
+
+Invoke directly via `Skill(skill="sp:sys-architecture", args="<question>")`, or as the design step of
+planning. Use the `spur` CLI via the Bash tool to write a task's `## Design`; edit `docs/00_ADR.md`
+directly for ADR entries.
+
+### Codex / OpenClaw / OpenCode / Antigravity
+
+Invoke this skill directly for design judgment; write decisions to the owning docs and task sections.
+The skill is the SSOT for the method; the result lives in the docs it routes to.

package/plugins/sp/skills/sys-architecture/references/decision-method.md

@@ -0,0 +1,137 @@
+---
+name: decision-method
+description: "The architecture decision method for sp:sys-architecture — candidate generation, the tradeoff dimensions, the deep-vs-shallow-module test, and the ADR-or-not gate. Produces a recorded decision with a one-line reason, routed to the owning doc."
+see_also:
+  - sys-architecture
+---
+
+# Architecture Decision Method
+
+The procedure `sp:sys-architecture` runs to turn a design question into a recorded decision. The
+output is always **a chosen option + a one-line reason**, routed to its owning doc.
+
+## 1. Frame the decision
+
+State, in one sentence, what is being decided. If you cannot state it in one sentence, the decision
+is actually several — split them and decide in dependency order. Read the codebase first: many
+"decisions" are already constrained by an existing pattern, dependency, or convention. If the answer
+is in the code, state it and stop — do not manufacture options for a settled question.
+
+## 2. Generate 2–3 candidates
+
+Never evaluate a single option (that is rationalization, not a decision) and rarely more than three
+(analysis paralysis). For each candidate, name what it commits to and what it defers. Bias toward
+options that *extend an existing seam* over options that *introduce a new one*.
+
+## 3. Weigh on the dimensions that matter
+
+Score the candidates on the axes relevant to this decision — not all apply every time:
+
+| Dimension | The question |
+|-----------|--------------|
+| **Coupling** | What does this bind together that was independent? Can the two sides still evolve apart? |
+| **Blast radius** | If this is wrong, how much has to change to undo it? |
+| **Reversibility** | Is this a one-way door (hard to reverse) or a two-way door (cheap to revisit)? |
+| **Scalability** | Does it hold at the next order of magnitude of load/size/teams, or is there a known cliff? |
+| **Cost** | Build/run/maintain cost — including the cost of a new dependency or runtime. |
+| **Conformance** | Does it match the codebase's existing conventions, or fork them? |
+
+A one-way door with a large blast radius deserves more deliberation and almost always an ADR; a
+two-way door can be decided fast and revisited.
+
+## 4. Apply the deep-module vocabulary
+
+Prefer a design whose modules are **deep**: a narrow interface hiding substantial capability, reused
+by callers that do not need to know its internals. Be suspicious of **shallow** modules — thin
+wrappers with a wide interface, or boundaries drawn along *temporal phases* ("a step-1 module and a
+step-2 module") rather than *capabilities*. A boundary that two callers almost always cross together
+is the wrong boundary; relocate or remove it.
+
+Use these seven terms precisely — each has near-synonyms this method deliberately avoids, because a
+vaguer word lets an under-designed boundary pass without scrutiny:
+
+| Term | Meaning | Avoid |
+|------|---------|-------|
+| **Module** | A unit of functionality with one owner and one reason to change. | "piece", "part", "chunk" |
+| **Interface** | The surface callers depend on — signatures, types, contracts. Not the implementation. | "API" (too transport-coded), "surface area" |
+| **Depth** | Capability hidden ÷ interface size. A deep module does a lot behind a little. | "complexity" (depth is the *ratio*, not raw complexity) |
+| **Seam** | A place the design can vary without the caller knowing — the proven joint an adapter sits on. | "layer", "boundary" (see Rejected framings) |
+| **Adapter** | A concrete implementation behind a seam. One adapter alone does not prove the seam is real. | "wrapper", "shim" |
+| **Leverage** | What a module buys its callers — the work it removes from every call site. | "value", "benefit" |
+| **Locality** | How much of a change stays inside one module vs. spilling across many. | "cohesion" (locality is about *change*, not static grouping) |
+
+**The deletion test:** for any proposed module or seam, ask "if I deleted this and inlined its one
+caller, would anything get harder?" If no caller would notice, the boundary is not pulling its
+weight — either it hides no real complexity, or it has exactly one caller and no second use in
+sight. Deletion-test failures are the most common shallow-module smell.
+
+**One adapter = hypothetical seam, two = real.** A seam justified by "we might swap this later" is
+speculative until a second adapter actually exists. Building a seam for a hypothetical second
+implementation is premature abstraction (R2); building it when the second implementation is already
+needed is a real seam. When in doubt, inline the single adapter and extract the seam when the second
+caller arrives — extraction is cheap, premature generality is not.
+
+**The interface is the test surface.** A deep module's tests exercise the interface, not the
+internals — if a test needs to reach past the interface to assert something, either the interface
+is missing a capability it should expose, or the test is coupling to implementation detail that
+will make refactors expensive. This is also the fastest depth check available: an interface you
+can test completely from outside is doing its job.
+
+### Rejected framings
+
+These near-synonym terms are deliberately **not** used in this method, to keep the vocabulary above
+unambiguous:
+
+| Term | Why rejected |
+|------|--------------|
+| **Component** | Overloaded across UI frameworks and infra tooling — does not distinguish depth from size. |
+| **Service** | Implies a network/process boundary; conflates *module* (a code-level unit) with *deployment* (an infra-level unit). A module is not always a service and a service is not always one module. |
+| **Boundary** | Too generic — used for module edges, security perimeters, and transaction scopes alike. This method uses **seam** for the specific "place the design can vary" meaning. |
+
+### Design-it-twice (for a genuinely unsettled interface)
+
+When the interface shape itself is the open question — not just which of two known options to
+pick, but what the right shape even is — fan out 2–3 radically different interface designs in
+parallel via `sp:parallel-execution` (independent subagents, one design each, same problem
+statement) rather than iterating on one design serially. Compare the results on **depth**,
+**locality**, and **seam placement** — the three axes above that a single linear design pass tends
+to anchor on its first idea instead of exploring. Use this only when the interface is the crux of
+the decision; for a settled interface with a build-vs-extend question, steps 1–3 above are enough.
+
+## 5. Recommend one, with the one-line reason
+
+Pick the candidate that best fits the weighed dimensions and state the single sentence that justifies
+it over the runner-up. The reason is the deliverable — a decision without its reason cannot be
+maintained or revisited honestly.
+
+## 6. The ADR-or-not gate
+
+Record a dated **ADR** entry in `docs/00_ADR.md` when the decision is **cross-cutting and hard to
+reverse** — any of:
+
+- introduces, swaps, or removes a dependency, transport, runtime, or data store;
+- changes a module/package boundary or an auth surface;
+- sets a convention other code must follow;
+- supersedes or diverges from a prior recorded decision.
+
+Otherwise the decision is **task-local**: write it to the task's `## Design` section via
+`spur task update <wbs> --section Design --from-file <tmp>`. When uncertain, prefer recording — a
+cheap ADR entry beats an undocumented divergence, and the project conflict rule forbids diverging
+from a decision that was never recorded.
+
+## 7. Route to the owning doc (do not restate)
+
+| Output | Home |
+|--------|------|
+| The decision + its one-line reason | `docs/00_ADR.md` (cross-cutting) or the task's `## Design` (task-local) |
+| Mechanism, data flow, invariants, rationale in depth | `docs/03_ARCHITECTURE.md` |
+| Concrete command / flag / config / schema shapes | `docs/04_DESIGN.md` |
+
+A fact lives in exactly one doc; the others link to it. If you find yourself writing *how it's built*
+or *why* inside `00`, it belongs in `03` — move it and link.
+
+## Handoff
+
+The decision is complete when: one option is chosen with a one-line reason, it is recorded in its
+owning doc (ADR or task `## Design`), and `sp:code-implementation` can build it without re-deciding
+anything. Hand off to the spine (`sp:spur-dev`) to dispatch implementation.

package/plugins/sp/skills/sys-architecture/references/upkeep-survey.md

@@ -0,0 +1,75 @@
+---
+name: upkeep-survey
+description: "The architecture-upkeep survey procedure for sp:sys-architecture — scan a codebase (or module tree) for shallow modules and deepening opportunities using the deep-module vocabulary, and emit a MARKDOWN candidate report that feeds the planning half. Surfaces candidates; never auto-refactors."
+see_also:
+  - sys-architecture
+---
+
+# Architecture-Upkeep Survey
+
+A whole-codebase (or named-module-tree) audit that surfaces **deepening opportunities** — places where
+a shallow module, a pass-through wrapper, or a leaky seam could be made deeper, simpler at the
+interface, or better-located. It is the standing-upkeep counterpart to the per-decision design method
+in [decision-method.md](decision-method.md): same vocabulary, different trigger. It **generates
+candidates for the planning half**; it never edits code.
+
+## Scope
+
+- **Whole codebase** (default) or a **named module tree** (`apps/cli`, `packages/domain`, …).
+- Prefer a bounded tree per run — a survey that flags fifty things helps no one. Rank hard, present few.
+
+## Method — reuse the deep-module vocabulary
+
+Apply the vocabulary and tests defined in [decision-method.md](decision-method.md) §4 (do not restate
+them here): **module / interface / depth / seam / adapter / leverage / locality**, and the **deletion
+test**. Scan for the smells that vocabulary names:
+
+| Smell | What to look for |
+|---|---|
+| **Shallow module** | Interface nearly as large as the implementation it hides — little capability per unit of interface. |
+| **Pass-through wrapper** | A module whose methods just forward to another with no added value — fails the deletion test. |
+| **Leaky seam** | A boundary that exposes its internals; callers reach past the interface into implementation. |
+| **Misplaced locality** | Logic that lives far from the data/state it operates on, forcing round-trips. |
+| **Repeated adapter** | The same glue written at many call sites instead of behind one seam. |
+
+For each candidate, run the **deletion test**: "if I deleted this module and inlined it, does the
+system get simpler?" A yes is the strongest signal it is shallow.
+
+## Output — a MARKDOWN candidate report (never HTML)
+
+Emit markdown the operator can read and paste. One block per candidate, ranked strongest-first:
+
+```markdown
+## Architecture-upkeep candidates — <scope> (<date>)
+
+### C1 — <short title>   [strength: strong | moderate | speculative]
+- **Files:** `path/a.ts`, `path/b.ts`
+- **Problem:** <which smell; the deletion-test result in one line>
+- **Proposed deepening:** <the restructuring — the deeper module / merged seam / relocated logic>
+- **Before → after (prose):** <today's shape> → <the proposed shape>, and why the interface shrinks
+- **Recommendation:** <do it now / schedule / leave — with the one-line reason>
+
+### C2 — …
+```
+
+- **Markdown only.** Never emit an HTML report; the corpus and the operator read markdown.
+- **Strength label is mandatory** so the operator can triage; a survey with no ranking is noise.
+- **Before/after in prose**, not a diff — the survey proposes shape, it does not write the change.
+
+## Route — candidate → grilling-to-design
+
+The survey ends at the report. The operator picks a candidate and routes it into the **planning half**
+as a generated idea:
+
+- `/sp:dev-idea` — turn the candidate into a feature + task batch (when it is a larger restructuring).
+- `/sp:dev-plan` — plan it directly (when it is a single, well-scoped deepening).
+
+The chosen candidate is then **grilled** through the normal design flow (2–3 approaches, tradeoffs,
+approval gate) before any code is written. The survey never auto-refactors — it only surfaces the
+candidate and hands it to planning.
+
+## Upkeep framing (the one rule)
+
+Surface candidates; **never** auto-refactor. The value is the ranked shortlist of where the
+architecture could deepen, presented for a human decision — not an autonomous rewrite. A survey that
+changes code has overstepped its role.