Codex skill: plan-governance

audit-checklist.md

Audit Checklist

Use this when validating a plan registry against the current codebase.

Discovery

• Find the plan root.
• Find the index file.
• Find any authoring guide.
• Find any canonical boundary doc.
• Determine how owner is expressed.
• Determine whether the repo uses a quarantine or unresolved-owner area.
• Identify canonical code roots.

Per-document audit

For each plan:

• What problem boundary does it own?
• What maturity does it claim?
• How is owner expressed?
• Is the current folder or placement part of the owner model?
• What code paths should implement it?
• What tests or artifacts should exist if it is real?

Code verification

Check:

• commands or handlers
• persisted files and schemas
• status/state enums
• runtime watchers or background jobs
• adapters or renderers
• tests covering the claimed behavior
• whether the document still lives under the correct owner folder or owner namespace
• whether quarantined docs still truly lack a safe owner

Drift detection

Look for:

• stale maturity labels
• stale terminology
• missing index entries
• index category mismatches
• mixed responsibility boundaries in one doc
• proposal text that no longer matches the product model
• owner drift
• folder-placement drift
• quarantine drift
• broken cross-links after doc moves

Update actions

• Reclassify maturity.
• Rewrite current status.
• Add or remove index entries.
• Move the file to the correct owner location.
• Add links to canonical docs.
• Split a plan if it covers multiple layers.

Reporting

Summarize with:

• confirmed landed
• confirmed partial
• still draft or historical
• registry drift requiring follow-up
• owner or folder drift requiring follow-up
• unresolved quarantine docs

maturity-model.md

Maturity Model

The exact labels can vary by repo. The semantics should stay stable.

Core states

Landed

Use when the document's core behavior is implemented in the current codebase.

Signals:

• main behavior exists in code
• runtime surfaces or artifacts described by the doc exist
• tests or direct validation support the claim
• remaining gaps are minor, not structural

Partially Landed

Use when the repo has real implementation, but the document still describes meaningful unfinished work.

Signals:

• some major path exists
• other major paths, state semantics, or guarantees are still missing
• the doc must separate implemented behavior from intended behavior

This is usually the most important category to keep accurate.

Draft

Use when the document is still mainly a proposal or design direction.

Signals:

• no meaningful end-to-end implementation yet
• only preparatory cleanup exists
• the codebase does not yet express the main model of the document

Retired / Historical

Use when the document no longer describes the current architecture, but is still kept for migration context, background, or comparison.

Signals:

• the implementation moved on to newer docs or newer ownership boundaries
• keeping the doc visible still helps explain historical behavior or refactor context
• the current answer now lives somewhere else

Reclassification rules

Move a doc upward only when the implementation actually exists.

Do not reclassify because:

• a related doc landed
• the terminology sounds mature
• there is a test stub
• there is a partial helper with no user-visible effect

Move a doc downward or mark drift when:

• the index overstates reality
• the doc claims more than the code does
• terminology changed enough that the current text is misleading
• the doc still claims current authority after becoming historical

Maturity alignment is not the same thing as owner alignment.

Check them separately:

• maturity asks whether implementation exists
• owner asks where the responsibility boundary now belongs
• a doc can be correctly marked partial and still sit under the wrong owner
• a retired doc can still remain in the same owner folder if that folder is the right historical home

Index alignment

If a repo has both an index and per-doc current status, they must agree.

When they do not agree:

1. verify against code
2. fix the single doc if needed
3. fix the index immediately after

openai.yaml

interface:
  display_name: "Plan Governance"
  short_description: "Audit and maintain living design registries"
  default_prompt: "Use $plan-governance to audit this repo's plan registry against the current code and filing model."

plan-template.md

Reusable Plan Template

Use this when a repo needs a new plan doc or an existing one is missing structure.

Adjust headings, labels, and filing conventions to local terminology, but keep the intent.

If the repo already expresses owner by folder path or another structural rule, keep that structure. Do not add redundant owner metadata to the registry unless the repo explicitly requires it.

# <Title>

## Current Status

State the repo-local maturity label. Common examples:

- landed
- partially landed
- draft
- retired

Then answer:

- what is already implemented
- what is not implemented
- what the known gaps are

## Problem / Background

Explain why this document exists.

Prefer concrete failure modes over abstract vision:

- what is unclear today
- what is split across multiple docs
- what currently has to be inferred from code

## Scope / Positioning

Define what this document covers and what it does not cover.

Useful prompts:

- Is this a lifecycle doc, a state model, a delivery model, or a UI surface doc?
- Which neighboring docs should define the other layers?

## Main Model

Describe the actual thing that needs to be implemented or reasoned about:

- states
- events
- artifacts
- ownership
- invariants
- transitions
- API or command shape

For each new concept, try to answer:

- valid values
- source of truth
- persistent or ephemeral
- owning layer
- update timing

## Relationship To Other Docs

State:

- which docs this depends on
- which docs should reference this
- which terms should not be redefined here
- whether owner is expressed here, in the registry, or by folder placement

## Open Questions

List only unresolved decisions that matter.

Examples:

- default mode
- visibility of a field
- failure UX
- persistence policy

## Suggested Next Steps

End with the next practical move:

- update a helper or API
- reclassify the index
- split a mixed document
- implement the smallest useful v1

SKILL.md

name	plan-governance
description	Use when a repository has plan, RFC, ADR, or design docs that must stay aligned with current code, be classified by maturity, and be maintained as a living design registry rather than a loose backlog.

Plan Governance

Overview

Use this skill when a repo treats plan, RFC, ADR, or architecture docs as a maintained design registry instead of a loose proposal pile.

This skill now assumes two governance questions must stay cleanly separated:

• status view: which docs are landed, partial, retired, or still draft
• owner view: which role, subsystem, or bounded area a doc belongs to

Some repos keep both views in one index. Others split them, for example:

• a README or registry file owns status
• folder paths own owner
• an authoring guide defines filing rules
• a canonical boundary doc defines the role vocabulary

Preserve the repo's stronger local model. Do not collapse a working split back into one handwritten index.

This skill is for five recurring jobs:

• audit plan progress against current code
• fix stale maturity labels or registry entries
• fix owner placement or quarantine placement drift
• decide whether to update an existing doc or create a new one
• write or move plan docs so they fit the local registry model cleanly

Quick Start

1. Find the plan root.
2. Find the canonical registry or index.
3. Determine how the repo expresses owner. Examples: README metadata, folder paths, ADR prefixes, domain folders
4. Find any authoring guide or canonical boundary doc.
5. Identify the local maturity model.
6. Map each document to the code areas that actually implement or should implement it.

If the repo already separates status view and owner view, keep that split.

Workflow

1. Establish the local registry model

Before editing anything, determine:

• where the registry lives
• whether there is a canonical index
• whether there is an authoring guide
• whether there is a canonical boundary doc
• how owner is expressed
• whether the repo treats these docs as current state, future design, or mixed

Common owner-expression models:

• owner metadata in an index
• owner by folder path
• owner by filename prefix
• mixed model with a quarantine bucket for unresolved ownership

Record the local model first. Do not start by imposing docs/plan/ or owner role: fields.

2. Inventory the documents

For each relevant document, capture:

• scope
• claimed maturity
• owner expression
• doc kind
• related code areas
• canonical dependencies
• whether it appears quarantined or unresolved

The point is to build a verification map, not just a file list.

3. Validate against code

Treat code as source of truth when docs and implementation diverge.

Check:

• handlers, commands, APIs, or modules named by the doc
• state models and persisted artifacts
• tests that confirm claimed behavior
• generated files or runtime surfaces the doc says should exist
• whether the current folder or owner placement still matches the real responsibility boundary

Do not mark a plan as landed just because another document says so.

4. Classify drift

Common drift patterns:

• maturity drift: index says draft, but code and the single doc show partial
• single-doc drift: the single doc overstates implementation
• terminology drift: code vocabulary changed, but docs still use old names
• boundary drift: one doc now mixes multiple responsibility boundaries
• owner drift: the doc's responsibility moved, but its owner expression did not
• folder-placement drift: the file now lives under the wrong owner folder
• quarantine drift: a doc is still parked in an unresolved bucket even though a safe owner now exists
• cross-link drift: doc moves happened, but registry links or references were not updated

5. Update with the smallest stable change

When editing:

• prefer updating an existing doc if the responsibility boundary is unchanged
• create a new doc only when the problem boundary genuinely changed
• keep maturity labels, current status, and registry entries aligned
• keep owner expression aligned with the repo's chosen model
• if owner is expressed by folder path, move the file instead of reintroducing handwritten owner metadata
• use a quarantine owner only when a safe owner cannot yet be named
• distinguish clearly between implemented behavior and intended behavior

6. Report outcomes

Close with a short report grouped as:

• verified
• partially verified
• registry drift
• owner or folder drift
• unresolved quarantine docs

Working Rules

• Keep each plan focused on one responsibility boundary.
• Keep current status near the top of each plan when the repo uses per-doc status.
• Separate current behavior from proposal text.
• Keep the registry and the single-doc status in sync.
• If the repo separates status view and owner view, preserve that split.
• If folder path already expresses owner, do not duplicate owner in the index unless the repo explicitly requires it.
• Treat quarantine owners or unresolved-owner folders as owner constructs, not maturity buckets.
• Canonical boundary docs beat shorthand summaries in the registry.
• Avoid using a plan directory as an unstructured idea dump.

Cross-Repo Adaptation

This skill is meant to transfer across repositories. Adapt only these local variables:

• registry path
• document naming convention
• maturity labels
• owner-expression model
• canonical index file
• canonical boundary doc
• authoring-guide location

Keep the workflow unchanged unless the repo already has a stronger local convention.

Read On Demand

• For a reusable single-plan shape, read references/plan-template.md.
• For maturity semantics and reclassification rules, read references/maturity-model.md.
• For audit work, including owner and folder checks, read references/audit-checklist.md.