@gobing-ai/spur 0.3.80 → 0.3.82

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

@@ -0,0 +1,145 @@
+---
+name: spur-composer
+description: "Select, compose and tune spur artifacts — tasks, features, rules, workflows and agent specs. Owns workflow catalog selection, the ephemeral→project→shared ladder, the ADR-115 budgets, trace-driven rule tuning, and applying accepted sp:spur-doctor proposals. Triggers: compose a workflow, tune a rule, apply doctor proposals."
+license: Apache-2.0
+version: 1.0.0
+metadata:
+  author: spur
+  platforms: "claude-code,codex,openclaw,opencode,antigravity"
+  category: artifact-composition
+  interactions:
+    - inversion
+    - companion
+  operations:
+    - select
+    - compose
+    - tune
+    - apply
+  openclaw:
+    emoji: "🎼"
+see_also:
+  - sp:spur-cli
+  - sp:spur-doctor
+  - sp:super-planner
+---
+
+# sp:spur-composer — compose, select and tune spur artifacts
+
+One cross-noun method (ADR-114, [spur artifact evolution](../../../../docs/design/spur-artifact-evolution.md)
+§2): **select** an existing artifact, **compose** a new one up the ladder, **tune** it against
+evidence, and **apply** the proposals the operator accepts from `sp:spur-doctor`. It never judges
+its own output and never runs a recurring loop — evaluation is the doctor's job.
+
+## Boundary — read before composing
+
+- **Verbs and flags live in `sp:spur-cli`.** This skill links references; it never restates a verb
+  or flag catalog: [../spur-cli/SKILL.md](../spur-cli/SKILL.md).
+- **Recurring loops and coordination go to `sp:super-planner`** or a workflow — not here. This skill
+  runs one bounded composition or tuning pass per invocation.
+- **Forbidden surface: `spur agent loop`** (supervisor-internal). Agent specs are read through
+  `spur agent list --specs`; they are declared in the fleet config, not authored by a CLI verb.
+- **Writes land only through `spur` verbs** and the ladder's gated file steps (§ below). The shared
+  step additionally needs recorded operator consent plus `build:bundle` parity.
+
+## Covered nouns
+
+| Noun | Composition / tuning method | Verb reference |
+| --- | --- | --- |
+| task | Apply accepted doctor rows via the CLI-gated corpus surface; author variants through the task reference's conventions | [../spur-cli/references/tasks.md](../spur-cli/references/tasks.md) |
+| feature | Apply accepted rows through `spur feature update --section --from-file`; keep acceptance criteria in Gherkin | [../spur-cli/references/features.md](../spur-cli/references/features.md) |
+| rule | The trace-driven tuning loop (§ Rule tuning loop) | [../spur-cli/references/rules.md](../spur-cli/references/rules.md) · [fine-tuning](../spur-cli/references/rules/fine-tuning.md) |
+| workflow | Catalog selection, the composition ladder, and the ADR-115 budgets (§ below) | [../spur-cli/references/workflows.md](../spur-cli/references/workflows.md) · [operations](../spur-cli/references/workflows/operations.md) |
+| agent spec | Read through `spur agent list --specs`; specs are materialized from the fleet declaration at serve start | [../spur-cli/references/agent.md](../spur-cli/references/agent.md) |
+
+Do not drive the planning→execution lifecycle from here — that is `sp:spur-dev`.
+
+## Workflow catalog selection
+
+Run this **before composing anything new**, exactly as the
+[find-existing-workflow](../spur-cli/references/workflows/operations.md#sub-procedure-find-existing-workflow)
+procedure: the catalog is `spur workflow list --json` across all layers, and each entry's
+`description` is its intent.
+
+| Catalog match | Action |
+| --- | --- |
+| Matches the intent | **Run it as is.** No new artifact. |
+| Near match | **Same-name override in the project layer** (`.spur/workflows/<name>.yaml`) — the project layer wins name resolution — and tune from there. |
+| No match | **Compose** up the ladder (§ Composition ladder). |
+
+Never glob a folder to enumerate candidates: layers you skip that way are layers a bare name
+cannot resolve from.
+
+## Composition ladder
+
+| Step | Location | Gate before use |
+| --- | --- | --- |
+| ephemeral | A scratch file outside every layer (for example under `.spur/run/`), run by explicit path | `spur workflow validate`, `spur workflow run --dry-run`, a `spur workflow show` preview |
+| project | `.spur/workflows/<name>.yaml` | The same gates |
+| shared | the spur repository's shipped shared workflow layer (layer id `shared` in `spur workflow list --json`) as `<name>.yaml` | The same gates, **plus recorded operator consent and `build:bundle` parity** |
+
+- `spur workflow validate --json` exits 1 on an error-level composition finding, so a definition
+  over a cap cannot climb. Warn-level findings do not block a step.
+- Verify each step through the shared
+  [validate-and-dry-run](../spur-cli/references/workflows/operations.md#sub-procedure-validate-and-dry-run)
+  core. The shared step is a promotion, not a copy: record the operator consent that authorizes it,
+  then rebuild the bundle (`bun run --filter @gobing-ai/spur build:bundle`) so the shipped config
+  matches.
+- In an adopting project the shared layer is the installed package and is read-only — the project
+  step is the tuning path there.
+
+## Composition budgets (ADR-115)
+
+The consolidation and cache-window rules are taught once in
+[workflow-fit-and-tuning.md](../spur-cli/references/workflows/workflow-fit-and-tuning.md#consolidation-and-cache-windows-adr-115)
+and owned by the
+[workflow composition contract](../../../../docs/design/workflow-composition-contract.md#composition-budgets-adr-115);
+link them, never restate them. While composing or tuning a workflow, apply them with the ADR-115
+budgets:
+
+- **Merge adjacent model steps** only when they share a role and an executor **and** no gate, HITL
+  state or independence boundary sits between them.
+- **Never merge an author step with the review or verify step that certifies it** — those keep
+  `freshSession: true`.
+- **Run long deterministic work outside `agent.run`** — an in-step tool call that outlasts the
+  cache window idles the model and cold-rewrites the prefix.
+
+A new model step in a shared workflow raises its `pipeline-budgets` `modelQueries`; that needs a
+recorded decision before the shared step.
+
+## Rule tuning loop
+
+Start from trace evidence, never from a guess:
+
+1. `spur rule trace <runId> --json` — read the per-rule `evaluations` findings and severities.
+2. Classify each hit: true positive, false positive, or noise.
+3. Tune with the [fine-tuning levers](../spur-cli/references/rules/fine-tuning.md) — severity,
+   glob scoping, exemptions, preset composition.
+4. `spur rule validate` on the tuned rule files.
+5. `spur rule run` on the affected inputs (constitution T11 — affected inputs, not a corpus sweep).
+6. Trace again and compare. A tuning with no trace pair behind it is a preference.
+
+## Applying doctor proposals
+
+`sp:spur-doctor` ([../spur-doctor/SKILL.md](../spur-doctor/SKILL.md)) returns a proposal table;
+the operator accepts rows; **this skill applies them**:
+
+1. For each accepted row, run its `apply` route — always the `spur` verb or ladder step named in
+   the row. Composer never invents a write route.
+2. Re-run that row's `verify` evidence and confirm it clears. An accepted row that cannot verify
+   is reported as not applied, never waved through.
+3. A `task` row carries the history-anatomy finding `key` in the task body — the existing handoff
+   route. Keep it.
+4. A row that changes a shared workflow goes through the ladder's shared step and its recorded
+   consent.
+
+A caller that wants a record saves the accepted table under `docs/reports/`; this skill creates no
+artifact store.
+
+## What this skill is not
+
+- **Not the judge.** `sp:spur-doctor` evaluates artifacts and proposes; code review is
+  `sp:super-reviewer`.
+- **Not a loop.** Recurring evolution loops and multi-agent coordination belong to
+  `sp:super-planner` or a workflow definition.
+- **Not a catalog.** Verb, flag, output and exit semantics live in the `sp:spur-cli` references
+  linked above.

package/plugins/sp/skills/spur-dev/references/ac-style-guide.md

@@ -127,6 +127,16 @@ unmatchable):
 | AC-0817-HERM-SKIP | MET | test | `tests/loader.test.ts:962` |        ← declared
 ```
 
+### A bullet's bold head is its id
+
+`verify-answer-lint` declares the bold span of a single-line criterion bullet
+(`- **AC2 — The roster runtime is gone (R3).** Given …, when …, then …`) and its head before the
+first ` — ` or `:` — so answer rows may key `AC2` or `AC2 — The roster runtime is gone (R3).`. Keep
+at least one answer row keyed to the verbatim feature scenario title the task graduates, and keep
+requirement ids in the corpus form they are checked against (`- **R1** — …`): `L3.requirements-format`
+matches `R\d+` followed by a space, so a colon after the bold span silently drops the whole section
+to a warning.
+
 ### The id is exactly the scenario title — no Gherkin body appended
 
 An AC row id must be **exactly** the scenario title (plus any of the four forms above), with the

package/plugins/sp/skills/spur-dev/references/execution-batch.md

@@ -885,7 +885,7 @@ command doc so it does not read as a bug.
 ## Still out of scope
 
 - **Interactive within-step Q&A** — a headless subprocess `agent.run` agent asking the operator a
-  real question. This waits for the workspace module + inbox module + `spur agent` team mode.
+  real question. This waits for the workspace module + inbox module + the agent fleet.
   `sp:super-planner` surfaces blockers/HITL only at the **batch boundary** (between task runs), not
   from inside a pipeline step.
 

package/plugins/sp/skills/spur-dev/references/execution-workflow.md

@@ -327,12 +327,10 @@ task.** A `cheap`/`standard`-tier model handed a task that big does not fail fas
 entire `implementTimeoutMs` and exits 3 with a partial tree (run `ca130182` — 7 reqs / 9 plan
 items / 12+ files → 30 minutes, 6 of 12 files, no tests, no docs, no `## Solution`).
 
-The precheck size gate enforces this: it resolves `$implementAgent`'s capability tier
-(`spur agent doctor <exec> --json` → `capabilityTier`) and writes FAIL for a large task on an
-executor below the `reviewer` role's floor, naming the executor and its tier. An unknown or
-undeclared tier reads as the `coder` floor, so the block is the default. Clear it deliberately —
-`--agent <capable>` / `--vars '{"implementAgent":"<capable>"}'`, or split — never by raising
-`maxImplementReqs`: the caps accept a big task, they do not make a flash model able to finish one.
+The precheck size gate is count-only: it writes FAIL above 10 requirements or 16 Plan items and
+never consults the executor's capability tier. Clear a FAIL deliberately — split the task, or raise
+the cap with `--vars '{"maxImplementReqs":<n>}'` — but the caps only accept a big task, they do not
+make a flash model able to finish one.
 
 The empty-implement guard (`requireDiff` on the task-pipeline `implement` step, R3) fails the
 run fast when an implement exits 0 with zero non-corpus changes — a no-op never drifts into

package/plugins/sp/skills/spur-dev/references/glossary.md

@@ -55,7 +55,7 @@ Avoid: *result* (too generic — a verdict has a fixed three-value contract), *r
 for narrative output like the dogfood report or batch report).
 
 **noun/verb** — the two-part CLI grammar: a noun names the domain object (`task`, `feature`,
-`rule`, `workflow`, `agent`, `message`, `team`), a verb names the operation on it (`create`,
+`rule`, `workflow`, `agent`, `message`), a verb names the operation on it (`create`,
 `update`, `check`, `run`, `list`). The `sp:spur-cli` facade organizes its references one file
 per noun.
 Avoid: *command* alone (ambiguous with a `/sp:dev-*` slash command, which is a different

package/plugins/sp/skills/spur-dev/references/inline-pipeline-driver.md

@@ -206,7 +206,12 @@ Action semantics come from the YAML and the workflow action contract:
   state mutates the task, the host validates the same refusal conditions inline — the declared
   artifact exists at the resolved path and is canonical-valid for the run's wbs (for
   `verify-verdict`: verdict `PASS`), `proofBinding: current` is honored against a freshly captured
-  proof digest, and the run-scoped review-completion marker exists — then appends one provenance
+  proof digest — capture it with `bun "$SETUP_SCRIPT" --fingerprint --task-file <task path>
+  [--feature-file <feature path>]`, the same entry point used at Run setup, which prints the engine
+  `sha256:<hex>` digest. Run it from the worktree root (cwd feeds the git-tree half of the digest)
+  and pass the same `--feature-file` the run folded in — omitting it, or running from elsewhere,
+  yields a different digest and the mismatch surfaces later as a refused `run.artifact`
+  registration — and the run-scoped review-completion marker exists — then appends one provenance
   line to `.spur/run/<run-id>.log` naming the equivalence (artifact kind, path, verdict, digest) and
   proceeds to `spur task record`. A failed validation stops at the state and follows the failure
   contract; the step is never silently skipped. Artifact-provenance consumers read that run-log
@@ -267,6 +272,11 @@ boundary, and a delegate left to re-derive them re-derives them against its own
 Nothing else: no task/session transcripts, no machine-specific session paths. The WBS/path already
 carried by the slash command remains the task handoff.
 
+**Delegate hygiene.** A dispatched stage cleans up after itself: temporary artifacts stay inside the
+execution tree, and an ad-hoc git worktree created for a comparison is removed before the stage
+reports. The G65 batch's implement dispatches left an 867 MB worktree plus a trail of `/tmp` scratch
+files that outlived the run (2026-09-15).
+
 **Verify-stage artifact contract.** A verify handoff names
 [`code-verification/references/verdict-schema.md`](../../code-verification/references/verdict-schema.md)
 as the canonical answer schema and carries this compact form verbatim:

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

@@ -270,6 +270,30 @@ missing title match. After batch creation, `handoff-finalize`:
    (runall is then omitted), otherwise `/sp:dev-runall --feature <id> --auto`. The terminal
    handoff note points at this report.
 
+**Ready preparation (ready-prepare, 0788).** The input is the `.wbs` array in
+`.spur/run/<runId>-idea-batch-create-result.json`. For EACH wbs: resolve the task file with
+`spur task path <wbs> --json` and apply the ready-refinement checklist — make requirements,
+design, plan, acceptance criteria, decisions, dependencies and premises present and
+non-placeholder so `spur task check <wbs> --json` exits 0. Write planning sections only, through
+`spur task update <wbs> --section <Name> --from-file <file>` — never Solution, Testing, Review
+or History. Record one checklist row per id, with concrete evidence of how you verified it.
+Compute the planning digest with the project's own implementation when this is a monorepo
+checkout — resolve the file with `spur task path <wbs> --json`, then run:
+
+```bash
+bun -e 'const m = await import("./packages/app/src/services/task-readiness"); console.log(m.computePlanningDigest(await Bun.file(process.argv[1]).text()))' <task-file>
+```
+
+When that is impossible in this checkout, set status `skipped` instead of guessing a digest.
+Finally write `.spur/run/<runId>-idea-ready.json` with exactly this shape:
+
+```json
+{"runId":"<runId>","depth":"ready","tasks":[{"wbs":"<wbs>","status":"ready" | "failed" | "skipped","planningDigest":"<sha256 hex>","checks":[{"id":"requirements" | "design" | "plan" | "ac" | "decisions" | "dependencies" | "premises","pass":true,"evidence":"<how verified>"}]}]}
+```
+
+A task you cannot fully prepare gets status `failed` or `skipped` — never fabricate evidence;
+the handoff degrades to refineall.
+
 ## Step 6: Refine before execute (the spec-completion gate)
 
 `batch-create` accepts optional `design` / `plan` / `acceptance_criteria` fields (plus

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

@@ -0,0 +1,138 @@
+---
+name: spur-doctor
+description: "Evaluate spur artifacts from read-only CLI evidence — tasks, features, rules, workflows, agent specs — reflect over sp:history-anatomy findings, and return a proposal table. Diagnoses spur artifacts, not runtime environments (that is spur agent doctor). Triggers: check artifact health, propose evolution, reflect over history findings."
+license: Apache-2.0
+version: 1.0.0
+metadata:
+  author: spur
+  platforms: "claude-code,codex,openclaw,opencode,antigravity,pi"
+  category: artifact-composition
+  interactions:
+    - reviewer
+    - inversion
+  operations:
+    - evaluate
+    - reflect
+    - propose
+  openclaw:
+    emoji: "🔬"
+see_also:
+  - sp:spur-cli
+  - sp:spur-composer
+  - sp:history-anatomy
+  - sp:super-planner
+---
+
+# sp:spur-doctor — evaluate spur artifacts and propose changes
+
+One cross-noun method (ADR-114, [spur artifact evolution](../../../../docs/design/spur-artifact-evolution.md)
+§2): gather **read-only CLI evidence** about tasks, features, rules, workflows and agent specs,
+**reflect** over `sp:history-anatomy` findings, and return a **proposal table**. It diagnoses spur
+**artifacts** — definitions, rules, corpus records — not runtime environments: whether an agent
+binary, host session or tool install is healthy is `spur agent doctor`'s job, not this skill's.
+
+## Read-only invariant
+
+The doctor **writes nothing and names no mutating verb**. It performs no task, feature, rule or
+workflow write — the operator accepts rows and `sp:spur-composer`
+([../spur-composer/SKILL.md](../spur-composer/SKILL.md)) applies them. A caller that wants a
+record saves the returned table under `docs/reports/`; the doctor creates no artifact store.
+
+- **History enters only through `sp:history-anatomy` findings.** Raw history records stay out
+  of scope and are never re-interpreted here; history-anatomy is the only history interpreter.
+- **Recurring reflection loops and coordination go to `sp:super-planner`** or a workflow — one
+  bounded evaluation pass per invocation.
+- **Forbidden surface: `spur agent loop`** (supervisor-internal). Agent specs are read only through
+  `spur agent list --specs --json`.
+
+## Evidence per noun
+
+| Noun | Evidence (read-only) |
+| --- | --- |
+| task | `spur task check <wbs> --json` |
+| feature | `spur feature check <id> --json` |
+| rule | `spur rule trace --json`, `spur rule validate` |
+| workflow | `spur workflow validate --json` (findings by `level`), `node "$(superskill script path sp workflow-step-profile.mjs)" <workflow> --json` |
+| agent spec | `spur agent list --specs --json` |
+| history | A `sp:history-anatomy` report ([../history-anatomy/SKILL.md](../history-anatomy/SKILL.md)), never raw history records |
+
+Every row of a proposal cites the evidence it rests on. No anchor, no proposal.
+
+## Workflow step profile and cache-window flags
+
+The step profile (`plugins/sp/scripts/workflow-step-profile`, ADR-065 plugin entrypoint) reads
+`spur workflow trace` for a workflow's last N completed, non-dry runs. Per node and action kind it
+reports run count, executions, p50 and max `durationMs`, p50 idle gap before the step, session mode
+(`fresh`, `resumed` or `mixed`) and `cacheHit` p50 with its coverage — satellite §10 step evidence.
+
+```bash
+node "$(superskill script path sp workflow-step-profile.mjs)" <workflow> --json
+```
+
+`W` is the cache window, **300** seconds by default (satellite §10). The script computes every flag
+arithmetically; doctor maps the flag ids to proposals and never re-derives numbers from prose. Each
+flag and each composition finding becomes one proposal row with action class **workflow
+optimization**, and the change comes from the §10 table:
+
+| Evidence | Flag | Proposed change |
+| --- | --- | --- |
+| Validate finding, `level: error` | always | Extract to an owner from the closed fix vocabulary |
+| Validate finding, `level: warn` | always | Extract, or record a stays-shell reason inside the warn band |
+| Deterministic step | `step-over-window` — p50 > W | Split it, or move the slow work out of the step |
+| Resumed `agent.run` | `resume-after-idle` — p50 idle gap before it > W | `freshSession: true` with the prior artifact as handoff |
+| Resumed `agent.run` | `resume-cold-cache` — `cacheHit` p50 < 0.5, with evidence | The same, or move a long in-step tool call to a deterministic step |
+| `agent.run` | `agent-run-over-2w` — p50 > 2W | Split at an artifact seam, or no-op when none exists |
+
+- The two validate finding rows classify by `level` alone and carry no flag id.
+- A row with `cacheHit.known: 0` raises no cache flag. Its cache evidence is **unknown, never a zero
+  hit rate**, and doctor reports it as unknown rather than as a 0% hit.
+- A proposal that changes a shared workflow goes through §7 of the composition ladder
+  ([spur-composer](../spur-composer/SKILL.md)), including its recorded operator consent.
+
+## Reflection map over history findings
+
+For each history-anatomy finding (`key`, `category`, `trend`, `ownerSurface`), assign **exactly
+one** action class. The first matching row wins:
+
+| # | Finding | Action class |
+| --- | --- | --- |
+| 1 | `trend` is `resolved` or `improved` | no-op |
+| 2 | `category` is `positive` | doc or learning |
+| 3 | Automatable, per step 1 of the [placement rule](../../references/environment-lens.md#placement-rule) | rule candidate |
+| 4 | `ownerSurface` is a workflow definition | workflow optimization |
+| 5 | `ownerSurface` is a doc, skill, reference or steering file | doc or learning |
+| 6 | Anything else | task |
+
+The five action classes are closed: **task**, **rule candidate**, **workflow optimization**,
+**doc or learning**, **no-op**. The doctor classifies the report's findings and never derives new
+ones from raw records — that would make it a second history interpreter.
+
+## Proposal table
+
+Return one row per actionable finding, with exactly these columns:
+
+| Column | Content |
+| --- | --- |
+| `key` | The finding key, or `<noun>:<id>:<check>` for an artifact finding |
+| `evidence` | The CLI output or report section the row rests on |
+| `action` | One action class from the reflection map (or the per-noun evaluation) |
+| `change` | The proposed change, in one line |
+| `apply` | The `spur` verb or composer procedure that lands it |
+| `verify` | The evidence to re-run after applying |
+
+Rules:
+
+- The `apply` route is always a `spur` verb or a gated composer step — never a raw file edit this
+  skill performs. Shared-workflow rows route through the composition ladder's shared step.
+- A `task` row carries the finding `key` in the task body (the history-anatomy handoff route).
+- Rows are proposals only. No applied change, diff, or command output claimed as run.
+
+## What this skill is not
+
+- **Not the applier.** `sp:spur-composer` applies accepted rows; this skill performs no
+  task/feature/rule/workflow write.
+- **Not a runtime doctor.** Environment, binary and session readiness belong to
+  `spur agent doctor`; this skill diagnoses spur artifacts from CLI evidence.
+- **Not a history interpreter.** Findings come from `sp:history-anatomy` reports, never from raw
+  history records.
+- **Not a loop.** Recurring evolution passes belong to `sp:super-planner` or a workflow.

package/plugins/sp/skills/taste-refactoring-api/README.md

@@ -0,0 +1,43 @@
+# taste-refactoring-api
+
+A reusable agent skill for designing, reviewing, and safely refactoring production APIs.
+
+## What it covers
+
+- REST/HTTP
+- RPC/gRPC
+- GraphQL
+- events/webhooks
+- domain/resource modeling
+- naming and schemas
+- errors
+- pagination/filtering/sorting
+- idempotency and retries
+- concurrency
+- versioning/deprecation/migration
+- API security
+- observability
+- reliability/performance
+- contract testing and documentation
+
+## Suggested installation
+
+Install/copy this directory as an agent skill named `taste-refactoring-api` and load `SKILL.md` as the skill instructions. Keep the `references`, `checklists`, and `examples` directories available for deeper reviews.
+
+## Daily usage examples
+
+- “Use taste-refactoring-api to review this OpenAPI spec.”
+- “Refactor these Express routes without breaking current clients.”
+- “Review this GraphQL schema for compatibility and developer experience.”
+- “Design a safe pagination and filtering contract for this endpoint.”
+- “Create a migration plan from v1 to v2 with no abrupt client breakage.”
+- “Run the daily API quality checklist on this PR.”
+
+## Files
+
+- `SKILL.md` — main agent operating instructions
+- `references/api-refactoring-playbook.md` — deeper operational guidance
+- `references/research-basis.md` — standards and sources used to build the skill
+- `checklists/daily-api-review.md` — fast daily checklist
+- `examples/review-template.md` — reusable review format
+- `examples/refactor-example.md` — worked refactoring example