Review Orchestrator

Output Path — MANDATORY

All review output goes into the feature's code-review directory:

{output_dir}/{feature}/code-review/{N}-{slug}/
├── summary.md                       ← consolidated findings (main output)
├── changes.md                       ← fixes applied (written after step 9)
└── detailed/
    └── <agent-name>.md              ← one file per dispatched agent

Where {output_dir} comes from .shield.json output_dir field (default docs/shield), {feature} is the feature folder name ({feature-name}-YYYYMMDD), {N} is a sequential number, and {slug} is a short kebab-case descriptor. Do NOT use any other path or directory structure. The Write tool creates directories automatically.

When to Use

• After implementing a feature or story step
• When explicitly invoked via /review
• As the final review at the end of an implementation pipeline

When NOT to Use

• For plan review — use plan-review skill instead
• For a single specific reviewer — use /review-security, /review-cost, etc.

Step Skeleton

At startup, call execute-steps to register these steps. Execute them in order, updating status after each.

Step	Action	Condition	Mandatory
1	Load prior context (plan, research)	skip if none exists	No
2	Code correctness review	always	Yes
3	Domain-specific review	skip if no active domains	No
4	Dispatch agent reviewers	explicit/final review only	No
5	AC verification	skip if no plan.json	No
6	Merge + present findings	always	Yes
7	Apply selected fixes	always	Yes
8	Write summary + update manifest	always	Yes

Review Process

1. Load Prior Context

Before reviewing, check for artifacts from prior phases (all optional — proceed without if missing):

• Plan sidecar — {output_dir}/{feature}/plan.json for stories and acceptance criteria
• Research — {output_dir}/{feature}/research/ for domain context
• Git changes — git log --oneline and git diff to see what changed during implementation

2. Determine Context and Scope

Identify the review context to determine depth:

Context	Scope	Depth
Per-step (during implementation)	Changed files for current story only	Code correctness + domain skill. No full agent suite.
Explicit /review	All files in scope	Full: code correctness + domain skills + all selected agents + AC verification
Final review	All files in scope	Full: everything + AC for all stories

3. Code Correctness Review

For all contexts, review the changed/staged files for:

• Logic bugs and error handling gaps
• Style consistency with surrounding code
• Test coverage — are new code paths tested?
• Edge cases and boundary conditions

4. Domain-Specific Review

Read .shield.json to get active domains. For each active domain, check if a domain-specific review skill exists:

• terraform → invoke shield:terraform:review
• atmos → invoke shield:atmos:review
• github-actions → invoke shield:github-actions:review

Domain skills run in parallel. Their findings are collected and merged.

5. External Plugin Skills

Check .shield.json for external_skills configured for the active domain's review phase. Invoke each configured external skill and merge findings.

6. Agent Reviews (explicit/final only)

Select reviewer agents based on:

• Auto-select: detect file types and content keywords → pick relevant reviewers
• always_include: from .shield.json reviewers section — always dispatched
• never_include: from .shield.json reviewers section — always skipped
• Minimum 3 agents for full review

Dispatch selected agents in parallel using the appropriate mode:

• For Terraform/HCL files → infra-code mode
• For plan documents → plan mode
• For application code → app-code mode (when available)

7. Save Detailed Findings

For each agent that returned results, write its full raw output to:

code-review/{N}-{slug}/detailed/<agent-name>.md

Where <agent-name> matches the agent (e.g., security.md, cost.md, architecture.md, operations.md, well-architected.md).

Each detailed file should include a header and back-link:

# <Agent Name> — Detailed Findings

> Back to [summary](../summary.md)

<full agent output>

If an agent fails or times out, omit its detailed file — do not write a placeholder.

8. Acceptance Criteria Verification (explicit/final only)

If an active story context exists (from the plan sidecar {output_dir}/{feature}/plan.json):

1. Read acceptance criteria from the plan JSON
2. Check each criterion against the implementation
3. Look for evidence in code, tests, and config
4. Produce an AC report table: criterion | status (met/not met/not verified) | evidence

9. Merge and Present Findings

1. Collect all findings from code review, domain skills, agents, and AC verification
2. Deduplicate — if multiple sources flag the same issue, keep the most detailed finding
3. Sort by severity (critical → important → warning)
4. Present summary table to user
5. Ask user which fixes to apply: all / select specific / skip
6. For findings flagged NEEDS_DISCUSSION, present options before applying
7. Optionally post findings to PM card (ask user)
8. In the summary file, add a "Detailed Agent Findings" section linking to each agent's file:

   ## Detailed Agent Findings
   - [Security](detailed/security.md)
   - [Cost](detailed/cost.md)
   - [Architecture](detailed/architecture.md)
   ...
   

10. Apply Fixes and Update Summary

1. Apply selected fixes
2. Write review summary to {output_dir}/{feature}/code-review/{N}-{slug}/summary.md (exact path from Output Path section above)
3. After writing, update {output_dir}/manifest.json and regenerate {output_dir}/index.html
4. Write changes.md in the same directory documenting applied fixes:

   # Code Review Changes
   
   > Review: [summary.md](summary.md)
   
   | # | Finding | File | Change Description |
   |---|---------|------|--------------------|
   | 1 | <finding from summary> | <file:line> | <what was changed> |
   

5. If any fixes were applied, re-render the plan HTML from sidecar

Output Format

Output Structure

code-review/{N}-{slug}/
├── summary.md                        ← table below
├── changes.md                        ← applied fixes log
└── detailed/<agent>.md               ← full per-agent output

Review Summary

#	Severity	Source	Location	Finding	Recommendation
1	Critical	security-reviewer	main.tf:42	Wildcard IAM policy	Scope to specific ARNs
2	Important	terraform/review	variables.tf:15	Missing validation block	Add CIDR validation

Acceptance Criteria Report (if applicable)

Criteria	Status	Evidence
Regional pools allocate /20 CIDRs	Met	main.tf:42 — netmask_length = 20
No CIDR overlap	Not verified	No test found

Actions

Which fixes would you like to apply?

• [a] Apply all
• [s] Select specific fixes
• [n] Skip — review only
• [p] Post findings to PM card

Detailed Agent Findings

• Security
• Cost
• Architecture
• Operations
• Well-Architected

Common Mistakes

Mistake	Fix
Running full agent suite for a per-step review during implementation	Per-step reviews only need code correctness + domain skills — save the full agent suite for explicit /review
Dispatching all agents without checking .shield.json reviewers config	Respect always_include and never_include from the project config before auto-selecting
Applying fixes without user confirmation	Always present findings and ask which to apply — never auto-fix, especially for NEEDS_DISCUSSION items
Writing detailed agent findings to summary.md instead of separate files	Each agent gets its own file in detailed/<agent>.md — summary.md only has the merged table
Skipping AC verification because no plan sidecar exists	If there's no plan.json, skip AC verification silently — don't error or ask the user to create one
Not deduplicating findings from multiple sources	If security-reviewer and terraform/security-audit flag the same issue, keep the most detailed one