Code Review

For each affected app or package, read (if they exist):

• <app-or-package>/README.md
• <app-or-package>/package.json
• Any subdirectory READMEs relevant to the changed files

The documentation tells you what kind of project this is. Examples of how this drives agent selection:

Step 3: Categorize Changed Files

After reading documentation, classify each changed file by domain. A file can belong to multiple domains (e.g., an auth service is both Backend and Security).

Step 4: Select and Launch Reviewer Agents in Parallel

Based on the project context (from Step 2) and file domains (from Step 3), select only the relevant agent personas. Use the Task tool to launch all selected agents simultaneously in a single message (max 4 per batch; if more than 4 are needed, run a second batch).

Available agent personas:

Constructing each agent's prompt:

Each agent receives a self-contained prompt (from agent-prompts.md) that includes:

1. The agent's persona and expertise
2. The project context summary (what kind of software it is, tech stack)
3. The relevant diff and file contents for their domain
4. Clear output format instructions (severity, file references, fix suggestions)

Read agent-prompts.md for the detailed prompt templates to use for each agent.

Step 5: Consolidate and Present

After all agents return their findings:

1. Group findings by file -- collect all issues across agents for each changed file
2. Tag each issue with the agent(s) that identified it -- if multiple agents flagged the same issue, merge into one entry referencing all agents
3. Deduplicate -- do not repeat the same issue twice; merge overlapping findings
4. Produce the final report using the output format below

Output Format

# 🔍 Code Review

## 📋 Summary

|                    |                                                    |
| ------------------ | -------------------------------------------------- |
| **Scope**          | staged / unstaged changes                          |
| **Files reviewed** | N                                                  |
| **Reviewers**      | 🏗️ Architecture · ⚙️ Backend · 🔒 Security · [...] |
| **Issues**         | 🔴 2 Critical · 🟡 3 Warning · 🔵 1 Suggestion     |

## 🔎 Findings

### `path/to/file.ts`

---

🔴 **Critical** · 🏗️ Architecture · ⚙️ Backend

Models are re-created on every retry attempt, causing unnecessary HTTP client setup overhead.

```ts
// ❌ path/to/file.ts:42
const result = await retry(async () => {
  const model = this.modelFactory.createChatModel(getTools())
  return model.invoke(messages)
})
```

// ✅ Fix
const model = this.modelFactory.createChatModel(getTools())
const result = await retry(async () => model.invoke(messages))

🟡 Warning · 🔒 Security

Description of issue.

// ❌ path/to/file.ts:88
const cmd = `convert ${userInput} output.png`
exec(cmd)

// ✅ Fix — use execFile with explicit args array
execFile('convert', [userInput, 'output.png'])

path/to/other-file.tsx

🔵 Suggestion · 🧪 Testing

Description of suggestion (no fix snippet required for minor suggestions).

// ❌ path/to/other-file.tsx:14
expect(result).toBeDefined()

// ✅ Fix — assert the actual value
expect(result).toEqual({ id: 1, name: 'foo' })

📝 Action Items

1. 🔴 Critical — 🏗️ Architecture · ⚙️ Backend — Short description · path/to/file.ts:42
2. 🔴 Critical — 🔒 Security — Short description · path/to/file.ts:88
3. 🟡 Warning — 🎨 Frontend — Short description · path/to/component.tsx:15
4. 🔵 Suggestion — 🧪 Testing — Short description · path/to/test.ts:30

The Action Items list must be:

- A single flat numbered list (no grouping by file or agent)
- Sorted by severity: 🔴 Critical → 🟡 Warning → 🔵 Suggestion
- Each item self-contained and concise (understandable without reading the detailed findings above)
- Include the file path and line number so I can jump directly to the code

**Agent emoji reference** (use consistently throughout):

| Agent | Emoji |
|---|---|
| Architecture | 🏗️ |
| Backend | ⚙️ |
| Security | 🔒 |
| Frontend | 🎨 |
| Testing | 🧪 |
| DevOps | 🚀 |
| Design/UX | 🖌️ |

## Additional Resources

- For detailed agent prompts and review criteria, see [agent-prompts.md](agent-prompts.md)