From govctl
Adopts govctl governance in existing projects by discovering undocumented decisions, backfilling ADRs/RFCs, and annotating source code. Use for ungoverned codebases or brownfield migrations.
npx claudepluginhub govctl-org/govctl --plugin govctlThis skill is limited to using the following tools:
Migrate an existing codebase to govctl governance per [[ADR-0032]].
Migrates existing projects to AgenticDev structure using AI analysis to discover, categorize docs, generate frontmatter, update links, and preserve git history. For brownfield projects with ad-hoc documentation.
Plans and executes phased migrations for framework upgrades, API bumps, dependency major versions, and deprecations with compatibility verification.
Share bugs, ideas, or general feedback.
Migrate an existing codebase to govctl governance per [[ADR-0032]].
Purpose: Systematically discover undocumented decisions and specifications in an existing project, codify them as govctl artifacts, and annotate source code with cross-references.
Outputs: Discovery report, backfilled governance artifacts, annotated source references, and an initial governed baseline.
Properties:
govctl adr accept, govctl rfc finalize, and govctl rfc advance.govctl verbs only./commit to record migration milestones. Do not embed raw VCS procedures in this workflow./discuss rather than inventing rationale.# Scaffold
govctl init # Initialize governance structure
govctl status # Verify setup
# Backfill ADRs
govctl adr new "<decision title>"
govctl adr set <ADR-ID> context --stdin <<'EOF' ... EOF
govctl adr set <ADR-ID> decision --stdin <<'EOF' ... EOF
govctl adr set <ADR-ID> consequences --stdin <<'EOF' ... EOF
govctl adr add <ADR-ID> alternatives "Option: ..." --pro "..." --con "..." --reject-reason "..."
govctl adr accept <ADR-ID>
# Backfill RFCs (optional)
govctl rfc new "<spec title>"
govctl clause new <RFC-ID>:C-<NAME> "<title>" -s "Specification" -k normative
govctl clause edit <RFC-ID>:C-<NAME> --stdin <<'EOF' ... EOF
govctl rfc finalize <RFC-ID> normative
govctl rfc advance <RFC-ID> impl
govctl rfc advance <RFC-ID> test
govctl rfc advance <RFC-ID> stable
# Validate
govctl check
govctl init
This creates the gov/ directory structure alongside existing project files. It is safe to run in an existing repo — it does not overwrite existing files.
govctl status
Confirm the governance structure was created. Read gov/config.toml and adjust if needed (e.g., source_scan.include patterns for the project's language).
If migration milestones should be recorded, /commit will choose the raw VCS workflow.
If the user wants to record scaffold creation, use /commit with chore(gov): initialize govctl governance structure.
Systematically scan the project to find implicit governance artifacts. Do not create any govctl artifacts yet — this phase is purely discovery.
Read these files (if they exist) to understand the project:
README.md — Project purpose, tech stack, architecture overviewCONTRIBUTING.md — Development conventions and processesARCHITECTURE.md or docs/architecture.md — System designCHANGELOG.md — History of changes and decisionsMakefile, Justfile, package.json, Cargo.toml — Build system and dependenciesScan for implicit decisions in:
| Source | What to look for |
|---|---|
| README/docs | "We chose X because...", "This project uses..." |
| Config files | Framework choices, database configs, deployment targets |
| Dependencies | Major library choices (ORM, web framework, test framework) |
| Directory structure | Architectural patterns (monorepo, microservices, MVC, hexagonal) |
| Code comments | "TODO: migrate to...", "HACK: because X doesn't support...", "We use X instead of Y" |
| Git/jj history | Large refactors, technology migrations, design pivots |
For each discovered decision, note:
Look for documents that function as specifications:
Check for:
Present findings to the user before proceeding. Format:
=== MIGRATION DISCOVERY REPORT ===
Architectural Decisions Found: N
1. [Brief description] — source: [where found]
2. ...
Existing Specifications Found: N
1. [Brief description] — source: [file path]
2. ...
In-Progress Work Found: N
1. [Brief description] — source: [where found]
2. ...
Recommended migration scope:
- ADRs to create: [list]
- RFCs to create: [list or "none"]
- Work items to create: [list or "none"]
Ask the user: Which items should be backfilled? The user may choose to skip some or prioritize others. Respect their choices.
For each decision the user confirmed, create an ADR.
Follow the adr-writer skill for quality guidelines.
govctl adr new "<decision title>"
govctl adr set <ADR-ID> context --stdin <<'EOF'
[Problem statement and what prompted the decision]
EOF
govctl adr set <ADR-ID> decision --stdin <<'EOF'
We will [what was decided].
[Rationale — why this was chosen]
EOF
govctl adr set <ADR-ID> consequences --stdin <<'EOF'
### Positive
- [Observed benefits]
### Negative
- [Observed downsides or trade-offs]
### Neutral
- [Side effects]
EOF
govctl adr add <ADR-ID> alternatives "Chosen: <what was adopted>" \
--pro "..." --con "..."
govctl adr tick <ADR-ID> alternatives --at 0 -s accepted
govctl adr add <ADR-ID> alternatives "Rejected: <what was not chosen>" \
--pro "..." --con "..." --reject-reason "..."
If rejected alternatives are unknown, it is acceptable to have only the accepted option. When that happens, say so explicitly in the ADR context. Historical backfills may not be able to reconstruct rejected options, and reviewers should evaluate them with that limitation in mind.
Invoke the adr-reviewer agent on each newly created ADR. For large batches, review the most important 3-5 ADRs and spot-check the rest.
Fix Critical findings before accepting the ADRs.
Since these are historical decisions already in effect:
govctl adr accept <ADR-ID>
govctl adr add <ADR-ID> refs <related-ADR-or-RFC>
Group related ADRs into logical commits:
Use /commit with docs(adr): backfill ADRs for existing architectural decisions.
Only if the user confirmed existing specifications in Phase 1. Most migrations skip this phase.
govctl rfc new "<spec title>"
For each requirement in the existing specification:
govctl clause new <RFC-ID>:C-<NAME> "<title>" -s "Specification" -k normative
govctl clause edit <RFC-ID>:C-<NAME> --stdin <<'EOF'
[Clause text extracted from existing spec, rewritten with RFC 2119 keywords]
EOF
Invoke the rfc-reviewer agent on each newly created RFC. For large batches, review the most important RFCs first and spot-check the rest.
Fix Critical findings before making the RFC authoritative.
Migration is a historical backfill workflow. Only finalize and advance the RFC after the user confirms the spec is already implemented and tested:
govctl rfc finalize <RFC-ID> normative
govctl rfc advance <RFC-ID> impl
govctl rfc advance <RFC-ID> test
govctl rfc advance <RFC-ID> stable
Use /commit with docs(rfc): backfill RFCs for existing specifications.
Add [[...]] references to existing source code so govctl check can trace implementations to their governing artifacts.
For each newly created ADR/RFC, find the source files that implement the decision or specification:
# Example: if ADR-0001 decided to use PostgreSQL
# Find database-related files and add reference comments:
Add comments in the project's comment style:
# Per [[ADR-0001]], we use PostgreSQL for persistence
// Implements [[RFC-0001:C-VALIDATION]]
// Per [[ADR-0003]], API responses use camelCase
govctl check
Fix any broken references. All [[...]] references must resolve to existing artifacts.
Use /commit with chore(gov): annotate source with governance artifact references.
Create work items for any in-progress work discovered in Phase 1.
For each active task:
govctl work new --active "<task title>"
govctl work set <WI-ID> description "<what is being done>"
govctl work add <WI-ID> acceptance_criteria "add: <expected outcome>"
govctl work add <WI-ID> refs <related-ADR-or-RFC>
govctl check
govctl render
Use /commit with chore(gov): establish govctl governance baseline.
Present the migration results:
=== MIGRATION COMPLETE ===
Project: <project name>
Artifacts created:
ADRs: N (documenting existing architectural decisions)
RFCs: N (codifying existing specifications)
Work Items: N (tracking in-progress tasks)
Source annotations: N files annotated with [[...]] references
Validation: govctl check passes
Next steps:
- Use /gov for all new work going forward
- Use /discuss for new design decisions
- Incrementally annotate more source files as you touch them
- Run govctl check in CI to enforce governance going forward
Not everything needs an ADR. Focus on decisions that:
Skip trivial decisions (indentation style, variable naming) — those belong in a linter config, not an ADR.
When discovering decisions:
It's fine to migrate in stages:
The /gov workflow naturally extends migration — every new decision gets an ADR, every new feature gets a work item.