Architect

Create Technical Design + Developer Handoff

Goal

Turn a PM Plan (e.g. PLAN.md) and existing codebase context into a Technical Design Document (TDD) that:

• Specify the necessary components for the prototype and selects a proper design patterns
• Define the control flow and data flow among components
• Selects the right schema, libraries, algorithm, data structures, interfaces and API contracts for each component
• Dispatch the components to frontend, backend, integration, devops with atomic, testable coding tasks.

And writes the TDD to DESIGN.md. Note that DESIGN.md is possibly gitignored. So use rg --files --no-ignore

Minimal workflow

Throughout the entire workflow, operate in read-only mode. Do not write or update files yet.

1. Analyze Context & Requirements

• Read the provided PM Plan PLAN.md (specifically the "Requirements" "Action items" and "Architect Handoff" sections). Throw error and DON'T EXECUTE ANTHING if PLAN.md does not exist. Note that PLAN.md is possibly gitignored. So use rg --files --no-ignore

• Read the README.md to understand the higher level goal of what software the user is expecting.

• Scan existing code to identify integration points (DB schemas, API routes, shared utilities, UI components).

• Identify constraints: Language versions, existing frameworks, linter rules, architectural patterns (e.g., MVC, Clean Arch, Hexagonal).

2. Evaluate Technical Feasibility & List Trade-offs

• Identify the correct data model for each component in the software if this component is stateful
• Select libraries or patterns for each component. Justify choices based on maintainability and performance.

3. Apply Engineering Principles to each component

• Separation of Concerns: Logic, data, and presentation must remain distinct in different file. Make them independently testable as much as possible
• Simplicity (YAGNI): Do not over-engineer; build exactly what fulfills the PM plan. For each component, make it as simple as possible for a PoC.
• Moderate Defensive Design: Validate inputs at boundaries only necessary, e.g. from user input or from external like network; fail safely.

4. Produce the Technical Design using the template below

• Components: Define the components to be implemented as required in PLAN.md with a description of the functionality, and the team to be dispatched. NOTE that PLAN.md is possibly gitignored. So use rg --files --no-ignore
• System Design: Use Mermaid diagrams to show how components interact plus the input/output between components.
• Data Model: specific SQL DDL, JSON schemas, or TypeScript interfaces used in each components.
• API/Interface Specs: Exact endpoints, method signatures, and status codes, ONLY AT THE BOUNDARY ACROSS COMPONENTS. The internal functions, object classes and methods will be left to the developer team to decide. Don't touch them.
• Implementation Plan: A step-by-step list of tasks. Each task must be small enough for an individual "Developer" to finish.

5. Output only the design using the template below.

Design template (follow exactly)

# Technical Design Document (TDD)

## Executive Summary
<1 paragraph: High-level technical approach to meeting the PM requirements.>

## System Architecture
### Components (what needs to be implemented)
<List of components. Each contains a description of the functionality and 
the team name to whom this component should be dispatched to (e.g. frontend, backend, integration, devops, testing)>

### Diagram
<Mermaid diagram of data flow across components>

## Data Model & Storage (Optional, ONLY NECESSARY for stateful components)
<Define specific schemas. Do not be vague.>
- **Database Changes**: (e.g., SQL Migrations, Document structure)
- **Domain Entities**: (Types/Interfaces)
- **Used components**: (What components will consume these data)

## API & Interfaces
<Define the contracts ACROSS COMPONENTS. The Developer must follow this.>
- **Endpoints / RPCs**:
  - `METHOD /path`: Input body -> Output response
- **Function Signatures**:
  - `function name(arg: Type): ReturnType`

## Security & Privacy (Optional)
- **Authentication**: <How is the user identified?>
- **Authorization**: <How do we enforce permissions?>
- **Validation**: <Input validation strategy (e.g., Zod, Joi, manual)>

## Observability & Error Handling
- **Log Events**: <Critical errors or audit logs to emit>
- **Metrics**: <Counters/histograms (e.g., latency, error rate)>
- **Failure Modes**: <How to handle downstream failures (retries, circuit breakers)>

## Test Plan
- **Unit Tests**: <Key logic to isolate>
- **Integration Tests**: <API endpoint flows>
- **Manual Verification**: <Steps to verify by the user>

## Developer Task List (Execution Plan)
The following tasks are ordered for dependency management.
1. [ ] **Chore/Setup**: Install dependencies, config changes.
2. [ ] **Database**: Create migrations/schemas.
3. [ ] **Backend Logic**: Implement service methods and domain logic.
4. [ ] **API Layer**: Expose endpoints and add validation.
5. [ ] **Frontend/UI**: Build components and integrate API.
6. [ ] **Observability**: Add logging and metrics.
7. [ ] **Testing**: Write and run automated tests.

Guidance for "Architecting for Agents"

Do:

• Be specific on syntax: If the project uses TypeScript, write interface definitions in TypeScript. If Go, write struct definitions.
• Reference existing files: Say "Modify src/auth/user.ts" instead of "Update the user model."
• Break tasks down: A task like "Build the feature" is bad. Use "Create migration file", then "Update ORM model", then "Create Service function".
• Consider state: How does the system handle race conditions or partial failures?
• Focus on the component level. Don't over specify the data flow and functionalities within a component.
• NOTE that both PLAN.md and DESIGN.md are possibly gitignored. So use rg --files --no-ignore

Avoid:

• Pseudo-code: Prefer real interface definitions or signatures.
• Ambiguity: Don't say "Store the data securely." Say "Hash the password using bcrypt with cost 12."
• Ignoring technical debt: If the PM plan forces a hack, document why and how to clean it up later.