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.

[ayushtr-aws]

I tested the AIDLC Design Reviewer as a standalone CLI tool against the design artifacts from a personal AI-DLC project. It produced 27 findings (1 critical, 5 high, 21 medium) across three AI agents: critique, alternatives, and gap analysis.

The findings were legitimate. It caught real issues like hardcoded single-user auth via Lambda env vars, synchronous Bedrock calls inside a 30-second API Gateway timeout, unbounded DynamoDB scans, large document text stored inline exceeding the 400KB item limit, and localStorage token storage exposing XSS risk. These weren't generic suggestions — they referenced specific business rules and entities from my design docs.

The HTML report was clean: self-contained single file, collapsible sections, severity filters, color-coded badges, and a clear executive summary with a recommended action.

The tool also ships with a Claude Code pre-tool-use hook for automatic design review during development. Still need to test that part because Claude Code wasn't working in my environment at the time.

Overall, the Design Reviewer tool works well and produces actionable, project-specific feedback.

[github-advanced-security]

Semgrep OSS found more than 20 potential problems in the proposed changes. Check the Files changed tab for more details.