feat: add AIDLC Design Reviewer tool with monorepo support

[harmjeff]

Add AI-powered design review tool for AIDLC projects with intelligent workspace detection for monorepo environments.

Features:

• Multi-agent design review (Critique, Alternatives, Gap Analysis)
• Quality scoring with weighted severity analysis
• Two deployment modes: CLI tool and Claude Code hook (experimental)
• Comprehensive test suite (743 tests)
• Full documentation and installation guides

Installation improvements:

• Smart workspace detection in all installers (Bash/PowerShell)
• Priority-based detection: .git > aidlc-rules > pyproject.toml
• Automatic detection from scripts/aidlc-designreview/tool-install/
• Backward compatible with standalone usage
• Visual feedback showing detected workspace directory

Documentation:

• Added "Supporting Tools" section to main README.md
• Links to design reviewer and evaluator documentation
• Installation instructions for both CLI and hook modes
• MONOREPO_INSTALLATION.md with detailed migration notes

New files:

• scripts/aidlc-designreview/: Complete tool with src/, tests/, docs/

Summary

Introduces automated design review capability for AIDLC projects using
Claude AI models via AWS Bedrock. Analyzes design artifacts and produces
actionable reports with severity-graded findings, alternative approaches,
and gap analysis.

Key Features:

• Three specialized AI agents (Critique, Alternatives, Gap Analysis)
• Weighted quality scoring with actionable recommendations
• Dual deployment: Python CLI tool + Claude Code hook integration
• Cross-platform hook installation (macOS, Linux, Windows)

---

Directory Structure in Target Repository

aidlc-workflows/
└── scripts/
    └── aidlc-designreview/
        ├── src/
        │   └── design_reviewer/        # Python package
        ├── tests/                      # Test suite
        ├── config/                     # Configuration files
        ├── tool-install/               # Hook installation scripts
        ├── docs/                       # Additional documentation
        ├── pyproject.toml              # Project configuration
        ├── uv.lock                     # Dependency lock file
        ├── README.md                   # Main documentation
        ├── INSTALLATION.md             # Hook installation guide
        ├── CHANGELOG.md                # Version history
        ├── LICENSE                     # MIT License
        ├── NOTICE                      # Third-party attributions
        └── LEGAL_DISCLAIMER.md         # Legal terms

---

Files

Core Application Files

• src/design_reviewer/ - Complete Python package (50 files, ~5,400 LOC)
  • foundation/ - Config, logging, exceptions, prompts, patterns (13 modules)
  • validation/ - Structure validation, artifact discovery (6 modules)
  • parsing/ - Artifact parsers (5 modules)
  • ai_review/ - AI agents and orchestration (8 modules)
  • reporting/ - Report builders and formatters (7 modules)
  • orchestration/ - Pipeline orchestrator (2 modules)
  • cli/ - CLI entry point (3 modules)
  • __init__.py - Package initialization
  • py.typed - Type checking marker

Configuration Files

• config/ - Configuration and templates directory
  • patterns/ - 15 architectural pattern definitions (markdown)
  • prompts/ - 3 agent system prompts (critique, alternatives, gap)
  • default-config.yaml - Bundled default configuration
  • example-config.yaml - Annotated user reference configuration

Hook Installation System

• tool-install/ - Complete hook installation system (~1,210 LOC bash)
  • lib/ - 7 library modules:
    • logger.sh - Logging functions
    • config-defaults.sh - Default configuration values
    • config-parser.sh - YAML parser with fallbacks
    • user-interaction.sh - User prompts
    • review-executor.sh - Artifact discovery and review
    • report-generator.sh - Report parsing and generation
    • audit-logger.sh - Audit trail logging
  • hooks/ - Hook entry point:
    • pre-tool-use - Main hook script
  • templates/ - Report templates:
    • design-review-report.md - Report template
  • Installation scripts:
    • install-mac.sh - macOS installer
    • install-linux.sh - Linux installer (symlink to macOS)
    • install-windows.ps1 - Windows PowerShell installer
    • install-windows.sh - Windows Git Bash/WSL installer
  • review-config.yaml.example - Example hook configuration
  • README.md - Technical documentation

Test Suite

• tests/ - Complete test suite (61 files, ~10,800 LOC, 743 tests)
  • unit1_foundation/ - 14 files, ~284 tests
  • unit2_validation/ - 7 files, ~122 tests
  • unit3_parsing/ - 6 files, ~71 tests
  • unit4_ai_review/ - 10 files, ~103 tests
  • unit5_reporting/ - 5 files, ~95 tests
  • unit5_orchestration/ - 2 files, ~15 tests
  • unit5_cli/ - 3 files, ~19 tests
  • functional/ - 4 files, ~34 tests
  • conftest.py - Pytest configuration and fixtures
  • __init__.py - Test package initialization

Documentation

• README.md - Main project documentation (38KB, comprehensive)

  • Architecture overview with both CLI and Hook deployment modes
  • Installation instructions for Python CLI
  • Hook installation guide with cross-platform support
  • Configuration reference
  • Security documentation
  • Usage examples
  • Developer's guide
  • Architecture details

• INSTALLATION.md - Hook installation guide (16KB)

  • Cross-platform installation (macOS, Linux, Windows)
  • Installing into existing AIDLC projects (new section)
  • Configuration guide
  • Validation and testing
  • Troubleshooting
  • Experimental feature warning

• CHANGELOG.md - Version history and release notes

• docs/ - Additional documentation

  • hook/TESTING.md - Hook testing guide
  • security/ - Security documentation directory
    • AWS_BEDROCK_SECURITY_GUIDELINES.md
    • SYSTEM_ARCHITECTURE.md
    • THREAT_MODEL.md
    • Other security-related docs
  • ai-security/ - AI security documentation
    • BEDROCK_GUARDRAILS.md
  • architecture/ - Architecture documentation

Legal and License Files

• LICENSE - MIT License
• NOTICE - Third-party software attributions
• LEGAL_DISCLAIMER.md - Legal terms and advisory notices (11KB)

Project Configuration

• pyproject.toml - Python project configuration

  • Package metadata
  • Dependencies (11 runtime packages)
  • Test dependencies
  • Build system configuration
  • CLI entry point configuration

• uv.lock - Dependency lock file (for reproducible builds)

---

Changes

Updated the README with instruction on how to get to the Design Review content

User experience

Before: 1 path (AI driven for design) without options for design

After: Tool builds documentation with actionable insights onb how to update the design before code creation

Checklist

If your change doesn't seem to apply, please leave them unchecked.

• I have reviewed the contributing guidelines
• I have performed a self-review of this change
• Changes have been tested
• Changes are documented

Test Plan

• CLI Tool Tests

  • Installation: uv sync completes successfully
  • CLI entry point: design-reviewer --version works
  • Full test suite: All 743 tests pass
  • Type checking: mypy passes with no errors
  • Review workflow: End-to-end review with mock AI
  • Real AI review: Test with AWS Bedrock (if credentials available)

• Hook Installation Tests

  • macOS: ./tool-install/install-mac.sh succeeds
  • Linux: ./tool-install/install-linux.sh succeeds
  • Windows PowerShell: .\tool-install\install-windows.ps1 succeeds
  • Windows Git Bash: ./tool-install/install-windows.sh succeeds
  • Hook execution: TEST_MODE=1 .claude/hooks/pre-tool-use works
  • Configuration parsing: All three fallback tiers work

• Documentation Tests

  • All links in README.md resolve correctly
  • Code examples execute without errors
  • Installation instructions are accurate
  • Configuration examples are valid YAML

• Security Tests

  • AWS credentials handling works correctly
  • (Optional) Guardrails configuration works (if available)
  • No secrets in committed files
  • Dependencies have no known vulnerabilities

Acknowledgment

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of the project license.