diff --git a/README.md b/README.md index 82bde02..58408e2 100644 --- a/README.md +++ b/README.md @@ -60,7 +60,7 @@ Then run: Plugin skills are namespaced by the plugin that ships them, which is why the name doubles here — the plugin and the skill are both called `stackwich`. Bare `/stackwich` only resolves if you still have a pre-3.0 standalone copy installed, which the upgrade steps below tell you to remove. -The skill does the rest interactively: asks for scope, writes the policy, offers the three agents. Run `/agents` afterwards to confirm `advisor`, `executor`, and `verifier` are picked up. Re-running it on an existing install detects the marker and offers an in-place upgrade. +The skill does the rest interactively: asks for scope, writes the policy, offers the three agents. Claude Code protects `CLAUDE.md` and files outside your project, so expect permission prompts to write `CLAUDE.md`, to read the plugin's agent files, and to create the `agents/` folder — approve them, or the skill reports each step 4 check as FAIL and changes nothing. Run `/agents` afterwards to confirm `advisor`, `executor`, and `verifier` are picked up. Re-running it on an existing install detects the marker and offers an in-place upgrade. New to Stackwich? [Your first verified task](docs/first-task.md) walks from install to a verified fix on a small demo and back out again. To list what is installed at each level and any conflicts, run `python3 tools/diagnose.py` from your project. No browser or API tests in your project? [Acceptance-check recipes](docs/recipes.md) give the verifier something real to run. To bind a `GATE: PASS` to the exact files it tested, see [verification records](docs/verify-gate.md); to pick up interrupted work safely, see [handoffs](docs/handoff.md). To check what an install left behind, run `python3 tools/check_install.py ~/.claude` from a clone of this repository (or `./.claude` for a project-level install). It reads files only and reports each marker, revision, block, and agent check as PASS or FAIL. [docs/evals.md](docs/evals.md) explains these checks and the separate behavior evals. diff --git a/docs/first-task.md b/docs/first-task.md index a7b1b57..c10028c 100644 --- a/docs/first-task.md +++ b/docs/first-task.md @@ -8,12 +8,17 @@ it is not evidence that Stackwich improves results on real work. See [enforcement.md](enforcement.md) for what is mechanical and what depends on the model. The command output below is real, recorded on 2026-10-31 with Python 3.13. Temporary paths are -shortened. What Claude says in step 4 depends on the model and is described, not quoted. +shortened. What Claude says in step 4 depends on the model. On 2026-10-31 the walkthrough was run +end to end in Claude Code 2.1.316 against the published 3.4.0 plugin; step 4 summarises what that +session did. ## 1. Install and check -Install the plugin and run the skill, as in the [README](../README.md#install). Then clone this -repository somewhere outside your project and run the diagnostics from your project directory: +Install the plugin and run the skill, as in the [README](../README.md#install). Claude Code asks +permission before the skill writes `CLAUDE.md`, reads the plugin's agent files, and creates the +`agents/` folder; approve each prompt. If a write is refused, the skill changes nothing, reports +every step 4 check as FAIL, and tells you what to allow. Then clone this repository somewhere +outside your project and run the diagnostics from your project directory: ```bash git clone https://github.com/ovhirup/stackwich ~/stackwich-tools @@ -102,6 +107,11 @@ What to watch for: If the first attempt is wrong you will see the gate fail. That is the workflow working. Whether the gate is used at all depends on the model following the policy; nothing forces it. +In the recorded run, Claude read both files, made the one-line fix to `total()`, ran the tests, +and then handed the change to the `verifier` subagent. The verifier re-ran `python3 -m unittest` +itself, checked that only `cart.py` had changed, and ended its report with `GATE: PASS`. The final +report quoted the command and its output and counted one subagent, no forks, and no loops. + ## 5. Check the evidence yourself Do not take the report's word for it. Run the same command and read the diff: