Skip to content

gz specify

Create a new implementation brief.

Usage

Bash
gz specify <name> --parent <ADR-ID> --item <N> [OPTIONS]

Arguments

Argument Required Description
name Yes Brief name

Options

Option Type Default Description
--parent string required Parent ADR ID
--item integer 1 Parent ADR checklist item number
--lane lite | heavy lite Governance lane
--author flag — Run the authored pass and fail unless the brief passes gz obpi validate --authored
--title string — Brief title
--dry-run flag — Show actions without writing

What It Does

  1. Resolves the parent ADR and loads Checklist + Decomposition Scorecard
  2. Enforces checklist/scorecard count consistency
  3. Binds OBPI --item N to the exact parent checklist text
  4. Creates OBPI brief under parent ADR obpis/ directory
  5. Records obpi_created event in ledger

Pool ADRs (ADR-pool.* or legacy ADR-*.pool.*) are blocked as parents until promoted. If the parent ADR scorecard is missing/invalid, or checklist count drifts from scorecard target, gz specify fails closed.

Example

Bash
# Basic usage
gz specify add-login --parent ADR-0.4.0-skill-capability-mirroring --item 1

# Generate and author in one pass
gz specify add-login --parent ADR-0.4.0-skill-capability-mirroring --item 1 --author

# With options
gz specify add-login --parent ADR-0.4.0-skill-capability-mirroring --item 2 \
  --lane heavy --title "Add Login Button"

# Dry run
gz specify add-login --parent ADR-0.4.0-skill-capability-mirroring --item 2 --dry-run

Output

Text Only
Created OBPI: docs/design/adr/pre-release/ADR-0.4.0-skill-capability-mirroring/obpis/OBPI-0.4.0-02-add-login.md
  Lane: heavy (source: WBS table)
  Objective: Add Login Button.
Note: Brief populated from ADR content. Brief must pass authored validation before pipeline entry.
  Validate with: uv run gz obpi validate --authored <path>

The created brief is an ADR-derived draft, not a finished implementation brief. gz specify seeds lane, objective, allowed paths, requirements, discovery hints, verification commands, and acceptance criteria from the parent ADR. The brief must still pass authored-readiness validation before the OBPI pipeline should execute it. Use gz obpi validate --authored to verify the brief is usable as an execution contract.

When --author is passed, gz specify strips template guidance comments, runs the authored pass, and fails closed unless the generated brief already passes gz obpi validate --authored.

Brief Template

The created brief contains:

  • Metadata: ID, title, parent, lane, status
  • ADR Item Linkage: exact quoted checklist item text from parent ADR
  • Acceptance Criteria: How to know it's done
  • REQ IDs: Each acceptance checkbox is seeded with REQ-<semver>-<obpi_item>-<nn>
  • Lane Requirements: Docs/BDD needed (based on lane)

Lanes

Lite (default)

  • Documentation: No
  • BDD: No
  • For internal changes

Heavy

  • Documentation: Yes
  • BDD: Yes
  • For contract changes (CLI, API, schema)

Workflow

  1. (Optional) Create a PRD with gz prd
  2. Create an ADR with gz plan
  3. Create and author an OBPI brief with gz specify --parent ADR-... --author
  4. Re-run authored validation if you edit the brief further: gz obpi validate --authored <path>
  5. Execute the OBPI through the pipeline: gz obpi pipeline OBPI-...
  6. Attest with gz attest (required for heavy-lane or foundation-kind parent ADRs)