/dev-arch - Architecture Design

Skill Awareness: See skills/_registry.md for all available skills.

• Called by: /debrief (can architecture support this?), /dev-specs (what patterns to use?)
• Reads: _quality-attributes.md (Architecture Level sections)
• After: Informs /dev-specs with architecture decisions

Make architecture decisions for features. Ensures scalability, maintainability, and quality from the start.

When to Use

• New feature that requires structural decisions
• Existing feature that needs significant changes
• When /debrief needs to validate feasibility
• When /dev-specs needs patterns for implementation
• Technical debt evaluation

Usage

/dev-arch auth                    # Architecture for auth feature
/dev-arch billing --new           # New feature (more thorough)
/dev-arch payments --evaluate     # Evaluate existing architecture

When Called

From /debrief

/debrief creates use cases
    ↓
Calls /dev-arch with question:
    "Can current architecture support these requirements?"
    ↓
/dev-arch returns:
    - Yes, existing patterns work
    - Yes, with minor additions (specify)
    - No, need new architecture (propose)

From /dev-specs

/dev-specs starts generating specs
    ↓
Calls /dev-arch with question:
    "What patterns should specs use?"
    ↓
/dev-arch returns:
    - API patterns (REST/GraphQL, conventions)
    - Data patterns (models, relationships)
    - Component patterns (structure, state)
    - Integration patterns (how pieces connect)

Output

plans/features/{feature}/
├── architecture.md          # Architecture decisions
├── adrs/                    # Architecture Decision Records
│   ├── ADR-001-api-style.md
│   ├── ADR-002-auth-strategy.md
│   └── ...
├── scout.md                 # From /dev-scout
└── specs/                   # From /dev-specs (uses architecture.md)

Expected Outcome

Architecture decisions for what's NEW. Follow existing for what's KNOWN.

Outputs:

• architecture.md - If architecture decisions made
• adrs/ADR-*.md - For new decisions only (not for following existing patterns)
• Patterns to follow (API, data, component, auth)
• Quality assessment against _quality-attributes.md

Success Criteria

• Existing patterns followed automatically (no questions asked)
• Only ask about gaps (missing tech, new requirements)
• Quality attributes checked (scalability, security, performance, etc.)
• Team stays in their comfort zone
• Minimal output for Follow mode, detailed for Design mode

Modes

Auto-detect based on scout:

Context Sources

Read to understand current state:

• plans/scout/README.md - Project-level patterns
• plans/features/{feature}/scout.md - Feature-level patterns
• plans/features/{feature}/README.md - Feature requirements
• plans/brd/use-cases/{feature}/*.md - Use cases
• _quality-attributes.md - Architecture Level checklists
• plans/docs-graph.json - Dependencies

Follow Mode

When: Scout shows established patterns

Approach: Extract and apply automatically

Extract from scout:

• API style (REST, GraphQL, tRPC)
• Database (PostgreSQL + Prisma, MySQL, etc.)
• Frontend (React + Zustand, Vue + Pinia, etc.)
• Auth (JWT, session, OAuth)
• Folder structure

Apply to new feature:

• New endpoints follow existing API pattern
• New models use existing ORM conventions
• New components follow existing structure
• Only flag if requirements CANNOT fit

Output: Minimal architecture.md noting patterns applied

Extend Mode

When: Existing patterns but feature needs something new

Approach: Ask ONLY about the gap

Identify gaps:

• Feature needs real-time (no WebSocket configured)
• Feature needs payments (no payment provider)
• Feature needs file uploads (no storage)
• Feature needs queue (no background jobs)

Present options for gap only:

• Recommend based on constraints
• Pros/cons of each option
• Ask user to choose

Everything else: Follow existing patterns

Design Mode

When: No existing patterns OR --new flag

Approach: Ask constraint questions, present options

Ask about:

• Project context (new/existing/rebuild)
• Team & deployment (solo/small/large, VPS/cloud)
• Key constraints (tech, budget, timeline, compliance)

Present recommendations based on constraints:

• Recommended stack with rationale
• Alternatives considered (why not)
• Ask user to approve or modify

Gap Analysis

For any mode, identify gaps:

Compare:

• Requirements (what feature needs)
• Current capabilities (what exists)
• Gaps (what's missing

...