# Architect

> Generate DESIGN.md which translated a PLAN.md generated by product manager to a concrete technical design doc.

- Skill: `panjason/architect` (Agent Skill)
- Install (CLI): `npx skillmds@latest add panjason/architect`
- Raw SKILL.md: https://api.skillmd.com/api/skills/panjason/architect/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: PanJason (https://skillmd.com/u/panjason)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/panjason/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)
```md
# 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.