gz-plan
Use to create an ADR, a pool ADR included, recording architecture intent and lane scope.
SKILL.md.claude/skills/gz-plan/SKILL.md
GitHubgz plan
Overview
Self-Escalation (opus-tier). The dialogue with the operator stays in the main session: a subagent cannot ask the operator a question or hear the answer, and what the operator adds is this skill's primary input. When the session model is below opus-tier, you may spawn an
Agentwithmodel="opus"for a bounded drafting or QC track that needs no operator input — pass the operator's words verbatim and the relevant context (ADR IDs, OBPI IDs, prior decisions), and treat what it returns as a draft you verify, not as the operator-facing result.
Scaffold one ADR from its template and, for a non-pool kind, book it in the
ledger. uv run gz plan create <name> (plan_cmd, src/gzkit/commands/plan.py):
- refuses before any write, exit 1, when
--kindis missing (argparse gives it no default;_validate_kind_and_semverrequires it); when--kind foundationis asked in a project that has sunset the kind (foundation_kind_is_closed:data/foundation_grandfather.jsonexists, as it does in gzkit per ADR-0.34.0; an adopter without that file keeps the kind open); when--kind featurecarries a0.0.x--semver; and, for a non-pool kind, whennameis a bare semver or a bareADR-<semver>id without a slug (_reject_noncanonical_name, GHI #494); - non-pool: composes the id
ADR-<semver>-<name>(anamealready of that form is used as given), renderssrc/gzkit/templates/adr.mdwith statusDraft, a Decomposition Scorecard and a## Checklistseeded with one placeholderOBPI-<semver>-NNitem per targeted OBPI, and writes it to<paths.adrs>/pre-release/<id>/<id>.md(foundation/<id>/for an open foundation kind); - then appends
adr_createdthroughregister_adr_in_ledger, which skips an id that already has one (Ledger.has_adr_created). It exits 3 when the directory name is not a canonical id or the package is an ungrandfathered foundation, and 2 when the append fails or the id is missing from the graph afterwards, each time naminguv run gz register-adrs --allas the recovery. The ADR file is already on disk in all of those cases; - pool: writes
<paths.adrs>/pool/ADR-pool.<name>.mdfromsrc/gzkit/templates/adr_pool.md(no scorecard, no checklist, nokind:orsemver:;--semveris ignored) and books nothing: the pool branch returns beforeregister_adr_in_ledger.uv run gz register-adrsbooks pool entries.
--dry-run runs every refusal above, prints the path it would write and, for a
non-pool kind, the adr_created it would append, and writes nothing.
It creates no OBPI briefs: gz specify (skill gz-obpi-specify) authors each
brief against a checklist item. gz-adr-create is the full authoring flow that
books an ADR together with its briefs.
Scorecard. The five --score-* flags (0–2) default from
default_dimension_scores (src/gzkit/core/scoring.py), which reads the semver
and lane. baseline_range_for_total maps their total to a baseline range;
--baseline-selected picks a count inside it (default: the lower bound; a value
outside the range fails, exit 1); each --split-* flag adds one OBPI. The sum
is the number of checklist items seeded. The doctrine the numbers implement is
docs/governance/GovZero/obpi-decomposition-matrix.md § Deterministic
Decomposition Gate.
Work order (operator ruling, verbatim canon)
- Work feature ADRs in ascending semver order: the lowest version with unlanded OBPIs is in flight. Do not work, author, or recommend a higher feature ADR ahead of it. The campaign selects work but cannot override that order. If campaign sequencing conflicts, semver governs; surface the conflict to the operator rather than silently resolving it. “One feature at a time” does not authorize swapping the order. An ADR in flight may be revised to take more OBPIs. The revision updates the document (an Intent amendment, a Decision item, a checklist item and the scorecard baseline) and the briefs table in the same change. A Validated ADR is not revised: scope missed from one enters the in-flight ADR as a repair assignment that cites the obligation it repairs. An item off the ADR's theme is labelled as such in the Intent amendment. The (m)ADR is a stopgap: a release-increment bucket, meant to be thematically cohesive. Its successor is a feature bundle between an enhancement proposal and a feature specification. Names are chosen later. This replaces the exception of 2026-09-29 (GHI #871), by which a correction to a Validated ADR took the next unallocated feature semver and could be worked ahead of the in-flight ADR; that route is retired (operator rulings 2026-10-04: 'the new loosening law here is we need to be able to revise an adr to allow for more obpis - the document and briefs table gets updated'; 'A, in-flight only'; the wording and the retirement, each 'A').
Carried verbatim from root
AGENTS.md§ Operator Doctrine on 2026-09-17 (GHI #921), and into this skill on 2026-09-24 (GHI #1091, sweep finding S06): the ruling governs authoring and recommending, not only working. The corpus.gzkit/corpus/AGENTS.md.jsonlkeeps the ruling's history.
Workflow
- Route first. A GHI authorizes direct defect repair, and a small in-flight
defect without one is fixed directly when it meets
AGENTS.md§ Defect-fix routing. Neither gets an ADR. - Read the target. Read the code and docs the change touches before sizing
it. Hand a subagent only an independent research track, with its Why
(
AGENTS.md§ Behavior Rules). - Size the decomposition with the matrix doc: the Rule of Three baseline
(which the doc sets for heavy-lane ADRs), then the Matrix of Four overlay,
whose four principles are the four
--split-*flags. Choose the dimension scores, then present them, the resulting OBPI count and the rationale for the operator's approval: the Granularity Assessment the doc's § Enforcement asks of this skill. - Ask before creating. Put up to 20 non-obvious questions to the operator on edge cases, dependencies and possible regressions. Do not create the ADR until they are answered.
- Ask the operator for
--kind; never propose a default. In gzkit the choices arefeature(ships a named capability, semver0.y.zand up) andpool(noted, not committed).foundationis closed here by ADR-0.34.0 and the command refuses it. In an adopter project withoutdata/foundation_grandfather.jsonit stays open: offer it with the invariance test, "Foundation = without it, we wouldn't be doing the project" (the hexagonal-ports lens: ports point to invariance; adapters are features), and seedocs/user/concepts/foundation-feature-invariance-test.mdanddocs/user/concepts/adr-taxonomy.md. Bareuv run gz planexits 2, since the subcommand is required. - Preview, then create. Pick a descriptive kebab-case
nameand, for a feature, the semver the work order allows. Run with--dry-run, then without it, passing the operator's--kindthrough unchanged. - Verify the booking. Non-pool:
uv run gz adr status <ADR-ID>shows the ADR. Do not re-run a registrar on success;register-adrs --allis only the recovery the exit-2/3 messages name. Pool:uv run gz register-adrs --pool-only --dry-runlists the entry as unregistered, anduv run gz register-adrs ADR-pool.<name>books it. - Hand off. The template's
_[Author: …]_prompts are the ADR sections left to write. Briefs follow 1:1 with the checklist throughgz-obpi-specify. A pool ADR needs a non-empty## Target Scopesection beforegz adr promoteaccepts it, and the pool template carries none (gz-adr-promote). - Report the ADR id, its path, the
adr_createdevent or, for pool, that none was booked, and the next step.
Example
uv run gz plan create login-impl --kind feature --semver 0.2.0 --lane heavy --dry-run
uv run gz plan create login-impl --kind feature --semver 0.2.0 --lane heavy \
--score-interface 2 --split-surface-boundary
uv run gz adr status ADR-0.2.0-login-impl
uv run gz plan create exotic-idea --kind pool
uv run gz register-adrs ADR-pool.exotic-idea
Related
gz-adr-create: authoring an ADR with its briefs end to endgz-obpi-specify: one brief per checklist itemgz-adr-promote: moving a pool ADR into a versioned packagegz-plan-audit:gz plan audit, the plan-to-brief alignment check