<!-- Generated by gzkit — do not edit manually -->
# src/gzkit/commands Agent Instructions

> Shared subtree rules. See root `AGENTS.md` for project-wide governance.

<!-- Generated by gz agent sync — do not edit -->

# CLI Contract Doctrine

**Baseline:** [clig.dev](https://clig.dev/) — Human-first CLI design principles.
**Mechanical check:** `uv run gz cli audit` (see § Core Principles — Consistency).
**Heavy Lane Trigger:** Any CLI contract change (subcommands, flags, exit codes, output schemas).

---

## Core Principles

| Principle | Rule |
|-----------|------|
| Human-first | Optimize for humans; add `--json`/`--plain` for machines |
| Consistency | Before landing a new flag or subcommand, run `uv run gz cli audit`; it must exit 0 with the new verb covered across manpage, command doc, and index. If coverage is missing, author the missing artifacts in the same patch — the audit is the mechanical check, not operator taste. |
| Discovery | Comprehensive help with examples; no web docs needed |
| Robustness | Validate early; fail fast; provide progress indicators |

---

## Exit Codes (Standard 4-Code Map)

| Code | Meaning | Recovery |
|------|---------|----------|
| **0** | Success | N/A |
| **1** | User/Config Error | Fix invocation or config |
| **2** | System/IO Error | Check network/disk; retry |
| **3** | Policy Breach | Review logs; partial success needs review |

Use `sys.exit(code)`. Document codes 2/3 in help text.

---

## Flag Conventions

| Flag | Behavior |
|------|----------|
| `--quiet` | Errors only |
| `--verbose` | Debug output |
| `--dry-run` | Show plan, don't execute |
| `--json` | Machine-readable to stdout |
| `--help` / `-h` | Always works |

---

## Output Contracts

| Mode | Output |
|------|--------|
| Default | Human-readable (tables, colors, progress) |
| `--json` | Valid JSON to stdout; logs to stderr |
| `--plain` | One record per line (grep-friendly) |

---

## Help Text Requirements

Every command must:

1. Respond to `-h`/`--help` (exit 0)
2. Include description (1-2 sentences)
3. Include usage line
4. List all options
5. Include at least one example
6. Keep lines <=80 chars

---

## Adding CLI Features

### New Flag (Additive = Lite Lane)

1. Follow naming conventions
2. Check for equivalent in other CLI
3. Update help text with example

### New Subcommand (Heavy Lane)

1. ADR or brief documenting purpose
2. Help text with examples
3. Behave smoke test
4. Manpage in `docs/user/manpages/`
5. Release notes

<!-- Generated by gz agent sync — do not edit -->

<!-- rule-version: 0.2.0 -->

# Tool / Skill / Runbook Alignment

> **Rule version:** `0.2.0` — lifted pedagogy, canonical violations, and enforcement details to rationale doc under GHI #327.

gzkit's operator surface is a three-layer hierarchy: **tools** (CLI verbs), **skills** (operator-facing value chains composing tools toward an intent), and **runbooks** (documentation preserving operator intent across iteration). These three invariants are the mechanical test for layer alignment; apply them whenever you author or modify any of the three surfaces.

## Invariants

### Invariant 1 — Every CLI tool has at least one skill that wields it

Every CLI verb registered in `src/gzkit/cli/` must be invoked by at least one skill under `.gzkit/skills/` — either via the skill's frontmatter `gz_command:` field or in the skill's body instructions. An orphaned tool (a live CLI verb with no skill pointing at it) is either dead code or hidden drift — either way, it is a defect signal.

### Invariant 2 — Every skill's `gz_command` matches a runbook-prescribed tool for the same operator moment

Every skill's declared `gz_command:` (frontmatter or body) must resolve to a CLI verb that the runbook prescribes for the same operator moment. If the skill name and its actual CLI target describe different operator moments — or if the skill invokes a verb the runbook does not prescribe for that moment — the skill is drifted from the runbook's preserved intent.

### Invariant 3 — Destination verb's default output form must honor the routing skill's Output Contract

When a skill's Output Contract declares a required rendering form ("table", "JSON", "tree", "plain text", etc.), the CLI verb in the skill's `gz_command` must produce that form as its default human-readable output. If the skill promises a table and the verb emits prose, the skill is drifted from its destination regardless of whether the verb name matches (Invariant 2). Invariant 3 closes the gap between "right verb routed" and "right rendering produced."

## When to apply

- **Authoring a new CLI verb** — confirm at least one skill will wield it before merging; author the skill in the same patch or file a follow-up GHI
- **Renaming a CLI verb** — audit every referencing skill (frontmatter `gz_command:` + body invocations); update in same patch
- **Authoring a new skill** — confirm `gz_command:` target matches the runbook-prescribed verb for that operator moment, and run the target once to verify output form matches Output Contract
- **Renaming a skill** — confirm `gz_command:` still aligns with the new name's implied operator moment
- **Re-routing a skill's `gz_command`** — run the new target and observe default output before committing; fix destination verb or skill contract if form disagrees
- **Editing the runbook** — confirm prescribed verbs still match skill-layer routing; add missing skills or update prescriptions
- **Editing a CLI verb's rendering** — check every skill whose `gz_command` points at that verb; preserve any Output Contract-declared form

> See [`docs/governance/tool-skill-runbook-rationale.md`](../../docs/governance/tool-skill-runbook-rationale.md) for canonical violation examples, enforcement details, commit-message discipline, and rationale.
