diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json new file mode 100644 index 0000000..802fbe1 --- /dev/null +++ b/.claude-plugin/marketplace.json @@ -0,0 +1,12 @@ +{ + "name": "stackwich", + "description": "Delivery discipline for AI coding agents: meta-prompt delegation, a plan/execute/verify/review sandwich, and fork-based context engineering.", + "owner": { "name": "Abhirup Banerjee", "url": "https://github.com/ovhirup" }, + "plugins": [ + { + "name": "stackwich", + "source": "./plugins/stackwich", + "description": "Installs the Stackwich architecture into a Claude Code setup: writes the five-layer operating policy into CLAUDE.md and scaffolds advisor, executor and verifier subagents." + } + ] +} diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml index 80bd402..9e75e19 100644 --- a/.github/workflows/validate.yml +++ b/.github/workflows/validate.yml @@ -13,24 +13,53 @@ jobs: steps: - uses: actions/checkout@v4 + - name: Manifests valid and in agreement + run: | + test -f .claude-plugin/marketplace.json || { echo "::error::marketplace.json missing"; exit 1; } + test -f plugins/stackwich/.claude-plugin/plugin.json || { echo "::error::plugin.json missing"; exit 1; } + jq -e . .claude-plugin/marketplace.json > /dev/null || { echo "::error::marketplace.json is not valid JSON"; exit 1; } + jq -e . plugins/stackwich/.claude-plugin/plugin.json > /dev/null || { echo "::error::plugin.json is not valid JSON"; exit 1; } + [ "$(jq '.plugins | length' .claude-plugin/marketplace.json)" -eq 1 ] || { echo "::error::marketplace must list exactly one plugin"; exit 1; } + [ "$(jq -r '.plugins[0].source' .claude-plugin/marketplace.json)" = "./plugins/stackwich" ] || { echo "::error::marketplace entry source must be ./plugins/stackwich"; exit 1; } + [ "$(jq -r '.plugins[0].name' .claude-plugin/marketplace.json)" = "$(jq -r '.name' plugins/stackwich/.claude-plugin/plugin.json)" ] || { echo "::error::marketplace entry name and plugin.json name disagree"; exit 1; } + PV="$(jq -r '.version' plugins/stackwich/.claude-plugin/plugin.json)" + SV="$(sed -n 's/^[[:space:]]*version:[[:space:]]*//p' plugins/stackwich/skills/stackwich/SKILL.md | head -1)" + [ "$PV" = "$SV" ] || { echo "::error::plugin.json version ($PV) != SKILL.md version ($SV)"; exit 1; } + cmp -s LICENSE plugins/stackwich/LICENSE || { echo "::error::plugins/stackwich/LICENSE has drifted from the root LICENSE"; exit 1; } + echo "manifests OK" + + - name: Plugin shape invariants + run: | + test ! -e SKILL.md || { echo "::error::a root SKILL.md reappeared — the canonical skill lives at plugins/stackwich/skills/stackwich/SKILL.md and must not be duplicated"; exit 1; } + test ! -e assets || { echo "::error::a root assets/ reappeared — the scaffolding source lives inside the skill directory"; exit 1; } + test ! -e plugins/stackwich/agents || { echo "::error::the plugin must NOT ship agents/ — plugin agents install namespaced (stackwich:advisor) and the policy block references bare names; the skill scaffolds them instead"; exit 1; } + [ "$(ls plugins/stackwich/skills | wc -l)" -eq 1 ] || { echo "::error::plugins/stackwich/skills must contain exactly one skill directory"; exit 1; } + echo "plugin shape OK" + - name: Frontmatter and structure checks run: | - test -f SKILL.md || { echo "::error::SKILL.md missing"; exit 1; } - head -1 SKILL.md | grep -qx -- '---' || { echo "::error::missing frontmatter opener"; exit 1; } - grep -q '^name: stackwich' SKILL.md || { echo "::error::frontmatter name missing"; exit 1; } - grep -q '^description:' SKILL.md || { echo "::error::frontmatter description missing"; exit 1; } - grep -qE '^[[:space:]]*author:' SKILL.md || { echo "::error::frontmatter author missing"; exit 1; } - [ "$(grep -cx -- '' SKILL.md)" -eq 1 ] || { echo "::error::SKILL.md must contain exactly one whole-line opening marker"; exit 1; } - [ "$(grep -cx -- '' SKILL.md)" -eq 1 ] || { echo "::error::SKILL.md must contain exactly one whole-line closing marker"; exit 1; } + S=plugins/stackwich/skills/stackwich/SKILL.md + test -f "$S" || { echo "::error::$S missing"; exit 1; } + head -1 "$S" | grep -qx -- '---' || { echo "::error::missing frontmatter opener"; exit 1; } + grep -q '^name: stackwich' "$S" || { echo "::error::frontmatter name missing"; exit 1; } + grep -q '^description:' "$S" || { echo "::error::frontmatter description missing"; exit 1; } + grep -qE '^[[:space:]]*author:' "$S" || { echo "::error::frontmatter author missing"; exit 1; } + [ "$(grep -cx -- '' "$S")" -eq 1 ] || { echo "::error::SKILL.md must contain exactly one whole-line opening marker"; exit 1; } + [ "$(grep -cx -- '' "$S")" -eq 1 ] || { echo "::error::SKILL.md must contain exactly one whole-line closing marker"; exit 1; } + [ "$(grep -cx -- '' "$S")" -eq 1 ] || { echo "::error::SKILL.md must contain exactly one whole-line policy-rev: 3 comment"; exit 1; } + for h in Prompt Context Harness Loop Graph; do + awk '/^$/,/^$/' "$S" | grep -q "^### $h" || { echo "::error::policy block missing the $h layer"; exit 1; } + done echo "SKILL.md OK" - name: Agent assets present and well-formed run: | + A=plugins/stackwich/skills/stackwich/assets for a in advisor executor verifier; do - test -f "assets/$a.md" || { echo "::error::assets/$a.md missing"; exit 1; } - grep -q "^name: $a" "assets/$a.md" || { echo "::error::assets/$a.md name wrong"; exit 1; } - grep -q '^model:' "assets/$a.md" || { echo "::error::assets/$a.md model missing"; exit 1; } - grep -q '^tools:' "assets/$a.md" || { echo "::error::assets/$a.md tools missing"; exit 1; } + test -f "$A/$a.md" || { echo "::error::$A/$a.md missing"; exit 1; } + grep -q "^name: $a" "$A/$a.md" || { echo "::error::$A/$a.md name wrong"; exit 1; } + grep -q '^model:' "$A/$a.md" || { echo "::error::$A/$a.md model missing"; exit 1; } + grep -q '^tools:' "$A/$a.md" || { echo "::error::$A/$a.md tools missing"; exit 1; } done echo "assets OK" diff --git a/CHANGELOG.md b/CHANGELOG.md index d141c72..10c5112 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,53 @@ 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.0.0 — installs as a plugin + +Stackwich is now a Claude Code plugin marketplace rather than a repo you clone into your skills +directory. **Your policy and your agents are unchanged.** `policy-rev` stays at 3, the +`CLAUDE.md` block is identical, the scaffolded `advisor` / `executor` / `verifier` keep their +names and contents, and there is nothing to re-run — only the delivery mechanism moved. + +### Upgrading + +``` +/plugin marketplace add ovhirup/stackwich +/plugin install stackwich@stackwich +``` + +Then remove the old clone — `rm -rf ~/.claude/skills/stackwich` at user level, and +`rm -rf ./.claude/skills/stackwich` in any repo you installed it into. Leaving it in place gives +you two skills both named `stackwich`. + +**Do not `git pull` instead.** The skill no longer lives at the repo root, so pulling into an +existing clone removes `SKILL.md` and `assets/` and leaves a directory Claude Code can load as +neither a skill nor a plugin. `/stackwich` stops resolving, with no error and no pointer to the +new install method. + +### Why the layout moved +- Claude Code discovers skills only by scanning a plugin's `skills/` directory, and no manifest + field can point at a root-level `SKILL.md`. The skill therefore moved to + `plugins/stackwich/skills/stackwich/`. +- `assets/` moved with it. `SKILL.md` resolves the agent definitions relative to its own + directory, so the two are only correct together — which also makes the skill directory + self-contained. + +### What the plugin deliberately does not ship +- **No `agents/` directory.** Plugin-supplied agents install namespaced, as `stackwich:advisor`. + That would break the policy block's bare references, remove the + choice to decline scaffolding, and make rename-on-collision impossible, since a file in the + plugin cache is overwritten on update. The skill keeps scaffolding them from `assets/`. +- **No stub `SKILL.md` at the repo root.** For anyone still holding a 2.x clone inside a skills + directory, a stub would itself be a skill named `stackwich` — the very duplicate this release + tells them to remove. + +### Repo +- CI validates both manifests, checks the marketplace entry and `plugin.json` agree on name, + checks `plugin.json`'s version matches the skill's frontmatter, and fails if a root + `SKILL.md`, a root `assets/`, or a `plugins/stackwich/agents/` ever reappears. +- The `grok/` and `codex/` ports are untouched and stay at the repo root — nothing there sits on + a Claude Code discovery path. + ## 2.2.0 — ports reach five-layer parity The `grok/` and `codex/` ports now install the same Prompt / Context / Harness / Loop / Graph diff --git a/README.md b/README.md index 2da9324..3d20073 100644 --- a/README.md +++ b/README.md @@ -39,24 +39,36 @@ Small, reversible changes skip the ceremony — the verifier alone closes the lo ## Install -Clone the whole repo into your Claude Code skills directory — the skill reads `assets/` when it scaffolds the agents, so fetching `SKILL.md` alone is not enough: +Add the marketplace, then install the plugin. Both are slash commands, typed inside a Claude Code session: -```bash -# user level — applies to every project -git clone https://github.com/ovhirup/stackwich ~/.claude/skills/stackwich - -# or project level -git clone https://github.com/ovhirup/stackwich ./.claude/skills/stackwich +``` +/plugin marketplace add ovhirup/stackwich +/plugin install stackwich@stackwich ``` -Then, inside any Claude Code session: +Then run: ``` -/stackwich +/stackwich:stackwich ``` +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. +### Upgrading from 2.x + +**Nothing about your policy changes.** Your `CLAUDE.md` block stays at `policy-rev 3`, your `advisor`, `executor` and `verifier` keep their existing names and contents, and there is nothing to re-run. Only the delivery mechanism moved. + +Before 3.0, Stackwich was installed by cloning this repo into a skills directory. Install the plugin above, then remove the old clone — leaving it in place gives you two skills both named `stackwich`: + +```bash +rm -rf ~/.claude/skills/stackwich # user level +rm -rf ./.claude/skills/stackwich # project level, in each repo you installed it into +``` + +**Don't `git pull` instead.** The skill no longer lives at the repo root, so pulling into an existing clone deletes `SKILL.md` and `assets/` and leaves a directory Claude Code can load as neither a skill nor a plugin. `/stackwich` stops resolving — with no error, and no pointer to the new install method. + ## What it writes | Path | What | @@ -82,15 +94,22 @@ The skill does the rest interactively: asks for scope, writes the policy, offers ``` stackwich/ -├── SKILL.md # the skill: install workflow + policy block -├── assets/ # agent definitions, read only when scaffolding is accepted -│ ├── advisor.md -│ ├── executor.md -│ └── verifier.md -├── evals/evals.json # test cases for the five install paths +├── .claude-plugin/ +│ └── marketplace.json # the marketplace catalog +├── plugins/stackwich/ +│ ├── .claude-plugin/ +│ │ └── plugin.json # the plugin manifest +│ ├── LICENSE +│ └── skills/stackwich/ +│ ├── SKILL.md # the skill: install workflow + policy block +│ └── assets/ # agent definitions, read only when scaffolding is accepted +│ ├── advisor.md +│ ├── executor.md +│ └── verifier.md +├── evals/evals.json # test cases for the five install paths ├── docs/sandwich.jpg -├── grok/ # Grok port (stackwich-grok) — not a Claude Code skill -├── codex/ # Codex port (stackwich-codex) — not a Claude Code skill +├── grok/ # Grok port (stackwich-grok) — not a Claude Code skill +├── codex/ # Codex port (stackwich-codex) — not a Claude Code skill ├── CHANGELOG.md ├── LICENSE └── README.md @@ -100,12 +119,19 @@ stackwich/ ## Uninstall +``` +/plugin uninstall stackwich +/plugin marketplace remove stackwich +``` + +The agents were scaffolded into your own agents directory, not shipped by the plugin, so removing the plugin leaves them behind. Delete them from whichever scope you installed into: + ```bash -rm -rf ~/.claude/skills/stackwich -rm -f ~/.claude/agents/{advisor,executor,verifier}.md +rm -f ~/.claude/agents/{advisor,executor,verifier}.md # user level +rm -f ./.claude/agents/{advisor,executor,verifier}.md # project level, in each repo ``` -…and delete the `` … `` block from your `CLAUDE.md`. +…and delete the `` … `` block from the matching `CLAUDE.md`: `~/.claude/CLAUDE.md` for a user-level install, the repo's own for a project-level one. ## FAQ diff --git a/grok/README.md b/grok/README.md index a26be71..863b21d 100644 --- a/grok/README.md +++ b/grok/README.md @@ -36,7 +36,7 @@ It also enforces: | Policy location | `CLAUDE.md` | `GROK.md` | | Architecture | 3 companion agents (advisor / executor / verifier) | Explicit phases inside one agent | | Verification | Dedicated verifier agent | Grok runs real project commands itself | -| Installation | Skill + agent scaffolding | Skill + policy block in `GROK.md` | +| Installation | Plugin marketplace + agent scaffolding | Skill + policy block in `GROK.md` | Both versions share the same philosophy. The implementation is adapted to each platform’s strengths. diff --git a/plugins/stackwich/.claude-plugin/plugin.json b/plugins/stackwich/.claude-plugin/plugin.json new file mode 100644 index 0000000..a02e2df --- /dev/null +++ b/plugins/stackwich/.claude-plugin/plugin.json @@ -0,0 +1,10 @@ +{ + "name": "stackwich", + "version": "3.0.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.", + "author": { "name": "Abhirup Banerjee" }, + "homepage": "https://github.com/ovhirup/stackwich", + "repository": "https://github.com/ovhirup/stackwich", + "license": "MIT", + "keywords": ["workflow", "subagents", "code-review", "delegation", "verification"] +} diff --git a/plugins/stackwich/LICENSE b/plugins/stackwich/LICENSE new file mode 100644 index 0000000..80b0e0b --- /dev/null +++ b/plugins/stackwich/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Abhirup Banerjee (@ovhirup) + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/SKILL.md b/plugins/stackwich/skills/stackwich/SKILL.md similarity index 99% rename from SKILL.md rename to plugins/stackwich/skills/stackwich/SKILL.md index 49004be..029c9a4 100644 --- a/SKILL.md +++ b/plugins/stackwich/skills/stackwich/SKILL.md @@ -3,11 +3,11 @@ 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. metadata: author: Abhirup Banerjee (@ovhirup) - version: 2.2.0 + version: 3.0.0 policy-rev: 3 --- -# /stackwich — install the Stackwich architecture +# Stackwich — install the Stackwich architecture > Created by **Abhirup Banerjee** ([@ovhirup](https://github.com/ovhirup)). If you're reading > this in a fork, mirror, or repost, please keep this line intact. diff --git a/assets/advisor.md b/plugins/stackwich/skills/stackwich/assets/advisor.md similarity index 100% rename from assets/advisor.md rename to plugins/stackwich/skills/stackwich/assets/advisor.md diff --git a/assets/executor.md b/plugins/stackwich/skills/stackwich/assets/executor.md similarity index 100% rename from assets/executor.md rename to plugins/stackwich/skills/stackwich/assets/executor.md diff --git a/assets/verifier.md b/plugins/stackwich/skills/stackwich/assets/verifier.md similarity index 100% rename from assets/verifier.md rename to plugins/stackwich/skills/stackwich/assets/verifier.md