# Repo Governance

> Use when the user asks about repository documentation governance — AGENTS.md scaffolding, a repo bootstrap, a roadmap alignment review, a doc curation pass, sanitizing a repository before publishing, or which governance command to run next. Guides the `aeo-repo-*` command family and its lifecycle sequencing: bootstrap a scaffold, iterate with alignment reviews and curation passes, sanitize before publishing. Trigger phrases include "set up AGENTS.md", "curate the docs", "align the roadmap", and "is this repo safe to publish".

- Skill: `aeyeops/repo-governance` (Agent Skill)
- Install (CLI): `npx skillmds@latest add aeyeops/repo-governance`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aeyeops/repo-governance/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- License: MIT
- Author: AeyeOps (https://skillmd.com/u/aeyeops)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/aeyeops/repo-governance

---


# Repository Governance

## Purpose

Keep repository documentation honest. Code evolves faster than the docs that describe it —
roadmap items get implemented but never retired, architecture docs describe plans instead of
reality, and issue trackers accumulate resolved items. This command family closes that gap
by providing a repeatable lifecycle: establish structure, check alignment, curate what's
stale, and verify before sharing.

## Intent

Documentation governance is not about volume — it's about signal. A repository where
`docs/roadmap/` only contains active plans and `docs/architecture/` only contains implemented
designs is more useful than one with comprehensive but stale artifacts. These commands treat
documentation as a living system with an explicit lifecycle: planning docs are born in
`roadmap/`, mature into `architecture/` or `modules/` when implemented, and retire to
`_archive/` with provenance when they no longer reflect reality.

The governance scaffold uses `AGENTS.md` policy files because they give every directory a
contract — what belongs there, how content enters and exits, and what quality means in that
context. This helps both human contributors and AI agents make consistent decisions about
where to put things and when to move them.

## Command Family

| Command | Verb | Modifies files? |
|---------|------|-----------------|
| `/aeo-repo-bootstrap` | Establish the governance scaffold | Yes |
| `/aeo-repo-roadmap-alignment-review` | Diagnose implementation vs roadmap drift | No |
| `/aeo-repo-curate-docs` | Retire, trim, and archive stale docs | Yes |
| `/aeo-repo-sanitize` | Scan for secrets, PII, supply-chain risk | Yes (with approval) |

## Lifecycle

### 1. Bootstrap (once)

`/aeo-repo-bootstrap` creates the scaffold: `AGENTS.md` policy files at 10 locations,
`docs/` subdirectories by purpose, `tmp/` and `_archive/` utility directories, and
language-aware `.gitignore` additions. Idempotent — detects whether to initialize or
augment based on what already exists, and merges rather than overwrites.

Run this first. The other governance commands assume this structure.

### 2. Review → Curate (iterative)

Two commands form a feedback loop:

```
    /aeo-repo-roadmap-alignment-review
    (read-only: identifies drift, stale docs, gaps)
                    │
                    ▼
    /aeo-repo-curate-docs
    (acts: archives done, trims partial, updates issues)
                    │
                    ▼
              commit, repeat
```

**Alignment review** is safe to run anytime because it only reads. It compares implementation
evidence against roadmap intent, flags drift, and recommends three prioritized next steps.
Use it as a status pulse — after a sprint, before planning, or when docs feel stale.

**Curate docs** acts on what the review found. It classifies each roadmap artifact against
the codebase using evidence-first reasoning, then:
- Archives fully implemented items to `_archive/` with path provenance
- Trims partially implemented docs to remaining scope only
- Leaves unimplemented items in place (conservative default)
- Updates issue trackers in whatever format they already use

Typical cadence: review after each milestone, curate when review flags stale artifacts,
commit, review again to confirm docs match reality.

### 3. Sanitize (before sharing)

`/aeo-repo-sanitize` is independent of the governance scaffold — it works on any repository.
Run before making a repo public, pushing to a shared remote, or onboarding collaborators.

<reference>
Scaffold structure created by bootstrap:

repo/
├── AGENTS.md                     # Root governance policy
├── docs/
│   ├── AGENTS.md                 # Docs directory contract
│   ├── roadmap/   + AGENTS.md    # Active planning (→ architecture when done)
│   ├── adr/       + AGENTS.md    # Architecture decision records
│   ├── architecture/ + AGENTS.md # Implemented system design
│   ├── modules/   + AGENTS.md    # Per-module documentation
│   ├── issues/    + AGENTS.md    # Issue tracking (row or file based)
│   └── kb/        + AGENTS.md    # Knowledge base
├── tmp/           + AGENTS.md    # Ephemeral working files (gitignored)
└── _archive/      + AGENTS.md    # Retired artifacts with provenance (gitignored)

Document lifecycle flow:
  roadmap/ → (implemented) → architecture/ or modules/
  roadmap/ → (obsolete) → _archive/docs/roadmap/
  issues/  → (resolved) → _archive/docs/issues/
</reference>

## When to Suggest Each Command

| User signal | Suggest |
|-------------|---------|
| Setting up a new project, wants structure | `/aeo-repo-bootstrap` |
| Asks "are we on track?" or "what's drifted?" | `/aeo-repo-roadmap-alignment-review` |
| Finished a milestone, wants to clean up docs | `/aeo-repo-curate-docs` |
| Preparing to publish or share the repo | `/aeo-repo-sanitize` |
| Says "docs feel stale" or "roadmap is outdated" | Alignment review first, then curate |
| Asks which command to run next | Check if scaffold exists → if not, bootstrap; if yes, alignment review |

## Design Principles

These inform how the commands behave and why — useful context when the user asks "why did
it do X?" or wants to customize the approach.

- **Evidence over assumption**: Curate-docs inspects actual code paths before classifying a
  roadmap item, because surface-level directory matches mislead. Ambiguous cases default to
  keeping the item active rather than archiving prematurely.
- **Archive with provenance**: Retired docs move to `_archive/` mirroring their source path
  (`docs/roadmap/x.md` → `_archive/docs/roadmap/x.md`) because being able to trace where
  something came from matters more than saving directory depth.
- **Format-adaptive**: Curate-docs detects whether issues use row-based trackers (CSV/JSONL)
  or file-based docs and adapts its actions accordingly, because imposing a new schema on an
  existing tracker disrupts workflows.
- **Generic by default**: Bootstrap creates framework-agnostic policy content. Projects
  customize their AGENTS.md files over time — the scaffold provides structure, not opinions
  about the project's domain.
- **Read-only diagnostics are free**: Alignment review modifies nothing, so suggest it
  liberally. Curate-docs modifies files, so confirm the user's intent before running it.