Skip to content

/gz-adr-create

Create and book a GovZero ADR with its OBPI briefs, through a structured interview and the governed scaffolders.

Purpose

/gz-adr-create is the entry point for recording a new architectural decision. It interviews you, scaffolds the ADR from the canonical template, co-creates one OBPI brief per checklist item, confirms the ADR is booked in the ledger, and runs post-authoring QC.

When to Use

Invoke /gz-adr-create when you have a new capability, architectural change, or design decision that needs formal governance tracking. Typical trigger points:

  • After design exploration — once /gz-design dialogue has produced a clear decision, create the ADR to formalize it.
  • When starting a new feature — before implementation begins, the ADR captures intent, scope, and the OBPI work breakdown.
  • When recording a retrospective decision — if a decision was made informally and needs governance backing.

This skill sits at the beginning of the ADR lifecycle. After creation, the operator initiates each OBPI through /gz-obpi-pipeline, and the ADR is closed through /gz-adr-closeout-ceremony. See Runbook: ADR Creation for the full workflow.

What to Expect

  1. An interview, one question at a time. The agent drafts each answer from what it already knows and you correct it: the ADR pro-forma (kind, problem, decision, alternatives, consequences, checklist) and seven design forcing functions. --kind is always asked, never defaulted. In gzkit itself foundation is closed to new authoring, so the choice is feature or pool.
  2. The answers are recorded to a JSON file kept alongside the ADR.
  3. The ADR is scaffolded by the CLI from src/gzkit/templates/adr.md — uv run gz interview adr --from <answers>.json for a feature ADR, uv run gz plan create <slug> --kind pool --lane <lite|heavy> for a pool ADR. The scaffolder chooses the directory under docs/design/adr/.
  4. OBPI briefs are co-created — one per checklist item — with uv run gz specify, then validated with uv run gz obpi validate --adr ADR-X.Y.Z --authored. Pool ADRs carry no briefs until they are promoted.
  5. The ADR is confirmed in the ledger. Feature scaffolding books it; uv run gz register-adrs books a pool ADR and regenerates the derived status index docs/governance/GovZero/adr-status.md, which is never hand-edited.
  6. Post-authoring QC runs through /gz-adr-evaluate (not for pool ADRs).
  7. Validation: uv run gz test and uv run mkdocs build --strict.

No closeout form is written at authoring; gz closeout writes ADR-CLOSEOUT-FORM.md when the ADR is closed out.

Success looks like: an ADR document with every template section populated, the interview answers beside it, one brief per checklist item, and the ADR visible in uv run gz adr report.

Failure looks like: a duplicate ADR ID, an ADR on disk that the ledger does not know, or more checklist items than briefs.

Invocation

Text Only
/gz-adr-create
/gz-adr-create ADR-0.36.0 --title convergence-moment-cross-family-critic
Argument Required Description
ADR-X.Y.Z no The ADR identifier; confirmed during the interview if omitted
--title no Kebab-case slug for the ADR directory name

Supporting Files

File Role Read/Write
.claude/skills/gz-adr-create/SKILL.md Agent execution instructions Read
src/gzkit/templates/adr.md Canonical ADR template Read
src/gzkit/templates/obpi.md OBPI brief template for generated briefs Read
docs/governance/GovZero/adr-status.md Derived ADR status index, regenerated by gz register-adrs Generated
Related Relationship
/gz-design Typically precedes ADR creation — produces the design decision
/gz-obpi-specify Creates and authors individual OBPI briefs after the ADR exists
/gz-adr-evaluate Post-authoring QC evaluation run during creation
/gz-obpi-pipeline Executes the OBPIs created by this skill, when the operator initiates them
/gz-adr-closeout-ceremony Closes the ADR after all OBPIs complete
gz register-adrs Books ADRs missing from the ledger and regenerates the status index