@stdd/plugin 0.9.0

package/scripts/stdd-hook.mjs

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { resolveAdoptingRoot } from "./adopting-root.mjs";
+
+const PLUGIN_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const SESSION_RUNTIME_FAILURE =
+	"stdd plugin: bundled runtime failed — update the STDD plugin or re-run `stdd init`\n";
+
+const mode = process.argv[2];
+if (mode !== "session" && mode !== "stop" && mode !== "stop-claude") process.exit(0);
+
+let stopOutput = null;
+let exitCode = 0;
+try {
+	const root = resolveAdoptingRoot(process.cwd());
+	const cli = path.join(PLUGIN_ROOT, "runtime", "cli", "stdd.mjs");
+	if (root && fs.existsSync(cli)) {
+		const input = mode === "session" ? undefined : fs.readFileSync(0);
+		const args =
+			mode === "session"
+				? ["status", "--local"]
+				: ["stop-hook", "--agent", mode === "stop" ? "codex" : "claude"];
+		const run = spawnSync(process.execPath, [cli, ...args], {
+			cwd: root,
+			encoding: "utf8",
+			input,
+			timeout: 9000,
+		});
+		if (!run.error && run.status === 0) {
+			if (mode === "session") {
+				if (run.stdout) process.stdout.write(run.stdout);
+				if (run.stderr) process.stderr.write(run.stderr);
+			} else if (mode === "stop") {
+				const text = run.stdout.trim();
+				if (text !== "") {
+					try {
+						const parsed = JSON.parse(text);
+						const object = typeof parsed === "object" && parsed !== null && !Array.isArray(parsed);
+						const keys = object ? Object.keys(parsed) : [];
+						const valid =
+							object &&
+							(keys.length === 0 ||
+								(keys.length === 2 &&
+									keys.includes("decision") &&
+									keys.includes("reason") &&
+									parsed.decision === "block" &&
+									typeof parsed.reason === "string" &&
+									parsed.reason.trim().length > 0));
+						if (valid) stopOutput = JSON.stringify(parsed);
+					} catch {
+						// Malformed child output is an internal failure: allow Stop.
+					}
+				}
+			}
+		} else if (mode === "session") {
+			process.stderr.write(SESSION_RUNTIME_FAILURE);
+		} else if (mode === "stop-claude" && !run.error && run.status === 2 && run.stderr.trim() !== "") {
+			process.stderr.write(run.stderr);
+			exitCode = 2;
+		}
+	}
+} catch {
+	// A lifecycle integration must never trap or abort the host agent.
+}
+
+// Lifecycle helpers fail open. Codex Stop always receives valid JSON:
+// a verified block object, or {} to allow the turn to end.
+if (mode === "stop") console.log(stopOutput ?? "{}");
+process.exit(exitCode);

package/skills/stdd-brainstorming/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: stdd-brainstorming
+description: "Shape a fuzzy idea into an agreed behavior contract before any plan or code. Use when: A non-trivial change is requested and the requirements, scope, or approach are not yet pinned down."
+---
+
+<!-- generated by stdd plugin build v0.9.0 — do not edit -->
+
+
+# Brainstorming
+
+The goal is agreement on **what** and **why** before anyone invests in **how**.
+The output is not a document — it is a shared understanding that becomes a
+docs edit and a PR description.
+
+## Process
+
+1. **Understand the current state first.** Read the relevant docs and the code
+   the change will touch. Questions asked from ignorance waste the other
+   side's time; questions asked from knowledge sharpen the idea.
+2. **Ask one question at a time.** Prefer questions that eliminate whole
+   branches of the design space: who is it for, what triggers it, what must
+   never happen, what is explicitly out of scope. When the answer space is
+   enumerable, offer it as a closed choice with your recommendation first —
+   a closed question costs the other side seconds, an open one minutes.
+   Keep open questions for genuinely open design space.
+3. **Challenge scope creep in both directions.** If the idea is bigger than
+   the need, say so and propose the smaller version. If the stated need hides
+   a larger real problem, surface it.
+4. **Propose 2–3 approaches with a recommendation.** For each: one paragraph,
+   the trade-off that actually matters, and what it costs later. Recommend
+   one; do not present a menu without an opinion.
+5. **Converge on the behavior contract.** State the agreed behavior as rules
+   precise enough to test. Confirm them explicitly.
+
+## Output
+
+- The agreed rules become the **docs edit** (the spec) — the first commit of
+  the branch.
+- The rationale, rejected alternatives, and scope decisions go into the
+  **PR description** when the branch opens.
+- Nothing from this conversation is committed as a standalone file.
+
+## Anti-patterns
+
+- Jumping to implementation detail while behavior is still unsettled.
+- Asking multiple stacked questions at once.
+- Writing a "spec document" instead of editing the real docs.
+- Agreeing silently: if you disagree with the direction, say so with reasons.

package/skills/stdd-debugging/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: stdd-debugging
+description: "Find and fix the root cause of a defect, not its symptom. Use when: A bug, crash, failing test, or unexplained behavior is reported."
+---
+
+<!-- generated by stdd plugin build v0.9.0 — do not edit -->
+
+
+# Debugging
+
+The discipline: no edit before a reproduction, no fix before a diagnosis.
+
+## Process
+
+1. **Reproduce first.** Turn the report into a deterministic reproduction —
+   ideally a failing test. If you cannot reproduce it, you are not debugging
+   yet; you are gathering facts.
+2. **Read the actual error.** The full message, the stack, the logs around
+   it. Do not pattern-match a familiar-looking symptom to a known failure —
+   verify the evidence supports *this* cause.
+3. **Form one hypothesis and test it cheaply.** Predict what you will observe
+   if the hypothesis is true, then look. One hypothesis at a time; a change
+   made under two hypotheses proves neither.
+4. **Fix the root cause minimally.** The smallest change that removes the
+   cause. Resist drive-by cleanup — it obscures the fix in review.
+5. **Keep the reproduction as a regression test.** Red before the fix, green
+   after, committed with it.
+6. **Verify the fix in the original context**, not only in the reduced
+   reproduction.
+
+## Stop rules
+
+- Two failed fix attempts mean the diagnosis is wrong. Stop editing, go back
+  to step 2, and widen what you consider suspect — including your own
+  earlier changes and the test itself.
+- If the evidence contradicts the reported story, surface the contradiction
+  instead of forcing a fix that matches the story.
+- A fix you cannot explain is not a fix. Do not ship it.

package/skills/stdd-delegate-slice/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: stdd-delegate-slice
+description: "Hand a slice of work to a worker session with a declared scope, a ledger handoff, and a reviewed result. Use when: Before implementing a multi-step change whose steps are independent — hand slices to worker sessions (subagent, second CLI, teammate) instead of implementing everything inline; also whenever a worker's result comes back for review."
+---
+
+<!-- generated by stdd plugin build v0.9.0 — do not edit -->
+
+
+# Delegate a Slice
+
+Roles are fixed. The orchestrator owns the docs edit, the commits, and the
+PR. The worker owns red-green inside a declared scope. The handoff artifact
+is the ledger, not prose — a worker's chat summary does not survive
+compaction, its recorded events do.
+
+## Before the worker starts (orchestrator)
+
+1. Make the docs decision yourself and record it:
+   `stdd docs <decision> [paths…] [--reason <why>]`.
+2. Choose the worker boundary and declare the scope. Prefer a managed gitless
+   sandbox when the worker does not need Git authority:
+
+   ```bash
+   stdd worker create ../stdd-worker-billing \
+     --frozen "docs/**,migrations/**" \
+     --allowed "src/billing/**,test/billing/**"
+   ```
+
+   Use `stdd slice new --frozen ... --allowed ...` only when the worker must
+   operate in an existing isolated checkout. `--frozen` names globs the worker
+   must not touch. `--allowed` names the only paths it may change. At least one
+   is required. A managed sandbox contains no `.git`, ignored dependencies,
+   credentials, or build output; run the repository's readiness setup there.
+3. Write the brief **to a file** (session scratchpad, never the repo) and
+   point the worker at it — pasted context stays resident in your window
+   for the rest of the session; a file does not. Template:
+
+   > **Task**: <one sentence>
+   > **Spec**: read <canonical doc paths> — the docs edit is already made.
+   > **Scope**: declared by `stdd worker create` or `stdd slice new`; check
+   > yours with `stdd scope`.
+   > **Loop**: failing test first — record it with `stdd red -- <cmd>`;
+   > verify with `stdd verify -- <narrowest command>`.
+   > **Do not**: commit, push, or edit docs — the orchestrator owns those.
+   > **Policy**: copy the `stdd policy show` notes that govern this area —
+   > a worker reads the brief, not the repository's standing decisions.
+   > **Questions**: ask them now, before starting — not mid-slice.
+   > **Report**: write it to <file>; end with exactly one status:
+   > `DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT`.
+
+4. Name the worker's model explicitly in the dispatch — an omitted model
+   silently inherits the orchestrator's tier. Mechanical transcription
+   tolerates a cheap tier; judgment does not.
+
+## Parallel slices
+
+Serial dispatch is the default; parallelism is safe only when every
+precondition holds:
+
+- **Independence** — no consumes/produces edge between the steps: neither
+  slice uses a name the other produces.
+- **Isolation** — each worker runs in its own managed gitless sandbox or
+  worktree (see the worktrees playbook); two workers in one directory race on
+  files and test state.
+- **Disjoint scopes** — the slices' `--allowed` globs must not overlap;
+  an overlap forces serialization, it is never "probably fine".
+
+Dispatch the workers concurrently, then review results as they land —
+never hold finished work hostage to the slowest slice. Integration stays
+serial: merge one slice at a time into the orchestrator's checkout and
+re-run its verification after each merge, so a conflict names the slice
+that caused it.
+
+While workers run, the orchestrator works too: review a landed slice,
+prepare the next brief, draft the PR body from the ledger. Waiting idle
+on a single dispatched worker is the delegation anti-pattern — if there
+is truly nothing to do until the worker returns, the slice was too big.
+
+## While the worker runs (worker)
+
+- Ask blocking questions before the first edit, then run without
+  "should I continue?" pauses.
+- Record the red before implementing: `stdd red -- <cmd>` (a genuine test
+  failure, not an environment error — the recorder tells you which).
+- Record every meaningful verification: `stdd verify -- <cmd>`.
+- Leave handoff context in the file, not the chat: `stdd note <text>`.
+- End with one status. `BLOCKED` and `NEEDS_CONTEXT` are good outcomes:
+  bad work is worse than no work — escalating is never penalized.
+
+## After the worker finishes (orchestrator)
+
+1. Run `stdd scope` in the worker environment. For a managed sandbox, then run
+   `stdd worker collect <directory>` from the source checkout. Collection
+   fails before import on scope, identity, source-drift, or path conflicts and
+   never stages or commits. It imports worker red/verify/note evidence, but the
+   orchestrator still verifies the collected source checkout freshly.
+2. `stdd status` — confirm the loop is complete (docs, genuine red, passing
+   verify).
+3. **Review the diff, never the report alone.** The report is a claim, and
+   a stated rationale never downgrades a finding. Two verdicts, in order:
+   - *Spec compliance*: anything **missing** from the brief, anything
+     **extra** beyond it (unrequested work is a finding, not a bonus),
+     anything **misunderstood**.
+   - *Code quality* on what was built.
+
+   With subagents available, dispatch a fresh reviewer that sees the brief,
+   the diff, and the report — never your session history — and reviews
+   read-only.
+
+   Route the verdict through `stdd review` so it lands in the ledger
+   instead of evaporating with the chat.
+
+4. A `BLOCKED` or `NEEDS_CONTEXT` slice is not retried unchanged: add
+   context, split the slice, or take it inline.
+5. Assemble the PR body from the ledger, not from the worker's summary:
+   `stdd evidence` drafts the docs line from the recorded decision and the
+   diff. STDD never removes a managed sandbox automatically; delete it
+   explicitly only after reviewing the collected result.

package/skills/stdd-finish-change/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: stdd-finish-change
+description: "Close an implemented change with independent review, PR evidence, terminal CI, and runtime verification when required. Use when: Implementation is locally verified and the change is ready for review, delivery, or handoff."
+---
+
+<!-- generated by stdd plugin build v0.9.0 — do not edit -->
+
+
+# Finish change
+
+Close the current checkout in this order:
+
+1. Run the complete affected local verification.
+2. Finish every plan item and run the independent closing review when the
+   capability profile supports it.
+   `stdd review --via subagent` prints the brief path for a fresh read-only
+   subagent; feed its JSON back with `stdd review --result <file>`.
+3. Generate the PR evidence with `stdd evidence`; never hand-author a claim
+   contradicted by the diff.
+4. Open or update the PR/MR and wait for terminal checks. On GitHub use
+   `stdd ci --watch`; on another forge use its adapter's equivalent.
+5. If the change includes a deploy, migration, package publish, or other
+   runtime effect, verify that surface separately. Green CI is not runtime
+   proof.
+6. Run `stdd task finish` only after the requested delivery boundary is
+   actually complete.
+
+An `approved` verdict freezes the checkout. Anything you notice afterwards —
+a stale comment, a better name, one more edge case — is deferred with
+`stdd defer`, not edited in. Editing discards the approval rather than
+improving on it, and buys a round that found nothing. Past the review
+budget, `--force` needs `--reason <text>`: write what the extra round is
+expected to settle, not that the reviewer asked again.
+
+Do not merge, deploy, publish, or mutate an external system unless the user
+has authorized that action. A permission that `stdd policy show` reports is
+that authorization, but only once this session has verified the entry's
+condition and said what it verified; an unverifiable condition leaves the rule
+exactly as it stands. An entry the command lists as ignored grants nothing.
+

package/skills/stdd-implement/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: stdd-implement
+description: "Execute one agreed behavior slice through docs, genuine red, implementation, and fresh verification. Use when: The behavior contract is agreed and production changes are ready to begin."
+---
+
+<!-- generated by stdd plugin build v0.9.0 — do not edit -->
+
+
+# Implement
+
+Run one narrow vertical slice at a time:
+
+1. Record the docs decision with `stdd docs`. For changed behavior, edit the
+   canonical docs first and record `updated-first`.
+2. Add the smallest test that proves the agreed behavior. Run it through
+   `stdd red -- <command>` and confirm the failure is genuine.
+3. Implement only enough production code to satisfy that contract.
+4. Run the focused and affected verification through
+   `stdd verify -- <command>`.
+5. Check `stdd status --local`; a later checkout change makes verification
+   stale and requires another verify.
+
+Frontend visual composition follows the method's design-first exception.
+Behavior embedded in the UI still follows the loop.
+
+Do not batch unrelated rules behind one red. If the plan has multiple items,
+update its checkboxes only after their named evidence exists.
+

package/skills/stdd-investigation/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: stdd-investigation
+description: "Read-only diagnosis — evidence-backed findings, no changes. Use when: Asked to diagnose, triage, or explain behavior WITHOUT changing anything."
+---
+
+<!-- generated by stdd plugin build v0.9.0 — do not edit -->
+
+
+# Investigation
+
+The discipline: the deliverable is an evidence-backed diagnosis and an
+explicit list of blockers — never an edit. For the fix that may follow,
+switch to the debugging playbook; this one deliberately does not restate
+it.
+
+## Contract
+
+- No file edits, no state-changing side effects — reads only.
+- Every claim in the report is backed by evidence you actually observed,
+  or labeled as unverified with the blocker named.
+
+## Process
+
+1. **Inventory the evidence channels first.** Before forming any theory,
+   check what you can actually observe: forge CLI auth, container / DB /
+   log access, environment-key **presence** (never values). Report dead
+   channels as blockers immediately — do not silently work around a
+   channel you could not reach.
+2. **A hypothesis is not a diagnosis.** Test it against runtime signals —
+   logs, states, reproductions — before reporting it as a finding. What
+   you could not test, report as an explicitly unverified hypothesis with
+   the blocker that prevented the test.
+3. **Deliver the report**: the diagnosis (or ranked hypotheses) with its
+   evidence, the blockers, and the narrowest next step a fixing session
+   should take.

package/skills/stdd-planning/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: stdd-planning
+description: "Turn an agreed behavior contract into an executable, verifiable sequence of work. Use when: The behavior contract is agreed (docs edit drafted or committed) and the change is large enough to need ordered steps — before the first implementation edit, to fix the execution mode and delivery boundary."
+---
+
+<!-- generated by stdd plugin build v0.9.0 — do not edit -->
+
+
+# Planning
+
+A plan is a disposable working artifact: it guides one execution and is thrown
+away. It is never committed as a file — its home is the PR description (for
+the durable summary) and `.stdd/plan.md` (for the working copy: per checkout,
+gitignored, read by `stdd status`, survives compaction).
+
+Write the plan for an executor with zero context and questionable taste:
+exact file paths, exact names, exact commands. The planning session's
+memory does not survive delegation or compaction — whatever the plan does
+not say, the executor does not know.
+
+## Structure
+
+A good plan has, in order:
+
+1. **Intent** — one paragraph: the problem and the agreed direction.
+2. **Docs delta** — which permanent docs change and how (added / modified /
+   removed rules, named per target file). This is the spec surface of the
+   plan; keep it exact so the docs edit is mechanical.
+3. **Global constraints** — the agreement's project-wide requirements
+   (version floors, naming and copy rules, platform limits), one line
+   each, exact values verbatim. Every step implicitly includes this
+   section; a delegated worker gets it copied into the brief.
+4. **Steps** — each step small enough to verify independently, written as
+   checkboxes (`- [ ]`) so `stdd status` can report progress and the next
+   open item. Per step:
+   - what changes (files, functions);
+   - the failing test that gates it (or the visual check, for frontend
+     visual work — see the design-first exception in the method);
+   - the verification command;
+   - for a step that may be delegated: its interfaces — **consumes**
+     (exact signatures it uses from earlier steps) and **produces**
+     (exact names and types later steps rely on). A worker sees only its
+     own slice; this block is how a neighbor's names reach it.
+
+   Tag a step whose gate is a failing test with `[red: <substring of the
+   test command>]` — it then closes only when a matching genuine red is
+   recorded via `stdd red`, not when the box is ticked.
+
+   The last step of a multi-step plan is always the independent review
+   (see "The closing review"). Write it into the plan at planning time —
+   the plan must carry the trigger, not the session's memory.
+   Tag it `[review:]`: like `[red:]`, the tag closes only through the
+   ledger (an approved verdict recorded by `stdd review`), never by
+   ticking the box.
+5. **Out of scope** — what this change deliberately does not do.
+6. **Risks** — what could invalidate the plan and how you would notice.
+
+## Plan failures
+
+These patterns void a step — rewrite it before presenting the plan:
+
+- "TBD", "TODO", "fill in later", "details during implementation".
+- "Add appropriate error handling" / "handle edge cases" — name the cases.
+- "Write tests for the above" without naming the test and its assertion.
+- "Similar to step N" — repeat the exact names; steps are read in
+  isolation.
+- A check that names no runnable command — the visual-check exception
+  still names the command that brings the surface up.
+- A reference to a type, function, or file that neither the repository
+  nor any step defines.
+
+## Self-review before presenting
+
+Re-read the docs delta with fresh eyes and check the plan against it:
+
+1. **Coverage** — every agreed rule maps to a step; list any gap.
+2. **Plan-failure scan** — search the plan for the patterns above.
+3. **Name consistency** — signatures and names used by later steps match
+   where earlier steps define them.
+
+Fix findings inline and present once — a plan that survives this check
+gets approved in one round instead of three.
+
+## Rules
+
+- Order steps so the system stays green between them.
+- Write verification per step, not one "run all tests" at the end.
+- A step that cannot fail its check is not a step — merge it into another.
+- When execution contradicts the plan, update the plan, do not force the
+  plan onto reality. If the *intent* changed, stop and re-enter
+  brainstorming.
+- Keep the durable parts flowing to their homes as you go: rules → docs
+  edit, rationale → PR description. The plan itself must stay deletable at
+  any moment without information loss.
+- Surface plan-invalidating discoveries as one batched question, not one
+  interrupt per finding.
+- Cut scope explicitly: `stdd defer <text>` appends the cut to the plan's
+  `## Deferred` section. Deferred work is carried into the PR
+  description's out-of-scope, never silently dropped.
+
+## Executing
+
+Close planning with an explicit execution choice. When `stdd policy show`
+reports an execution-mode default, adopt it and state the choice instead of
+asking — the question exists to settle the mode, not to be asked twice.
+Otherwise ask it as a closed question to the user, your recommendation
+first. Template (recommend **inline** for
+tightly coupled steps, **delegated** for independent ones; lead with
+whichever you recommend):
+
+> Plan ready (N steps). How should it run?
+> 1. **Inline (recommended)** — this session implements the steps itself.
+> 2. **Delegated** — independent steps go to workers via delegate-slice;
+>    this session orchestrates and reviews.
+
+The modes differ only in who types: the loop and its recording stay
+identical. Delegation is a context optimization, never a requirement —
+it preserves the orchestrating session's window for coordination instead
+of burning it on implementation detail.
+Steps with no consumes/produces edge between them are candidates for
+parallel delegation — see "Parallel slices" in delegate-slice for the
+preconditions.
+
+Record the answer as a `Mode: inline|delegated` line at the top of the
+plan working copy — the plan carries the mode, not the session's memory,
+so the choice survives compaction.
+
+## The closing review
+
+Every multi-step plan ends the same way, inline or delegated: an
+independent review of the cumulative diff, before the evidence line and
+the PR. Independence means a fresh context — the reviewer sees the
+plan's intent, the docs delta, and the diff, never the implementing
+session's history. A self-review by the session that wrote the code is
+not independent: rationales in its own summary are the implementer
+grading their own work. Two verdicts, in order: spec compliance against
+the plan (missing / extra / misunderstood), then code quality on what
+was built.
+Use one of the route-specific commands below. Each invocation builds the brief
+(plan + diff + governing docs + the method's quality rubric + output
+contract), records the request, derives the verdict from the findings, and
+closes the `[review:]` item on approval. After `changes-requested`, fix the
+findings and repeat the same route-specific command; the newest verdict
+controls the item.
+`stdd review --via subagent` prints the brief path: hand it to a fresh
+read-only subagent, then feed its JSON back through
+`stdd review --result <file>`.
+
+## The final report
+
+When the plan is exhausted, report to the user —
+in their language, for a human deciding what happens next, not as a
+second copy of the ledger:
+
+1. **Outcome first** — one or two sentences: what shipped and what
+   proves it (tests and gate).
+   Include the independent review verdict in that proof.
+2. **Deviations from the plan** — deferred cuts, extra work, decisions
+   changed mid-flight. If there are none, say so in one line.
+3. **The technical trail last** — commands, file:line references,
+   round counts, for the reader who wants them.
+
+The machine record (findings JSON, ledger events, evidence line) already
+exists; the report earns its place only by being readable — plain
+sentences over verdict tables, terms spelled out over shorthand.

package/skills/stdd-pr-green/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: stdd-pr-green
+description: "A PR is done only when its required checks settle terminal-green on the current head. Use when: A PR/MR exists, or is about to be opened, for the current branch."
+---
+
+<!-- generated by stdd plugin build v0.9.0 — do not edit -->
+
+
+# PR Green
+
+The discipline: local verification governs the inner loop; the PR's required
+checks govern the definition of done. "CI started" and "pushed" are never
+done.
+
+## The one command
+
+Do not hand-roll pollers, sleeps, or `gh pr checks` loops:
+
+```bash
+stdd ci --watch        # current branch's PR; stdd ci <n> --watch for another
+```
+
+It resolves the PR, pins the watch to the PR's **current head**, refuses to
+settle until the check set is stable and fully terminal, restarts itself
+when the head moves (amend, force-push, new commit), and exits 0 only on
+terminal green — nonzero the moment a check fails terminally. On GitLab,
+`glab ci status --live` is the nearest equivalent; the recognition table
+below still applies.
+
+## Recognition table
+
+| You see | It means | Do |
+| --- | --- | --- |
+| Green summary seconds after a push, suspiciously few checks | The full check set has not registered yet | Trust only `stdd ci --watch` — it never settles on the first sighting of a set |
+| A failure attached to an older SHA | Stale result, not a red | Nothing — the watch is pinned to the current head |
+| `cancelled` on a superseded run | A concurrency twin, not a failure | Nothing to debug — `stdd ci` collapses same-named entries to the freshest run; re-run only if a ruleset still waits on that check |
+| A required check failed on the current head | A real red — it outranks everything else | Pull the failed job's log (the error, not the job name), reproduce locally with the narrowest matching command, fix the root cause, push, re-watch |
+| Checks green, but the change needs a deploy or migration to be observable | Green CI ≠ working | Verify the runtime surface the change touches before reporting done |
+| The watch times out with checks still pending | Runner starvation or a hung job | Read the run page; re-run or escalate — never report green |
+
+## After a real red
+
+A fix-commit without a re-watch repeats the original mistake: every push
+starts a new settlement, and only `stdd ci --watch` reaching terminal
+green closes it.
+
+## Before opening
+
+Run the local lanes that cover the surfaces the diff touches — not only the
+narrowest lane that proved the last edit. CI settlement stays the
+authoritative backstop; pre-running the entire CI matrix locally is not the
+goal.

package/skills/stdd-start-change/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: stdd-start-change
+description: "Classify a request, open durable task state only for changes, and route to the smallest applicable workflow. Use when: A new implementation, fix, refactor, investigation, or repository change is beginning."
+---
+
+<!-- generated by stdd plugin build v0.9.0 — do not edit -->
+
+
+# Start change
+
+Classify the request before writing task state:
+
+- read-only question or diagnosis → invoke `stdd-investigation`; do not start a
+  task or write the ledger;
+- uncertain behavior or scope → invoke `stdd-brainstorming`;
+- agreed multi-step behavior → invoke `stdd-planning`;
+- known defect without a diagnosis → invoke `stdd-debugging`;
+- small agreed change → invoke `stdd-implement` directly.
+
+Run `stdd policy show` before asking anything: it may already answer which
+agent owns this area, which standing permission covers the work, and what this
+repository treats as routine rather than a decision. Read it through the
+command, never as raw markdown — the command is where the rules are applied.
+
+For every route that may change the repository, open one task boundary before
+carrying state across prompts:
+
+```bash
+stdd task start "<short change name>"
+stdd status --local
+```
+
+If another task is active, do not reset it silently. Finish it, continue it,
+or ask the user which task owns the checkout.
+
+For a change, read `.stdd/method.md` and the canonical docs governing the
+touched behavior. The classification is a routing decision, not ceremony:
+skip workflows that do not apply, but never skip a mechanical contract that
+does.