docs: add comprehensive documentation from multi-agent brownfield analysis

.claude/agents/README.md

@@ -0,0 +1,119 @@
+# Specialized Agents
+
+This directory contains agent definitions for the multi-agent brownfield modernization system. Each agent specializes in a specific aspect of codebase analysis and modernization.
+
+## Agent Overview
+
+| Agent                        | Phase | Purpose                                    |
+| ---------------------------- | ----- | ------------------------------------------ |
+| `architecture-analyzer.md`   | 1     | Codebase structure and dependency analysis |
+| `validation-runner.md`       | 2     | Validation harness setup and execution     |
+| `documentation-generator.md` | 7     | Documentation creation and validation      |
+| `modernization-planner.md`   | 4     | Modernization planning and risk assessment |
+
+## Agent Definitions
+
+### architecture-analyzer.md
+
+**Purpose**: Analyzes codebase structure and dependencies using AST patterns and import analysis.
+
+**Allowed Tools**: Read, Grep, Glob, Bash
+
+**Responsibilities**:
+
+- Initial codebase inventory with verification loop
+- Dependency graph construction
+- Security and quality baseline establishment
+
+**Output**: Updates `architecture-analysis` phase in checkpoint file with findings including:
+
+- Total files and source file list
+- Export catalog
+- Internal and external dependencies
+- Security concerns and dynamic imports
+
+### validation-runner.md
+
+**Purpose**: Sets up and runs validation harness including type checking, linting, and test suite execution.
+
+**Allowed Tools**: Read, Write, Bash, Glob, Grep
+
+**Responsibilities**:
+
+- Type checking infrastructure setup
+- Linting rules configuration
+- Test harness as ground truth
+- Self-correction loop protocol
+
+**Output**: Updates `validation-harness` phase with gate results:
+
+- Type check status (tsc)
+- Linting status (eslint)
+- Test status (jest) with coverage
+
+### documentation-generator.md
+
+**Purpose**: Generates and validates comprehensive documentation including per-directory READMEs and file-level documentation.
+
+**Allowed Tools**: Read, Write, Grep, Bash, Glob
+
+**Responsibilities**:
+
+- Per-directory README generation with validation
+- File-level purpose documentation with cross-validation
+- Navigation-optimized structure
+- Documentation accuracy validation
+
+**Output**: Updates `documentation` phase with:
+
+- List of documented files
+- Validation results (files documented, cross-references verified, discrepancies found/corrected)
+
+### modernization-planner.md
+
+**Purpose**: Generates verified modernization plans with task breakdown, dependency validation, and risk assessment.
+
+**Allowed Tools**: Read, Grep, Glob, Bash
+
+**Responsibilities**:
+
+- Task breakdown with dependency validation
+- Risk assessment with historical validation
+- Rollback procedure creation
+- Verification protocol execution
+
+**Output**: Updates `modernization-plan` phase with:
+
+- Task list with dependencies and acceptance criteria
+- Risk assessment with evidence
+- Mitigation strategies
+
+## Chain-of-Verification Protocol
+
+All agents follow the CoVe protocol:
+
+```
+1. Generate initial output/analysis
+2. Create verification questions
+3. Answer questions against actual code (using tools)
+4. Self-correct any discrepancies
+5. Only accept output after verification passes
+```
+
+## Usage
+
+Agents are invoked by the orchestration command (`/modernize-brownfield`) or can be referenced directly:
+
+```
+"Use the architecture-analyzer agent to analyze the codebase"
+"Use the validation-runner agent to set up validation gates"
+"Use the documentation-generator agent to create documentation"
+"Use the modernization-planner agent to create the modernization plan"
+```
+
+## Related Files
+
+- `../.claude/commands/modernize-brownfield.md` - Main orchestration command
+- `../.claude/hooks/` - Checkpoint management scripts
+- `../.claude/checkpoints/modernization-progress.json` - Progress tracking
+- `../../docs/AI-ASSISTED-BROWNFIELD-MODERNIZATION-CHECKLIST.md` - Reference documentation

.claude/checkpoints/README.md

@@ -0,0 +1,109 @@
+# Checkpoints Directory
+
+This directory stores progress tracking files for the brownfield modernization process. Checkpoints enable session resumption and cross-agent state sharing.
+
+## Files
+
+| File                          | Purpose                                     |
+| ----------------------------- | ------------------------------------------- |
+| `modernization-progress.json` | Active checkpoint tracking current progress |
+| `checkpoint-template.json`    | Template showing checkpoint structure       |
+
+## Checkpoint System
+
+The checkpoint system provides:
+
+- **Progress Tracking**: Records completion status of all 8 modernization phases
+- **Session Resumption**: Enables picking up where previous sessions left off
+- **Cross-Agent State**: Shared state between specialized agents
+- **Audit Trail**: Logs verification results and agent invocations
+
+## modernization-progress.json
+
+The active checkpoint file contains:
+
+### Phases Section
+
+Tracks 8 modernization phases from the checklist:
+
+1. `architecture-analysis` - Codebase inventory and dependency mapping
+2. `validation-harness` - Type checking, linting, and test setup
+3. `architecture-documentation` - System architecture documentation
+4. `modernization-plan` - Task breakdown and risk assessment
+5. `cicd-pipeline` - CI/CD pipeline configuration
+6. `review-cycles` - Code review and hallucination detection
+7. `documentation` - Per-directory and file-level documentation
+8. `continuous-validation` - Pre-commit hooks and drift detection
+
+Each phase has:
+
+- `status`: `pending`, `in_progress`, or `completed`
+- `startedAt` / `completedAt`: Timestamps
+- `findings` / specific data: Phase-specific results
+- `verificationPassed`: Whether CoVe verification succeeded
+
+### Agents Section
+
+Tracks 4 specialized agents:
+
+1. `architecture-analyzer` - Phase 1 analysis
+2. `validation-runner` - Phase 2 validation setup
+3. `documentation-generator` - Phase 7 documentation
+4. `modernization-planner` - Phase 4 planning
+
+Each agent tracks:
+
+- `invocations`: How many times the agent has run
+- `lastRun`: Last execution timestamp
+- `status`: `ready` or `running`
+- `lastError`: Any error from previous run
+
+### Resume Info Section
+
+Contains:
+
+- `lastIncompletePhase`: Which phase to resume
+- `blockers`: Any issues preventing progress
+- `notes`: Additional context for resumption
+
+## checkpoint-template.json
+
+A template file showing the expected structure for checkpoints. Useful for:
+
+- Understanding the data format
+- Creating new checkpoints programmatically
+- Documentation reference
+
+## Managing Checkpoints
+
+### Initialize New Checkpoint
+
+```bash
+.claude/hooks/checkpoint-init.sh
+```
+
+### Check Current Progress
+
+```bash
+.claude/hooks/checkpoint-read.sh --summary
+```
+
+### Update After Agent Work
+
+```bash
+.claude/hooks/checkpoint-update.sh <agent-name> <phase> <status>
+```
+
+### View Raw Checkpoint
+
+```bash
+.claude/hooks/checkpoint-read.sh --json
+```
+
+## Related Files
+
+- `../hooks/checkpoint-init.sh` - Initialization script
+- `../hooks/checkpoint-read.sh` - Status reading script
+- `../hooks/checkpoint-update.sh` - Update script
+- `../commands/modernize-brownfield.md` - Uses checkpoint system
+- `../../docs/AI-ASSISTED-BROWNFIELD-MODERNIZATION-CHECKLIST.md` - Phase definitions

.claude/commands/README.md

@@ -0,0 +1,87 @@
+# Slash Commands
+
+This directory contains slash command definitions for Claude Code that enable complex automated workflows.
+
+## Available Commands
+
+### modernize-brownfield.md
+
+**Command**: `/modernize-brownfield`
+
+**Description**: Orchestrates multi-agent brownfield modernization using Chain-of-Verification techniques with checkpoint-based resumption.
+
+**Allowed Tools**: Read, Write, Bash, Glob, Grep, Task, TodoWrite
+
+**Purpose**: Coordinates the 8-phase modernization process defined in `docs/AI-ASSISTED-BROWNFIELD-MODERNIZATION-CHECKLIST.md`.
+
+## How It Works
+
+When you run `/modernize-brownfield`, the orchestrator:
+
+1. **Initializes Checkpoint System**
+
+   - Creates `.claude/checkpoints/modernization-progress.json` if needed
+   - Reads existing progress to determine resume point
+
+2. **Identifies Resume Point**
+
+   - Checks phase statuses: `pending`, `in_progress`, `completed`
+   - Determines which phases need work
+
+3. **Launches Specialized Agents**
+
+   - Architecture Analyzer (Phase 1)
+   - Validation Runner (Phase 2)
+   - Documentation Generator (Phase 7)
+   - Modernization Planner (Phase 4)
+
+4. **Monitors and Coordinates**
+
+   - Waits for agent completion
+   - Verifies successful completion
+   - Re-launches with corrections if needed
+
+5. **Final Verification**
+   - Runs hallucination detection checklist
+   - Validates documentation cross-references
+   - Updates checkpoint with final status
+
+## Checkpoint-Based Resumption
+
+If a session is interrupted:
+
+1. Run `/modernize-brownfield` again
+2. The orchestrator reads the existing checkpoint
+3. Work resumes from the last incomplete phase
+
+## Success Criteria
+
+The modernization is complete when:
+
+- All 8 phases have status "completed"
+- All verification checks passed
+- Hallucination detection found no issues
+- Documentation is navigable and accurate
+- Modernization plan is actionable with correct dependencies
+
+## Creating New Commands
+
+To add a new slash command:
+
+1. Create a new `.md` file in this directory
+2. Add YAML frontmatter with:
+   ```yaml
+   ---
+   description: Brief description of the command
+   allowed-tools: Comma-separated list of tools
+   ---
+   ```
+3. Document the command behavior in Markdown
+4. Test the command in Claude Code
+
+## Related Files
+
+- `../agents/` - Specialized agent definitions
+- `../hooks/` - Checkpoint management scripts
+- `../checkpoints/` - Progress tracking files
+- `../../docs/AI-ASSISTED-BROWNFIELD-MODERNIZATION-CHECKLIST.md` - Reference