swe-workflow-skills 0.1.0

package/skills/effort-estimation/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: effort-estimation
+description: "Estimate engineering effort with agile techniques — story points, t-shirt sizing, three-point estimation, capacity planning. Triggers: estimate this, how long will this take, story points, t-shirt sizing, effort estimation, capacity planning, sprint planning, budget estimate, forecast, velocity, when will this be done."
+model: haiku
+allowed-tools: Read, Grep, Glob, Write, Edit
+---
+
+# Effort Estimation
+
+Produce honest, useful estimates that help teams plan without creating false precision. Estimation in agile is about making informed decisions under uncertainty, not predicting the future exactly.
+
+## Core Philosophy
+
+**Estimates are forecasts, not commitments.** They communicate "based on what we know today, here's our best guess at the range of effort." They should always include uncertainty ranges, and they should improve as you learn more.
+
+## Workflow
+
+### Step 1: Ensure Tasks Are Defined
+
+You can't estimate undefined work. Before estimating, ensure:
+
+- Tasks are broken down (use `feature-planning` if not)
+- Acceptance criteria exist for each task
+- Technical approach is at least sketched (spikes completed for unknowns)
+
+If the work is too vague to estimate, say so. "I can't estimate this until we do a spike" is a valid and responsible answer.
+
+### Step 2: Choose the Estimation Method
+
+| Method | Best For | Precision | Speed |
+|--------|----------|-----------|-------|
+| **T-shirt sizing** | Roadmap planning, early-stage sizing, large backlogs | Low (ranges) | Very fast |
+| **Story points** (Fibonacci) | Sprint planning, velocity tracking, mature teams | Medium (relative) | Moderate |
+| **Three-point estimation** | High-stakes estimates, budget requests, uncertain work | High (ranges with confidence) | Slow |
+| **Time-based** | Well-understood tasks with low uncertainty | High (hours/days) | Moderate |
+
+**Default recommendation**: T-shirt sizing for roadmap/quarter planning, story points for sprint planning. Three-point for budget requests and stakeholder communication.
+
+### Step 3: Apply the Method
+
+See [references/estimation-methods.md](references/estimation-methods.md) for detailed guidance on each method.
+
+**Key principles across all methods:**
+
+1. **Estimate as a team**, not individually. The person most and least familiar with the area should both contribute — the gap reveals hidden complexity.
+2. **Estimate relative to known work**, not in absolute terms. "This is about twice as hard as that login feature we built" is more accurate than "this will take 3 days."
+3. **Include uncertainty explicitly.** "3-5 days" is more honest than "4 days."
+4. **Estimate the work, not the worker.** Story points measure the task's size, not who's doing it.
+5. **Re-estimate when you learn more.** Initial estimates are educated guesses. Update them as spikes complete and requirements clarify.
+
+### Step 4: Handle Budget and Timeline Requests
+
+When stakeholders need dates or dollars, translate estimates thoughtfully:
+
+**From story points to time:**
+```
+Estimated story points for the project: 85
+Team velocity: ~30 points per sprint (2-week sprints)
+Sprints needed: 85 / 30 = ~3 sprints = 6 weeks
+
+Add buffer for unknowns (20-30%): 7-8 weeks
+Communicate as range: "6-8 weeks with the current team"
+```
+
+**From effort to cost:**
+```
+Effort estimate: 12-16 person-weeks
+Team loaded cost: $X per person-week
+Total: 12 × $X to 16 × $X
+Communicate as range: "$A - $B"
+```
+
+**Always provide ranges, never single numbers.** A single number becomes a commitment; a range communicates confidence.
+
+### Step 5: Track and Calibrate
+
+Estimates improve with feedback. After each sprint or project:
+
+- Compare estimated vs actual effort
+- Identify systematic patterns (always overestimate UI? Always underestimate integrations?)
+- Adjust team velocity based on recent data (use the last 3-5 sprints, not all-time average)
+
+## Common Estimation Traps
+
+- **Anchoring**: The first number said influences everyone else. Use blind estimation (planning poker, simultaneous reveal).
+- **Planning fallacy**: People consistently underestimate. Use historical data to calibrate.
+- **Scope creep blindness**: Estimate the work as defined, then add buffer for scope growth — it always grows.
+- **Hero planning**: Estimating based on the best-case scenario with the best developer with zero interruptions. Estimate for a typical day with meetings and context switches.
+- **Precision theater**: Saying "47 hours" when you mean "roughly a week." False precision erodes trust faster than honest ranges.
+
+## Principles Applied
+
+- **KISS**: Use the simplest estimation method appropriate. T-shirt sizing is fine for most roadmap decisions.
+- **Honesty over optimism**: A realistic estimate that disappoints a stakeholder is better than an optimistic estimate that misses a deadline.
+- **YAGNI**: Don't estimate items far in the future with precision. Estimate near-term work in detail, far-term work in ranges.

package/skills/effort-estimation/evals/evals.json

@@ -0,0 +1,32 @@
+{
+  "skill_name": "effort-estimation",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "My PM asked me 'how long will it take to build a notification system?' I have a feature plan with 8 tasks. Help me estimate and communicate this to the PM.",
+      "expected_output": "Should walk through estimating each task, choose appropriate method, calculate total with buffer, and produce stakeholder-friendly communication with ranges.",
+      "assertions": [
+        "Chooses an appropriate estimation method for the context",
+        "Estimates each task individually, not the project as a single unit",
+        "Produces a range, not a single number",
+        "Includes buffer for unknowns (20-30%)",
+        "Communicates in stakeholder-friendly language (weeks, not story points)",
+        "States assumptions explicitly",
+        "Does NOT promise a specific date without qualifying it"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Our VP wants a budget estimate for a 6-month data platform rebuild. We're in early discovery and a lot is still unknown. How do I estimate this responsibly?",
+      "expected_output": "Should recommend three-point estimation for high-uncertainty work, produce wide ranges, clearly state assumptions and unknowns, and suggest narrowing the estimate through phased discovery.",
+      "assertions": [
+        "Recommends three-point estimation due to high uncertainty",
+        "Produces wide initial ranges (appropriate for early discovery)",
+        "Suggests a phased approach: estimate phase 1 tightly, phases 2-3 loosely",
+        "Clearly states which assumptions drive the estimate",
+        "Recommends a technical spike before committing to precise numbers",
+        "Does NOT produce a precise single-number estimate for 6 months of unknown work"
+      ]
+    }
+  ]
+}

package/skills/effort-estimation/references/estimation-methods.md

@@ -0,0 +1,154 @@
+# Estimation Methods
+
+## Contents
+- T-shirt sizing guide
+- Story points with Fibonacci
+- Three-point estimation
+- Velocity and capacity planning
+- Communicating estimates to stakeholders
+
+## T-Shirt Sizing
+
+Best for: roadmap planning, early-stage scoping, large backlogs (50+ items).
+
+| Size | Relative Effort | Typical Duration | Uncertainty |
+|------|----------------|-----------------|-------------|
+| XS | Trivial | Hours | Very low |
+| S | Simple, well-understood | 1-2 days | Low |
+| M | Moderate complexity | 3-5 days | Medium |
+| L | Complex, some unknowns | 1-2 weeks | High |
+| XL | Very complex, significant unknowns | 2-4 weeks | Very high — break it down |
+
+**Process:**
+1. Pick 3-5 reference items the team already understands well. Place them on the scale.
+2. For each new item, discuss briefly: "Is this bigger or smaller than reference X?"
+3. Place it on the scale. If there's disagreement, discuss briefly and converge.
+4. Any XL item should be broken into smaller items before sprint planning.
+
+**Converting to time for roadmap purposes:**
+```
+XS: 0.5 days    S: 2 days    M: 5 days    L: 10 days    XL: 20 days
+Sum all items × buffer (1.3-1.5) = rough project duration
+```
+
+## Story Points (Fibonacci)
+
+Best for: sprint planning, velocity tracking with mature agile teams.
+
+Scale: 1, 2, 3, 5, 8, 13, 21
+
+| Points | Meaning |
+|--------|---------|
+| 1 | Trivial — clear, no unknowns, done in minutes to an hour |
+| 2 | Small — straightforward, few unknowns |
+| 3 | Small-medium — some complexity or one minor unknown |
+| 5 | Medium — moderate complexity, some unknowns |
+| 8 | Large — significant complexity, multiple unknowns |
+| 13 | Very large — high complexity, should consider splitting |
+| 21 | Epic — too large for a single sprint, must be broken down |
+
+**Planning Poker process:**
+1. Product owner describes the story and acceptance criteria
+2. Each team member privately selects a card (Fibonacci number)
+3. All cards revealed simultaneously
+4. If consensus: record and move on
+5. If divergence: highest and lowest explain their reasoning, then re-vote
+6. Converge within 2 rounds (don't debate endlessly)
+
+**Calculating velocity:**
+```
+Sprint 1: 28 points completed
+Sprint 2: 32 points completed
+Sprint 3: 25 points completed
+Sprint 4: 30 points completed
+
+Average velocity: (28 + 32 + 25 + 30) / 4 = 28.75 ≈ 29 points/sprint
+Use the last 3-5 sprints (not all-time) for more accurate forecasting
+```
+
+## Three-Point Estimation
+
+Best for: budget estimates, high-stakes commitments, uncertain work.
+
+For each task, estimate three values:
+- **O** (Optimistic): Everything goes right, no surprises
+- **M** (Most Likely): Normal conditions, typical obstacles
+- **P** (Pessimistic): Significant problems but not catastrophic
+
+**PERT formula:**
+```
+Expected = (O + 4M + P) / 6
+Standard Deviation = (P - O) / 6
+```
+
+**Example:**
+```
+Task: Integrate payment provider
+  O: 3 days (API is clean, docs are accurate)
+  M: 7 days (some undocumented behavior, 1-2 issues)
+  P: 15 days (API issues, need vendor support, edge cases)
+
+  Expected: (3 + 4×7 + 15) / 6 = 46/6 = 7.7 days
+  StdDev: (15 - 3) / 6 = 2 days
+
+  68% confidence: 5.7 - 9.7 days
+  95% confidence: 3.7 - 11.7 days
+
+  Communicate: "Roughly 8 days, could range from 6-12."
+```
+
+**For full project estimates**, sum the expected values and sum the variances (not standard deviations):
+```
+Total Expected = sum of all task expected values
+Total Variance = sum of all task variances
+Total StdDev = sqrt(Total Variance)
+```
+
+## Velocity and Capacity Planning
+
+### Sprint capacity
+```
+Team size: 5 engineers
+Sprint length: 2 weeks (10 working days)
+Availability: 80% (account for meetings, PTO, on-call, interruptions)
+
+Gross capacity: 5 × 10 = 50 person-days
+Net capacity: 50 × 0.8 = 40 person-days
+
+If average velocity is 29 story points per sprint:
+  1 story point ≈ 40/29 ≈ 1.4 person-days (for rough conversion only)
+```
+
+### Forecasting project completion
+```
+Total remaining story points: 120
+Average velocity: 29 points/sprint
+Sprints remaining: 120 / 29 = 4.1 sprints
+
+Optimistic (velocity = 35): 120 / 35 = 3.4 sprints
+Pessimistic (velocity = 23): 120 / 23 = 5.2 sprints
+
+Communicate: "4-5 sprints (8-10 weeks), assuming current team and no major scope changes"
+```
+
+## Communicating Estimates to Stakeholders
+
+### Do:
+- Provide ranges, not single numbers
+- State assumptions explicitly ("assumes the team of 4, no major scope changes")
+- Update estimates when assumptions change
+- Use visual aids (burndown charts, probability cones)
+- Distinguish between effort (person-days) and duration (calendar time)
+
+### Don't:
+- Convert story points to hours for external communication (this invites micromanagement)
+- Present estimates as commitments
+- Pad estimates secretly (be transparent about buffers)
+- Estimate work you don't understand (do a spike first)
+- Let someone else's deadline become your estimate ("we need it by Friday" is not an estimate)
+
+### Useful phrasing:
+- "Based on what we know today, this is roughly X-Y weeks of work for a team of N."
+- "We'll have a more precise estimate after the technical spike in sprint 1."
+- "The main uncertainty is [specific unknown]. If that goes smoothly, it's X weeks. If not, it could be Y weeks."
+- "We can commit to delivering [core scope] by [date]. The [stretch goals] depend on how the first sprint goes."

package/skills/feature-planning/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: feature-planning
+description: "Break features into well-scoped tasks with acceptance criteria, risk assessment, and dependency mapping. Triggers: plan this, break this down, scope this feature, create tasks for, sprint planning, how should I implement this feature, user stories, acceptance criteria, dependency mapping, feature breakdown."
+model: sonnet
+allowed-tools: Read, Grep, Glob, Write, Edit
+---
+
+# Feature Planning
+
+Guide the user through transforming a feature idea or requirement into a structured, actionable implementation plan. The goal is a plan that a developer (or Claude Code) can pick up and execute with minimal ambiguity.
+
+## Workflow
+
+### Step 1: Understand the Feature
+
+Ask clarifying questions to close knowledge gaps. Focus on:
+
+- **What problem does this solve?** (user pain, business value)
+- **Who is the user?** (persona, role, access level)
+- **What exists today?** (current behavior, workarounds)
+- **What are the constraints?** (timeline, tech stack, backwards compatibility)
+- **What's out of scope?** (explicitly define boundaries)
+
+If the user provides a vague request like "add authentication", ask about specifics: what auth methods, what protected resources, what user roles. Don't proceed with assumptions.
+
+### Step 2: Define Acceptance Criteria
+
+For each user-facing behavior, write acceptance criteria using the Given/When/Then format:
+
+```
+Given [precondition]
+When [action]
+Then [expected outcome]
+```
+
+Aim for 3-7 acceptance criteria per feature. Each criterion should be independently testable.
+
+### Step 3: Break Down into Tasks
+
+Decompose the feature into implementation tasks. Each task should:
+
+- Be completable in one focused session (roughly 1-4 hours of work)
+- Have a single clear deliverable (a file, a test, a migration, etc.)
+- Follow dependency order (what must exist before this task can start)
+- Be independently verifiable
+
+Use this structure for each task — see [templates/task.md](templates/task.md).
+
+### Step 4: Map Dependencies
+
+Identify and visualize dependencies between tasks:
+
+- **Hard dependencies**: Task B literally cannot start until Task A is done
+- **Soft dependencies**: Task B benefits from Task A but could start in parallel
+- **External dependencies**: Waiting on APIs, design assets, or decisions
+
+Present dependencies as an ordered list or ASCII diagram showing the critical path.
+
+### Step 5: Identify Risks and Open Questions
+
+Flag anything that could derail the plan:
+
+- **Technical risks**: Unproven technology, complex integration, performance concerns
+- **Scope risks**: Feature creep indicators, ambiguous requirements
+- **Dependency risks**: External team blockers, API availability
+
+For each risk, suggest a mitigation strategy or a spike task to reduce uncertainty.
+
+### Step 6: Produce the Plan
+
+Output the complete plan using the template at [templates/plan.md](templates/plan.md). Save it as a markdown file in the project (e.g., `docs/plans/feature-name.md`).
+
+## Principles Applied
+
+- **YAGNI**: Only plan what's needed now. Flag nice-to-haves separately.
+- **KISS**: Prefer the simplest approach that meets acceptance criteria.
+- **Functional Independence**: Each task should touch a single concern when possible.
+- **Testability**: Every task should specify how to verify it's done.
+
+## When to Go Deeper
+
+If the feature involves architectural decisions (new services, database changes, API design), suggest using the `architecture-design` skill before finalizing the plan.
+
+If the feature requires data model changes, suggest using the `data-modeling` skill for that portion.

package/skills/feature-planning/evals/evals.json

@@ -0,0 +1,44 @@
+{
+  "skill_name": "feature-planning",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "I need to add a notification system to our app. Users should get email and in-app notifications when someone comments on their posts. We're using a Node.js/Express backend with PostgreSQL and a React frontend. Can you help me plan this out?",
+      "expected_output": "A structured plan with clarifying questions asked first, acceptance criteria in Given/When/Then format, 5-10 granular tasks with dependencies, risk identification, and a saved markdown plan file.",
+      "assertions": [
+        "Asks clarifying questions before producing the plan",
+        "Includes acceptance criteria in Given/When/Then format",
+        "Tasks are granular (1-4 hours each) with clear deliverables",
+        "Dependency map is present showing task ordering",
+        "Risks section identifies at least 2 technical risks",
+        "Out of scope section explicitly excludes something",
+        "Saves the plan as a markdown file"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "plan adding dark mode to our vue app",
+      "expected_output": "Should ask clarifying questions first (CSS variables vs theme library? System preference detection? Per-component or global? Persistence?), then produce a structured plan after getting answers.",
+      "assertions": [
+        "Does not immediately produce a plan from this vague request",
+        "Asks at least 3 clarifying questions",
+        "Applies YAGNI by not over-engineering the approach",
+        "Tasks include both implementation and testing",
+        "Acceptance criteria are independently testable"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "We need to migrate our REST API to GraphQL. It's a Django backend serving a React Native mobile app and a Next.js web app. We have about 40 endpoints. The CEO wants it done in 3 sprints. Help me plan this.",
+      "expected_output": "Should flag the complexity and risks, suggest an incremental migration strategy rather than big-bang, break into phased milestones, and identify the critical path.",
+      "assertions": [
+        "Flags the risk of a full rewrite in 3 sprints",
+        "Suggests incremental or parallel migration strategy",
+        "Recommends architectural decisions be made first",
+        "References the architecture-design skill for ADR",
+        "Identifies external dependencies (mobile app release cycle)",
+        "Creates phased milestones, not just flat task list"
+      ]
+    }
+  ]
+}

package/skills/feature-planning/templates/plan.md

@@ -0,0 +1,55 @@
+# Feature Plan Template
+
+```markdown
+# Feature: [Feature Name]
+
+**Date**: [YYYY-MM-DD]
+**Author**: [Name]
+**Status**: Draft | In Review | Approved
+
+## Summary
+[2-3 sentences: what this feature does and why it matters]
+
+## Problem Statement
+[What user pain or business need does this address?]
+
+## Scope
+
+### In Scope
+- [Bullet list of what's included]
+
+### Out of Scope
+- [Bullet list of what's explicitly excluded]
+
+## Acceptance Criteria
+
+1. Given [precondition], When [action], Then [outcome]
+2. Given [precondition], When [action], Then [outcome]
+3. ...
+
+## Implementation Tasks
+
+[Ordered list of tasks using the task template]
+
+## Dependency Map
+
+```
+Task 1 (data model) ──► Task 2 (API) ──► Task 4 (UI)
+                                    └──► Task 5 (tests)
+Task 3 (config) ─────► Task 4 (UI)
+```
+
+## Risks & Mitigations
+
+| Risk | Impact | Likelihood | Mitigation |
+|------|--------|------------|------------|
+| [Risk description] | High/Med/Low | High/Med/Low | [Strategy] |
+
+## Open Questions
+- [ ] [Question that needs answering before implementation]
+
+## Related
+- Architecture Decision: [link if applicable]
+- Data Model: [link if applicable]
+- Design Mockups: [link if applicable]
+```

package/skills/feature-planning/templates/task.md

@@ -0,0 +1,26 @@
+# Task Template
+
+Use this structure for each implementation task:
+
+```markdown
+## Task [N]: [Short descriptive title]
+
+**Type**: [implementation | test | migration | spike | config | docs]
+**Estimated effort**: [S/M/L — roughly 1h / 2-3h / 4h+]
+**Depends on**: [Task numbers or "none"]
+
+### Description
+[1-2 sentences: what this task produces and why]
+
+### Deliverables
+- [ ] [Specific file or artifact]
+- [ ] [Tests passing]
+- [ ] [Other verifiable output]
+
+### Acceptance Criteria
+- [ ] [Criterion 1]
+- [ ] [Criterion 2]
+
+### Notes
+[Edge cases, gotchas, or implementation hints — only if non-obvious]
+```

package/skills/frontend-architecture/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: frontend-architecture
+description: "Design frontend architecture — React component hierarchy, state management, design tokens, data fetching, routing, error boundaries, code organization. Triggers: component architecture, state management, design system, design tokens, component library, React structure, folder structure, Zustand vs Redux, React Query, code splitting, error boundary, compound component."
+model: sonnet
+allowed-tools: Read, Grep, Glob, Write, Edit
+---
+
+# Frontend Architecture
+
+Design the technical structure of frontend applications — component hierarchy, state management, data fetching, and code organization. Good frontend architecture makes features easy to build, bugs easy to find, and the codebase easy to onboard into.
+
+## Core Principle
+
+**Colocation over separation.** Keep related things together. A component's styles, tests, types, and stories should live next to the component, not in separate `/styles`, `/tests`, `/types` directories. Separation by file type creates coupling across the filesystem; separation by feature creates independence.
+
+## Workflow
+
+### Step 1: Design the Component Hierarchy
+
+Start from the UI design (or the screen spec from `ui-ux-design`) and decompose into components:
+
+1. **Identify the visual boundaries** — Draw boxes around distinct UI regions
+2. **Apply the single-responsibility principle** — Each component does one thing
+3. **Identify reusability** — Which components appear in multiple places?
+4. **Define the tree** — Parent → child relationships
+
+Component classification:
+- **Page components**: Route-level, fetch data, compose layout
+- **Feature components**: Implement a business feature (UserProfile, OrderSummary)
+- **UI components**: Reusable, no business logic (Button, Card, Modal, Input)
+- **Layout components**: Structure only (Sidebar, Grid, Stack, Container)
+
+See [references/component-patterns.md](references/component-patterns.md) for design patterns.
+
+### Step 2: Plan State Management
+
+State management is the most impactful architectural decision in a React app. Apply the state placement ladder — use the simplest option that works:
+
+```
+1. Local state (useState)           → Simplest. Use for UI state within a component.
+2. Lifted state (parent useState)   → Share between siblings via parent.
+3. Composition (children prop)      → Avoid prop drilling with component composition.
+4. Context                          → Share across distant components (theme, auth, locale).
+5. URL state (query params)         → Shareable, bookmarkable state (filters, pagination).
+6. Server state (React Query / SWR) → Data from API with caching + refetching.
+7. Global store (Zustand / Redux)   → Client state shared across many unrelated components.
+```
+
+**Decision rules:**
+- If it's only used in one component → `useState`
+- If shared between parent/child → lift state up
+- If shared across distant components but rarely changes → Context
+- If it comes from the server → React Query / SWR / TanStack Query (NOT global store)
+- If it's complex client state updated from many places → Zustand or Redux Toolkit
+- If it should survive a page refresh → URL params or localStorage
+
+See [references/component-patterns.md](references/component-patterns.md) for detailed guidance.
+
+### Step 3: Define Design Tokens
+
+Design tokens are the foundation of visual consistency. Define tokens before building components:
+
+```typescript
+// tokens.ts
+export const tokens = {
+  color: {
+    primary: { 50: '#eff6ff', 500: '#3b82f6', 700: '#1d4ed8' },
+    neutral: { 50: '#f9fafb', 200: '#e5e7eb', 800: '#1f2937' },
+    success: '#10b981',
+    warning: '#f59e0b',
+    error: '#ef4444',
+  },
+  spacing: { xs: '0.25rem', sm: '0.5rem', md: '1rem', lg: '1.5rem', xl: '2rem' },
+  radius: { sm: '0.25rem', md: '0.5rem', lg: '1rem', full: '9999px' },
+  fontSize: { sm: '0.875rem', base: '1rem', lg: '1.125rem', xl: '1.25rem' },
+  shadow: {
+    sm: '0 1px 2px rgba(0,0,0,0.05)',
+    md: '0 4px 6px rgba(0,0,0,0.1)',
+  },
+};
+```
+
+Use tokens everywhere — never hardcode `#3b82f6` or `16px` in a component.
+
+### Step 4: Design the Data Fetching Strategy
+
+Choose patterns based on the data's nature:
+
+| Data Pattern | Approach | When |
+|-------------|----------|------|
+| Server data (read) | TanStack Query / SWR | Lists, details, dashboards |
+| Server data (mutate) | TanStack Query mutations | Create, update, delete |
+| Real-time data | WebSocket + state sync | Chat, notifications, live dashboards |
+| Form data | React Hook Form / Formik | Any form |
+| Static data | Build-time fetch (SSG) | Blog posts, docs, marketing pages |
+
+Key rules:
+- **Separate server state from client state.** Server state lives in the query cache, not in Redux.
+- **Fetch at the route level** when possible. Components receive data as props, not fetch their own.
+- **Handle loading, error, and empty** at every fetch boundary. Use error boundaries for unexpected errors.
+
+### Step 5: Organize the Codebase
+
+Recommended structure — feature-based with shared library:
+
+```
+src/
+├── app/                    # App-level: providers, routing, global config
+│   ├── providers.tsx       # All context providers composed
+│   ├── router.tsx          # Route definitions
+│   └── layout.tsx          # Root layout
+├── features/               # Feature modules (the meat of the app)
+│   ├── auth/
+│   │   ├── components/     # Feature-specific components
+│   │   ├── hooks/          # Feature-specific hooks
+│   │   ├── api.ts          # API calls for this feature
+│   │   ├── types.ts        # Types for this feature
+│   │   └── index.ts        # Public API (barrel file)
+│   ├── projects/
+│   └── settings/
+├── components/             # Shared UI components (Button, Modal, etc.)
+│   ├── ui/                 # Atomic UI primitives
+│   └── layout/             # Layout components (Sidebar, Stack)
+├── hooks/                  # Shared hooks (useDebounce, useMediaQuery)
+├── lib/                    # Shared utilities, API client, tokens
+│   ├── api-client.ts
+│   ├── tokens.ts
+│   └── utils.ts
+└── types/                  # Shared types
+```
+
+Rules:
+- Features import from `components/` and `lib/`, never from other features
+- Features export a clean public API through their `index.ts`
+- Circular imports between features means a responsibility boundary is wrong
+
+Use [templates/folder-structure.md](templates/folder-structure.md) as a starting point — includes the full `src/` layout, a co-located component template, design tokens, and a custom hook pattern.
+
+### Step 6: Validate the Architecture
+
+- [ ] Can a new engineer understand where to add a new feature?
+- [ ] Can you delete a feature directory without breaking unrelated features?
+- [ ] Is server state separate from client state?
+- [ ] Are components reusable without bringing business logic along?
+- [ ] Is there one clear way to do common tasks (fetching, forms, navigation)?
+- [ ] Are design tokens used consistently (no hardcoded values)?
+
+## Principles Applied
+
+- **KISS**: Use `useState` until you need something more. Don't reach for Redux on day one.
+- **DRY**: Shared UI components in `components/`, shared hooks in `hooks/`. Feature-specific code in features.
+- **Functional Independence**: Features don't know about each other. Shared dependencies go in `lib/` or `components/`.
+- **YAGNI**: Don't abstract until you have 2+ consumers. A single-use component doesn't need to be in the shared library.
+- **Separation of Concerns**: Components render UI. Hooks manage state and side effects. API modules handle HTTP. Types define shapes. Keep them apart.