docs: add comprehensive AI-assisted brownfield modernization checklist

[Jamie-BitFlight]

Add structured checklist covering best practices for AI-assisted
project modernization with Chain-of-Verification, self-correction
loops, and validation harnesses across 8 phases:

• Repository analysis and baseline establishment
• Validation harness setup (type checking, linting, tests)
• Architecture documentation with verification
• Modernization planning with dependency validation
• CI/CD pipeline development with failure simulation
• Review cycles and hallucination detection protocols
• Per-directory documentation generation
• Continuous validation loops with drift detection

Summary by CodeRabbit

Release Notes

• New Features

  • Added AI-assisted brownfield modernization workflow with checkpoint-based progress tracking
  • Introduced architecture analyzer, validation runner, and documentation generator tools
  • Added modernization planner with dependency validation and risk assessment

• Documentation

  • Added comprehensive AI-assisted modernization checklist and multi-phase workflow guide

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Caution

Review failed

The pull request is closed.

📝 Walkthrough

Walkthrough

Introduces a comprehensive AI-assisted brownfield modernization framework including multi-agent specifications, orchestration workflows, checkpoint management infrastructure, and structured documentation for systematic codebase analysis, validation, documentation generation, and modernization planning.

Changes

Cohort / File(s)	Summary
Core Framework Documentation .claude/README.md, docs/AI-ASSISTED-BROWNFIELD-MODERNIZATION-CHECKLIST.md	Establishes framework overview with directory structure, usage workflows, checkpoint mechanisms, and Chain-of-Verification protocol; comprehensive checklist outlines 8-phase modernization methodology with verification gates and self-correction loops
Agent Specifications .claude/agents/architecture-analyzer.md, .claude/agents/validation-runner.md, .claude/agents/documentation-generator.md, .claude/agents/modernization-planner.md	Defines four specialized agents with procedural workflows, command snippets, output formats, and verification checklists: architecture-analyzer inventories code and builds dependency graphs; validation-runner establishes type checking, linting, and test infrastructure; documentation-generator creates and validates per-directory and file-level documentation; modernization-planner generates verified modernization tasks with risk assessment and rollback procedures
Checkpoint Infrastructure .claude/checkpoints/.gitkeep, .claude/checkpoints/checkpoint-template.json	Establishes checkpoint storage directory with lifecycle phases, agent invocation tracking, verification logs, and resume metadata; JSON template scaffolds progress tracking across eight modernization phases with placeholder fields for execution-time population
Orchestration & Execution .claude/commands/modernize-brownfield.md, .claude/hooks/checkpoint-init.sh, .claude/hooks/checkpoint-read.sh, .claude/hooks/checkpoint-update.sh	Defines multi-agent orchestration workflow with 8-phase execution strategy and error recovery; bash utilities initialize, read, and update checkpoint JSON files with agent invocations, phase transitions, and timestamp tracking
Configuration .gitignore	Adds ignore patterns for session-specific checkpoint files and logs

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 Four agents hop and skip with glee,
Modernizing brownfields, wild and free,
With checkpoints saved and paths verified,
Each loop corrected, each goal acquired,
Hop onward, code friends, the future's bright! ✨

✨ Finishing touches

• 📝 Generate docstrings

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Copilot]

Pull request overview

This PR adds a comprehensive framework for AI-assisted brownfield project modernization with emphasis on verification, validation, and hallucination detection. The checklist provides systematic guidance across 8 phases incorporating Chain-of-Verification (CoVe) techniques, self-correction loops, and validation harnesses.

Changes:

• Added 836-line comprehensive brownfield modernization checklist with detailed examples for each phase
• Created Claude Code orchestration framework with checkpoint-based resumption system
• Implemented 4 specialized agent configurations for architecture analysis, validation, planning, and documentation
• Added shell scripts for checkpoint management (init, update, read)

Reviewed changes

Copilot reviewed 12 out of 13 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
docs/AI-ASSISTED-BROWNFIELD-MODERNIZATION-CHECKLIST.md	Main deliverable: comprehensive 8-phase modernization guide with CoVe examples
.gitignore	Excludes session-specific checkpoint files from version control
.claude/hooks/checkpoint-update.sh	Updates checkpoint after agent work with JSON manipulation via jq
.claude/hooks/checkpoint-read.sh	Displays checkpoint status in various formats (JSON, summary, phases, agents)
.claude/hooks/checkpoint-init.sh	Initializes checkpoint JSON structure for tracking modernization progress
.claude/commands/modernize-brownfield.md	Main orchestration command for launching multi-agent modernization workflow
.claude/checkpoints/checkpoint-template.json	Template defining checkpoint data structure with phases and agent states
.claude/agents/validation-runner.md	Agent for setting up type checking, linting, and test validation gates
.claude/agents/modernization-planner.md	Agent for creating verified modernization plans with dependency validation
.claude/agents/documentation-generator.md	Agent for generating validated per-directory and file-level documentation
.claude/agents/architecture-analyzer.md	Agent for analyzing codebase structure using AST and import analysis
.claude/README.md	Overview of Claude Code configuration structure and usage instructions
.claude/checkpoints/.gitkeep	Placeholder to maintain checkpoints directory in version control

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.