Architect

System Architect

Analyze system architecture, module boundaries, API contracts, data models, and code patterns.

Context Discovery

Run the shared context discovery protocol in CONTEXT_DISCOVERY.md. Execute all phases in order (use deep scan mode for Phase 7). Also glob for architecture-specific documents:

docs/adr/**/*.md, docs/architecture/**/*.md, docs/design/**/*.md

After standard discovery, perform architecture-specific scans from TECH_STACK_DETECTION.md § Architecture-Specific Scanning (framework detection, architecture patterns, database patterns).

Arguments

Parse from $ARGUMENTS:

Mode Execution

See WORKFLOW.md for detailed execution steps per mode.

Output Rules

• Conversational with optional file persistence — analysis in chat, offer to save
• Diagram-friendly — use Mermaid diagrams when they clarify relationships
• Pattern-consistent — always reference existing codebase patterns
• Practical — recommendations should be implementable
• Scoped — answer the specific question; don't redesign the whole system

File Persistence

After producing the analysis, ask the user:

Save this analysis to `{output_dir}/architecture/{filename}.md`?

Where {output_dir} comes from .arkhe.yaml (default: arkhe/roadmap).

Deep Mode (--deep)

When $ARGUMENTS contains --deep, run the full multi-agent pipeline with Adversarial Review. A red team agent actively tries to break the proposed architecture.

See WORKFLOW.md § Deep Pipeline for the 5-phase execution protocol.

Patterns applied: Pipeline, Confession, Adversarial Review, Confidence-Gated Completion.

Lane Discipline

See the System Architect section of LANE_DISCIPLINE.md. Stay in your lane.

References

• WORKFLOW.md — Detailed pattern analysis workflows
• EXAMPLES.md — Usage examples
• TROUBLESHOOTING.md — Common issues and fixes

Architect Skill — Examples

Usage examples for the System Architect skill.

Example 1: Module Analysis

Input: /roadmap:architect module payments

Output:

## Module: payments

### Structure
payments/
├── models/
│   ├── Payment.ts
│   ├── PaymentMethod.ts
│   └── Transaction.ts
├── services/
│   ├── PaymentService.ts
│   └── StripeAdapter.ts
├── routes/
│   └── payments.ts
└── __tests__/
    ├── PaymentService.test.ts
    └── payments.routes.test.ts

### Domain Model
| Type | Name | Fields | Notes |
|------|------|--------|-------|
| Entity | Payment | id, amount, currency, status, method, createdAt | Aggregate root |
| Entity | Transaction | id, paymentId, type, amount, stripeId | Child of Payment |
| Value Object | PaymentMethod | type, last4, brand | Embedded in Payment |

### API Surface
| Method | Path | Auth | Notes |
|--------|------|------|-------|
| POST | /api/v1/payments | Required | Create payment intent |
| GET | /api/v1/payments/:id | Required | Get payment status |
| POST | /api/v1/payments/:id/confirm | Required | Confirm payment |
| GET | /api/v1/payments | Required | List user payments (paginated) |

### Dependencies
- Depends on: auth (user context), orders (order reference)
- Depended by: notifications (payment events)

### Maturity: Service Layer
Payment processing logic exists but controllers have TODOs for
webhook handling and refund flows.

### Quality Assessment

| Area | Rating | Notes |
|------|--------|-------|
| Code Quality | Moderate | `StripeAdapter.ts` is 450 lines with deeply nested error handling |
| Test Coverage | Low | 2 test files for 5 source files; no error scenario tests |
| API Design | Good | RESTful, consistent with other modules |
| Module Isolation | Good | Uses IDs for cross-module references |

### Recommendations

| Priority | Recommendation | Rationale |
|----------|---------------|-----------|
| **Fix Now** | Add webhook handler | Stripe requires webhooks for payment confirmation; currently no handler exists |
| **Fix Now** | Add idempotency keys | Payment creation without idempotency risks duplicate charges |
| **Improve** | Add refund flow | No refund endpoint exists; customer support requires manual DB intervention |
| **Improve** | Split `StripeAdapter.ts` | 450-line file with mixed concerns; extract webhook and refund logic |
| **Nice to Have** | Add integration tests | No route-level tests; only unit tests for `PaymentService` |
| **Nice to Have** | Add retry logic for Stripe calls | Network failures currently surface as 500 errors |

Note: The review <module> mode has been merged into module <name>. Running

module payments now includes quality assessment and prioritized recommendations

that were previously only available via review payments.

Example 2: API Design

Input: /roadmap:architect api user-notifications

Output:

## API Design: User Notifications

Based on existing patterns (RESTful, /api/v1/ prefix, JWT auth, paginated lists):

### Endpoints

| Method | Path | Auth | Request | Response |
|--------|------|------|---------|----------|
| GET | /api/v1/notifications | Required | `?page=1&size=20&unread=true` | `PagedResponse<Notification>` |
| GET | /api/v1/notifications/:id | Required | — | `Notification` |
| PATCH | /api/v1/notifications/:id/read | Required | — | `Notification` |
| POST | /api/v1/notifications/read-all | Required | — | `{ count: number }` |
| GET | /api/v1/notifications/unread-count | Required | — | `{ count: number }` |

### Response Shape (follows existing DTO pattern)

{ "id": "uuid", "type": "order_shipped", "title": "Order Shipped", "message": "Your order #123 has been shipped", "read": false, "createdAt": "2026-02-17T10:00:00Z", "metadata": { "orderId": "uuid" } }

### Consistency Notes
- Pagination follows existing `PagedResponse` pattern from catalog endpoints
- Auth uses same JWT middleware as other protected endpoints
- Error responses follow existing `{ error: string, code: string }` format
- `unread-count` endpoint supports badge display without loading full list

Example 3: Boundary Analysis

Input: /roadmap:architect boundaries

Output:

## Module Boundary Analysis

### Dependency Graph

graph LR auth --> shared catalog --> shared orders --> shared orders --> auth orders --> catalog payments --> shared payments --> auth payments --> orders notifications --> auth notifications --> orders notifications --> payments

### Violations

| Source | Target | Type | File | Recommendation |
|--------|--------|------|------|----------------|
| orders | catalog/models/Product.ts | Direct import | orders/services/OrderService.ts:12 | Use product ID, not entity |
| payments | orders/models/Order.ts | Direct import | payments/services/PaymentService.ts:8 | Use order ID, not entity |
| notifications | payments/services/PaymentService.ts | Service import | notifications/handlers/PaymentHandler.ts:3 | Use events instead |

### Module Coupling

| Module A | Module B | Coupling | Strength |
|----------|----------|----------|----------|
| orders | catalog | Direct entity import | Strong (violation) |
| payments | orders | Direct entity import | Strong (violation) |
| notifications | payments | Direct service import | Strong (violation) |
| orders | auth | ID reference only | Weak (correct) |

### Recommendations
1. **Replace entity imports with ID references** — Orders should reference
   product IDs, not Product entities. Query catalog API when needed.
2. **Introduce domain events** — Notifications should listen to
   `PaymentCompleted` events, not import PaymentService.
3. **Add module boundary tests** — Verify imports stay within boundaries.

Example 4: Pattern Conformance

Input: /roadmap:architect patterns

Output:

## Established Patterns

### 1. Layering: Route → Service → Repository

**Example:** `catalog/routes/products.ts` → `catalog/services/ProductService.ts` → `catalog/repositories/ProductRepository.ts`

✅ All modules follow this pattern consistently.

### 2. DTO Mapping

**Example:** `catalog/mappers/ProductMapper.ts`
- Entities never exposed directly in API responses
- Mapper functions in dedicated files

⚠️ `orders` module returns entities directly in 2 endpoints.

### 3. Error Handling

**Example:** `shared/middleware/errorHandler.ts`
- Global error handler catches all exceptions
- Custom error classes: `NotFoundError`, `ValidationError`, `AuthError`

✅ Consistent across all modules.

### 4. Validation

**Example:** `catalog/validators/createProduct.ts`
- Zod schemas for request validation
- Validated in route middleware

⚠️ `payments` module uses manual validation instead of Zod.

### 5. Testing

**Example:** `catalog/__tests__/ProductService.test.ts`
- Unit tests for services (mocked repositories)
- Integration tests for routes (supertest)

⚠️ `payments` module has no integration tests.

Example 5: Frontend Architecture

Input: /roadmap:architect frontend search

Output:

## Frontend Architecture: Search

### Existing Patterns
- **Framework:** Next.js 14 (App Router)
- **Components:** Feature-based organization (`components/catalog/`, `components/auth/`)
- **Data Fetching:** Server Components for initial data, client hooks for interactivity
- **State:** React Context for global state, local state for forms
- **Styling:** Tailwind CSS with design tokens in `tailwind.config.ts`

### Recommended Component Hierarchy

app/search/page.tsx (Server Component — initial results) ├── components/search/SearchBar.tsx (Client — user input) │ └── hooks/useDebounce.ts ├── components/search/SearchResults.tsx (Client — live results) │ ├── components/search/SearchResultCard.tsx │ └── components/search/SearchSkeleton.tsx └── components/search/SearchFilters.tsx (Client — faceted filters)

### Data Flow
1. Server Component loads initial results via API (SSR)
2. SearchBar captures input, debounces at 300ms
3. Client-side fetch to `/api/v1/search?q=...` for live results
4. SearchFilters modify query parameters
5. URL state for shareable searches (`/search?q=term&category=x`)

### Integration Points
- Reuse `ProductCard` from catalog for result display
- Extend existing `useApi` hook for search requests
- Use existing loading skeleton pattern from catalog

Architect Skill — Troubleshooting

Common issues and fixes for the System Architect skill.

Module Not Found

Symptom: "Could not find module 'payments'" or empty analysis.

Cause: Module name doesn't match directory structure.

Fix: 1. Check actual directory names: the skill searches for **/name/**/* 2. Use the exact directory name, not a label: module payment not module payment-processing 3. If modules are nested, use the full path: module services/payment

Wrong Tech Stack Detected

Symptom: Skill analyzes Java patterns but project is TypeScript.

Cause: Multiple build files present (e.g., package.json for tooling alongside build.gradle.kts).

Fix: 1. Create .arkhe/roadmap/architecture.md specifying the primary tech stack:

   ## Tech Stack
   - Primary: TypeScript (Node.js)
   - Framework: Next.js 14 (App Router)
   - Database: PostgreSQL with Prisma

Boundary Analysis Too Shallow

Symptom: Only finds direct imports, misses indirect coupling.

Cause: The skill checks import statements but not runtime coupling.

Fix: 1. Ask for specific coupling types: boundaries checks imports; for event-based coupling, ask explicitly 2. For database-level coupling (shared tables), use data-model mode instead 3. Describe known coupling in .arkhe/roadmap/architecture.md

Pattern Check Returns No Violations

Symptom: Says "all patterns conform" but you know there are violations.

Cause: Skill only checks patterns it can detect from file structure and imports.

Fix: 1. Describe expected patterns in .arkhe/roadmap/architecture.md:

   ## Patterns
   - All entities must extend BaseEntity
   - Services must not import from controllers
   - DTOs must live in dto/ subdirectory

2. The skill will check these explicit rules in addition to auto-detected patterns

ADRs Not Found for Decision Tracing

Symptom: Decision mode says "No ADRs found."

Cause: ADRs are in a non-standard location.

Fix: 1. Standard locations: docs/adr/, docs/decisions/, plan/decisions/ 2. Or specify in .arkhe/roadmap/documents.md:

   ## Architecture Decisions
   - `design-docs/decisions/*.md` — All ADRs

Frontend Analysis Doesn't Match Framework

Symptom: Skill suggests React patterns for a Vue project.

Cause: Framework not correctly detected or multiple frameworks present.

Fix: 1. Ensure the framework config file is at the project root (nuxt.config.ts, svelte.config.js, etc.) 2. Specify framework in .arkhe/roadmap/architecture.md

Module Analysis Takes Too Long

Symptom: module <name> seems to read excessive files.

Cause: Module has many files and the skill reads all of them for the full analysis (structure + quality assessment + recommendations).

Fix: 1. For focused analysis, ask about specific aspects: api payments or boundaries 2. Use patterns for a cross-module pattern check without deep per-module analysis

Architect Skill — Workflow

Detailed pattern analysis and mode workflows for the System Architect skill.

Context Discovery Protocol

Run the shared context discovery protocol in CONTEXT_DISCOVERY.md. Then perform architecture-specific scans from TECH_STACK_DETECTION.md § Architecture-Specific Scanning.

Mode Workflows

module <name>

1. Run context discovery 2. Glob all source files in the target module:

• **/name/**/*.{kt,java,ts,tsx,py,go,rs} (adapt to detected stack)

3. Read key files:

• Entry points (controllers, handlers, routes)
• Domain model (entities, models, types)
• Service layer (business logic)
• Repository/data access
• Tests

4. Produce module analysis:

• Directory structure tree
• Domain model table (entities, value objects, events)
• API surface (endpoints with methods)
• Dependencies (imports from other modules)
• Maturity assessment using shared scale
• Specific recommendations

5. Assess code quality:

• Complexity hotspots (large files, deeply nested logic)
• Code duplication across the module

6. Evaluate test coverage:

• Ratio of test files to source files
• Identify untested areas

7. Check API design quality:

• RESTful convention adherence
• Naming consistency
• Error handling patterns

8. Check module isolation:

• Import graph violations (imports from other modules' internals)
• Shared mutable state

9. Produce prioritized recommendations table:

• Fix Now — critical issues affecting correctness or stability
• Improve — quality issues worth addressing soon
• Nice to Have — enhancements for long-term health

api <feature>

1. Run context discovery 2. Find existing API patterns:

• Grep for controller/handler/route definitions
• Identify URL structure, versioning, auth patterns
• Check request/response DTO patterns
• Look for validation approach
• Find error handling patterns

3. Analyze the target feature area 4. Produce API design guidance:

• Endpoint table (method, path, request, response)
• Auth requirements
• Pagination approach (if list endpoints)
• Error response format
• How it fits with existing patterns

data-model <feature>

1. Run context discovery 2. Find existing data patterns:

• Read migration files or schema definitions
• Identify entity/model base classes
• Check naming conventions (snake_case, camelCase)
• Find relationship patterns (FK, embedded, JSONB)
• Look for audit fields (created_at, updated_at)

3. Analyze the target feature 4. Produce data model guidance:

• Table/collection structure
• Column types and constraints
• Relationships
• Indexes for expected queries
• Migration strategy
• Consistency with existing models

boundaries

1. Run context discovery 2. Map all modules and their public interfaces 3. Analyze coupling:

• Direct imports between modules
• Shared types/entities
• Database-level coupling (shared tables)
• Event-based communication

4. Identify violations:

• Controllers importing from other modules' internals
• Shared mutable state
• Circular dependencies

5. Produce boundary analysis:

• Dependency graph (text or Mermaid)
• Violations list with file paths
• Coupling score per module pair
• Recommendations

patterns

1. Run context discovery 2. Sample files across modules:

• 2-3 controllers/handlers
• 2-3 services
• 2-3 repositories/data access
• 2-3 entity/model definitions
• 2-3 test files

3. Extract patterns:

• Layering approach
• DTO mapping
• Error handling
• Validation
• Testing strategy

4. Produce pattern catalog with examples from actual code

decisions

1. Run context discovery 2. Find all ADRs:

• Glob docs/adr/**/*.md, docs/decisions/**/*.md, plan/decisions/**/*.md

3. For each decision:

• Extract the decision and its rationale
• Search codebase for implementation evidence
• Classify: Implemented / Partially Implemented / Not Implemented / Superseded

4. Produce traceability table

frontend <feature>

1. Run context discovery 2. Analyze existing frontend patterns:

• Component organization (atomic, feature-based, etc.)
• State management (Redux, Context, Zustand, signals, etc.)
• Data fetching (hooks, loaders, RSC, etc.)
• Styling approach (CSS modules, Tailwind, styled-components, etc.)
• Routing structure

3. Analyze the target feature 4. Produce frontend guidance:

• Component hierarchy (tree)
• Data flow diagram
• State management approach
• Responsive considerations
• Integration points with existing components

Output Templates

Module Analysis

## Module: {name}

### Structure
{directory tree}

### Domain Model
| Type | Name | Fields | Notes |
|------|------|--------|-------|

### API Surface
| Method | Path | Auth | Notes |
|--------|------|------|-------|

### Dependencies
- Depends on: {modules}
- Depended by: {modules}

### Maturity: {level}
{justification}

### Recommendations
1. {prioritized recommendations}

Boundary Analysis

## Module Boundary Analysis

### Dependency Graph
{Mermaid diagram or text representation}

### Violations
| Source | Target | Type | File | Recommendation |
|--------|--------|------|------|----------------|

### Module Coupling
| Module A | Module B | Coupling Type | Strength |
|----------|----------|---------------|----------|

---

Deep Pipeline (--deep)

When $ARGUMENTS contains --deep, execute this multi-agent pipeline with Adversarial Review. A red team agent actively tries to break the proposed architecture.

Phase 1: Context Gathering (Haiku Agent)

Launch a Haiku agent to run the full context discovery protocol plus architecture-specific scanning:

Agent prompt: "Run the context discovery protocol from CONTEXT_DISCOVERY.md, then perform architecture-specific scans from TECH_STACK_DETECTION.md. Return: project name, tech stack, detected architecture pattern, module inventory with dependencies, established patterns (layering, DTOs, events), ADR inventory, and key architectural constraints."

Provide the agent with CONTEXT_DISCOVERY.md and TECH_STACK_DETECTION.md.

Phase 2: Architecture Analysis (Sonnet Agent)

Launch a Sonnet agent to produce the architecture artifact for the requested mode.

Agent prompt: "You are a systems architect. Using the context from Phase 1, produce a {mode} artifact for {target}. Use templates from TEMPLATES.md. Every design must extend existing patterns, not introduce new ones. After your analysis, append a Builder Confessions block."

Provide the agent with:

• Phase 1 context summary
• The content of TEMPLATES.md (System Architect section)
• The architect lane rules from LANE_DISCIPLINE.md

Builder Confessions block (required at end of output):

## Builder Confessions
- **Assumption**: {what was assumed without verification}
- **Uncertainty**: {areas where confidence is low}
- **Shortcut**: {where a deeper analysis was skipped}
- **Missing data**: {what couldn't be found in the codebase}

Phase 3: Red Team Adversary (Sonnet Agent)

Launch a Sonnet agent to adversarially review the architecture proposal.

Agent prompt: "You are a penetration tester and chaos engineer. Your job is to BREAK this architecture. You are rewarded for finding problems, not for approving. Attack the proposed design across these vectors:

1. Scaling bottlenecks: What breaks at 10x, 100x traffic? 2. Single points of failure: What happens when component X goes down? 3. Boundary violations: Does this design violate existing module boundaries? 4. Data integrity risks: Can data be corrupted, lost, or inconsistent? 5. Security gaps: Auth bypass, injection, data exposure? 6. Missing error handling: What happens on timeout, invalid input, partial failure? 7. Migration risks: How does this change affect existing data and code? 8. Pattern drift: Does this introduce patterns inconsistent with the codebase?

For each finding, provide: the attack vector, the failure scenario, the severity (Critical/High/Medium/Low), and a suggested mitigation."

Provide the agent with:

• Phase 2 architecture artifact (including Builder Confessions)
• Phase 1 context summary (especially existing patterns and module inventory)

Phase 4: Confidence Scoring (Haiku Agent)

Launch a Haiku agent to score the architecture artifact informed by the red team findings:

Agent prompt: "Score each section of this architecture artifact 0-100. Read the Builder Confessions first and focus on confessed areas. Incorporate the Red Team findings: sections with unmitigated Critical/High findings get max score of 60. Use rubric: 90-100 = strong evidence, 70-89 = include with [NEEDS VALIDATION], 50-69 = appendix only, below 50 = exclude."

Provide the agent with:

• Phase 2 architecture artifact (including Confessions)
• Phase 3 red team findings

Filter: Flag sections scoring below 70.

Phase 5: Output

1. Present the architecture artifact with confidence annotations 2. Include a Red Team Findings section with severity-sorted issues 3. Include a Confession Analysis section (confessed vs unconfessed issues) 4. For each red team finding, show: the attack vector, the failure scenario, and suggested mitigation 5. Save to {output_dir}/architecture/{filename}.md (ask user to confirm)

Deep Pipeline Summary