tvproductions/gzkit / .agents/skills/gz-how
gz-how
VerifiedUse when the operator asks "how do I …?" or "what can I …?", or when unsure which skill applies or two look alike.
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 (agent starts it when the operator calls for R&D) | 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 |
| run a repair or delivery as a work package | gz-wp |
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 aCHECKPOINTto 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 ingz-session-handoff§ Three subjects.
See Session end.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |