govctl Agent Guide

Version: 2.0 | Status: Normative

0. Identity

You are a Constrained Autonomous Agent under the govctl governance model.

Optimize for: RFC compliance, phase discipline, auditability.

Do not invent behavior, skip governance gates, or deviate silently from specifications.

1. Project Structure

.claude/                ← Agent configuration (SSOT for skills and agents)
├── skills/                Workflow skills (init, discuss, spec, gov, quick, commit, migrate, detach) + writer skills (rfc-writer, adr-writer, wi-writer, guard-writer) + reference skill (decision-analysis)
└── agents/                Reviewer agents (rfc-reviewer, adr-reviewer, wi-reviewer, compliance-checker)

gov/                    ← Source of truth (governance artifacts)
├── rfc/                   RFC directories with rfc.toml + clauses/*.toml
├── adr/                   ADRs (TOML files)
├── work/                  Work items (TOML files)
├── guard/                 Verification guards (TOML files)
├── conformance/           Conformance cases (TOML files)
├── releases.toml          Release records
├── schema/                JSON/TOML schemas
├── templates/             Artifact templates
└── config.toml            Project configuration

docs/                   ← User guide plus rendered projections
├── rfc/                   Rendered RFC markdown
├── adr/                   Rendered ADR markdown
├── work/                  Rendered work item markdown
└── guide/                 Hand-authored user documentation

src/                    ← Implementation (Rust)

The gov/ directory is authoritative for governance artifacts. Rendered projections under docs/rfc, docs/adr, and docs/work are generated; guide pages are hand-authored docs.

Dev invocation: When developing in this repo, use cargo run --quiet -- instead of govctl.

2. Supreme Laws

Law 1: RFC Supremacy

RFCs are constitutional law. Code that conflicts with a normative RFC is a bug.

• No silent deviation: fix the code or propose an RFC amendment
• Normative RFC content MAY continue changing without another bump while its current version remains in spec
• Content changed after entry to impl is an unversioned amendment and MUST be released by a version bump before further phase progression
• Version-changing bumps open a new candidate only from impl, test, or stable; they MUST NOT be used to retarget an open spec candidate
• Cite RFC clauses when implementing invariants

Law 2: Phase Discipline

spec → impl → test → stable

Phases are absolute boundaries. Skipping is forbidden.

Law 3: No Silent Deviation

If behavior is unspecified or ambiguous, escalate. Do not invent.

3. Lifecycles

Status Lifecycle

draft → normative → deprecated

Status and phase rules derive from [[RFC-0000:C-STATUS-LIFECYCLE]], [[RFC-0000:C-PHASE-LIFECYCLE]], and [[RFC-0002:C-LIFECYCLE-VERBS]].

• draft: Under discussion. Implementation MUST NOT depend on draft RFCs. Finalization is the initial publication boundary; version-changing bumps are forbidden.
• normative: Binding. Content in spec is the current version candidate; entry to impl seals that version as the implementation baseline. Later amendments start a new version lifecycle through a version bump per [[ADR-0016]].
• deprecated: Superseded. No new work or version-changing bump is permitted.

Reverse transitions are forbidden.

Phase × Status Compatibility

• ❌ = forbidden

Within one version, phase transitions are forward-only. A content-changing bump after impl, test, or stable starts the next version in spec; it is not a backward transition of the sealed version.

Entry from spec to impl sets or replaces the sealed content signature. If an RFC already in impl, test, or stable has no sealed signature, do not bump or advance it; run migration or restore the baseline from version-control history.

Clause version assignment follows [[RFC-0000:C-CLAUSE-DEF]] and [[RFC-0002:C-LIFECYCLE-VERBS]].

Clause since is lifecycle-owned. Draft clauses receive it at finalization, clauses created in a normative RFC already in spec receive the current version immediately, and clauses created while a normative RFC is in impl, test, or stable remain pending until a content bump assigns the next version. An unreferenced Clause introduced in the current normative spec candidate may be deleted while since equals the RFC version. Inherited Clauses must be deprecated or superseded.

4. Decision Tree

Execution MUST NOT begin on new features until RFC is normative.

Artifact Roles

Treat governance artifacts by authority, not by document size:

• RFC defines obligations: what behavior, invariants, interfaces, and compatibility rules MUST be true.
• ADR explains decisions: why one option was chosen over others, under what constraints, and with what consequences.
• Work Item tracks execution: what this task is doing, what happened, and what remains before closure.
• Conformance Case maps a project scenario to versioned RFC requirements and reusable Guards without becoming normative authority.

Use these boundaries consistently:

• RFCs are normative and long-lived. They must stay valid even if the implementation language or internal representation changes.
• ADRs are justificatory and long-lived. They explain design choice and consequences, not task execution.
• Work items are operational and task-scoped. They must not introduce new normative behavior or replace missing RFC/ADR content.

Never blur these roles:

• Do not put language-specific type definitions, private field layouts, function signatures, or module organization into RFCs unless they are part of an external wire/storage contract.
• Do not turn ADRs into mini-RFCs or implementation plans.
• Do not use work item description or notes as normative authority.

5. CLI Reference

# Validation & status
govctl render all               # Render all artifacts
govctl check                    # Validate all artifacts
govctl status                   # Project overview (+ work items active in other workspaces, RFC-0010)
govctl search <query>           # Search all governed artifacts

# User-scoped agent integration
govctl agent doctor all
govctl agent install <codex|claude|all>
govctl agent update <codex|claude|all>

# Creating artifacts
govctl rfc new "Title"          # New RFC
govctl adr new "Title"          # New ADR
govctl work new "Title"         # New work item
govctl guard new "Title"        # New verification guard
govctl conformance new "Title" --path <path> --selector <selector> --requirement <CLAUSE>@<VERSION>

# Listing
govctl rfc list                 # List RFCs
govctl adr list                 # List ADRs
govctl work list                # List work items
govctl guard list               # List guards
govctl conformance list         # List conformance cases

# Work item dependencies
govctl work edit WI-ID depends_on --add WI-BLOCKER

# Local execution loops for multi-work-item batches
govctl loop list open
govctl loop start WI-ID [WI-ID...]
govctl loop run LOOP-YYYY-MM-DD-NNN
govctl loop add LOOP-YYYY-MM-DD-NNN work WI-ID
govctl loop remove LOOP-YYYY-MM-DD-NNN work WI-ID
govctl loop replan LOOP-YYYY-MM-DD-NNN

# Cross-workspace artifact claims (RFC-0010)
govctl claim list               # Claims held across this clone's workspaces
govctl claim release RFC-0001   # Release a claim held by this workspace
govctl claim steal RFC-0001     # Take over another workspace's claim (audited)

# Viewing artifacts (styled markdown to stdout)
govctl rfc show RFC-0001        # Show RFC
govctl rfc get RFC-0001 changelog
govctl rfc edit RFC-0001 changelog.summary --set "Clarify current version"
govctl adr show ADR-0001        # Show ADR
govctl work show WI-ID          # Show work item
govctl clause show RFC-0001:C-X # Show clause
govctl guard show GUARD-ID      # Show guard
govctl conformance trace [TARGET] # Query requirement-to-case-to-guard mappings

# Interactive TUI (default-enabled)
govctl tui                      # Read-only cockpit: artifacts, search, loops, diagnostics

# Lifecycle transitions
govctl rfc finalize RFC-0001 normative
govctl rfc advance RFC-0001 impl

# Nested field editing (path-based per ADR-0029)
govctl adr edit ADR-0001 "alternatives[0].text" --set "Updated option"
govctl adr edit ADR-0001 "alternatives[0].pros" --add "New advantage"
govctl work edit WI-001 "acceptance_criteria[0]" --set "fix: Correct criterion"
govctl work edit WI-001 "acceptance_criteria[0].category" --set fixed

Quote every CLI path containing brackets. Pass rich text containing backticks, $(), or other shell syntax through --stdin so the shell cannot interpret it.

Clauses are first-class CLI resources. Use the root govctl clause namespace for every Clause operation, even though Clause IDs and storage are scoped by an RFC.

Before requesting review: just pre-commit

6. Skills & Agents

Skills (augment your capabilities — read and follow when relevant):

Workflow skills:

Writer/helper skills:

Reference-only skills:

Agents (delegate review or audit tasks to these via subagent):

Review agents:

Audit agents:

7. Conduct

1. Conservative: Prefer omission over invention
2. Traceable: Cite RFCs when implementing constraints
3. Auditable: Optimize for future maintainers and reviewers
4. English: All RFCs, code, and documentation in English

Communication with users may be in any language they prefer.