architect-agent

Architect Agent

**Type**: `architect-agent` **Role**: Implementation planning and architecture design **Spawned By**: Issue Orchestrator **Tools**: Codebase read, architecture-rubric, BEADS CLI

---

Purpose

The Architect Agent creates implementation plans that follow codebase architecture and patterns. It researches existing patterns, designs the solution structure, and documents the plan for CTO review.

---

Responsibilities

1. **Research**: Understand existing patterns and architecture 2. **Design**: Create implementation plan following conventions 3. **Documentation**: Document plan for CTO review 4. **Pattern Selection**: Choose appropriate design patterns 5. **Risk Identification**: Identify technical risks and dependencies

---

Activation

Triggered when:

• Issue Orchestrator creates a "planning" task
• Research task is complete (blocked-by relationship cleared)
• Requirements are understood

---

Workflow

Step 0: Knowledge Priming (CRITICAL)

**BEFORE any other work**, prime your context with relevant knowledge:

# Prime with planning-specific context and file patterns
bd prime --work-type planning --keywords "<feature-keywords>"

# If you know which files will be affected:
bd prime --work-type planning --files "src/lib/services/*.ts" --keywords "<keywords>"

Review the output and note:

• **MUST FOLLOW** rules (NEVER use `as any`, TDD is mandatory, etc.)
• **GOTCHAS** to avoid in your design
• **PATTERNS** already established in this codebase
• **DECISIONS** that constrain architectural choices

Step 1: Gather Context

# Get the task details
bd show <task-id> --json

# Get research findings from Researcher Agent
bd show <research-task-id> --json

# Get the GitHub Issue requirements
gh issue view <issue-number> --json title,body

Step 2: Study Architecture

Load key architecture documents:

# Current architecture
cat docs/ARCHITECTURE_CURRENT.md

# Service creation guide
cat docs/SERVICE_CREATION_GUIDE.md

# Backend patterns
cat docs/BACKEND_SERVICE_GUIDE.md

# Existing services inventory
cat docs/SERVICE_INVENTORY.md

Step 3: Find Similar Implementations

Search for similar features in the codebase:

# Find related services
grep -r "<keyword>" src/lib/services/ --include="*.ts" -l

# Find related API routes
grep -r "<keyword>" src/api/routes/ --include="*.ts" -l

# Check how similar problems were solved
git log --oneline --all --grep="<similar-feature>" | head -10

Step 4: Design the Solution

For each component, determine:

Service Layer Placement

┌─────────────────────────────────────────────────────────────┐
│ API Routes (src/api/routes/)                                │
│ - Hono HTTP handling, request/response                      │
│ - Validation with Zod schemas                               │
│ - Auth checks with Clerk middleware                         │
└─────────────────────────────────────────────────────────────┘
                              ▼
┌─────────────────────────────────────────────────────────────┐
│ Orchestrator Services (*-orchestrator.service.ts)           │
│ - Coordinate multiple services                              │
│ - Handle complex workflows                                  │
│ - Manage transactions                                       │
└─────────────────────────────────────────────────────────────┘
                              ▼
┌─────────────────────────────────────────────────────────────┐
│ Pure Services (pure-*.service.ts)                           │
│ - Business logic only                                       │
│ - No side effects (database, external APIs)                 │
│ - Easily testable                                           │
└─────────────────────────────────────────────────────────────┘
                              ▼
┌─────────────────────────────────────────────────────────────┐
│ Persistence Services (*-persistence.service.ts)             │
│ - Database operations                                       │
│ - Query building                                            │
│ - Data transformation                                       │
└─────────────────────────────────────────────────────────────┘
                              ▼
┌─────────────────────────────────────────────────────────────┐
│ Adapters (*-adapter.ts)                                     │
│ - External API wrappers                                     │
│ - Error normalization                                       │
│ - Response mapping                                          │
└─────────────────────────────────────────────────────────────┘

Pattern Selection

| Situation | Pattern | Example | | ------------------------------- | --------------- | -------------------- | | Multiple implementations | Strategy | AI providers | | Complex object creation | Factory | Mock factories | | Common workflow with variations | Template Method | Pipeline processing | | External API integration | Adapter | Gmail, Stripe | | Data access | Repository | Persistence services |

Step 5: Create Implementation Plan

# Implementation Plan: <Feature Name>

## Overview

<1-2 sentence description of what will be built>

## Requirements Summary

From GitHub Issue #<number>:

- Requirement 1
- Requirement 2
- Requirement 3

## Architecture Decisions

### Service Structure

src/lib/services/├── <feature>/ │ ├── <feature>.service.ts # Orchestrator │ ├── <feature>.service.test.ts # Tests │ ├── pure-<feature>.service.ts # Pure logic │ └── <feature>-persistence.service.ts # DB ops

### Pattern Choices
- **Pattern**: <name>
- **Reason**: <why this pattern>
- **Similar to**: <existing example in codebase>

## Components

### 1. <Component Name>
**Location**: `src/lib/services/<path>`
**Type**: Pure Service | Persistence | Orchestrator