12 KiB

Raw Blame History

name

description

argument_hint

version

/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 --docs - Documentation only (ensure all docs consistent with PROJECT.md)
/align --retrofit - Brownfield retrofit (5-phase project transformation)

Quick Usage

# Default: Full alignment check
/align

# Documentation consistency only
/align --docs

# Brownfield project retrofit
/align --retrofit
/align --retrofit --dry-run
/align --retrofit --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 (regex fallback)
python plugins/autonomous-dev/lib/validate_manifest_doc_alignment.py

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)

Run alignment-analyzer agent to check:

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

Check for inflation in validation hooks:

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_claude_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

PROJECT.md as Source of Truth
- All other docs reference PROJECT.md correctly
- No contradictions between docs and PROJECT.md
- Version/date consistency
Internal Doc Consistency
- CLAUDE.md matches README claims
- Agent docs match AGENTS.md
- Command docs match COMMANDS.md
- No orphaned documentation
Architecture Documentation
- Documented file structure matches reality
- API documentation matches actual endpoints
- Database schema docs match migrations
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 that)
Doesn't modify code, only documentation
Doesn't retrofit project structure

Example Output

/align --docs

Validating documentation consistency...

Source of Truth: PROJECT.md
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✓ Last updated: 2025-12-13
✓ Version: v3.40.0

Cross-Reference Check
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✓ CLAUDE.md references PROJECT.md correctly
✓ README.md and PROJECT.md both say 7 commands
✓ docs/AGENTS.md matches agents/ directory

Architecture Docs
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✓ File structure documented correctly
⚠ docs/LIBRARIES.md missing 5 new libraries

Count Validation
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Running alignment_fixer.py...
Found 3 count mismatches in documentation

Summary: 3 issues found
Fix with: /align --docs --fix

Mode 3: Brownfield Retrofit (`--retrofit`)

Purpose: Transform existing projects to autonomous-dev standards for /auto-implement compatibility.

Time: 30-90 minutes

Workflow: 5-phase process with backup/rollback safety

Phases

Phase 1: Analyze Codebase

Tool: codebase_analyzer.py
Detects: Language, framework, package manager, test framework, file organization
Output: Comprehensive codebase analysis report

Phase 2: Assess Alignment

Tool: alignment_assessor.py
Calculates: Alignment score, gaps, PROJECT.md draft
Output: Assessment with prioritized remediation steps

Phase 3: Generate Migration Plan

Tool: migration_planner.py
Creates: Step-by-step plan with effort/impact estimates
Output: Optimized migration plan with dependencies

Phase 4: Execute Migration

Tool: retrofit_executor.py
Modes: --dry-run (preview), default (step-by-step), --auto (all at once)
Safety: Automatic backup, rollback on failure

Phase 5: Verify Results

Tool: retrofit_verifier.py
Checks: PROJECT.md, file organization, tests, docs, git config
Output: Readiness score (0-100) and blocker list

Usage

# Preview what would change
/align --retrofit --dry-run

# Step-by-step with confirmations (safest)
/align --retrofit

# Automatic execution (fastest)
/align --retrofit --auto

What Gets Retrofitted

PROJECT.md Creation - GOALS, SCOPE, CONSTRAINTS, ARCHITECTURE
File Organization - Move to .claude/ structure
Test Infrastructure - Configure test framework and coverage
CI/CD Integration - Pre-commit hooks, GitHub Actions
Documentation - CLAUDE.md, CONTRIBUTING.md, README sections
Git Configuration - .gitignore, commit conventions

Rollback

# Automatic on failure
# Manual rollback:
python plugins/autonomous-dev/lib/retrofit_executor.py --rollback <timestamp>

When to Use Each Mode

Scenario	Mode
Regular development check	`/align`
After adding/removing components	`/align`
Before major release	`/align`
Updating documentation only	`/align --docs`
Onboarding new developers	`/align --docs`
Adopting autonomous-dev	`/align --retrofit`
Legacy codebase migration	`/align --retrofit`

Implementation

Based on arguments, invoke the appropriate alignment workflow:

Default mode (/align or /align --project): Invoke the alignment-analyzer agent to validate PROJECT.md and fix conflicts
Documentation mode (/align --docs): Run documentation consistency validation via alignment_fixer.py
Retrofit mode (/align --retrofit): Execute 5-phase brownfield retrofit workflow

Implementation Details

Mode Detection

Parse arguments from user input:

IF --retrofit flag:
    → Run 5-phase brownfield retrofit
    → Check for --dry-run or --auto sub-flags

ELIF --docs flag:
    → Run documentation consistency check
    → alignment_fixer.py + cross-reference validation
    → No code changes, docs only

ELSE (default):
    → Phase 1: alignment_fixer.py (quick scan)
    → Phase 2: alignment-analyzer agent (semantic validation)
    → Phase 3: Hook inflation review
    → Phase 4: Interactive resolution

Libraries Used

Default mode:

validate_manifest_doc_alignment.py - Quick count/reference scan
alignment-analyzer agent - Semantic validation (via Claude Code)

--docs mode:

alignment_fixer.py - Count validation
Cross-reference validation logic

--retrofit mode:

codebase_analyzer.py - Phase 1
alignment_assessor.py - Phase 2
migration_planner.py - Phase 3
retrofit_executor.py - Phase 4
retrofit_verifier.py - Phase 5

Troubleshooting

"Alignment check takes too long"

Use --docs for faster documentation-only check:

/align --docs  # 5-15 min vs 10-30 min

"Too many conflicts to review"

Run in batches:

/align --docs           # Fix docs first
/align                  # Then full check (fewer issues)

"Retrofit fails at Phase 4"

Automatic rollback should restore backup. Manual rollback:

ls ~/.autonomous-dev/backups/
python plugins/autonomous-dev/lib/retrofit_executor.py --rollback <timestamp>

/auto-implement - Uses PROJECT.md for feature alignment
/setup - Initial project setup (calls /align --retrofit internally)
/health-check - Plugin integrity validation

Migration from Old Commands

Old Command	New Command
`/align-project`	`/align` (default)
`/align-claude`	`/align --docs`
`/align-project-retrofit`	`/align --retrofit`

Note: Old commands archived to commands/archive/ (Issue #121).

12 KiB Raw Blame History

/align - Unified Alignment Command

Quick Usage

Mode 1: Full Alignment (Default)

Phase 1: Quick Scan (GenAI or Regex)

Phase 2: Semantic Validation (GenAI)

Phase 3: Hooks/Rules Review

Phase 4: Interactive Resolution (Bidirectional)

Example Output

Mode 2: Documentation Alignment (--docs)

Checks Performed

What It Doesn't Do

Example Output

Mode 3: Brownfield Retrofit (--retrofit)

Phases

Phase 1: Analyze Codebase

Phase 2: Assess Alignment

Phase 3: Generate Migration Plan

Phase 4: Execute Migration

Phase 5: Verify Results

Usage

What Gets Retrofitted

Rollback

When to Use Each Mode

Implementation

Implementation Details

Mode Detection

Libraries Used

Troubleshooting

"Alignment check takes too long"

"Too many conflicts to review"

"Retrofit fails at Phase 4"

Related Commands

Migration from Old Commands

12 KiB

Raw Blame History

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

Mode 3: Brownfield Retrofit (`--retrofit`)