AIDLC Design Review Hook - Installation Guide

⚠️ EXPERIMENTAL FEATURE: The Claude Code hook integration is currently in experimental status. While functional, it may have limitations and edge cases that have not been fully tested in all production environments. Please use with caution and report any issues you encounter.

Cross-platform installation tool for the AIDLC Design Review Hook.

Overview
Prerequisites
Installation
Configuration
Validation
Updating
Uninstallation
Troubleshooting

Overview

The AIDLC Design Review Hook is a pre-tool-use hook for Claude Code that automatically reviews design artifacts before code generation. This installation tool sets up the hook in your workspace.

Features:

✅ Cross-platform support (macOS, Linux, Windows)
✅ Fresh installation and update support
✅ Automatic backup of existing installations
✅ Interactive configuration prompts
✅ Dependency checking with helpful instructions
✅ Installation validation tests
✅ Multi-agent design review (critique + alternatives + gaps)

Prerequisites

Required

All Platforms:

Bash 4.0 or higher

Windows:

Git Bash (recommended) OR WSL (Windows Subsystem for Linux)
Download Git Bash: https://git-scm.com/download/win

Optional (for full functionality)

Configuration Parsing:

yq v4+ (preferred): https://github.com/mikefarah/yq#install
Python 3 with PyYAML (fallback): pip install pyyaml
If neither available, hook uses hardcoded defaults (still functional)

Installation Commands:

macOS:

brew install yq
brew install python3
pip3 install pyyaml

Linux (Ubuntu/Debian):

sudo wget -qO /usr/local/bin/yq https://github.com/mikefarah/yq/releases/latest/download/yq_linux_amd64
sudo chmod +x /usr/local/bin/yq
sudo apt-get install python3 python3-pip
pip3 install pyyaml

Windows:

Download yq from: https://github.com/mikefarah/yq/releases
Install Python: https://www.python.org/downloads/
Install PyYAML: pip install pyyaml

Installation

Installing Into Existing AIDLC Project

If you already have an AIDLC project and want to add the design review hook capability:

Step 1: Obtain the Hook Source Files

You have two options:

Option A: Clone the design-reviewer repository (recommended if you want updates):

# Clone to a temporary location
git clone <design-reviewer-repo-url> /tmp/design-reviewer

# Navigate to your AIDLC project
cd /path/to/your/aidlc-project

# Copy the tool-install directory
cp -r /tmp/design-reviewer/tool-install ./

# Optional: Clean up
rm -rf /tmp/design-reviewer

Option B: Download just the tool-install directory (if you only need the hook files):

Download the tool-install/ directory from the design-reviewer repository
Place it in the root of your AIDLC project

Step 2: Verify Your AIDLC Project Structure

Ensure your project has the standard AIDLC structure:

your-aidlc-project/
├── aidlc-docs/
│   ├── construction/
│   │   └── unit-*/
│   └── audit.md
└── tool-install/        # Just added

Step 3: Run the Installer

From your AIDLC project root:

macOS:

./tool-install/install-mac.sh

Linux:

./tool-install/install-linux.sh

Windows PowerShell:

.\tool-install\install-windows.ps1

Windows Git Bash/WSL:

./tool-install/install-windows.sh

Step 4: Configure for Your Project

After installation, edit .claude/review-config.yaml to match your project structure:

# Hook behavior
enabled: true
dry_run: false  # Set to true for testing without blocking

# Review depth
review:
  threshold: 3  # Adjust based on your needs (1-4)
  enable_alternatives: true
  enable_gap_analysis: true

# Reporting - verify these paths exist in your project
reports:
  output_dir: reports/design_review  # Create if doesn't exist

# Logging - verify this path exists
logging:
  audit_file: aidlc-docs/audit.md  # Must match your AIDLC structure
  level: info

Step 5: Create Required Directories

# Create report directory if it doesn't exist
mkdir -p reports/design_review

# Verify audit file exists
ls -la aidlc-docs/audit.md

Step 6: Test the Installation

# Test with mock AI (no AWS credentials needed)
TEST_MODE=1 .claude/hooks/pre-tool-use

# Verify report was generated
ls -la reports/design_review/

Step 7: Integration Testing

Enable in your Claude Code workflow:
- The hook will now automatically run during Claude Code operations
- Look for design review prompts during code generation stages

Test with real AI (requires AWS Bedrock access):

USE_REAL_AI=1 TEST_MODE=1 .claude/hooks/pre-tool-use

Monitor the first few runs:
- Check aidlc-docs/audit.md for logged reviews
- Review generated reports in reports/design_review/
- Adjust threshold and enabled agents in config as needed

Troubleshooting Existing Project Installation

Issue: "aidlc-docs not found"

Ensure you're running the installer from the AIDLC project root
Verify aidlc-docs/ directory exists with proper structure

Issue: Hook doesn't detect design artifacts

Verify construction units exist: ls aidlc-docs/construction/unit-*/
Check that design markdown files exist in unit subdirectories
Ensure filenames match expected patterns (see config)

Issue: Audit logging fails

Create audit file if missing: touch aidlc-docs/audit.md
Verify write permissions: ls -la aidlc-docs/audit.md
Check logging.audit_file path in .claude/review-config.yaml

macOS

Navigate to workspace root:
```
cd /path/to/your/workspace
```
Run installer:
```
./tool-install/install-mac.sh
```
Follow prompts:
- Enable design review hook? (yes/no) [yes]
- Enable dry-run mode? (yes/no) [no]
- Review threshold (1-4) [3]
- Enable alternative approaches analysis? (yes/no) [yes]
- Enable gap analysis? (yes/no) [yes]
Verify installation:
```
TEST_MODE=1 .claude/hooks/pre-tool-use
```

Linux

Navigate to workspace root:
```
cd /path/to/your/workspace
```
Run installer:
```
./tool-install/install-linux.sh
```
Follow prompts (same as macOS)
Verify installation:
```
TEST_MODE=1 .claude/hooks/pre-tool-use
```

Windows PowerShell

Open PowerShell as Administrator
Navigate to workspace root:
```
cd C:\path\to\your\workspace
```

Enable script execution (if needed):

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Run installer:
```
.\tool-install\install-windows.ps1
```
Follow prompts (same as macOS)

Verify installation (Git Bash):

TEST_MODE=1 ./.claude/hooks/pre-tool-use

Windows Git Bash/WSL

Open Git Bash or WSL terminal

Navigate to workspace root:

cd /c/path/to/your/workspace  # Git Bash
# OR
cd /mnt/c/path/to/your/workspace  # WSL

Run installer:
```
./tool-install/install-windows.sh
```
Follow prompts (same as macOS)
Verify installation:
```
TEST_MODE=1 .claude/hooks/pre-tool-use
```

Configuration

After installation, the hook is configured via .claude/review-config.yaml.

Configuration Options

# Hook behavior
enabled: true                    # Enable/disable hook
dry_run: false                   # Dry run mode (reports only, no blocking)

# Review depth
review:
  threshold: 3                   # 1=Low, 2=Medium, 3=High, 4=Critical
  enable_alternatives: true      # Alternative approaches analysis
  enable_gap_analysis: true      # Gap analysis

# Reporting
reports:
  output_dir: reports/design_review
  format: markdown

# Performance
performance:
  batch_size: 20                 # Max files per batch
  batch_max_size: 25             # Max batch size (KB)

# Logging
logging:
  audit_file: aidlc-docs/audit.md
  level: info

Review Modes

Comprehensive Mode (Default):

All 3 agents enabled (critique + alternatives + gaps)
Execution time: ~2-3 minutes with real AI
Recommended for: Production, critical features

Fast Mode (Opt-Out):

review:
  enable_alternatives: false
  enable_gap_analysis: false

Critique agent only
Execution time: ~20 seconds with real AI
Recommended for: Development, rapid iteration

Editing Configuration

macOS/Linux:

nano .claude/review-config.yaml
# OR
vim .claude/review-config.yaml

Windows:

notepad .claude\review-config.yaml

Validation

The installer automatically runs validation tests. To manually validate:

Check File Integrity

macOS/Linux:

ls -R .claude/

Windows:

Get-ChildItem -Recurse .claude\

Expected structure:

.claude/
├── hooks/
│   └── pre-tool-use
├── lib/
│   ├── audit-logger.sh
│   ├── config-defaults.sh
│   ├── config-parser.sh
│   ├── logger.sh
│   ├── report-generator.sh
│   ├── review-executor.sh
│   └── user-interaction.sh
├── templates/
│   └── design-review-report.md
├── review-config.yaml
└── review-config.yaml.example

Run Test Review

All Platforms:

TEST_MODE=1 .claude/hooks/pre-tool-use

This will:

Generate a test report in reports/design_review/
Not block or prompt user
Validate end-to-end functionality

Updating

To update an existing installation:

Back up your configuration (optional):

cp .claude/review-config.yaml .claude/review-config.yaml.backup

Run installer again:

# macOS
./tool-install/install-mac.sh

# Linux
./tool-install/install-linux.sh

# Windows PowerShell
.\tool-install\install-windows.ps1

# Windows Git Bash/WSL
./tool-install/install-windows.sh

The installer automatically detects existing installation
Creates timestamped backup: .claude.backup.YYYYMMDD_HHMMSS
Prompts for new configuration values

Restore custom config (if needed):

cp .claude/review-config.yaml.backup .claude/review-config.yaml

Automatic Backup

Installer creates backup before updating:

.claude.backup.20260327_170500/

To restore from backup:

rm -rf .claude
mv .claude.backup.20260327_170500 .claude

Uninstallation

To remove the AIDLC Design Review Hook:

macOS/Linux:

rm -rf .claude
rm -rf .claude.backup.*  # Optional: remove backups

Windows PowerShell:

Remove-Item -Recurse -Force .claude
Remove-Item -Recurse -Force .claude.backup.*  # Optional

Note: This does NOT remove:

Source files in tool-install/
Generated reports in reports/design_review/
Audit logs in aidlc-docs/audit.md

Troubleshooting

Common Issues

1. "Bash 4.0 required" error

macOS:

# Check version
bash --version

# Upgrade via Homebrew
brew install bash

# Update shell
chsh -s /opt/homebrew/bin/bash  # Apple Silicon
# OR
chsh -s /usr/local/bin/bash     # Intel

Linux:

# Check version
bash --version

# Upgrade (Ubuntu/Debian)
sudo apt-get update
sudo apt-get install --only-upgrade bash

Windows:

Update Git Bash to latest version
Or use WSL with recent Ubuntu/Debian distribution

2. "Permission denied" errors

macOS/Linux:

chmod +x tool-install/install-mac.sh         # macOS
chmod +x tool-install/install-linux.sh       # Linux
chmod +x tool-install/install-windows.sh     # Windows (Git Bash/WSL)

Windows PowerShell:

# Run as Administrator
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

3. Hook not executing

Check hook permissions:

ls -l .claude/hooks/pre-tool-use
# Should show: -rwxr-xr-x

# Fix if needed:
chmod +x .claude/hooks/pre-tool-use

Check Claude Code hook configuration:

Hook should be automatically detected in .claude/hooks/
No additional configuration required in Claude Code

4. "Command not found: yq" warnings

This is not an error. The hook will use Python fallback or defaults.

To suppress warnings:

Install yq: see Prerequisites
OR install Python PyYAML: pip install pyyaml

5. YAML parsing errors

Validate YAML syntax:

# With yq
yq eval . .claude/review-config.yaml

# With Python
python3 -c "import yaml; yaml.safe_load(open('.claude/review-config.yaml'))"

Common issues:

Incorrect indentation (use spaces, not tabs)
Missing quotes around string values with special characters
Trailing commas (not allowed in YAML)

6. Windows line ending issues (Git Bash)

Symptoms:

"bad interpreter: /usr/bin/env: bash^M: no such file or directory"
Scripts fail with syntax errors

Fix:

# Configure Git to use Unix line endings
git config --global core.autocrlf input

# Reinstall hook (automatically converts line endings)
./tool-install/install-windows.sh

7. Report not generated

Check report directory:

ls -la reports/design_review/

Check permissions:

# Create directory if missing
mkdir -p reports/design_review

# Fix permissions
chmod 755 reports/design_review

Check configuration:

reports:
  output_dir: reports/design_review  # Correct
  # NOT: /reports/design_review (leading slash)

Advanced Configuration

Environment Variables

TEST_MODE: Skip bypass detection and user prompts

TEST_MODE=1 .claude/hooks/pre-tool-use

USE_REAL_AI: Use real AWS Bedrock API instead of mock responses

USE_REAL_AI=1 .claude/hooks/pre-tool-use

LOG_LEVEL: Override logging level

LOG_LEVEL=debug .claude/hooks/pre-tool-use

Custom Installation Path

To install to a different location, edit installer scripts before running:

# Edit installation path
TARGET_DIR="/path/to/custom/location"

Support

For issues, questions, or contributions:

Documentation: See tool-install/README.md for technical details
Source Files: Located in tool-install/ directory
Configuration Example: .claude/review-config.yaml.example

Version Information

Version: 1.0 Release Date: 2026-03-27 License: MIT License

Installer Scripts:

install-mac.sh - macOS installer
install-linux.sh - Linux installer (symlink to macOS version)
install-windows.ps1 - Windows PowerShell installer
install-windows.sh - Windows Git Bash/WSL installer

Source Location: tool-install/ directory

What Gets Installed

The installer copies the following to .claude/:

Hook Entry Point (1 file):
- hooks/pre-tool-use - Main hook script
Library Modules (7 files):
- lib/logger.sh - Logging functions
- lib/config-defaults.sh - Default configuration
- lib/config-parser.sh - YAML parser with fallbacks
- lib/user-interaction.sh - User prompts
- lib/review-executor.sh - Artifact discovery and review
- lib/report-generator.sh - Report parsing and formatting
- lib/audit-logger.sh - Audit trail logging
Templates (1 file):
- templates/design-review-report.md - Report template
Configuration (2 files):
- review-config.yaml - Active configuration (generated)
- review-config.yaml.example - Example configuration

Total: ~1,210 LOC (lines of code) in bash scripts

License

Licensed under the MIT License. See LICENSE file for details.

FilesExpand file tree

INSTALLATION.md

Latest commit

History

INSTALLATION.md

File metadata and controls

AIDLC Design Review Hook - Installation Guide

Table of Contents

Overview

Prerequisites

Required

Optional (for full functionality)

Installation

Installing Into Existing AIDLC Project

Step 1: Obtain the Hook Source Files

Step 2: Verify Your AIDLC Project Structure

Step 3: Run the Installer

Step 4: Configure for Your Project

Step 5: Create Required Directories

Step 6: Test the Installation

Step 7: Integration Testing

Troubleshooting Existing Project Installation

macOS

Linux

Windows PowerShell

Windows Git Bash/WSL

Configuration

Configuration Options

Review Modes

Editing Configuration

Validation

Check File Integrity

Run Test Review

Updating

Automatic Backup

Uninstallation

Troubleshooting

Common Issues

1. "Bash 4.0 required" error

2. "Permission denied" errors

3. Hook not executing

4. "Command not found: yq" warnings

5. YAML parsing errors

6. Windows line ending issues (Git Bash)

7. Report not generated

Advanced Configuration

Environment Variables

Custom Installation Path

Support

Version Information

What Gets Installed

License