align-docs

name	align-docs
description	Use when user wants project docs (AGENTS.md, .agents/rules, docs/, README) aligned with the codebase, or the agent context compatible with both Claude Code and Codex CLI. Captures session discoveries; --clean consolidates obsolete chronicles/plans into ATLAS.md. Triggers on /align-docs, convert agent context.
user-invocable	true
allowed-tools	Read, Edit, Write, Bash, Glob, Grep, AskUserQuestion

Align Docs — one canonical agent context

Claude Code, Codex CLI, and every other agent read the same canonical context from the repo, without duplication. Convert structure where missing, capture what the session learned, then reduce every docs/agents file and project memory to the most critical, non-trivial domain · infrastructure · company · project-specific facts in the fewest words that stay clear. Everything else is noise — removed. The repo is the only context teammates share: anything load-bearing outside it is invisible to them and lost.

Target architecture

repo/
├── CLAUDE.md                  # single line: @AGENTS.md
├── AGENTS.md                  # canonical context, ≤70 lines, references rules by path
├── .agents/rules/             # single source of truth — path-scoped rule files
├── .claude/
│   ├── rules → ../.agents/rules   # symlink; Claude auto-loads
│   └── CLAUDE.md                  # gitignored — personal per-project (Claude)
└── .gitignore                 # ignores .claude/CLAUDE.md and AGENTS.override.md

Agent	Discovery
Claude Code	CLAUDE.md → @AGENTS.md import; .claude/rules/*.md auto-loaded recursively (symlinks OK), gated by paths: frontmatter
Codex CLI	Native AGENTS.md walk-up; at most ONE file per directory; precedence AGENTS.override.md > AGENTS.md; no imports — agent must Read rule files when in scope

Step 0 — Root & mode

root=$(git rev-parse --show-toplevel 2>/dev/null) || root=. — all paths below resolve under $root. $ARGUMENTS contains --clean / clean → read references/clean-mode.md and follow it (runs Steps 1-7, then deep consolidation).

Step 1 — Inventory

ls -la CLAUDE.md AGENTS.md .claude/rules .agents/rules MEMORY.md 2>&1
wc -l AGENTS.md CLAUDE.md 2>&1
grep -nE "\.claude/CLAUDE\.md|AGENTS\.override\.md" .gitignore 2>&1
ls ~/.claude/projects/*/memory/ 2>&1   # pick the dir matching this project

Report what exists, what's missing, what's over budget. Then diff docs against disk: structure trees vs ls, versions vs manifests, README tables (skills/agents/shared) vs directories, every referenced path exists, links resolve.

Step 2 — Structure (idempotent)

• CLAUDE.md — overwrite with exactly one line, no trailing prose: @AGENTS.md
• .agents/rules/ — create if missing. One topic per file, descriptive name. Every file starts with scope frontmatter (else it loads into Claude's context every session):

---
paths:
  - "src/**"
---

• Symlink — mkdir -p .claude; [ -e .claude/rules ] || ln -s ../.agents/rules .claude/rules; commit it (git stores symlinks natively on Unix).
• .gitignore — append .claude/CLAUDE.md and AGENTS.override.md if missing. Tell the user: personal notes → .claude/CLAUDE.md (Claude, auto-loaded) or ~/.codex/AGENTS.md (Codex, user-global); AGENTS.override.md replaces shared AGENTS.md — avoid unless scoped to a subdirectory.

Step 3 — AGENTS.md (≤70 lines)

Prepend this block at the top; if a similar one exists, replace it:

# {Name of the project}

## Principles to always follow

Think critically from first principles; prize simplicity above all. Maximize efficiency, maintainability, and state-of-the-art quality while keeping every requested feature. Say everything in the fewest clear words. These principles bind every line, claim, gate, skill, phase, and subagent in development-skills; any skipped gate, suppressed test, swallowed warning, or hidden failure is a violation, whatever the intent. On conflict, pick the application least surprising to a critical reader.

0. **Don't pander · be critical.** Challenge assumptions, push back on bad ideas. No flattery openers. User confirmation validates the decision, not the analysis.
1. **Think before coding.** State assumptions explicitly. Ask when unclear. Don't guess, don't hide confusion.
2. **Plan before implementing.** Explore → plan → lock the HOW (edge cases · data shapes · error semantics · contract boundaries · test scope · rollback) → code.
3. **Simplicity by default.** Minimum code that solves the problem. Filters before adding anything: can this be one fewer file / abstraction / config / dependency? · would removing it cause a real failure? A refactor must measurably improve one of: clear · descriptive · efficient · performant · reliable · robust · maintainable.
4. **Surgical changes.** Every changed line traces to the request. No refactoring of adjacent code. No error handling for impossible scenarios. Clean up only your own mess.
5. **All signal, zero noise.** No dead branches, no defensive try/catch on safe paths, no wrapper-for-nothing functions, no unused imports. No filler openers, no trailing summaries when the diff is the answer.
6. **Comments explain WHY, not WHAT.** Non-obvious business logic, hidden constraints, workarounds — yes. Restating what the next line does — no.
7. **TDD: Red → Green → Refactor.** No production code without a failing test first. One test = one cycle. Wrote production code before the test? Delete it. Untestable (UI-heavy / infrastructure / config-only) → closest automated check + documented WHY + manual evidence.
8. **No claim without fresh evidence.** IDENTIFY → RUN → READ → VERIFY → CLAIM. *"I'm confident"* is not a step. Skipping any step = lying, not verifying.
9. **Root cause, not symptoms.** Fix the underlying error, never suppress it. `# type: ignore`, swallowed exceptions, disabled tests, `--no-verify` are admissions the bug is winning.
10. **Document every discovery** (anything you lacked at the start — non-obvious, domain·infrastructure·company·project-specific). WHY → `docs/chronicles/`, HOW → `docs/plans/`; a critical always-read fact → one line in the `AGENTS.md` list; a topic with depth → `.agents/rules/<topic>.md` (same convention), indexed from `AGENTS.md`. Fewest words. Pay investigation costs once.
11. **No commits without explicit user request.** Approving a plan, completing phases, passing review — none are permission. Omit AI-attribution trailers when authorized (e.g. "Co-Authored By ...")
12. **Slim docs · English · memory ≈ empty.** `AGENTS.md` ≤ 70 lines: principles → *use development-skills* → single fewest-words list of the most critical, non-trivial domain·infra·company·project facts → index to `.agents/rules/`; no section headings. Each rules file: same convention, vertical per topic. English only across all artifacts. Teammates share only the repo — memory is per-machine and invisible to them: project facts live in `AGENTS.md` / `.agents/rules/`, never in memory; machine-specific facts → gitignored `.claude/CLAUDE.md` / `~/.codex/AGENTS.md`; memory stays ≈ empty.

Always use the `development-skills` plugin for every task on this project (brainstorming, development, bug fixing, new feature, ...). If the plugin is not available on the user's system, notice it and tell the user to download it.

Then, in this order and nothing else — no section headings or decoration:

• Project scope (1-2 sentences)
• Single fewest-words list of the most critical, non-trivial domain·infra·company·project facts (safety rules, test commands; tables/commands beat prose)
• Rules index table at the bottom — one row per file in .agents/rules/: Rule | Scope (paths:) | Topic

If it's in a rule file, reference — never duplicate.

Step 4 — Capture session discoveries

Cold invocation (no prior work this session) → state "CAPTURE: NONE". Else harvest what this session learned that it lacked at the start:

• Non-inferable only — domain·infra·company·project-specific, not derivable from the code. No structure/architecture overviews.
• Idempotent — write only facts not already on disk.
• Critical always-read fact → AGENTS.md line; topic with depth → .agents/rules/<topic>.md + index row. Never memory.

Step 5 — Memory sweep

Memory is per-machine: teammates share only the repo, so facts parked there diverge per person and get lost. Read every project-memory file (Claude auto-memory ~/.claude/projects/<project>/memory/, repo MEMORY.md if present):

• Critical, non-trivial domain·infra·company·project fact → move to AGENTS.md or .agents/rules/<topic>.md, delete from memory.
• Machine-specific (env paths, personal tooling) → gitignored .claude/CLAUDE.md / ~/.codex/AGENTS.md.
• Leave memory ≈ empty: only what fits neither home.

Step 6 — Total cleanup

Not just AGENTS.md ≤ 70 lines: audit every docs/agents file — AGENTS.md, CLAUDE.md, .agents/rules/**, READMEs, docs/**. Every line passes one gate: most critical, non-trivial fact the next agent must read — domain·infra·company·project-specific — in the fewest words? Keep it at its right home (always-read → AGENTS.md · topic depth → rules file · WHY → chronicle · HOW → plan), else delete.

• Fix misalignments found in Step 1 (structure, versions, paths, README tables, index rows — including files added in Steps 4-5). Chronicle bodies are immutable — touch only if they reference incorrect content.
• Remove noise: entries referencing nonexistent things · duplicates (keep once, link from others) · empty sections/placeholders · generic content the agent already knows from general training.
• Preserve all load-bearing content (safety rules, domain glossary, test commands, rules index) — shrink the expression, never the function.

Step 7 — Self-verify

wc -l AGENTS.md CLAUDE.md
[ "$(cat CLAUDE.md | tr -d '[:space:]')" = "@AGENTS.md" ] && echo "CLAUDE.md OK"
readlink .claude/rules && diff <(ls .claude/rules/) <(ls .agents/rules/) && echo "symlink OK"
git check-ignore -v .claude/CLAUDE.md AGENTS.override.md

Report: AGENTS.md line count (≤70) · rule files vs index rows (must match) · symlink status · gitignore entries · memory residue after sweep.

Hard gates — STOP if

• CLAUDE.md is not exactly @AGENTS.md.
• AGENTS.md exceeds 70 lines — trim further.
• A rule file lacks paths: frontmatter.
• A rule file is absent from the AGENTS.md index table.
• A domain·infra·company·project fact survives only in memory.

Anti-patterns

Bad	Good
@rules/x.md import inside AGENTS.md — Codex has no imports	Textual index row: | .agents/rules/x.md | src/** | topic |
Rule file without paths: frontmatter — loads every session	Path-scoped frontmatter
AGENTS.override.md committed beside AGENTS.md — two sources of truth	Personal Codex notes in ~/.codex/AGENTS.md; override only per-subdirectory, gitignored
Project facts in memory / MEMORY.md	In repo: AGENTS.md or .agents/rules/

Never commit .claude/CLAUDE.md or AGENTS.override.md.