From b6059fdfb273e2651b25d05ae0a0cf5226cd3a96 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 31 Oct 2026 07:37:22 +0000 Subject: [PATCH] Warn about install permission prompts, from a real walkthrough run docs/first-task.md was run end to end in Claude Code 2.1.316 against the published 3.4.0 plugin. Installing from GitHub, the gated fix with the verifier subagent, and the uninstall all behaved as documented. The one gap: Claude Code asks permission before the skill writes CLAUDE.md, reads the plugin's agent files, and creates agents/, and a refused write leaves the install undone. README and the walkthrough now say so, and the walkthrough summarises what the recorded step 4 session did. Fixes #11 Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01TgCNfzRULZvxaP1GfyqzRe --- README.md | 2 +- docs/first-task.md | 16 +++++++++++++--- 2 files changed, 14 insertions(+), 4 deletions(-) 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: