diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml index a2c24db..13e85d0 100644 --- a/.github/workflows/validate.yml +++ b/.github/workflows/validate.yml @@ -194,6 +194,14 @@ jobs: cd measured && python3 -m unittest -v test_measured python3 approve.py --self-check + - name: Policy block within its word budget + run: | + BUDGET=735 + W=$(awk '/^$/,/^$/' plugins/stackwich/skills/stackwich/SKILL.md | wc -w) + [ "$W" -gt 0 ] || { echo "::error::no policy block found to measure"; exit 1; } + [ "$W" -le "$BUDGET" ] || { echo "::error::policy block is $W words, over its $BUDGET-word budget — it is read on every turn, so cut before adding"; exit 1; } + echo "policy block: $W of $BUDGET words OK" + recipes: name: Acceptance-check recipes runs-on: ubuntu-latest diff --git a/CHANGELOG.md b/CHANGELOG.md index 531e945..0991c6b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,31 @@ Headings are `## — `. Ports are named in the body with their own rev counters: a port tracks the parent's layer structure, not its revision number. +## 3.5.0 — policy-rev 8: a leaner policy with one failure ladder + +The Claude Code policy changes, so `policy-rev` moves from 7 to 8: re-run `/stackwich:stackwich` +to apply it in place. The `` marker is unchanged. `executor.md` changed too: +agents scaffolded before this release keep the older file, so accept the scaffolding again to +pick it up. + +### Policy +- One failure ladder replaces the 2-cycle cap and the two-strike rule, which overlapped. A first + `GATE: FAIL` or `REVISE:` goes back to `executor`; a second goes to `advisor` to re-plan; a + third stops and goes to the user. The count never resets. (#39) +- Read-heavy scans go to a fork, never to `executor`, which only writes. `executor.md`'s + description no longer offers scans. (#40) +- The block is 700 words, down from 952, and is read on every turn. Removed: the + memory/plans/tasks bullet and "don't re-read a file you just wrote", which restate Claude Code's + own behavior; the separate "consult `advisor` before" bullet, merged into the mandatory-sandwich + rule with the same triggers. The handoff rule now keeps `.stackwich/` out of git. (#41) +- CI fails if the block grows past a 735-word budget. + +### Ports +- Codex moves to `stackwich-codex-rev 6` (failure ladder; scans never go to `executor`) and Grok + to `stackwich-grok-rev 5` (failure ladder as EXECUTE, then PLAN, then the user). Their other + bullets are unchanged: the cuts above rely on Claude Code's own behavior, which the ports' + runtimes may not share. + ## 3.4.0 — policy-rev 7: resume interrupted work safely The Claude Code policy changes, so `policy-rev` moves from 6 to 7: re-run `/stackwich:stackwich` diff --git a/README.md b/README.md index 58408e2..b41491b 100644 --- a/README.md +++ b/README.md @@ -19,9 +19,9 @@ Stackwich is 15 years of delivery coaching — plan → build → test → revie | Layer | Habit | |---|---| | **Prompt** | Meta-prompt every delegation. Context-full, with a stated done condition. Understanding never gets delegated. | -| **Context** | Fork research and read-heavy scans off the main thread. Memory, plans, and tasks each do their own job. | +| **Context** | Fork research and read-heavy scans off the main thread, never to the writer. Interrupted work resumes from a handoff. | | **Harness** | One writer. Read-only roles stay read-only in practice, not just in the tool list. Nothing "done" until observed. | -| **Loop** | Recurring work runs on `/loop`. Failure loops are capped at 2 cycles and never silent. | +| **Loop** | Recurring work runs on `/loop`. Failures climb one ladder — retry, re-plan, then stop — and are never silent. | | **Graph** | `advisor` plans → `executor` implements → `verifier` gates → `advisor` reviews, with explicit hand-off contracts. | Cost discipline isn't a sixth layer — it's how the five are practiced: cheap models grind, expensive models only plan and review, and nothing already established gets re-derived. @@ -83,12 +83,12 @@ Four numbers move independently. Only the policy revisions change what an instal | Number | Current | Where it lives | When you act | |---|---|---|---| -| Repository and plugin version | 3.4.0 | `plugin.json`, git tags `vX.Y.Z`, [CHANGELOG](CHANGELOG.md) headings | Update the plugin. | -| Claude Code policy revision | `policy-rev 7` | The comment inside the `` block in your `CLAUDE.md` | Re-run `/stackwich:stackwich` when it changes. | -| Grok port revision | `stackwich-grok-rev 4` | Inside the block the Grok port writes | Re-apply the Grok port when it changes. | -| Codex port revision | `stackwich-codex-rev 5` | Inside the `` block in `AGENTS.md` | Re-apply the Codex port when it changes. | +| Repository and plugin version | 3.5.0 | `plugin.json`, git tags `vX.Y.Z`, [CHANGELOG](CHANGELOG.md) headings | Update the plugin. | +| Claude Code policy revision | `policy-rev 8` | The comment inside the `` block in your `CLAUDE.md` | Re-run `/stackwich:stackwich` when it changes. | +| Grok port revision | `stackwich-grok-rev 5` | Inside the block the Grok port writes | Re-apply the Grok port when it changes. | +| Codex port revision | `stackwich-codex-rev 6` | Inside the `` block in `AGENTS.md` | Re-apply the Codex port when it changes. | -A repository release can leave every policy revision unchanged; 3.2.0 did, while 3.3.0 and 3.4.0 each moved all three. Each CHANGELOG entry says whether there is anything to re-run. The markers themselves never change. +A repository release can leave every policy revision unchanged; 3.2.0 did, while 3.3.0, 3.4.0 and 3.5.0 each moved all three. Each CHANGELOG entry says whether there is anything to re-run. The markers themselves never change. ### Older copies @@ -111,7 +111,7 @@ A repository release can leave every policy revision unchanged; 3.2.0 did, while **Single writer.** Only `executor` mutates the filesystem. `advisor` and `verifier` have no edit tools, and their `Bash` is for inspection and verification, scoped away from writes by instruction — a fix from a reviewer is an unreviewed change nobody knows exists. The tool list is enforced by Claude Code; the `Bash` boundary depends on the model following it. Tests and builds the verifier runs can still create caches and build output; what read-only protects is product source and external state. See [docs/enforcement.md](docs/enforcement.md). -**Loops are capped.** `GATE: FAIL` and `REVISE:` both route back to `executor` with the original plan attached, for at most 2 cycles. On the third, it stops and surfaces everything to the human. Verdict lines are fixed strings so routing doesn't depend on interpreting prose; the main session still does the routing, and the cap is instructed, not counted by a tool. +**Loops are capped.** A first `GATE: FAIL` or `REVISE:` goes back to `executor` with the original plan attached; a second goes to `advisor` to re-plan from what was tried; a third stops and surfaces everything to the human. The count never resets. Verdict lines are fixed strings so routing doesn't depend on interpreting prose; the main session still does the routing, and the cap is instructed, not counted by a tool. **Input contracts are explicit.** Each agent states what it must receive and is instructed to stop when a piece is missing rather than reconstruct it — a reviewer that rebuilds the plan from the diff reviews the change against itself and approves anything self-consistent. diff --git a/codex/README.md b/codex/README.md index c770ad1..cb30e23 100644 --- a/codex/README.md +++ b/codex/README.md @@ -17,7 +17,8 @@ Stackwich installs five layers into Codex sessions: 4. **Loop** — schedule recurring work; failure cycles are capped, never silent 5. **Graph** — PLAN → EXECUTE → VERIFY → REVIEW for anything risky -It also instructs the two-strike rule (same failure twice → stop and escalate), verification +It also instructs a failure ladder (first failure → retry, second → `advisor` re-plans, third → +stop and ask you), verification by behavior rather than re-reading a just-written file, and no suffixed file copies as a debugging strategy. @@ -68,7 +69,7 @@ scaffold `advisor`, `executor`, and `verifier` as TOML agents. > insert a duplicate block. > **Port status:** at parity with the Claude Code parent's five-layer policy, as -> `stackwich-codex-rev 5`. The port tracks the parent's layer structure, not its revision +> `stackwich-codex-rev 6`. The port tracks the parent's layer structure, not its revision > number — a parent bump does not automatically oblige a port bump. --- diff --git a/codex/SKILL.md b/codex/SKILL.md index 58cdc6a..2a5b629 100644 --- a/codex/SKILL.md +++ b/codex/SKILL.md @@ -70,9 +70,8 @@ accounts and future model catalogs. - Verify behavior or structure rather than re-reading a just-written file solely to confirm that the write occurred. -Fix validation failures before reporting success. Apply the two-strike rule to repeated -verification failures: after the same failure occurs twice, stop blind retries and report the -evidence. +Fix validation failures before reporting success. If the same validation failure occurs twice, +stop blind retries and report the evidence. ## 6. Report the result diff --git a/codex/references/templates.md b/codex/references/templates.md index 2a3ae9c..d4823b4 100644 --- a/codex/references/templates.md +++ b/codex/references/templates.md @@ -7,7 +7,7 @@ credit in every custom-agent file. ```markdown - + ## Working Architecture (Stackwich Codex) ### Prompt @@ -59,21 +59,22 @@ credit in every custom-agent file. - Before creating a scheduled automation or any repeating run, state its stop condition and a maximum run count; if either is missing, ask the user instead of starting. A repeating run with no change for 3 consecutive runs stops and reports (unless the user set another number). -- Failure routing, with hard stops: - - `GATE: FAIL` -> return the failure output to `executor` together with the original plan. - - `REVISE: ...` -> return the numbered list to `executor` together with the original plan. - - Either path is capped at 2 cycles. On the third, stop and bring the user the plan, what was - tried, and the outstanding gate or review output. Never loop silently. +- Failure ladder for `GATE: FAIL` or `REVISE: ...` on the same change; the count never resets: + 1. First failure -> return the failure output or numbered list to `executor` together with + the original plan. + 2. Second -> `advisor` re-plans from the plan, the commands, outputs, and attempted fixes; + `executor` applies the new plan. + 3. Third -> stop and bring the user the plan, what was tried, and the outstanding gate or + review output. + Never loop silently, and never create a suffixed copy of a real file to debug around a + failure. - Distinguish an infrastructure failure, such as a missing dependency or an unavailable service, from a failed change, so cycles are not burned on environment problems. -- Two-strike rule: if the same verification fails twice, stop blind iteration and escalate to - `advisor` with the commands, outputs, and attempted fixes. Never create a suffixed copy of a - real file merely to debug around the failure. ### Graph - Work alone for small, reversible changes. Delegate to `executor` for a fully specified - mechanical batch of roughly five or more files, or for a read-heavy scan that would pollute - the main context. Batch related mechanical work into one delegation. + mechanical batch of roughly five or more files; read-heavy scans go to a context-carrying + subagent, never `executor`. Batch related mechanical work into one delegation. - Consult `advisor` before any change that is hard to reverse, touches shared or production systems, or spans repositories or services. Obtain user confirmation before any action that needs new authority or mutates shared or production state. @@ -142,7 +143,7 @@ Every item in a REVISE list must be independently actionable. The executor gets ```toml # Created by Abhirup Banerjee (@ovhirup) as part of the Stackwich Codex architecture. name = "executor" -description = "Low-reasoning executor for fully specified mechanical edits, large batches, and read-heavy scans." +description = "Low-reasoning executor for fully specified mechanical edits and large batches." model_reasoning_effort = "low" developer_instructions = """ Carry out the provided instructions exactly. Do not redesign, extend, or opportunistically refactor. @@ -152,7 +153,7 @@ Inputs you require: the plan's exact steps, its declared file scope, and the ver - Follow every applicable AGENTS.md file and existing conventions for touched files. - Never create suffixed copies such as name2.ts or fix-v2.py to work around a problem. - If an instruction is ambiguous, stop and report the ambiguity instead of guessing. -- If the same verification fails twice, stop and return both attempts, outputs, and relevant diff. +- If the same verification fails twice, stop and return both attempts, outputs, and relevant diff; a second failure goes to `advisor` to re-plan, not to another blind retry. - Report changed paths, the diff or edits made, commands run, exit codes, and material raw output. - Never mutate shared or production state, deploy, push, publish, or call a live write API unless the parent task explicitly authorizes that exact action. """ diff --git a/docs/enforcement.md b/docs/enforcement.md index 25832b2..c7af604 100644 --- a/docs/enforcement.md +++ b/docs/enforcement.md @@ -23,7 +23,8 @@ Three kinds of claim: | Each agent's model tier | Mechanical, as configuration | Set by `model:` in each agent's frontmatter. Which agent gets used for a task is instructed. | | Plan → execute → verify → review for risky changes | Instructed | The main session decides when a change is risky and whether to run the sandwich. | | Verdict lines (`GATE: PASS`, `APPROVE`, `REVISE:`) | Instructed | They are fixed strings so routing does not depend on reading prose, but the main session does the routing. | -| Failure loops capped at 2 cycles | Instructed | No counter exists outside the conversation. | +| Failure ladder: retry, then `advisor` re-plans, then stop at the third failure | Instructed | No counter exists outside the conversation. | +| Read-heavy scans go to a fork, not `executor` | Instructed | The main session chooses where to send a scan. | | Nothing "done" until verified | Instructed | The policy requires reporting the command and its output. No tool checks that a claim matches a run. | ## Codex port @@ -32,7 +33,7 @@ Three kinds of claim: |---|---|---| | `advisor` and `verifier` cannot write files | Mechanical, where Codex honors the setting | Their templates set `sandbox_mode = "read-only"`, so Codex runs their commands in its read-only sandbox. | | `executor` stays in scope and does not push, deploy, or publish | Instructed | `executor` has no `sandbox_mode` in its template and inherits the session's sandbox and approval settings. | -| Sandwich, verdict routing, 2-cycle cap, two-strike rule | Instructed | Same as the Claude Code plugin. | +| Sandwich, verdict routing, failure ladder, scan routing | Instructed | Same as the Claude Code plugin. | | Model choice | Not pinned | The templates set reasoning effort and sandbox only, so they stay portable across accounts. | A read-only sandbox also blocks legitimate writes. A test, build, or coverage run that needs to @@ -44,7 +45,7 @@ verifier's instructions say to label environment problems as such. | Behavior | Kind | Detail | |---|---|---| | Single writer, PLAN/VERIFY/REVIEW never edit | Instructed | The port runs the sandwich as phases inside one agent. There is no separate role with fewer tools. | -| Sandwich, 2-cycle cap, verification before "done" | Instructed | Same policy as the parent, carried by `grok/SKILL.md`. | +| Sandwich, failure ladder (EXECUTE, then PLAN, then the user), verification before "done" | Instructed | Same policy as the parent, carried by `grok/SKILL.md`. | ## Measured approval gate (`measured/approve.py`) diff --git a/docs/first-task.md b/docs/first-task.md index c10028c..9404ff8 100644 --- a/docs/first-task.md +++ b/docs/first-task.md @@ -26,7 +26,7 @@ cd ~/my-project python3 ~/stackwich-tools/tools/diagnose.py ``` -A healthy user-level install reports `policy-rev 7`, three Stackwich agents, and +A healthy user-level install reports the checkout's current `policy-rev`, three Stackwich agents, and `Problems: none found`. Here is a setup with a real conflict: the project has its own agent called `executor`, which shadows Stackwich's. diff --git a/evals/evals.json b/evals/evals.json index bb2cadb..c7af010 100644 --- a/evals/evals.json +++ b/evals/evals.json @@ -5,7 +5,7 @@ "id": 1, "name": "fresh-user-level-install", "prompt": "Set up the Stackwich architecture on this machine at the user level, including the subagents.", - "expected_output": "~/.claude/CLAUDE.md created with exactly one stackwich:v1 marker pair and policy-rev 7; advisor.md, executor.md, verifier.md written to ~/.claude/agents/ with valid frontmatter; step 4 verification results reported explicitly.", + "expected_output": "~/.claude/CLAUDE.md created with exactly one stackwich:v1 marker pair and policy-rev 8; advisor.md, executor.md, verifier.md written to ~/.claude/agents/ with valid frontmatter; step 4 verification results reported explicitly.", "assertions": [ "CLAUDE.md contains exactly one opening and one closing marker", "policy-rev line is present inside the block", @@ -19,12 +19,12 @@ "id": 2, "name": "update-existing-v1-install", "prompt": "I already have Stackwich installed from a while back — can you bring it up to date?", - "expected_output": "Existing block located via the opening marker, shown to the user with its declared policy-rev, replaced in place after confirmation with the policy-rev 7 block. No duplicate section appended.", + "expected_output": "Existing block located via the opening marker, shown to the user with its declared policy-rev, replaced in place after confirmation with the policy-rev 8 block. No duplicate section appended.", "assertions": [ "existing block is shown to the user before modification", "user is asked before replacing", "final file contains exactly one marker pair", - "final block declares policy-rev 7 and no older policy-rev line remains" + "final block declares policy-rev 8 and no older policy-rev line remains" ], "files": [] }, diff --git a/grok/README.md b/grok/README.md index de535ea..c62a6da 100644 --- a/grok/README.md +++ b/grok/README.md @@ -17,12 +17,12 @@ Stackwich installs five layers into Grok coding sessions: 1. **Prompt** — meta-prompt every non-trivial sub-task; never hand off understanding 2. **Context** — keep research and raw tool output out of the main reasoning thread 3. **Harness** — one writer, and nothing is "done" without observed output -4. **Loop** — deliberate iteration, capped at two cycles before you're brought in +4. **Loop** — deliberate iteration: retry, then re-plan, then you're brought in 5. **Graph** — PLAN → EXECUTE → VERIFY → REVIEW for anything risky It also instructs: - A verification gate with fixed verdicts (`GATE: PASS` / `GATE: FAIL`) -- Two-strike rule (same failure twice → stop and escalate) +- A failure ladder (first failure → retry, second → re-plan, third → stop and ask you) - No suffixed file copies as a debugging strategy - Concrete plans with verification commands before non-trivial edits @@ -60,7 +60,7 @@ cp SKILL.md LICENSE ~/.grok/skills/stackwich-grok/ ``` > **Port status:** at parity with the Claude Code parent's five-layer policy, as -> `stackwich-grok-rev 4`. The port tracks the parent's layer structure, not its revision +> `stackwich-grok-rev 5`. The port tracks the parent's layer structure, not its revision > number — a parent bump does not automatically oblige a port bump. The Graph layer is > expressed as explicit phases inside one agent rather than three subagents: a deliberate > design choice for this runtime, not a shortfall. diff --git a/grok/SKILL.md b/grok/SKILL.md index 998597f..ada2720 100644 --- a/grok/SKILL.md +++ b/grok/SKILL.md @@ -32,8 +32,8 @@ Stackwich turns Grok from a fast code generator into a disciplined delivery part 4. **Loop — iterate deliberately, and cap it** Recurring work runs as explicit iteration that tracks what was attempted and what failed, - not as repeated one-shot "try again" prompts. Failure routes back to EXECUTE with the - original plan, capped at two cycles before the user is brought in. + not as repeated one-shot "try again" prompts. A first failure routes back to EXECUTE with + the original plan, a second back to PLAN, and a third brings the user in. 5. **Graph — plan, execute, verify, review** Anything hard to reverse, production-touching, schema-changing, or wide in blast radius @@ -103,7 +103,7 @@ When the user asks to install or activate Stackwich: ```markdown - + ## Working Architecture (Stackwich) ### Prompt @@ -149,14 +149,12 @@ When the user asks to install or activate Stackwich: consecutive runs stops and reports (unless the user set a different number). - Recurring work runs as explicit iteration that tracks what was attempted and what failed, not as repeated one-shot "try again" prompts. -- Failure routing, with a hard stop: - - `GATE: FAIL` -> return to EXECUTE with the failure output and the original plan. - - `REVISE: ...` -> return to EXECUTE with the numbered list and the original plan. - - Either path is capped at 2 cycles. On the third, stop and bring the user the plan, what was - tried, and the outstanding gate or review output. Never loop silently. -- Two-strike rule: if the same verification fails twice, stop iterating blind and escalate with - what was tried. Never respond to repeated failure by creating a suffixed copy of a file to - debug in. +- Failure ladder for `GATE: FAIL` or `REVISE: ...` on the same change; the count never resets: + 1. First failure -> return to EXECUTE with the output (or numbered list) and the original plan. + 2. Second -> return to PLAN: re-plan from the plan, what was tried, and the outputs; then + EXECUTE the new plan. + 3. Third -> stop and bring the user the plan, what was tried, and the outstanding output. + Never loop silently, and never debug in a suffixed copy of a file. ### Graph - Risky or hard-to-reverse changes follow PLAN -> EXECUTE -> VERIFY -> REVIEW in full. Small, diff --git a/plugins/stackwich/.claude-plugin/plugin.json b/plugins/stackwich/.claude-plugin/plugin.json index d0c390e..8b4d238 100644 --- a/plugins/stackwich/.claude-plugin/plugin.json +++ b/plugins/stackwich/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "stackwich", - "version": "3.4.0", + "version": "3.5.0", "description": "Delivery discipline for AI coding agents. Writes the five-layer Stackwich policy (Prompt / Context / Harness / Loop / Graph) into CLAUDE.md and scaffolds advisor, executor and verifier subagents. An optional local measured layer can record sandwich steps and delivery signals without changing that policy.", "author": { "name": "Abhirup Banerjee" }, "homepage": "https://github.com/ovhirup/stackwich", diff --git a/plugins/stackwich/skills/stackwich/SKILL.md b/plugins/stackwich/skills/stackwich/SKILL.md index 1181ce0..cb044ae 100644 --- a/plugins/stackwich/skills/stackwich/SKILL.md +++ b/plugins/stackwich/skills/stackwich/SKILL.md @@ -3,8 +3,8 @@ name: stackwich description: Installs the Stackwich architecture — meta-prompt delegation, a plan/execute/verify/review sandwich, loop-by-default for recurring work, and fork-based context engineering — into any Claude Code setup. Writes the operating policy into CLAUDE.md and optionally scaffolds three companion subagents (advisor/executor/verifier). Use this whenever the user wants to adopt, install, bootstrap, upgrade, or re-apply this delegation architecture on a new machine, project, or someone else's setup — and also when they ask more loosely for help making their Claude Code setup more disciplined, setting up planner/executor/reviewer subagents, adding a review gate before risky changes, enforcing cheap-model tiering, or fixing agents that make sloppy or out-of-scope edits. Also use it when the user asks why agent usage or cost keeps climbing despite cheaper models, or whether a loop or more parallel agents will actually save effort. metadata: author: Abhirup Banerjee (@ovhirup) - version: 3.4.0 - policy-rev: 7 + version: 3.5.0 + policy-rev: 8 --- # Stackwich — install the Stackwich architecture @@ -17,9 +17,9 @@ Stackwich is a stack, not a framework — five layers, each a habit: | Layer | Habit | |---|---| | **Prompt** | meta-prompt every delegation; never delegate understanding | -| **Context** | fork research off the main thread; right mechanism for each kind of state | +| **Context** | fork research and scans off the main thread; resume from a handoff | | **Harness** | one writer, real read-only, nothing "done" until verified | -| **Loop** | recurring work loops; failure loops are capped, never silent | +| **Loop** | recurring work loops; failures climb retry -> re-plan -> stop, never silent | | **Graph** | plan -> execute -> verify -> review, with explicit hand-off contracts | This skill writes those five layers as durable policy into a CLAUDE.md, and optionally @@ -59,92 +59,72 @@ substitute consistently everywhere they appear. ```markdown - + ## Working Architecture (Stackwich) ### Prompt -- Any time work is delegated to a subagent (fork or fresh), write a context-full prompt — the - why, what's already been tried/ruled out, exact files/lines/identifiers — never a terse - command. Never delegate understanding to the subagent. -- Every delegation states its own done condition: the verification command and the expected - output. Work handed off without one comes back unverifiable. +- Delegate with a context-full prompt — the why, what's been tried or ruled out, exact + files/lines/identifiers — never a terse command. Never delegate understanding. +- Every delegation states its done condition: the verification command and expected output. ### Context -- Fork for research, exploration, or read-heavy scans so raw tool output stays out of the main - conversation. Prefer forking over a fresh agent when prior context is reusable (warm cache, - no re-briefing) — a fresh agent is the default only when the work is genuinely unrelated to - what's already in context. -- Use memory (if available) for durable cross-session facts, plans for pre-implementation - alignment, tasks for in-conversation progress — each mechanism for its own purpose, not - interchangeably. -- When work may outlive the session (a sandwich in flight, a multi-step plan), keep - `.stackwich/handoff.md` current at each stage change: the plan and where it lives, the stage, - the next step, the last gate verdict with its command, and the commit plus - `git status --short`. On resuming, read it first, compare the repository with what it - recorded, and treat any difference as unverified — re-run the gate before building on an - earlier PASS. -- Don't re-read a file you just wrote/edited to "confirm" it — the write already succeeded or - would have errored. Don't re-fetch or re-derive facts already established this session. +- Fork research, exploration, and read-heavy scans so raw tool output stays out of the main + conversation; prefer a fork over a fresh agent unless the work is unrelated. Never send + scans to `executor`. +- When work may outlive the session, keep `.stackwich/handoff.md` current at each stage change, + with `.stackwich/` kept out of git: the plan and where it lives, the stage, the next step, the + last gate verdict with its command, and the commit plus `git status --short`. On resuming, + read it first, compare the repository with it, and treat any difference as unverified — + re-run the gate before building on an earlier PASS. +- Don't re-fetch or re-derive facts already established this session. ### Harness - Single writer: only `executor` (or you, working alone) mutates files. `advisor` and - `verifier` never write, even when the fix looks obvious and one character long — a fix from a - reviewer is an unreviewed change nobody knows exists. -- Read-only means read-only in practice, not just in the tool list: `Bash` granted to a - read-only agent is for inspection and verification only (tests, lint, build, + `verifier` never write, even a one-character fix — a reviewer's fix is an unreviewed change + nobody knows exists. +- A read-only agent's `Bash` is for inspection and verification only (tests, lint, build, `git diff`/`status`) — never writes, installs, deploys, or pushes. -- Nothing is "done" on the strength of intent. Report what was observed — the command run and - its actual output. If it wasn't verified, say that instead of implying it was. -- Model tiering is a cost control: don't escalate a task to a pricier model or a bigger - subagent than the work actually requires. (Each agent's tier is set in its own frontmatter — - trust it rather than restating it per task.) +- Nothing is "done" on intent: report the command run and its actual output, or say it wasn't + verified. +- Don't escalate to a pricier model or bigger subagent than the task requires; each agent's + tier is set in its own frontmatter. - Size each delegation to what `verifier` and the reviewer can check in one pass; split a larger batch into sequential gated batches. When reporting done, state how many delegations, forks, - and loop runs the task used — add token or cost figures only where the environment shows them. + and loop runs the task used, with token or cost figures only where the environment shows them. ### Loop -- Recurring or repeated work defaults to `/loop`, not a manual re-run-by-hand habit. -- Before starting a loop, fixed-cadence or self-paced, state its stop condition and a maximum - run count; if either is missing, ask the user instead of starting. A loop that produces no - change for 3 consecutive runs stops and reports (unless the user set a different number). -- Failure routing, with hard stops: - - `GATE: FAIL` -> hand the failure output back to `executor` with the original plan. - - `REVISE: ...` -> hand the numbered list back to `executor` with the original plan. - - Either path is capped at 2 cycles. On the third, stop and bring the user the plan, what was - tried, and the outstanding gate/review output. Never loop silently. -- Two-strike rule: if the same verification fails twice, stop iterating blind — escalate to - `advisor` with what was tried. Never respond to repeated failure by creating a suffixed copy - of a file to debug in. +- Recurring or repeated work defaults to `/loop`. Before starting one, fixed-cadence or + self-paced, state its stop condition and a maximum run count; if either is missing, ask the + user instead of starting. A loop with no change for 3 consecutive runs (or the user's + number) stops and reports. +- Failure ladder for `GATE: FAIL` or `REVISE: ...` on the same change; the count never resets: + 1. First failure -> `executor` retries with the output (or numbered list) and the original plan. + 2. Second -> `advisor` re-plans from the plan, what was tried, and the outputs; `executor` + applies the new plan. + 3. Third -> stop and bring the user the plan, what was tried, and the outstanding output. + Never loop silently, and never debug in a suffixed copy of a file. ### Graph -- Default: work alone for small/reversible changes. Spawn `executor` only for >=5-file - mechanical batches or read-heavy scans that would pollute the main context. Batch related - mechanical work into one delegation instead of many small round-trips. -- If a batch is large AND the items are independent (no shared file, no ordering dependency), - shard it across parallel `executor` runs and fan the results into a single `verifier` pass. - Launch only as many shards as that pass and the reviewer can check; state the count and why. - If items touch the same files or must land in order, keep it serial — concurrent writers - corrupt diffs. -- Consult `advisor` BEFORE any change that's hard to reverse, touches shared/production - systems, or spans multiple repos/services. Concretely: schema migrations, prod/staging - config, published API or CLI surfaces, auth and permissions, force-push or history rewrite, - dependency-version bumps, CI/CD pipeline edits, anything deleting data, anything another - person or service consumes. +- Default: work alone for small/reversible changes; `verifier` alone closes the loop. Spawn + `executor` for >=5-file mechanical batches, as one delegation, not many round-trips. +- If a large batch's items are independent (no shared file, no ordering dependency), shard it + across parallel `executor` runs fanned into one `verifier` pass; launch only as many shards as + that pass and the reviewer can check, and state the count and why. Otherwise keep it serial — + concurrent writers corrupt diffs. - Full sandwich (`advisor` plans -> `executor` implements -> `verifier` gates -> `advisor` - reviews) is MANDATORY, not optional, whenever a change meets that bar — do not skip it - because the change looks small or under time pressure. Otherwise `verifier` alone closes the - loop. + reviews) is MANDATORY, however small or urgent the change looks, when it is hard to + reverse, touches shared/production systems, or spans repos/services: schema migrations, + prod/staging config, published API or CLI surfaces, auth and permissions, force-push or + history rewrite, dependency-version bumps, CI/CD pipeline edits, anything deleting data, + anything another person or service consumes. - If the user already has a plan, spec, or ticket for the change, that is the plan — never - write a competing one. `advisor` refines it into executor-ready steps (exact files, edits, a - verification command per step) without redesigning it, returns gaps, ambiguities, and - conflicts with the code to the user as open questions instead of settling them silently, and + write a competing one. `advisor` refines it into executor-ready steps without redesigning it, + returns gaps and conflicts to the user as open questions instead of settling them, and reviews the diff against the user's plan as well as the refinement. -- You are the orchestrator: artifacts travel through you, so forward them intact. `executor` - receives the plan's exact steps plus its verification command and expected output. - `verifier` receives that same verification spec plus the executor's raw reported diff and the - plan's declared file scope. `advisor` (reviewing) receives its own original plan plus the - diff and the gate result. An agent missing its input contract should say so and stop, not - improvise the missing half. +- Forward artifacts intact: `executor` gets the plan's exact steps and verification command + with expected output; `verifier` gets that spec, the plan's declared file scope, and the + executor's raw diff; `advisor` reviewing gets its own original plan, the diff, and the gate + result. An agent missing its input contract says so and stops. ``` @@ -194,7 +174,7 @@ This skill installs a verify-before-done policy, so it holds itself to it. After confirm and report actual observed results — not intentions: 1. Both markers present in `/CLAUDE.md`, exactly once each. -2. `policy-rev: 7` is present inside the block (an upgrade from an older revision must +2. `policy-rev: 8` is present inside the block (an upgrade from an older revision must leave no trace of the previous one). 3. If agents were scaffolded: all three files exist in `/agents/`, each starts with valid YAML frontmatter containing `name`, `description`, `model`, and `tools`. diff --git a/plugins/stackwich/skills/stackwich/assets/executor.md b/plugins/stackwich/skills/stackwich/assets/executor.md index b252270..1834886 100644 --- a/plugins/stackwich/skills/stackwich/assets/executor.md +++ b/plugins/stackwich/skills/stackwich/assets/executor.md @@ -1,6 +1,6 @@ --- name: executor -description: Cheap executor for fully-specified, mechanical edits and bulk batches. No design decisions. Use for >=5-file mechanical batches or read-heavy scans that would pollute the main context. +description: Cheap executor for fully-specified, mechanical edits and bulk batches. No design decisions. Use for >=5-file mechanical batches; read-only scans go to a fork instead. model: haiku tools: Read, Edit, Write, Bash, Glob, Grep author: Abhirup Banerjee (@ovhirup) — part of the Stackwich architecture @@ -27,7 +27,8 @@ it. If the steps themselves are ambiguous, stop before editing — see below. - NEVER create a suffixed copy of a file (`name2.ts`, `fix-x-v2.py`) to work around a problem — all edits happen in place on the real file. - STOP and report, rather than improvising, when: an instruction is ambiguous, the - verification command fails twice in a row, or a file doesn't match what the plan described + verification command fails twice in a row (a second failure goes to `advisor` to re-plan, not + to another blind retry), or a file doesn't match what the plan described (wrong line numbers, already-changed content). A stale plan means the world moved; guessing at intent from a stale plan compounds the drift. - Report results verbatim: the diff you made (or files you wrote), the commands you ran, and