| name | repo-align |
| description | This skill should be used when the user says "repo-align", "align the repo", "clean up the repo", "check for drift", "is the repo in good shape", "find contradictions", "what's gotten messy", "doc cleanup", "are my docs consistent", "tidy up the docs", or when startup's trust report went red. The deep, opt-in alignment pass: mechanical scans (drift, freshness, structure drift, vocabulary, size budgets) plus judgment passes — a doc router that reads off-shelf files and proposes where their content belongs, a routes-vs-api.md and modules-vs-module-map diff, and an on-request rules audit of AGENTS.md. Proposes before acting on every judgment call; preserves history with git mv; never silently merges, deletes, or archives.
|
| argument-hint | [--report-only] [--rules-audit] |
| user-invocable | true |
| allowed-tools | Read Glob Grep Bash Write Edit AskUserQuestion |
Repo Align — bring the repo back to the shelf
The deep, opt-in pass — run it every ~25 commits or when the trust report goes red.
Find documentation drift, surface it in plain English, and propose one disposition
per judgment call — always confirmed before acting. Never silently merge, delete,
archive, or rewrite.
The model you're aligning to is <plugin-root>/references/shelf-spec.md — the
context stack (L0 AGENTS.md ≤40 lines, L1 docs/handoff.md ≤60 lines), the closed
shelf of docs under docs/, active initiatives, vocabulary profiles, the one-writer
table, and domain authority. Read it before judging.
With --report-only, do steps 1–3 (find and present) and stop — propose no changes.
1. Run the mechanical scans
Pure-stdlib, advisory. Capture each JSON; they surface candidates, not verdicts.
Your judgment decides which are real. (Use python3, or python on Windows.)
PLUGIN_ROOT=$( [ -d "./plugins/rad-repo-manager" ] && echo "./plugins/rad-repo-manager" || echo "${CLAUDE_PLUGIN_ROOT:-$HOME/.gemini/config/plugins/rad-repo-manager}" )
python3 "$PLUGIN_ROOT/scripts/repo-scan.py" . --json --no-record
python3 "$PLUGIN_ROOT/scripts/doc-freshness.py" . --json
python3 "$PLUGIN_ROOT/scripts/structure-drift.py" . --json
python3 "$PLUGIN_ROOT/scripts/vocab-lint.py" . --json
python3 "$PLUGIN_ROOT/scripts/doc-contradiction.py" . --json
python3 "$PLUGIN_ROOT/scripts/doc-redundancy.py" . --json
python3 "$PLUGIN_ROOT/scripts/audit-user-content.py" . --json
(If Python 3 is unavailable, do the same checks by reading the docs directly and say
the mechanical pass was skipped.)
Size budgets: the repo-scan JSON flags l0_over_budget (root AGENTS.md > 40 lines)
and l1_over_budget (handoff > 60 lines). L0 overflow is a rules-audit trigger
(step 2d); L1 overflow means durable content leaked into the handoff — route it to
plan.md/prd.md/lessons.md in step 4.
2. The judgment passes
2a. Doc router — read what's off the shelf, route its content
For every file the scan flagged as floating (created since the last pass, not on the
shelf): read it — don't just report the filename. Classify what's inside and
propose a routing per finding, e.g. "this file is three settled decisions and one
idea — append them to docs/decisions.md / docs/ideas.md, then archive the file?"
Transient brainstorm specs (docs/*-spec.md / *-design.md) whose plan already
exists get proposed for docs/archive/. An approved finite migration may instead be
routed to docs/initiatives/<slug>.md from templates/initiative.md; require all
lifecycle metadata and a link from docs/plan.md. A domain reference doc with no shelf slot is
a satellite, not a loose end — propose a link from the nearest core doc if it's
unlinked, and leave it in place (shelf-spec "Satellite docs" / "Conformance without
loss"). Propose, never silently act.
2b. Vocabulary lint
Read the vocab-lint findings. Advisory synonym hits invite a proposed reword; strict
profile hits must be resolved before the check is green. Judge each candidate —
"staging environment" is not a tracked unit — and preview every drafting edit.
Ladder terms in the wrong doc still need routing. Content-level plan
problems get flagged to /rad-planner:replan, not fixed here (format is this
plugin's lane; plan substance is the planner's).
2c. Structure drift — api.md routes and architecture.md's module map
structure-drift.py (step 1) already did the mechanical diff; this pass judges its
candidates and drafts the doc edits.
- api.md (when it exists): routes in code but not the doc → propose the missing
lines; routes in the doc but not the code → propose removal. If the script found
no route patterns for this codebase, fall back to a manual grep — Express/Fastify
app.get|post|...(, Next.js app/**/route.ts / pages/api/**, Flask/FastAPI
decorators, Rails routes.rb — and say the diff was inconclusive rather than
guessing.
- architecture.md (when it exists): source modules absent from the
## Module map → propose rows (name · what it owns · entry point · LOCKED flag where a
decision record pins a boundary); map rows whose module is gone → propose removal.
If architecture.md has no ## Module map section yet, draft one from the actual
source tree (this is the one place a map gets bolted onto a legacy
architecture.md) and propose it as a single addition, per the shelf-spec format.
2d. Rules audit — on request (--rules-audit) or when L0 is over budget
For each rule in AGENTS.md, classify by evidence (git history, lessons.md, what
you can observe in the repo — say when evidence is thin):
- Promote to hook — violated in practice AND mechanically checkable.
- Keep — violated in practice, needs judgment; it earns one of the ≤7 hard-rule
slots.
- Demote — dormant (no sign it's been needed in months) → move to a referenced
guardrails file (
docs/archive/ or a linked doc), leaving L0 lean.
Present the classification with one line of reasoning per rule. Propose-only — the
owner decides every move; this is how a beloved-but-bloated AGENTS.md gets condensed
without losing the guardrails the owner values.
2e. The classic drift checks
Read the shelf docs that exist plus CLAUDE.md, README.md, docs/archive/ names
(not contents). Identify: duplicate authorities, stale docs, pointer chains, missing
docs whose triggers have clearly fired, contradictory read paths, off-model
status/roadmap docs, scoped AGENTS.md files without materially different subtree
rules, scoped overlays missing a one-line CLAUDE.md shim, duplicate root facts in
scoped files, and root-README content that has become stale status.
Resolve contradictions by domain authority (shelf-spec): applicable root/scoped
instructions and locked ADRs govern constraints; prd.md governs product intent;
code plus architecture.md/api.md govern current state; plan.md and active
initiatives govern approved future change; design.md governs visual direction;
handoff is only a session snapshot. A plan never overrides a locked ADR. Propose the
edit to the incorrect domain document (step 5). If authorities in the same domain
disagree, or the owner has not made the product decision, STOP and surface it under
"Needs a decision." Never silently merge two conflicting decisions.
Check the role boundaries — each doc holds only its own kind of content:
execution detail in the PRD → plan.md; permanent product rules in the plan → prd.md;
durable facts in the handoff → plan/prd/lessons; product summaries or roadmap in
AGENTS.md → replace with a pointer. Settled decisions stranded in a brainstorm, the
handoff, or AGENTS.md → propose appending to docs/decisions.md (visual/design
decisions → docs/design.md).
Terminology / superseded sweep. If AGENTS.md has a ## Retired terminology
table, grep the managed docs for each retired term and flag stray uses (suggest the
replacement). Regardless, flag any doc that calls something "current" when newer
evidence in the same domain has overtaken it, and any superseded content lacking a
superseded banner.
3. Present findings — plain language, grouped
# Repo alignment
## Needs a decision
- The plan builds offline mode, but the PRD lists offline as a non-goal. Which wins?
## Doc router
- `docs/2026-06-28-notes.md` — contains two settled decisions and an idea: append to decisions.md/ideas.md, archive the file?
## Vocabulary
- `docs/prd.md:14` says "sprint 2" — the ladder term is Milestone (M2), and it belongs in plan.md, not the PRD.
## Size budgets
- `AGENTS.md` is 57 lines (budget 40) — rules audit below proposes what to demote.
## Structure drift
- `POST /api/upload` exists in code but not in docs/api.md.
- `src/stores/` has no row in architecture.md's module map.
## Conflicts / redundancy / role-boundary leaks
- `docs/prd.md` and `AGENTS.md` both define the validation steps — pick one home.
## Rules audit (when run)
- "Never push without tests" — violated twice, mechanically checkable → promote to a hook.
## Loose / misplaced docs · pointer problems · missing docs
- `smoke-2026-05-30.md` (repo root) — a smoke-test report sitting loose.
## Suggested actions
[per-item dispositions below]
No jargon, no validator names in the user-facing report — describe the problem and
the fix in words a non-coder follows.
4. Offer fixes — closed disposition set, confirmed per item
For each finding, propose ONE disposition and ask before acting (via
AskUserQuestion, ask_question on Antigravity, or a clear yes/no per item):
- Route — append the content to its shelf home (decisions/ideas/lessons/design), then archive the original.
- Fold — merge durable content into the owning shelf doc, then archive the original.
- Archive — historical / done →
git mv into docs/archive/, add the archive banner.
- Relocate — a misplaced doc → move to its shelf home.
- Banner — content overtaken but staying in place → add a superseded banner pointing at the current authority.
- Reword — a vocabulary or budget fix inside a doc this plugin may edit.
Rules:
- Propose, never auto-act. Every route/fold/move/delete waits for the user's yes.
- Preserve history: move tracked files with
git mv, never delete-and-recreate.
- Append-only files stay append-only — route content by appending new entries,
never by editing existing decisions/ideas/lessons lines.
- Keep
CLAUDE.md/GEMINI.md as thin @AGENTS.md pointers — if one has grown
its own content, propose folding it into AGENTS.md and restoring the shim.
- After approved moves, confirm the L0/L1 read path still points at reality.
5. Durable changes — draft the edit, apply only on explicit confirmation
When a finding implies a change to a doc the manager doesn't write — docs/prd.md,
docs/design.md, or docs/plan.md content — the user owns the decision, not the
typing. Draft the exact edit (old → new) and ask per doc via AskUserQuestion:
apply / skip / let me reword. Apply only on an explicit "apply" for that specific
edit; a skip means hands off, restated in one line at the end. Never bundle
user-owned edits into a blanket OK. Structural plan problems go to
/rad-planner:replan, not to an edit here.
6. Stamp the run — align cadence tracking
At the end of the pass (including --report-only runs — the repo was inspected
either way), record it:
python3 "$PLUGIN_ROOT/scripts/repo-scan.py" . --record-align --json >/dev/null
This stamps the current HEAD into .rad/repo-manager-state.json; startup, ship,
and the SessionStart hook read it to report "last align was N commits ago" against
the ~25-commit cadence. Skip silently if Python is unavailable.
What this skill does NOT do
- Does not auto-apply judgment calls — every move/merge/archive/reword is user-confirmed.
- Does not write
docs/prd.md/docs/design.md without an explicit per-edit "apply".
- Does not edit existing entries in append-only docs.
- Does not create
docs/status.md, docs/roadmap.md, docs/implementation-plan.md,
loose root status docs, speculative scoped instructions, or scoped AGENTS.md
files without matching one-line CLAUDE.md shims.
- Does not run on every session — it's the opt-in deep pass (
/ship runs only the
mechanical scans, none of the judgment passes).
References
<plugin-root>/references/shelf-spec.md — shelf, profiles, budgets, initiatives, one-writer table, domain authority<plugin-root>/scripts/ — drift scans, repository contract discovery, and pre-ship gate
