@stdd/plugin 0.9.1 → 0.10.0

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.10.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.
+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.10.0 — 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.10.0 — do not edit -->
 
 
 # Delegate a Slice
@@ -21,11 +21,17 @@ compaction, its recorded events do.
    sandbox when the worker does not need Git authority:
 
    ```bash
-   stdd worker create ../stdd-worker-billing \
+   mkdir -p ../.stdd-workers
+   stdd worker create ../.stdd-workers/billing \
      --frozen "docs/**,migrations/**" \
      --allowed "src/billing/**,test/billing/**"
    ```
 
+   A sandbox cannot live inside the checkout or inside any Git repository, so
+   it goes beside the project — in one hidden container, not as a visible
+   sibling per slice. A directory of projects collects one `.stdd-workers/`
+   however many slices you delegate, and deleting it removes every sandbox.
+
    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

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

@@ -1,9 +1,9 @@
 ---
 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."
+description: "Close an implemented change with the review, PR evidence, terminal CI, and runtime verification its delivery boundary requires. 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.10.0 — do not edit -->
 
 
 # Finish change
@@ -11,8 +11,10 @@ description: "Close an implemented change with independent review, PR evidence,
 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.
+2. Finish every plan item. Run the independent closing review when the plan
+   carries a `[review:]` item or a slice was delegated, and the capability
+   profile supports it; a single slice makes no review claim and is not asked
+   for one.
    `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
@@ -25,6 +27,11 @@ Close the current checkout in this order:
 6. Run `stdd task finish` only after the requested delivery boundary is
    actually complete.
 
+Steps 3 and 4 apply when that delivery boundary is a PR. A change the user
+asked for as a local edit is complete after step 2 and closes at step 6 —
+opening a PR for it is work nobody requested. Step 5 is not a PR step: any
+delivery carrying a runtime effect gets that verification, PR or not.
+
 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

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.10.0 — 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.10.0 — 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

@@ -1,13 +1,17 @@
 ---
 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."
+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 more than one slice — a second independent outcome, an ordering dependency between parts, work to hand to another session, or an unresolved design decision — 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.10.0 — do not edit -->
 
 
 # Planning
 
+A single-slice change does not come here: it goes straight to
+`stdd-implement`. Planning starts when a second slice appears, which is
+usually mid-work rather than at classification time.
+
 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,

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.10.0 — 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.10.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.
+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,24 @@ 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 route. The default is one slice: invoke `stdd-implement` directly. A
+change is one slice when, at the moment of deciding, it has one agreed
+observable outcome, one coherent implementation boundary, one acceptance check,
+and no known dependency on another independently verifiable change.
+
+Escalate from that default only on a named trigger:
+
+- a second independent outcome or an ordering dependency between parts →
+  invoke `stdd-planning`;
+- work to hand to another session → invoke `stdd-planning`, then
+  `stdd-delegate-slice`;
+- a design decision nobody has made yet → invoke `stdd-brainstorming` within
+  the active change boundary;
+- a known defect without a diagnosis → invoke `stdd-debugging`.
+
+Any of them may appear mid-work. Escalating then is the normal case, not a
+failed classification.
+
+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.10.0 — do not edit -->
 
 
 # Isolated Workspaces

package/runtime/templates/github-stdd.yml

@@ -1,42 +0,0 @@
-# __STAMP__
-#
-# Validates the PR body fetched LIVE from the API, not the event payload —
-# the payload is frozen at trigger time, so a body-only edit would never be
-# re-checked. The `edited` trigger re-runs this workflow on body changes.
-name: STDD
-on:
-  pull_request:
-    types: [opened, edited, synchronize, reopened]
-
-permissions:
-  contents: read
-  pull-requests: read
-
-jobs:
-  stdd:
-    name: STDD Contract
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0 # check-pr --base diffs against the base ref
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 22
-      - name: stdd check
-        run: npx --yes @stdd/cli@__VERSION__ check .
-      - name: PR docs evidence (live body)
-        env:
-          GH_TOKEN: ${{ github.token }}
-          PR_NUMBER: ${{ github.event.pull_request.number }}
-        # node, not gh: node is already required for stdd, while self-hosted
-        # runners often lack the gh CLI. pipefail: a failed fetch must fail
-        # the gate as a fetch error, not feed check-pr an empty body.
-        run: |
-          set -o pipefail
-          node --input-type=module -e '
-            const url = "https://api.github.com/repos/" + process.env.GITHUB_REPOSITORY + "/pulls/" + process.env.PR_NUMBER;
-            const res = await fetch(url, { headers: { authorization: "Bearer " + process.env.GH_TOKEN, accept: "application/vnd.github+json" } });
-            if (!res.ok) { console.error("GitHub API " + res.status + " for " + url); process.exit(1); }
-            process.stdout.write((await res.json()).body ?? "");
-          ' | npx --yes @stdd/cli@__VERSION__ check-pr - --base "origin/$GITHUB_BASE_REF"

package/runtime/templates/gitlab-stdd.yml

@@ -1,72 +0,0 @@
-# __STAMP__
-#
-# Include this file from the repository's root .gitlab-ci.yml:
-#   include:
-#     - local: .gitlab/stdd.gitlab-ci.yml
-#
-# The job defaults to GitLab's reserved .pre stage, so this include stays valid
-# when a consumer defines custom stages without "test". To run STDD in an
-# existing consumer stage, override the included job in the root .gitlab-ci.yml.
-# The override must name a stage declared by that pipeline:
-#
-# stdd:
-#   stage: verify
-#
-# Same-project merge requests use CI_JOB_TOKEN. A fork pipeline runs in its
-# source project, so the target must allowlist that project under CI/CD job
-# token permissions. Only for a controlled, trusted source project, an
-# optional masked and hidden STDD_GITLAB_READ_API_TOKEN may carry a
-# target-project access token with read_api. Never expose a target token to
-# untrusted fork code.
-stdd:
-  stage: .pre
-  image: node:22
-  variables:
-    GIT_DEPTH: "0"
-  rules:
-    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
-  script:
-    - npx --yes @stdd/cli@__VERSION__ check .
-    - |
-      set -o pipefail
-      node --input-type=module -e '
-        const targetProjectId = process.env.CI_MERGE_REQUEST_PROJECT_ID;
-        const pipelineProjectId = process.env.CI_PROJECT_ID;
-        const crossProject = Boolean(
-          pipelineProjectId && targetProjectId && pipelineProjectId !== targetProjectId
-        );
-        const readApiToken = crossProject
-          ? process.env.STDD_GITLAB_READ_API_TOKEN
-          : "";
-        const headers = readApiToken
-          ? { "PRIVATE-TOKEN": readApiToken, accept: "application/json" }
-          : { "JOB-TOKEN": process.env.CI_JOB_TOKEN, accept: "application/json" };
-        const url = process.env.CI_API_V4_URL + "/projects/" +
-          encodeURIComponent(targetProjectId) + "/merge_requests/" +
-          process.env.CI_MERGE_REQUEST_IID;
-        const res = await fetch(url, { headers });
-        if (!res.ok) {
-          console.error("GitLab API " + res.status + " for " + url);
-          if (crossProject && !readApiToken) {
-            console.error(
-              "Fork or cross-project MR pipeline project " + pipelineProjectId +
-              " cannot read target project " + targetProjectId +
-              ". Add pipeline project " + pipelineProjectId +
-              " to the target CI/CD job token allowlist, or only for a trusted source project " +
-              "define masked and hidden STDD_GITLAB_READ_API_TOKEN with target-project read_api."
-            );
-          } else if (crossProject) {
-            console.error(
-              "STDD_GITLAB_READ_API_TOKEN cannot read target project " + targetProjectId +
-              "; verify that it is a target-project token with read_api."
-            );
-          } else {
-            console.error(
-              "The same-project CI_JOB_TOKEN cannot read this merge request; " +
-              "verify the triggering user and job-token permissions."
-            );
-          }
-          process.exit(1);
-        }
-        process.stdout.write((await res.json()).description ?? "");
-      ' | npx --yes @stdd/cli@__VERSION__ check-pr - --base "$CI_MERGE_REQUEST_DIFF_BASE_SHA"