gov

Prompt file imported from govctl-org/skillc (.claude/commands/gov.md). Fill in {{arguments}} before use. Copyright stays with the author.

/gov — Governed Workflow

Execute a complete, auditable workflow to do: {{arguments}}

QUICK REFERENCE

# govctl commands
govctl status                             # Show summary
govctl work list pending                  # List queue + active items
govctl rfc list                           # List all RFCs
govctl adr list                           # List all ADRs
govctl work new --active "<title>"        # Create + activate work item
govctl work move <WI-ID> <status>         # Transition (queue|active|done|cancelled)
govctl rfc new "<title>"                  # Create RFC (auto-assigns ID)
govctl adr new "<title>"                  # Create ADR
govctl check                              # Validate everything
govctl render                             # Render to markdown
govctl render changelog                   # Generate CHANGELOG.md
govctl release <version>                  # Cut a release (e.g., 1.0.0)

# Checklist management (with changelog category prefixes)
govctl work add <WI-ID> acceptance_criteria "add: New feature"    # → Added section
govctl work add <WI-ID> acceptance_criteria "fix: Bug fixed"      # → Fixed section
govctl work add <WI-ID> acceptance_criteria "chore: Tests pass"   # → excluded from changelog
govctl work tick <WI-ID> acceptance_criteria "pattern" -s done

# Multi-line input
govctl clause edit <clause-id> --stdin <<'EOF'
multi-line text here
EOF

CRITICAL RULES

1. All governance operations MUST use govctl CLI — never edit governed files directly
2. Proceed autonomously unless you hit a blocking condition (see ERROR HANDLING)
3. Phase discipline — follow spec → impl → test → stable for RFC-governed work
4. RFC supremacy — behavioral changes must be grounded in RFCs
5. RFC advancement requires permission — see RFC ADVANCEMENT GATE below
6. Reference format in code — when referencing artifacts in source code comments, use [[artifact-id]] syntax (e.g., // Implements [[RFC-0001:C-FOO]]) to enable validation by govctl check

RFC ADVANCEMENT GATE

Default behavior: Ask for human permission before:

• govctl rfc finalize <RFC-ID> normative
• govctl rfc advance <RFC-ID> <phase>

Override: If {{arguments}} contains phrases like:

• "free", "autonomous", "all allowed", "no permission needed", "full authority"

Then RFC advancement may proceed without asking.

Rationale: RFC status/phase changes are significant governance actions. They should not happen silently unless explicitly authorized.

PHASE 0: INITIALIZATION

0.1 Validate Environment

govctl status

Detect VCS: Try jj status first. If it succeeds, use jujutsu. Otherwise use git. Error if neither works.

0.2 Read Project Configuration

Read the governance config to understand project-specific settings. Use the Read tool or your IDE to view gov/config.toml.

Key settings to note:

• source_scan.pattern — the [[...]] pattern used for inline artifact references
• Output directories for rendered artifacts
• Any project-specific overrides

VCS commands (use detected VCS throughout):

0.3 Classify the Target

Parse {{arguments}} and classify:

Fast path for doc-only changes: Skip to Phase 1, then directly to Phase 3 (implementation). No RFC/ADR required.

PHASE 1: WORK ITEM MANAGEMENT

1.1 Check Existing Work Items

govctl work list pending

Decision:

• Active item matches → use it, proceed to Phase 2
• Queued item matches → govctl work move <WI-ID> active
• No match → create new

1.2 Create New Work Item

# Create and activate in one command
govctl work new --active "<concise-title>"

1.3 Add Acceptance Criteria

Important: Work items cannot be marked done without acceptance criteria.

Category prefixes (for changelog generation per ADR-0012/ADR-0013):

Note: Explicit category is required. Use prefix syntax (add: ...) or --category option.

govctl work add <WI-ID> acceptance_criteria "add: Implement feature X"
govctl work add <WI-ID> acceptance_criteria "fix: Memory leak resolved"
govctl work add <WI-ID> acceptance_criteria "chore: All tests pass"  # won't appear in changelog

1.4 Record

# jj
jj commit -m "chore(work): activate <WI-ID> for <brief-description>"

# git
git add . && git commit -m "chore(work): activate <WI-ID> for <brief-description>"

PHASE 2: GOVERNANCE ANALYSIS

Skip this phase for doc-only changes (README, comments, typos).

2.1 Survey Existing Governance

govctl rfc list
govctl adr list

2.2 Determine Requirements

2.3 Create RFC (if needed)

# Create RFC (auto-assigns next ID, or use --id RFC-NNNN)
govctl rfc new "<title>"

# Add clauses
govctl clause new <RFC-ID>:<CLAUSE-ID> "<title>" -s "Specification" -k normative

# Edit clause text via stdin
govctl clause edit <RFC-ID>:<CLAUSE-ID> --stdin <<'EOF'
The system MUST...
EOF

2.4 Create ADR (if needed)

govctl adr new "<title>"

2.5 Link to Work Item

govctl work add <WI-ID> refs <RFC-ID>

2.6 Record

# jj
jj commit -m "docs(rfc): draft <RFC-ID> for <summary>"

# git
git add . && git commit -m "docs(rfc): draft <RFC-ID> for <summary>"

PHASE 3: IMPLEMENTATION

3.1 Gate Check (for RFC-governed work)

Before implementation, verify:

• RFC status is normative (required for production features)
• RFC phase is impl or later

# Check current state
govctl rfc list

Gate conditions:

If permission granted (or override in {{arguments}}):

govctl rfc finalize <RFC-ID> normative  # if draft
govctl rfc advance <RFC-ID> impl        # if spec phase

Amending normative RFCs during implementation:

Per [[ADR-0016]], normative RFCs MAY be amended during implementation. Amendments MUST bump version and add changelog entry:

# Edit clause content
govctl clause edit <RFC-ID>:<CLAUSE-ID> --stdin <<'EOF'
Updated specification text.
EOF

3.2 Implement

1. Write code following RFC clauses (if applicable)
2. Reference artifacts in comments — use [[artifact-id]] syntax:

   // Implements [[RFC-0001:C-VALIDATION]]
   fn validate() { ... }

3. Keep changes focused — one logical change per commit
4. Run validations after substantive changes:

   # Run your project's lint/format checks
   govctl check

3.3 Record

# jj
jj commit -m "feat(<scope>): <description>"

# git
git add . && git commit -m "feat(<scope>): <description>"

PHASE 4: TESTING

For doc-only changes: Run tests to verify no regressions, but skip RFC phase advancement.

4.1 Advance Phase (if RFC exists)

ASK PERMISSION before advancing (unless override in {{arguments}}):

govctl rfc advance <RFC-ID> test

4.2 Run Tests

# Run your project's test command

If tests fail, fix implementation and re-run. Do not proceed until green.

4.3 Record

# jj
jj commit -m "test(<scope>): add tests for <feature>"

# git
git add . && git commit -m "test(<scope>): add tests for <feature>"

PHASE 5: COMPLETION

5.1 Final Validation

# Run your project's full validation suite
govctl check

5.2 Advance RFC to Stable (if applicable)

If RFC exists and all tests pass, ASK PERMISSION before advancing (unless override in {{arguments}}):

govctl rfc advance <RFC-ID> stable

5.3 Tick Acceptance Criteria

Pre-flight: Verify acceptance criteria were added in Phase 1. If missing, add now:

govctl work add <WI-ID> acceptance_criteria "add: Feature implemented"

Then tick each completed criterion:

govctl work tick <WI-ID> acceptance_criteria "Feature implemented" -s done

5.4 Mark Work Item Done

govctl work move <WI-ID> done

5.5 Record

# jj
jj commit -m "chore(work): complete <WI-ID> — <summary>"

# git
git add . && git commit -m "chore(work): complete <WI-ID> — <summary>"

5.6 Summary Report

=== WORKFLOW COMPLETE ===

Target: {{arguments}}
Work Item: <WI-ID>
Status: done

Governance: <RFC/ADR list or "none">
Files modified: <count>

All validations passed.

ERROR HANDLING

When to Stop and Ask

1. Ambiguous requirements — cannot determine actionable items
2. RFC conflict — implementation conflicts with normative RFC
3. Breaking change — would break existing behavior
4. Security concern — credentials, secrets, sensitive data
5. Scope explosion — task grew beyond reasonable bounds

For all other errors: fix and continue.

Recovery

CONVENTIONS

Content Field Formatting

When editing content fields (description, context, decision, consequences, notes), use proper markdown:

Code and technical terms: Wrap in backticks

# Good
description = "Add `expand_inline_refs()` function using `Vec<String>`"

# Bad - will cause mdbook warnings
description = "Add expand_inline_refs() function using Vec<String>"

Artifact references: Use [[artifact-id]] syntax for inline references

# Good - expands to clickable link when rendered
context = "Per [[RFC-0000]], all work items must have acceptance criteria."

# Also good for clauses
decision = "Follow [[RFC-0000:C-WORK-DEF]] requirements."

# Bad - plain text, not linked
context = "Per RFC-0000, all work items must have acceptance criteria."

The [[...]] pattern is automatically expanded to markdown links during govctl render.

Source code comments: Use [[artifact-id]] in code comments to enable validation:

// Implements [[RFC-0001:C-VALIDATION]]
fn validate_input(data: &str) -> Result<()> { ... }

// Per [[ADR-0005]], we use streaming instead of buffering
fn process_stream() { ... }

govctl check validates these references exist and warns if they're deprecated/superseded.

Note: The refs field uses plain artifact IDs (not [[...]] syntax):

govctl work add <WI-ID> refs RFC-0000      # Correct
govctl work add <WI-ID> refs "[[RFC-0000]]" # Wrong

Commit Messages

Multi-line Input

govctl: Use --stdin with input redirection.

bash/zsh (macOS/Linux):

govctl clause edit <clause-id> --stdin <<'EOF'
Multi-line content here.
EOF

PowerShell (Windows):

@"
Multi-line content here.
"@ | govctl clause edit <clause-id> --stdin

Multi-line Commits

jujutsu (bash/zsh):

jj describe --stdin <<'EOF'
feat(scope): summary

- Detail one
- Detail two
EOF
jj new

jujutsu (PowerShell):

@"
feat(scope): summary

- Detail one
- Detail two
"@ | jj describe --stdin
jj new

git (bash/zsh):

git add . && git commit -m "$(cat <<'EOF'
feat(scope): summary

- Detail one
- Detail two
EOF
)"

git (PowerShell):

git add .
git commit -m @"
feat(scope): summary

- Detail one
- Detail two
"@

EXECUTION CHECKLIST

• Environment validated, VCS detected
• Work item active with acceptance criteria
• Governance analysis (skip for doc-only)
• Implementation complete
• Tests passing
• Acceptance criteria ticked
• Work item marked done
• Summary reported

BEGIN EXECUTION NOW.