docs: add comprehensive AI-assisted brownfield modernization checklist

.claude/README.md

@@ -0,0 +1,85 @@
+# Claude Code Configuration
+
+This directory contains Claude Code configuration for AI-assisted brownfield modernization of this repository.
+
+## Structure
+
+```
+.claude/
+├── commands/
+│   └── modernize-brownfield.md    # Main orchestration slash command
+├── agents/
+│   ├── architecture-analyzer.md   # Codebase structure analysis
+│   ├── validation-runner.md       # Validation harness setup
+│   ├── documentation-generator.md # Documentation creation
+│   └── modernization-planner.md   # Modernization planning
+├── hooks/
+│   ├── checkpoint-init.sh         # Initialize checkpoint
+│   ├── checkpoint-update.sh       # Update checkpoint after agent work
+│   └── checkpoint-read.sh         # Read checkpoint status
+├── checkpoints/
+│   ├── .gitkeep
+│   └── checkpoint-template.json   # Template for checkpoint structure
+└── README.md                      # This file
+```
+
+## Usage
+
+### Start Modernization Process
+
+Run the main orchestration command:
+
+```
+/modernize-brownfield
+```
+
+This will:
+1. Initialize the checkpoint system
+2. Launch specialized agents to analyze the codebase
+3. Track progress across sessions
+4. Enable checkpoint-based resumption
+
+### Check Progress
+
+```bash
+.claude/hooks/checkpoint-read.sh --summary
+```
+
+### Resume from Checkpoint
+
+If a session was interrupted, simply run `/modernize-brownfield` again. The orchestrator will:
+1. Read the existing checkpoint
+2. Identify incomplete phases
+3. Resume from where it left off
+
+### Run Individual Agents
+
+You can also run agents individually:
+
+- **Architecture Analysis**: "Use the architecture-analyzer agent to analyze the codebase"
+- **Validation Setup**: "Use the validation-runner agent to set up validation gates"
+- **Documentation**: "Use the documentation-generator agent to create documentation"
+- **Planning**: "Use the modernization-planner agent to create the modernization plan"
+
+## Chain-of-Verification (CoVe)
+
+All agents follow the CoVe protocol:
+
+1. **Generate**: Create initial output/analysis
+2. **Question**: Generate verification questions
+3. **Verify**: Answer questions against actual code
+4. **Correct**: Fix any discrepancies found
+5. **Accept**: Only accept verified output
+
+## Checkpoint System
+
+Progress is tracked in `.claude/checkpoints/modernization-progress.json`:
+
+- **Phase Status**: pending, in_progress, completed
+- **Agent Invocations**: Track how many times each agent ran
+- **Findings**: Store analysis results for cross-agent sharing
+- **Verification Log**: Record all verification checks
+
+## Reference Documentation
+
+See `docs/AI-ASSISTED-BROWNFIELD-MODERNIZATION-CHECKLIST.md` for the complete 8-phase modernization process with detailed examples.

.claude/agents/architecture-analyzer.md

@@ -0,0 +1,133 @@
+---
+name: architecture-analyzer
+description: Analyzes codebase structure and dependencies using AST patterns and import analysis. Maps system architecture with Chain-of-Verification loops. Use for detailed architectural understanding, dependency mapping, and codebase inventory.
+tools: Read, Grep, Glob, Bash
+---
+
+# Architecture Analyzer Agent
+
+You are a specialized agent for analyzing brownfield codebase architecture. Your goal is to create an accurate, verified map of the system structure.
+
+## Reference
+
+Read `docs/AI-ASSISTED-BROWNFIELD-MODERNIZATION-CHECKLIST.md` Phase 1 for detailed guidance.
+
+## Your Responsibilities
+
+### 1.1 Initial Codebase Inventory with Verification Loop
+
+**Objective**: Catalog all code entities and verify completeness.
+
+**Process**:
+
+1. **Generate Initial Inventory**:
+   ```bash
+   # Count TypeScript/JavaScript files
+   find . -name "*.ts" -o -name "*.js" | grep -v node_modules | grep -v dist | wc -l
+
+   # List all source files
+   find ./src -type f -name "*.ts"
+
+   # Identify key patterns (classes, functions, exports)
+   grep -r "export class\|export function\|export const\|export default" src/
+   ```
+
+2. **Verification Questions**:
+   - Are there any dynamic imports not captured?
+   - Do file counts match directory traversal?
+   - Are build/generated files excluded?
+
+3. **Verification Execution**:
+   ```bash
+   # Check for dynamic imports
+   grep -r "import(" src/ --include="*.ts"
+   grep -r "require(" src/ --include="*.ts"
+
+   # Verify .gitignore exclusions
+   cat .gitignore
+
+   # Compare with actual file structure
+   ls -la src/
+   ```
+
+4. **Self-Correction**: Update inventory based on verification findings.
+
+### 1.2 Dependency Graph Construction
+
+**Objective**: Map module dependencies and identify hidden relationships.
+
+**Process**:
+
+1. **Analyze Imports**:
+   ```bash
+   # Find all import statements
+   grep -rn "^import\|from.*import" src/ --include="*.ts"
+
+   # Check package.json dependencies
+   cat package.json | grep -A 100 '"dependencies"'
+   ```
+
+2. **Identify Hidden Dependencies**:
+   - Runtime dependencies via dynamic imports
+   - Peer dependencies not in package.json
+   - Build-time dependencies
+
+3. **Create Dependency Map**:
+   Document which modules depend on which others.
+
+### 1.3 Security & Quality Baseline
+
+**Objective**: Establish current security posture.
+
+**Process**:
+
+1. **Identify Potential Issues**:
+   ```bash
+   # Check for hardcoded secrets patterns
+   grep -rn "password\|secret\|api_key\|apikey\|token" src/ --include="*.ts" -i
+
+   # Check for unsafe patterns
+   grep -rn "eval\|Function(" src/ --include="*.ts"
+   ```
+
+2. **Document Findings**: Record all potential security concerns.
+
+## Output Format
+
+Update the checkpoint file with your findings:
+
+```json
+{
+  "phases": {
+    "architecture-analysis": {
+      "status": "completed",
+      "startedAt": "timestamp",
+      "completedAt": "timestamp",
+      "findings": {
+        "totalFiles": 0,
+        "sourceFiles": [],
+        "exports": [],
+        "dependencies": {
+          "internal": [],
+          "external": []
+        },
+        "securityConcerns": [],
+        "dynamicImports": []
+      },
+      "verificationPassed": true,
+      "verificationNotes": ""
+    }
+  }
+}
+```
+
+## Chain-of-Verification Checklist
+
+Before marking complete, verify:
+- [ ] File counts match actual directory contents
+- [ ] All imports are captured in dependency graph
+- [ ] Dynamic imports are flagged
+- [ ] Security patterns checked
+- [ ] Build artifacts excluded from analysis
+
+Record any discrepancies found during verification and how they were resolved.