@codihaus/claude-skills 1.0.0

package/skills/dev-arch/SKILL.md

@@ -0,0 +1,747 @@
+---
+name: dev-arch
+description: Architecture decisions and technical design for features
+version: 1.1.0
+---
+
+# /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)
+```
+
+## Workflow
+
+### Phase 0: Mode Detection
+
+Determine approach based on existing architecture:
+
+```
+1. Check: plans/scout/README.md exists?
+   Check: plans/features/{feature}/scout.md exists?
+
+2. If scout exists → Read existing patterns
+   - API style (REST, GraphQL)
+   - Database (PostgreSQL + Prisma, etc.)
+   - Frontend (React + Zustand, Vue + Pinia, etc.)
+   - Auth (JWT, session, etc.)
+   - Folder structure
+
+3. Determine mode:
+```
+
+| Condition | Mode | Approach |
+|-----------|------|----------|
+| Scout has established patterns | **Follow Mode** | Use existing patterns, no questions |
+| Scout exists but feature needs NEW tech | **Extend Mode** | Ask only about the new parts |
+| No scout / greenfield | **Design Mode** | Ask constraint questions |
+| `--new` flag provided | **Design Mode** | Force full architecture design |
+
+### Phase 1: Load Context
+
+```
+1. Read quality attributes
+   → skills/_quality-attributes.md (Architecture Level)
+
+2. Read feature requirements
+   → plans/features/{feature}/README.md
+   → plans/brd/use-cases/{feature}/*.md
+
+3. Read existing architecture
+   → plans/scout/README.md (project-level)
+   → plans/features/{feature}/scout.md (feature-level)
+
+4. Read docs-graph
+   → plans/docs-graph.json
+```
+
+### Phase 2A: Follow Mode (Existing Patterns)
+
+**When**: Scout detected established patterns.
+
+**Approach**: Use what exists, don't ask.
+
+```
+1. Extract patterns from scout:
+   - "Project uses Next.js App Router"
+   - "API is REST with /api/{resource} convention"
+   - "Database is PostgreSQL with Prisma"
+   - "Auth is JWT in httpOnly cookies"
+   - "State management: Zustand"
+
+2. Apply to new feature automatically:
+   → New endpoints follow existing REST pattern
+   → New models use Prisma conventions
+   → New components follow existing structure
+
+3. Only flag if requirements CANNOT fit existing patterns
+```
+
+**Output (minimal):**
+
+```markdown
+## Architecture: {Feature}
+
+### Approach: Follow Existing Patterns
+
+Using established project patterns from scout:
+
+| Aspect | Existing Pattern | Apply To Feature |
+|--------|------------------|------------------|
+| API | REST `/api/{resource}` | `/api/billing`, `/api/invoices` |
+| Database | Prisma + PostgreSQL | New Invoice, Payment models |
+| Auth | JWT + RBAC | Require `billing:read`, `billing:write` |
+| Frontend | React + Zustand | BillingStore, InvoiceList component |
+
+### New Elements (within existing patterns)
+- Invoice model with relations
+- Stripe webhook endpoint
+- BillingContext for subscription state
+
+### No Architecture Changes Needed
+Existing patterns fully support this feature.
+```
+
+### Phase 2B: Extend Mode (New Parts Only)
+
+**When**: Existing patterns, but feature needs something new.
+
+**Approach**: Ask ONLY about the new part.
+
+```
+1. Identify what's new:
+   - "Feature needs real-time updates" (no WebSocket in project)
+   - "Feature needs payment processing" (no payment provider yet)
+   - "Feature needs file uploads" (no storage configured)
+
+2. Ask ONLY about the gap:
+```
+
+**Example - Need payment provider:**
+
+```markdown
+**New Requirement**: This feature needs payment processing.
+Your project doesn't have a payment provider configured.
+
+**Options:**
+| Option | Pros | Cons |
+|--------|------|------|
+| A: Stripe (Recommended) | Most popular, good docs | 2.9% + 30¢ fees |
+| B: Paddle | Handles taxes/VAT | Higher fees, less flexible |
+| C: LemonSqueezy | Simple, handles taxes | Newer, less features |
+
+**Which payment provider?**
+```
+
+**Only ask what's truly new. Everything else follows existing patterns.**
+
+### Phase 2C: Design Mode (Greenfield)
+
+**When**: No existing patterns OR `--new` flag.
+
+**Approach**: Ask constraint questions, present options.
+
+**Q1: Project Context**
+- New project (no code yet)
+- Existing project, but new architecture area
+- Complete rebuild
+
+**Q2: Team & Deployment**
+- Solo / Small VPS → Recommend simple stack
+- Small team / Managed cloud → Recommend proven patterns
+- Larger team / Full cloud → More options available
+
+**Q3: Key Constraints** (multi-select)
+- Must use specific tech (specify)
+- Limited budget/resources
+- Tight timeline
+- Compliance requirements
+- None
+
+**Then present options based on constraints:**
+
+```markdown
+## Architecture Options
+
+Based on: Small team, Vercel deployment, tight timeline
+
+### Recommended Stack
+
+| Layer | Choice | Why |
+|-------|--------|-----|
+| Framework | Next.js | You're on Vercel, natural fit |
+| Database | PostgreSQL + Prisma | Reliable, good DX |
+| Auth | NextAuth.js | Integrates well, handles OAuth |
+| State | Zustand | Simple, minimal boilerplate |
+
+### Alternatives Considered
+
+| Alternative | Why Not |
+|-------------|---------|
+| GraphQL | Adds complexity, REST sufficient for your UCs |
+| MongoDB | Team knows SQL, PostgreSQL better fit |
+| Redux | Overkill for this project size |
+
+**Proceed with recommended stack?**
+- Yes, use recommended
+- Modify (specify what to change)
+- Show me other options
+```
+
+### Phase 3: Gap Analysis
+
+For any mode, identify gaps between requirements and architecture:
+
+```markdown
+## Gap Analysis
+
+### Requirements vs Capabilities
+
+| Requirement | Current Support | Gap | Action |
+|-------------|-----------------|-----|--------|
+| User login | ✓ JWT exists | None | Use existing |
+| Payments | ✗ None | Need provider | Asked user → Stripe |
+| Real-time | ✗ None | Need WebSocket | Add Pusher/Ably |
+| File upload | ✓ S3 configured | None | Use existing |
+
+### Gaps Requiring Decisions
+1. Payment provider → User chose Stripe
+2. Real-time → Recommend Pusher (simple, managed)
+```
+
+### Phase 4: Make Decisions (Only for Gaps)
+
+Only create ADRs for NEW decisions, not for following existing patterns.
+
+For each NEW architecture decision:
+
+```markdown
+## Decision: {Topic}
+
+### Context
+{Why this decision is needed}
+
+### Options Considered
+
+**Option A: {Name}**
+- Pros: {benefits}
+- Cons: {drawbacks}
+- Effort: {Low/Medium/High}
+
+**Option B: {Name}**
+- Pros: {benefits}
+- Cons: {drawbacks}
+- Effort: {Low/Medium/High}
+
+### Decision
+{Chosen option and rationale}
+
+### Consequences
+- {What this means for implementation}
+- {Trade-offs accepted}
+```
+
+**Key decisions to make:**
+
+| Category | Decisions |
+|----------|-----------|
+| API | REST vs GraphQL, versioning, conventions |
+| Data | Database choice, ORM, schema design |
+| Auth | Strategy (JWT/session/OAuth), permission model |
+| Frontend | State management, component structure |
+| Integration | How services connect, event-driven? |
+| Infrastructure | Caching, queues, external services |
+
+### Phase 4: Apply Quality Attributes
+
+Run through `_quality-attributes.md` Architecture Level checklists:
+
+```markdown
+## Quality Assessment
+
+### Scalability
+- [x] Stateless API design
+- [x] Database can handle 10x load
+- [ ] Caching strategy defined → Need to decide
+
+### Maintainability
+- [x] Clear module boundaries
+- [x] Consistent folder structure
+- [x] Dependencies abstracted
+
+### Security
+- [x] Auth strategy chosen (JWT)
+- [x] Permission model (RBAC)
+- [ ] Data encryption → Need for PII
+
+### Reliability
+- [ ] Single points of failure → Database needs replica
+- [x] Graceful degradation planned
+
+### Performance
+- [x] Latency targets defined (P95 < 200ms)
+- [ ] CDN for static assets → TODO
+
+### Testability
+- [x] Dependencies injectable
+- [x] Test strategy defined
+```
+
+### Phase 5: Generate Architecture Document
+
+Create `plans/features/{feature}/architecture.md`:
+
+```markdown
+# {Feature} Architecture
+
+> **Feature**: [[feature-{name}]]
+> **Created**: {date}
+> **Status**: Draft | Approved
+
+## Overview
+
+{High-level architecture description}
+
+## Architecture Diagram
+
+```mermaid
+flowchart TB
+    subgraph Frontend
+        UI[React App]
+        State[Zustand Store]
+    end
+
+    subgraph Backend
+        API[Next.js API]
+        Auth[Auth Middleware]
+        DB[(PostgreSQL)]
+    end
+
+    subgraph External
+        Payment[Stripe]
+        Email[SendGrid]
+    end
+
+    UI --> API
+    API --> Auth
+    API --> DB
+    API --> Payment
+    API --> Email
+```
+
+## Key Decisions
+
+| Decision | Choice | Rationale |
+|----------|--------|-----------|
+| API Style | REST | Matches existing patterns, simpler |
+| Auth | JWT + httpOnly cookies | Secure, stateless |
+| State | Zustand | Lightweight, already in project |
+| Database | PostgreSQL | Existing, supports needed features |
+
+## Patterns to Follow
+
+### API Patterns
+- RESTful endpoints: `/{resource}` and `/{resource}/:id`
+- Response format: `{ data, error, meta }`
+- Error format: `{ error: { code, message, details } }`
+
+### Data Patterns
+- Use Prisma ORM
+- Soft deletes with `deletedAt`
+- Timestamps on all tables
+
+### Component Patterns
+- Feature folders: `src/features/{feature}/`
+- Shared components: `src/components/ui/`
+- API clients: `src/lib/api/{feature}.ts`
+
+### Auth Patterns
+- Middleware checks on protected routes
+- Role-based permissions
+- Token refresh on activity
+
+## Quality Checklist
+
+### Scalability
+- [x] Stateless API
+- [x] Pagination on lists
+- [x] Caching strategy: Redis for sessions
+- [x] Background jobs: Queue for emails
+
+### Security
+- [x] Input validation: Zod schemas
+- [x] Auth: JWT in httpOnly cookie
+- [x] Permissions: RBAC with roles table
+
+### Performance
+- [x] Database indexes defined
+- [x] N+1 queries prevented with includes
+- [x] CDN for static assets
+
+## ADRs
+
+| ID | Title | Status |
+|----|-------|--------|
+| [ADR-001](./adrs/ADR-001-api-style.md) | REST vs GraphQL | Accepted |
+| [ADR-002](./adrs/ADR-002-auth-strategy.md) | Authentication Strategy | Accepted |
+
+## Risks & Mitigations
+
+| Risk | Impact | Mitigation |
+|------|--------|------------|
+| Stripe rate limits | Medium | Implement queue for batch operations |
+| Database growth | Low | Archival strategy after 1 year |
+
+## Open Questions
+
+- [ ] {Any unresolved questions}
+
+## Next Steps
+
+1. Review with team
+2. Create specs with `/dev-specs`
+3. Implement with `/dev-coding`
+```
+
+### Phase 6: Generate ADRs (if significant decisions)
+
+Create `plans/features/{feature}/adrs/ADR-{NNN}-{slug}.md`:
+
+```markdown
+# ADR-{NNN}: {Title}
+
+> **Status**: Proposed | Accepted | Deprecated | Superseded
+> **Date**: {date}
+> **Decision Makers**: {who}
+
+## Context
+
+{What is the issue that we're seeing that motivates this decision?}
+
+## Decision
+
+{What is the change that we're proposing and/or doing?}
+
+## Options Considered
+
+### Option 1: {Name}
+{Description}
+- **Pros**: {list}
+- **Cons**: {list}
+
+### Option 2: {Name}
+{Description}
+- **Pros**: {list}
+- **Cons**: {list}
+
+## Consequences
+
+### Positive
+- {benefit 1}
+- {benefit 2}
+
+### Negative
+- {drawback 1}
+- {drawback 2}
+
+### Neutral
+- {observation}
+
+## Related Decisions
+
+- {Link to related ADRs}
+```
+
+## Decision Categories
+
+### API Design
+
+| Question | Options |
+|----------|---------|
+| Style | REST, GraphQL, tRPC, gRPC |
+| Versioning | URL path, header, none |
+| Auth header | Bearer token, cookie, API key |
+| Response format | JSON:API, custom, none |
+
+### Database
+
+| Question | Options |
+|----------|---------|
+| Type | PostgreSQL, MySQL, MongoDB, SQLite |
+| ORM | Prisma, TypeORM, Drizzle, raw SQL |
+| Migrations | ORM-managed, manual, none |
+| Soft deletes | Yes (deletedAt), no |
+
+### Frontend State
+
+| Question | Options |
+|----------|---------|
+| Global state | Redux, Zustand, Jotai, Context |
+| Server state | React Query, SWR, manual |
+| Forms | React Hook Form, Formik, native |
+
+### Authentication
+
+| Question | Options |
+|----------|---------|
+| Strategy | JWT, session, OAuth only |
+| Token storage | httpOnly cookie, localStorage, memory |
+| Refresh | Sliding window, explicit refresh |
+| Permissions | RBAC, ABAC, simple roles |
+
+### Infrastructure
+
+| Question | Options |
+|----------|---------|
+| Caching | Redis, in-memory, CDN |
+| Queue | Redis/BullMQ, SQS, RabbitMQ |
+| File storage | S3, local, Cloudinary |
+| Email | SendGrid, SES, SMTP |
+
+## 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 |
+
+### Context7 for Architecture Research
+
+When making architecture decisions, use Context7 to look up best practices:
+
+```
+1. Resolve library ID
+   → mcp__context7__resolve-library-id({
+       libraryName: "prisma",
+       query: "database schema design patterns"
+     })
+
+2. Query documentation
+   → mcp__context7__query-docs({
+       libraryId: "/prisma/prisma",
+       query: "relations and foreign keys best practices"
+     })
+```
+
+**Use for:**
+- ORM patterns (Prisma, TypeORM, Drizzle)
+- Framework architecture (Next.js, NestJS)
+- Auth library patterns (NextAuth, Lucia)
+- API design (REST, GraphQL, tRPC)
+
+## 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
+
+### Example 1: Follow Mode (Most Common)
+
+```
+User: /dev-arch notifications
+
+1. Mode detection
+   → Scout exists with established patterns
+   → Mode: FOLLOW
+
+2. Load context
+   → Project uses: Next.js, REST API, PostgreSQL, Prisma
+   → Feature needs: notification preferences, email sending
+
+3. Apply existing patterns (NO QUESTIONS)
+   → API: POST /api/notifications, GET /api/notifications
+   → Database: Notification model with Prisma
+   → Frontend: NotificationSettings component
+
+4. Check for gaps
+   → Email sending needed
+   → Project already has SendGrid configured ✓
+   → No gaps!
+
+5. Output (minimal)
+   "Using existing patterns. No architecture changes needed.
+    - New Notification model
+    - New API endpoints following REST convention
+    - Uses existing SendGrid for emails"
+
+No ADRs created. No questions asked.
+```
+
+### Example 2: Extend Mode (New Part Only)
+
+```
+User: /dev-arch billing
+
+1. Mode detection
+   → Scout exists with established patterns
+   → Mode: FOLLOW initially...
+
+2. Load context
+   → Project uses: Next.js, REST, PostgreSQL
+   → Feature needs: payment processing, subscriptions
+
+3. Check for gaps
+   → Payment processing needed
+   → Project has NO payment provider ← Gap found!
+   → Mode switches to: EXTEND
+
+4. Ask ONLY about the gap
+   "Feature needs payment processing. No provider configured.
+    Options:
+    A: Stripe (Recommended) - Popular, good docs
+    B: Paddle - Handles taxes
+    C: LemonSqueezy - Simpler
+
+    Which provider?"
+
+   → User: "Stripe"
+
+5. Everything else follows existing patterns
+   → API: REST endpoints for billing
+   → Database: Prisma models
+   → Frontend: Existing component patterns
+
+6. Output
+   → architecture.md (documents Stripe choice)
+   → ADR-001-payment-provider.md (only for the NEW decision)
+
+   "Stripe selected. All other patterns follow existing project architecture."
+```
+
+### Example 3: Design Mode (Greenfield)
+
+```
+User: /dev-arch auth --new
+
+1. Mode detection
+   → --new flag provided
+   → Mode: DESIGN
+
+2. Ask constraint questions
+   Q1: "Team size?"
+   → Small team (3 devs)
+
+   Q2: "Deployment target?"
+   → Vercel
+
+   Q3: "Constraints?"
+   → Tight timeline
+
+3. Present options based on constraints
+   "Based on: Small team, Vercel, tight timeline
+
+    Recommended:
+    - NextAuth.js (simple, works with Vercel)
+    - JWT in httpOnly cookies
+    - RBAC for permissions
+
+    Alternatives considered:
+    - Auth0: Good but adds external dependency
+    - Custom JWT: More work, tight timeline
+
+    Proceed with NextAuth.js?"
+
+   → User: "Yes"
+
+4. Generate full architecture
+   → architecture.md (complete auth design)
+   → ADR-001-auth-strategy.md
+   → ADR-002-permission-model.md
+```
+
+## Summary
+
+| 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.**