@codihaus/claude-skills 1.6.7 → 1.6.8

package/skills/dev-arch/SKILL.md

@@ -73,447 +73,164 @@ plans/features/{feature}/
 └── specs/                   # From /dev-specs (uses architecture.md)
 ```
 
-## Workflow
+## Expected Outcome
 
-### Phase 0: Mode Detection
+Architecture decisions for what's **NEW**. Follow existing for what's **KNOWN**.
 
-Determine approach based on existing architecture:
+**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`
 
-```
-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)
+## Success Criteria
 
-**When**: Existing patterns, but feature needs something new.
+- 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
 
-**Approach**: Ask ONLY about the new part.
+## Modes
 
-```
-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)
+Auto-detect based on scout:
 
-2. Ask ONLY about the gap:
-```
+| 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 |
 
-**Example - Need payment provider:**
+## Context Sources
 
-```markdown
-**New Requirement**: This feature needs payment processing.
-Your project doesn't have a payment provider configured.
+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
 
-**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 |
+## Follow Mode
 
-**Which payment provider?**
-```
+**When:** Scout shows established patterns
 
-**Only ask what's truly new. Everything else follows existing patterns.**
+**Approach:** Extract and apply automatically
 
-### Phase 2C: Design Mode (Greenfield)
+**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
 
-**When**: No existing patterns OR `--new` flag.
+**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
 
-**Approach**: Ask constraint questions, present options.
+**Output:** Minimal architecture.md noting patterns applied
 
-**Q1: Project Context**
-- New project (no code yet)
-- Existing project, but new architecture area
-- Complete rebuild
+## Extend Mode
 
-**Q2: Team & Deployment**
-- Solo / Small VPS → Recommend simple stack
-- Small team / Managed cloud → Recommend proven patterns
-- Larger team / Full cloud → More options available
+**When:** Existing patterns but feature needs something new
 
-**Q3: Key Constraints** (multi-select)
-- Must use specific tech (specify)
-- Limited budget/resources
-- Tight timeline
-- Compliance requirements
-- None
+**Approach:** Ask ONLY about the gap
 
-**Then present options based on constraints:**
+**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)
 
-```markdown
-## Architecture Options
+**Present options for gap only:**
+- Recommend based on constraints
+- Pros/cons of each option
+- Ask user to choose
 
-Based on: Small team, Vercel deployment, tight timeline
+**Everything else:** Follow existing patterns
 
-### Recommended Stack
+## Design Mode
 
-| 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 |
+**When:** No existing patterns OR `--new` flag
 
-### Alternatives Considered
+**Approach:** Ask constraint questions, present options
 
-| Alternative | Why Not |
-|-------------|---------|
-| GraphQL | Adds complexity, REST sufficient for your UCs |
-| MongoDB | Team knows SQL, PostgreSQL better fit |
-| Redux | Overkill for this project size |
+**Ask about:**
+- Project context (new/existing/rebuild)
+- Team & deployment (solo/small/large, VPS/cloud)
+- Key constraints (tech, budget, timeline, compliance)
 
-**Proceed with recommended stack?**
-- Yes, use recommended
-- Modify (specify what to change)
-- Show me other options
-```
+**Present recommendations based on constraints:**
+- Recommended stack with rationale
+- Alternatives considered (why not)
+- Ask user to approve or modify
 
-### 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)
+For any mode, identify gaps:
 
-Only create ADRs for NEW decisions, not for following existing patterns.
+**Compare:**
+- Requirements (what feature needs)
+- Current capabilities (what exists)
+- Gaps (what's missing)
+- Actions (decisions needed)
 
-For each NEW architecture decision:
+**Output:**
+- Requirements vs Capabilities table
+- Gaps requiring decisions
 
-```markdown
-## Decision: {Topic}
+## Decision Making
 
-### Context
-{Why this decision is needed}
+**Only create ADRs for NEW decisions**, not for following existing patterns.
 
-### Options Considered
+**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)
 
-**Option A: {Name}**
-- Pros: {benefits}
-- Cons: {drawbacks}
-- Effort: {Low/Medium/High}
+**Each decision includes:**
+- Context (why needed)
+- Options considered (pros/cons/effort)
+- Decision (chosen option + rationale)
+- Consequences (trade-offs accepted)
 
-**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}
-```
+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