update-docs

update-docs

Execute comprehensive documentation alignment based on markdown-table-of-contents.md analysis. Implements CLAUDE.md → AGENTS.md migration, architectural alignment planning, and AI agent optimization.

PRIMARY_UPDATE_OBJECTIVES

1. Execute CLAUDE.md → AGENTS.md migrations preserving custom guidance
2. Plan architectural alignment without modifying existing architecture
3. Update ROADMAP.md with complexity-annotated Next Steps
4. Synchronize C4 levels with implementation status annotations
5. Update /ai_docs using web search for stale content
6. Optimize all documentation for AI agent workflows
7. Execute smart consolidation across AI platforms

EXECUTION_SEQUENCE

PHASE_0: ALIGNMENT_PLANNING

echo "=== ALIGNMENT PLANNING PHASE ==="

# Create alignment plan before any updates
cat > "ALIGNMENT_PLAN_$(date +%Y-%m-%d).md" << 'PLAN_EOF'
# Documentation Alignment Plan

## Governance Mode: $(grep "GOVERNANCE_MODE" markdown-table-of-contents.md | cut -d: -f2)

## Planned Updates:
### CLAUDE.md Migrations
$(grep -A5 "CLAUDE_MD_MIGRATION_TASKS" markdown-table-of-contents.md)

### Architecture Alignment
$(grep -A10 "ARCHITECTURAL_ALIGNMENT_STATUS" markdown-table-of-contents.md)

### Priority Order:
1. Migrate custom guidance (no conflicts expected)
2. Update ROADMAP.md Next Steps (complexity-based)
3. Annotate architecture files (document-only mode)
4. Update stale AI docs via web search
5. Consolidate AI platform files

## Risk Assessment:
- CLAUDE.md migrations: LOW RISK
- Architecture updates: DOCUMENTATION ONLY
- AI docs updates: MEDIUM RISK (web search quality)

## Rollback Strategy:
- All original files backed up to .backup/
- Git commit before changes recommended
PLAN_EOF

echo "Alignment plan created. Review before proceeding? (y/n)"
# In real implementation, would pause for review

PHASE_1: CLAUDE_MD_TO_AGENTS_MD_MIGRATION

echo "=== EXECUTING CLAUDE.MD MIGRATIONS ==="

# Backup existing files
mkdir -p .backup/$(date +%Y%m%d)

# Process each CLAUDE.md file
find . -name "CLAUDE.md" -type f | while read claude_file; do
    dir=$(dirname "$claude_file")
    agents_file="$dir/AGENTS.md"
    backup_dir=".backup/$(date +%Y%m%d)${dir}"
    
    # Backup originals
    mkdir -p "$backup_dir"
    [ -f "$claude_file" ] && cp "$claude_file" "$backup_dir/"
    [ -f "$agents_file" ] && cp "$agents_file" "$backup_dir/"
    
    # Extract custom guidance
    custom_content=$(grep -v "refer to.*AGENTS.md" "$claude_file" | grep -v "^#.*AGENTS.md" | grep -v "^$")
    
    if [ -n "$custom_content" ]; then
        echo "Migrating custom guidance from $claude_file"
        
        # Append to AGENTS.md with context
        if [ -f "$agents_file" ]; then
            echo -e "\n## Migrated from CLAUDE.md ($(date +%Y-%m-%d))\n$custom_content" >> "$agents_file"
        else
            # Create new AGENTS.md
            cat > "$agents_file" << 'AGENTS_NEW_EOF'
# Agent Instructions for $dir

## Migrated from CLAUDE.md ($(date +%Y-%m-%d))
$custom_content

## Additional Context
- See root AGENTS.md for project-wide guidelines
- Check architecture/ for component designs
- Reference ROADMAP.md for implementation priorities
AGENTS_NEW_EOF
        fi
    fi
    
    # Standardize CLAUDE.md as pure pointer
    cat > "$claude_file" << 'CLAUDE_STD_EOF'
# Claude Agent Instructions
> **AI Agents:** All guidance has been consolidated into `AGENTS.md` in this directory.

See @AGENTS.md for complete instructions.
See @/ROADMAP.md for implementation priorities.
See @/architecture/workspace.dsl for system design.

# important-instruction-reminders
- Follow complexity ordering in Next Steps
- Check architecture alignment before implementing
- Update implementation status after completing tasks
CLAUDE_STD_EOF
done