# dzafran-claude-plugins
Personal Claude Code plugin marketplace. One plugin: **zuko**.
## zuko
Idea to shipped, one vertical slice at a time.
```mermaid
flowchart LR
I((rough idea)) --> SH["/shape"]
SH -- "problem + slice map" --> SP["/spec"]
SP -- "spec.md + visual page" --> B["/build"]
B -- "code + e2e green" --> R["/review"]
R -- "verified findings fixed" --> S["/ship"]
S --> P((shipped))
S -. "next slice" .-> SP
```
Five stages in the line, six helpers reached whenever needed.
| Command | What it does |
| ------- | ------------ |
| `/shape` | Rough idea to a stated problem and an ordered list of shippable slices |
| `/spec` | One slice, three pauses: scope and acceptance, the interface, the technical and ship plan. Publishes a visual page. |
| `/build` | Test-first, scenario by scenario, parallel chunks in isolated worktrees, ends with the slice's e2e test green |
| `/review` | Correctness, security, and quality in one pass. Every finding re-judged blind. |
| `/ship` | Checks the gates, opens the PR, watches CI to green, confirms the signal that proves it works |
| `/design-system` | Builds or extends the product's one design system through Claude Design: brief, direction, primitives, push |
| `/design` | Designs one screen or component from the design system, no spec needed |
| `/poc` | A timeboxed spike answering one risky question. Code dies, answer stays. |
| `/debug` | Reproduce, find the root cause, fix it if small or route to `/spec` if it is design |
| `/status` | Where every slice sits: version, status, open items, next command |
| `/learn` | Audit, consolidate, and remove lessons. Capture is automatic. |
## Enforced by scripts, guided by prompts
Most of zuko is instructions to Claude. The rules that matter most are also
bash scripts. A script gives the same answer every time, and Claude cannot
talk its way past it.
**Hooks.** Claude Code runs these itself. They block the action.
| Hook | Runs | Blocks |
| ---- | ---- | ------ |
| block-dangerous | before every shell command | force pushes, `rm -rf` on top-level or home paths, commits on main |
| secret-scan | before `git commit` | a staged diff with key, token, or password patterns |
| block-attribution | before a commit, tag, release, or PR | a message that signs Claude's name |
| scope-verifier-bash | before each finding-verifier command | anything but read-only `git diff`, `show`, `log`, and `ls-files` |
| scope-pentester-bash | before each pentester command | anything but read-only git and work in its own scratch copy |
| block-pentest-target | before every shell command, during a live pentest | a network call to any host but the one target |
| verify-gates | at the end of every turn | an invalid spec status, a versioned spec outside `archive/`, or a missing ledger |
| check-open-items | at the end of every turn | a shape marked Shaped, or a spec marked Refined, Built or Shipped, while an item is still Open |
`auto-format` also runs after each edit. It formats with the repo's own
formatter, only if one is configured, and never blocks.
**Gate scripts.** A stage runs these and stops on a failure. The verdict is
fixed. The call to the script is a prompt step, so the Stop hooks above back up
the ones that matter most.
| Script | Run by | Fails on |
| ------ | ------ | -------- |
| check-open-items | `/build`, before it starts | any Open row in the spec |
| check-design-drift | `/spec`, `/design`, `/review` | raw hex, arbitrary values, layout animation, emoji, placeholder text, unknown tokens, or no files scanned |
| check-rendered-drift | `/spec`, `/design` | a rendered colour, font size, font family or corner radius that is not a token value, in light or dark, or no page rendered |
| verify-ship-gates | `/ship` | the mechanical pre-ship checks. `/ship` checks the rest by hand. |
**Guided.** These are Claude's judgement, and no script checks them:
- where to cut a slice, and whether it passes the four tests
- whether a review finding is real (verifiers vote, but a model casts each vote)
- the quality of the spec, the tests, and the code
- which lessons to capture
That is why zuko stops for you. `/spec` has three pauses. `/build` and
`/review` record each choice they make alone in the ledger, and you read them
at the PR. Read the PR before you merge it. zuko does not replace that.
## One spec = one vertical slice
A spec is one thin cut through every layer it touches — interface, logic,
data — complete enough to work on its own. It passes only if all four hold:
1. It cuts every layer it needs. No "backend now, UI later".
2. One end-to-end test can walk it start to finish.
3. If it shipped tomorrow alone, someone is better off.
4. It fits: no more than about five acceptance scenarios, no more than two
areas of the system.
Too big fails the test, so it splits into sibling slices. The spec never
widens to make itself pass.
On an empty repo the first slice is a **walking skeleton**: one screen, one
endpoint, one row, one e2e test, deployed, CI running. It does almost nothing
on purpose — its job is to prove the rails exist.
## Nothing unresolved reaches the build
Every spec carries an **open-items ledger** that can only grow. Rows are
resolved, never deleted, so a resolved row is the decision record.
Any moment a stage would assume something, it writes the assumption down
instead of making it silently. `/build` refuses to start while a row is still
`Open` — each becomes `Resolved`, or `Accepted risk` with a stated reason. A
Stop hook enforces it, because prompt rules drift and grep does not.
## Every plan carries diagrams
| Stage | Required |
| ----- | -------- |
| `/shape` | context diagram, slice map |
| `/spec` pause 1 | user or caller flow; state diagram when it has states |
| `/spec` pause 2 | screen flow or interface map |
| `/spec` pause 3 | architecture, one runtime sequence; plus data flow, ER, or deployment when they apply |
| `/debug` | the traced path from symptom to root cause |
Mermaid in the Markdown is the source of truth — it diffs in git, and terminal
replies draw the same diagrams in ASCII, since the terminal shows Mermaid as
source. Each spec also publishes one page with the same diagrams rendered
properly, for reading away from the terminal.
## One design system per product
The design system is the product's identity. Slices refer to it; a slice never
has its own.
```mermaid
flowchart TB
subgraph once["once per product"]
A["/design-system"] --> B[("claude.ai/design
tokens + primitives")]
end
subgraph each["every slice"]
C["/spec pause 2"] --> D["assemble from primitives"] --> E{"drift check"}
E -- fail --> D
E -- pass --> F["preview with real motion"]
end
B -. "tokens + primitives" .-> D
F -. "shipped, reused twice" .-> B
```
`/design-system` starts with a brief, because a system built without one fills
its gaps with the model's defaults, and those defaults are the slop. Every
token traces back to an answer in the brief.
After that, screens are **assembled**, never invented. Needs something the
system lacks → it is added to the system deliberately, or the screen is
reworked. `check-design-drift.sh` catches raw hex, arbitrary values, layout
animation, emoji, placeholder text, generated-UI copy, and unknown tokens
before a preview ever reaches you.
## Pause 2 is the interface stage, not the pixels stage
| Project type | Pause 2 designs | Design system | Proven by |
| --- | --- | --- | --- |
| Web app with UI | screens, states, motion | required | browser e2e |
| API / service | endpoint shape, payloads, status codes | skipped | API e2e |
| CLI / library | command surface, output, help, errors | skipped | invoking the built artifact |
| Data / LLM app | input and output contract, prompt shape | skipped | fixture run, plus evals |
Detected from the repo, never asked twice.
## Verified reviews, sized to the diff
No raw finding reaches you. Each one is re-judged by a `finding-verifier` that
sees only the bare claim — never the finder's reasoning, because a verifier
shown the reasoning agrees with it — and defaults to false-positive.
Diffs of five files or fewer get one reviewer and one verifier per finding.
Larger diffs get a reviewer per chunk and three verifiers per finding with a
2-of-3 majority. Breadth scales with the diff. The verification bar never does.
## Voice
One shared reference every stage loads. No consultant vocabulary, no emojis,
no summary of a three-line thing, no compliment before an answer. Say the
thing first, say the number, and say "I don't know" when that is the truth.
The sentence rules come from ASD-STE100, Simplified Technical English. An
instruction has 20 words or fewer, and a description has 25 or fewer.
## Learning
Lessons are captured without being asked — your corrections, blockers,
recurring review findings — into the target repo's `docs/learnings/`. A
SessionStart hook replays the index every session. `/learn consolidate` merges
duplicates, drops stale entries, and promotes real conventions into
`CLAUDE.md`, so the store does not rot.
## What it does
A personal Claude Code plugin marketplace with one plugin, zuko: a delivery workflow
that takes a rough idea to a shipped vertical slice. Used by its author across personal
projects.
## Install and run
| Task | Command |
| ------- | --------------------------------------------------------------------------------------------------- |
| install | `/plugin marketplace add dzaffren/claude-plugin` then `/plugin install zuko@dzafran-claude-plugins` |
| run | `/shape` in a Claude Code session |
| test | `bash plugins/zuko/scripts/tests/run.sh` |
## Features
- Guards match the git command that actually runs, not text inside arguments
- One naming format for branches, commits and PRs, and no Claude attribution
- Writes and loads a living project overview; /ship keeps it current
- A README block rendered from the overview and checked at ship time
- An append-only DECISIONS.md, loaded every session and enforced by /review
- Seeds DECISIONS.md from a repo's existing ADRs
- /ship writes plain-language CHANGELOG.md lines, enforced by the ship gate
- /release cuts a version from the commits: changelog, tag, GitHub release
- /review judges security against OWASP Top 10:2025, with a category and severity on every finding
- Test checks on text over 64 KB pass or fail for the right reason
- /release pentests the code since the last release; a proven critical or high blocks it
- /review judges what a diff introduced: a deleted guard or changed caller is a finding, silent failures are A10, untested auth is coverage
- /release on a GitLab origin says it supports GitHub only, instead of promising a GitLab slice that was dropped
- A shape cannot be Shaped, or a spec Refined, with an Open ledger row; a shape hands a later slice's question forward
- The attribution hook blocks a gh pr create whose body or title signs Claude's name
- The ship gate reads a Mermaid decision node as diagram syntax, not an unfilled placeholder
- A commit is judged on the branch and staged diff of the directory it runs in, so worktree commits pass the guards and secrets staged there are scanned
- /design-system builds the product's design system as its own command; /design is for screens and points its old system form at the new name
- Diagrams in terminal replies are drawn in ASCII; Mermaid stays the source in specs and pages
- /shape KEY starts the shape from that Jira ticket when Jira is connected, and never writes to Jira
- Spec and shape templates end with a Glossary, and the spec gate fails a live doc that uses a listed jargon term without defining it
- /design-system takes a Figma frame link when Figma is connected and builds the brief from that frame's variables and styles
- /release also attacks a running web app with real requests, checking broken access control and authentication; a guard holds every request to the one host you named
- /release makes its own commit on main again: the guard lets through exactly the commit cut prepared, and the commit guards block a hook payload they cannot read
- The design drift gate runs under macOS's default bash, and a scanned file's name can no longer make it write a file
- The pentester fence no longer allows awk, sed, sort, uniq or file, which ran a shell or wrote files the fence never saw
- The release commit's exception on main refuses an unquoted brace or glob, which bash expanded into extra files in the commit
- The force-push guard blocks every spelling git forces with: a + refspec, a bundled -f, --mirror, and a brace or glob the shell expands
- The Stop hooks judge only the zuko docs this work changed, so runbooks, other tools' specs and old breaches no longer fail a turn
- zuko writes to the ASD-STE100 writing rules, a published standard you can check it against, and every skill and agent reads them
- At each pause, /spec and /shape ask every open question and assumption in the question prompt, recommended answer first; a pause is approved only with no Open row
- /build and /review run to the end without asking; each choice they make alone is a Decided alone row in the spec, which does not block
- /ship opens the PR with each choice made without you, then the review result, then what ships; the ship gate fails a choice with no undo, or a spec with no review
- The guards' shared command parser refuses a command over 64 KB, and block-dangerous blocks it, so no guard takes 20 s and no long command times a guard out
- The guards' parser reads # comments as bash does, and block-dangerous blocks a command the parser cannot read, so a comment or a broken line no longer hides a force push or a commit on main
- The attribution hook reads gh pr edit and gh pr merge as it reads gh pr create, so a replaced PR body or a merge commit message cannot sign Claude's name
- The guards' parser refuses a `<<` inside `(( ))`, `$(( ))`, `$[ ]` or `${ }`, where bash reads a shift, so it no longer hides the lines after it
- The attribution hook gives each value option of gh pr create and gh release create its value, so a value option before the body or the notes no longer hides a signed text
- The hook and gate scripts give grep -q its text with a here-string, not a pipe, so a slow printf can no longer turn a match into a miss and let a force push, a commit on main or a staged secret pass
- The guards' parser refuses a heredoc inside a double-quoted $( ) or backticks when a line of its body changes the parser's quotes, so it no longer hides the lines after it
- /ship marks a slice Shipped in the slice's own PR, with the README and the lessons, so no slice needs a second, status-only PR after the merge
- Each idea gets one claude.ai board with its slices in order, each slice's stage, diagrams and decisions; every stage republishes it
- At each /spec pause and the end of /shape, the board shows what waits for you, what is settled and what changed since the last stop; the terminal prints only the board link, one picture and the questions
- The board shows each built slice's scenarios next to the tests and files its spec names, with the choices made without you; the PR body links the board
- The hub page lists every idea with its board link, how many of its slices shipped and a mark per slice; /shape now publishes the hub too
- The board steps through each commit that changed an idea's shape or specs, with the commits of squash-merged PRs read from GitHub, and shows what moved and what changed at each step
- The spec gate fails a zuko doc in which a code block swallows the text after it, so a broken spec can no longer reach a commit and mislead the board, the gate card and the PR body
- The board refuses a shape whose Slices table names a slice with a / or \\, so a slice name can no longer read a file outside docs/specs into a published board
- /spec pause 2 and /design open each preview in headless Chrome, light and dark, and stop it when a colour, font size, font family or corner radius is not a design system token
- The vendored taste skill moves to v2.1.5, pinned by tag; /design-system deals directions with it, /spec and /design inspect previews with it, and each design stage says when a newer release is out
- A Windows clone of zuko gets every script and skill with LF line ends, as on Linux and macOS, so a test that reads a skill file across a line end no longer fails on Windows only
- On Windows, the attribution, main-branch and secret-scan guards read Git Bash paths such as /tmp/... and block a message they cannot read, and the pentester fence lets proofs into its scratch copy but not out of it
- Each Python script that zuko starts reads and writes UTF-8 with LF on every OS, so on Windows the board renders, and the PR body, the session-start decisions and the release guard show and compare the same text as on Linux
- The release pentest also hunts with the Cloudflare attack-class files that match the code in the range, such as prompt injection in agents and plugin trust, and the report names each class file it assessed or skipped
- The release pentest keeps each lead it traced but could not prove under Needs validation, with the one fact that settles it; a lead has no severity and never blocks, and the release notes count the leads
- Each release pentest records the files it checked in a committed coverage ledger, and also checks up to 10 files that no run has checked yet, so code older than the last tag gets covered over a few releases
- The test suite runs on Windows Git Bash with a 600 s limit for each file and a named SKIP for a setup that Windows refuses, and a windows-latest job runs it on each push of the branch; zuko finds gh and bash on PATH as Git Bash does
- Each path that zuko prints, writes or compares uses / on every OS, so on Windows DECISIONS.md, the spec gates, the board and /release give the same paths as on Linux
- With strix 1.7.0 or newer, an LLM key and Docker, /release also runs Strix on its own copy of the release; zuko's blind verifier checks each Strix finding, a confirmed critical or high blocks the release, and a missing Strix gets a pinned install offer
- On Windows, zuko's hooks and gates start git and cygpath from PATH only, so a git.exe or cygpath.exe at the root of a project never runs, and a program that is not on PATH fails as not found
- When the release pentest targets a staging URL, the Strix run also attacks that app with real requests, after a yes each run that names the host, the missing guard and the data loss; a live finding blocks only through its code location
- Each inline Python call in a zuko hook runs in isolated mode, so a json.py at the root of a project or on PYTHONPATH never runs from a hook and never turns a block into a pass
- Each PR to main runs the test suite on windows-latest and ubuntu-latest, and main requires both checks, so a test that passes on one OS only can no longer merge; the repo admin still pushes the release commit straight to main
- On Windows, the rendered drift check stops Chrome with the taskkill.exe in System32, so a taskkill.exe at the root of a project never runs
- The pentester fence judges each command with \\ as /, as Git Bash reads it, and again as typed, so on Linux and macOS a write to a \\ sibling of the scratch dir no longer passes
- The rendered drift check starts only a browser at an absolute path, so a chrome.exe planted in a repo never runs from /spec pause 2 or /design on Linux and macOS
- /review keeps each lead it traced but could not settle under Needs validation, with the one unknown fact and a check, and the PR body shows it
- The git guards now block a force push or a commit on main hidden behind an unreadable heredoc delimiter, a newline in a quoted argument, or --attr-source, --config-env or --shallow-file
- The git guards now see a git call that bash runs inside another command: a $( ) or backticks in double quotes or a heredoc body, and a bash -c or eval string
- The git guards now read a path to git or gh, git's dashed form, and an inline -c alias, and refuse an alias whose value the command does not show
- The pentester fence blocks a tar option that runs a program, reads options from a file or reads a remote archive, in the repo and in the scratch copy
- The secret scan reads what each commit takes: the work tree for -a, the named paths for git commit , and every diff as plain text whatever the repo's attributes say
- On main, the commit guard also blocks merge, cherry-pick, rebase, pull, revert and am; a --ff-only merge or pull and --abort still pass
- The commit guard follows a git checkout or git switch to main earlier in the same command, and checks a commit in an unknown dir in each dir the command names
- The git guards read the aliases and push refspecs in git's config, and block a push that deletes main or master on the remote
- The attribution guard reads --trailer on git commit and git tag, the message of git merge, and the value of each value option
- The rm guard blocks a recursive delete of /, a path one level under /, or a home dir, in every spelling that bash and rm read
## Docs
- [Overview](OVERVIEW.md)
- [Architecture](docs/ARCHITECTURE.md)
- [Decisions](DECISIONS.md)
- [Changelog](CHANGELOG.md)
## Replaces shipwright
zuko is a clean rebuild of the former `shipwright` plugin. The marketplace
carries a rename, so an existing install migrates. `/spec` reads an old
shipwright spec and offers to migrate it rather than choking on it.
## Licence
[MIT](LICENSE)