@stdd/plugin 0.9.1 → 0.9.2

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "stdd",
-  "version": "0.9.1",
+  "version": "0.9.2",
   "description": "Native STDD workflow skills and lifecycle context",
   "author": {
     "name": "Azamat Almazbek uulu"

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "stdd",
-  "version": "0.9.1",
+  "version": "0.9.2",
   "description": "Native STDD workflow skills and lifecycle context for Codex",
   "author": {
     "name": "Azamat Almazbek uulu"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stdd/plugin",
-  "version": "0.9.1",
+  "version": "0.9.2",
   "description": "Universal STDD workflow skills and lifecycle integration for Codex, Claude Code, and Pi",
   "type": "module",
   "license": "MIT",

package/runtime/adapters/README.md

@@ -6,6 +6,15 @@ runs the adapters; re-run it after upgrading stdd to refresh the output.
 
 ## Common output
 
+Every host receives the same five-route always-on contract. Investigation
+answers current-state factual or diagnostic questions directly, Brainstorming
+explores opinions and future or hypothetical behavior directly, and only
+explicit intent to persist or modify the repository enters Start Change.
+Implement and Finish Change execute and close that action. Unknown current
+facts may cause Investigation → Brainstorming; ordinary docs or code reading
+inside Brainstorming does not. The renderer preserves host-native invocation
+syntax: Claude `/name`, Codex `$name`, and Pi `/skill:name`.
+
 Every init installs `.stdd/` into the target repo:
 
 ```
@@ -148,6 +157,10 @@ fail-open and never forward arbitrary child output.
 
 ## Design rules for adapters
 
+- The five direct/action routes are mandatory and stay semantically identical
+  across hosts; only their invocation syntax changes.
+- Idle lifecycle output is neutral: discussion and read-only work do not need a
+  task, and generated hooks do not prime agents to create one.
 - One source of truth: adapters copy or point, never fork playbook content.
 - Always-on instructions contain invariants and routing only; detailed
   workflows live in lazy skills.

package/runtime/cli/status.mjs

@@ -89,12 +89,12 @@ export function status(cwd, asJson, localOnly = false) {
 			plan: { present: false },
 			review: null,
 			pr: { state: "unknown", reason: "idle task" },
-			next: 'start a task with `stdd task start "<short name>"`',
+			next: "no task is required for discussion or read-only work",
 		};
 		if (asJson) console.log(JSON.stringify(idle, null, "\t"));
 		else
 			console.log(
-				`task:   idle on ${branch}\nnext:   start a task with \`stdd task start "<short name>"\``,
+				`task:   idle on ${branch}\nnext:   no task is required for discussion or read-only work`,
 			);
 		return;
 	}

package/runtime/method/README.md

@@ -220,10 +220,17 @@ Agent adapters have two outputs with deliberately different context costs:
 - a short, always-on instruction block carrying only repository invariants;
 - native, lazily loaded skills carrying the task workflows.
 
-Three routing skills make the main path explicit instead of asking an agent
-to infer a workflow from a flat list: `stdd-start-change` classifies first,
-opens a task only for repository-changing work, and routes read-only questions
-without writing state; `stdd-implement` runs the docs/red/green/verify loop, and
+Five routing skills make the main path explicit instead of asking an agent
+to infer a workflow from a flat list. `stdd-investigation` directly answers
+current-state factual and diagnostic questions with evidence;
+`stdd-brainstorming` directly explores opinions, future behavior, and
+hypothetical implementation approaches. Both are read-only and create no task,
+ledger event, persisted artifact, or repository mutation. When unknown current
+facts materially affect a design, they may run in sequence as Investigation →
+Brainstorming; reading docs or code while brainstorming does not itself switch
+workflows. `stdd-start-change` begins only after explicit intent to persist a
+work artifact or modify the repository; a hypothetical plan shown in chat stays
+Brainstorming. `stdd-implement` runs the docs/red/green/verify loop, and
 `stdd-finish-change` closes review, evidence, PR checks, and any requested
 runtime verification. Specialized playbooks remain independently invocable.
 
@@ -249,7 +256,9 @@ half-written state — see
 `stdd status --json` has one stable top-level shape in every lifecycle
 state: `state`, `task`, `branch`, `loop`, `slice`, `plan`, `review`, `pr`,
 and `next` are always present. Idle state uses explicit empty/null values,
-so integrations never need a second response schema.
+so integrations never need a second response schema. Its string-valued `next`
+is neutral: no task is required for discussion or read-only work, and a task
+starts only when the user chooses persisted or repository-changing action.
 
 Readers consider only the current branch's active task. A plan that was
 already present when the task started stays invisible until rewritten for

package/runtime/method/reference-integration.md

@@ -71,6 +71,15 @@ syntax when both hosts are selected. The append-system file is user-owned;
 init maintains only its marked STDD section and saves the generated source as
 `.stdd/PI-snippet.md`.
 
+Every host's managed instructions expose five mandatory routes in native
+syntax: Investigation and Brainstorming are direct read-only routes, Start
+Change is the explicit boundary for persisted or repository-changing action,
+and Implement and Finish Change execute and close that action. The router may
+sequence Investigation → Brainstorming only when unknown current facts
+materially affect future design. It never sends read-only work through Start
+Change or treats ordinary code and docs reading during Brainstorming as a
+separate Investigation.
+
 ## Adoption modes and the universal bundle
 
 STDD has three cumulative adoption modes. **Personal plugin** use installs the
@@ -144,10 +153,11 @@ and do not enumerate either kit or project skills. A local recipe that
 reuses a kit playbook's `name` replaces it: project knowledge outranks the kit.
 Local recipe names must otherwise be unique; init rejects duplicates before
 writing generated state and names both conflicting source files.
-The three skills named by that router (`stdd-start-change`, `stdd-implement`,
-and `stdd-finish-change`) are mandatory; init rejects a profile or local
-override that would make one inactive. Other inactive local overrides still
-shadow their kit playbook intentionally.
+The five skills named by that router (`stdd-investigation`,
+`stdd-brainstorming`, `stdd-start-change`, `stdd-implement`, and
+`stdd-finish-change`) are mandatory; init rejects a profile or local override
+that would make one inactive. Other inactive local overrides still shadow
+their kit playbook intentionally.
 
 ## CI adapters
 
@@ -222,8 +232,10 @@ re-init removes older managed Claude `PostCompact` entries to avoid running the
 ritual twice, while preserving unrelated user hooks. Each integration runs
 `stdd status --local`, which never calls a forge or the network, so every fresh
 context opens with local loop state and the next step already in it — recorded
-state instead of recall. Hook entries are merged into existing valid files
-without duplication. A conflicting Pi extension or invalid JSON settings are
+state instead of recall. When that state is idle, the injected human or JSON
+output is neutral: it says that discussion and read-only work require no task
+instead of prompting task creation. Hook entries are merged into existing valid
+files without duplication. A conflicting Pi extension or invalid JSON settings are
 left untouched and a manual instruction is printed instead. Codex hooks and
 Pi project extensions remain subject to their host's repository trust review.
 

package/runtime/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@stdd/cli",
-	"version": "0.9.1",
+	"version": "0.9.2",
 	"description": "Spec + Test Driven Development — a markdown-first methodology kit for teams building software with AI coding agents",
 	"type": "module",
 	"exports": {

package/runtime/playbooks/brainstorming.md

@@ -1,46 +1,65 @@
 ---
 name: stdd-brainstorming
-description: Shape a fuzzy idea into an agreed behavior contract before any plan or code
-when: A non-trivial change is requested and the requirements, scope, or approach are not yet pinned down.
+description: Explore future behavior and hypothetical approaches without forcing action
+when: Asked for opinions, ideation, future behavior, or a hypothetical implementation approach, with no explicit intent to persist or modify the repository.
 ---
 
 # 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.
+Use Brainstorming as an adaptive conversational stance, not a fixed interview.
+The goal is useful clarity about **what** and **why** before anyone commits to
+action. Clarity, deciding not to act, and continuing later are all successful
+outcomes.
+
+## Contract
+
+- Stay read-only: create no task, ledger event, persisted artifact, or
+  repository mutation.
+- Ground the discussion in current docs or code when materially useful. If
+  unknown current facts materially affect the design, invoke
+  `stdd-investigation` first; ordinary reading here is not Investigation.
+- A hypothetical plan shown in chat remains Brainstorming. Explicit intent to
+  persist an artifact or modify the repository crosses into Start Change when
+  no action boundary is active. Within an active change, do not invoke Start
+  Change again; proceed to Planning or Implement as the agreed action requires.
+
+## Conversation
+
+1. **Understand the real need.** Let the user provide context in their own
+   shape. Challenge assumptions and decompose ideas that are larger than the
+   need; apply YAGNI rather than rewarding scope.
+2. **Ask only decision-bearing questions.** Ask at most one per turn, and only
+   when its answer is needed to proceed. Prefer a concise closed choice when
+   the answer space is known. Use a question batch only when the user requests
+   one.
+3. **Offer useful alternatives.** Once context is sufficient, present two or
+   three materially distinct approaches, state the trade-off that matters, and
+   lead with a recommendation. Do not manufacture alternatives when only one
+   approach is sensible.
+4. **Validate incrementally.** Check substantive decisions as they emerge
+   instead of withholding all validation for a final ceremony. An optional
+   recap may state the problem, preferred approach, and unresolved questions.
+
+## Outcomes
+
+Follow the user's intent without forcing a three-option menu:
+
+- **No action:** summarize if useful, then stop. Do not pressure the user to
+  formalize or implement anything.
+- **Defer:** leave a portable backlog note in chat. Persist it only when the
+  user explicitly chooses a destination; if no action boundary is active,
+  invoke `stdd-start-change` before writing it.
+- **Act now:** when the user explicitly chooses persisted or
+  repository-changing action, invoke `stdd-start-change` if no action boundary
+  is active. Within an active change, proceed directly to Planning or Implement
+  as appropriate.
 
 ## 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.
+- Turning exploration into a mandatory interview or checklist.
+- Asking stacked questions when one decision would unlock progress.
+- Jumping into code or artifact creation without explicit action intent.
+- Treating every conversation as a change that must converge on docs, a plan,
+  or a PR.
+- Presenting options without an opinion, or inventing options to satisfy a
+  quota.

package/runtime/playbooks/investigation.md

@@ -1,7 +1,7 @@
 ---
 name: stdd-investigation
-description: Read-only diagnosis — evidence-backed findings, no changes
-when: Asked to diagnose, triage, or explain behavior WITHOUT changing anything.
+description: Read-only current-state diagnosis — evidence-backed findings, no changes
+when: Asked a factual question about current behavior, or to diagnose or triage it, WITHOUT changing anything.
 ---
 
 # Investigation
@@ -13,9 +13,12 @@ it.
 
 ## Contract
 
-- No file edits, no state-changing side effects — reads only.
+- No task, ledger event, persisted artifact, file edit, or state-changing side
+  effect — reads only.
 - Every claim in the report is backed by evidence you actually observed,
   or labeled as unverified with the blocker named.
+- Opinions, future behavior, and hypothetical implementation approaches belong
+  in Brainstorming, not Investigation.
 
 ## Process
 
@@ -29,5 +32,8 @@ it.
    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.
+   evidence, the blockers, and the narrowest useful next step.
+4. **Hand off only when the prompt needs design.** If unknown current facts
+   materially affect requested future behavior, finish the factual diagnosis
+   and then invoke `stdd-brainstorming`. Merely reading docs or code during
+   Brainstorming does not require a separate Investigation.

package/runtime/playbooks/start-change.md

@@ -1,27 +1,24 @@
 ---
 name: stdd-start-change
-description: Classify a request, open durable task state only for changes, and route to the smallest applicable workflow
-when: A new implementation, fix, refactor, investigation, or repository change is beginning.
+description: Open durable task state and route work after explicit intent to persist or modify the repository
+when: The user explicitly wants a persisted work artifact or repository change.
 ---
 
 # 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.
+Start Change is the action boundary. Invoke it only after explicit intent to
+persist a work artifact or modify the repository. Read-only factual diagnosis
+routes directly to `stdd-investigation`; opinions, future behavior, and
+hypothetical implementation approaches route directly to `stdd-brainstorming`.
+Neither needs a task. A hypothetical plan shown only in chat remains
+Brainstorming.
 
 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:
+Open one task boundary before carrying action state across prompts:
 
 ```bash
 stdd task start "<short change name>"
@@ -31,7 +28,14 @@ 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.
+Then classify the chosen action and route to the smallest applicable workflow:
+
+- behavior or scope is still uncertain → invoke `stdd-brainstorming` within
+  the active change boundary;
+- agreed multi-step behavior → invoke `stdd-planning`;
+- known defect without a diagnosis → invoke `stdd-debugging`;
+- small agreed change → invoke `stdd-implement` directly.
+
+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.

package/runtime/sdk/adapters.mjs

@@ -17,6 +17,8 @@ const deepFreeze = (value) => {
 };
 
 export const MANDATORY_ROUTING_SKILLS = deepFreeze([
+	"stdd-investigation",
+	"stdd-brainstorming",
 	"stdd-start-change",
 	"stdd-implement",
 	"stdd-finish-change",
@@ -212,16 +214,27 @@ export function renderAgentInstructions({
 		throw new TypeError("agent instructions projectLogEnabled must be a boolean");
 	}
 	const invoke = (name) => `\`${adapter.explicitPrefix}${name}\``;
-	const [startChange, implement, finishChange] = MANDATORY_ROUTING_SKILLS;
+	const [investigation, brainstorming, startChange, implement, finishChange] = MANDATORY_ROUTING_SKILLS;
 	return [
 		`<!-- ${safeStamp} -->`,
 		"",
 		"## STDD",
 		"",
-		"This repository follows `.stdd/method.md`. Before any repository change",
-		"(behavior, implementation-only work, fixes, refactors, or investigation),",
-		`invoke ${invoke(startChange)}; use ${invoke(implement)} for`,
-		`the docs/red/green/verify slice and ${invoke(finishChange)} to close it.`,
+		"This repository follows `.stdd/method.md`. Route read-only current-state",
+		`factual or diagnostic questions directly to Investigation with ${invoke(investigation)}.`,
+		"Route opinions, future behavior, and hypothetical implementation approaches",
+		`directly to Brainstorming with ${invoke(brainstorming)}.`,
+		"",
+		"Use Investigation → Brainstorming only when unknown current facts materially affect future design.",
+		"Reading docs or code during Brainstorming does not by itself require Investigation.",
+		"",
+		"Start Change is the action boundary. Invoke it only after explicit intent to",
+		`persist a work artifact or modify the repository, using ${invoke(startChange)}.`,
+		"A hypothetical plan shown only in chat remains Brainstorming.",
+		"",
+		"Before any repository change (behavior, implementation-only work, fixes, or",
+		`refactors), invoke ${invoke(startChange)}; use ${invoke(implement)} for the`,
+		`docs/red/green/verify slice and ${invoke(finishChange)} to close it.`,
 		"",
 		...(projectLogEnabled
 			? [

package/skills/stdd-brainstorming/SKILL.md

@@ -1,48 +1,67 @@
 ---
 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."
+description: "Explore future behavior and hypothetical approaches without forcing action. Use when: Asked for opinions, ideation, future behavior, or a hypothetical implementation approach, with no explicit intent to persist or modify the repository."
 ---
 
-<!-- generated by stdd plugin build v0.9.1 — do not edit -->
+<!-- generated by stdd plugin build v0.9.2 — 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.
+Use Brainstorming as an adaptive conversational stance, not a fixed interview.
+The goal is useful clarity about **what** and **why** before anyone commits to
+action. Clarity, deciding not to act, and continuing later are all successful
+outcomes.
+
+## Contract
+
+- Stay read-only: create no task, ledger event, persisted artifact, or
+  repository mutation.
+- Ground the discussion in current docs or code when materially useful. If
+  unknown current facts materially affect the design, invoke
+  `stdd-investigation` first; ordinary reading here is not Investigation.
+- A hypothetical plan shown in chat remains Brainstorming. Explicit intent to
+  persist an artifact or modify the repository crosses into Start Change when
+  no action boundary is active. Within an active change, do not invoke Start
+  Change again; proceed to Planning or Implement as the agreed action requires.
+
+## Conversation
+
+1. **Understand the real need.** Let the user provide context in their own
+   shape. Challenge assumptions and decompose ideas that are larger than the
+   need; apply YAGNI rather than rewarding scope.
+2. **Ask only decision-bearing questions.** Ask at most one per turn, and only
+   when its answer is needed to proceed. Prefer a concise closed choice when
+   the answer space is known. Use a question batch only when the user requests
+   one.
+3. **Offer useful alternatives.** Once context is sufficient, present two or
+   three materially distinct approaches, state the trade-off that matters, and
+   lead with a recommendation. Do not manufacture alternatives when only one
+   approach is sensible.
+4. **Validate incrementally.** Check substantive decisions as they emerge
+   instead of withholding all validation for a final ceremony. An optional
+   recap may state the problem, preferred approach, and unresolved questions.
+
+## Outcomes
+
+Follow the user's intent without forcing a three-option menu:
+
+- **No action:** summarize if useful, then stop. Do not pressure the user to
+  formalize or implement anything.
+- **Defer:** leave a portable backlog note in chat. Persist it only when the
+  user explicitly chooses a destination; if no action boundary is active,
+  invoke `stdd-start-change` before writing it.
+- **Act now:** when the user explicitly chooses persisted or
+  repository-changing action, invoke `stdd-start-change` if no action boundary
+  is active. Within an active change, proceed directly to Planning or Implement
+  as appropriate.
 
 ## 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.
+- Turning exploration into a mandatory interview or checklist.
+- Asking stacked questions when one decision would unlock progress.
+- Jumping into code or artifact creation without explicit action intent.
+- Treating every conversation as a change that must converge on docs, a plan,
+  or a PR.
+- Presenting options without an opinion, or inventing options to satisfy a
+  quota.

package/skills/stdd-debugging/SKILL.md

@@ -3,7 +3,7 @@ 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.1 — do not edit -->
+<!-- generated by stdd plugin build v0.9.2 — do not edit -->
 
 
 # Debugging

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

@@ -3,7 +3,7 @@ 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.1 — do not edit -->
+<!-- generated by stdd plugin build v0.9.2 — do not edit -->
 
 
 # Delegate a Slice

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

@@ -3,7 +3,7 @@ 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.1 — do not edit -->
+<!-- generated by stdd plugin build v0.9.2 — do not edit -->
 
 
 # Finish change

package/skills/stdd-implement/SKILL.md

@@ -3,7 +3,7 @@ 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.1 — do not edit -->
+<!-- generated by stdd plugin build v0.9.2 — do not edit -->
 
 
 # Implement

package/skills/stdd-investigation/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: stdd-investigation
-description: "Read-only diagnosis — evidence-backed findings, no changes. Use when: Asked to diagnose, triage, or explain behavior WITHOUT changing anything."
+description: "Read-only current-state diagnosis — evidence-backed findings, no changes. Use when: Asked a factual question about current behavior, or to diagnose or triage it, WITHOUT changing anything."
 ---
 
-<!-- generated by stdd plugin build v0.9.1 — do not edit -->
+<!-- generated by stdd plugin build v0.9.2 — do not edit -->
 
 
 # Investigation
@@ -15,9 +15,12 @@ it.
 
 ## Contract
 
-- No file edits, no state-changing side effects — reads only.
+- No task, ledger event, persisted artifact, file edit, or state-changing side
+  effect — reads only.
 - Every claim in the report is backed by evidence you actually observed,
   or labeled as unverified with the blocker named.
+- Opinions, future behavior, and hypothetical implementation approaches belong
+  in Brainstorming, not Investigation.
 
 ## Process
 
@@ -31,5 +34,8 @@ it.
    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.
+   evidence, the blockers, and the narrowest useful next step.
+4. **Hand off only when the prompt needs design.** If unknown current facts
+   materially affect requested future behavior, finish the factual diagnosis
+   and then invoke `stdd-brainstorming`. Merely reading docs or code during
+   Brainstorming does not require a separate Investigation.

package/skills/stdd-planning/SKILL.md

@@ -3,7 +3,7 @@ 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.1 — do not edit -->
+<!-- generated by stdd plugin build v0.9.2 — do not edit -->
 
 
 # Planning

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

@@ -3,7 +3,7 @@ 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.1 — do not edit -->
+<!-- generated by stdd plugin build v0.9.2 — do not edit -->
 
 
 # PR Green

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

@@ -1,29 +1,26 @@
 ---
 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."
+description: "Open durable task state and route work after explicit intent to persist or modify the repository. Use when: The user explicitly wants a persisted work artifact or repository change."
 ---
 
-<!-- generated by stdd plugin build v0.9.1 — do not edit -->
+<!-- generated by stdd plugin build v0.9.2 — 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.
+Start Change is the action boundary. Invoke it only after explicit intent to
+persist a work artifact or modify the repository. Read-only factual diagnosis
+routes directly to `stdd-investigation`; opinions, future behavior, and
+hypothetical implementation approaches route directly to `stdd-brainstorming`.
+Neither needs a task. A hypothetical plan shown only in chat remains
+Brainstorming.
 
 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:
+Open one task boundary before carrying action state across prompts:
 
 ```bash
 stdd task start "<short change name>"
@@ -33,7 +30,14 @@ 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.
+Then classify the chosen action and route to the smallest applicable workflow:
+
+- behavior or scope is still uncertain → invoke `stdd-brainstorming` within
+  the active change boundary;
+- agreed multi-step behavior → invoke `stdd-planning`;
+- known defect without a diagnosis → invoke `stdd-debugging`;
+- small agreed change → invoke `stdd-implement` directly.
+
+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.

package/skills/stdd-worktrees/SKILL.md

@@ -3,7 +3,7 @@ name: stdd-worktrees
 description: "Work in an isolated workspace without fighting the platform's native isolation. Use when: Starting implementation work that should not disturb the user's current checkout."
 ---
 
-<!-- generated by stdd plugin build v0.9.1 — do not edit -->
+<!-- generated by stdd plugin build v0.9.2 — do not edit -->
 
 
 # Isolated Workspaces