/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:

Condition	Mode	Behavior
Scout has established patterns	Follow	Use existing patterns, no questions, minimal output
Scout exists but feature needs NEW tech	Extend	Ask ONLY about the gap
No scout / greenfield OR --new flag	Design	Ask constraint questions, present options

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)
• Actions (decisions needed)

Output:

• Requirements vs Capabilities table
• Gaps requiring decisions

Decision Making

Only create ADRs for NEW decisions, not for following existing patterns.

Decision categories:

• API (REST vs GraphQL, versioning, conventions)
• Data (database, ORM, schema design)
• Auth (JWT/session/OAuth, permissions)
• Frontend (state management, component structure)
• Integration (service connections, event-driven)
• Infrastructure (caching, queues, storage, email)

Each decision includes:

• Context (why needed)
• Options considered (pros/cons/effort)
• Decision (chosen option + rationale)
• Consequences (trade-offs accepted)

Quality Assessment

Apply _quality-attributes.md Architecture Level checklists:

• Scalability: Stateless design, pagination, caching, background jobs
• Maintainability: Module boundaries, consistent structure, abstracted dependencies
• Security: Auth strategy, permission model, data encryption
• Reliability: No single points of failure, graceful degradation
• Performance: Latency targets, CDN, optimizations
• Testability: Injectable dependencies, test strategy

Architecture Document

Create plans/features/{feature}/architecture.md with:

• Overview (high-level description)
• Architecture diagram (Mermaid)
• Key decisions table
• Patterns to follow (API, data, component, auth)
• Quality checklist
• ADRs (if created)
• Risks & mitigations
• Next steps

ADR Format

Create plans/features/{feature}/adrs/ADR-{NNN}-{slug}.md with:

• Status (Proposed/Accepted/Deprecated/Superseded)
• Context (why this decision)
• Decision (what we're doing)
• Options considered (with pros/cons)
• Consequences (positive/negative/neutral)
• Related decisions

Decision Categories

See references/decision-categories.md for option tables (API, Database, Frontend State, Auth, Infrastructure) and Context7 usage for architecture research.

Categories: API Design, Database, Frontend State, Authentication, Infrastructure.

Tools Used

Tool	Purpose
Read	Load requirements, scout, quality attributes
Write	Create architecture.md, ADRs
Glob	Find existing patterns
Grep	Search for conventions
AskUserQuestion	Clarify decisions
Context7	Look up architecture best practices
WebSearch	Find architecture patterns

Integration

Skill	Relationship
/debrief	Calls to validate feasibility
/dev-scout	Provides current state analysis
/dev-specs	Consumes architecture decisions
/utils/diagram	Validates mermaid diagrams
_quality-attributes.md	Provides checklists

Key Principle

Use existing patterns. Only ask about what's truly new.

The team's current architecture is their comfort zone. They know it, they control it.
Don't suggest microservices to a monolith team. Don't ask about database choice when they're already on PostgreSQL.

Existing patterns → Follow automatically
New requirements that don't fit → Ask only about those
Greenfield → Ask constraint questions

Example Flows

See references/examples.md for detailed Follow/Extend/Design mode examples.

Mode	Questions Asked	ADRs Created
Follow	None	None
Extend	Only for gaps	Only for new decisions
Design	Full constraint gathering	For all decisions

Default to Follow mode. Only escalate when necessary.

References

• references/decision-categories.md - Option tables, Context7 usage
• references/examples.md - Follow/Extend/Design mode examples