@gobing-ai/spur 0.3.63 → 0.3.65

package/plugins/sp/skills/redesign-web-ui/references/upgrade-techniques.md

@@ -0,0 +1,66 @@
+# Upgrade techniques
+
+Optional moves for `sp:redesign-web-ui` Plan/Apply. Load this file only when a Diagnose finding
+needs a technique from it.
+
+Every technique here is **polish**. Accessibility and token authority always win. Honor
+`prefers-reduced-motion: reduce` by disabling or replacing motion with an instant state change.
+
+Product/app chrome (dashboards, settings, editors) stays restrained. Marketing/landing pages can
+spend more on one signature moment. Spend boldness in **one** place.
+
+---
+
+## When a technique is in play
+
+Use a technique when:
+
+- The finding is `polish`, and
+- The page type supports it (landing/marketing, or a single product moment), and
+- The authority layer (`DESIGN.md` / theme) does not forbid it.
+
+Skip the technique when:
+
+- It requires a new animation library or a CSS-framework migration.
+- It hijacks scroll (inertia/custom scrollbar physics) on a product UI.
+- It would be the second signature moment on the same page.
+
+---
+
+## Typography
+
+- **Variable-font weight/width** on hover or a short scroll range — one word or one heading, not every line.
+- **Outlined-to-fill** on a display line that is the page's thesis.
+- **Text as mask** only when a real, owned video/image sits behind it.
+
+## Layout
+
+- **Broken grid / overlap** — one element bleeds or overlaps on purpose; the rest stay on the grid.
+- **Whitespace maximization** — one block gets aggressive negative space so it is the only focus.
+- **Sticky stack** — sections pin and stack on scroll on a marketing long-scroll, not inside app chrome.
+- **Split-screen scroll** — two panes moving in opposition; marketing only, and never the only way to reach content.
+
+## Motion
+
+- **Staggered entry** — small Y + opacity cascade on first paint of a group (40–80ms steps).
+- **Spring on press** — interactive controls, not page load.
+- **Scroll-driven reveal** — mask, wipe, or SVG draw tied to scroll *progress*, with a reduced-motion static end-state.
+
+Do not add smooth-scroll inertia, scrolljacking, or a custom scrollbar on product UI. Native
+`scroll-behavior: smooth` plus a reduced-motion instant fallback is the ceiling unless the operator
+asks for more.
+
+## Surfaces
+
+- **Glass** — `backdrop-filter` plus a 1px inner border and a faint inner shadow; only over content
+  that remains readable.
+- **Spotlight border** — cursor-tracking edge light on one featured card.
+- **Grain overlay** — `pointer-events: none`, fixed, very low contrast; skip on dense data tables.
+- **Tinted shadows** — shadow hue matches the surface, not generic black.
+
+---
+
+## Signature test
+
+After picking techniques, keep one memorable moment. If two techniques compete, drop the weaker
+one. The surrounding UI stays quiet so the signature can read.

package/plugins/sp/skills/session-review/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: session-review
+description: "Review the active coding-agent session, distinguish resolved and open issues with evidence, and propose bounded improvements. Triggers: review this session, session wrap-up, immediate retrospective, what happened, what was resolved."
+license: Apache-2.0
+version: 1.0.0
+metadata:
+  author: spur
+  platforms: "claude-code,codex,openclaw,opencode,antigravity,pi"
+  category: analysis-core
+  interactions:
+    - reviewer
+see_also:
+  - sp:history-anatomy
+  - sp:indexed-context
+  - sp:code-verification
+---
+
+# sp:session-review — Active Session Review
+
+Review the active coding-agent session while its conversation context is still available. Produce a
+compact, evidence-backed report of outcomes, resolved issues, remaining risks, and improvements.
+
+## When to use
+
+Use this skill immediately after focused operations when the operator asks what happened, what was
+resolved, or how the session could improve. Use imported-history analysis for ended sessions,
+cross-agent windows, recurrence, trends, or quantitative performance forensics.
+
+## Arguments
+
+| Argument | Description | Default |
+| --- | --- | --- |
+| `[focus]` | Question or operation to emphasize. It changes ordering, not evidence collection. | full active session |
+
+## Evidence boundary
+
+- Treat the active conversation as the primary evidence plane.
+- Verify each material claim with source evidence from the conversation or a read-only repository
+  check, and cite the exact result or path in the report.
+- Use read-only repository checks only when they confirm a material claim; prefer existing tool
+  results already visible in the session over rerunning commands.
+- Mark an issue **resolved** only when the session shows the symptom, root cause, applied resolution,
+  and verification evidence. Otherwise classify it as open or attempted.
+- Separate observation from inference. Label an unsupported causal explanation as a hypothesis and
+  name the confirmation needed.
+- State `not available` when compaction or missing output removed evidence. Never reconstruct it from
+  memory or claim a verification that did not run.
+
+## Protocol
+
+1. **Resolve scope.** Review the active session from the operator's initiating request through the
+   latest result. Use `[focus]` only to rank relevant material.
+2. **Inventory outcomes.** List requested outcomes and classify each as completed, partial, blocked,
+   or not attempted. Collapse repeated attempts into one outcome.
+3. **Classify issues.** For every material issue, distinguish resolved, open, or attempted. Record
+   root cause only when the evidence boundary supports it.
+4. **Select improvements.** Keep at most three changes that would prevent meaningful recurrence.
+   Apply the placement rule in
+   [the environment-improvement mapping](../../references/environment-lens.md): automate with a
+   check when possible, place coding standards on the review path, and keep always-loaded steering
+   as navigation pointers.
+5. **Render the report.** Use the exact compact output contract below. Omit empty table rows, not
+   headings; write `None observed` when a section has no supported entry.
+
+## Output contract
+
+### Outcome
+
+State the overall result in one to three sentences, including partial or blocked scope.
+
+### Resolved issues
+
+| Issue | Root cause | Resolution | Evidence |
+| --- | --- | --- | --- |
+
+Evidence names the tool result, verification command, or concrete repository state visible in the
+session. Do not list ordinary implementation steps as issues.
+
+### Open issues and risks
+
+| Issue or risk | State | Evidence or confirmation needed |
+| --- | --- | --- |
+
+### Process and environment improvements
+
+For each supported proposal, name its owner surface, expected impact, verification method, and
+reversibility. Proposals remain report-only: apply no change and create no task.
+
+### Next actions
+
+List only actions needed to finish partial scope, confirm a hypothesis, or preserve a demonstrated
+improvement. Use `None` when the session is complete and no follow-up is justified.
+
+## Boundaries
+
+- Stay in the active host session. Do not delegate; a fresh context loses the evidence being reviewed.
+- Do not launch a workflow, import history, create or update corpus items, or edit files.
+- Do not append indexed-context memory.
+- Do not perform baseline comparison, recurrence classification, cache publication, or a twelve-section
+  forensic report; those belong to imported-history analysis.
+- Do not turn a single low-impact observation into a new policy. Report it as a candidate until it
+  recurs or demonstrates a high-impact contract violation.
+
+## Platform notes
+
+On platforms without slash commands, invoke this skill directly before ending the active session.

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

@@ -48,7 +48,7 @@ through a coding agent as an external process, producing a persisted run record
 
 | Flag | Purpose |
 | ------ | --------- |
-| `--agent <name>` | Role, executor, agent binary, `auto`, or `inline`. A **role** (`scribe`/`coder`/`reviewer`/`planner`, from `plugins/sp/references/roles.md`) selects the starting tier; an **executor** (an `agent.executors` entry) is a permanent pin; a **bare binary name** works with a one-time warning (transition shim); `auto` uses the declared/default role. **`inline` is host-session-only** (G5 / ADR-047 amendment): `agent run` is a headless subprocess surface, so explicit `inline` is rejected with exit 2 and a stable error message — it never normalizes to `agent.default`. |
+| `--agent <name>` | Role, executor, agent binary, `auto`, or `inline`. A **role** (`scribe`/`coder`/`reviewer`/`planner`, from `plugins/sp/references/roles.md`) selects the starting tier; an **executor** (an `agent.executors` entry) is a permanent pin; a **bare binary name** works with a one-time warning (transition shim); `auto` uses the declared/default role. `inline` is the default selector (0687 / ADR-087): on a host session the work runs in-session; on a headless subprocess surface like `agent run` it substitutes tier resolution and warns once naming the resolved executor — no rejection, no `agent.default` normalization. |
 | `--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. |

package/plugins/sp/skills/spur-cli/references/workflows/authoring-workflows.md

@@ -218,9 +218,14 @@ verifying shape, or stand in a `note` action until the path is proven, then swap
 
 ## Authoring checklist
 
+- [ ] Fit gate cleared before the mode gate — replay + machine-checkable branch + durable record
+      ([workflow-fit-and-tuning.md](workflow-fit-and-tuning.md#1-fit-gate--workflow-or-prose)).
 - [ ] Mode chosen deliberately (loop → state-machine; pipeline → transition-flow); recorded the reason.
 - [ ] `kind: transition-flow` set for flows; `$schema` quoted.
 - [ ] Initial + terminal states/nodes declared; every transition/edge target exists.
 - [ ] Guards/conditions ordered so the specific case precedes the fallback.
 - [ ] `iterationBound` set for any loop; `env.allow` lists every `${env.X}` used.
+- [ ] Every node inside the simplicity budget — `shell` at or under 5 non-comment units,
+      `agent.run` input referencing a command rather than a raw prompt, guards a single predicate
+      ([workflow-fit-and-tuning.md](workflow-fit-and-tuning.md#3-node-simplicity-budget)).
 - [ ] Validates clean AND dry-run reaches the expected terminal state.

package/plugins/sp/skills/spur-cli/references/workflows/operations.md

@@ -161,22 +161,31 @@ Turn a described process into a validated, dry-run-verified workflow in the righ
 1. **Clarify intent** — restate the process as one or two sentences: the steps, the success terminal,
    the loop/branch points. If ambiguous (which step retries? what ends it?), state the interpretation
    taken.
-2. **Mode-selection gate** — run [mode-selection gate](#sub-procedure-mode-selection-gate). This is
+2. **Fit gate** — run the three-part test in
+   [workflow-fit-and-tuning.md](workflow-fit-and-tuning.md#the-three-part-test) *before* the mode
+   gate: the process earns a workflow only if it replays, branches on a machine-checkable predicate,
+   and needs a durable per-run record. Fewer than three → recommend a descriptive procedure /
+   checklist instead and stop; do not author YAML the process will not use.
+3. **Mode-selection gate** — run [mode-selection gate](#sub-procedure-mode-selection-gate). This is
    mandatory and gating: surface the recommended mode with its reason and the rejected alternative,
    and **confirm before authoring**. Honor an explicit `--kind`.
-3. **Reconcile against existing workflows** — run [find-existing-workflow](#sub-procedure-find-existing-workflow).
+4. **Reconcile against existing workflows** — run [find-existing-workflow](#sub-procedure-find-existing-workflow).
    If the process is already covered, **stop and hand to refine (or extend the existing flow) on
    confirmation** — do not author a redundant workflow. Only the "no real match" / "add-new" branch
    proceeds to author below.
-4. **Author the YAML** — use the **real schema shape** for the chosen mode
+5. **Author the YAML** — use the **real schema shape** for the chosen mode
    ([authoring-workflows.md → Per-mode shapes](authoring-workflows.md#per-mode-shapes)). Set `name`,
    `description` (the WHY), the initial + terminal states/nodes, the steps with their actions, the
    transitions/edges with guards/conditions in the right declaration order, `iterationBound` for any
    loop, `env.allow` for any `${env.X}`, and a quoted `$schema`. For transition-flow, set
    `kind: transition-flow`.
-5. **Place the file** — default `.spur/workflows/<name>.yaml` (a `--file` arg overrides), named for
+   Keep each node inside the simplicity budget
+   ([workflow-fit-and-tuning.md](workflow-fit-and-tuning.md#3-node-simplicity-budget)): `shell`
+   commands at or under 5 non-comment units, `agent.run` inputs referencing a slash command rather
+   than carrying a raw prompt, guards a single predicate.
+6. **Place the file** — default `.spur/workflows/<name>.yaml` (a `--file` arg overrides), named for
    what the workflow does.
-6. **Verify** — run the [validate-and-dry-run core](#sub-procedure-validate-and-dry-run) with the
+7. **Verify** — run the [validate-and-dry-run core](#sub-procedure-validate-and-dry-run) with the
    expected terminal state. Not done until the definition validates AND the dry-run reaches it.
 
 Output contract: YAML workflow content + chosen mode + reason + destination path + validate result +
@@ -197,6 +206,12 @@ Adjust an existing workflow with the smallest change that meets the intent. Proc
    - missing step → add a state/node + its transition/edge in the correct declaration order
    - runaway loop → set or raise `iterationBound`
    - missing variable/env → add to `vars` or `env.allow`
+   - too slow / unreadable trace (not a correctness bug) → the
+     [optimize procedure](workflow-fit-and-tuning.md#optimize--refine-an-accepted-workflow-in-place),
+     backed by a before/after `spur workflow trace <run-id> --json` pair
+   - the whole file is the wrong surface (all nodes raw `agent.run`, no branching, edited more than
+     run) → not a refine: the
+     [demote procedure](workflow-fit-and-tuning.md#demote--workflow--descriptive-procedure)
    See [authoring-workflows.md](authoring-workflows.md) for each mechanism's real shape. **Do not
    switch mode** in a refine — a mode change is a rewrite; hand it back to `add`.
 3. **Apply the smallest change.** Preserve declaration order semantics (the first passing

package/plugins/sp/skills/spur-cli/references/workflows/workflow-fit-and-tuning.md

@@ -0,0 +1,230 @@
+---
+name: workflow-fit-and-tuning
+description: Decide whether a process should be a spur workflow at all, tune an accepted one for latency and observability, keep its nodes inside the simplicity budget, and refactor across the boundary — promote a descriptive procedure into YAML, demote a YAML back to prose, or optimize one in place.
+see_also:
+  - spur-cli
+  - operations
+  - authoring-workflows
+---
+
+# Workflow Fit & Tuning
+
+Three questions that sit **before and around** the mode gate:
+
+1. **Fit** — should this be a `spur workflow` at all, or a descriptive procedure / checklist?
+2. **Tuning** — given it is one, how is it configured for low latency and legible traces?
+3. **Refactor** — how do you move a process across that boundary in either direction?
+
+**Polaris:** get things done with high efficiency, low latency, and observability. A workflow that
+does not beat prose on all three is prose with a YAML tax.
+
+---
+
+## 1. Fit gate — workflow or prose?
+
+Run this **before** the [mode-selection gate](operations.md#sub-procedure-mode-selection-gate). The
+mode gate answers *which kind of workflow*; it presumes an answer to *whether* — and that
+presumption is the more expensive one to get wrong.
+
+### What each side actually buys
+
+| | `spur workflow` YAML | Descriptive procedure (skill reference, slash command, checklist) |
+| --- | --- | --- |
+| Buys you | Durable run record, resumable HITL pause, bounded retry loops, machine-readable terminal status, `trace`/`--follow`, `cancel`/`clean`, unattended `--async` | Judgment at every step, zero authoring ceremony, edits are one-line, no subprocess per step |
+| Costs you | Authoring + `validate`/`dry-run` upkeep, one subprocess per action node, indirection an agent must read through, a definition that rots when the surface moves | Nothing is replayable, nothing is recorded, "what happened on that run" is unanswerable |
+| Fails at | Steps whose outcome only a reader can judge | Anything that must run the same way twice, unattended |
+
+### The three-part test
+
+A process earns a workflow only when **all three** hold:
+
+- **Replay** — it runs repeatedly, unattended, or across different operators.
+- **Branch** — at least one step routes on a *machine-checkable* predicate (exit code, JSON field,
+  file present), and the run may retry or gate on it.
+- **Record** — someone will later need to answer "what happened on run X" from persisted evidence.
+
+Three yes → author the workflow. Two → borderline: prefer prose plus one shell script, and revisit
+when the run count justifies it. One or zero → **descriptive procedure**; say so and stop.
+
+### Signals
+
+| Signal in the described process | Read as |
+| --- | --- |
+| "Retry until the gate passes", "loop until clean" | workflow — bounded loop is the engine's job |
+| "Pause for approval, continue later / in another session" | workflow — HITL resume needs a run record |
+| "Every night", "for each task in the batch", unattended | workflow — replay + record |
+| "Then check whether it looks right and decide" | prose — the predicate is judgment, not an exit code |
+| "It depends what the diff says" | prose — the branch has no machine-checkable condition |
+| Runs once, then the situation has changed | prose — a checklist, not a definition |
+| One operator, in-session, watching each step | prose — the trace has no second reader |
+
+### The two anti-patterns
+
+- **Prose wearing YAML.** Every node is an `agent.run` with a raw prompt, edges are all
+  unconditional. The engine adds a process spawn per node and contributes no branching, no gate, no
+  retry. This is the ADR-069 R2 measure firing on *every* node — the advisory is telling you the
+  whole file is misplaced, not that eight prompts need polish. Demote it.
+- **YAML wearing prose.** A skill reference that says "then run the checks, and if they fail fix and
+  re-run, up to three times" — a bounded retry loop written as a paragraph an agent re-interprets
+  every session, with no record of how many attempts actually happened. Promote it.
+
+### Hybrid is the usual answer
+
+The boundary runs *through* most processes, not around them. Keep judgment in the skill or slash
+command; put the deterministic gate loop in the workflow; let the workflow's judgment steps call the
+command by name. That is the ADR-043 preference restated as an architecture: **the workflow selects
+and orders capabilities, it does not contain them** (ADR-069).
+
+---
+
+## 2. Tuning — latency, efficiency, observability
+
+### Cost model — know what you are spending
+
+| Node / element | Real cost | Consequence for design |
+| --- | --- | --- |
+| `agent.run` action | A full agent session: seconds to minutes, plus tokens | **The dominant cost.** Count them; every one you remove is the largest single win available |
+| `shell` action | One `sh -c` subprocess, milliseconds | Cheap individually — but each node is also a persisted transition round-trip |
+| Guard (`kind: shell`) | One subprocess **per evaluation**, re-run on every loop iteration | A loop with a bound of 5 pays its guards 5 times |
+| Loop `iterationBound` | Worst case = bound x per-iteration cost | It is a **latency ceiling**, not only a runaway safety net |
+| HITL pause | Unbounded wall-clock (waits on a human) | Never put one inside a loop body |
+
+### Latency checklist
+
+- [ ] **Fewest `agent.run` nodes that still do the work.** Two adjacent judgment steps with no gate
+      between them are one judgment step.
+- [ ] **Soft status-file probe over repeated probing.** Run the expensive check once in an action
+      that always exits 0 and writes its verdict to a run-scoped file; branch with ordered cheap
+      guards that read that file. One subprocess instead of one per branch — the `basic.yaml` and
+      `task-pipeline.yaml` quality-gate idiom.
+- [ ] **Order guards cheapest-discriminating-first.** The first passing guard wins, so a `test -f`
+      ahead of a `spur … --json` parse skips the expensive call on the common path.
+- [ ] **No guard recomputes what a prior node already wrote to disk.**
+- [ ] **`iterationBound` from the budget, not from optimism.** Set it to the observed maximum plus
+      one; a bound of 10 on a 40-second gate is a seven-minute worst case nobody chose.
+- [ ] **Fan out only genuinely independent branches** (`type: parallel`, transition-flow). Serial
+      nodes with no data dependency are pure dead latency.
+- [ ] **`--async` when the caller does not need the terminal state inline**, then follow with
+      `spur workflow trace <run-id> --follow`.
+
+### Observability is an authoring decision, not a run flag
+
+The flags (`--detail`, `--verbose`, `--trace-file`, `--follow`, `--output`) are catalogued in
+[../workflows.md](../workflows.md); they only expose what the definition already made legible.
+
+- [ ] **Name states/nodes after the outcome they establish, not the tool they invoke.**
+      `quality-gate-passed` reads at 3am; `run-script-2` does not.
+- [ ] **`description` carries the WHY** of the workflow; a one-line comment carries the why of any
+      non-obvious guard order or `iterationBound`.
+- [ ] **Every gate writes a machine-readable verdict to a run-scoped file.** It is the guard's input
+      *and* the post-mortem's evidence — one artifact, two consumers.
+- [ ] **Declare `failureStates`** so a failed run reports `status: 'failed'` instead of finalizing as
+      a `done` run that landed somewhere bad (the 0425 reader contract).
+- [ ] **`env.allow` lists exactly what is used** — no more; an over-broad allowlist is an
+      undocumented dependency.
+- [ ] **While tuning:** `--detail full` plus `--trace-file`, and compare traces. **In production:**
+      default detail, retained run log.
+
+---
+
+## 3. Node simplicity budget
+
+Simplicity is the operating constraint, and it is already measurable — `spur workflow validate`
+reports it. Do not invent a second threshold; author to the one that is frozen (ADR-069, task 0614).
+
+| Element | Budget | What breaching it means |
+| --- | --- | --- |
+| `shell` action `command` | **<= 5** non-comment units (split on newline and `;`) | >= 6 flags the composition advisory: the program holds reusable behavior that wants an owner |
+| `agent.run` action `input` | A **slash command or skill invocation** | A raw prose prompt flags: the operation belongs behind a centralized command (ADR-043). Prompt length sets severity only |
+| Transition guard | **One** boolean predicate | Guards are exempt from the shell measure by design. A guard needing five lines is a probe node in disguise — make it one |
+| Node count | Every node earns its transition round-trip | A node that always runs immediately after another, with no guard between them, is one node |
+
+**When a node breaches the budget, do not reformat to dodge the measure.** Joining five lines with
+`&&` moves the complexity, not the ownership. Pick an owner from the five recorded options in
+`docs/design/workflow-shell-ownership.md`: public `spur` verb (consent-gated), application service,
+least-privilege built-in action kind, workflow-relative external extension, or a recorded
+stays-shell exception with its reason in `config/workflow-composition-baseline.json`.
+
+**Advisory posture is binding.** Composition findings never block a run, never change a `validate`
+exit status, and are never a reason to hot-edit an executing pipeline. Surface them; fix on operator
+acceptance.
+
+---
+
+## 4. Refactor — moving across the boundary
+
+Three named directions. All three end in the shared
+[validate-and-dry-run core](operations.md#sub-procedure-validate-and-dry-run) when a YAML definition
+survives the change.
+
+### promote — descriptive procedure → workflow
+
+Use only when the [fit gate](#the-three-part-test) clears all three parts. Steps:
+
+1. **Split the prose into spine and judgment.** The spine is every step whose outcome is
+   machine-checkable. Everything else stays judgment and does *not* become a node's inline prompt.
+2. **Name the terminals** — the success terminal, and every failure terminal that deserves its own
+   name. Declare them in `failureStates`.
+3. **Run the [mode-selection gate](operations.md#sub-procedure-mode-selection-gate)** — the spine's
+   shape decides it: retry loop → state-machine; forward pipeline → transition-flow.
+4. **Author one node per spine step.** Each judgment step becomes an `agent.run` whose `input`
+   *references the existing slash command or skill* — never a copy of the prose. If no such command
+   exists, create it first; a promotion that inlines prompts has produced anti-pattern one.
+5. **Verify** with validate-and-dry-run against the expected terminal.
+6. **Rewrite the descriptive doc as the entry point** — it now explains the WHY and delegates to
+   `spur workflow run`, rather than restating the steps. Two copies of the procedure is the drift
+   the promotion was supposed to end.
+
+### demote — workflow → descriptive procedure
+
+Triggers (any two are sufficient; the first alone is sufficient):
+
+- Every node is an `agent.run` with a raw prompt and every edge is unconditional.
+- The definition has been edited more often than it has been run.
+- The graph is a straight line — no guard, no gate, no loop.
+- The run count over its lifetime is in the single digits and not growing.
+- Its `iterationBound` has never been reached because nothing ever loops.
+
+Steps:
+
+1. **Check for live dependents** — `spur workflow trace --workflow <name> --last 20 --json` for
+   recent runs, and grep the shipped surfaces for the filename. A definition another command invokes
+   is not demoted unilaterally.
+2. **Return each node's work to its owner** — judgment nodes to the command or skill they should
+   have been calling; a genuinely useful shell sequence to one script under its owning surface.
+3. **Rewrite the entry surface as the procedure**, in the order the graph ran.
+4. **Delete the YAML and its `config/workflow-composition-baseline.json` entries** in the same
+   change. A baseline entry whose action no longer exists fails the two-sided check.
+5. **Record the demotion** and its trigger, so the next author does not re-promote it by reflex.
+
+### optimize — refine an accepted workflow in place
+
+A [refine](operations.md#refine) whose `--intent` is latency or legibility rather than correctness.
+Dimensions, highest leverage first:
+
+1. **Remove or merge `agent.run` nodes** — the dominant cost, always the first pass.
+2. **Collapse probe-then-branch into a soft status-file probe** with ordered guards.
+3. **Reorder guards** cheapest-discriminating-first.
+4. **Lower `iterationBound`** to the observed maximum plus one.
+5. **Merge nodes that always run together** with no guard between them.
+6. **Move any `>= 6`-unit shell program to a recorded owner** (never by reformatting).
+7. **Rename states/nodes to outcomes** and add the missing `failureStates`.
+
+**Measure, do not estimate.** Capture `spur workflow trace <run-id> --json` before and after and
+compare wall-clock per state and the transition sequence. An optimization with no trace pair behind
+it is a preference. Rules that still bind: the smallest change that meets the intent, no mode
+switch inside a refine (that is a rewrite — hand it to `add`), and never edit a workflow that is
+currently executing.
+
+---
+
+## Checklist
+
+- [ ] Fit gate run **before** the mode gate; the prose-vs-workflow verdict stated with its reason.
+- [ ] All three of replay / branch / record hold, or the answer was a descriptive procedure.
+- [ ] Judgment steps reference an existing command; none inline a raw prompt.
+- [ ] `agent.run` node count is the minimum the branching requires.
+- [ ] `iterationBound` chosen from a latency budget; guards ordered cheapest-first.
+- [ ] States/nodes named for outcomes; `failureStates` declared; gates write a verdict file.
+- [ ] Every `shell` action within the <= 5-unit budget, or carrying a recorded owner/disposition.
+- [ ] Refactors verified through validate-and-dry-run; optimizations backed by a before/after trace.

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

@@ -9,12 +9,24 @@ see_also:
 
 `spur workflow` runs declarative YAML workflows (powered by `@gobing-ai/ts-dual-workflow-engine`) that
 orchestrate a multi-step process — an implement→check→fix loop, an import→validate→transform→write
-pipeline, an approval gate. The engine executes **two distinct workflow kinds**, and the first act of
-any new workflow is choosing between them. Get the mode right and the rest of authoring follows the
+pipeline, an approval gate. The engine executes **two distinct workflow kinds**, and choosing between
+them is the first act of *authoring*. Get the mode right and the rest of authoring follows the
 schema; get it wrong and you fight the engine.
 
-Operating a workflow well is a full lifecycle — choose the mode, author the YAML, validate it, run it,
-read the trace, and refine. This skill covers all of it.
+Operating a workflow well is a full lifecycle — decide it should be a workflow at all, choose the mode,
+author the YAML, validate it, run it, read the trace, tune it, and refine. This skill covers all of it.
+
+## Decide it is a workflow at all — before the mode
+
+The mode gate presumes the process belongs in YAML. That presumption is the more expensive one to get
+wrong: a workflow whose nodes are all raw `agent.run` prompts is a descriptive procedure paying a
+process spawn per step, and a bounded retry loop written as a paragraph in a skill reference is a
+workflow nobody authored. Run the **fit gate** first — a process earns a workflow only when it
+replays, branches on a machine-checkable predicate, **and** needs a durable per-run record.
+
+Fit gate, cost model, latency/observability tuning, the node simplicity budget, and the
+promote / demote / optimize refactor procedures:
+[workflows/workflow-fit-and-tuning.md](workflows/workflow-fit-and-tuning.md).
 
 ## Choose the execution mode first
 
@@ -62,6 +74,9 @@ before authoring. Full procedure: [workflows/authoring-workflows.md](workflows/a
 
 Use this skill to:
 
+- **Decide fit** — judge whether a process should be a workflow at all or stay a descriptive
+  procedure / checklist, and tune an accepted one for latency and legible traces.
+  → workflows/workflow-fit-and-tuning.md
 - **Author a workflow** — turn a described process into a validated, dry-run-verified YAML definition
   in the right mode. → authoring-workflows.md
 - **Validate before trusting** — schema + semantic-check a workflow file (references, terminal
@@ -70,6 +85,9 @@ Use this skill to:
   taken, terminal status).
 - **Refine an existing workflow** — fix a stuck guard, add a state/node, retune `iterationBound`,
   re-scope variables / `env.allow`, with the smallest change. → workflows/operations.md
+- **Refactor across the prose/YAML boundary** — promote a descriptive procedure into a workflow,
+  demote a workflow back to prose, or optimize an accepted one for latency.
+  → workflows/workflow-fit-and-tuning.md
 - **Extend the engine** — register a custom action/guard runner or a trust-gated extension module when
   the built-ins (`note`, `shell`, `always`, `action-ok`) fall short. → workflows/validation-and-extension.md
 
@@ -237,7 +255,7 @@ the operator accepts it, and never hot-edit a running workflow's shell in place.
 
 ```
 spur workflow validate <file> [--no-schema] [--json]
-spur workflow show      <file>
+spur workflow show      <file> [--format <mermaid|todo>] [--json]
 spur workflow run      <file> [--run-id <id>] [--vars <json>] [--dry-run] [--async] [--no-plan] [--quiet/--silent/--verbose] [--detail <level>] [--trace-file] [--no-log] [--steer] [--json]
 spur workflow continue [run-id] [--yes] [--answer <yes|no|cancel>] [--json]
 spur workflow cancel   <run-id> [--json]
@@ -362,6 +380,10 @@ the workflow's actions (`shell`, custom runners) do that; this skill builds and
 
 ## Additional Resources
 
+- [workflows/workflow-fit-and-tuning.md](workflows/workflow-fit-and-tuning.md) — the fit gate
+  (workflow vs. descriptive procedure), the per-node cost model, latency and observability tuning,
+  the node simplicity budget tied to the frozen ADR-069 measures, and the promote / demote /
+  optimize refactor procedures. Read before `add` and before any performance-motivated `refine`.
 - [workflows/operations.md](workflows/operations.md) — the operation procedures (validate/run/list/add/refine),
   the shared find-existing-workflow and validate-and-dry-run cores, and the mode-selection gate. The
   entry point for slash-command delegation.