gz-how

Use when the operator asks "how do I …?" or "what can I …?", or when unsure which skill applies or two look alike.

SKILL.md

GitHub

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

  1. 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.
  2. No question. Answer "what can I do?": one line per flow, then the catalog.
  3. 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

  • gz-how — this guide.

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.