zstack
/zstack
Routes a non-trivial engineering goal to a playbook, an execution shape and a set of cited principles. Use for bugs and bug tickets (cause known or unknown), explaining how a system works or why it is built that way across files, choosing between approaches ("which approach should we take?"), turning an open or vague ticket into a spec, new features, refactors, performance work, code or PR review, opening and landing PRs, "what should I test today", running work in parallel or overnight, "is it live" or "did it ship", taking over another agent's work, pausing cleanly, or when the human says th
- Author
- simsketch ↗
- Repository
- zstack ↗
- Licence
- MIT
- Last repository change
- 08.11.2026
Assessment and security
- Files in this package
- 91
- Scripts
- 14
- HTML comments
- 0
- URLs in SKILL.md
- 1
No signals detected. Repository changed on 08.11.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- 14 scripts in this package. Review them before installing, as Claude may execute them.
Scripts: example/run-trigger-tests.sh, example/setup-demo.sh, scripts/checklist.py, scripts/classify.sh, scripts/ledger.py, scripts/lib.sh, scripts/trust.sh, scripts/zcheck.sh, tests/helpers.sh, tests/run.sh, tests/test_checklist.sh, tests/test_classify.sh, tests/test_ledger_trust.sh, tests/test_zcheck.sh
What it does and when to use it
Routes a non-trivial engineering goal to a playbook, an execution shape and a set of cited principles. Use for bugs and bug tickets (cause known or unknown), explaining how a system works or why it is built that way across files, choosing between approaches ("which approach should we take?"), turning an open or vague ticket into a spec, new features, refactors, performance work, code or PR review, opening and landing PRs, "what should I test today", running work in parallel or overnight, "is it live" or "did it ship", taking over another agent's work, pausing cleanly, or when the human says th
Triggers from the description
Original author description
Routes a non-trivial engineering goal to a playbook, an execution shape and a set of cited principles. Use for bugs and bug tickets (cause known or unknown), explaining how a system works or why it is built that way across files, choosing between approaches ("which approach should we take?"), turning an open or vague ticket into a spec, new features, refactors, performance work, code or PR review, opening and landing PRs, "what should I test today", running work in parallel or overnight, "is it live" or "did it ship", taking over another agent's work, pausing cleanly, or when the human says th
How it works
- When it applies
- On activation
- Execution shapes
- Playbook catalog
- Principle index
- Evidence and gates
- Drive-by fixes
- Human-busy mode
- Briefing subagents
- Scripts and templates
SKILL.md preview
---
name: zstack
description: Routes a non-trivial engineering goal to a playbook, an execution shape and a set of cited principles. Use for bugs and bug tickets (cause known or unknown), explaining how a system works or why it is built that way across files, choosing between approaches ("which approach should we take?"), turning an open or vague ticket into a spec, new features, refactors, performance work, code or PR review, opening and landing PRs, "what should I test today", running work in parallel or overnight, "is it live" or "did it ship", taking over another agent's work, pausing cleanly, or when the human says they are busy testing. Answers to /zstack. Skip for one-line questions and trivial edits.
license: MIT
metadata:
version: "1.2.0"
source: "https://github.com/simsketch/zstack"
---
# zStack
A goal goes in. A playbook, an execution shape and a short list of principles come out, and every
decision you make afterwards names the principle behind it.
`<zstack dir>` is the folder that holds this SKILL.md. Every `scripts/` and `templates/` path in this
skill, its playbooks and its briefs is relative to it, and a subagent brief passes the absolute
`<zstack dir>` (the `{{ZSTACK_DIR}}` slot in the worker-brief template).
The repo's own rules (CLAUDE.md, AGENTS.md, CONTRIBUTING and the like) outrank this skill. When they
conflict, follow the repo and say which rule won.
## When it applies
Use zStack when the work has more than one reasonable path, touches more than one file, or ends in a
claim someone will rely on ("fixed", "shipped", "safe to merge"). Typical inputs:
- a bug whose cause is unknown, or a bug ticket
- a feature, refactor, performance problem or prototype question
- a review of a PR, branch or diff, or a PR to open, babysit or land
- a queue of tickets to run while the human is away
- "is it live?", "what should I test?", "pick this up", "stop here for today"
Skip it for one-line questions, a lookup, or a trivial edit the human has fully specified (rename this,
fix this typo). Answer those directly.
## On activation
Work through these seven steps in order, every time.
1. **Restate the goal and the definition of done** in one or two lines, and triage it **clear** or
**open**. Clear: done is testable and no product choice (behavior, copy, a default, a flow) is left to
the builder. Open work that is anything other than an investigation routes through `spec-pass` first
(`Route: spec-pass -> feature`); for a single small gap, ask one question instead. In human-busy mode,
write the question to the decision page, record a default and flag it `revisit`.
2. **Pick a playbook** from the catalog below. Overrides come before narrow matches: work the human wants
to walk away from, or that spans days, goes to `autopilot-queue` (or a fleet wave when zstack-fleet is
installed); "which approach is better?" goes to `prototype`. When the human is also busy, human-busy
mode wraps the work and the work itself routes by these rules (a queue of tickets:
`autopilot-queue`). When nothing fits, write a one-off playbook in the same shape as the shipped ones
and save it under `.git/zstack/playbooks/<name>.md` so the next session can reuse it.
3. **Pick an execution shape** from the signals in the next section.
4. **State the route in one line**, in exactly this format:
```
Route: <playbook>[ -> <chained playbook>], shape: <inline|one subagent|lane|fleet wave>, principles: <p1>, <p2>[, ...]
```
Example: `Route: debug -> bug-class-sweep, shape: one subagent, principles: reproduce-first, fix-the-class, evidence-before-the-word`
5. **Copy the playbook's steps into your todo list word for word.** A step you skip stays in the list,
marked skipped, with the reason.
6. **Read each principle leaf before applying it** (`references/principles/<name>.md`). You may cite
only principles whose leaf you read in this session. Every final reply and PR body names the
principles that shaped a decision and what each one changed.
7. **Propagate down.** Every subagent brief starts with "Read the zstack router first", then the chosen
playbook, then the principles in force (see "Briefing subagents" below).
## Execution shapes
| Shape | What it is | Pick when |
|---|---|---|
| inline | this session does the work itself | one area, small, done is clear, or the harness cannot run subagents |
| one subagent | one background worker in its own worktree; this session coordinates | one area, but long enough to crowd your context, or the human wants to keep talking |
| lane | 2-6 workers in parallel worktrees, one coordinator, merges one at a time | several pieces that each merge and revert on their own, with predicted files disjoint |
| fleet wave | many lanes across repos or accounts with lane leads, a merge desk and a safety net | zstack-fleet installed, its accounts check green, quota under pace, merge mode Normal |
Read every signal, in order. Each one can only shrink the shape, never grow it, and the smallest shape
left after all six is the one you run.
1. **Definition-of-done clarity.** While done is unclear, stay at inline or one subagent. In a queue,
open tickets wait for their `spec-pass` while clear ones run.
2. **Predicted file overlap.** Pieces that are likely to edit the same files join one lane or run in
sequence.
3. **Solo classes.** Migrations, auth and security, infra and CI workflows, and payments each run as
their own lane, never batched with other work, and their PRs open with a `hold` label. At L0 (the
solo default) the PR opens as a draft and the human takes it over.
4. **Harness capability.** Look up what this harness can do in `references/harness-capabilities.md`.
With no background subagents, lanes run in sequence, or as headless runs where the harness has a
headless mode.
5. **Fleet signals** (only with zstack-fleet installed): merge mode, quota pace, CI budget headroom and
drift of the open queue. A Slow or Drain merge mode caps new work and points workers at open PRs.
6. **The human's state.** In human-busy mode, prefer shapes that need no answer soon.
**Starting a lane.** Start workers a few at a time, at most three in any two minutes, and wait for
each batch to report before starting the next. A slow start spreads the load on the machine and the
repo, and a bad brief shows up after three workers instead of six.
When you choose a smaller shape than the work wanted, name the signal that capped it in one line, for
example: "wanted a lane; this harness has no background subagents, so the three pieces run in sequence."
**Fleet hand-off.** With zstack-fleet installed, read its SKILL.md before choosing fleet wave; without it
cap at lane and say so.
## Playbook catalog
Each playbook lives at `playbooks/<name>.md` and has the same shape: use when, inputs, numbered steps,
the gate that ends it, the principles it cites, and the shape it prefers.
| Playbook | Use when | Ends with |
|---|---|---|
| `investigate` | a read-only question: how something works, why it exists | an answer with file and line citations and no code change |
| `debug` | a bug whose cause is unknown | a reproduced, root-caused, tested fix, then chains to `bug-class-sweep` |
| `bug-class-sweep` | a bug's cause is known, or a bug ticket arrives | every instance classified and fixed or ticketed, a guardrail, and a note on why tests missed it |
| `perf` | slowness someone measured or can measure | before and after numbers taken on the same baseline |
| `feature` | new behavior | data shape and owner named first, tests first where the repo has tests |
| `refactor` | a structure change that must keep behavior | proof behavior held: passing tests or a recorded diff of outputs |
| `prototype` | "which approach?" | a throwaway comparison that settles the choice, and the decision written down |
| `spec-pass` | an open ticket: no testable done, or a product choice left to the builder | a written spec with every question answered or flagged `revisit`, then the playbook it routes to |
| `review` | review a PR, branch or diff | a verdict of PASS, CHANGES NEEDED or FIX FIRST with findings by severity |
| `babysit-pr` | drive an open PR to merge-ready | conflicts resolved, threads answered, checks recorded at the head commit |
| `land` | open or land a PR | small ordered commits, the evidence packet in the body, merge pinned to the verified head |
| `autopilot-queue` | a queue of independent tickets to run to merged, often unattended | one owner per ticket, a second agent verifying, merges within the trust ladder |
| `verify-release` | "is it live?", "did it ship?", "is it deployed?" | implemented, deployed and verified stated separately with machine evidence |
| `manual-test-checklist` | "what should I test today?", or the end of a merge batch | an ordered checklist per environment, with results written back to the PRs |
| `pickup` | take over another agent's or person's in-flight work | state read from disk and the handoff file, the plan restated before any edit |
| `pause` | stop cleanly for now | a handoff file and a WIP commit, with nothing left only in a working tree |
| `human-busy` | the human says they are busy, or two questions sit unanswered for 30 minutes | one decision page, safe defaults flagged `revisit`, work continuing on what needs no answer |
Chains: `spec-pass` continues into the playbook the clarified goal routes to. `debug` always continues into `bug-class-sweep` once the cause is known. Work that ends in a PR
continues into `land`. A failed item on a manual-test checklist opens a bug, which starts `debug` or
`bug-class-sweep`.
## Principle index
Each principle has a leaf at `references/principles/<name>.md` with the rule, why it exists, and the
checks that show you followed it. Read the leaf before you cite it.
**Method**
- `reproduce-first`: when fixing a bug. No fix lands before a reproduction, or a written reason why one
is impossible.
- `fix-the-class`: when a cause is known. Search for every sibling of the bug before calling it fixed.
- `smallest-reversible-change`: when shaping commits and PRs. One ticket per change, and each commit
can be reverted alone.
- `data-shape-first`: when starting a feature. Name the data, its shape and its owner before any UI or
endpoint.
- `subtract-first`: when about to add code, config or a dependency. Try removing or reusing first.
- `one-copy-of-domain-logic`: when about to write a helper or change domain logic. Search first, list
what you reused under `## Reused`, change every copy, and never add a second copy of business rules,
money, dates, permissions, masking, pricing or shared copy.
- `walk-the-edge-classes`: before calling a change done. Answer every class in
`references/edge-cases.md` as N/A with a reason, covered by a named test, or open with the risk.
**Evidence**
- `evidence-before-the-word`: when about to say shipped, live, fixed or passing. Each word needs machine
evidence at a named commit.
- `three-words`: when reporting status. Implemented, deployed and verified are reported separately.
- `empty-check-fails`: when reading a check result. A check that ran zero tests failed.
- `numbers-from-tested-queries`: when giving a human a number. It comes from a named, tested query, or
it is marked unverified.
**Parallel work**
- `one-owner-per-file`: when splitting work across workers. Each hot file is leased to one lane.
- `rebase-once-late`: when branches fall behind. Rebase at merge time, oldest PR first, once.
- `count-the-living`: when counting workers. A worker counts only if it produced output in the last 10
minutes.
**Safety**
- `report-the-guard`: when a hook, guard, limit or permission blocks you. Report it and stop; never
route around it.
- `secrets-stay-in-process`: when work touches credentials. Never read or print a credential file.
- `stop-by-pid`: when stopping a process. Stop it by a pid you captured or a path in your own worktree.
**Human**
- `ask-with-options`: when a decision is needed. Product, scope, money, data deletion, security,
production and disputes go to the human with options and a recommendation; answer everything else
from code, docs or prior words, and cite the source.
- `leave-it-better-separately`: when you notice an unrelated defect. Fix it in its own tagged commit if
it passes the drive-by test; otherwise ticket it.
- `spend-attention-carefully`: when you have questions. Batch them, and keep working on whatever does
not depend on the answers.
- `list-your-assumptions`: when you settle an open product or behavior choice yourself. List it with why
under `## Assumptions`; a product call opens the PR with `hold`.
**Meta**
- `name-what-changed`: in every final reply and PR body. Name the principles that shaped the work and
what each one changed.
## Evidence and gates
Three words, kept apart in every report (details in `references/evidence.md`):
- **implemented**: merged, with the merge sha
- **deployed**: running in a named environment, proven by the serving artifact containing the commit
- **verified**: someone checked the behavior there, with who and when
Never write "shipped" or "live" without the deployed evidence.
Every PR body also carries `## Assumptions` (each open product choice the author made, with why, or
`None.`) and `## Edge cases` (one line per class in `references/edge-cases.md` and the repo's
`.git/zstack/edge-cases.md`), and `## Reused` (what existing code it used or extended). A product-call assumption, or an `open` edge case on money, permissions or
personal data, keeps the PR with the human (`hold`) until they answer.
Four gates before a merge:
1. A check counts only when recorded on a clean tree at the PR head commit:
`<zstack dir>/scripts/zcheck.sh --name <n> -- <cmd>`, confirmed with `<zstack dir>/scripts/zcheck.sh --verify <sha> <name>...`.
Zero tests fails.
2. The merge is pinned to the verified head (`gh pr merge --match-head-commit <sha>`).
3. One merge at a time per repo.
4. Sensitive classes open with `hold` (as drafts at L0); a push after review needs a delta review
before the hold comes off.
A PR's class comes from `<zstack dir>/scripts/classify.sh` (riskiest file wins, unmatched files count as `feature`).
You may raise a class by hand and never lower it. How much you may do alone is set per class by the
trust ladder: L0 draft only (a draft PR labelled `hold` that the human takes over), L1 open, L2 merge
on evidence, L3 batch (fleet only). Check it with `<zstack dir>/scripts/trust.sh --gate <class>`, and
record each merge with `<zstack dir>/scripts/ledger.py add`. Only the human raises a level. The full ladder and class rules are in `references/evidence.md`; every state file is
listed in `references/state.md`.
## Drive-by fixes
An unrelated defect you notice may ride in the same PR only when all of these hold: one file (or one
file plus its test), it has a test or is a pure typo, dead import or comment fix, the file is outside
solo classes and nobody else's lease, and it is under about 20 changed lines. It goes in its own commit
with the subject prefix `drive-by:` and a line under `## Drive-bys` in the PR body. Anything larger
becomes a ticket listed under `## Follow-ups` with its evidence. Full rule: `references/drive-by.md`.
## Human-busy mode
Enter the `human-busy` playbook when the human says they are occupied ("I'm testing for the next two
hours", "in meetings until 3"), or on your own after two questions have gone unanswered for 30 minutes.
Questions then go to one decision page (`.git/zstack/decisions.md`, from `<zstack dir>/templates/decision-page.md`),
the human gets one short message when the page changes, and work continues on whatever needs no answer.
Safe, reversible defaults proceed flagged `revisit`; anything on the `ask-with-options` list waits.
## Briefing subagents
Every brief you hand a subagent, worker or headless run starts with these lines, in this order (the
full brief shape is `<zstack dir>/templates/worker-brief.md`):
1. "Read the zstack router first" and where it lives.
2. The playbook it is running, and the route line.
3. The principles in force, by name.
4. The drive-by rule, no CI polling loops, no credential reads, and "report any guard that blocks you".
5. The spec path from `spec-pass` (or "clear as written"), and that the PR lists its assumptions and
answers the edge-case checklist.
A worker that receives a brief without these lines asks for them before starting; a headless run that
cannot ask stops and reports the missing lines.
## Scripts and templates
Scripts (bash 3.2 and Python 3 standard library, state under `.git/zstack/`):
- `<zstack dir>/scripts/zcheck.sh`: record a check at the head commit, `--verify` before merge, `--list` to see them
- `<zstack dir>/scripts/classify.sh`: compute a PR's class from its files (`--pr <n>`, `--base <ref>`, `--files <file>`)
- `<zstack dir>/scripts/ledger.py`: record merges, reverts and bugs; `stats`, `export`, `import`
- `<zstack dir>/scripts/trust.sh`: per-class track record and effective trust level; `--gate <class>`
- `<zstack dir>/scripts/checklist.py`: `generate` the manual-test checklist and `record` results back to PRs
Edge-case checklist: `<zstack dir>/references/edge-cases.md`.
Templates: `<zstack dir>/templates/pr-body.md`, `decision-page.md`, `sweep-report.md`, `handoff.md`,
`worker-brief.md`, `classes.conf`, `config`, `smoke.md`.
## Closing every task
End with a reply that carries the route line, what was done, the three evidence words where they apply,
and one line per cited principle saying what it changed. If you followed a repo rule over this skill,
name it.
Files in this package (91)
- SKILL.md 17 KB
- example/run-trigger-tests.sh 7 KB
- example/setup-demo.sh 8 KB
- example/trigger-prompts.txt 1 KB
- example/results/SUMMARY.md 9 KB
- example/results/plugin-install.md 7 KB
- example/results/claude/01.txt 5 KB
- example/results/claude/02.txt 4 KB
- example/results/claude/03.txt 4 KB
- example/results/claude/04.txt 4 KB
- example/results/claude/05.txt 4 KB
- example/results/claude/06.txt 5 KB
- example/results/claude/07.txt 3 KB
- example/results/claude/08.txt 5 KB
- example/results/claude/09.txt 5 KB
- example/results/claude/10.txt 4 KB
- example/results/codex/01.txt 2 KB
- example/results/codex/02.txt 4 KB
- example/results/codex/03.txt 3 KB
- example/results/codex/04.txt 3 KB
- example/results/codex/05.txt 3 KB
- example/results/codex/06.txt 6 KB
- example/results/codex/07.txt 2 KB
- example/results/codex/08.txt 4 KB
- example/results/codex/09.txt 3 KB
- example/results/codex/10.txt 2 KB
- playbooks/autopilot-queue.md 5 KB
- playbooks/babysit-pr.md 3 KB
- playbooks/bug-class-sweep.md 4 KB
- playbooks/debug.md 3 KB
- playbooks/feature.md 4 KB
- playbooks/human-busy.md 3 KB
- playbooks/investigate.md 2 KB
- playbooks/land.md 5 KB
- playbooks/manual-test-checklist.md 3 KB
- playbooks/pause.md 3 KB
- playbooks/perf.md 3 KB
- playbooks/pickup.md 3 KB
- playbooks/prototype.md 3 KB
- playbooks/refactor.md 3 KB
- playbooks/review.md 5 KB
- playbooks/spec-pass.md 3 KB
- playbooks/verify-release.md 3 KB
- references/drive-by.md 1 KB
- references/edge-cases.md 4 KB
- references/evidence.md 6 KB
- references/harness-capabilities.md 5 KB
- references/state.md 3 KB
- references/principles/ask-with-options.md 1 KB
- references/principles/count-the-living.md 1 KB
- references/principles/data-shape-first.md 1 KB
- references/principles/empty-check-fails.md 1 KB
- references/principles/evidence-before-the-word.md 1 KB
- references/principles/fix-the-class.md 1 KB
- references/principles/leave-it-better-separately.md 1 KB
- references/principles/list-your-assumptions.md 1 KB
- references/principles/name-what-changed.md 1 KB
- references/principles/numbers-from-tested-queries.md 1 KB
- references/principles/one-copy-of-domain-logic.md 1 KB
- references/principles/one-owner-per-file.md 1 KB
- references/principles/rebase-once-late.md 1 KB
- references/principles/report-the-guard.md 1 KB
- references/principles/reproduce-first.md 1 KB
- references/principles/secrets-stay-in-process.md 1 KB
- references/principles/smallest-reversible-change.md 1 KB
- references/principles/spend-attention-carefully.md 1 KB
- references/principles/stop-by-pid.md 1 KB
- references/principles/subtract-first.md 1 KB
- references/principles/three-words.md 1 KB
- references/principles/walk-the-edge-classes.md 1 KB
- scripts/checklist.py 20 KB
- scripts/classify.sh 8 KB
- scripts/ledger.py 13 KB
- scripts/lib.sh 2 KB
- scripts/trust.sh 1 KB
- scripts/zcheck.sh 6 KB
- templates/classes.conf 1 KB
- templates/config 1 KB
- templates/decision-page.md 1 KB
- templates/handoff.md 1 KB
- templates/pr-body.md 2 KB
- templates/smoke.md 1 KB
- templates/sweep-report.md 1 KB
- templates/worker-brief.md 4 KB
- tests/helpers.sh 2 KB
- tests/run.sh 1 KB
- tests/test_checklist.sh 8 KB
- tests/test_classify.sh 4 KB
- tests/test_ledger_trust.sh 6 KB
- tests/test_zcheck.sh 5 KB
- tests/stubs/gh 1 KB
Versions
The database has no other skills named zstack.
Database snapshot: 13.11.2026 · package version 559e57c108fa (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 90engineering-craft
Use when writing or changing any production code or tests — new features, bug fixes, refactors, or test authoring, in any language, by any model on any CLI. - 95implement
Implement a piece of work based on a spec or set of tickets. Use when an agreed spec or ticket set should now be built. Triggers on: implement, build this spec, work these tickets. - 100modemax
modemax, the default way of working: shape the work with the user into tickets on the issue tracker, then build each ticket with deliberate subagents, simple code, unslopped prose, and verified evidence, and ship it as a PR that closes the ticket. Use for /modemax, for any… - 100plan-mode
Holistic, system-aware planning before implementing non-trivial tasks. Use when the task involves new features, architectural decisions, multi-file changes, unclear requirements, or multiple valid approaches. Triggers on "/plan", "plan this", "design an approach", "let's plan first".