diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml index 9e75e19..7fce4c0 100644 --- a/.github/workflows/validate.yml +++ b/.github/workflows/validate.yml @@ -26,6 +26,7 @@ jobs: 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; } + grep -q "^## $PV " CHANGELOG.md || { echo "::error::CHANGELOG.md has no '## $PV' heading — a shipped version with no release note"; exit 1; } echo "manifests OK" - name: Plugin shape invariants @@ -52,6 +53,39 @@ jobs: done echo "SKILL.md OK" + - name: Frontmatter parses as YAML + run: | + python3 -m pip install --quiet --disable-pip-version-check pyyaml + python3 - <<'PY' + import sys, yaml, pathlib + targets = { + "plugins/stackwich/skills/stackwich/SKILL.md": "stackwich", + "grok/SKILL.md": "stackwich-grok", + "codex/SKILL.md": "stackwich-codex", + } + bad = False + for path, expect in targets.items(): + text = pathlib.Path(path).read_text() + if not text.startswith("---\n"): + print(f"::error::{path} has no frontmatter block"); bad = True; continue + block = text.split("---\n", 2)[1] + try: + fm = yaml.safe_load(block) + except yaml.YAMLError as e: + print(f"::error::{path} frontmatter is not valid YAML: {e}"); bad = True; continue + if fm.get("name") != expect: + print(f"::error::{path} name is {fm.get('name')!r}, expected {expect!r}"); bad = True + desc = fm.get("description") or "" + if not desc: + print(f"::error::{path} has no description"); bad = True + elif len(desc) > 1024: + print(f"::error::{path} description is {len(desc)} chars, over the 1024 limit"); bad = True + if not fm.get("author") and not (fm.get("metadata") or {}).get("author"): + print(f"::error::{path} has no author — every distributed copy must name one"); bad = True + sys.exit(1 if bad else 0) + PY + echo "frontmatter OK" + - name: Agent assets present and well-formed run: | A=plugins/stackwich/skills/stackwich/assets diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..f4a85ee --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,65 @@ +# Contributing + +Issues and pull requests are welcome. This file exists because the repo has five rules that +aren't obvious from reading the code, and each one has already caused a real bug. + +`.github/workflows/validate.yml` enforces all of them. If CI fails on your PR, it is probably +one of these. + +## 1. Markers are never renamed + +`` is a permanent search key, not a version number. A release that +searched for a different string could not find existing installs to upgrade — it would append +a second policy block beside the old one instead of replacing it. + +The `v1` is frozen forever. The actual revision lives on a `policy-rev` comment **inside** the +block. + +## 2. Each port keeps the marker it shipped with + +`grok/` reuses `stackwich:v1`. `codex/` uses `stackwich-codex:v1`. They differ because Codex +shipped first with its own marker, and rule 1 applies to it too. + +Ports also carry their own counters — `stackwich-grok-rev`, `stackwich-codex-rev` — starting at +1. A port tracks the parent's **layer structure**, not its revision number. Bumping the parent +does not oblige a port bump. + +## 3. The plugin never ships an `agents/` directory + +Plugin-supplied agents install namespaced, as `stackwich:advisor`. The policy block refers to +`advisor`, `executor` and `verifier` by bare name, so shipping them in the plugin would break +every reference, remove the user's ability to decline scaffolding, and make rename-on-collision +impossible — a file in the plugin cache is overwritten on update. + +The skill scaffolds them from `assets/` instead. CI fails if `plugins/stackwich/agents/` appears. + +## 4. Marker checks in CI match whole lines on purpose + +These files **document their own syntax**. `SKILL.md` contains the sentence "search for the +opening marker ``" as prose, next to the real marker. + +A substring check is satisfied by the documentation instead of the thing it documents. That is +not hypothetical: a release once shipped with its opening marker destroyed, and CI passed, +because the grep matched the prose. Every marker and revision assertion is an exact whole-line +count. Do not relax them to `grep -q`. + +## 5. `SKILL.md` and `assets/` move together + +`SKILL.md` resolves the agent definitions relative to its own directory. Separating them +silently breaks scaffolding for every user, and nothing outside the assets check would notice. + +## Running the checks locally + +```bash +python3 -m pip install pyyaml +``` + +Then run the steps in `.github/workflows/validate.yml`. There is no separate test command — the +workflow is the test suite. + +## Versioning + +One version for the repo, declared in `plugins/stackwich/.claude-plugin/plugin.json` and the +skill's frontmatter. CI asserts they agree and that `CHANGELOG.md` has a matching heading. + +`policy-rev` is separate and only moves when the policy block's content changes. diff --git a/codex/README.md b/codex/README.md index 07bee94..5b44c17 100644 --- a/codex/README.md +++ b/codex/README.md @@ -42,6 +42,8 @@ Copy the whole directory. `SKILL.md` reads `references/templates.md` at install copying `SKILL.md` alone is not enough: ```bash +git clone https://github.com/ovhirup/stackwich +cd stackwich/codex mkdir -p ~/.agents/skills/stackwich-codex cp -R SKILL.md references agents LICENSE ~/.agents/skills/stackwich-codex/ ``` diff --git a/codex/SKILL.md b/codex/SKILL.md index 9ed08fd..58cdc6a 100644 --- a/codex/SKILL.md +++ b/codex/SKILL.md @@ -1,6 +1,7 @@ --- name: stackwich-codex description: "Install the Stackwich Codex delegation architecture: context-rich delegation, a plan-execute-verify-review sandwich for risky work, scheduled automation for recurring work, and subagent-based context engineering. Write durable policy to AGENTS.md and optionally scaffold advisor, executor, and verifier custom agents. Use when the user asks to adopt, install, convert, or bootstrap Stackwich or Stackwich Codex for a ChatGPT/Codex user account, repository, or team setup." +author: Abhirup Banerjee (@ovhirup) --- # Stackwich Codex diff --git a/grok/LICENSE b/grok/LICENSE new file mode 100644 index 0000000..80b0e0b --- /dev/null +++ b/grok/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/grok/README.md b/grok/README.md index 863b21d..1f7b81a 100644 --- a/grok/README.md +++ b/grok/README.md @@ -46,11 +46,13 @@ Both versions share the same philosophy. The implementation is adapted to each p ### As a Grok skill -Copy the `SKILL.md` into your Grok skills directory: +Get the files, then copy the skill and its license into your Grok skills directory: ```bash +git clone https://github.com/ovhirup/stackwich +cd stackwich/grok mkdir -p ~/.grok/skills/stackwich-grok -cp SKILL.md ~/.grok/skills/stackwich-grok/ +cp SKILL.md LICENSE ~/.grok/skills/stackwich-grok/ ``` > **Port status:** at parity with the Claude Code parent's five-layer policy, as diff --git a/grok/SKILL.md b/grok/SKILL.md index ba48b8e..3d157c9 100644 --- a/grok/SKILL.md +++ b/grok/SKILL.md @@ -1,10 +1,15 @@ --- name: stackwich-grok description: Installs delivery discipline for Grok coding sessions. Enforces meta-prompting, a mandatory plan-execute-verify-review sandwich for risky work, loop-by-default for recurring tasks, and strict context engineering. Use when the user wants better agent reliability, wants to reduce "done but broken" outcomes, is doing non-trivial code changes, or asks to install/activate Stackwich or delivery discipline. +author: Abhirup Banerjee (@ovhirup) --- # Stackwich — Delivery Discipline for Grok +Created by **Abhirup Banerjee** ([@ovhirup](https://github.com/ovhirup)). Adapted for Grok from +`ovhirup/stackwich` under the MIT License. Preserve this credit and the bundled `LICENSE` when +copying or distributing the skill. + Stackwich turns Grok from a fast code generator into a disciplined delivery partner. It encodes five layers that prevent the most common failure mode of AI coding agents: declaring work done when it is not actually correct or complete. ## The Five Layers (always active once this skill is loaded)