diff --git a/docs/EVOLUTION.md b/docs/EVOLUTION.md new file mode 100644 index 0000000..8f6bd14 --- /dev/null +++ b/docs/EVOLUTION.md @@ -0,0 +1,73 @@ +# How Stackwich evolved + +Stackwich went from a single skill with a policy block (1.0.0, July 2026) to a Claude Code plugin +with Codex and Grok ports, an optional measured layer, and policy-rev 9. The latest release is 3.6.1 (2 Nov 2026), the 14th. +Every fact below comes from [CHANGELOG.md](../CHANGELOG.md) and the GitHub releases. + +![Stackwich evolution timeline](assets/stackwich-evolution.svg) + +## Timeline + +```mermaid +timeline + title Stackwich releases + section Foundations (Jul 2026) + 1.0.0 : Policy block, idempotent install, three subagents + 2.0.0 : Capped failure routing, install self-check + 2.1.0 : Five named layers, harness made explicit + section Ports and plugin (Sep 2026) + 2.2.0 : Codex and Grok ports reach five-layer parity + 3.0.0 : Installs as a Claude Code plugin + section Ceilings and measurement (Oct 2026) + 3.1.0 : Every efficiency gets a ceiling + 3.1.1 : Parallel shards fit one verifier pass + 3.1.2 : Same fix for the Codex port + 3.2.0 : Optional measured teams layer + section Plans, resume, lean (Oct to Nov 2026) + 3.3.0 : Work from the user's own plan + 3.4.0 : Resume interrupted work safely + 3.5.0 : 700-word policy, one failure ladder + 3.6.0 : Research retries, then names what it did not check + 3.6.1 : Confirm agents without the removed /agents command +``` + +## Release by release + +Dates are tag commit dates. 1.0.0 and 2.0.0 have no tags; they predate 2.1.0 (28 Jul 2026), and the +first commit is 22 Jul 2026. + +| Date | Version | policy-rev | What changed | Value added | +|---|---|---|---|---| +| Jul 2026 | 1.0.0 | 1 | Policy block, marker-based install, three subagents, two-strike rule | A repeatable advisor / executor / verifier setup | +| Jul 2026 | 2.0.0 | 2 | Agent files moved to `assets/`; `GATE: FAIL` and `REVISE:` routed back to `executor`, capped at 2 cycles; install verifies itself | About 55% smaller skill body per trigger; revise loops are bounded | +| 28 Jul 2026 | 2.1.0 | 3 | Policy reorganised under Prompt / Context / Harness / Loop / Graph | Each rule has a clear place; audits become mechanical | +| 15 Sep 2026 | 2.2.0 | 3 | Codex and Grok ports adopt the five layers; CI checks markers as whole lines | Ports cannot drift silently | +| 15 Sep 2026 | 3.0.0 | 3 | Ships as a Claude Code plugin marketplace | Install with `/plugin install`; policy and agents unchanged | +| 1 Oct 2026 | 3.1.0 | 4 | Loops state a stop condition and a max run count; shard counts are stated; done reports count delegations | Cheaper steps can't quietly raise total spend or review load | +| 1 Oct 2026 | 3.1.1 | 5 | Only launch as many shards as one verifier pass can check | Fixes review overload left in 3.1.0 | +| 2 Oct 2026 | 3.1.2 | 5 | Codex port gets the same parallel-run rule (codex-rev 3) | Codex matches the parent | +| 15 Oct 2026 | 3.2.0 | 5 | Optional `measured/` layer: append-only log, report, four-role approval gate | Team runs can be recorded and reported locally | +| 31 Oct 2026 | 3.3.0 | 6 | An existing plan, spec or ticket is the plan; adds `check_install.py`, `diagnose.py`, `uninstall.py`, `verify_gate.py`, recipes | Respects the user's plan; installs can be checked and removed cleanly | +| 31 Oct 2026 | 3.4.0 | 7 | `.stackwich/handoff.md` and `tools/handoff.py` | Interrupted work resumes with changes flagged as unverified | +| 2 Nov 2026 | 3.5.0 | 8 | Policy cut from 952 to 700 words; one failure ladder; scans go to forks; stale agents refreshed on upgrade; `tools/validate.py` | Fewer tokens every turn; a clear escalation path; upgrades really update | +| 2 Nov 2026 | 3.6.0 | 9 | Research forks retry thin results at most twice, then report `Sources:`, `NOT FOUND:`, `UNCHECKED:` | Gaps in research are stated, not hidden | +| 2 Nov 2026 | 3.6.1 | 9 | Installer report and README say to ask Claude to list subagents instead of running the removed `/agents` | Install confirmation works on current Claude Code | + +## Themes + +**Token leanness.** The policy block is read on every turn, so size matters. 2.0.0 moved agent +definitions out of `SKILL.md`. 3.5.0 cut the block from 952 to 700 words by removing lines that +restate Claude Code's own behaviour, and CI now fails past 735 words. 3.6.0 sits at 734. + +**Safety and the failure ladder.** 1.0.0 had a two-strike rule; 2.0.0 added a 2-cycle cap on +`GATE: FAIL` and `REVISE:`. 3.5.0 replaced both with one ladder: first failure back to `executor`, +second to `advisor` to re-plan, third to the user. The count never resets. 3.1.x added ceilings on +loops and parallel work. + +**Ports to Codex and Grok.** Both ports reached five-layer parity in 2.2.0 and have followed each +policy change with their own revision counters, reaching `stackwich-codex-rev 7` and +`stackwich-grok-rev 6` in 3.6.0. Grok runs as one agent with explicit phases. + +**Install and upgrade.** Installs have always upgraded in place by marker. 3.0.0 moved delivery +to a plugin. 3.3.0 added tools to check, diagnose and uninstall. 3.5.0 detects agents left by an +earlier release and offers to refresh them, keeping their names and models. diff --git a/docs/assets/stackwich-evolution.svg b/docs/assets/stackwich-evolution.svg new file mode 100644 index 0000000..0776a30 --- /dev/null +++ b/docs/assets/stackwich-evolution.svg @@ -0,0 +1,126 @@ + + +AGILE AI PIONEERS · FIELD NOTES +The evolution of Stackwich +14 releases, Jul – Nov 2026 · policy-rev 1 → 9 · Claude Code plugin with Codex and Grok ports + +FOUNDATIONS +Jul 2026 + +PORTS + PLUGIN +Sep 2026 + +CEILINGS + MEASUREMENT +Oct 2026 + +PLANS, RESUME, LEAN +Oct – Nov 2026 + + + +v1.0.0 +Jul 2026 · rev 1 +Policy block, +3 subagents + + +v2.0.0 +Jul 2026 · rev 2 +Capped fail routing, +self-checked install + + +v2.1.0 +28 Jul · rev 3 +Five named layers, +harness explicit + + +v2.2.0 +15 Sep · rev 3 +Codex + Grok ports +reach parity + + +v3.0.0 +15 Sep · rev 3 +Installs as a +Claude Code plugin + + +v3.1.0 +1 Oct · rev 4 +Every efficiency +gets a ceiling + + +v3.1.1 +1 Oct · rev 5 +Parallel shards fit +one verifier pass + + +v3.1.2 +2 Oct · rev 5 +Same fix for +the Codex port + + +v3.2.0 +15 Oct · rev 5 +Optional measured +teams layer + + +v3.3.0 +31 Oct · rev 6 +Works from the +user’s own plan + + +v3.4.0 +31 Oct · rev 7 +Resume interrupted +work safely + + +v3.5.0 +2 Nov · rev 8 +952 → 700 words, +one failure ladder + + +v3.6.0 +2 Nov · rev 9 +Research retries, +names what’s unchecked + + +v3.6.1 +2 Nov · rev 9 +Confirm agents +without /agents + + +Token leanness +Agents moved out of SKILL.md (~55% smaller body). +Policy block 952 → 700 words; CI budget 735. + + +Safety: failure ladder +2-cycle cap (2.0) became one ladder (3.5): +executor → advisor → user. Count never resets. + + +Ports +Codex and Grok reached five-layer parity in 2.2; +now codex-rev 7, grok-rev 6, same rules. + + +Install + upgrade +Marker-based in-place upgrades; plugin in 3.0; +stale agents detected and refreshed in 3.5. +Abhirup Banerjee · github.com/ovhirup/stackwich · Source: CHANGELOG.md and GitHub releases +release +latest (v3.6.1) +