plan-architecture

name	plan-architecture
description	Plan feature architecture with component breakdown, data flow, and dependency mapping. Use before implementation to define contracts between layers.
context	fork
globs	["agents/**","platform/**","docs/ARCHITECTURE.md"]
alwaysApply	false

Plan Architecture Skill

When to Use

Use this skill when:

• Designing a new feature end-to-end before writing code
• Breaking down a complex change into implementation phases
• Mapping dependencies between components
• Defining API contracts between layers
• Evaluating architectural trade-offs
• Preparing a TDD-driven implementation plan

Architecture Planning Workflow

1. Understand the Requirement

Before drawing boxes:

• Identify the user-facing goal (what changes for the user?)
• Identify the system boundary (what components are touched?)
• Identify external dependencies (APIs, databases, queues, third-party services)

2. Component Breakdown

Break the feature into layers:

Request → Route/Handler → Service → Repository → Database
                       ↓
                   External APIs

For each component define:

• Responsibility — single sentence
• Inputs / Outputs — types, not just names
• Error cases — what can go wrong and how it surfaces

3. Data Flow Diagram

Map the happy path first, then edge cases:

Client
  │ POST /feature
  ▼
Handler (validates input, calls service)
  │
  ▼
Service (business logic, orchestrates)
  │         │
  ▼         ▼
Repo     External API
  │
  ▼
Database

4. Dependency Map

Component	Depends On	Depended By
Handler	Service	Client
Service	Repo, External API	Handler
Repo	Database	Service

5. API Contracts

Define contracts before implementation:

# Input schema
class CreateFeatureRequest(BaseModel):
    name: str
    config: dict[str, Any]

# Output schema
class FeatureResponse(BaseModel):
    id: UUID
    name: str
    created_at: datetime

# Error cases
# 400 — validation error
# 404 — dependency not found
# 409 — conflict (already exists)
# 500 — upstream failure

6. Implementation Phases

Split into parallel-safe phases for TDD execution:

Phase 1 — Data layer (Demeter)
  - Migration: create table
  - Model: ORM class
  - Repository: CRUD methods + tests

Phase 2 — Service layer (Hermes) [depends on Phase 1]
  - Service class: business logic + tests
  - External API client + mock tests

Phase 3 — API layer (Hermes) [depends on Phase 2]
  - Route handler + tests
  - Request/response schemas

Phase 4 — Frontend (Aphrodite) [can parallel Phase 2+3]
  - Component tree
  - API integration
  - Tests

Architectural Trade-offs Checklist

Before finalizing the plan, evaluate:

• Coupling — are components independently testable?
• Reversibility — can this be rolled back without data loss?
• Performance — any N+1 queries or blocking I/O?
• Security — input validation at boundary? Auth checked?
• Observability — can failures be traced end-to-end?
• Scalability — does this break under 10x load?

Output Format

The plan output should be a PLAN-<feature>.md artifact:

# PLAN-<feature>
**Date:** YYYY-MM-DD  **Status:** Awaiting Approval

## Goal
[One sentence]

## Component Breakdown
[Table: Component | Responsibility | Inputs | Outputs]

## Data Flow
[ASCII diagram]

## API Contracts
[Key schemas and error codes]

## Phases
1. Phase 1 — @demeter — [scope]
2. Phase 2 — @hermes — [scope]
3. Phase 3 — @aphrodite — [scope] (parallel with Phase 2)

## Risks
- [Risk and mitigation]

## Open Questions
- [ ] [Decision needed from human]