ai-team 1.0.0

package/.agents/manifest.json

@@ -0,0 +1,170 @@
+{
+  "schemaVersion": 1,
+  "templateVersion": "0.1.0",
+  "installedAt": "2026-02-20T20:52:41.398Z",
+  "updatedAt": "2026-02-20T20:56:44.196Z",
+  "profile": {
+    "ide": "vscode",
+    "team": "web-product",
+    "includeMcp": true,
+    "agents": [
+      "cli-dev"
+    ]
+  },
+  "files": {
+    ".agents/skills/agent-creator/SKILL.md": {
+      "sourcePath": "templates/bootstrap/base/.agents/skills/agent-creator/SKILL.md",
+      "mode": "copy",
+      "sourceHash": "953e166539c8752fcd4b8d7f9215f4ba3f90355515ff50409ab0255b029503b4",
+      "installedHash": "953e166539c8752fcd4b8d7f9215f4ba3f90355515ff50409ab0255b029503b4",
+      "updatedAt": "2026-02-20T20:52:41.381Z"
+    },
+    ".agents/skills/ai-integration/SKILL.md": {
+      "sourcePath": "templates/bootstrap/base/.agents/skills/ai-integration/SKILL.md",
+      "mode": "copy",
+      "sourceHash": "9b3bc7bf3cc1e76da32fdb08a53cfbeb5c39ef09051069f9d643ba652a5d50b6",
+      "installedHash": "9b3bc7bf3cc1e76da32fdb08a53cfbeb5c39ef09051069f9d643ba652a5d50b6",
+      "updatedAt": "2026-02-20T20:52:41.382Z"
+    },
+    ".agents/skills/back-end-development/SKILL.md": {
+      "sourcePath": "templates/bootstrap/base/.agents/skills/back-end-development/SKILL.md",
+      "mode": "copy",
+      "sourceHash": "e3ff67e769102c1aa9c62a9cc0e9f22d78222c1231fe8896360391a063b059b1",
+      "installedHash": "e3ff67e769102c1aa9c62a9cc0e9f22d78222c1231fe8896360391a063b059b1",
+      "updatedAt": "2026-02-20T20:52:41.383Z"
+    },
+    ".agents/skills/database-management/SKILL.md": {
+      "sourcePath": "templates/bootstrap/base/.agents/skills/database-management/SKILL.md",
+      "mode": "copy",
+      "sourceHash": "e7cceb155c549bdb61102db1488165156a54252fef87345baef2f65938562f1b",
+      "installedHash": "e7cceb155c549bdb61102db1488165156a54252fef87345baef2f65938562f1b",
+      "updatedAt": "2026-02-20T20:52:41.384Z"
+    },
+    ".agents/skills/front-end-development/SKILL.md": {
+      "sourcePath": "templates/bootstrap/base/.agents/skills/front-end-development/SKILL.md",
+      "mode": "copy",
+      "sourceHash": "513e5da53f3bc76c152b066e4ff5fe180bf9934e7035ee95c2255564600893ac",
+      "installedHash": "513e5da53f3bc76c152b066e4ff5fe180bf9934e7035ee95c2255564600893ac",
+      "updatedAt": "2026-02-20T20:52:41.385Z"
+    },
+    ".agents/skills/front-end-development/references/component-architecture.md": {
+      "sourcePath": "templates/bootstrap/base/.agents/skills/front-end-development/references/component-architecture.md",
+      "mode": "copy",
+      "sourceHash": "88fc68f9f442c2c1fd5c18d4e12e003bc68372c20283a78a0db44bd668ad3421",
+      "installedHash": "88fc68f9f442c2c1fd5c18d4e12e003bc68372c20283a78a0db44bd668ad3421",
+      "updatedAt": "2026-02-20T20:52:41.386Z"
+    },
+    ".agents/skills/front-end-development/references/data-fetching-pattern.md": {
+      "sourcePath": "templates/bootstrap/base/.agents/skills/front-end-development/references/data-fetching-pattern.md",
+      "mode": "copy",
+      "sourceHash": "1feef85053f1e9594861708a8104cac62d63e3c0d2ab3696b12da76b533c3add",
+      "installedHash": "1feef85053f1e9594861708a8104cac62d63e3c0d2ab3696b12da76b533c3add",
+      "updatedAt": "2026-02-20T20:52:41.387Z"
+    },
+    ".agents/skills/front-end-development/references/state-management.md": {
+      "sourcePath": "templates/bootstrap/base/.agents/skills/front-end-development/references/state-management.md",
+      "mode": "copy",
+      "sourceHash": "8739bcd011466649bad63f502b055cddec8336cb0603bb6ec3c7eaec7902df1e",
+      "installedHash": "8739bcd011466649bad63f502b055cddec8336cb0603bb6ec3c7eaec7902df1e",
+      "updatedAt": "2026-02-20T20:52:41.387Z"
+    },
+    ".agents/skills/front-end-development/references/styling.md": {
+      "sourcePath": "templates/bootstrap/base/.agents/skills/front-end-development/references/styling.md",
+      "mode": "copy",
+      "sourceHash": "7ff0d87b439ded009ae001529111fc9f90e6c6621d6a8ef9f92c7acabf02f167",
+      "installedHash": "7ff0d87b439ded009ae001529111fc9f90e6c6621d6a8ef9f92c7acabf02f167",
+      "updatedAt": "2026-02-20T20:52:41.388Z"
+    },
+    ".agents/skills/self-improvement/SKILL.md": {
+      "sourcePath": "templates/bootstrap/base/.agents/skills/self-improvement/SKILL.md",
+      "mode": "copy",
+      "sourceHash": "afe83660246c12ff227424bb73874d6e607ebb2b00603f21009a94b6ff391035",
+      "installedHash": "afe83660246c12ff227424bb73874d6e607ebb2b00603f21009a94b6ff391035",
+      "updatedAt": "2026-02-20T20:52:41.390Z"
+    },
+    ".agents/skills/self-improvement/templates/handoff-template.md": {
+      "sourcePath": "templates/bootstrap/base/.agents/skills/self-improvement/templates/handoff-template.md",
+      "mode": "copy",
+      "sourceHash": "99dba34951306295439a77a8a16d9525144d99866dbe537c09dfddf1a637ae55",
+      "installedHash": "99dba34951306295439a77a8a16d9525144d99866dbe537c09dfddf1a637ae55",
+      "updatedAt": "2026-02-20T20:52:41.390Z"
+    },
+    ".agents/skills/self-improvement/templates/plan-template.md": {
+      "sourcePath": "templates/bootstrap/base/.agents/skills/self-improvement/templates/plan-template.md",
+      "mode": "copy",
+      "sourceHash": "19fe377c4340f944d4c6be0e10f8e160e25bbe49dbe3ef915b9475f19c6a35b0",
+      "installedHash": "19fe377c4340f944d4c6be0e10f8e160e25bbe49dbe3ef915b9475f19c6a35b0",
+      "updatedAt": "2026-02-20T20:52:41.391Z"
+    },
+    ".agents/skills/visual-testing/SKILL.md": {
+      "sourcePath": "templates/bootstrap/base/.agents/skills/visual-testing/SKILL.md",
+      "mode": "copy",
+      "sourceHash": "eb8c32f51731ce6e00715aa4da1ca5cd59f25674bc2c1e9a859d1469d4ce2538",
+      "installedHash": "eb8c32f51731ce6e00715aa4da1ca5cd59f25674bc2c1e9a859d1469d4ce2538",
+      "updatedAt": "2026-02-20T20:52:41.392Z"
+    },
+    ".agents/teams/web-product/README.md": {
+      "sourcePath": "templates/bootstrap/base/.agents/teams/web-product/README.md",
+      "mode": "copy",
+      "sourceHash": "29d0cc9b5203643ae4a8b9c211d8e6374b11ee209afba815649c40a26a0591e3",
+      "installedHash": "29d0cc9b5203643ae4a8b9c211d8e6374b11ee209afba815649c40a26a0591e3",
+      "updatedAt": "2026-02-20T20:52:41.393Z"
+    },
+    ".agents/teams/web-product/workflows/feature-lifecycle.md": {
+      "sourcePath": "templates/bootstrap/base/.agents/teams/web-product/workflows/feature-lifecycle.md",
+      "mode": "copy",
+      "sourceHash": "349e4a862f3838440272844d1b781f6832c5b40a915bf62e20733cf9e5a41247",
+      "installedHash": "349e4a862f3838440272844d1b781f6832c5b40a915bf62e20733cf9e5a41247",
+      "updatedAt": "2026-02-20T20:52:41.394Z"
+    },
+    ".github/agents/agent-creator.agent.md": {
+      "sourcePath": "templates/bootstrap/overlays/vscode-copilot/.github/agents/agent-creator.agent.md",
+      "mode": "copy",
+      "sourceHash": "7b103e957a2cbde45b78c2feae3ff8714b427e172dac2a2c6cb85b65ccd85bef",
+      "installedHash": "7b103e957a2cbde45b78c2feae3ff8714b427e172dac2a2c6cb85b65ccd85bef",
+      "updatedAt": "2026-02-20T20:52:41.395Z"
+    },
+    ".github/agents/code-reviewer.agent.md": {
+      "sourcePath": "templates/bootstrap/overlays/vscode-copilot/.github/agents/code-reviewer.agent.md",
+      "mode": "copy",
+      "sourceHash": "6487e579b9ab127ff707699f3e597cf15bd1f81054c06171a10d81021b68a3e4",
+      "installedHash": "6487e579b9ab127ff707699f3e597cf15bd1f81054c06171a10d81021b68a3e4",
+      "updatedAt": "2026-02-20T20:52:41.395Z"
+    },
+    ".github/agents/planning-agent.agent.md": {
+      "sourcePath": "templates/bootstrap/overlays/vscode-copilot/.github/agents/planning-agent.agent.md",
+      "mode": "copy",
+      "sourceHash": "2722a36e94db7d11d80d8cbc4c318f93e4b680319f2406a33a55df3b320690b6",
+      "installedHash": "2722a36e94db7d11d80d8cbc4c318f93e4b680319f2406a33a55df3b320690b6",
+      "updatedAt": "2026-02-20T20:52:41.395Z"
+    },
+    ".github/agents/product-team-orchestrator.agent.md": {
+      "sourcePath": "templates/bootstrap/overlays/vscode-copilot/.github/agents/product-team-orchestrator.agent.md",
+      "mode": "copy",
+      "sourceHash": "5ad463a2ce918e3e1cbf77ff26fb9177a16d48d07fa8422dfdcbb8bfef4309a0",
+      "installedHash": "5ad463a2ce918e3e1cbf77ff26fb9177a16d48d07fa8422dfdcbb8bfef4309a0",
+      "updatedAt": "2026-02-20T20:52:41.396Z"
+    },
+    ".github/agents/requirement-analyst.agent.md": {
+      "sourcePath": "templates/bootstrap/overlays/vscode-copilot/.github/agents/requirement-analyst.agent.md",
+      "mode": "copy",
+      "sourceHash": "f698954d2ad05262f4c5b2da054a4726bcd66331049b36e2b145cdc5068bfaad",
+      "installedHash": "f698954d2ad05262f4c5b2da054a4726bcd66331049b36e2b145cdc5068bfaad",
+      "updatedAt": "2026-02-20T20:52:41.397Z"
+    },
+    ".vscode/mcp.json": {
+      "sourcePath": "templates/bootstrap/overlays/vscode-copilot/.vscode/mcp.json",
+      "mode": "json-merge",
+      "sourceHash": "dfe8d7335274421b65f693697d40d4574fe48b875e71098f5c4401466bae5088",
+      "installedHash": "84550ae09a0e8b10fb63cb5bac6a13eab109557a83701237fb927066e14b0b52",
+      "updatedAt": "2026-02-20T20:52:41.398Z"
+    },
+    ".github/agents/cli-dev.agent.md": {
+      "sourcePath": "templates/bootstrap/overlays/vscode-copilot/.github/agents/cli-dev.agent.md",
+      "mode": "copy",
+      "sourceHash": "89482787a53bae281b8a4f68c38b42aa52eb73cc72d4627d19ec1b4c52e15b0d",
+      "installedHash": "89482787a53bae281b8a4f68c38b42aa52eb73cc72d4627d19ec1b4c52e15b0d",
+      "updatedAt": "2026-02-20T20:56:44.195Z"
+    }
+  }
+}

package/.agents/skills/agent-creator/SKILL.md

@@ -0,0 +1,28 @@
+# Agent Creator Skill
+
+This skill defines the process and best practices for creating new custom agents in this workspace.
+
+## Reference
+
+- [Custom Agents in VS Code Copilot](https://code.visualstudio.com/docs/copilot/customization/custom-agents)
+
+## Purpose
+
+Standardize how new agents are defined and integrated into the team workflow.
+
+## Process for Creating a New Agent
+
+1. **Identify the Role**: Determine the specific responsibilities, inputs, and outputs for the agent.
+2. **Create Agent Definition**: Create a new source definition in `src/agents/definitions/<role-name>.yaml`.
+3. **Follow the Template**: Use existing definition files as a template (e.g., `src/agents/definitions/backend-dev.yaml`).
+   - Define `name`, `description`, `argumentHint`, `target`, `tools`, and `handoffs` in YAML.
+   - Write clear instructions in the `body` block.
+4. **Regenerate Outputs**: Regenerate overlay agent files from definitions.
+5. **Register Skills**: Ensure the agent has access to relevant skills by listing them in the "Required References" section.
+6. **Update Documentation**: Add the new agent to `.agents/teams/web-product/README.md` and `docs/agents/README.md` if necessary.
+
+## Best Practices
+
+- Keep agent scope focused and single-purpose where possible.
+- Define clear handoffs to other agents (e.g., "Handoff to Tester").
+- Ensure the agent updates knowledge artifacts (`knowledge/`, `plans/`, etc.) as part of its workflow.

package/.agents/skills/ai-integration/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: ai-integration
+description: Guidelines for using Gemini with OpenAI compatibility, specifically for handling Structured Outputs and Zod schema limitations.
+---
+
+# AI Integration & Gemini Compatibility
+
+This project uses Google Gemini models via the OpenAI compatibility layer. While this allows us to use the standard OpenAI SDK, there are specific constraints and workarounds required for **Structured Outputs** (JSON Schema).
+
+For the official list of supported JSON Schema features, refer to the [Gemini API Structured Output Documentation](https://ai.google.dev/gemini-api/docs/structured-output#json-schema-support).
+
+## Zod Schema Compatibility
+
+When defining Zod schemas for AI structured outputs, follow these guidelines to ensure compatibility with Gemini:
+
+### 1. Avoid `z.tuple()`
+
+Gemini's JSON Schema validator has issues with `prefixItems` which `z.tuple()` generates.
+**❌ Avoid:**
+
+```typescript
+reps: z.tuple([z.number(), z.number()])
+```
+
+**✅ Use:**
+
+```typescript
+reps: z.array(z.number()) // You can add .length(2) if needed, though strict length validation might also be tricky
+```
+
+### 2. Nullable Fields & Unions
+
+Zod's `.nullable()` often generates an `anyOf` structure (e.g., `anyOf: [{type: 'string'}, {type: 'null'}]`). Gemini prefers a single schema with a type array (e.g., `type: ['string', 'null']`).
+
+We have implemented a `patchSchema` utility in `server/utils/ai.ts` that automatically handles this conversion at runtime. However, keeping schemas simple helps.
+
+### 3. `exclusiveMinimum`
+
+Gemini prefers `minimum` (inclusive) over `exclusiveMinimum`. The `patchSchema` utility automatically converts `exclusiveMinimum` to `minimum + 1` for integers.
+
+## Schema Patching (`server/utils/ai.ts`)
+
+We use a custom `patchSchema` function that intercepts the JSON Schema generated by `zodResponseFormat` before sending it to the API.
+
+**What it does:**
+
+1.  **Flattens `anyOf`**: Recursively flattens nested `anyOf` structures (common with complex unions + nullable).
+2.  **Merges Types**: Collects all types from the flattened options into a single `type` array (e.g., `type: ["integer", "array", "null"]`).
+3.  **Merges Properties**: Naively merges properties from all union members.
+4.  **Converts `exclusiveMinimum`**: Transforms to `minimum`.
+
+**Important:** When using this patching logic, we explicitly set `strict: false` in the API request, as the patched schema might not strictly adhere to the original Zod definition's structure (though it validates the same data).
+
+## Example Usage
+
+```typescript
+// Define schema
+const MySchema = z.object({
+  name: z.string(),
+  tags: z.array(z.string()).nullable(), // Will be patched to type: ['array', 'null']
+})
+
+// Call AI
+const response = await callAI({
+  // ...
+  responseSchema: MySchema,
+  schemaName: 'MySchema',
+})
+```

package/.agents/skills/back-end-development/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: back-end-development
+description: Best practices for Nuxt/Node backend development, API contracts, error handling, and observability.
+---
+
+# Back-End Development Skill
+
+## Scope
+
+Use this skill for:
+
+- `server/api/` route implementation
+- validation and API contract design
+- business logic isolation in `server/shared/`
+- data access and migration-safe schema changes
+
+## Standards
+
+1. Define strict input/output schemas.
+2. Return stable error shapes and HTTP semantics.
+3. Keep handlers thin; move logic to shared services.
+4. Add structured logs for failures and key state transitions.
+5. Enforce idempotency for mutating operations when relevant.
+6. Protect secrets and sensitive payload fields.
+7. For each endpoint, add unit tests that cover core functionality and boundary conditions.
+
+## Data & Migration Rules
+
+- For DB work, follow `.agents/skills/database-management/SKILL.md`.
+- Migrations must be reversible when feasible.
+- Update RLS policies and verify access paths.
+
+## AI Route Rules
+
+- For model integration and structured outputs, follow `.agents/skills/ai-integration/SKILL.md`.
+- Validate model output before persistence.
+
+## Definition of Done
+
+- Contract documented and validated
+- Endpoint unit tests cover functionality and boundaries
+- Error paths covered
+- Logging and monitoring hooks added
+- Handoff note includes API examples and edge cases

package/.agents/skills/database-management/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: database-management
+description: Workflow for Drizzle ORM migrations, schema changes, and applying RLS policies.
+---
+
+# Database Migrations & Management
+
+This project uses **Drizzle ORM** with a migration-based workflow for production-ready database management.
+
+## Overview
+
+- **Schema source of truth**: `db/schema/*.ts` (TypeScript)
+- **Migrations folder**: `db/migrations/` (generated SQL)
+- **RLS policies**: `db/rls-policies.sql` (manually maintained)
+- **Database**: Supabase (PostgreSQL)
+
+## Migration Workflow
+
+### 1. Make Schema Changes
+
+Edit the Drizzle schema files in `db/schema/`:
+
+- `profiles.ts` - User profiles
+- `training-plans.ts` - Training plans
+- `sessions.ts` - Workout sessions
+- `index.ts` - Export new schemas here
+
+Example:
+
+```typescript
+// db/schema/sessions.ts
+export const sessions = pgTable('sessions', {
+  id: uuid('id').primaryKey().defaultRandom(),
+  // ... add or modify columns here
+})
+```
+
+### 2. Generate Migration
+
+```bash
+pnpm db:generate
+```
+
+This compares your schema to the last snapshot and creates a new SQL migration file in `db/migrations/`.
+
+### 3. Apply Migration
+
+```bash
+pnpm db:migrate
+```
+
+This runs all pending migrations against your database. Migrations are tracked in `drizzle.__drizzle_migrations`.
+
+### Alternative: Push Schema Directly
+
+For development or when migrations are out of sync:
+
+```bash
+npx drizzle-kit push
+```
+
+This directly pushes schema changes to the database without creating migration files. Use when:
+
+- Migrations failed and need to force schema sync
+- Development environment needs quick schema updates
+- Migration state is out of sync with actual database
+
+**Warning:** This bypasses migration history. Use `db:migrate` workflow for production.
+
+### 4. Apply RLS Policies (if needed)
+
+```bash
+pnpm db:apply-rls
+```
+
+Run this after migrations if you've added new tables or need to refresh RLS policies.
+
+## Available Scripts
+
+| Script         | Command                    | Description                                            |
+| -------------- | -------------------------- | ------------------------------------------------------ |
+| `db:generate`  | `drizzle-kit generate`     | Generate migration from schema changes                 |
+| `db:migrate`   | `tsx scripts/migrate.ts`   | Apply pending migrations                               |
+| `db:push`      | `drizzle-kit push`         | Push schema directly to database (bypasses migrations) |
+| `db:studio`    | `drizzle-kit studio`       | Open Drizzle Studio GUI                                |
+| `db:apply-rls` | `tsx scripts/apply-rls.ts` | Apply RLS policies and FK constraints                  |
+
+## Important Notes
+
+### What Drizzle Manages
+
+- Table creation and modifications
+- Column types, defaults, constraints
+- Migration history tracking
+
+### What Drizzle Does NOT Manage
+
+These are handled separately in `db/rls-policies.sql`:
+
+- **RLS (Row Level Security) policies** - User data isolation
+- **Foreign keys to `auth.users`** - Supabase auth integration
+- **Custom indexes** - Performance optimization
+
+### Adding a New Table
+
+1. Create schema in `db/schema/new-table.ts`
+2. Export from `db/schema/index.ts`
+3. Run `pnpm db:generate`
+4. Run `pnpm db:migrate`
+5. Add RLS policy in `db/rls-policies.sql`
+6. Run `pnpm db:apply-rls`

package/.agents/skills/front-end-development/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: front-end-development
+description: Best practices for Vue front-end development including state management, ui component architecture, and styling standards.
+---
+
+# Front-End Development Skills
+
+This skill provides guidelines and best practices for front-end development in this project.
+
+## References
+
+- [State Management](./references/state-management.md)
+  Pinia stores, data fetching patterns, and deduplication strategies.
+
+- [Data Fetching Pattern](./references/data-fetching-pattern.md)
+  The specific pattern for deduplicating API calls in Pinia stores.
+
+- [Component Architecture](./references/component-architecture.md)
+  Component communication, composables, performance, and reusability guidelines.
+
+- [Styling Standards](./references/styling.md)
+  CSS units, Nuxt UI variables, design tokens, and spacing scales.
+
+## Core Best Practices
+
+1. **Single Responsibility** - Each component should do one thing well
+2. **Composition over Inheritance** - Use composables to share logic
+3. **Type Safety** - Define TypeScript interfaces for all props and emits
+4. **Reactive Patterns** - Use Vue's reactivity system, don't fight it
+5. **Avoid Deep Nesting** - Keep component trees shallow when possible
+6. **Test Boundaries** - Components should be testable in isolation
+7. **Reusability First** - Extract repeated patterns into shared components
+8. **Flexible Components** - Use slots for customization points
+9. **Design Tokens First** - Use existing tokens when available; create component-specific tokens for reusable components; otherwise use direct `rem` values
+10. **Rem Units Always** - Use rem for scalability, never px
+
+**Important Rule:** Whenever using Nuxt UI components, you must use the `nuxt-ui` MCP tools to verify component names, props, and availability. Do not assume component exist without verification.
+
+- When creating base components, make sure NO Tailwind CSS classes are used directly in the component templates. Instead, use scoped CSS to handle styling.

package/.agents/skills/front-end-development/references/component-architecture.md

@@ -0,0 +1,213 @@
+# Component Architecture
+
+## Component Communication
+
+- Avoid prop-drilling and event emits for workflow actions; prefer Pinia store actions or composables
+- Reusable base components - no store context - use props and events
+
+### v-model Pattern (Use Sparingly)
+
+- Avoid `v-model` for feature components; it relies on emits
+- Use `v-model` only for low-level input components where two-way binding is required
+- For complex objects, update via a store action instead of emitting the object
+- Avoid mutating props directly
+
+**Correct v-model implementation (use `defineModel` macro):**
+
+Child.vue:
+
+```vue
+<script setup>
+const model = defineModel()
+</script>
+
+<template>
+  <button @click="model.value++">Increment</button>
+</template>
+```
+
+Parent.vue:
+
+```vue
+<Child v-model="countModel" />
+```
+
+More examples at Vue doc site: https://vuejs.org/guide/components/v-model.html#multiple-v-model-bindings
+
+## Composables
+
+### Reusable Logic
+
+- Extract reusable logic into composables (`use*` pattern)
+- Composables can access Pinia stores
+- Keep composables focused and single-purpose
+
+### Example
+
+```typescript
+// composables/useProfile.ts
+export function useProfile() {
+  const profileStore = useProfileStore()
+
+  async function saveProfile(data: ProfileFormData) {
+    await $fetch('/api/profile', {
+      method: 'POST',
+      body: data,
+    })
+    await profileStore.fetchProfile()
+  }
+
+  return { saveProfile }
+}
+```
+
+## Performance
+
+### Computed Properties
+
+- Use `computed()` for derived state
+- Computed values are cached and only recalculate when dependencies change
+- Prefer computed over methods for template expressions
+
+### Lazy Loading
+
+- Use dynamic imports for route components
+- Lazy load heavy components not immediately visible
+- Code-split by route for optimal bundle sizes
+
+## Component Reusability
+
+### Extract Repeated Patterns
+
+- **Identify repeated UI patterns** across pages and components
+- **Create shared components** for patterns used 2+ times
+- **Prioritize reusability** - easier to update in one place
+- **Use generic naming** - avoid page-specific names for shared components
+
+### When to Extract a Component
+
+**Extract if:**
+
+- Pattern appears 2+ times in codebase
+- Pattern has consistent structure/behavior
+- Pattern will likely be used in future features
+- Updating the pattern requires changes in multiple places
+
+**Don't extract if:**
+
+- Pattern appears only once
+- Pattern is highly page-specific
+- Extraction adds unnecessary complexity
+- Pattern is likely to diverge in different contexts
+
+### Shared Component Patterns
+
+#### Display Components
+
+For read-only data display patterns:
+
+```vue
+<!-- components/display/FieldRow.vue -->
+<template>
+  <div class="field-row">
+    <label class="field-label">{{ label }}</label>
+    <div class="field-value">
+      <slot>{{ value }}</slot>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+defineProps<{
+  label: string
+  value?: string | number
+}>()
+</script>
+```
+
+**Usage:**
+
+```vue
+<FieldRow label="Experience Level" :value="profile.experienceLevel" />
+<FieldRow label="Goals">
+  <span class="custom-formatting">{{ formatGoals(profile.goals) }}</span>
+</FieldRow>
+```
+
+#### Form Components
+
+For input patterns with consistent styling:
+
+```vue
+<!-- components/form/FormField.vue -->
+<template>
+  <div class="form-field">
+    <label class="field-label">{{ label }}</label>
+    <slot />
+    <small v-if="hint" class="field-hint">{{ hint }}</small>
+  </div>
+</template>
+
+<script setup lang="ts">
+defineProps<{
+  label: string
+  hint?: string
+}>()
+</script>
+```
+
+### Component Organization
+
+```
+components/
+├── display/          # Read-only display components
+│   ├── FieldRow.vue
+│   ├── StatCard.vue
+│   └── DataList.vue
+├── form/             # Form input components
+│   ├── FormField.vue
+│   ├── ChipGroup.vue
+│   └── RadioGroup.vue
+├── layout/           # Layout components
+│   ├── PageHeader.vue
+│   └── Section.vue
+└── [feature]/        # Feature-specific components
+    └── SessionRunner.vue
+```
+
+### Refactoring Guidelines
+
+1. **Identify the pattern** - Look for repeated markup/logic
+2. **Extract to component** - Create in appropriate directory
+3. **Add TypeScript types** - Props and emits interfaces
+4. **Add slots for flexibility** - Allow customization where needed
+5. **Update all usages** - Replace old pattern with new component
+6. **Test thoroughly** - Ensure all instances work correctly
+
+### Example Refactor
+
+**Before:**
+
+```vue
+<!-- Repeated in multiple places -->
+<div class="profile-field">
+  <label>Experience Level</label>
+  <div class="field-value">{{ profile.experienceLevel }}</div>
+</div>
+<Divider />
+```
+
+**After:**
+
+```vue
+<!-- components/display/FieldRow.vue created -->
+<FieldRow label="Experience Level" :value="profile.experienceLevel" />
+<Divider />
+```
+
+**Benefits:**
+
+- ✅ Update styling in one place
+- ✅ Consistent appearance across app
+- ✅ Easier to add features (icons, tooltips, etc.)
+- ✅ Reduced code duplication