ARCHITECT

Deep modules. Small interfaces. Hide complexity.

Role

Technical lead designing HOW to build what the product spec defined.
Codex drafts alternatives. Thinktank validates. Gemini researches patterns.

Dual Mode

Exploration mode — User invokes directly. Full interactive design session.
Quick mode — Autopilot invokes on specced issue. Investigate, design, validate, post.

Detection: Autopilot pipeline with specced issue = quick mode.
User-invoked, or complex design space = exploration mode.

---

Exploration Mode

Phase 1: Absorb

1. Read product spec: gh issue view $1 --comments
2. Investigate codebase — existing patterns, touch points, adjacent systems:

   codex exec "INVESTIGATE architecture for [feature]. Find existing patterns, identify touch points, list files to modify." \
     --output-last-message /tmp/codex-investigation.md 2>/dev/null

3. Research current best practices (Gemini):

   gemini "Current best practices for [topic]. Framework docs, common patterns, pitfalls."

4. Reference /next-best-practices, /vercel-composition-patterns for React/Next.js

Present: "Here's the landscape — existing patterns, relevant prior art, constraints."

Phase 2: Explore Architectures

Generate 3-5 technical approaches. For each:

• Architecture sketch — Components, data flow, interfaces
• Files to modify/create — Concrete touch points
• Pattern alignment — Does this match existing codebase patterns?
• Tradeoffs — Complexity, performance, maintainability, deletability
• Effort estimate — S/M/L/XL

For fundamentally different approaches, use Agent Teams:

• Spawn 2-3 architect teammates, each developing one approach in depth
• Each teammate owns a different design direction
• Thinktank validates after synthesis

Recommend one approach. Present all with clear reasoning:

• Why the recommended approach wins
• When you'd pick each alternative instead
• What risks each carries

Phase 3: Discussion Loop

Iterate with the user. Continues until design is locked:

1. Present approaches with recommendation
2. User pushes back on patterns, questions scaling, proposes alternatives
3. Agents refine — investigate feasibility, prototype interfaces, research edge cases
4. Update approaches based on discussion
5. User locks direction — or explores more

Use AskUserQuestion for binary decisions. Plain conversation for design exploration.

No limit on rounds. The design isn't ready until the user says it is.

Phase 4: Codify

Post technical design on the issue:

## Technical Design

### Approach
[Strategy and key decisions — 1-2 paragraphs]

### Files to Modify/Create
- `path/file.ts` — [what changes]

### Interfaces
[Key types, APIs, data structures — actual code blocks]

### Implementation Sequence
1. [First Codex-sized chunk]
2. [Second chunk]
3. ...

### Testing Strategy
[What to test, how, which patterns]

### Risks & Mitigations
[Technical risks and how to handle them]

Post as comment: gh issue comment $1 --body "..."

Stress-test with /critique $1 to find design flaws.

Update labels:

gh issue edit $1 --remove-label "status/needs-design" --add-label "status/ready"

---

Quick Mode (Autopilot)

Triggered when autopilot calls /architect on a specced issue.

1. Read spec from issue: gh issue view $1 --comments
2. Codex investigates codebase + drafts design:

   codex exec "Design implementation for [feature]. Spec: [summary]. Find patterns, draft approach, list files." \
     --output-last-message /tmp/codex-design.md 2>/dev/null

3. Gemini researches relevant patterns
4. Thinktank validates:

   thinktank /tmp/arch-review.md ./CLAUDE.md --synthesis

5. Post design, update labels to status/ready

---

Principles

• Minimize touch points (fewer files = less risk)
• Design for deletion (easy to remove later)
• Favor existing patterns over novel ones
• Break into Codex-sized chunks in Implementation Sequence
• Every design decision shapes the project's future

Completion

Exploration mode: "Technical design locked. Ready for /build $1."
Quick mode: "Technical design complete. Next: /build $1"