/align

name: align
description: "Unified alignment command (--project, --docs, --retrofit, --content)"
argument-hint: "[--project [--invariants] | --docs | --retrofit | --content] [--dry-run] [--auto]"
version: 3.1.0
category: core
allowed-tools: [Read, Write, Edit, Grep, Glob]
disable-model-invocation: true
user-invocable: true
user_facing: true

/align - Unified Alignment Command

**Purpose**: Validate and fix alignment between PROJECT.md, documentation, and codebase.

**Default**: `/align` runs full alignment check (docs + code + hooks review)

**Modes**:

• `/align` - Full alignment (PROJECT.md + CLAUDE.md + README vs code + hooks review)
• `/align --project --invariants` - Derive or audit the `### INVARIANTS` section of PROJECT.md (approval-gated; opts a brownfield repo into the #1467 architecture-delta gate)
• `/align --docs` - Documentation only (ensure all docs consistent with PROJECT.md)
• `/align --retrofit` - Brownfield retrofit (5-phase project transformation)
• `/align --content` - Content allocation audit (CLAUDE.md/PROJECT.md/MEMORY.md sizing + de-dup)

---

Quick Usage

# Default: Full alignment check
/align

# Documentation consistency only
/align --docs

# Brownfield project retrofit
/align --retrofit
/align --retrofit --dry-run
/align --retrofit --auto

# Content allocation audit
/align --content
/align --content --dry-run
/align --content --auto

---

Mode 1: Full Alignment (Default)

**Purpose**: Comprehensive check that PROJECT.md, CLAUDE.md, README, and codebase are all aligned.

**Time**: 10-30 minutes

**What it does**:

Phase 1: Quick Scan (GenAI or Regex)

Run manifest alignment validation:

# With OpenRouter (recommended - cheap GenAI validation)
OPENROUTER_API_KEY=sk-or-... python plugins/autonomous-dev/lib/genai_validate.py manifest-alignment

# Without API key (hybrid validator with regex fallback)
python plugins/autonomous-dev/lib/hybrid_validator.py --mode regex-only

**Validates**:

• Count mismatches (agents, commands, hooks, skills) vs install_manifest.json
• Version consistency (CLAUDE.md, PROJECT.md, manifest)
• Semantic alignment (GenAI mode only)

**Options**:

• **OpenRouter** (recommended): ~$0.001 per validation, uses Gemini Flash
• **Claude Code**: Semantic analysis in conversation (uses Max subscription)
• **Regex only**: Fast, free, catches count mismatches

Phase 2: Semantic Validation (GenAI)

Check the following:

**PROJECT.md vs Code**:

• Do GOALS match what's implemented?
• Is SCOPE (in/out) respected in code?
• Are CONSTRAINTS followed?
• Does ARCHITECTURE match directory structure?

**CLAUDE.md vs Reality**:

• Do workflow descriptions match actual behavior?
• Do agent descriptions match capabilities?
• Do command descriptions match what they do?
• Are documented features actually implemented?

**README vs Reality**:

• Do feature claims match implementation?
• Are installation instructions accurate?
• Do examples actually work?

Phase 3: Hooks/Rules Review

MUST review validation hooks for inflation:

• Are hooks still necessary?
• Do hook rules match current standards?
• Any redundant or conflicting hooks?

Phase 4: Interactive Resolution (Bidirectional)

For each conflict found, determine which source is correct:

**Documentation vs Reality conflicts:**

CONFLICT: CLAUDE.md says "10 active commands"
Reality: 7 commands exist (example - already fixed)

What should we do?
A) Update CLAUDE.md to say "7 commands"
B) This is correct (explain why)

Your choice [A/B]:

**Code vs PROJECT.md conflicts (Bidirectional):**

CONFLICT: /create-issue exists in code/docs but not in PROJECT.md SCOPE

Which is correct?
A) Code/docs are right → Update PROJECT.md to include /create-issue
B) PROJECT.md is right → This shouldn't have been built (flag for removal)

Your choice [A/B]:

If A: Propose PROJECT.md update (requires approval) If B: Log conflict for manual resolution

Example Output

/align

Phase 1: Quick Scan
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✓ Scanning file system for truth...
  Agents: 20, Commands: 7, Hooks: 45, Skills: 28

Found 5 count mismatches, 3 dead refs
→ Will address in Phase 4

Phase 2: Semantic Validation
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Checking PROJECT.md alignment...
✓ GOALS: 4/4 implemented
✓ SCOPE: No out-of-scope code found
⚠ ARCHITECTURE: docs/ structure doesn't match documented pattern

Checking CLAUDE.md alignment...
✓ Workflow descriptions accurate
⚠ Agent count outdated (says 18, actual 20)
⚠ Command list missing /create-issue

Checking README alignment...
✓ Installation instructions work
✓ Examples are accurate

Phase 3: Hooks Review
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Reviewing 45 hooks for inflation...
⚠ validate_project_alignment.py duplicates alignment_fixer.py logic
⚠ 3 hooks reference archived commands

Phase 4: Resolution
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Found 8 issues to resolve...
[Interactive fixing begins]

---

Mode 2: Documentation Alignment (`--docs`)

**Purpose**: Ensure all documentation is internally consistent and matches PROJECT.md (source of truth).

**Time**: 5-15 minutes

**What it does**:

Checks Performed

1. **PROJECT.md as Source of Truth**

• All other docs reference PROJECT.md correctly
• No contradictions between docs and PROJECT.md
• Version/date consistency

2. **Internal Doc Consistency**

• CLAUDE.md matches README claims
• Agent docs match AGENTS.md
• Command docs match COMMANDS.md
• No orphaned documentation

3. **Architecture Documentation**

• Documented file structure matches reality
• API documentation matches actual endpoints
• Database schema docs match migrations

4. **Count/Reference Accuracy**

• All counts (agents, commands, hooks) correct
• No dead links or references
• Examples use correct syntax

What It Doesn't Do

• Doesn't check if code implements what docs say (use default `/align` for tha