gz-how
The map of how gzkit's skills fit together. Every skill belongs to a flow: a
path work travels, with an order, branches, and steps only the operator may take.
Find the flow, then say where the question sits in it.
This skill answers; it never acts and reads no project state. "What should I do
next here?" is gz-status's question: it reads the ledger and the campaign.
How to answer
- A question. Match it in the question index, open the flow file it names
under
references/, and answer in this shape:
- Flow: the flow, and where the question sits in it.
- Run: the skill. Name a bare
uv run gz … command only when no skill
wraps the task.
- Not to be confused with: the look-alike, when there is one.
- Only you can: the steps reserved to the operator, if any.
- Then: the next step in the flow.
- No question. Answer "what can I do?": one line per flow, then the catalog.
- No match. Say the question is not covered and show the flows. Never
guess a skill. When an agent consulted this, it then runs the Run line
itself.
Question index
| How do I … / what can I … |
Flow |
| set up gzkit in a repository, write a constitution or PRD |
Project setup |
| start or resume a session, see where things stand |
Session start |
| turn an idea into an ADR, design something, promote a pool ADR |
Idea to ADR |
| implement an OBPI, resume a pipeline, attest a brief |
OBPI delivery |
| close out or validate an ADR |
ADR closeout |
| cut a release |
Release |
| report, triage or fix a defect; file an issue |
Defects and GHIs |
| check, commit, push, sync mirrors |
Commit and sync |
| change AGENTS.md or another canon surface |
Canon content |
| handle a complexity crossing |
Complexity |
| run a chore, reduce tech debt, upgrade dependencies |
Codebase upkeep |
| validate governance surfaces, audit CLI docs, fix config paths |
Surface integrity |
| find out whether gzkit really works as intended |
Does it work? |
| repair governance, undo a completion |
Repair |
| learn from outside tools or projects |
Looking outward |
| trace what relates to what |
Traceability |
| end a session or a phase |
Session end |
| add, review or retire a skill |
Skill maintenance |
What can I do? (catalog)
Every active skill, under its flow. gz validate --how-coverage fails when a
skill is missing here, so this list cannot fall behind the catalog.
Project setup
| Intent |
Skill |
| install gzkit's scaffolding in a repository |
gz-init |
| write or refresh the constitution |
gz-constitute |
| write product requirements |
gz-prd |
Session start and end
| Intent |
Skill |
| resume the last session, or write this one's handoff |
gz-session-handoff |
| see workflow fronts, blockers and next actions |
gz-status |
| enter or leave a unit of work; ad-hoc reconnaissance |
gz-airlock |
| step back for the whole-project view (operator-invoked) |
gz-big-picture |
Idea to ADR
| Intent |
Skill |
| shape an idea through design dialogue |
gz-design |
| frame an open problem whose outcome is unknown (operator-invoked) |
gz-rnd |
| book an ADR with its OBPI briefs |
gz-adr-create |
| scaffold an ADR from the CLI |
gz-plan |
| score an ADR and its OBPIs |
gz-adr-evaluate |
| reason through a case before implementing |
gz-justify |
| promote a pool ADR |
gz-adr-promote |
| author or finish an OBPI brief |
gz-obpi-specify |
OBPI delivery
| Intent |
Skill |
| audit the plan against the brief before coding |
gz-plan-audit |
| run an OBPI from plan to attested completion |
gz-obpi-pipeline |
| claim or release an OBPI lock |
gz-obpi-lock |
| check a brief against the project tree |
gz-obpi-brief-drift |
| review an OBPI's code for reuse and quality |
gz-obpi-simplify |
| wrap QA commands in receipts for attestation |
gz-arb |
| run Gate 2 for one ADR |
gz-implement |
| reconcile briefs and the ADR table from the ledger |
gz-obpi-sync |
ADR closeout and release
| Intent |
Skill |
| reconcile an ADR's evidence and ledger state |
gz-adr-sync |
| witness and attest ADR completion |
gz-adr-closeout-ceremony |
| audit a completed ADR to Validated |
gz-adr-audit |
| record an ADR receipt event |
gz-adr-emit-receipt |
| show ADR lifecycle and OBPI detail |
gz-adr-status |
| cut a GHI-driven patch release |
gz-patch-release |
Defects and GHIs
| Intent |
Skill |
| file an issue from inside gzkit |
ghi-author |
| file an issue against gzkit from an adopter repo |
gz-issue-file |
| rank the open issue queue |
ghi-triage |
| do an issue's work and close it |
ghi-close |
| record a course-correction, defect or discovery |
gz-insights-remember |
Commit and sync
| Intent |
Skill |
| run the per-change quality gate |
gz-check |
| commit and push through the guarded ritual (operator-invoked) |
git-sync |
| regenerate mirrors after a skill or canon edit |
gz-agent-sync |
Canon content
| Intent |
Skill |
| capture an entry into a surface's corpus |
gz-content-remember |
| stage a candidate rendition |
gz-content-compose |
| judge a candidate rendition before attestation |
gz-advisor-qc |
| trim per-turn instruction load |
gz-context-diet |
Complexity
| Intent |
Skill |
| preview complexity hints while writing |
gz-complexity-guide |
| read the advisor's diagnosis of a crossing |
gz-complexity-advisor |
| refresh the distilled complexity doctrine |
gz-complexity-distill |
Codebase upkeep
| Intent |
Skill |
| run a maintenance chore |
gz-chore-runner |
| survey technical debt |
gz-tech-debt-review |
| find Java-flavoured shapes to make Pythonic |
gz-pythonic-pattern-detect |
| record the evidence for an applied rewrite |
gz-pythonic-pattern-apply |
| upgrade uv, Python and dependencies |
gz-deps-upgrade |
| rank the foundation backlog |
gz-foundation-triage |
| report maintenance findings |
gz-tidy |
Surface integrity
| Intent |
Skill |
| run governance validators |
gz-validate |
| audit CLI manpage and index coverage |
gz-cli-audit |
| check configured and manifest paths |
gz-check-config-paths |
| record bare-to-slug ID renames |
gz-migrate-semver |
Does it work?
| Intent |
Skill |
| run the four-axis health audit (operator-invoked) |
gz-health-audit |
| trace declared intent to shipped surface |
gz-intent-trace |
| prove a workflow end to end on a target repo |
gz-flighttest |
Repair
| Intent |
Skill |
| enter or leave the maintenance hangar |
gz-mx |
Looking outward
| Intent |
Skill |
| scan competitor tools for moves (gzkit repo only) |
gz-competitor-radar |
| scan AirlineOps governance parity (gzkit repo only) |
airlineops-parity-scan |
Traceability
| Intent |
Skill |
| query the artifact graph and readiness |
gz-state |
| map an ADR to the artifacts it produced |
gz-adr-map |
| image the governance shape and a node's blast radius |
gz-ontology |
Skill maintenance
| Intent |
Skill |
| review a skill against the code it wields |
gz-skill-review |
Namespace routers
Each picks a skill by intent; this guide explains the flow the skill sits in.
All are operator-invoked.
| Intent |
Skill |
| design through release |
gz-workflow |
| ADR, OBPI and ledger governance |
gz-governance |
| quality and complexity |
gz-quality |
| project lifecycle |
gz-project |
| context preservation and orientation |
gz-context |
| repository and release management |
gz-manage |
| maintenance chores |
gz-chores |
Not in the catalog
Look-alikes
| You want |
Use |
Not |
| where things stand and what to do next |
gz-status |
this guide (what is possible) or gz-state (the artifact graph) |
| relationships, what is unattested, what is ready |
gz-state |
gz-status (fronts and next actions) |
| whether one OBPI is complete |
uv run gz obpi status, a command |
gz-state (its completion is Layer 2; read the ledger) |
| one ADR's lifecycle |
gz-adr-status |
gz-state |
| the per-change gate |
gz-check |
gz-implement (Gate 2 for one ADR, writes the ledger) or gz-validate (one validator) |
| a brief checked against the code tree |
gz-obpi-brief-drift |
gz-obpi-sync (brief against ledger evidence) or gz-adr-sync (a whole ADR, every layer) |
| an issue filed from inside gzkit |
ghi-author |
gz-issue-file (from an adopter repository) |
| a correction, defect or discovery recorded |
gz-insights-remember |
gz-content-remember (changes canon) |
| an idea you can state, shaped |
gz-design |
gz-rnd (open problem, outcome unknown) or gz-plan (an ADR already decided) |
| one issue's work done |
ghi-close |
ghi-triage (ranks the whole queue) |
| code reviewed |
gz-obpi-simplify |
gz-tech-debt-review (a debt survey) |
| attestation evidence |
gz-arb |
gz-check (a bare run produces no receipt) |
| complexity help while writing |
gz-complexity-guide |
gz-complexity-advisor (a crossing at commit) or gz-complexity-distill (the doctrine) |
| to know whether it really works |
gz-intent-trace |
gz-health-audit (it feels wobbly), gz-flighttest (prove a flow), gz-big-picture (the wide view) |
| Gate 5 on an ADR |
gz-adr-closeout-ceremony |
gz-adr-audit (verification after attestation) |
| governance repaired |
gz-mx |
gz-airlock (reconnaissance with light repair at most) |
| session memory |
gz-session-handoff |
gz-airlock (transit) or gz-obpi-lock (occupancy) |
| a skill picked by intent |
a namespace router |
this guide (the flow around it) |
Phase boundaries
Decide at a boundary between phases, never mid-phase; mid-phase, continue or
hand a bounded track to a subagent.
- Continue when the next phase needs this one verbatim: design into booking
the ADR, plan into the pipeline.
- Subagent for a bounded, independent track, dispatched with its Why
(
AGENTS.md § Behavior Rules).
- Compact when the context still matters and the session continues;
CLAUDE.md § Compact Instructions says what must survive.
- Clear when nothing here matters next; the ledger and the handoff chain
carry the state.
- Handoff (
gz-session-handoff) at the end of every session, and as a
CHECKPOINT to bookmark mid-flight. In gzkit a handoff is session memory and
carries the operator's rulings forward, not only a way to move work elsewhere.
- Airlock (
gz-airlock) when entering or leaving a unit of work. Transit,
exchange and handoff are three subjects; the ruling that separates them is
carried verbatim in gz-session-handoff § Three subjects.
See Session end.