/architect — Implementation Architecture from PRD

When to Use

Don't use when: you already have an architecture and want to implement it (use /marshal or /archon); you need a PRD first (use /prd before /architect).

After /prd produces an approved PRD (greenfield or feature mode)
When the user has a clear direction + existing codebase (no PRD needed)
When /do routes a build request
When the user has a spec and wants a build plan

Inputs

One of:

A PRD file path (from /prd) — preferred, contains structured requirements
A user-provided spec or description + an existing codebase — sufficient
Neither — suggest /prd first, but don't hard-gate. If the user has a clear direction ("add auth to my app"), that + the existing code IS the input.

Mode Detection

Greenfield mode: PRD exists with Mode: greenfield, or no existing source files. Produces a complete architecture from scratch.

Feature mode: PRD exists with Mode: feature, OR the user describes a feature and the project has existing source files. The architecture describes changes to existing code, not a standalone system.

In feature mode:

Read the existing file tree FIRST — understand the current architecture before planning changes
Read key files (package.json, tsconfig, main entry points, existing patterns)
The File Tree section shows ONLY new and modified files, not the entire project
Phases include a Phase 0: "Baseline" that records current typecheck/test state
Every phase's end conditions include "no new typecheck errors" and "existing tests pass"
The Risk Register includes "regression in existing functionality" as a default risk

Protocol

Step 1: READ

If PRD exists, read it. Extract:

Core features (the numbered list)
Technical decisions (stack choices)
End conditions (what "done" looks like)
Out of scope (what NOT to build)
Integration points (feature mode)

If no PRD, read the codebase instead:

Scan the file tree for structure and conventions
Read package.json / equivalent for dependencies and scripts
Read the main entry point(s) to understand the architecture
Use the user's description as the feature spec
Infer end conditions from the description ("add auth" → "protected routes return 401 without token")

Step 2: EVALUATE OPTIONS (for non-trivial decisions)

For decisions with multiple valid approaches — state management, API structure, auth pattern, DB schema, routing — generate 2-3 candidates. Assess each on complexity, risk, maintainability, and LLM-friendliness. Pick the winner and document why. Reject alternatives with reasoning.

Simple decisions (file naming, folder structure, CSS) don't need this — use the PRD's stack choices and move on.

Step 3: PRODUCE

Write to .planning/architecture-{slug}.md:

# Architecture: {App Name}
> PRD: .planning/prd-{slug}.md  |  Date: {ISO date}

## File Tree
{Greenfield: complete file tree for v1, every file listed.
Feature mode: ONLY new (+) and modified (~) files.}

## Component Breakdown
### Feature: {name}
- Files: | Dependencies: | Complexity: {low/medium/high}

## Data Model
### {Entity name}
- Fields: {name: type}  |  Relationships: {connections}
{Omit section if no database.}

## Key Decisions
### {Decision}: {chosen approach}
- **Chosen**: {approach} — {reasoning}
- **Rejected**: {alternative} — {why not}

## Build Phases
### Phase N: {name}
- **Goal**: {one sentence}
- **Files**: | **Dependencies**: {or "none"}
- **End Conditions**: [ ] {machine-verifiable}

## Phase Dependency Graph
{Text format: Phase 1 → Phase 2 → Phase 3 / Phase 3 + 4 → Phase 5}

## Risk Register
1. {risk}: {mitigation}
2. {risk}: {mitigation}
3. {risk}: {mitigation}

## Deployment Strategy
{Skip if "deploy later" or static-only.}
- **Platform**: | **Method**: | **Environment variables**: | **Pre-deploy checks**:
{Final phase is "Deploy" when a platform is specified. A failed deploy does NOT fail the campaign.}

Step 4: CONNECT TO CAMPAIGN

Each build phase becomes a campaign phase; end conditions carry over; the dependency graph determines ordering; parallel-safe phases flagged for Fleet.

Present summary to user (file count, phase count, key decisions, estimated complexity) and ask: "Ready to build? This will create an Archon campaign." If approved, write the campaign file.

Step 5: HANDOFF

---HANDOFF---
- Architecture: {app name}
- Document: .planning/architecture-{slug}.md
- Phases: {count}
- Estimated complexity: {low/medium/high}
- Next: Archon campaign ready to execute
- Reversibility: green — delete .planning/architecture-{slug}.md to undo
---

Contextual Gates

Disclosure: "Generating architecture plan for [description]. No files modified until you approve." Reversibility: green — creates .planning/architecture-{slug}.md only; undo with rm .planning/architecture-{slug}.md. Trust gates:

Any: generate architecture document, evaluate options, connect to campaign.

Quality Gates

Every phase has at least one machine-verifiable end condition
Every key decision documents what was rejected and why
File tree is complete (no "etc." or "..." placeholders)
Phase dependencies are explicit (no implicit ordering)
Risk register has at least 2 entries

Fringe Cases

No PRD: Treat user description + existing codebase as the spec; read file tree and package.json; proceed without requiring a PRD.

Project already has code: Use feature mode; read existing architecture first; file tree shows only new/modified files; Phase 0 records baseline typecheck/test state.

Vague description: Ask at most 2 clarifying questions; don't block on perfect clarity.

.planning/ missing: Create it; if not possible, output the architecture inline and instruct the user to save it.

Exit Protocol

---HANDOFF---
- Architecture: {app name}
- Document: .planning/architecture-{slug}.md
- Phases: {count}
- Estimated complexity: {low/medium/high}
- Next: Archon campaign ready to execute
- Reversibility: green — delete .planning/architecture-{slug}.md to undo
---

architect