AIDLC Design Reviewer

An agent-native re-implementation of the AIDLC Design Reviewer: a multi-phase design review (Critique → Alternatives → Gap Analysis) that runs entirely inside an AI coding assistant, with no Bedrock/AWS dependency. It produces a weighted quality score and Markdown + HTML reports.

Layout

.
├── common/                 # IDE-agnostic resources (single source of truth)
│   ├── patterns/           #   architectural pattern definitions (extensible; see its README)
│   ├── methodology/        #   critique/alternatives/gap agent bodies (the
│   │                       #   canonical methodology, {{PATTERNS_DIR}} placeholder)
│   ├── tools/              #   deterministic Python tools (stdlib only)
│   │   ├── discover_artifacts.py   # validation + discovery + classification
│   │   └── build_report.py         # scoring + Markdown/HTML rendering
│   └── review-config.yaml  #   shared review settings (severity, phase toggles)
├── claude/                 # Claude Code packaging (implemented)
│   ├── agents/*.head.md    #   thin frontmatter heads (composed with methodology)
│   └── skills/design-review/SKILL.md   # the /design-review orchestrator
├── kiro/                   # Kiro packaging (implemented)
├── codex/                  # Codex CLI packaging (implemented)
├── copilot/                # GitHub Copilot packaging (implemented)
├── install.sh              # copies the right pieces into an IDE's config dir
├── SECURITY.md             # trust model + threat/mitigation notes
└── README.md

Per-IDE config dirs (.claude/, .kiro/, .github/, .codex/, and a root AGENTS.md) are generated install targets — gitignored, not shown above.

The IDE config directory (e.g. .claude/) is an install target, regenerated from this source by install.sh. It is intentionally gitignored — edit the source here, then re-run the installer.

Single source of truth. The review methodology lives once in common/methodology/{critique,alternatives,gap}.md. Each IDE folder holds only the thin glue it actually needs — for Claude that is a 6-line frontmatter head per agent (claude/agents/*.head.md). At install time the installer composes head + methodology (substituting {{PATTERNS_DIR}} for the IDE's pattern path) into the final agent file, so the methodology is never duplicated and cannot drift between IDEs.

Install

Pick your assistant and run the matching command from the repo root. The same command configures both the CLI and IDE form of that assistant.

Claude Code

./install.sh --ide claude            # installs into ./.claude

Then run /design-review in Claude Code (restart the session to pick up the new skill/agents).

Kiro

./install.sh --ide kiro              # installs into ./.kiro

Then ask Kiro "review my design", or switch to the agent with /agent design-reviewer. See kiro/README.md.

GitHub Copilot

./install.sh --ide copilot           # installs into ./.github

Then run /design-review in Copilot Chat (agent mode). See copilot/README.md.

Codex

./install.sh --ide codex             # installs into ./.codex + root AGENTS.md

Then ask Codex "review my design" (the root AGENTS.md routes to the orchestrator). See codex/README.md.

Common flags

All assistants accept the same flags:

./install.sh --ide <name> --dry-run        # preview the file operations, write nothing
./install.sh --ide <name> --dest <dir>      # install to a custom location (e.g. ~/.claude)

Re-run install.sh after editing anything in common/ or an assistant's source folder — the config dirs it writes are regenerated install targets.

Architecture

Concern	Implementation
Discovery + classification of design artifacts	common/tools/discover_artifacts.py (deterministic)
Corpus assembly	inside the orchestrator (skill/prompt/steering doc)
Critique / Alternatives / Gap analysis	the assistant's agent(s)
Orchestration (critique → [alternatives ∥ gap])	the orchestrator
Scoring + Markdown/HTML report	common/tools/build_report.py (deterministic)

The agents do the reasoning; the two Python tools do the math and formatting so scores and report layout are exact and reproducible.

Customizing the pattern library

The architectural patterns the reviewer checks against live in common/patterns/ — one Markdown file per pattern. The library is extensible: the agents read every file present, so you can add your own patterns (e.g. an org-specific one) without touching any code or config.

To add a pattern, create common/patterns/<your-pattern>.md following the documented format, then re-run install.sh for your assistant. See common/patterns/README.md for the file format and step-by-step instructions.

Supported assistants (CLI and IDE)

Each assistant works equally well in its CLI and IDE forms — both read the same config directory the installer writes (e.g. .claude/, .kiro/, .github/, .codex/ + root AGENTS.md), so a single install.sh --ide <name> configures both. No separate CLI-vs-IDE setup is needed.

• Claude Code — implemented (/design-review skill + subagents, parallel phase 2).
• Kiro — implemented (steering doc + agent config, sequential phases).
• Copilot — implemented (/design-review reusable prompt, sequential phases).
• Codex — implemented (root AGENTS.md pointer + orchestrator, sequential phases).

common/ is shared verbatim across all of them; only the per-assistant packaging and an install_<ide> function differ.

Security

See SECURITY.md for the trust model and threat/mitigation notes (untrusted-input handling, report XSS, responsible-AI/advisory framing, local data sensitivity, and per-IDE model approval). The reviewer has no cloud dependency — it runs on the host IDE's model and ships only stdlib helper tools.

License

This sample is licensed under the MIT-0 License. See the LICENSE file.