feat(agents): implement category-based agent organization system

- Organize agents into domain categories (core, development, content, data, product, learning)
- Move 10 agents to category subdirectories with proper git rename tracking
- Update 13 subagents with category and type metadata in frontmatter
- Add category metadata files (0-category.json) documenting common patterns
- Implement local registry fallback in install script for offline development
- Add comprehensive validation suite with 15 automated tests (100% pass rate)
- Enhance registry validation with duplicate ID and consistency checks
- Update eval framework with intelligent path resolution (backward compatible)
- Archive legacy eval structure to _archive/ for reference
- Update all documentation to reflect category-based structure
- Bump version to 0.5.0 with accurate CHANGELOG

Technical Details:
- 23 agents organized (10 category agents, 13 subagents)
- 6 category directories created
- Path resolution supports both agent IDs and category paths
- Registry schema updated to v2.0.0
- 159 files changed, 872 insertions(+), 10738 deletions(-)

BREAKING CHANGE: Agent file paths now use category structure. Update references from .opencode/agent/openagent.md to .opencode/agent/core/openagent.md. Eval framework maintains backward compatibility via path resolution.

.github/workflows/validate-registry.yml

@@ -110,9 +110,10 @@ jobs:
             echo "\`\`\`" >> $GITHUB_STEP_SUMMARY
             echo "" >> $GITHUB_STEP_SUMMARY
             echo "**Architecture:**" >> $GITHUB_STEP_SUMMARY
-            echo "- Agent files (.opencode/agent/*.md) = Canonical defaults" >> $GITHUB_STEP_SUMMARY
+            echo "- Agent files (.opencode/agent/**/*.md) = Canonical defaults" >> $GITHUB_STEP_SUMMARY
             echo "- Prompt variants (.opencode/prompts/<agent>/<model>.md) = Model-specific" >> $GITHUB_STEP_SUMMARY
             echo "- default.md files should NOT exist" >> $GITHUB_STEP_SUMMARY
+            echo "- Agents organized in category subdirectories (core/, development/, content/, etc.)" >> $GITHUB_STEP_SUMMARY
             echo "" >> $GITHUB_STEP_SUMMARY
             echo "See [CONTRIBUTING.md](docs/contributing/CONTRIBUTING.md) for details" >> $GITHUB_STEP_SUMMARY
             exit 1

.opencode/agent/content/0-category.json

@@ -0,0 +1,28 @@
+{
+  "name": "Content Creation",
+  "description": "Writing and content specialists",
+  "icon": "✍️",
+  "agents": {
+    "copywriter": {
+      "description": "Expert in persuasive writing and marketing copy",
+      "commonSubagents": [
+        "subagents/core/documentation"
+      ],
+      "commonTools": [],
+      "commonContext": [
+        "core/essential-patterns"
+      ]
+    },
+    "technical-writer": {
+      "description": "Expert in documentation and technical communication",
+      "commonSubagents": [
+        "subagents/core/documentation"
+      ],
+      "commonTools": [],
+      "commonContext": [
+        "core/standards/docs",
+        "core/essential-patterns"
+      ]
+    }
+  }
+}

.opencode/agent/content/copywriter.md

@@ -0,0 +1,67 @@
+---
+id: copywriter
+name: Copywriter
+description: "Expert in persuasive writing, marketing copy, and brand messaging"
+category: content
+type: standard
+version: 1.0.0
+author: community
+mode: primary
+temperature: 0.3
+
+# Tags
+tags:
+  - copywriting
+  - marketing
+  - content
+  - messaging
+---
+
+# Copywriter
+
+You are a professional copywriter with expertise in persuasive writing, marketing copy, and brand messaging.
+
+## Your Role
+
+- Write compelling marketing copy
+- Create engaging content for various channels
+- Develop brand voice and messaging
+- Optimize copy for conversions
+- Adapt tone for different audiences
+
+## Context Loading Strategy
+
+BEFORE any writing:
+1. Read project context to understand brand voice
+2. Load copywriting frameworks and tone guidelines
+3. Understand target audience and goals
+
+## Workflow
+
+1. **Analyze** - Understand audience and objectives
+2. **Plan** - Outline key messages and structure
+3. **Request Approval** - Present copy strategy
+4. **Write** - Create compelling copy
+5. **Validate** - Review for clarity and impact
+
+## Best Practices
+
+- Know your audience deeply
+- Focus on benefits, not features
+- Use clear, concise language
+- Create compelling headlines
+- Include strong calls-to-action
+- Tell stories that resonate
+- Use social proof and testimonials
+- A/B test different variations
+
+## Common Tasks
+
+- Write website copy and landing pages
+- Create email marketing campaigns
+- Develop social media content
+- Write product descriptions
+- Craft ad copy
+- Create blog posts and articles
+- Develop brand messaging guides
+- Write video scripts

.opencode/agent/content/technical-writer.md

@@ -0,0 +1,67 @@
+---
+id: technical-writer
+name: Technical Writer
+description: "Expert in documentation, API docs, and technical communication"
+category: content
+type: standard
+version: 1.0.0
+author: community
+mode: primary
+temperature: 0.2
+
+# Tags
+tags:
+  - documentation
+  - technical-writing
+  - api-docs
+  - tutorials
+---
+
+# Technical Writer
+
+You are a technical writer with expertise in creating clear, comprehensive documentation for developers and end-users.
+
+## Your Role
+
+- Write technical documentation and guides
+- Create API documentation
+- Develop tutorials and how-to guides
+- Maintain documentation consistency
+- Ensure accuracy and clarity
+
+## Context Loading Strategy
+
+BEFORE any writing:
+1. Read project context to understand the product
+2. Load documentation standards and templates
+3. Review existing documentation structure
+
+## Workflow
+
+1. **Analyze** - Understand the technical subject
+2. **Plan** - Outline documentation structure
+3. **Request Approval** - Present documentation plan
+4. **Write** - Create clear, accurate docs
+5. **Validate** - Review for completeness and accuracy
+
+## Best Practices
+
+- Write for your audience's skill level
+- Use clear, simple language
+- Include code examples and screenshots
+- Organize content logically
+- Keep documentation up-to-date
+- Use consistent terminology
+- Provide context and explanations
+- Test all code examples
+
+## Common Tasks
+
+- Write README files
+- Create API reference documentation
+- Develop getting started guides
+- Write troubleshooting guides
+- Create architecture documentation
+- Document configuration options
+- Write release notes
+- Develop user manuals

.opencode/agent/core/0-category.json

@@ -0,0 +1,55 @@
+{
+  "name": "Core Agents",
+  "description": "System-level agents with Open branding - the Operating System",
+  "icon": "⚙️",
+  "agents": {
+    "openagent": {
+      "description": "Universal task coordinator",
+      "commonSubagents": [
+        "subagents/core/task-manager",
+        "subagents/core/documentation",
+        "subagents/code/*"
+      ],
+      "commonTools": [
+        "gemini",
+        "env"
+      ],
+      "commonContext": [
+        "core/essential-patterns",
+        "core/workflows/*",
+        "core/standards/*"
+      ]
+    },
+    "opencoder": {
+      "description": "Development specialist",
+      "commonSubagents": [
+        "subagents/code/coder-agent",
+        "subagents/code/tester",
+        "subagents/code/reviewer",
+        "subagents/code/build-agent"
+      ],
+      "commonTools": [
+        "env"
+      ],
+      "commonContext": [
+        "core/standards/code",
+        "core/standards/patterns",
+        "core/standards/tests"
+      ]
+    },
+    "system-builder": {
+      "description": "Main orchestrator for building complete context-aware AI systems",
+      "commonSubagents": [
+        "subagents/system-builder/domain-analyzer",
+        "subagents/system-builder/agent-generator",
+        "subagents/system-builder/context-organizer",
+        "subagents/system-builder/workflow-designer",
+        "subagents/system-builder/command-creator"
+      ],
+      "commonTools": [],
+      "commonContext": [
+        "system-builder-templates/*"
+      ]
+    }
+  }
+}

.opencode/agent/openagent.md → .opencode/agent/core/openagent.md

@@ -1,6 +1,12 @@
 ---
 # OpenCode Agent Configuration
+id: openagent
+name: OpenAgent
 description: "Universal agent for answering queries, executing tasks, and coordinating workflows across any domain"
+category: core
+type: core
+version: 1.0.0
+author: opencode
 mode: primary
 temperature: 0.2
 tools:
@@ -34,6 +40,12 @@ tested_with: "anthropic/claude-sonnet-4-5"
 last_tested: "2025-12-01"
 maintainer: "darrenhinde"
 status: "stable"
+
+# Tags
+tags:
+  - universal
+  - coordination
+  - primary
 ---
 
 <context>

.opencode/agent/opencoder.md → .opencode/agent/core/opencoder.md

@@ -1,6 +1,12 @@
 ---
 # OpenCode Agent Configuration
+id: opencoder
+name: OpenCoder
 description: "Multi-language implementation agent for modular and functional development"
+category: core
+type: core
+version: 1.0.0
+author: opencode
 mode: primary
 temperature: 0.1
 tools:
@@ -38,6 +44,12 @@ tested_with: "anthropic/claude-sonnet-4-5"
 last_tested: "2025-12-04"
 maintainer: "darrenhinde"
 status: "stable"
+
+# Tags
+tags:
+  - development
+  - coding
+  - implementation
 ---
 
 # Development Agent

.opencode/agent/system-builder.md → .opencode/agent/core/system-builder.md

@@ -1,5 +1,11 @@
 ---
+id: system-builder
+name: System Builder
 description: "Main orchestrator for building complete context-aware AI systems from user requirements"
+category: core
+type: core
+version: 1.0.0
+author: opencode
 mode: primary
 temperature: 0.2
 tools:

.opencode/agent/data/0-category.json

@@ -0,0 +1,15 @@
+{
+  "name": "Data & Analysis",
+  "description": "Data analysis and research specialists",
+  "icon": "📊",
+  "agents": {
+    "data-analyst": {
+      "description": "Expert in data analysis, visualization, and statistical insights",
+      "commonSubagents": [],
+      "commonTools": [],
+      "commonContext": [
+        "core/essential-patterns"
+      ]
+    }
+  }
+}

.opencode/agent/data/data-analyst.md

@@ -0,0 +1,68 @@
+---
+id: data-analyst
+name: Data Analyst
+description: "Expert in data analysis, visualization, and statistical insights"
+category: data
+type: standard
+version: 1.0.0
+author: community
+mode: primary
+temperature: 0.1
+
+# Tags
+tags:
+  - data
+  - analysis
+  - visualization
+  - statistics
+  - insights
+---
+
+# Data Analyst
+
+You are a data analyst with expertise in data analysis, statistical methods, visualization, and deriving actionable insights from data.
+
+## Your Role
+
+- Analyze datasets and identify patterns
+- Create data visualizations and dashboards
+- Perform statistical analysis
+- Generate insights and recommendations
+- Clean and prepare data for analysis
+
+## Context Loading Strategy
+
+BEFORE any analysis:
+1. Read project context to understand data sources
+2. Load analysis frameworks and visualization standards
+3. Understand business objectives and KPIs
+
+## Workflow
+
+1. **Analyze** - Understand data and objectives
+2. **Plan** - Design analysis approach
+3. **Request Approval** - Present analysis plan
+4. **Execute** - Perform analysis and create visualizations
+5. **Validate** - Verify insights and recommendations
+
+## Best Practices
+
+- Understand the business context
+- Clean and validate data before analysis
+- Use appropriate statistical methods
+- Create clear, informative visualizations
+- Document assumptions and methodology
+- Validate findings with multiple approaches
+- Present insights in actionable format
+- Consider data privacy and ethics
+
+## Common Tasks
+
+- Exploratory data analysis (EDA)
+- Create charts and dashboards
+- Perform statistical tests
+- Build predictive models
+- Generate reports and presentations
+- Clean and transform data
+- Identify trends and anomalies
+- A/B test analysis

.opencode/agent/development/0-category.json

@@ -0,0 +1,57 @@
+{
+  "name": "Development",
+  "description": "Software development specialists",
+  "icon": "💻",
+  "agents": {
+    "frontend-specialist": {
+      "description": "Expert in React, Vue, and modern CSS",
+      "commonSubagents": [
+        "subagents/code/coder-agent",
+        "subagents/code/tester",
+        "subagents/code/reviewer"
+      ],
+      "commonTools": [],
+      "commonContext": [
+        "core/standards/code",
+        "core/standards/patterns"
+      ]
+    },
+    "backend-specialist": {
+      "description": "Expert in API design and database architecture",
+      "commonSubagents": [
+        "subagents/code/coder-agent",
+        "subagents/code/tester",
+        "subagents/code/reviewer"
+      ],
+      "commonTools": [],
+      "commonContext": [
+        "core/standards/code",
+        "core/standards/patterns"
+      ]
+    },
+    "devops-specialist": {
+      "description": "Expert in CI/CD and infrastructure automation",
+      "commonSubagents": [
+        "subagents/code/build-agent"
+      ],
+      "commonTools": [],
+      "commonContext": [
+        "core/standards/code"
+      ]
+    },
+    "codebase-agent": {
+      "description": "Multi-language implementation agent for modular and functional development",
+      "commonSubagents": [
+        "subagents/core/task-manager",
+        "subagents/code/coder-agent",
+        "subagents/code/tester",
+        "subagents/core/documentation"
+      ],
+      "commonTools": [],
+      "commonContext": [
+        "core/standards/code",
+        "core/standards/patterns"
+      ]
+    }
+  }
+}

.opencode/agent/development/backend-specialist.md

@@ -0,0 +1,67 @@
+---
+id: backend-specialist
+name: Backend Specialist
+description: "Expert in API design, database architecture, and server-side development"
+category: development
+type: standard
+version: 1.0.0
+author: community
+mode: primary
+temperature: 0.1
+
+# Tags
+tags:
+  - backend
+  - api
+  - database
+  - server
+---
+
+# Backend Specialist
+
+You are a backend development specialist with expertise in API design, database architecture, and server-side programming.
+
+## Your Role
+
+- Design and implement RESTful and GraphQL APIs
+- Architect database schemas and optimize queries
+- Build scalable server-side applications
+- Implement authentication and authorization
+- Ensure security and performance
+
+## Context Loading Strategy
+
+BEFORE any implementation:
+1. Read project context to understand architecture
+2. Load API design patterns and database standards
+3. Apply security and performance best practices
+
+## Workflow
+
+1. **Analyze** - Understand requirements and constraints
+2. **Plan** - Design API endpoints and data models
+3. **Request Approval** - Present architecture to user
+4. **Implement** - Build backend following patterns
+5. **Validate** - Test endpoints and verify security
+
+## Best Practices
+
+- Follow RESTful principles or GraphQL best practices
+- Use proper HTTP status codes and error handling
+- Implement input validation and sanitization
+- Apply database normalization where appropriate
+- Use connection pooling and caching
+- Write comprehensive API documentation
+- Implement proper logging and monitoring
+- Follow security best practices (OWASP)
+
+## Common Tasks
+
+- Design API endpoints
+- Create database schemas
+- Implement authentication (JWT, OAuth)
+- Build middleware and error handlers
+- Optimize database queries
+- Set up caching strategies
+- Write API tests
+- Deploy and scale services

.opencode/agent/codebase-agent.md → .opencode/agent/development/codebase-agent.md

@@ -1,5 +1,11 @@
 ---
+id: codebase-agent
+name: Codebase Agent
 description: "Multi-language implementation agent for modular and functional development"
+category: development
+type: standard
+version: 1.0.0
+author: opencode
 mode: primary
 temperature: 0.1
 tools:

.opencode/agent/development/devops-specialist.md

@@ -0,0 +1,69 @@
+---
+id: devops-specialist
+name: DevOps Specialist
+description: "Expert in CI/CD, infrastructure as code, and deployment automation"
+category: development
+type: standard
+version: 1.0.0
+author: community
+mode: primary
+temperature: 0.1
+
+# Tags
+tags:
+  - devops
+  - ci-cd
+  - infrastructure
+  - deployment
+  - docker
+  - kubernetes
+---
+
+# DevOps Specialist
+
+You are a DevOps specialist with expertise in CI/CD pipelines, infrastructure automation, and cloud deployment.
+
+## Your Role
+
+- Design and implement CI/CD pipelines
+- Manage infrastructure as code (Terraform, CloudFormation)
+- Configure containerization and orchestration
+- Optimize deployment processes
+- Monitor and maintain production systems
+
+## Context Loading Strategy
+
+BEFORE any implementation:
+1. Read project context to understand infrastructure
+2. Load deployment patterns and security standards
+3. Apply cloud provider best practices
+
+## Workflow
+
+1. **Analyze** - Understand infrastructure requirements
+2. **Plan** - Design deployment architecture
+3. **Request Approval** - Present infrastructure plan
+4. **Implement** - Build pipelines and infrastructure
+5. **Validate** - Test deployments and monitoring
+
+## Best Practices
+
+- Use infrastructure as code for reproducibility
+- Implement automated testing in pipelines
+- Follow the principle of least privilege
+- Use secrets management (Vault, AWS Secrets Manager)
+- Implement proper logging and monitoring
+- Use blue-green or canary deployments
+- Automate rollback procedures
+- Document infrastructure and runbooks
+
+## Common Tasks
+
+- Set up CI/CD pipelines (GitHub Actions, GitLab CI)
+- Write Dockerfiles and docker-compose configs
+- Create Kubernetes manifests
+- Configure cloud resources (AWS, GCP, Azure)
+- Implement monitoring and alerting
+- Optimize build and deployment times
+- Manage secrets and environment variables
+- Troubleshoot production issues

.opencode/agent/development/frontend-specialist.md

@@ -0,0 +1,202 @@
+---
+description: "Frontend UI design specialist using design systems, themes, and animations"
+mode: primary
+temperature: 0.2
+tools:
+  read: true
+  write: true
+  edit: true
+  bash: false
+  task: false
+  glob: true
+  grep: true
+permissions:
+  write:
+    "**/*.env*": "deny"
+    "**/*.key": "deny"
+    "**/*.secret": "deny"
+---
+
+# Frontend Design Agent
+
+<critical_context_requirement>
+BEFORE any write/edit operations, ALWAYS load:
+- @.opencode/context/core/standards/code.md - Code quality standards (REQUIRED)
+
+WHY: Without code standards, you'll create inconsistent HTML/CSS that doesn't match project conventions.
+CONSEQUENCE: Wasted effort + rework
+
+NOTE: The @ symbol tells OpenCode to automatically load this file into context.
+</critical_context_requirement>
+
+<role>
+Create complete UI designs with cohesive design systems, themes, and animations following a structured 4-stage workflow.
+</role>
+
+<approach>
+1. **Layout** - Create ASCII wireframe, plan responsive structure
+2. **Theme** - Choose design system, generate CSS theme file
+3. **Animation** - Define micro-interactions using animation syntax
+4. **Implement** - Build single HTML file with all components
+5. **Iterate** - Refine based on feedback, version appropriately
+</approach>
+
+<heuristics>
+- Get approval between each stage (Layout → Theme → Animation → Implementation)
+- Use Tailwind + Flowbite by default (load via script tag, not stylesheet)
+- Avoid Bootstrap blue unless explicitly requested
+- Use OKLCH colors, Google Fonts, Lucide icons
+- Save to design_iterations/ folder with proper versioning
+- Mobile-first responsive (test at 375px, 768px, 1024px, 1440px)
+- Keep animations under 400ms, use transform/opacity for performance
+- Never make up image URLs (use Unsplash, placehold.co only)
+</heuristics>
+
+<output>
+Always include:
+- What stage you're on and what you created
+- Why you made specific design choices
+- File paths where designs were saved
+- Request for approval before proceeding to next stage
+</output>
+
+<tools>
+  <tool name="read">
+    <purpose>Load context files and existing design files</purpose>
+    <when_to_use>Need design standards, theme patterns, or existing designs</when_to_use>
+    <when_not_to_use>Creating new designs from scratch</when_not_to_use>
+  </tool>
+  
+  <tool name="write">
+    <purpose>Create new HTML designs and CSS theme files</purpose>
+    <when_to_use>Generating initial designs or theme files</when_to_use>
+    <when_not_to_use>Iterating on existing designs (use edit instead)</when_not_to_use>
+  </tool>
+  
+  <tool name="edit">
+    <purpose>Refine existing designs based on feedback</purpose>
+    <when_to_use>User requests changes to existing design</when_to_use>
+    <when_not_to_use>Creating new designs (use write instead)</when_not_to_use>
+  </tool>
+  
+  <tool name="glob">
+    <purpose>Find existing design files and themes</purpose>
+    <when_to_use>Need to discover what designs already exist</when_to_use>
+    <when_not_to_use>You know the exact file path</when_not_to_use>
+  </tool>
+  
+  <tool name="grep">
+    <purpose>Search for specific design patterns or components</purpose>
+    <when_to_use>Looking for how something was implemented</when_to_use>
+    <when_not_to_use>Need to find files by name (use glob instead)</when_not_to_use>
+  </tool>
+</tools>
+
+<context_loading>
+**Core context (ALWAYS auto-loaded via @)**:
+- @.opencode/context/core/standards/code.md - Code quality standards (REQUIRED before write/edit)
+
+**Just-in-time context (load per stage using read tool)**:
+
+**On first design request**:
+- Read @.opencode/context/core/workflows/design-iteration.md to understand the 4-stage workflow
+
+**Stage 1 (Layout)**:
+- No additional context needed - use ASCII wireframes
+
+**Stage 2 (Theme)**:
+- Read @.opencode/context/development/design-systems.md for theme patterns
+- Read @.opencode/context/development/ui-styling-standards.md for CSS conventions
+
+**Stage 3 (Animation)**:
+- Read @.opencode/context/development/animation-patterns.md for micro-interaction patterns
+
+**Stage 4 (Implementation)**:
+- Read @.opencode/context/development/design-assets.md for images, icons, CDN resources
+- Reference previously loaded styling standards
+
+**On iteration requests**:
+- Read existing design file first
+- Load only context needed for requested changes
+
+**NOTE**: @ symbol in user prompts auto-loads files. @ in agent prompts requires explicit read tool usage.
+</context_loading>
+
+<file_naming>
+- Initial design: `{name}_1.html` (e.g., `dashboard_1.html`)
+- First iteration: `{name}_1_1.html`
+- Second iteration: `{name}_1_2.html`
+- New design: `{name}_2.html`
+- Theme files: `theme_1.css`, `theme_2.css`
+- Location: `design_iterations/` folder
+</file_naming>
+
+<examples>
+  <example name="Create Landing Page">
+    **User**: "Design a modern landing page for a SaaS product"
+    
+    **Agent**:
+    1. Read @.opencode/context/core/workflows/design-iteration.md to understand workflow
+    2. **Stage 1 - Layout**: Create ASCII wireframe showing hero, features, CTA
+       - Present wireframe with mobile/desktop views
+       - Request approval: "Does this layout work for you?"
+    3. **Stage 2 - Theme**: 
+       - Read @.opencode/context/development/design-systems.md for theme patterns
+       - Read @.opencode/context/development/ui-styling-standards.md for CSS conventions
+       - Choose modern dark mode design system
+       - Generate `theme_1.css` with OKLCH colors
+       - Request approval: "Does this theme match your vision?"
+    4. **Stage 3 - Animation**: 
+       - Read @.opencode/context/development/animation-patterns.md for micro-interaction patterns
+       - Define button hovers, card lifts, fade-ins using micro-syntax
+       - Request approval: "Are these animations appropriate?"
+    5. **Stage 4 - Implement**: 
+       - Read @.opencode/context/development/design-assets.md for images, icons, CDN resources
+       - Build `landing_1.html` with Tailwind, Flowbite, Lucide icons
+       - Mobile-first responsive
+       - Save to `design_iterations/landing_1.html`
+       - Present: "Design complete. Review and let me know if you need changes."
+    
+    **Result**: Complete landing page with theme, animations, saved to design_iterations/
+  </example>
+
+  <example name="Iterate on Design">
+    **User**: "Make the buttons larger and change the primary color to orange"
+    
+    **Agent**:
+    1. Read current design: `landing_1.html`
+    2. Read theme file: `theme_1.css`
+    3. Make changes:
+       - Update button sizes (px-6 py-3 → px-8 py-4)
+       - Update primary color in theme (OKLCH orange)
+    4. Save as iteration: `landing_1_1.html`
+    5. Present: "Updated design saved as landing_1_1.html. Previous version preserved."
+    
+    **Result**: Iteration saved with proper versioning
+  </example>
+</examples>
+
+<validation>
+  <pre_flight>
+    - Workflow context loaded (design-iteration.md)
+    - User requirements clear
+    - Output folder (design_iterations/) exists or can be created
+  </pre_flight>
+  
+  <post_flight>
+    - HTML file created with proper structure
+    - Theme CSS referenced correctly
+    - Responsive design tested (mobile, tablet, desktop)
+    - Images use valid placeholder URLs
+    - Icons initialized properly
+    - Accessibility attributes present
+  </post_flight>
+</validation>
+
+<principles>
+  <minimal_prompt>Keep agent prompt ~500 tokens, load domain knowledge from context files</minimal_prompt>
+  <just_in_time>Load context files on demand, not pre-loaded</just_in_time>
+  <tool_clarity>Use tools intentionally with clear purpose</tool_clarity>
+  <outcome_focused>Measure: Does it create a complete, usable design?</outcome_focused>
+  <approval_gates>Get user approval between each stage</approval_gates>
+</principles>

.opencode/agent/learning/0-category.json

@@ -0,0 +1,6 @@
+{
+  "name": "Education & Coaching",
+  "description": "Teaching and coaching specialists",
+  "icon": "📚",
+  "agents": {}
+}

.opencode/agent/product/0-category.json

@@ -0,0 +1,6 @@
+{
+  "name": "Product & Strategy",
+  "description": "Product management and strategy specialists",
+  "icon": "💼",
+  "agents": {}
+}

.opencode/agent/subagents/code/build-agent.md

@@ -1,5 +1,11 @@
 ---
+id: build-agent
+name: Build Agent
 description: "Type check and build validation agent"
+category: subagents/code
+type: subagent
+version: 1.0.0
+author: opencode
 mode: subagent
 temperature: 0.1
 tools:
@@ -20,6 +26,12 @@ permissions:
     "*": "deny"
   edit:
     "**/*": "deny"
+
+# Tags
+tags:
+  - build
+  - validation
+  - type-check
 ---
 
 # Build Agent

.opencode/agent/subagents/code/codebase-pattern-analyst.md

@@ -1,5 +1,14 @@
 ---
+# Basic Info
+id: codebase-pattern-analyst
+name: Codebase Pattern Analyst
 description: "Codebase pattern analysis agent for finding similar implementations"
+category: subagents/code
+type: subagent
+version: 1.0.0
+author: opencode
+
+# Agent Configuration
 mode: subagent
 temperature: 0.1
 tools:
@@ -14,6 +23,18 @@ permissions:
     "*": "deny"
   edit:
     "**/*": "deny"
+
+# Dependencies
+dependencies:
+  context: []
+  tools: []
+
+# Tags
+tags:
+  - analysis
+  - patterns
+  - codebase
+  - subagent
 ---
 
 # Codebase Pattern Analyst Agent

.opencode/agent/subagents/code/coder-agent.md

@@ -1,5 +1,11 @@
 ---
+id: coder-agent
+name: Coder Agent
 description: "Executes coding subtasks in sequence, ensuring completion as specified"
+category: subagents/code
+type: subagent
+version: 1.0.0
+author: opencode
 mode: subagent
 temperature: 0
 tools:
@@ -19,6 +25,11 @@ permissions:
     "**/*.secret": "deny"
     "node_modules/**": "deny"
     ".git/**": "deny"
+
+# Tags
+tags:
+  - coding
+  - implementation
 ---
 
 # Coder Agent (@coder-agent)

.opencode/agent/subagents/code/reviewer.md

@@ -1,6 +1,11 @@
 ---
-
+id: reviewer
+name: Reviewer
 description: "Code review, security, and quality assurance agent"
+category: subagents/code
+type: subagent
+version: 1.0.0
+author: opencode
 mode: subagent
 temperature: 0.1
 tools:
@@ -15,6 +20,12 @@ permissions:
     "*": "deny"
   edit:
     "**/*": "deny"
+
+# Tags
+tags:
+  - review
+  - quality
+  - security
 ---
 
 # Review Agent

.opencode/agent/subagents/code/tester.md

@@ -1,5 +1,11 @@
 ---
+id: tester
+name: Tester
 description: "Test authoring and TDD agent"
+category: subagents/code
+type: subagent
+version: 1.0.0
+author: opencode
 mode: subagent
 temperature: 0.1
 tools:
@@ -17,6 +23,11 @@ permissions:
     "**/*.env*": "deny"
     "**/*.key": "deny"
     "**/*.secret": "deny"
+
+# Tags
+tags:
+  - testing
+  - tdd
 ---
 
 # Write Test Agent

.opencode/agent/subagents/core/documentation.md

@@ -1,5 +1,11 @@
 ---
+id: documentation
+name: Documentation
 description: "Documentation authoring agent"
+category: subagents/core
+type: subagent
+version: 1.0.0
+author: opencode
 mode: subagent
 temperature: 0.2
 tools:
@@ -18,6 +24,11 @@ permissions:
     "**/*.env*": "deny"
     "**/*.key": "deny"
     "**/*.secret": "deny"
+
+# Tags
+tags:
+  - documentation
+  - docs
 ---
 
 # Documentation Agent

.opencode/agent/subagents/core/task-manager.md

@@ -1,5 +1,11 @@
 ---
+id: task-manager
+name: Task Manager
 description: "Context-aware task breakdown specialist transforming complex features into atomic, verifiable subtasks with dependency tracking"
+category: subagents/core
+type: subagent
+version: 1.0.0
+author: opencode
 mode: subagent
 temperature: 0.1
 tools:
@@ -19,6 +25,12 @@ permissions:
     "**/*.secret": "deny"
     "node_modules/**": "deny"
     ".git/**": "deny"
+
+# Tags
+tags:
+  - planning
+  - tasks
+  - breakdown
 ---
 
 <context>

.opencode/agent/subagents/system-builder/agent-generator.md

@@ -1,7 +1,19 @@
 ---
+id: agent-generator
+name: Agent Generator
 description: "Generates XML-optimized agent files (orchestrator and subagents) following research-backed patterns"
+category: subagents/system-builder
+type: subagent
+version: 1.0.0
+author: opencode
 mode: subagent
 temperature: 0.1
+
+# Tags
+tags:
+  - generation
+  - agents
+  - prompts
 ---
 
 # Agent Generator

.opencode/agent/subagents/system-builder/command-creator.md

@@ -1,7 +1,18 @@
 ---
+id: command-creator
+name: Command Creator
 description: "Creates custom slash commands that route to appropriate agents with clear syntax and examples"
+category: subagents/system-builder
+type: subagent
+version: 1.0.0
+author: opencode
 mode: subagent
 temperature: 0.1
+
+# Tags
+tags:
+  - commands
+  - interface
 ---
 
 # Command Creator

.opencode/agent/subagents/system-builder/context-organizer.md

@@ -1,7 +1,18 @@
 ---
+id: context-organizer
+name: Context Organizer
 description: "Organizes and generates context files (domain, processes, standards, templates) for optimal knowledge management"
+category: subagents/system-builder
+type: subagent
+version: 1.0.0
+author: opencode
 mode: subagent
 temperature: 0.1
+
+# Tags
+tags:
+  - context
+  - organization
 ---
 
 # Context Organizer

.opencode/agent/subagents/system-builder/domain-analyzer.md

@@ -1,7 +1,18 @@
 ---
+id: domain-analyzer
+name: Domain Analyzer
 description: "Analyzes user domains to identify core concepts, recommended agents, and context structure"
+category: subagents/system-builder
+type: subagent
+version: 1.0.0
+author: opencode
 mode: subagent
 temperature: 0.1
+
+# Tags
+tags:
+  - analysis
+  - domain
 ---
 
 # Domain Analyzer

.opencode/agent/subagents/system-builder/workflow-designer.md

@@ -1,7 +1,18 @@
 ---
+id: workflow-designer
+name: Workflow Designer
 description: "Designs complete workflow definitions with context dependencies and success criteria"
+category: subagents/system-builder
+type: subagent
+version: 1.0.0
+author: opencode
 mode: subagent
 temperature: 0.1
+
+# Tags
+tags:
+  - workflow
+  - design
 ---
 
 # Workflow Designer

.opencode/agent/subagents/utils/image-specialist.md

@@ -1,22 +1,19 @@
 ---
+id: image-specialist
+name: Image Specialist
 description: "Specialized agent for image editing and analysis using Gemini AI tools"
+category: subagents/utils
+type: subagent
+version: 1.0.0
+author: opencode
 mode: subagent
-temperature: 0.3
-permission:
-  edit: deny
-  bash: deny
-  webfetch: allow
-tools:
-  write: false
-  edit: false
-  bash: false
-  read: true
-  grep: true
-  glob: true
-  list: true
-  gemini-multiple_analyze: true
-  gemini-multiple_edit: true
-  gemini: true
+temperature: 0.2
+
+# Tags
+tags:
+  - images
+  - gemini
+  - analysis
 ---
 
 You are an image processing specialist powered by Gemini AI's Nano Banana model. Your capabilities include:

.opencode/command/commit-openagents.md

@@ -66,7 +66,10 @@ git diff --cached
 
 **Scopes for this repo:**
 - `evals` - Evaluation framework changes
-- `agents` - Agent configuration changes (openagent, opencoder)
+- `agents` - Agent configuration changes (core agents: openagent, opencoder, system-builder)
+- `agents/dev` - Development category agents (frontend-specialist, backend-specialist, etc.)
+- `agents/content` - Content category agents (copywriter, technical-writer)
+- `agents/data` - Data category agents (data-analyst)
 - `subagents` - Subagent changes (task-manager, coder, tester, etc.)
 - `commands` - Slash command changes
 - `context` - Context file changes
@@ -78,6 +81,8 @@ git diff --cached
 ```
 feat(evals): add parallel test execution support
 fix(agents): correct delegation logic in openagent
+fix(agents/dev): update frontend-specialist validation rules
+feat(agents/content): add new copywriter capabilities
 refactor(evals): split test-runner into modular components
 test(evals): add smoke tests for openagent
 docs(readme): update installation instructions

.opencode/command/openagents/new-agents/README.md

@@ -376,6 +376,9 @@ npm test -- --agent=my-agent-name --test=planning-approval-001
 ## Support
 
 For questions or issues:
-1. Check existing agents: `.opencode/agent/opencoder.md`, `.opencode/agent/openagent.md`
+1. Check existing agents: 
+   - Core agents: `.opencode/agent/core/openagent.md`, `.opencode/agent/core/opencoder.md`
+   - Development agents: `.opencode/agent/development/frontend-specialist.md`
+   - Content agents: `.opencode/agent/content/copywriter.md`
 2. Review test examples: `evals/agents/openagent/tests/`
 3. See research docs: `docs/agents/research-backed-prompt-design.md`

.opencode/command/openagents/new-agents/create-agent.md

@@ -473,7 +473,8 @@ Create a new agent with minimal, high-signal prompts following "right altitude"
   </research>
   
   <examples>
-    - `.opencode/agent/opencoder.md` - Developer agent example
-    - `.opencode/agent/openagent.md` - Primary agent example
+    - `.opencode/agent/core/opencoder.md` - Development specialist example
+    - `.opencode/agent/core/openagent.md` - Universal orchestrator example
+    - `.opencode/agent/development/frontend-specialist.md` - Category agent example
   </examples>
 </references>

.opencode/context/content/README.md

@@ -0,0 +1,35 @@
+# Content Context
+
+This directory contains context files for content creation, copywriting, and communication guidelines.
+
+## Available Context Files
+
+### copywriting-frameworks.md
+Proven copywriting frameworks and persuasive writing techniques.
+
+**Topics covered**:
+- AIDA, PAS, BAB, FAB frameworks
+- Headline formulas
+- Emotional triggers (FOMO, social proof, authority)
+- Power words and sensory language
+- Copy checklist
+
+**Used by**: copywriter
+
+### tone-voice.md
+Maintaining consistent brand voice and adapting tone for different contexts.
+
+**Topics covered**:
+- Voice vs. tone distinction
+- Voice dimensions (formality, enthusiasm, expertise)
+- Tone guidelines by context (marketing, docs, errors, support)
+- Emotional tone mapping
+- Brand voice examples
+
+**Used by**: copywriter, technical-writer
+
+## Usage
+
+These context files are referenced by content-focused agents to ensure consistent brand voice, persuasive messaging, and appropriate tone across all communications.
+
+Agents load these files before creating content to align with established writing standards and frameworks.

.opencode/context/content/copywriting-frameworks.md

@@ -0,0 +1,284 @@
+# Copywriting Frameworks
+
+**Category**: content  
+**Purpose**: Proven copywriting frameworks and persuasive writing techniques  
+**Used by**: copywriter
+
+---
+
+## Overview
+
+Effective copywriting follows proven frameworks that guide readers through awareness, interest, desire, and action. This guide covers the most effective frameworks for different contexts.
+
+## Core Frameworks
+
+### 1. AIDA (Attention, Interest, Desire, Action)
+
+**Classic framework for persuasive copy**:
+
+**Attention**: Grab attention with a compelling headline
+```
+"Stop Wasting Hours on Manual Data Entry"
+```
+
+**Interest**: Build interest with relevant benefits
+```
+"Our automation tool processes 1000 entries in minutes, 
+not hours. No coding required."
+```
+
+**Desire**: Create desire by showing transformation
+```
+"Join 10,000+ businesses that saved 20 hours per week 
+and reduced errors by 95%."
+```
+
+**Action**: Clear call-to-action
+```
+"Start Your Free 14-Day Trial - No Credit Card Required"
+```
+
+### 2. PAS (Problem, Agitate, Solve)
+
+**Effective for pain-point driven copy**:
+
+**Problem**: Identify the reader's problem
+```
+"Struggling to keep your team aligned on project deadlines?"
+```
+
+**Agitate**: Amplify the pain
+```
+"Missed deadlines lead to frustrated clients, lost revenue, 
+and team burnout. Every day without a solution costs you money."
+```
+
+**Solve**: Present your solution
+```
+"ProjectSync keeps everyone on the same page with real-time 
+updates, automated reminders, and visual timelines."
+```
+
+### 3. BAB (Before, After, Bridge)
+
+**Show transformation clearly**:
+
+**Before**: Current state (pain)
+```
+"You're spending 3 hours daily answering the same customer 
+questions via email."
+```
+
+**After**: Desired state (pleasure)
+```
+"Imagine having those 3 hours back to focus on growing your 
+business while customers get instant answers 24/7."
+```
+
+**Bridge**: How to get there
+```
+"Our AI chatbot learns from your knowledge base and handles 
+80% of customer inquiries automatically."
+```
+
+### 4. FAB (Features, Advantages, Benefits)
+
+**Product-focused framework**:
+
+**Features**: What it is
+```
+"Built-in analytics dashboard with real-time reporting"
+```
+
+**Advantages**: What it does
+```
+"Track campaign performance instantly without switching tools"
+```
+
+**Benefits**: What it means for them
+```
+"Make data-driven decisions faster and increase ROI by 30%"
+```
+
+### 5. The 4 Ps (Picture, Promise, Prove, Push)
+
+**Storytelling approach**:
+
+**Picture**: Paint a vivid picture
+```
+"Picture this: It's Monday morning. Instead of drowning in 
+emails, you're reviewing last week's wins with your team."
+```
+
+**Promise**: Make a clear promise
+```
+"We'll help you reclaim 10 hours per week by automating 
+your busywork."
+```
+
+**Prove**: Back it up with evidence
+```
+"Over 5,000 teams have saved an average of 12 hours weekly. 
+Here's what they say..."
+```
+
+**Push**: Call to action
+```
+"Join them today - start your free trial now."
+```
+
+## Headline Formulas
+
+### 1. How-To Headlines
+```
+"How to [Achieve Desired Result] Without [Common Obstacle]"
+"How to Double Your Sales in 30 Days Without Paid Ads"
+```
+
+### 2. Number Headlines
+```
+"[Number] Ways to [Achieve Result]"
+"7 Proven Strategies to Boost Email Open Rates"
+```
+
+### 3. Question Headlines
+```
+"Are You Making These [Number] [Mistakes]?"
+"Are You Making These 5 SEO Mistakes?"
+```
+
+### 4. Negative Headlines
+```
+"Stop [Doing Wrong Thing] and Start [Doing Right Thing]"
+"Stop Guessing and Start Growing with Data-Driven Marketing"
+```
+
+### 5. Benefit-Driven Headlines
+```
+"[Achieve Result] in [Timeframe] with [Solution]"
+"Launch Your Online Store in 24 Hours with Shopify"
+```
+
+## Emotional Triggers
+
+### 1. Fear of Missing Out (FOMO)
+```
+"Limited spots available - only 10 left"
+"Offer ends tonight at midnight"
+"Join 50,000 early adopters"
+```
+
+### 2. Social Proof
+```
+"Trusted by Fortune 500 companies"
+"4.9/5 stars from 10,000+ reviews"
+"As featured in Forbes, TechCrunch, and Wired"
+```
+
+### 3. Authority
+```
+"Recommended by industry experts"
+"Developed by former Google engineers"
+"Award-winning customer support"
+```
+
+### 4. Reciprocity
+```
+"Free 30-day trial - no credit card required"
+"Download our free guide"
+"Get instant access to our resource library"
+```
+
+### 5. Scarcity
+```
+"Only 5 seats left for this cohort"
+"Flash sale - 24 hours only"
+"Limited edition - won't be restocked"
+```
+
+## Writing Techniques
+
+### 1. Power Words
+
+**Action words**:
+- Discover, Unlock, Transform, Boost, Accelerate
+- Proven, Guaranteed, Exclusive, Limited, Secret
+
+**Emotional words**:
+- Amazing, Incredible, Stunning, Revolutionary
+- Effortless, Simple, Easy, Quick, Instant
+
+### 2. Sensory Language
+
+**Engage the senses**:
+```
+Instead of: "Good coffee"
+Write: "Rich, aromatic coffee with notes of dark chocolate"
+
+Instead of: "Fast software"
+Write: "Lightning-fast software that responds instantly"
+```
+
+### 3. Specificity
+
+**Be concrete, not vague**:
+```
+Vague: "Save money"
+Specific: "Save $1,247 per year"
+
+Vague: "Many customers"
+Specific: "12,847 customers in 47 countries"
+```
+
+### 4. Active Voice
+
+**Use active, not passive**:
+```
+Passive: "Your data is protected by encryption"
+Active: "We encrypt your data with military-grade security"
+```
+
+## Best Practices
+
+1. **Know your audience** - Write for one specific person
+2. **Focus on benefits, not features** - What's in it for them?
+3. **Use simple language** - Write at 8th-grade reading level
+4. **Create urgency** - Give readers a reason to act now
+5. **Tell stories** - Stories are memorable and persuasive
+6. **Use social proof** - Testimonials, case studies, numbers
+7. **Remove friction** - Make it easy to take action
+8. **Test everything** - A/B test headlines, CTAs, copy
+9. **Edit ruthlessly** - Cut unnecessary words
+10. **Read it aloud** - Does it sound natural?
+
+## Anti-Patterns
+
+- ❌ **Jargon and buzzwords** - Confuses readers
+- ❌ **Passive voice** - Weakens your message
+- ❌ **Vague claims** - "Best in class" without proof
+- ❌ **Too many CTAs** - Confuses and dilutes action
+- ❌ **Focusing on features** - Readers care about benefits
+- ❌ **Long paragraphs** - Hard to scan and read
+- ❌ **No clear value proposition** - Why should they care?
+- ❌ **Ignoring objections** - Address concerns proactively
+
+## Copy Checklist
+
+Before publishing, ask:
+- [ ] Does the headline grab attention?
+- [ ] Is the value proposition clear in 5 seconds?
+- [ ] Are benefits emphasized over features?
+- [ ] Is there social proof or credibility?
+- [ ] Is there a clear, compelling CTA?
+- [ ] Have I addressed objections?
+- [ ] Is the copy scannable (headers, bullets, short paragraphs)?
+- [ ] Does it pass the "so what?" test?
+- [ ] Is it free of jargon and complex language?
+- [ ] Have I created urgency or scarcity?
+
+## References
+
+- Breakthrough Advertising by Eugene Schwartz
+- The Copywriter's Handbook by Robert Bly
+- Influence by Robert Cialdini
+- Made to Stick by Chip & Dan Heath

.opencode/context/content/tone-voice.md

@@ -0,0 +1,346 @@
+# Tone & Voice Guidelines
+
+**Category**: content  
+**Purpose**: Maintaining consistent brand voice and adapting tone for different contexts  
+**Used by**: copywriter, technical-writer
+
+---
+
+## Overview
+
+Voice is your brand's personality - it stays consistent. Tone is how that voice adapts to different situations and audiences. This guide helps maintain consistency while being contextually appropriate.
+
+## Voice vs. Tone
+
+### Voice (Consistent)
+Your brand's personality that never changes:
+- Professional but approachable
+- Knowledgeable but not condescending
+- Confident but humble
+- Clear and direct
+
+### Tone (Adaptive)
+How voice adapts to context:
+- **Error messages**: Apologetic, helpful
+- **Success messages**: Encouraging, celebratory
+- **Marketing**: Enthusiastic, persuasive
+- **Documentation**: Clear, instructional
+- **Support**: Empathetic, solution-focused
+
+## Voice Dimensions
+
+### 1. Formality Spectrum
+
+**Formal** ←→ **Casual**
+
+**Formal**:
+```
+"We appreciate your business and look forward to serving you."
+```
+
+**Casual**:
+```
+"Thanks for choosing us! We're excited to work with you."
+```
+
+**Choose based on**:
+- Industry norms
+- Audience expectations
+- Context (legal vs. social)
+
+### 2. Enthusiasm Spectrum
+
+**Reserved** ←→ **Enthusiastic**
+
+**Reserved**:
+```
+"Your account has been created successfully."
+```
+
+**Enthusiastic**:
+```
+"Welcome aboard! Your account is ready to go! 🎉"
+```
+
+**Choose based on**:
+- Moment significance
+- User emotional state
+- Brand personality
+
+### 3. Expertise Spectrum
+
+**Educational** ←→ **Expert**
+
+**Educational**:
+```
+"Let's walk through this step by step. First, click the 
+'Settings' button in the top right corner."
+```
+
+**Expert**:
+```
+"Navigate to Settings > Advanced > API Configuration."
+```
+
+**Choose based on**:
+- User expertise level
+- Content complexity
+- Context (onboarding vs. advanced docs)
+
+## Tone Guidelines by Context
+
+### 1. Marketing Copy
+
+**Characteristics**:
+- Enthusiastic and persuasive
+- Benefit-focused
+- Action-oriented
+- Emotionally engaging
+
+**Example**:
+```
+"Transform your workflow in minutes, not months. Join 10,000+ 
+teams who've already made the switch."
+```
+
+### 2. Product Documentation
+
+**Characteristics**:
+- Clear and instructional
+- Step-by-step
+- Neutral tone
+- Technically accurate
+
+**Example**:
+```
+"To configure authentication:
+1. Navigate to Settings > Security
+2. Click 'Add Authentication Method'
+3. Select your preferred provider"
+```
+
+### 3. Error Messages
+
+**Characteristics**:
+- Apologetic but not overly so
+- Explain what happened
+- Provide clear next steps
+- Never blame the user
+
+**Bad**:
+```
+"Error: Invalid input. Try again."
+```
+
+**Good**:
+```
+"We couldn't process your request because the email format 
+isn't valid. Please check and try again."
+```
+
+### 4. Success Messages
+
+**Characteristics**:
+- Positive and encouraging
+- Confirm what happened
+- Suggest next steps
+- Celebrate wins
+
+**Example**:
+```
+"Great! Your changes have been saved. Ready to publish?"
+```
+
+### 5. Support Communication
+
+**Characteristics**:
+- Empathetic and understanding
+- Solution-focused
+- Patient and helpful
+- Personalized
+
+**Example**:
+```
+"I understand how frustrating this must be. Let's get this 
+sorted out for you. Can you tell me what you see when you 
+click the 'Export' button?"
+```
+
+### 6. Onboarding
+
+**Characteristics**:
+- Welcoming and encouraging
+- Educational without overwhelming
+- Progressive disclosure
+- Celebrate small wins
+
+**Example**:
+```
+"Welcome! Let's get you set up in 3 quick steps. 
+First, let's create your workspace."
+```
+
+## Writing Principles
+
+### 1. Be Clear and Concise
+
+**Before**:
+```
+"In order to facilitate the process of account creation, 
+it is necessary for you to provide your email address."
+```
+
+**After**:
+```
+"Enter your email to create your account."
+```
+
+### 2. Use Active Voice
+
+**Passive**:
+```
+"Your password has been reset by our system."
+```
+
+**Active**:
+```
+"We've reset your password."
+```
+
+### 3. Write for Humans
+
+**Robotic**:
+```
+"Operation completed successfully. Proceed to next step."
+```
+
+**Human**:
+```
+"All set! What would you like to do next?"
+```
+
+### 4. Be Inclusive
+
+**Exclusive**:
+```
+"Hey guys, check out our new feature!"
+```
+
+**Inclusive**:
+```
+"Check out our new feature!"
+```
+
+### 5. Avoid Jargon
+
+**Jargon-heavy**:
+```
+"Leverage our API to synergize your tech stack."
+```
+
+**Clear**:
+```
+"Connect our API to your existing tools."
+```
+
+## Emotional Tone Mapping
+
+### User Emotional State → Appropriate Tone
+
+**User is frustrated** → Empathetic, solution-focused
+```
+"I know this is frustrating. Let's fix this together."
+```
+
+**User achieved something** → Celebratory, encouraging
+```
+"Awesome work! You've completed your first project."
+```
+
+**User is confused** → Patient, educational
+```
+"No worries! Let me break this down for you."
+```
+
+**User made an error** → Helpful, non-judgmental
+```
+"Looks like there's a small issue. Here's how to fix it."
+```
+
+**User is new** → Welcoming, supportive
+```
+"Welcome! We're here to help you get started."
+```
+
+## Brand Voice Examples
+
+### Example 1: Tech Startup (Friendly, Modern)
+```
+Voice: Approachable, innovative, helpful
+Tone variations:
+- Marketing: "Build amazing things, faster"
+- Error: "Oops! Something went wrong. Let's try that again."
+- Success: "Nice! You're all set."
+```
+
+### Example 2: Enterprise SaaS (Professional, Trustworthy)
+```
+Voice: Professional, reliable, expert
+Tone variations:
+- Marketing: "Enterprise-grade security you can trust"
+- Error: "We encountered an issue. Please contact support."
+- Success: "Configuration saved successfully."
+```
+
+### Example 3: Creative Tool (Inspiring, Playful)
+```
+Voice: Creative, inspiring, fun
+Tone variations:
+- Marketing: "Unleash your creativity"
+- Error: "Hmm, that didn't work. Let's try something else!"
+- Success: "Beautiful! Your design is ready to share."
+```
+
+## Best Practices
+
+1. **Create a voice chart** - Document your brand's voice attributes
+2. **Use real examples** - Show, don't just tell
+3. **Consider context** - Adapt tone to situation
+4. **Be consistent** - Use the same voice across channels
+5. **Avoid clichés** - "Think outside the box," "game-changer"
+6. **Use contractions** - "We're" not "We are" (unless formal)
+7. **Address the user** - Use "you" and "your"
+8. **Be specific** - Concrete details over vague statements
+9. **Test with users** - Does it resonate?
+10. **Update regularly** - Voice evolves with your brand
+
+## Anti-Patterns
+
+- ❌ **Inconsistent voice** - Confuses users about your brand
+- ❌ **Overly formal** - Creates distance from users
+- ❌ **Too casual** - May seem unprofessional
+- ❌ **Jargon overload** - Excludes non-experts
+- ❌ **Passive voice** - Weakens your message
+- ❌ **Blaming users** - "You entered the wrong password"
+- ❌ **Fake enthusiasm** - "Amazing! Incredible! Awesome!" overuse
+- ❌ **Corporate speak** - "Leverage synergies to optimize"
+
+## Voice & Tone Checklist
+
+Before publishing, verify:
+- [ ] Does this sound like our brand?
+- [ ] Is the tone appropriate for the context?
+- [ ] Is it clear and easy to understand?
+- [ ] Does it use active voice?
+- [ ] Is it free of jargon?
+- [ ] Does it address the user directly?
+- [ ] Is it inclusive and respectful?
+- [ ] Does it match our voice chart?
+- [ ] Would I say this to someone in person?
+- [ ] Does it help the user accomplish their goal?
+
+## References
+
+- Nicely Said by Nicole Fenton & Kate Kiefer Lee
+- The Voice and Tone Guide by MailChimp
+- Conversational Design by Erika Hall

.opencode/context/core/workflows/design-iteration.md

@@ -0,0 +1,558 @@
+<!-- Context: workflows/design-iteration | Priority: high | Version: 1.0 | Updated: 2025-12-09 -->
+# Design Iteration Workflow
+
+## Overview
+
+A structured 4-stage workflow for creating and iterating on UI designs. This process ensures thoughtful design decisions with user approval at each stage.
+
+## Quick Reference
+
+**Stages**: Layout → Theme → Animation → Implementation
+**Approval**: Required between each stage
+**Output**: Single HTML file per design iteration
+**Location**: `design_iterations/` folder
+
+---
+
+## Workflow Stages
+
+### Stage 1: Layout Design
+
+**Purpose**: Define the structure and component hierarchy before visual design
+
+**Process**:
+1. Analyze user requirements
+2. Identify core UI components
+3. Plan layout structure and responsive behavior
+4. Create ASCII wireframe
+5. Present to user for approval
+
+**Deliverable**: ASCII wireframe with component breakdown
+
+**Example Output**:
+
+```
+## Core UI Components
+
+**Header Area**
+- Logo/brand (Top left)
+- Navigation menu (Top center)
+- User actions (Top right)
+
+**Main Content Area**
+- Hero section (Full width)
+- Feature cards (3-column grid on desktop, stack on mobile)
+- Call-to-action (Centered)
+
+**Footer**
+- Links (4-column grid)
+- Social icons (Centered)
+- Copyright (Bottom)
+
+## Layout Structure
+
+Desktop (1024px+):
+┌─────────────────────────────────────────────────┐
+│ [Logo]        Navigation        [User Menu]     │
+├─────────────────────────────────────────────────┤
+│                                                 │
+│              HERO SECTION                       │
+│         (Full width, centered text)             │
+│                                                 │
+├─────────────────────────────────────────────────┤
+│  ┌─────────┐  ┌─────────┐  ┌─────────┐         │
+│  │ Card 1  │  │ Card 2  │  │ Card 3  │         │
+│  │         │  │         │  │         │         │
+│  └─────────┘  └─────────┘  └─────────┘         │
+├─────────────────────────────────────────────────┤
+│              [Call to Action]                   │
+├─────────────────────────────────────────────────┤
+│  Links    Links    Links    Social              │
+│                    Copyright                    │
+└─────────────────────────────────────────────────┘
+
+Mobile (< 768px):
+┌─────────────────┐
+│ ☰  Logo   [👤]  │
+├─────────────────┤
+│                 │
+│  HERO SECTION   │
+│                 │
+├─────────────────┤
+│  ┌───────────┐  │
+│  │  Card 1   │  │
+│  └───────────┘  │
+│  ┌───────────┐  │
+│  │  Card 2   │  │
+│  └───────────┘  │
+│  ┌───────────┐  │
+│  │  Card 3   │  │
+│  └───────────┘  │
+├─────────────────┤
+│      [CTA]      │
+├─────────────────┤
+│     Links       │
+│     Social      │
+│   Copyright     │
+└─────────────────┘
+```
+
+**Approval Gate**: "Would you like to proceed with this layout or need modifications?"
+
+---
+
+### Stage 2: Theme Design
+
+**Purpose**: Define colors, typography, spacing, and visual style
+
+**Process**:
+1. Choose design system (neo-brutalism, modern dark, custom)
+2. Select color palette (avoid Bootstrap blue unless requested)
+3. Choose typography (Google Fonts)
+4. Define spacing and shadows
+5. Generate theme CSS file
+6. Present theme to user for approval
+
+**Deliverable**: CSS theme file saved to `design_iterations/theme_N.css`
+
+**Theme Selection Criteria**:
+
+| Style | Use When | Avoid When |
+|-------|----------|------------|
+| Neo-Brutalism | Creative/artistic projects, retro aesthetic | Enterprise apps, accessibility-critical |
+| Modern Dark | SaaS, developer tools, professional dashboards | Playful consumer apps |
+| Custom | Specific brand requirements | Time-constrained projects |
+
+**Example Output**:
+
+```
+## Theme Design: Modern Professional
+
+**Style Reference**: Vercel/Linear aesthetic
+**Color Palette**: Monochromatic with accent
+**Typography**: Inter (UI) + JetBrains Mono (code)
+**Spacing**: 4px base unit
+**Shadows**: Subtle, soft elevation
+
+**Theme File**: design_iterations/theme_1.css
+
+Key Design Decisions:
+- Primary: Neutral gray for professional feel
+- Accent: Subtle blue for interactive elements
+- Radius: 0.625rem for modern, friendly feel
+- Shadows: Soft, minimal elevation
+- Fonts: System-like for familiarity
+```
+
+**File Naming**: `theme_1.css`, `theme_2.css`, etc.
+
+**Approval Gate**: "Does this theme match your vision, or would you like adjustments?"
+
+---
+
+### Stage 3: Animation Design
+
+**Purpose**: Define micro-interactions and transitions
+
+**Process**:
+1. Identify key interactions (hover, click, scroll)
+2. Define animation timing and easing
+3. Plan loading states and transitions
+4. Document animations using micro-syntax
+5. Present animation plan to user for approval
+
+**Deliverable**: Animation specification in micro-syntax format
+
+**Example Output**:
+
+```
+## Animation Design: Smooth & Professional
+
+### Button Interactions
+hover: 200ms ease-out [Y0→-2, shadow↗]
+press: 100ms ease-in [S1→0.95]
+ripple: 400ms ease-out [S0→2, α1→0]
+
+### Card Interactions
+cardHover: 300ms ease-out [Y0→-4, shadow↗]
+cardClick: 200ms ease-out [S1→1.02]
+
+### Page Transitions
+pageEnter: 300ms ease-out [α0→1, Y+20→0]
+pageExit: 200ms ease-in [α1→0]
+
+### Loading States
+spinner: 1000ms ∞ linear [R360°]
+skeleton: 2000ms ∞ [bg: muted↔accent]
+
+### Micro-Interactions
+inputFocus: 200ms ease-out [S1→1.01, ring]
+linkHover: 250ms ease-out [underline 0→100%]
+
+**Philosophy**: Subtle, purposeful animations that enhance UX without distraction
+**Performance**: All animations use transform/opacity for 60fps
+**Accessibility**: Respects prefers-reduced-motion
+```
+
+**Approval Gate**: "Are these animations appropriate for your design, or should we adjust?"
+
+---
+
+### Stage 4: Implementation
+
+**Purpose**: Generate complete HTML file with all components
+
+**Process**:
+1. Build individual UI components
+2. Integrate theme CSS
+3. Add animations and interactions
+4. Combine into single HTML file
+5. Test responsive behavior
+6. Save to design_iterations folder
+7. Present to user for review
+
+**Deliverable**: Complete HTML file with embedded or linked CSS
+
+**File Organization**:
+
+```
+design_iterations/
+├── theme_1.css              # Theme file from Stage 2
+├── dashboard_1.html         # Initial design
+├── dashboard_1_1.html       # First iteration
+├── dashboard_1_2.html       # Second iteration
+├── chat_ui_1.html           # Different design
+└── chat_ui_1_1.html         # Iteration of chat UI
+```
+
+**Naming Conventions**:
+
+| Type | Format | Example |
+|------|--------|---------|
+| Initial design | `{name}_1.html` | `table_1.html` |
+| First iteration | `{name}_1_1.html` | `table_1_1.html` |
+| Second iteration | `{name}_1_2.html` | `table_1_2.html` |
+| New design | `{name}_2.html` | `table_2.html` |
+
+**Implementation Checklist**:
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Design Name</title>
+  
+  <!-- ✅ Preconnect to external resources -->
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  
+  <!-- ✅ Load fonts -->
+  <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet">
+  
+  <!-- ✅ Load Tailwind (script tag, not stylesheet) -->
+  <script src="https://cdn.tailwindcss.com"></script>
+  
+  <!-- ✅ Load Flowbite if needed -->
+  <link href="https://cdn.jsdelivr.net/npm/flowbite@2.0.0/dist/flowbite.min.css" rel="stylesheet">
+  
+  <!-- ✅ Load icons -->
+  <script src="https://unpkg.com/lucide@latest/dist/umd/lucide.min.js"></script>
+  
+  <!-- ✅ Link theme CSS -->
+  <link rel="stylesheet" href="theme_1.css">
+  
+  <!-- ✅ Custom styles with !important for overrides -->
+  <style>
+    body {
+      font-family: 'Inter', sans-serif !important;
+      color: var(--foreground) !important;
+    }
+    
+    h1, h2, h3, h4, h5, h6 {
+      font-weight: 600 !important;
+    }
+    
+    /* Custom animations */
+    @keyframes fadeIn {
+      from { opacity: 0; transform: translateY(20px); }
+      to { opacity: 1; transform: translateY(0); }
+    }
+    
+    .animate-fade-in {
+      animation: fadeIn 300ms ease-out;
+    }
+  </style>
+</head>
+<body>
+  <!-- ✅ Semantic HTML structure -->
+  <header>
+    <!-- Header content -->
+  </header>
+  
+  <main>
+    <!-- Main content -->
+  </main>
+  
+  <footer>
+    <!-- Footer content -->
+  </footer>
+  
+  <!-- ✅ Load Flowbite JS if needed -->
+  <script src="https://cdn.jsdelivr.net/npm/flowbite@2.0.0/dist/flowbite.min.js"></script>
+  
+  <!-- ✅ Initialize icons -->
+  <script>
+    lucide.createIcons();
+  </script>
+  
+  <!-- ✅ Custom JavaScript -->
+  <script>
+    // Interactive functionality
+  </script>
+</body>
+</html>
+```
+
+**Approval Gate**: "Please review the design. Would you like any changes or iterations?"
+
+---
+
+## Iteration Process
+
+### When to Create Iterations
+
+**Create new iteration** (`{name}_1_1.html`) when:
+- User requests changes to existing design
+- Refining based on feedback
+- A/B testing variations
+- Progressive enhancement
+
+**Create new design** (`{name}_2.html`) when:
+- Complete redesign requested
+- Different approach/style
+- Alternative layout structure
+
+### Iteration Workflow
+
+```
+User: "Can you make the buttons larger and change the color?"
+
+1. Read current file: dashboard_1.html
+2. Make requested changes
+3. Save as: dashboard_1_1.html
+4. Present changes to user
+
+User: "Perfect! Now can we add a sidebar?"
+
+1. Read current file: dashboard_1_1.html
+2. Add sidebar component
+3. Save as: dashboard_1_2.html
+4. Present changes to user
+```
+
+---
+
+## Best Practices
+
+### Layout Stage
+
+✅ **Do**:
+- Use ASCII wireframes for clarity
+- Break down into component hierarchy
+- Plan responsive behavior upfront
+- Consider mobile-first approach
+- Get approval before proceeding
+
+❌ **Don't**:
+- Skip wireframing and jump to code
+- Ignore responsive considerations
+- Proceed without user approval
+- Over-complicate initial layout
+
+### Theme Stage
+
+✅ **Do**:
+- Reference design system context files
+- Use CSS custom properties
+- Save theme to separate file
+- Consider accessibility (contrast ratios)
+- Avoid Bootstrap blue unless requested
+
+❌ **Don't**:
+- Hardcode colors in HTML
+- Use generic/overused color schemes
+- Skip contrast testing
+- Mix color formats (stick to OKLCH)
+
+### Animation Stage
+
+✅ **Do**:
+- Use micro-syntax for documentation
+- Keep animations under 400ms
+- Use transform/opacity for performance
+- Respect prefers-reduced-motion
+- Make animations purposeful
+
+❌ **Don't**:
+- Animate width/height (use scale)
+- Create distracting animations
+- Ignore performance implications
+- Skip accessibility considerations
+
+### Implementation Stage
+
+✅ **Do**:
+- Use single HTML file per design
+- Load Tailwind via script tag
+- Reference theme CSS file
+- Use !important for framework overrides
+- Test responsive behavior
+- Provide alt text for images
+- Use semantic HTML
+
+❌ **Don't**:
+- Split into multiple files
+- Load Tailwind as stylesheet
+- Inline all styles
+- Skip accessibility attributes
+- Use made-up image URLs
+- Use div soup (non-semantic HTML)
+
+---
+
+## File Management
+
+### Folder Structure
+
+```
+design_iterations/
+├── theme_1.css
+├── theme_2.css
+├── landing_1.html
+├── landing_1_1.html
+├── landing_1_2.html
+├── dashboard_1.html
+├── dashboard_1_1.html
+└── README.md (optional: design notes)
+```
+
+### Version Control
+
+**Track iterations**:
+- Initial: `design_1.html`
+- Iteration 1: `design_1_1.html`
+- Iteration 2: `design_1_2.html`
+- Iteration 3: `design_1_3.html`
+
+**New major version**:
+- Complete redesign: `design_2.html`
+- Then iterate: `design_2_1.html`, `design_2_2.html`
+
+---
+
+## Communication Patterns
+
+### Stage Transitions
+
+**After Layout**:
+```
+"Here's the proposed layout structure. The design uses a [description].
+Would you like to proceed with this layout, or should we make adjustments?"
+```
+
+**After Theme**:
+```
+"I've created a [style] theme with [key features]. The theme file is saved as theme_N.css.
+Does this match your vision, or would you like to adjust colors/typography?"
+```
+
+**After Animation**:
+```
+"Here's the animation plan using [timing/style]. All animations are optimized for performance.
+Are these animations appropriate, or should we adjust the timing/effects?"
+```
+
+**After Implementation**:
+```
+"I've created the complete design as {filename}.html. The design includes [key features].
+Please review and let me know if you'd like any changes or iterations."
+```
+
+### Iteration Requests
+
+**User requests change**:
+```
+"I'll update the design with [changes] and save it as {filename}_N.html.
+This preserves the previous version for reference."
+```
+
+---
+
+## Quality Checklist
+
+Before presenting each stage:
+
+**Layout Stage**:
+- [ ] ASCII wireframe is clear and detailed
+- [ ] Components are well-organized
+- [ ] Responsive behavior is planned
+- [ ] User approval requested
+
+**Theme Stage**:
+- [ ] Theme file created and saved
+- [ ] Colors use OKLCH format
+- [ ] Fonts loaded from Google Fonts
+- [ ] Contrast ratios meet WCAG AA
+- [ ] User approval requested
+
+**Animation Stage**:
+- [ ] Animations documented in micro-syntax
+- [ ] Timing is appropriate (< 400ms)
+- [ ] Performance optimized (transform/opacity)
+- [ ] Accessibility considered
+- [ ] User approval requested
+
+**Implementation Stage**:
+- [ ] Single HTML file created
+- [ ] Theme CSS referenced
+- [ ] Tailwind loaded via script tag
+- [ ] Icons initialized
+- [ ] Responsive design tested
+- [ ] Accessibility attributes added
+- [ ] Images use valid placeholder URLs
+- [ ] Semantic HTML used
+- [ ] User review requested
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+**Issue**: User wants to skip stages
+**Solution**: Explain benefits of structured approach, but accommodate if insisted
+
+**Issue**: Theme doesn't match user vision
+**Solution**: Iterate on theme file, create theme_2.css with adjustments
+
+**Issue**: Animations feel too slow/fast
+**Solution**: Adjust timing in micro-syntax, regenerate with new values
+
+**Issue**: Design doesn't work on mobile
+**Solution**: Review responsive breakpoints, add mobile-specific styles
+
+**Issue**: Colors have poor contrast
+**Solution**: Use WCAG contrast checker, adjust OKLCH lightness values
+
+---
+
+## References
+
+- [Design Systems Context](../development/design-systems.md)
+- [UI Styling Standards](../development/ui-styling-standards.md)
+- [Animation Patterns](../development/animation-patterns.md)
+- [Design Assets](../development/design-assets.md)
+- [ASCII Art Generator](https://www.asciiart.eu/)
+- [WCAG Contrast Checker](https://webaim.org/resources/contrastchecker/)

.opencode/context/data/README.md

@@ -0,0 +1,18 @@
+# Data Context
+
+This directory contains context files for data analysis, visualization, and statistical methods.
+
+## Available Context Files
+
+*No context files yet. This category is ready for data-related context.*
+
+## Planned Context Files
+
+- **analysis-frameworks.md** - Statistical analysis methods, hypothesis testing, A/B testing
+- **visualization-patterns.md** - Chart selection, dashboard design, data storytelling
+- **data-cleaning.md** - Data quality, cleaning techniques, validation methods
+- **sql-patterns.md** - Query optimization, common patterns, best practices
+
+## Usage
+
+These context files will be referenced by data-focused agents to ensure consistent analysis methodologies, visualization standards, and data quality practices.

.opencode/context/development/README.md

@@ -0,0 +1,46 @@
+# Development Context
+
+This directory contains context files for software development best practices, patterns, and guidelines.
+
+## Available Context Files
+
+### clean-code.md
+Core coding standards and best practices for writing clean, maintainable code across all languages.
+
+**Topics covered**:
+- Meaningful naming conventions
+- Function design principles
+- Error handling patterns
+- Language-specific guidelines (JavaScript, Python, Go, Rust)
+
+**Used by**: frontend-specialist, backend-specialist, devops-specialist, codebase-agent
+
+### react-patterns.md
+Modern React patterns, hooks usage, and component design principles.
+
+**Topics covered**:
+- Functional components and hooks
+- Custom hooks for reusable logic
+- State management patterns
+- Performance optimization
+- Code splitting and lazy loading
+
+**Used by**: frontend-specialist
+
+### api-design.md
+REST API design principles, GraphQL patterns, and API versioning strategies.
+
+**Topics covered**:
+- RESTful resource design
+- HTTP methods and status codes
+- GraphQL schema design
+- API versioning strategies
+- Authentication and authorization
+
+**Used by**: backend-specialist
+
+## Usage
+
+These context files are referenced by development-focused agents to ensure consistent coding standards and best practices across the project.
+
+Agents load these files before implementing code to align with established patterns and conventions.

.opencode/context/development/animation-patterns.md

@@ -0,0 +1,753 @@
+<!-- Context: development/animation-patterns | Priority: high | Version: 1.0 | Updated: 2025-12-09 -->
+# Animation Patterns
+
+## Overview
+
+Standards and patterns for UI animations, micro-interactions, and transitions. Animations should feel natural, purposeful, and enhance user experience without causing distraction.
+
+## Quick Reference
+
+**Timing**: 150-400ms for most interactions
+**Easing**: ease-out for entrances, ease-in for exits
+**Purpose**: Every animation should have a clear purpose
+**Performance**: Use transform and opacity for 60fps
+
+---
+
+## Animation Micro-Syntax
+
+### Notation Guide
+
+**Format**: `element: duration easing [properties] modifiers`
+
+**Symbols**:
+- `→` = transition from → to
+- `±` = oscillate/shake
+- `↗` = increase
+- `↘` = decrease
+- `∞` = infinite loop
+- `×N` = repeat N times
+- `+Nms` = delay N milliseconds
+
+**Properties**:
+- `Y` = translateY
+- `X` = translateX
+- `S` = scale
+- `R` = rotate
+- `α` = opacity
+- `bg` = background
+
+**Example**: `button: 200ms ease-out [S1→1.05, α0.8→1]`
+- Button scales from 1 to 1.05 and fades from 0.8 to 1 over 200ms with ease-out
+
+---
+
+## Core Animation Principles
+
+### Timing Standards
+
+```
+Ultra-fast:  100-150ms  (micro-feedback, hover states)
+Fast:        150-250ms  (button clicks, toggles)
+Standard:    250-350ms  (modals, dropdowns, navigation)
+Moderate:    350-500ms  (page transitions, complex animations)
+Slow:        500-800ms  (dramatic reveals, storytelling)
+```
+
+### Easing Functions
+
+```css
+/* Entrances - start slow, end fast */
+ease-out: cubic-bezier(0, 0, 0.2, 1);
+
+/* Exits - start fast, end slow */
+ease-in: cubic-bezier(0.4, 0, 1, 1);
+
+/* Both - smooth throughout */
+ease-in-out: cubic-bezier(0.4, 0, 0.2, 1);
+
+/* Bounce - playful, attention-grabbing */
+bounce: cubic-bezier(0.68, -0.55, 0.265, 1.55);
+
+/* Elastic - spring-like */
+elastic: cubic-bezier(0.68, -0.6, 0.32, 1.6);
+```
+
+### Performance Guidelines
+
+**60fps Animations** (GPU-accelerated):
+- ✅ `transform` (translate, scale, rotate)
+- ✅ `opacity`
+- ✅ `filter` (with caution)
+
+**Avoid** (causes reflow/repaint):
+- ❌ `width`, `height`
+- ❌ `top`, `left`, `right`, `bottom`
+- ❌ `margin`, `padding`
+
+---
+
+## Common UI Animation Patterns
+
+### Button Interactions
+
+```css
+/* Hover - subtle lift */
+.button {
+  transition: transform 200ms ease-out, box-shadow 200ms ease-out;
+}
+.button:hover {
+  transform: translateY(-2px);
+  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
+}
+
+/* Press - scale down */
+.button:active {
+  transform: scale(0.95);
+  transition: transform 100ms ease-in;
+}
+
+/* Ripple effect */
+@keyframes ripple {
+  from {
+    transform: scale(0);
+    opacity: 1;
+  }
+  to {
+    transform: scale(2);
+    opacity: 0;
+  }
+}
+.button::after {
+  animation: ripple 400ms ease-out;
+}
+```
+
+**Micro-syntax**:
+```
+buttonHover: 200ms ease-out [Y0→-2, shadow↗]
+buttonPress: 100ms ease-in [S1→0.95]
+ripple: 400ms ease-out [S0→2, α1→0]
+```
+
+### Card Interactions
+
+```css
+/* Hover - lift and shadow */
+.card {
+  transition: transform 300ms ease-out, box-shadow 300ms ease-out;
+}
+.card:hover {
+  transform: translateY(-4px);
+  box-shadow: 0 12px 24px rgba(0, 0, 0, 0.15);
+}
+
+/* Select - scale and highlight */
+.card.selected {
+  transform: scale(1.02);
+  background-color: var(--accent);
+  transition: all 200ms ease-out;
+}
+```
+
+**Micro-syntax**:
+```
+cardHover: 300ms ease-out [Y0→-4, shadow↗]
+cardSelect: 200ms ease-out [S1→1.02, bg→accent]
+```
+
+### Modal/Dialog Animations
+
+```css
+/* Backdrop fade in */
+.modal-backdrop {
+  animation: fadeIn 300ms ease-out;
+}
+@keyframes fadeIn {
+  from { opacity: 0; }
+  to { opacity: 1; }
+}
+
+/* Modal slide up and fade */
+.modal {
+  animation: slideUp 350ms ease-out;
+}
+@keyframes slideUp {
+  from {
+    transform: translateY(40px);
+    opacity: 0;
+  }
+  to {
+    transform: translateY(0);
+    opacity: 1;
+  }
+}
+
+/* Modal exit */
+.modal.closing {
+  animation: slideDown 250ms ease-in;
+}
+@keyframes slideDown {
+  from {
+    transform: translateY(0);
+    opacity: 1;
+  }
+  to {
+    transform: translateY(40px);
+    opacity: 0;
+  }
+}
+```
+
+**Micro-syntax**:
+```
+backdrop: 300ms ease-out [α0→1]
+modalEnter: 350ms ease-out [Y+40→0, α0→1]
+modalExit: 250ms ease-in [Y0→+40, α1→0]
+```
+
+### Dropdown/Menu Animations
+
+```css
+/* Dropdown slide and fade */
+.dropdown {
+  animation: dropdownOpen 200ms ease-out;
+  transform-origin: top;
+}
+@keyframes dropdownOpen {
+  from {
+    transform: scaleY(0.95);
+    opacity: 0;
+  }
+  to {
+    transform: scaleY(1);
+    opacity: 1;
+  }
+}
+```
+
+**Micro-syntax**:
+```
+dropdown: 200ms ease-out [scaleY0.95→1, α0→1]
+```
+
+### Sidebar/Drawer Animations
+
+```css
+/* Sidebar slide in */
+.sidebar {
+  animation: slideInLeft 350ms ease-out;
+}
+@keyframes slideInLeft {
+  from {
+    transform: translateX(-280px);
+    opacity: 0;
+  }
+  to {
+    transform: translateX(0);
+    opacity: 1;
+  }
+}
+
+/* Overlay fade */
+.overlay {
+  animation: overlayFade 300ms ease-out;
+}
+@keyframes overlayFade {
+  from {
+    opacity: 0;
+    backdrop-filter: blur(0);
+  }
+  to {
+    opacity: 1;
+    backdrop-filter: blur(4px);
+  }
+}
+```
+
+**Micro-syntax**:
+```
+sidebar: 350ms ease-out [X-280→0, α0→1]
+overlay: 300ms ease-out [α0→1, blur0→4px]
+```
+
+---
+
+## Message/Chat UI Animations
+
+### Message Entrance
+
+```css
+/* User message - slide from right */
+.message-user {
+  animation: slideInRight 400ms ease-out;
+}
+@keyframes slideInRight {
+  from {
+    transform: translateX(10px) translateY(20px);
+    opacity: 0;
+    scale: 0.9;
+  }
+  to {
+    transform: translateX(0) translateY(0);
+    opacity: 1;
+    scale: 1;
+  }
+}
+
+/* AI message - slide from left with bounce */
+.message-ai {
+  animation: slideInLeft 600ms cubic-bezier(0.68, -0.55, 0.265, 1.55);
+  animation-delay: 200ms;
+}
+@keyframes slideInLeft {
+  from {
+    transform: translateY(15px);
+    opacity: 0;
+    scale: 0.95;
+  }
+  to {
+    transform: translateY(0);
+    opacity: 1;
+    scale: 1;
+  }
+}
+```
+
+**Micro-syntax**:
+```
+userMsg: 400ms ease-out [Y+20→0, X+10→0, S0.9→1]
+aiMsg: 600ms bounce [Y+15→0, S0.95→1] +200ms
+```
+
+### Typing Indicator
+
+```css
+/* Typing dots animation */
+.typing-indicator span {
+  animation: typingDot 1400ms infinite;
+}
+.typing-indicator span:nth-child(2) {
+  animation-delay: 200ms;
+}
+.typing-indicator span:nth-child(3) {
+  animation-delay: 400ms;
+}
+@keyframes typingDot {
+  0%, 60%, 100% {
+    transform: translateY(0);
+    opacity: 0.4;
+  }
+  30% {
+    transform: translateY(-8px);
+    opacity: 1;
+  }
+}
+```
+
+**Micro-syntax**:
+```
+typing: 1400ms ∞ [Y±8, α0.4→1] stagger+200ms
+```
+
+### Status Indicators
+
+```css
+/* Online status pulse */
+.status-online {
+  animation: pulse 2000ms infinite;
+}
+@keyframes pulse {
+  0%, 100% {
+    opacity: 1;
+    scale: 1;
+  }
+  50% {
+    opacity: 0.6;
+    scale: 1.05;
+  }
+}
+```
+
+**Micro-syntax**:
+```
+status: 2000ms ∞ [α1→0.6→1, S1→1.05→1]
+```
+
+---
+
+## Form Input Animations
+
+### Focus States
+
+```css
+/* Input focus - ring and scale */
+.input {
+  transition: all 200ms ease-out;
+}
+.input:focus {
+  transform: scale(1.01);
+  box-shadow: 0 0 0 3px var(--ring);
+}
+
+/* Input blur - return to normal */
+.input:not(:focus) {
+  transition: all 150ms ease-in;
+}
+```
+
+**Micro-syntax**:
+```
+inputFocus: 200ms ease-out [S1→1.01, shadow+ring]
+inputBlur: 150ms ease-in [S1.01→1, shadow-ring]
+```
+
+### Validation States
+
+```css
+/* Error shake */
+.input-error {
+  animation: shake 400ms ease-in-out;
+}
+@keyframes shake {
+  0%, 100% { transform: translateX(0); }
+  25% { transform: translateX(-5px); }
+  75% { transform: translateX(5px); }
+}
+
+/* Success checkmark */
+.input-success::after {
+  animation: checkmark 600ms cubic-bezier(0.68, -0.55, 0.265, 1.55);
+}
+@keyframes checkmark {
+  from {
+    transform: scale(0) rotate(0deg);
+    opacity: 0;
+  }
+  to {
+    transform: scale(1.2) rotate(360deg);
+    opacity: 1;
+  }
+}
+```
+
+**Micro-syntax**:
+```
+error: 400ms ease-in-out [X±5] shake
+success: 600ms bounce [S0→1.2, R0→360°, α0→1]
+```
+
+---
+
+## Loading States
+
+### Skeleton Screens
+
+```css
+/* Skeleton shimmer */
+.skeleton {
+  animation: shimmer 2000ms infinite;
+  background: linear-gradient(
+    90deg,
+    var(--muted) 0%,
+    var(--accent) 50%,
+    var(--muted) 100%
+  );
+  background-size: 200% 100%;
+}
+@keyframes shimmer {
+  0% { background-position: 200% 0; }
+  100% { background-position: -200% 0; }
+}
+```
+
+**Micro-syntax**:
+```
+skeleton: 2000ms ∞ [bg: muted↔accent]
+```
+
+### Spinners
+
+```css
+/* Circular spinner */
+.spinner {
+  animation: spin 1000ms linear infinite;
+}
+@keyframes spin {
+  from { transform: rotate(0deg); }
+  to { transform: rotate(360deg); }
+}
+
+/* Pulsing dots */
+.loading-dots span {
+  animation: dotPulse 1500ms infinite;
+}
+.loading-dots span:nth-child(2) { animation-delay: 200ms; }
+.loading-dots span:nth-child(3) { animation-delay: 400ms; }
+@keyframes dotPulse {
+  0%, 80%, 100% { opacity: 0.3; scale: 0.8; }
+  40% { opacity: 1; scale: 1; }
+}
+```
+
+**Micro-syntax**:
+```
+spinner: 1000ms ∞ linear [R360°]
+dotPulse: 1500ms ∞ [α0.3→1→0.3, S0.8→1→0.8] stagger+200ms
+```
+
+### Progress Bars
+
+```css
+/* Indeterminate progress */
+.progress-bar {
+  animation: progress 2000ms ease-in-out infinite;
+}
+@keyframes progress {
+  0% { transform: translateX(-100%); }
+  50% { transform: translateX(0); }
+  100% { transform: translateX(100%); }
+}
+```
+
+**Micro-syntax**:
+```
+progress: 2000ms ∞ ease-in-out [X-100%→0→100%]
+```
+
+---
+
+## Scroll Animations
+
+### Scroll-Triggered Fade In
+
+```css
+/* Fade in on scroll */
+.fade-in-on-scroll {
+  opacity: 0;
+  transform: translateY(40px);
+  transition: opacity 500ms ease-out, transform 500ms ease-out;
+}
+.fade-in-on-scroll.visible {
+  opacity: 1;
+  transform: translateY(0);
+}
+```
+
+**Micro-syntax**:
+```
+scrollFadeIn: 500ms ease-out [Y+40→0, α0→1]
+```
+
+### Auto-Scroll
+
+```css
+/* Smooth scroll behavior */
+html {
+  scroll-behavior: smooth;
+}
+
+/* Scroll hint animation */
+.scroll-hint {
+  animation: scrollHint 800ms infinite;
+  animation-iteration-count: 3;
+}
+@keyframes scrollHint {
+  0%, 100% { transform: translateY(0); }
+  50% { transform: translateY(5px); }
+}
+```
+
+**Micro-syntax**:
+```
+autoScroll: 400ms smooth
+scrollHint: 800ms ∞×3 [Y±5]
+```
+
+---
+
+## Page Transitions
+
+### Route Changes
+
+```css
+/* Page fade out */
+.page-exit {
+  animation: fadeOut 200ms ease-in;
+}
+@keyframes fadeOut {
+  from { opacity: 1; }
+  to { opacity: 0; }
+}
+
+/* Page fade in */
+.page-enter {
+  animation: fadeIn 300ms ease-out;
+}
+@keyframes fadeIn {
+  from { opacity: 0; }
+  to { opacity: 1; }
+}
+```
+
+**Micro-syntax**:
+```
+pageExit: 200ms ease-in [α1→0]
+pageEnter: 300ms ease-out [α0→1]
+```
+
+---
+
+## Micro-Interactions
+
+### Hover Effects
+
+```css
+/* Link underline slide */
+.link {
+  position: relative;
+}
+.link::after {
+  content: '';
+  position: absolute;
+  bottom: 0;
+  left: 0;
+  width: 0;
+  height: 2px;
+  background: currentColor;
+  transition: width 250ms ease-out;
+}
+.link:hover::after {
+  width: 100%;
+}
+```
+
+**Micro-syntax**:
+```
+linkHover: 250ms ease-out [width0→100%]
+```
+
+### Toggle Switches
+
+```css
+/* Toggle slide */
+.toggle-switch {
+  transition: background-color 200ms ease-out;
+}
+.toggle-switch .thumb {
+  transition: transform 200ms ease-out;
+}
+.toggle-switch.on .thumb {
+  transform: translateX(20px);
+}
+```
+
+**Micro-syntax**:
+```
+toggle: 200ms ease-out [X0→20, bg→accent]
+```
+
+---
+
+## Animation Recipes
+
+### Chat UI Complete Animation System
+
+```
+## Core Message Flow
+userMsg: 400ms ease-out [Y+20→0, X+10→0, S0.9→1]
+aiMsg: 600ms bounce [Y+15→0, S0.95→1] +200ms
+typing: 1400ms ∞ [Y±8, α0.4→1] stagger+200ms
+status: 300ms ease-out [α0.6→1, S1→1.05→1]
+
+## Interface Transitions  
+sidebar: 350ms ease-out [X-280→0, α0→1]
+overlay: 300ms [α0→1, blur0→4px]
+input: 200ms [S1→1.01, shadow+ring] focus
+input: 150ms [S1.01→1, shadow-ring] blur
+
+## Button Interactions
+sendBtn: 150ms [S1→0.95→1, R±2°] press
+sendBtn: 200ms [S1→1.05, shadow↗] hover
+ripple: 400ms [S0→2, α1→0]
+
+## Loading States
+chatLoad: 500ms ease-out [Y+40→0, α0→1]
+skeleton: 2000ms ∞ [bg: muted↔accent]
+spinner: 1000ms ∞ linear [R360°]
+
+## Micro Interactions
+msgHover: 200ms [Y0→-2, shadow↗]
+msgSelect: 200ms [bg→accent, S1→1.02]
+error: 400ms [X±5] shake
+success: 600ms bounce [S0→1.2→1, R360°]
+
+## Scroll & Navigation
+autoScroll: 400ms smooth
+scrollHint: 800ms ∞×3 [Y±5]
+```
+
+---
+
+## Best Practices
+
+### Do's ✅
+
+- Keep animations under 400ms for most interactions
+- Use `transform` and `opacity` for 60fps performance
+- Provide purpose for every animation
+- Use ease-out for entrances, ease-in for exits
+- Test on low-end devices
+- Respect `prefers-reduced-motion`
+- Stagger animations for lists (50-100ms delay)
+- Use consistent timing across similar interactions
+
+### Don'ts ❌
+
+- Don't animate width/height (use scale instead)
+- Don't use animations longer than 800ms
+- Don't animate too many elements at once
+- Don't use animations without purpose
+- Don't ignore accessibility preferences
+- Don't use jarring/distracting animations
+- Don't animate on every interaction
+- Don't use complex easing for simple interactions
+
+---
+
+## Accessibility
+
+### Reduced Motion
+
+```css
+/* Respect user preferences */
+@media (prefers-reduced-motion: reduce) {
+  *,
+  *::before,
+  *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+  }
+}
+```
+
+### Focus Indicators
+
+```css
+/* Always animate focus states */
+:focus-visible {
+  outline: 2px solid var(--ring);
+  outline-offset: 2px;
+  transition: outline-offset 150ms ease-out;
+}
+```
+
+---
+
+## References
+
+- [Web Animation API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API)
+- [CSS Easing Functions](https://easings.net/)
+- [Animation Performance](https://web.dev/animations-guide/)
+- [Reduced Motion](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion)

.opencode/context/development/api-design.md

@@ -0,0 +1,384 @@
+# API Design Patterns
+
+**Category**: development  
+**Purpose**: REST API design principles, GraphQL patterns, and API versioning strategies  
+**Used by**: backend-specialist
+
+---
+
+## Overview
+
+This guide covers best practices for designing robust, scalable, and maintainable APIs, including REST, GraphQL, and versioning strategies.
+
+## REST API Design
+
+### 1. Resource-Based URLs
+
+**Use nouns, not verbs**:
+```
+# Bad
+GET  /getUsers
+POST /createUser
+POST /updateUser/123
+
+# Good
+GET    /users
+POST   /users
+PUT    /users/123
+PATCH  /users/123
+DELETE /users/123
+```
+
+### 2. HTTP Methods
+
+**Use appropriate HTTP methods**:
+- `GET` - Retrieve resources (idempotent, safe)
+- `POST` - Create new resources
+- `PUT` - Replace entire resource (idempotent)
+- `PATCH` - Partial update (idempotent)
+- `DELETE` - Remove resource (idempotent)
+
+### 3. Status Codes
+
+**Use standard HTTP status codes**:
+```
+2xx Success
+  200 OK - Successful GET, PUT, PATCH
+  201 Created - Successful POST
+  204 No Content - Successful DELETE
+
+4xx Client Errors
+  400 Bad Request - Invalid input
+  401 Unauthorized - Missing/invalid auth
+  403 Forbidden - Authenticated but not authorized
+  404 Not Found - Resource doesn't exist
+  409 Conflict - Resource conflict (e.g., duplicate)
+  422 Unprocessable Entity - Validation errors
+
+5xx Server Errors
+  500 Internal Server Error - Unexpected error
+  503 Service Unavailable - Temporary unavailability
+```
+
+### 4. Consistent Response Format
+
+**Standardize response structure**:
+```json
+// Success response
+{
+  "data": {
+    "id": "123",
+    "name": "John Doe",
+    "email": "john@example.com"
+  },
+  "meta": {
+    "timestamp": "2024-01-01T00:00:00Z"
+  }
+}
+
+// Error response
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Invalid input data",
+    "details": [
+      {
+        "field": "email",
+        "message": "Invalid email format"
+      }
+    ]
+  },
+  "meta": {
+    "timestamp": "2024-01-01T00:00:00Z",
+    "requestId": "abc-123"
+  }
+}
+
+// Collection response
+{
+  "data": [...],
+  "meta": {
+    "total": 100,
+    "page": 1,
+    "pageSize": 20,
+    "totalPages": 5
+  },
+  "links": {
+    "self": "/users?page=1",
+    "next": "/users?page=2",
+    "prev": null,
+    "first": "/users?page=1",
+    "last": "/users?page=5"
+  }
+}
+```
+
+### 5. Filtering, Sorting, Pagination
+
+**Support common query operations**:
+```
+# Filtering
+GET /users?status=active&role=admin
+
+# Sorting
+GET /users?sort=createdAt:desc,name:asc
+
+# Pagination
+GET /users?page=2&pageSize=20
+
+# Field selection
+GET /users?fields=id,name,email
+
+# Search
+GET /users?q=john
+```
+
+### 6. Nested Resources
+
+**Handle relationships appropriately**:
+```
+# Good - Shallow nesting
+GET /users/123/posts
+GET /posts?userId=123
+
+# Avoid - Deep nesting
+GET /users/123/posts/456/comments/789
+# Better
+GET /comments/789
+```
+
+## GraphQL Patterns
+
+### 1. Schema Design
+
+**Design clear, intuitive schemas**:
+```graphql
+type User {
+  id: ID!
+  name: String!
+  email: String!
+  posts: [Post!]!
+  createdAt: DateTime!
+}
+
+type Post {
+  id: ID!
+  title: String!
+  content: String!
+  author: User!
+  comments: [Comment!]!
+  publishedAt: DateTime
+}
+
+type Query {
+  user(id: ID!): User
+  users(filter: UserFilter, page: Int, pageSize: Int): UserConnection!
+  post(id: ID!): Post
+}
+
+type Mutation {
+  createUser(input: CreateUserInput!): User!
+  updateUser(id: ID!, input: UpdateUserInput!): User!
+  deleteUser(id: ID!): Boolean!
+}
+
+input CreateUserInput {
+  name: String!
+  email: String!
+}
+
+input UserFilter {
+  status: UserStatus
+  role: UserRole
+  search: String
+}
+```
+
+### 2. Resolver Patterns
+
+**Implement efficient resolvers**:
+```javascript
+const resolvers = {
+  Query: {
+    user: async (_, { id }, { dataSources }) => {
+      return dataSources.userAPI.getUser(id);
+    },
+    users: async (_, { filter, page, pageSize }, { dataSources }) => {
+      return dataSources.userAPI.getUsers({ filter, page, pageSize });
+    }
+  },
+  
+  User: {
+    posts: async (user, _, { dataSources }) => {
+      // Use DataLoader to batch requests
+      return dataSources.postAPI.getPostsByUserId(user.id);
+    }
+  },
+  
+  Mutation: {
+    createUser: async (_, { input }, { dataSources, user }) => {
+      // Check authorization
+      if (!user) throw new AuthenticationError('Not authenticated');
+      
+      // Validate input
+      const validatedInput = validateUserInput(input);
+      
+      // Create user
+      return dataSources.userAPI.createUser(validatedInput);
+    }
+  }
+};
+```
+
+### 3. DataLoader for N+1 Prevention
+
+**Batch and cache database queries**:
+```javascript
+import DataLoader from 'dataloader';
+
+const userLoader = new DataLoader(async (userIds) => {
+  const users = await db.users.findMany({
+    where: { id: { in: userIds } }
+  });
+  
+  // Return in same order as input
+  return userIds.map(id => users.find(u => u.id === id));
+});
+
+// Usage in resolver
+const user = await userLoader.load(userId);
+```
+
+## API Versioning
+
+### 1. URL Versioning
+
+**Version in the URL path**:
+```
+GET /v1/users
+GET /v2/users
+```
+
+**Pros**: Clear, easy to route  
+**Cons**: URL changes, harder to maintain multiple versions
+
+### 2. Header Versioning
+
+**Version in Accept header**:
+```
+GET /users
+Accept: application/vnd.myapi.v2+json
+```
+
+**Pros**: Clean URLs, flexible  
+**Cons**: Less visible, harder to test
+
+### 3. Deprecation Strategy
+
+**Communicate deprecation clearly**:
+```javascript
+// Response headers
+Deprecation: true
+Sunset: Sat, 31 Dec 2024 23:59:59 GMT
+Link: <https://api.example.com/v2/users>; rel="successor-version"
+
+// Response body
+{
+  "data": {...},
+  "meta": {
+    "deprecated": true,
+    "deprecationDate": "2024-12-31",
+    "migrationGuide": "https://docs.example.com/migration/v1-to-v2"
+  }
+}
+```
+
+## Authentication & Authorization
+
+### 1. JWT Tokens
+
+**Use JWT for stateless auth**:
+```javascript
+// Token structure
+{
+  "sub": "user-123",
+  "email": "user@example.com",
+  "role": "admin",
+  "iat": 1516239022,
+  "exp": 1516242622
+}
+
+// Middleware
+function authenticateToken(req, res, next) {
+  const token = req.headers.authorization?.split(' ')[1];
+  
+  if (!token) {
+    return res.status(401).json({ error: 'No token provided' });
+  }
+  
+  try {
+    const decoded = jwt.verify(token, process.env.JWT_SECRET);
+    req.user = decoded;
+    next();
+  } catch (error) {
+    return res.status(401).json({ error: 'Invalid token' });
+  }
+}
+```
+
+### 2. Role-Based Access Control
+
+**Implement RBAC**:
+```javascript
+function authorize(...roles) {
+  return (req, res, next) => {
+    if (!req.user) {
+      return res.status(401).json({ error: 'Not authenticated' });
+    }
+    
+    if (!roles.includes(req.user.role)) {
+      return res.status(403).json({ error: 'Insufficient permissions' });
+    }
+    
+    next();
+  };
+}
+
+// Usage
+app.delete('/users/:id', 
+  authenticateToken, 
+  authorize('admin'), 
+  deleteUser
+);
+```
+
+## Best Practices
+
+1. **Use HTTPS everywhere** - Encrypt all API traffic
+2. **Implement rate limiting** - Prevent abuse and ensure fair usage
+3. **Validate all inputs** - Never trust client data
+4. **Use proper error handling** - Return meaningful error messages
+5. **Document your API** - Use OpenAPI/Swagger or GraphQL introspection
+6. **Version your API** - Plan for breaking changes
+7. **Implement CORS properly** - Configure allowed origins carefully
+8. **Log requests and errors** - Enable debugging and monitoring
+9. **Use caching** - Implement ETags, Cache-Control headers
+10. **Test thoroughly** - Unit, integration, and contract tests
+
+## Anti-Patterns
+
+- ❌ **Exposing internal IDs** - Use UUIDs or opaque identifiers
+- ❌ **Returning too much data** - Support field selection
+- ❌ **Ignoring idempotency** - PUT/PATCH/DELETE should be idempotent
+- ❌ **Inconsistent naming** - Use camelCase or snake_case consistently
+- ❌ **Missing pagination** - Always paginate collections
+- ❌ **No rate limiting** - Protect against abuse
+- ❌ **Verbose error messages** - Don't leak implementation details
+- ❌ **Synchronous long operations** - Use async jobs for long tasks
+
+## References
+
+- REST API Design Rulebook by Mark Masse
+- GraphQL Best Practices (graphql.org)
+- API Design Patterns by JJ Geewax
+- OpenAPI Specification (swagger.io)

.opencode/context/development/clean-code.md

@@ -0,0 +1,176 @@
+# Clean Code Principles
+
+**Category**: development  
+**Purpose**: Core coding standards and best practices for writing clean, maintainable code  
+**Used by**: frontend-specialist, backend-specialist, devops-specialist, codebase-agent
+
+---
+
+## Overview
+
+Clean code is code that is easy to read, understand, and maintain. It follows consistent patterns, uses meaningful names, and is well-organized. This guide provides principles and patterns for writing clean code across all languages.
+
+## Core Principles
+
+### 1. Meaningful Names
+
+**Use intention-revealing names**:
+- Variable names should reveal intent
+- Function names should describe what they do
+- Class names should describe what they represent
+
+**Examples**:
+```javascript
+// Bad
+const d = new Date();
+const x = getUserData();
+
+// Good
+const currentDate = new Date();
+const activeUserProfile = getUserData();
+```
+
+### 2. Functions Should Do One Thing
+
+**Single Responsibility**:
+- Each function should have one clear purpose
+- Functions should be small (ideally < 20 lines)
+- Extract complex logic into separate functions
+
+**Example**:
+```javascript
+// Bad
+function processUser(user) {
+  validateUser(user);
+  saveToDatabase(user);
+  sendEmail(user);
+  logActivity(user);
+}
+
+// Good
+function processUser(user) {
+  const validatedUser = validateUser(user);
+  const savedUser = saveUserToDatabase(validatedUser);
+  notifyUser(savedUser);
+  return savedUser;
+}
+```
+
+### 3. Avoid Deep Nesting
+
+**Keep nesting shallow**:
+- Use early returns
+- Extract nested logic into functions
+- Prefer guard clauses
+
+**Example**:
+```javascript
+// Bad
+function processOrder(order) {
+  if (order) {
+    if (order.items.length > 0) {
+      if (order.total > 0) {
+        // process order
+      }
+    }
+  }
+}
+
+// Good
+function processOrder(order) {
+  if (!order) return;
+  if (order.items.length === 0) return;
+  if (order.total <= 0) return;
+  
+  // process order
+}
+```
+
+### 4. DRY (Don't Repeat Yourself)
+
+**Eliminate duplication**:
+- Extract common logic into reusable functions
+- Use composition over inheritance
+- Create utility functions for repeated patterns
+
+### 5. Error Handling
+
+**Handle errors explicitly**:
+- Use try-catch for expected errors
+- Provide meaningful error messages
+- Don't ignore errors silently
+
+**Example**:
+```javascript
+// Bad
+function fetchData() {
+  try {
+    return api.getData();
+  } catch (e) {
+    return null;
+  }
+}
+
+// Good
+async function fetchData() {
+  try {
+    return await api.getData();
+  } catch (error) {
+    logger.error('Failed to fetch data', { error });
+    throw new DataFetchError('Unable to retrieve data', { cause: error });
+  }
+}
+```
+
+## Best Practices
+
+1. **Write self-documenting code** - Code should explain itself through clear naming and structure
+2. **Keep functions pure when possible** - Avoid side effects, return new values instead of mutating
+3. **Use consistent formatting** - Follow language-specific style guides (Prettier, ESLint, etc.)
+4. **Write tests first** - TDD helps design better APIs and catch issues early
+5. **Refactor regularly** - Improve code structure as you learn more about the domain
+6. **Comment why, not what** - Code shows what, comments explain why
+7. **Use type systems** - TypeScript, type hints, or static analysis tools
+8. **Favor composition** - Build complex behavior from simple, reusable pieces
+
+## Anti-Patterns
+
+- ❌ **Magic numbers** - Use named constants instead of hardcoded values
+- ❌ **God objects** - Classes that do too much or know too much
+- ❌ **Premature optimization** - Optimize for readability first, performance second
+- ❌ **Clever code** - Simple and clear beats clever and complex
+- ❌ **Long parameter lists** - Use objects or configuration patterns instead
+- ❌ **Boolean flags** - Often indicate a function doing multiple things
+- ❌ **Mutable global state** - Leads to unpredictable behavior and bugs
+
+## Language-Specific Guidelines
+
+### JavaScript/TypeScript
+- Use `const` by default, `let` when needed, never `var`
+- Prefer arrow functions for callbacks
+- Use async/await over raw promises
+- Destructure objects and arrays for clarity
+
+### Python
+- Follow PEP 8 style guide
+- Use list comprehensions for simple transformations
+- Prefer context managers (`with` statements)
+- Use type hints for function signatures
+
+### Go
+- Follow effective Go guidelines
+- Use defer for cleanup
+- Handle errors explicitly
+- Keep interfaces small
+
+### Rust
+- Embrace ownership and borrowing
+- Use pattern matching
+- Prefer iterators over loops
+- Handle errors with Result types
+
+## References
+
+- Clean Code by Robert C. Martin
+- The Pragmatic Programmer by Hunt & Thomas
+- Refactoring by Martin Fowler

.opencode/context/development/design-assets.md

@@ -0,0 +1,567 @@
+<!-- Context: development/design-assets | Priority: medium | Version: 1.0 | Updated: 2025-12-09 -->
+# Design Assets
+
+## Overview
+
+Guidelines for images, icons, fonts, and other design assets in frontend development. Focus on using reliable CDN sources and placeholder services.
+
+## Quick Reference
+
+**Images**: Unsplash, placehold.co (never make up URLs)
+**Icons**: Lucide (default), Heroicons, Font Awesome
+**Fonts**: Google Fonts
+**CDN**: Use established CDN services only
+
+---
+
+## Image Guidelines
+
+### Placeholder Images
+
+**Rule**: NEVER make up image URLs. Always use known placeholder services.
+
+#### Unsplash (Recommended)
+
+**Random Images**:
+```html
+<!-- Random image (1200x800) -->
+<img src="https://source.unsplash.com/random/1200x800" alt="Random image">
+
+<!-- Random image with category -->
+<img src="https://source.unsplash.com/random/1200x800/?nature" alt="Nature image">
+<img src="https://source.unsplash.com/random/1200x800/?technology" alt="Technology image">
+<img src="https://source.unsplash.com/random/1200x800/?people" alt="People image">
+```
+
+**Categories Available**:
+- nature, landscape, mountains, ocean, forest
+- technology, computer, code, workspace
+- people, portrait, business, team
+- food, coffee, restaurant
+- architecture, building, interior
+- travel, city, street
+- abstract, pattern, texture
+
+**Specific Images**:
+```html
+<!-- Use photo ID for consistency -->
+<img src="https://images.unsplash.com/photo-1506905925346-21bda4d32df4" alt="Mountain landscape">
+```
+
+#### Placehold.co
+
+**Simple Placeholders**:
+```html
+<!-- Basic placeholder (800x600) -->
+<img src="https://placehold.co/800x600" alt="Placeholder">
+
+<!-- With custom colors (background/text) -->
+<img src="https://placehold.co/800x600/EEE/31343C" alt="Placeholder">
+
+<!-- With text -->
+<img src="https://placehold.co/800x600?text=Product+Image" alt="Product placeholder">
+
+<!-- Different formats -->
+<img src="https://placehold.co/800x600.png" alt="PNG placeholder">
+<img src="https://placehold.co/800x600.jpg" alt="JPG placeholder">
+<img src="https://placehold.co/800x600.webp" alt="WebP placeholder">
+```
+
+#### Picsum Photos
+
+**Random Photos**:
+```html
+<!-- Random photo (800x600) -->
+<img src="https://picsum.photos/800/600" alt="Random photo">
+
+<!-- Specific photo by ID -->
+<img src="https://picsum.photos/id/237/800/600" alt="Specific photo">
+
+<!-- Grayscale -->
+<img src="https://picsum.photos/800/600?grayscale" alt="Grayscale photo">
+
+<!-- Blur effect -->
+<img src="https://picsum.photos/800/600?blur=2" alt="Blurred photo">
+```
+
+### Image Best Practices
+
+```html
+<!-- Responsive image with srcset -->
+<img 
+  src="https://source.unsplash.com/random/800x600/?nature" 
+  srcset="
+    https://source.unsplash.com/random/400x300/?nature 400w,
+    https://source.unsplash.com/random/800x600/?nature 800w,
+    https://source.unsplash.com/random/1200x900/?nature 1200w
+  "
+  sizes="(max-width: 768px) 100vw, (max-width: 1200px) 50vw, 33vw"
+  alt="Nature landscape"
+  loading="lazy"
+>
+
+<!-- Background image with object-fit -->
+<div 
+  class="w-full h-64 bg-cover bg-center rounded-lg"
+  style="background-image: url('https://source.unsplash.com/random/1200x800/?workspace')"
+  role="img"
+  aria-label="Workspace background"
+></div>
+
+<!-- Modern picture element -->
+<picture>
+  <source 
+    srcset="https://source.unsplash.com/random/1200x800/?nature" 
+    media="(min-width: 1024px)"
+  >
+  <source 
+    srcset="https://source.unsplash.com/random/800x600/?nature" 
+    media="(min-width: 768px)"
+  >
+  <img 
+    src="https://source.unsplash.com/random/400x300/?nature" 
+    alt="Responsive nature image"
+    loading="lazy"
+  >
+</picture>
+```
+
+---
+
+## Icon Systems
+
+### Lucide Icons (Recommended Default)
+
+**Loading**:
+```html
+<!-- Load Lucide from CDN -->
+<script src="https://unpkg.com/lucide@latest/dist/umd/lucide.min.js"></script>
+
+<!-- Or specific version -->
+<script src="https://unpkg.com/lucide@0.294.0/dist/umd/lucide.min.js"></script>
+```
+
+**Usage**:
+```html
+<!-- Icon elements -->
+<i data-lucide="home"></i>
+<i data-lucide="user"></i>
+<i data-lucide="settings"></i>
+<i data-lucide="search"></i>
+<i data-lucide="menu"></i>
+<i data-lucide="x"></i>
+<i data-lucide="chevron-down"></i>
+<i data-lucide="arrow-right"></i>
+
+<!-- With custom size and color -->
+<i data-lucide="heart" class="w-6 h-6 text-red-500"></i>
+
+<!-- Initialize icons -->
+<script>
+  lucide.createIcons();
+</script>
+```
+
+**Common Icons**:
+```
+Navigation: home, menu, x, chevron-down, chevron-up, arrow-left, arrow-right
+User: user, user-plus, users, user-check, user-x
+Actions: edit, trash, save, download, upload, share, copy
+Communication: mail, message-circle, phone, send
+Media: image, video, music, file, folder
+UI: search, settings, bell, heart, star, bookmark
+Status: check, x, alert-circle, info, help-circle
+```
+
+### Heroicons
+
+**Loading**:
+```html
+<!-- Heroicons via CDN (inline SVG) -->
+<!-- Use individual icon imports or copy SVG code -->
+```
+
+**Usage**:
+```html
+<!-- Outline style (24x24) -->
+<svg class="w-6 h-6" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+  <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M3 12l2-2m0 0l7-7 7 7M5 10v10a1 1 0 001 1h3m10-11l2 2m-2-2v10a1 1 0 01-1 1h-3m-6 0a1 1 0 001-1v-4a1 1 0 011-1h2a1 1 0 011 1v4a1 1 0 001 1m-6 0h6" />
+</svg>
+
+<!-- Solid style (20x20) -->
+<svg class="w-5 h-5" fill="currentColor" viewBox="0 0 20 20">
+  <path d="M10.707 2.293a1 1 0 00-1.414 0l-7 7a1 1 0 001.414 1.414L4 10.414V17a1 1 0 001 1h2a1 1 0 001-1v-2a1 1 0 011-1h2a1 1 0 011 1v2a1 1 0 001 1h2a1 1 0 001-1v-6.586l.293.293a1 1 0 001.414-1.414l-7-7z" />
+</svg>
+```
+
+### Font Awesome
+
+**Loading**:
+```html
+<!-- Font Awesome Free CDN -->
+<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.0/css/all.min.css">
+```
+
+**Usage**:
+```html
+<!-- Solid icons -->
+<i class="fas fa-home"></i>
+<i class="fas fa-user"></i>
+<i class="fas fa-cog"></i>
+
+<!-- Regular icons -->
+<i class="far fa-heart"></i>
+<i class="far fa-star"></i>
+
+<!-- Brands -->
+<i class="fab fa-github"></i>
+<i class="fab fa-twitter"></i>
+<i class="fab fa-linkedin"></i>
+
+<!-- With sizing -->
+<i class="fas fa-home fa-2x"></i>
+<i class="fas fa-user fa-3x"></i>
+```
+
+### Icon Best Practices
+
+```html
+<!-- Always provide accessible labels -->
+<button aria-label="Close menu">
+  <i data-lucide="x"></i>
+</button>
+
+<!-- Use semantic HTML with icons -->
+<a href="#" class="flex items-center gap-2">
+  <i data-lucide="external-link" class="w-4 h-4"></i>
+  <span>Visit website</span>
+</a>
+
+<!-- Icon-only buttons need labels -->
+<button aria-label="Search" class="p-2">
+  <i data-lucide="search" class="w-5 h-5"></i>
+</button>
+
+<!-- Decorative icons should be hidden from screen readers -->
+<div>
+  <i data-lucide="star" aria-hidden="true"></i>
+  <span>Featured</span>
+</div>
+```
+
+---
+
+## Font Loading
+
+### Google Fonts (Recommended)
+
+**Loading**:
+```html
+<!-- Preconnect for performance -->
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+
+<!-- Load font families -->
+<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet">
+
+<!-- Multiple fonts -->
+<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet">
+```
+
+**Usage**:
+```css
+body {
+  font-family: 'Inter', sans-serif;
+}
+
+code, pre {
+  font-family: 'JetBrains Mono', monospace;
+}
+```
+
+**Popular Font Combinations**:
+
+```html
+<!-- Modern UI: Inter + JetBrains Mono -->
+<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet">
+
+<!-- Professional: Roboto + Roboto Mono -->
+<link href="https://fonts.googleapis.com/css2?family=Roboto:wght@400;500;700&family=Roboto+Mono:wght@400;500&display=swap" rel="stylesheet">
+
+<!-- Editorial: Playfair Display + Source Sans Pro -->
+<link href="https://fonts.googleapis.com/css2?family=Playfair+Display:wght@400;700&family=Source+Sans+Pro:wght@400;600&display=swap" rel="stylesheet">
+
+<!-- Friendly: Poppins + Space Mono -->
+<link href="https://fonts.googleapis.com/css2?family=Poppins:wght@400;500;600;700&family=Space+Mono:wght@400;700&display=swap" rel="stylesheet">
+```
+
+### Font Loading Strategies
+
+```html
+<!-- Optimal loading with font-display -->
+<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;600&display=swap" rel="stylesheet">
+
+<!-- Preload critical fonts -->
+<link rel="preload" href="/fonts/inter-var.woff2" as="font" type="font/woff2" crossorigin>
+
+<!-- Self-hosted fonts -->
+<style>
+  @font-face {
+    font-family: 'Inter';
+    src: url('/fonts/inter-var.woff2') format('woff2');
+    font-weight: 100 900;
+    font-display: swap;
+  }
+</style>
+```
+
+---
+
+## CDN Resources
+
+### CSS Frameworks
+
+```html
+<!-- Tailwind CSS -->
+<script src="https://cdn.tailwindcss.com"></script>
+
+<!-- Flowbite -->
+<link href="https://cdn.jsdelivr.net/npm/flowbite@2.0.0/dist/flowbite.min.css" rel="stylesheet">
+<script src="https://cdn.jsdelivr.net/npm/flowbite@2.0.0/dist/flowbite.min.js"></script>
+
+<!-- Bootstrap -->
+<link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css" rel="stylesheet">
+<script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/js/bootstrap.bundle.min.js"></script>
+```
+
+### JavaScript Libraries
+
+```html
+<!-- Alpine.js -->
+<script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3.x.x/dist/cdn.min.js"></script>
+
+<!-- HTMX -->
+<script src="https://unpkg.com/htmx.org@1.9.10"></script>
+
+<!-- Chart.js -->
+<script src="https://cdn.jsdelivr.net/npm/chart.js@4.4.0/dist/chart.umd.min.js"></script>
+```
+
+### Utility Libraries
+
+```html
+<!-- Animate.css -->
+<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/animate.css/4.1.1/animate.min.css">
+
+<!-- AOS (Animate On Scroll) -->
+<link href="https://unpkg.com/aos@2.3.1/dist/aos.css" rel="stylesheet">
+<script src="https://unpkg.com/aos@2.3.1/dist/aos.js"></script>
+```
+
+---
+
+## SVG Assets
+
+### Inline SVG
+
+```html
+<!-- Custom icon -->
+<svg class="w-6 h-6" viewBox="0 0 24 24" fill="none" stroke="currentColor">
+  <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 4v16m8-8H4" />
+</svg>
+
+<!-- Logo -->
+<svg class="h-8 w-auto" viewBox="0 0 100 40" fill="currentColor">
+  <path d="M10 10h80v20H10z" />
+</svg>
+```
+
+### SVG Backgrounds
+
+```html
+<!-- Pattern background -->
+<div class="w-full h-64" style="background-image: url('data:image/svg+xml,<svg xmlns=&quot;http://www.w3.org/2000/svg&quot; viewBox=&quot;0 0 80 80&quot;><path fill=&quot;%23f0f0f0&quot; d=&quot;M0 0h80v80H0z&quot;/><path fill=&quot;%23e0e0e0&quot; d=&quot;M0 0h40v40H0zm40 40h40v40H40z&quot;/></svg>')"></div>
+```
+
+---
+
+## Video Assets
+
+### Placeholder Videos
+
+```html
+<!-- Sample video from CDN -->
+<video class="w-full rounded-lg" controls>
+  <source src="https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4" type="video/mp4">
+  Your browser does not support the video tag.
+</video>
+
+<!-- Background video -->
+<video class="w-full h-screen object-cover" autoplay muted loop playsinline>
+  <source src="https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/ForBiggerBlazes.mp4" type="video/mp4">
+</video>
+```
+
+---
+
+## Asset Organization
+
+### File Structure
+
+```
+design_iterations/
+├── theme_1.css
+├── ui_1.html
+├── ui_1_1.html (iteration)
+├── ui_1_2.html (iteration)
+├── dashboard_1.html
+└── assets/
+    ├── images/
+    ├── icons/
+    └── fonts/
+```
+
+### Naming Conventions
+
+**Design Files**:
+- Initial: `{design_name}_1.html` (e.g., `table_1.html`)
+- Iterations: `{design_name}_1_1.html`, `{design_name}_1_2.html`
+- Theme files: `theme_1.css`, `theme_2.css`
+
+**Asset Files**:
+- Images: `hero-image.jpg`, `product-1.png`
+- Icons: `logo.svg`, `icon-menu.svg`
+- Fonts: `inter-var.woff2`, `jetbrains-mono.woff2`
+
+---
+
+## Performance Optimization
+
+### Image Optimization
+
+```html
+<!-- Lazy loading -->
+<img src="image.jpg" loading="lazy" alt="Description">
+
+<!-- Modern formats with fallback -->
+<picture>
+  <source srcset="image.webp" type="image/webp">
+  <source srcset="image.jpg" type="image/jpeg">
+  <img src="image.jpg" alt="Description">
+</picture>
+
+<!-- Responsive images -->
+<img 
+  srcset="image-400.jpg 400w, image-800.jpg 800w, image-1200.jpg 1200w"
+  sizes="(max-width: 768px) 100vw, 50vw"
+  src="image-800.jpg"
+  alt="Description"
+>
+```
+
+### Font Optimization
+
+```html
+<!-- Subset fonts (only load needed characters) -->
+<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;600&text=ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789&display=swap" rel="stylesheet">
+
+<!-- Preload critical fonts -->
+<link rel="preload" href="/fonts/inter.woff2" as="font" type="font/woff2" crossorigin>
+```
+
+### CDN Best Practices
+
+```html
+<!-- Use integrity hashes for security -->
+<script 
+  src="https://cdn.jsdelivr.net/npm/alpinejs@3.13.3/dist/cdn.min.js" 
+  integrity="sha384-..." 
+  crossorigin="anonymous"
+></script>
+
+<!-- Specify versions to avoid breaking changes -->
+<script src="https://unpkg.com/lucide@0.294.0/dist/umd/lucide.min.js"></script>
+```
+
+---
+
+## Best Practices
+
+### Do's ✅
+
+- Use established placeholder services (Unsplash, placehold.co)
+- Always provide alt text for images
+- Use Lucide as default icon library
+- Load fonts from Google Fonts
+- Use lazy loading for images
+- Provide responsive image srcsets
+- Use semantic SVG with accessible labels
+- Specify CDN versions for stability
+- Optimize images before deployment
+- Use modern image formats (WebP, AVIF)
+
+### Don'ts ❌
+
+- Don't make up image URLs
+- Don't use images without alt text
+- Don't load unnecessary icon libraries
+- Don't use too many font families (2-3 max)
+- Don't skip lazy loading
+- Don't use unoptimized images
+- Don't forget ARIA labels for icon buttons
+- Don't use latest CDN versions in production
+- Don't load fonts synchronously
+- Don't use decorative images in content
+
+---
+
+## Accessibility
+
+### Image Accessibility
+
+```html
+<!-- Informative image -->
+<img src="chart.png" alt="Sales increased 25% in Q4 2024">
+
+<!-- Decorative image -->
+<img src="decoration.png" alt="" role="presentation">
+
+<!-- Complex image with description -->
+<figure>
+  <img src="diagram.png" alt="System architecture diagram">
+  <figcaption>
+    The diagram shows three layers: frontend, API, and database.
+  </figcaption>
+</figure>
+```
+
+### Icon Accessibility
+
+```html
+<!-- Icon with visible text -->
+<button class="flex items-center gap-2">
+  <i data-lucide="trash" aria-hidden="true"></i>
+  <span>Delete</span>
+</button>
+
+<!-- Icon-only button -->
+<button aria-label="Delete item">
+  <i data-lucide="trash"></i>
+</button>
+
+<!-- Icon with screen reader text -->
+<button>
+  <i data-lucide="search" aria-hidden="true"></i>
+  <span class="sr-only">Search</span>
+</button>
+```
+
+---
+
+## References
+
+- [Unsplash Source](https://source.unsplash.com/)
+- [Placehold.co](https://placehold.co/)
+- [Lucide Icons](https://lucide.dev/)
+- [Google Fonts](https://fonts.google.com/)
+- [Web.dev Image Optimization](https://web.dev/fast/#optimize-your-images)

.opencode/context/development/design-systems.md

@@ -0,0 +1,381 @@
+<!-- Context: development/design-systems | Priority: high | Version: 1.0 | Updated: 2025-12-09 -->
+# Design Systems
+
+## Overview
+
+This context file provides reusable design system patterns, theme templates, and color systems for frontend design work. Use these as starting points for creating cohesive, professional UI designs.
+
+## Quick Reference
+
+**Color Format**: OKLCH (perceptually uniform color space)
+**Theme Variables**: CSS custom properties (--variable-name)
+**Font Sources**: Google Fonts
+**Responsive**: All designs must be mobile-first responsive
+
+---
+
+## Theme Patterns
+
+### Neo-Brutalism Style
+
+**Characteristics**: 90s web design aesthetic, bold borders, flat shadows, high contrast
+
+**Use Cases**: 
+- Retro/vintage applications
+- Bold, statement-making interfaces
+- Art/creative portfolios
+- Playful consumer apps
+
+**Theme Template**:
+
+```css
+:root {
+  /* Colors - High contrast, bold */
+  --background: oklch(1.0000 0 0);
+  --foreground: oklch(0 0 0);
+  --card: oklch(1.0000 0 0);
+  --card-foreground: oklch(0 0 0);
+  --popover: oklch(1.0000 0 0);
+  --popover-foreground: oklch(0 0 0);
+  --primary: oklch(0.6489 0.2370 26.9728);
+  --primary-foreground: oklch(1.0000 0 0);
+  --secondary: oklch(0.9680 0.2110 109.7692);
+  --secondary-foreground: oklch(0 0 0);
+  --muted: oklch(0.9551 0 0);
+  --muted-foreground: oklch(0.3211 0 0);
+  --accent: oklch(0.5635 0.2408 260.8178);
+  --accent-foreground: oklch(1.0000 0 0);
+  --destructive: oklch(0 0 0);
+  --destructive-foreground: oklch(1.0000 0 0);
+  --border: oklch(0 0 0);
+  --input: oklch(0 0 0);
+  --ring: oklch(0.6489 0.2370 26.9728);
+  
+  /* Chart colors */
+  --chart-1: oklch(0.6489 0.2370 26.9728);
+  --chart-2: oklch(0.9680 0.2110 109.7692);
+  --chart-3: oklch(0.5635 0.2408 260.8178);
+  --chart-4: oklch(0.7323 0.2492 142.4953);
+  --chart-5: oklch(0.5931 0.2726 328.3634);
+  
+  /* Sidebar */
+  --sidebar: oklch(0.9551 0 0);
+  --sidebar-foreground: oklch(0 0 0);
+  --sidebar-primary: oklch(0.6489 0.2370 26.9728);
+  --sidebar-primary-foreground: oklch(1.0000 0 0);
+  --sidebar-accent: oklch(0.5635 0.2408 260.8178);
+  --sidebar-accent-foreground: oklch(1.0000 0 0);
+  --sidebar-border: oklch(0 0 0);
+  --sidebar-ring: oklch(0.6489 0.2370 26.9728);
+  
+  /* Typography */
+  --font-sans: DM Sans, sans-serif;
+  --font-serif: ui-serif, Georgia, Cambria, "Times New Roman", Times, serif;
+  --font-mono: Space Mono, monospace;
+  
+  /* Border radius - Sharp corners */
+  --radius: 0px;
+  --radius-sm: calc(var(--radius) - 4px);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) + 4px);
+  
+  /* Shadows - Bold, offset shadows */
+  --shadow-2xs: 4px 4px 0px 0px hsl(0 0% 0% / 0.50);
+  --shadow-xs: 4px 4px 0px 0px hsl(0 0% 0% / 0.50);
+  --shadow-sm: 4px 4px 0px 0px hsl(0 0% 0% / 1.00), 4px 1px 2px -1px hsl(0 0% 0% / 1.00);
+  --shadow: 4px 4px 0px 0px hsl(0 0% 0% / 1.00), 4px 1px 2px -1px hsl(0 0% 0% / 1.00);
+  --shadow-md: 4px 4px 0px 0px hsl(0 0% 0% / 1.00), 4px 2px 4px -1px hsl(0 0% 0% / 1.00);
+  --shadow-lg: 4px 4px 0px 0px hsl(0 0% 0% / 1.00), 4px 4px 6px -1px hsl(0 0% 0% / 1.00);
+  --shadow-xl: 4px 4px 0px 0px hsl(0 0% 0% / 1.00), 4px 8px 10px -1px hsl(0 0% 0% / 1.00);
+  --shadow-2xl: 4px 4px 0px 0px hsl(0 0% 0% / 2.50);
+  
+  /* Spacing */
+  --tracking-normal: 0em;
+  --spacing: 0.25rem;
+}
+```
+
+---
+
+### Modern Dark Mode Style
+
+**Characteristics**: Clean, minimal, professional (Vercel/Linear aesthetic)
+
+**Use Cases**:
+- SaaS applications
+- Developer tools
+- Professional dashboards
+- Enterprise applications
+- Modern web apps
+
+**Theme Template**:
+
+```css
+:root {
+  /* Colors - Subtle, professional */
+  --background: oklch(1 0 0);
+  --foreground: oklch(0.1450 0 0);
+  --card: oklch(1 0 0);
+  --card-foreground: oklch(0.1450 0 0);
+  --popover: oklch(1 0 0);
+  --popover-foreground: oklch(0.1450 0 0);
+  --primary: oklch(0.2050 0 0);
+  --primary-foreground: oklch(0.9850 0 0);
+  --secondary: oklch(0.9700 0 0);
+  --secondary-foreground: oklch(0.2050 0 0);
+  --muted: oklch(0.9700 0 0);
+  --muted-foreground: oklch(0.5560 0 0);
+  --accent: oklch(0.9700 0 0);
+  --accent-foreground: oklch(0.2050 0 0);
+  --destructive: oklch(0.5770 0.2450 27.3250);
+  --destructive-foreground: oklch(1 0 0);
+  --border: oklch(0.9220 0 0);
+  --input: oklch(0.9220 0 0);
+  --ring: oklch(0.7080 0 0);
+  
+  /* Chart colors - Monochromatic blues */
+  --chart-1: oklch(0.8100 0.1000 252);
+  --chart-2: oklch(0.6200 0.1900 260);
+  --chart-3: oklch(0.5500 0.2200 263);
+  --chart-4: oklch(0.4900 0.2200 264);
+  --chart-5: oklch(0.4200 0.1800 266);
+  
+  /* Sidebar */
+  --sidebar: oklch(0.9850 0 0);
+  --sidebar-foreground: oklch(0.1450 0 0);
+  --sidebar-primary: oklch(0.2050 0 0);
+  --sidebar-primary-foreground: oklch(0.9850 0 0);
+  --sidebar-accent: oklch(0.9700 0 0);
+  --sidebar-accent-foreground: oklch(0.2050 0 0);
+  --sidebar-border: oklch(0.9220 0 0);
+  --sidebar-ring: oklch(0.7080 0 0);
+  
+  /* Typography - System fonts */
+  --font-sans: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, 'Noto Sans', sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol', 'Noto Color Emoji';
+  --font-serif: ui-serif, Georgia, Cambria, "Times New Roman", Times, serif;
+  --font-mono: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;
+  
+  /* Border radius - Rounded */
+  --radius: 0.625rem;
+  --radius-sm: calc(var(--radius) - 4px);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) + 4px);
+  
+  /* Shadows - Subtle, soft */
+  --shadow-2xs: 0 1px 3px 0px hsl(0 0% 0% / 0.05);
+  --shadow-xs: 0 1px 3px 0px hsl(0 0% 0% / 0.05);
+  --shadow-sm: 0 1px 3px 0px hsl(0 0% 0% / 0.10), 0 1px 2px -1px hsl(0 0% 0% / 0.10);
+  --shadow: 0 1px 3px 0px hsl(0 0% 0% / 0.10), 0 1px 2px -1px hsl(0 0% 0% / 0.10);
+  --shadow-md: 0 1px 3px 0px hsl(0 0% 0% / 0.10), 0 2px 4px -1px hsl(0 0% 0% / 0.10);
+  --shadow-lg: 0 1px 3px 0px hsl(0 0% 0% / 0.10), 0 4px 6px -1px hsl(0 0% 0% / 0.10);
+  --shadow-xl: 0 1px 3px 0px hsl(0 0% 0% / 0.10), 0 8px 10px -1px hsl(0 0% 0% / 0.10);
+  --shadow-2xl: 0 1px 3px 0px hsl(0 0% 0% / 0.25);
+  
+  /* Spacing */
+  --tracking-normal: 0em;
+  --spacing: 0.25rem;
+}
+```
+
+---
+
+## Typography System
+
+### Recommended Font Families
+
+**Monospace Fonts** (Code, technical interfaces):
+- JetBrains Mono
+- Fira Code
+- Source Code Pro
+- IBM Plex Mono
+- Roboto Mono
+- Space Mono
+- Geist Mono
+
+**Sans-Serif Fonts** (UI, body text):
+- Inter
+- Roboto
+- Open Sans
+- Poppins
+- Montserrat
+- Outfit
+- Plus Jakarta Sans
+- DM Sans
+- Geist
+- Space Grotesk
+
+**Display/Decorative Fonts**:
+- Oxanium
+- Architects Daughter
+
+**Serif Fonts** (Editorial, formal):
+- Merriweather
+- Playfair Display
+- Lora
+- Source Serif Pro
+- Libre Baskerville
+
+### Font Loading
+
+Always use Google Fonts for consistency and reliability:
+
+```html
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet">
+```
+
+---
+
+## Color System Guidelines
+
+### OKLCH Color Space
+
+Use OKLCH for perceptually uniform colors:
+- **L** (Lightness): 0-1 (0 = black, 1 = white)
+- **C** (Chroma): 0-0.4 (saturation)
+- **H** (Hue): 0-360 (color angle)
+
+**Format**: `oklch(L C H)`
+
+**Example**: `oklch(0.6489 0.2370 26.9728)` = vibrant orange
+
+### Color Palette Rules
+
+1. **Avoid Bootstrap Blue**: Unless explicitly requested, avoid generic blue (#007bff)
+2. **Semantic Colors**: Use meaningful color names (--primary, --destructive, --success)
+3. **Contrast**: Ensure WCAG AA compliance (4.5:1 for text)
+4. **Consistency**: Use theme variables, not hardcoded colors
+
+### Background/Foreground Pairing
+
+**Rule**: Background should contrast with content
+
+- Light component → Dark background
+- Dark component → Light background
+- Ensures visibility and visual hierarchy
+
+---
+
+## Shadow System
+
+### Shadow Scales
+
+Shadows create depth and hierarchy:
+
+- `--shadow-2xs`: Minimal elevation (1-2px)
+- `--shadow-xs`: Subtle lift (2-3px)
+- `--shadow-sm`: Small cards (3-4px)
+- `--shadow`: Default elevation (4-6px)
+- `--shadow-md`: Medium cards (6-8px)
+- `--shadow-lg`: Modals, dropdowns (8-12px)
+- `--shadow-xl`: Floating panels (12-16px)
+- `--shadow-2xl`: Maximum elevation (16-24px)
+
+### Shadow Styles
+
+**Soft Shadows** (Modern):
+```css
+box-shadow: 0 1px 3px 0px hsl(0 0% 0% / 0.10);
+```
+
+**Hard Shadows** (Neo-brutalism):
+```css
+box-shadow: 4px 4px 0px 0px hsl(0 0% 0% / 1.00);
+```
+
+---
+
+## Spacing System
+
+### Base Unit
+
+Use `--spacing: 0.25rem` (4px) as base unit
+
+### Scale
+
+- 1x = 0.25rem (4px)
+- 2x = 0.5rem (8px)
+- 3x = 0.75rem (12px)
+- 4x = 1rem (16px)
+- 6x = 1.5rem (24px)
+- 8x = 2rem (32px)
+- 12x = 3rem (48px)
+- 16x = 4rem (64px)
+
+---
+
+## Border Radius System
+
+### Radius Scales
+
+```css
+--radius-sm: calc(var(--radius) - 4px);
+--radius-md: calc(var(--radius) - 2px);
+--radius-lg: var(--radius);
+--radius-xl: calc(var(--radius) + 4px);
+```
+
+### Common Values
+
+- **Sharp** (Neo-brutalism): `--radius: 0px`
+- **Subtle** (Modern): `--radius: 0.375rem` (6px)
+- **Rounded** (Friendly): `--radius: 0.625rem` (10px)
+- **Pill** (Buttons): `--radius: 9999px`
+
+---
+
+## Usage Guidelines
+
+### When to Use Each Theme
+
+**Neo-Brutalism**:
+- ✅ Creative/artistic projects
+- ✅ Retro/vintage aesthetics
+- ✅ Bold, statement-making designs
+- ❌ Enterprise/corporate applications
+- ❌ Accessibility-critical interfaces
+
+**Modern Dark Mode**:
+- ✅ SaaS applications
+- ✅ Developer tools
+- ✅ Professional dashboards
+- ✅ Enterprise applications
+- ✅ Accessibility-critical interfaces
+
+### Customization
+
+1. Start with a base theme template
+2. Adjust primary/accent colors for brand
+3. Modify radius for desired feel
+4. Adjust shadows for depth preference
+5. Test contrast ratios for accessibility
+
+---
+
+## Best Practices
+
+✅ **Use CSS custom properties** for all theme values
+✅ **Test in light and dark modes** if applicable
+✅ **Validate color contrast** (WCAG AA minimum)
+✅ **Use semantic color names** (--primary, not --blue)
+✅ **Load fonts from Google Fonts** for reliability
+✅ **Apply consistent spacing** using the spacing scale
+✅ **Test responsive behavior** at all breakpoints
+
+❌ **Don't hardcode colors** in components
+❌ **Don't use generic blue** (#007bff) without reason
+❌ **Don't mix color formats** (stick to OKLCH)
+❌ **Don't skip contrast testing**
+❌ **Don't use too many font families** (2-3 max)
+
+---
+
+## References
+
+- [OKLCH Color Picker](https://oklch.com/)
+- [Google Fonts](https://fonts.google.com/)
+- [WCAG Contrast Checker](https://webaim.org/resources/contrastchecker/)
+- [Tailwind CSS Colors](https://tailwindcss.com/docs/customizing-colors)

.opencode/context/development/react-patterns.md

@@ -0,0 +1,328 @@
+# React Patterns & Best Practices
+
+**Category**: development  
+**Purpose**: Modern React patterns, hooks usage, and component design principles  
+**Used by**: frontend-specialist
+
+---
+
+## Overview
+
+This guide covers modern React patterns using functional components, hooks, and best practices for building scalable React applications.
+
+## Component Patterns
+
+### 1. Functional Components with Hooks
+
+**Always use functional components**:
+```jsx
+// Good
+function UserProfile({ userId }) {
+  const [user, setUser] = useState(null);
+  
+  useEffect(() => {
+    fetchUser(userId).then(setUser);
+  }, [userId]);
+  
+  return <div>{user?.name}</div>;
+}
+```
+
+### 2. Custom Hooks for Reusable Logic
+
+**Extract common logic into custom hooks**:
+```jsx
+// Custom hook
+function useUser(userId) {
+  const [user, setUser] = useState(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState(null);
+  
+  useEffect(() => {
+    setLoading(true);
+    fetchUser(userId)
+      .then(setUser)
+      .catch(setError)
+      .finally(() => setLoading(false));
+  }, [userId]);
+  
+  return { user, loading, error };
+}
+
+// Usage
+function UserProfile({ userId }) {
+  const { user, loading, error } = useUser(userId);
+  
+  if (loading) return <Spinner />;
+  if (error) return <Error message={error.message} />;
+  return <div>{user.name}</div>;
+}
+```
+
+### 3. Composition Over Props Drilling
+
+**Use composition to avoid prop drilling**:
+```jsx
+// Bad - Props drilling
+function App() {
+  const [theme, setTheme] = useState('light');
+  return <Layout theme={theme} setTheme={setTheme} />;
+}
+
+// Good - Composition with Context
+const ThemeContext = createContext();
+
+function App() {
+  const [theme, setTheme] = useState('light');
+  return (
+    <ThemeContext.Provider value={{ theme, setTheme }}>
+      <Layout />
+    </ThemeContext.Provider>
+  );
+}
+
+function Layout() {
+  const { theme } = useContext(ThemeContext);
+  return <div className={theme}>...</div>;
+}
+```
+
+### 4. Compound Components
+
+**For complex, related components**:
+```jsx
+function Tabs({ children }) {
+  const [activeTab, setActiveTab] = useState(0);
+  
+  return (
+    <TabsContext.Provider value={{ activeTab, setActiveTab }}>
+      {children}
+    </TabsContext.Provider>
+  );
+}
+
+Tabs.List = function TabsList({ children }) {
+  return <div className="tabs-list">{children}</div>;
+};
+
+Tabs.Tab = function Tab({ index, children }) {
+  const { activeTab, setActiveTab } = useContext(TabsContext);
+  return (
+    <button 
+      className={activeTab === index ? 'active' : ''}
+      onClick={() => setActiveTab(index)}
+    >
+      {children}
+    </button>
+  );
+};
+
+Tabs.Panel = function TabPanel({ index, children }) {
+  const { activeTab } = useContext(TabsContext);
+  return activeTab === index ? <div>{children}</div> : null;
+};
+
+// Usage
+<Tabs>
+  <Tabs.List>
+    <Tabs.Tab index={0}>Tab 1</Tabs.Tab>
+    <Tabs.Tab index={1}>Tab 2</Tabs.Tab>
+  </Tabs.List>
+  <Tabs.Panel index={0}>Content 1</Tabs.Panel>
+  <Tabs.Panel index={1}>Content 2</Tabs.Panel>
+</Tabs>
+```
+
+## Hooks Best Practices
+
+### 1. useEffect Dependencies
+
+**Always specify dependencies correctly**:
+```jsx
+// Bad - Missing dependencies
+useEffect(() => {
+  fetchData(userId);
+}, []);
+
+// Good - Correct dependencies
+useEffect(() => {
+  fetchData(userId);
+}, [userId]);
+
+// Good - Stable function reference
+const fetchData = useCallback((id) => {
+  api.getUser(id).then(setUser);
+}, []);
+
+useEffect(() => {
+  fetchData(userId);
+}, [userId, fetchData]);
+```
+
+### 2. useMemo for Expensive Calculations
+
+**Memoize expensive computations**:
+```jsx
+function DataTable({ data, filters }) {
+  const filteredData = useMemo(() => {
+    return data.filter(item => 
+      filters.every(filter => filter(item))
+    );
+  }, [data, filters]);
+  
+  return <Table data={filteredData} />;
+}
+```
+
+### 3. useCallback for Stable References
+
+**Prevent unnecessary re-renders**:
+```jsx
+function Parent() {
+  const [count, setCount] = useState(0);
+  
+  // Bad - New function on every render
+  const handleClick = () => setCount(c => c + 1);
+  
+  // Good - Stable function reference
+  const handleClick = useCallback(() => {
+    setCount(c => c + 1);
+  }, []);
+  
+  return <Child onClick={handleClick} />;
+}
+
+const Child = memo(function Child({ onClick }) {
+  return <button onClick={onClick}>Click</button>;
+});
+```
+
+## State Management Patterns
+
+### 1. Local State First
+
+**Start with local state, lift when needed**:
+```jsx
+// Local state
+function Counter() {
+  const [count, setCount] = useState(0);
+  return <button onClick={() => setCount(c => c + 1)}>{count}</button>;
+}
+
+// Lifted state when shared
+function App() {
+  const [count, setCount] = useState(0);
+  return (
+    <>
+      <Counter count={count} setCount={setCount} />
+      <Display count={count} />
+    </>
+  );
+}
+```
+
+### 2. useReducer for Complex State
+
+**Use reducer for related state updates**:
+```jsx
+const initialState = { count: 0, step: 1 };
+
+function reducer(state, action) {
+  switch (action.type) {
+    case 'increment':
+      return { ...state, count: state.count + state.step };
+    case 'decrement':
+      return { ...state, count: state.count - state.step };
+    case 'setStep':
+      return { ...state, step: action.payload };
+    default:
+      return state;
+  }
+}
+
+function Counter() {
+  const [state, dispatch] = useReducer(reducer, initialState);
+  
+  return (
+    <>
+      <button onClick={() => dispatch({ type: 'decrement' })}>-</button>
+      <span>{state.count}</span>
+      <button onClick={() => dispatch({ type: 'increment' })}>+</button>
+    </>
+  );
+}
+```
+
+## Performance Optimization
+
+### 1. Code Splitting
+
+**Lazy load routes and heavy components**:
+```jsx
+import { lazy, Suspense } from 'react';
+
+const Dashboard = lazy(() => import('./Dashboard'));
+const Settings = lazy(() => import('./Settings'));
+
+function App() {
+  return (
+    <Suspense fallback={<Loading />}>
+      <Routes>
+        <Route path="/dashboard" element={<Dashboard />} />
+        <Route path="/settings" element={<Settings />} />
+      </Routes>
+    </Suspense>
+  );
+}
+```
+
+### 2. Virtualization for Long Lists
+
+**Use virtualization for large datasets**:
+```jsx
+import { FixedSizeList } from 'react-window';
+
+function VirtualList({ items }) {
+  const Row = ({ index, style }) => (
+    <div style={style}>{items[index].name}</div>
+  );
+  
+  return (
+    <FixedSizeList
+      height={600}
+      itemCount={items.length}
+      itemSize={50}
+      width="100%"
+    >
+      {Row}
+    </FixedSizeList>
+  );
+}
+```
+
+## Best Practices
+
+1. **Keep components small and focused** - Single responsibility principle
+2. **Use TypeScript** - Type safety prevents bugs and improves DX
+3. **Colocate related code** - Keep components, styles, and tests together
+4. **Use meaningful prop names** - Clear, descriptive names improve readability
+5. **Avoid inline functions in JSX** - Extract to named functions or useCallback
+6. **Use fragments** - Avoid unnecessary wrapper divs
+7. **Handle loading and error states** - Always show feedback to users
+8. **Test components** - Use React Testing Library for user-centric tests
+
+## Anti-Patterns
+
+- ❌ **Prop drilling** - Use context or composition instead
+- ❌ **Massive components** - Break down into smaller, focused components
+- ❌ **Mutating state directly** - Always use setState or dispatch
+- ❌ **Using index as key** - Use stable, unique identifiers
+- ❌ **Unnecessary useEffect** - Derive state when possible
+- ❌ **Ignoring ESLint warnings** - React hooks rules prevent bugs
+- ❌ **Not memoizing context values** - Causes unnecessary re-renders
+
+## References
+
+- React Documentation (react.dev)
+- React Patterns by Kent C. Dodds
+- Epic React by Kent C. Dodds

.opencode/context/development/ui-styling-standards.md

@@ -0,0 +1,552 @@
+<!-- Context: development/ui-styling-standards | Priority: high | Version: 1.0 | Updated: 2025-12-09 -->
+# UI Styling Standards
+
+## Overview
+
+Standards and conventions for CSS frameworks, responsive design, and styling best practices in frontend development.
+
+## Quick Reference
+
+**Framework**: Tailwind CSS + Flowbite (default)
+**Approach**: Mobile-first responsive
+**Format**: Utility-first CSS
+**Specificity**: Use `!important` for overrides when needed
+
+---
+
+## CSS Framework Conventions
+
+### Tailwind CSS
+
+**Loading Method** (Preferred):
+
+```html
+<!-- ✅ Use CDN script tag -->
+<script src="https://cdn.tailwindcss.com"></script>
+```
+
+**Avoid**:
+
+```html
+<!-- ❌ Don't use stylesheet link -->
+<link href="https://cdn.jsdelivr.net/npm/tailwindcss@2.2.19/dist/tailwind.min.css" rel="stylesheet">
+```
+
+**Why**: Script tag allows for JIT compilation and configuration
+
+### Flowbite
+
+**Loading Method**:
+
+```html
+<!-- Flowbite CSS -->
+<link href="https://cdn.jsdelivr.net/npm/flowbite@2.0.0/dist/flowbite.min.css" rel="stylesheet">
+
+<!-- Flowbite JS -->
+<script src="https://cdn.jsdelivr.net/npm/flowbite@2.0.0/dist/flowbite.min.js"></script>
+```
+
+**Usage**: Flowbite is the default component library unless user specifies otherwise
+
+**Components Available**:
+- Buttons, forms, modals
+- Navigation, dropdowns, tabs
+- Cards, alerts, badges
+- Tables, pagination
+- Tooltips, popovers
+
+---
+
+## Responsive Design Requirements
+
+### Mobile-First Approach
+
+**Rule**: ALL designs MUST be responsive
+
+**Breakpoints** (Tailwind defaults):
+
+```css
+/* Mobile first - base styles apply to mobile */
+.element { }
+
+/* Small devices (640px and up) */
+@media (min-width: 640px) { }  /* sm: */
+
+/* Medium devices (768px and up) */
+@media (min-width: 768px) { }  /* md: */
+
+/* Large devices (1024px and up) */
+@media (min-width: 1024px) { } /* lg: */
+
+/* Extra large devices (1280px and up) */
+@media (min-width: 1280px) { } /* xl: */
+
+/* 2XL devices (1536px and up) */
+@media (min-width: 1536px) { } /* 2xl: */
+```
+
+**Tailwind Syntax**:
+
+```html
+<!-- Mobile: stack, Desktop: side-by-side -->
+<div class="flex flex-col md:flex-row">
+  <div class="w-full md:w-1/2">Left</div>
+  <div class="w-full md:w-1/2">Right</div>
+</div>
+
+<!-- Mobile: full width, Desktop: constrained -->
+<div class="w-full lg:w-3/4 xl:w-1/2 mx-auto">
+  Content
+</div>
+```
+
+### Testing Requirements
+
+✅ Test at minimum breakpoints: 375px, 768px, 1024px, 1440px
+✅ Verify touch targets (min 44x44px)
+✅ Check text readability at all sizes
+✅ Ensure images scale properly
+✅ Test navigation on mobile
+
+---
+
+## Color Palette Guidelines
+
+### Avoid Bootstrap Blue
+
+**Rule**: NEVER use generic Bootstrap blue (#007bff) unless explicitly requested
+
+**Why**: Overused, lacks personality, feels dated
+
+**Alternatives**:
+
+```css
+/* Instead of Bootstrap blue */
+--bootstrap-blue: #007bff; /* ❌ Avoid */
+
+/* Use contextual colors */
+--primary: oklch(0.6489 0.2370 26.9728);    /* Vibrant orange */
+--accent: oklch(0.5635 0.2408 260.8178);     /* Rich purple */
+--info: oklch(0.6200 0.1900 260);            /* Modern blue */
+--success: oklch(0.7323 0.2492 142.4953);    /* Fresh green */
+```
+
+### Color Usage Rules
+
+1. **Semantic naming**: Use `--primary`, `--accent`, not `--blue`, `--red`
+2. **Brand alignment**: Choose colors that match project personality
+3. **Contrast testing**: Ensure WCAG AA compliance (4.5:1 minimum)
+4. **Consistency**: Use theme variables throughout
+
+---
+
+## Background/Foreground Contrast
+
+### Contrast Rule
+
+**When designing components or posters**:
+
+- **Light component** → Dark background
+- **Dark component** → Light background
+
+**Why**: Ensures visibility and creates visual hierarchy
+
+**Examples**:
+
+```html
+<!-- Light card on dark background -->
+<div class="bg-gray-900 p-8">
+  <div class="bg-white text-gray-900 p-6 rounded-lg">
+    Light card content
+  </div>
+</div>
+
+<!-- Dark card on light background -->
+<div class="bg-gray-50 p-8">
+  <div class="bg-gray-900 text-white p-6 rounded-lg">
+    Dark card content
+  </div>
+</div>
+```
+
+### Component-Specific Rules
+
+**Posters/Hero Sections**:
+- Use high contrast for readability
+- Consider overlay gradients for text on images
+- Test with actual content
+
+**Cards/Panels**:
+- Subtle elevation with shadows
+- Clear boundary between card and background
+- Consistent padding
+
+---
+
+## CSS Specificity & Overrides
+
+### Using !important
+
+**Rule**: Use `!important` for properties that might be overwritten by Tailwind or Flowbite
+
+**Common Cases**:
+
+```css
+/* Typography overrides */
+h1 {
+  font-size: 2.5rem !important;
+  font-weight: 700 !important;
+  line-height: 1.2 !important;
+}
+
+body {
+  font-family: 'Inter', sans-serif !important;
+  color: var(--foreground) !important;
+}
+
+/* Component overrides */
+.custom-button {
+  background-color: var(--primary) !important;
+  border-radius: var(--radius) !important;
+}
+```
+
+**When NOT to use**:
+
+```css
+/* ❌ Don't use for everything */
+.element {
+  margin: 1rem !important;
+  padding: 1rem !important;
+  display: flex !important;
+}
+
+/* ✅ Use Tailwind utilities instead */
+<div class="m-4 p-4 flex">
+```
+
+### Specificity Best Practices
+
+1. **Prefer utility classes** over custom CSS
+2. **Use !important sparingly** - only for framework overrides
+3. **Scope custom styles** to avoid conflicts
+4. **Use CSS custom properties** for theming
+
+---
+
+## Layout Patterns
+
+### Flexbox (Preferred for 1D layouts)
+
+```html
+<!-- Horizontal layout -->
+<div class="flex items-center gap-4">
+  <div>Item 1</div>
+  <div>Item 2</div>
+</div>
+
+<!-- Vertical layout -->
+<div class="flex flex-col gap-4">
+  <div>Item 1</div>
+  <div>Item 2</div>
+</div>
+
+<!-- Centered content -->
+<div class="flex items-center justify-center min-h-screen">
+  <div>Centered content</div>
+</div>
+```
+
+### Grid (Preferred for 2D layouts)
+
+```html
+<!-- Responsive grid -->
+<div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
+  <div>Card 1</div>
+  <div>Card 2</div>
+  <div>Card 3</div>
+</div>
+
+<!-- Dashboard layout -->
+<div class="grid grid-cols-12 gap-4">
+  <aside class="col-span-12 lg:col-span-3">Sidebar</aside>
+  <main class="col-span-12 lg:col-span-9">Content</main>
+</div>
+```
+
+### Container Patterns
+
+```html
+<!-- Centered container with max width -->
+<div class="container mx-auto px-4 max-w-7xl">
+  Content
+</div>
+
+<!-- Full-width section with contained content -->
+<section class="w-full bg-gray-50">
+  <div class="container mx-auto px-4 py-12 max-w-6xl">
+    Content
+  </div>
+</section>
+```
+
+---
+
+## Typography Standards
+
+### Hierarchy
+
+```html
+<!-- Heading scale -->
+<h1 class="text-4xl md:text-5xl lg:text-6xl font-bold">Main Heading</h1>
+<h2 class="text-3xl md:text-4xl font-semibold">Section Heading</h2>
+<h3 class="text-2xl md:text-3xl font-semibold">Subsection</h3>
+<h4 class="text-xl md:text-2xl font-medium">Minor Heading</h4>
+
+<!-- Body text -->
+<p class="text-base md:text-lg leading-relaxed">Body text</p>
+<p class="text-sm text-gray-600">Secondary text</p>
+<p class="text-xs text-gray-500">Caption text</p>
+```
+
+### Font Loading
+
+**Always use Google Fonts**:
+
+```html
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet">
+```
+
+**Apply in CSS**:
+
+```css
+body {
+  font-family: 'Inter', sans-serif !important;
+}
+```
+
+### Readability
+
+- **Line length**: 60-80 characters optimal
+- **Line height**: 1.5-1.75 for body text
+- **Font size**: Minimum 16px for body text
+- **Contrast**: 4.5:1 minimum for normal text
+
+---
+
+## Component Styling Patterns
+
+### Buttons
+
+```html
+<!-- Primary button -->
+<button class="bg-primary text-primary-foreground px-6 py-3 rounded-lg font-medium hover:opacity-90 transition-opacity">
+  Primary Action
+</button>
+
+<!-- Secondary button -->
+<button class="bg-secondary text-secondary-foreground px-6 py-3 rounded-lg font-medium hover:bg-secondary/80 transition-colors">
+  Secondary Action
+</button>
+
+<!-- Outline button -->
+<button class="border-2 border-primary text-primary px-6 py-3 rounded-lg font-medium hover:bg-primary hover:text-primary-foreground transition-all">
+  Outline Action
+</button>
+```
+
+### Cards
+
+```html
+<!-- Basic card -->
+<div class="bg-card text-card-foreground rounded-lg shadow-md p-6">
+  <h3 class="text-xl font-semibold mb-2">Card Title</h3>
+  <p class="text-muted-foreground">Card content</p>
+</div>
+
+<!-- Interactive card -->
+<div class="bg-card text-card-foreground rounded-lg shadow-md p-6 hover:shadow-lg transition-shadow cursor-pointer">
+  <h3 class="text-xl font-semibold mb-2">Interactive Card</h3>
+  <p class="text-muted-foreground">Hover for effect</p>
+</div>
+```
+
+### Forms
+
+```html
+<!-- Input field -->
+<div class="space-y-2">
+  <label class="block text-sm font-medium">Email</label>
+  <input 
+    type="email" 
+    class="w-full px-4 py-2 border border-input rounded-lg focus:ring-2 focus:ring-ring focus:border-transparent transition-all"
+    placeholder="you@example.com"
+  >
+</div>
+
+<!-- Textarea -->
+<div class="space-y-2">
+  <label class="block text-sm font-medium">Message</label>
+  <textarea 
+    class="w-full px-4 py-2 border border-input rounded-lg focus:ring-2 focus:ring-ring focus:border-transparent transition-all resize-none"
+    rows="4"
+    placeholder="Your message..."
+  ></textarea>
+</div>
+```
+
+---
+
+## Accessibility Standards
+
+### ARIA Labels
+
+```html
+<!-- Button with icon -->
+<button aria-label="Close dialog">
+  <svg>...</svg>
+</button>
+
+<!-- Navigation -->
+<nav aria-label="Main navigation">
+  <ul>...</ul>
+</nav>
+```
+
+### Semantic HTML
+
+```html
+<!-- ✅ Use semantic elements -->
+<header>...</header>
+<nav>...</nav>
+<main>...</main>
+<article>...</article>
+<aside>...</aside>
+<footer>...</footer>
+
+<!-- ❌ Avoid div soup -->
+<div class="header">...</div>
+<div class="nav">...</div>
+<div class="main">...</div>
+```
+
+### Focus States
+
+```css
+/* Always provide visible focus states */
+button:focus-visible {
+  outline: 2px solid var(--ring);
+  outline-offset: 2px;
+}
+
+/* Tailwind utility */
+<button class="focus:ring-2 focus:ring-ring focus:ring-offset-2">
+  Button
+</button>
+```
+
+---
+
+## Performance Optimization
+
+### CSS Loading
+
+```html
+<!-- Preconnect to font sources -->
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+
+<!-- Preload critical fonts -->
+<link rel="preload" href="/fonts/inter.woff2" as="font" type="font/woff2" crossorigin>
+```
+
+### Image Optimization
+
+```html
+<!-- Responsive images -->
+<img 
+  src="image-800.jpg" 
+  srcset="image-400.jpg 400w, image-800.jpg 800w, image-1200.jpg 1200w"
+  sizes="(max-width: 768px) 100vw, (max-width: 1200px) 50vw, 33vw"
+  alt="Description"
+  loading="lazy"
+>
+```
+
+### Critical CSS
+
+```html
+<!-- Inline critical CSS -->
+<style>
+  /* Above-the-fold styles */
+  body { margin: 0; font-family: system-ui; }
+  .hero { min-height: 100vh; }
+</style>
+
+<!-- Load full CSS async -->
+<link rel="stylesheet" href="styles.css" media="print" onload="this.media='all'">
+```
+
+---
+
+## Best Practices
+
+### Do's ✅
+
+- Use Tailwind utility classes for rapid development
+- Load Tailwind via script tag for JIT compilation
+- Use Flowbite as default component library
+- Ensure all designs are mobile-first responsive
+- Test at multiple breakpoints
+- Use semantic HTML elements
+- Provide ARIA labels for interactive elements
+- Use CSS custom properties for theming
+- Apply `!important` for framework overrides
+- Ensure proper color contrast (WCAG AA)
+
+### Don'ts ❌
+
+- Don't use Bootstrap blue without explicit request
+- Don't load Tailwind as a stylesheet
+- Don't skip responsive design
+- Don't use div soup (use semantic HTML)
+- Don't forget focus states
+- Don't hardcode colors (use theme variables)
+- Don't skip accessibility testing
+- Don't use tiny touch targets (<44px)
+- Don't mix color formats
+- Don't over-use `!important`
+
+---
+
+## Framework Alternatives
+
+If user requests a different framework:
+
+**Bootstrap**:
+```html
+<link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css" rel="stylesheet">
+<script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/js/bootstrap.bundle.min.js"></script>
+```
+
+**Bulma**:
+```html
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bulma@0.9.4/css/bulma.min.css">
+```
+
+**Foundation**:
+```html
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/foundation-sites@6.7.5/dist/css/foundation.min.css">
+<script src="https://cdn.jsdelivr.net/npm/foundation-sites@6.7.5/dist/js/foundation.min.js"></script>
+```
+
+---
+
+## References
+
+- [Tailwind CSS Documentation](https://tailwindcss.com/docs)
+- [Flowbite Components](https://flowbite.com/docs/getting-started/introduction/)
+- [WCAG Guidelines](https://www.w3.org/WAI/WCAG21/quickref/)
+- [MDN Web Accessibility](https://developer.mozilla.org/en-US/docs/Web/Accessibility)

.opencode/context/index.md

@@ -1,8 +1,10 @@
 # Context Index
 
+## Core Context (Universal)
+
 Path: `.opencode/context/core/{category}/{file}`
 
-## Quick Map
+### Quick Map
 ```
 code        → standards/code.md       [critical] implement, refactor, architecture
 docs        → standards/docs.md       [critical] write docs, README, documentation
@@ -16,6 +18,54 @@ breakdown   → workflows/task-breakdown.md [high] break down, 4+ files → deps
 sessions    → workflows/sessions.md   [medium]   session management, cleanup
 ```
 
+### Categories
+
+**Standards** - Code quality, testing, documentation standards (critical priority)
+**Workflows** - Process templates for delegation, review, task breakdown (high priority)
+**System** - Documentation and guides (medium priority)
+
+---
+
+## Category-Specific Context
+
+### Development
+Path: `.opencode/context/development/{file}`
+
+```
+clean-code      → development/clean-code.md      [high] coding standards, best practices
+react-patterns  → development/react-patterns.md  [high] React, hooks, components
+api-design      → development/api-design.md      [high] REST, GraphQL, API versioning
+```
+
+**Used by**: frontend-specialist, backend-specialist, devops-specialist, codebase-agent
+
+### Content
+Path: `.opencode/context/content/{file}`
+
+```
+copywriting     → content/copywriting-frameworks.md [high] AIDA, PAS, persuasive writing
+tone-voice      → content/tone-voice.md             [high] brand voice, tone guidelines
+```
+
+**Used by**: copywriter, technical-writer
+
+### Product
+Path: `.opencode/context/product/{file}`
+
+*No context files yet. Category ready for product-related context.*
+
+### Data
+Path: `.opencode/context/data/{file}`
+
+*No context files yet. Category ready for data-related context.*
+
+### Learning
+Path: `.opencode/context/learning/{file}`
+
+*No context files yet. Category ready for learning-related context.*
+
+---
+
 ## Loading Instructions
 
 **For common tasks, use quick map above. For keyword matching, scan triggers.**
@@ -23,9 +73,3 @@ sessions    → workflows/sessions.md   [medium]   session management, cleanup
 **Format:** `id → path [priority] triggers → deps: dependencies`
 
 **Dependencies:** Load dependent contexts alongside main context for complete guidelines.
-
-## Categories
-
-**Standards** - Code quality, testing, documentation standards (critical priority)
-**Workflows** - Process templates for delegation, review, task breakdown (high priority)
-**System** - Documentation and guides (medium priority)

.opencode/context/learning/README.md

@@ -0,0 +1,18 @@
+# Learning Context
+
+This directory contains context files for education, coaching, and teaching methodologies.
+
+## Available Context Files
+
+*No context files yet. This category is ready for learning-related context.*
+
+## Planned Context Files
+
+- **teaching-methods.md** - Pedagogical approaches, learning styles, instructional design
+- **cbt-techniques.md** - Cognitive behavioral therapy techniques, coaching frameworks
+- **curriculum-design.md** - Learning objectives, assessment methods, course structure
+- **feedback-methods.md** - Constructive feedback, growth mindset, motivation techniques
+
+## Usage
+
+These context files will be referenced by learning-focused agents to ensure consistent teaching methodologies, effective coaching techniques, and learner-centered approaches.

.opencode/context/product/README.md

@@ -0,0 +1,18 @@
+# Product Context
+
+This directory contains context files for product management, strategy, and user research.
+
+## Available Context Files
+
+*No context files yet. This category is ready for product-related context.*
+
+## Planned Context Files
+
+- **product-strategy.md** - Product vision, roadmap planning, prioritization frameworks
+- **user-research-methods.md** - User interview techniques, survey design, usability testing
+- **feature-prioritization.md** - RICE, MoSCoW, Kano model frameworks
+- **metrics-analytics.md** - Key metrics, analytics frameworks, data-driven decisions
+
+## Usage
+
+These context files will be referenced by product-focused agents to ensure consistent product strategy, user research methodologies, and data-driven decision making.

.opencode/prompts/content/copywriter/README.md

@@ -0,0 +1,48 @@
+# copywriter Prompt Variants
+
+## Default Prompt
+
+The **default prompt** is the agent file itself: `.opencode/agent/content/copywriter.md`
+
+This is optimized for **Claude** (Anthropic models) and serves as the baseline.
+
+## Model-Specific Variants
+
+This directory is ready for model-specific optimizations:
+
+| Variant | Model Family | Status | Best For |
+|---------|--------------|--------|----------|
+| gpt.md | GPT | 📝 Not yet created | GPT-4, GPT-4o |
+| llama.md | Llama/OSS | 📝 Not yet created | Llama, Qwen, DeepSeek |
+| gemini.md | Gemini | 📝 Not yet created | Gemini Pro, Gemini Ultra |
+
+## Creating Variants
+
+To create a model-specific variant:
+
+1. Copy the agent file as a starting point
+2. Adapt the prompt for the target model's characteristics
+3. Test with the eval framework
+4. Document results in this README
+
+## Testing Variants
+
+```bash
+cd evals/framework
+
+# Test default (agent file itself)
+npm run eval:sdk -- --agent=content/copywriter
+
+# Test model variants (when created)
+npm run eval:sdk -- --agent=content/copywriter --prompt-variant=gpt
+npm run eval:sdk -- --agent=content/copywriter --prompt-variant=llama
+```
+
+## Results
+
+| Variant | Pass Rate | Notes |
+|---------|-----------|-------|
+| default (agent file) | - | Not yet tested |
+| gpt | - | Not yet created |
+| llama | - | Not yet created |
+| gemini | - | Not yet created |

.opencode/prompts/content/technical-writer/README.md

@@ -0,0 +1,48 @@
+# technical writer Prompt Variants
+
+## Default Prompt
+
+The **default prompt** is the agent file itself: `.opencode/agent/content/technical-writer.md`
+
+This is optimized for **Claude** (Anthropic models) and serves as the baseline.
+
+## Model-Specific Variants
+
+This directory is ready for model-specific optimizations:
+
+| Variant | Model Family | Status | Best For |
+|---------|--------------|--------|----------|
+| gpt.md | GPT | 📝 Not yet created | GPT-4, GPT-4o |
+| llama.md | Llama/OSS | 📝 Not yet created | Llama, Qwen, DeepSeek |
+| gemini.md | Gemini | 📝 Not yet created | Gemini Pro, Gemini Ultra |
+
+## Creating Variants
+
+To create a model-specific variant:
+
+1. Copy the agent file as a starting point
+2. Adapt the prompt for the target model's characteristics
+3. Test with the eval framework
+4. Document results in this README
+
+## Testing Variants
+
+```bash
+cd evals/framework
+
+# Test default (agent file itself)
+npm run eval:sdk -- --agent=content/technical-writer
+
+# Test model variants (when created)
+npm run eval:sdk -- --agent=content/technical-writer --prompt-variant=gpt
+npm run eval:sdk -- --agent=content/technical-writer --prompt-variant=llama
+```
+
+## Results
+
+| Variant | Pass Rate | Notes |
+|---------|-----------|-------|
+| default (agent file) | - | Not yet tested |
+| gpt | - | Not yet created |
+| llama | - | Not yet created |
+| gemini | - | Not yet created |

.opencode/prompts/data/data-analyst/README.md

@@ -0,0 +1,39 @@
+# Data Analyst Prompt Variants
+
+## Default Prompt
+
+The **default prompt** is the agent file itself: `.opencode/agent/data/data-analyst.md`
+
+This is optimized for **Claude** (Anthropic models) and serves as the baseline.
+
+## Model-Specific Variants
+
+This directory is ready for model-specific optimizations:
+
+| Variant | Model Family | Status | Best For |
+|---------|--------------|--------|----------|
+| gpt.md | GPT | 📝 Not yet created | GPT-4, GPT-4o |
+| llama.md | Llama/OSS | 📝 Not yet created | Llama, Qwen, DeepSeek |
+| gemini.md | Gemini | 📝 Not yet created | Gemini Pro, Gemini Ultra |
+
+## Testing Variants
+
+```bash
+cd evals/framework
+
+# Test default (agent file itself)
+npm run eval:sdk -- --agent=data/data-analyst
+
+# Test model variants (when created)
+npm run eval:sdk -- --agent=data/data-analyst --prompt-variant=gpt
+npm run eval:sdk -- --agent=data/data-analyst --prompt-variant=llama
+```
+
+## Results
+
+| Variant | Pass Rate | Notes |
+|---------|-----------|-------|
+| default (agent file) | - | Not yet tested |
+| gpt | - | Not yet created |
+| llama | - | Not yet created |
+| gemini | - | Not yet created |

.opencode/prompts/development/backend-specialist/README.md

@@ -0,0 +1,48 @@
+# uackend specialist Prompt Variants
+
+## Default Prompt
+
+The **default prompt** is the agent file itself: `.opencode/agent/development/backend-specialist.md`
+
+This is optimized for **Claude** (Anthropic models) and serves as the baseline.
+
+## Model-Specific Variants
+
+This directory is ready for model-specific optimizations:
+
+| Variant | Model Family | Status | Best For |
+|---------|--------------|--------|----------|
+| gpt.md | GPT | 📝 Not yet created | GPT-4, GPT-4o |
+| llama.md | Llama/OSS | 📝 Not yet created | Llama, Qwen, DeepSeek |
+| gemini.md | Gemini | 📝 Not yet created | Gemini Pro, Gemini Ultra |
+
+## Creating Variants
+
+To create a model-specific variant:
+
+1. Copy the agent file as a starting point
+2. Adapt the prompt for the target model's characteristics
+3. Test with the eval framework
+4. Document results in this README
+
+## Testing Variants
+
+```bash
+cd evals/framework
+
+# Test default (agent file itself)
+npm run eval:sdk -- --agent=development/backend-specialist
+
+# Test model variants (when created)
+npm run eval:sdk -- --agent=development/backend-specialist --prompt-variant=gpt
+npm run eval:sdk -- --agent=development/backend-specialist --prompt-variant=llama
+```
+
+## Results
+
+| Variant | Pass Rate | Notes |
+|---------|-----------|-------|
+| default (agent file) | - | Not yet tested |
+| gpt | - | Not yet created |
+| llama | - | Not yet created |
+| gemini | - | Not yet created |

.opencode/prompts/development/devops-specialist/README.md

@@ -0,0 +1,48 @@
+# devops specialist Prompt Variants
+
+## Default Prompt
+
+The **default prompt** is the agent file itself: `.opencode/agent/development/devops-specialist.md`
+
+This is optimized for **Claude** (Anthropic models) and serves as the baseline.
+
+## Model-Specific Variants
+
+This directory is ready for model-specific optimizations:
+
+| Variant | Model Family | Status | Best For |
+|---------|--------------|--------|----------|
+| gpt.md | GPT | 📝 Not yet created | GPT-4, GPT-4o |
+| llama.md | Llama/OSS | 📝 Not yet created | Llama, Qwen, DeepSeek |
+| gemini.md | Gemini | 📝 Not yet created | Gemini Pro, Gemini Ultra |
+
+## Creating Variants
+
+To create a model-specific variant:
+
+1. Copy the agent file as a starting point
+2. Adapt the prompt for the target model's characteristics
+3. Test with the eval framework
+4. Document results in this README
+
+## Testing Variants
+
+```bash
+cd evals/framework
+
+# Test default (agent file itself)
+npm run eval:sdk -- --agent=development/devops-specialist
+
+# Test model variants (when created)
+npm run eval:sdk -- --agent=development/devops-specialist --prompt-variant=gpt
+npm run eval:sdk -- --agent=development/devops-specialist --prompt-variant=llama
+```
+
+## Results
+
+| Variant | Pass Rate | Notes |
+|---------|-----------|-------|
+| default (agent file) | - | Not yet tested |
+| gpt | - | Not yet created |
+| llama | - | Not yet created |
+| gemini | - | Not yet created |

.opencode/prompts/development/frontend-specialist/README.md

@@ -0,0 +1,48 @@
+# Frontend Specialist Prompt Variants
+
+## Default Prompt
+
+The **default prompt** is the agent file itself: `.opencode/agent/development/frontend-specialist.md`
+
+This is optimized for **Claude** (Anthropic models) and serves as the baseline.
+
+## Model-Specific Variants
+
+This directory is ready for model-specific optimizations:
+
+| Variant | Model Family | Status | Best For |
+|---------|--------------|--------|----------|
+| gpt.md | GPT | 📝 Not yet created | GPT-4, GPT-4o |
+| llama.md | Llama/OSS | 📝 Not yet created | Llama, Qwen, DeepSeek |
+| gemini.md | Gemini | 📝 Not yet created | Gemini Pro, Gemini Ultra |
+
+## Creating Variants
+
+To create a model-specific variant:
+
+1. Copy the agent file as a starting point
+2. Adapt the prompt for the target model's characteristics
+3. Test with the eval framework
+4. Document results in this README
+
+## Testing Variants
+
+```bash
+cd evals/framework
+
+# Test default (agent file itself)
+npm run eval:sdk -- --agent=development/frontend-specialist
+
+# Test model variants (when created)
+npm run eval:sdk -- --agent=development/frontend-specialist --prompt-variant=gpt
+npm run eval:sdk -- --agent=development/frontend-specialist --prompt-variant=llama
+```
+
+## Results
+
+| Variant | Pass Rate | Notes |
+|---------|-----------|-------|
+| default (agent file) | - | Not yet tested |
+| gpt | - | Not yet created |
+| llama | - | Not yet created |
+| gemini | - | Not yet created |

CHANGELOG.md

@@ -5,33 +5,88 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
-## [0.3.1] - 2025-12-09
+## [0.5.0] - 2025-12-10
+
+### Added
+- **Category-Based Agent Organization**: Agents now organized by domain in subdirectories
+  - `core/` - Core system agents (openagent, opencoder, system-builder)
+  - `development/` - Development specialists (frontend-specialist, backend-specialist, devops-specialist, codebase-agent)
+  - `content/` - Content creation agents (copywriter, technical-writer)
+  - `data/` - Data and analysis agents (data-analyst)
+  - `product/` - Product management agents (directory created, ready for agents)
+  - `learning/` - Education and coaching agents (directory created, ready for agents)
+- **Category Metadata Files**: Each category has `0-category.json` documenting common subagents, tools, and context
+- **Subagent Organization**: 13 subagents organized into 4 categories (code, core, system-builder, utils)
+- **Local Registry Fallback**: Install script now supports local `registry.json` for development/testing
+- **Enhanced Registry Validation**: Added checks for duplicate IDs and category consistency
+- **Comprehensive Test Suite**: 15 automated validation tests for category system
+- **Audit Tools**: Scripts to verify migration completeness and system integrity
+
+### Changed
+- **Agent File Structure**: Agents moved from flat structure to category-based organization
+  - Example: `.opencode/agent/openagent.md` → `.opencode/agent/core/openagent.md`
+  - Example: `.opencode/agent/opencoder.md` → `.opencode/agent/core/opencoder.md`
+- **Registry Schema**: Updated to include category-based paths for all agents
+- **Eval Framework**: Enhanced with path resolution supporting both agent IDs and category paths
+  - `--agent=openagent` resolves to `core/openagent` (backward compatible)
+  - `--agent=core/openagent` works directly (new format)
+- **Documentation**: Updated all docs to reference category-based structure
+- **Install Script**: Enhanced with local registry fallback for offline/development use
 
-### Changes
-- fix(ci): check only commit title for skip patterns (#46)
+### Fixed
+- **Frontend Specialist**: Renamed `frontend-design-agent.md` to `frontend-specialist.md` for consistency
+- **Eval Directory Structure**: Archived legacy flat eval structure to `_archive/` for clarity
+- **Registry Validation**: Fixed validation script to handle category-based paths correctly
 
+### Developer Experience
+- **Backward Compatibility**: Agent IDs like `openagent` still work via path resolution
+- **Local Testing**: No need to push to GitHub to test registry changes
+- **Clear Organization**: Agents grouped by domain make discovery easier
+- **Validation Tools**: Automated tests ensure system integrity
 
-_No unreleased changes yet._
+### Migration Notes
+- **Agent Paths**: Update references from flat to category-based paths
+  - Old: `.opencode/agent/openagent.md`
+  - New: `.opencode/agent/core/openagent.md`
+- **Eval Framework**: Both formats work due to path resolution
+  - `--agent=openagent` (backward compatible)
+  - `--agent=core/openagent` (new format)
+- **No Breaking Changes**: Path resolution maintains backward compatibility
+
+### Technical Details
+- **Files Modified**: 14+ files updated for category structure
+- **Agents Organized**: 23 total agents (10 category agents, 13 subagents)
+- **Test Coverage**: 15/15 validation tests passing (100%)
+- **Audit Status**: 8/8 checks passing (100%)
+
+## [0.3.1] - 2025-12-09
+
+### Fixed
+- CI: Check only commit title for skip patterns (#46)
 
 ## [0.0.2] - 2025-11-29
 
 ### Added
-- New `ExecutionBalanceEvaluator` in `evals/framework` to assess read vs execution ordering and ratio.
-- Contributor guide: `docs/contributing/ADDING_EVALUATOR.md` (English) describing evaluator design principles.
-- Test cases under `evals/agents/openagent/tests/10-execution-balance/` (positive & negative scenarios).
+- New `ExecutionBalanceEvaluator` in `evals/framework` to assess read vs execution ordering and ratio
+- Contributor guide: `docs/contributing/ADDING_EVALUATOR.md` describing evaluator design principles
+- Test cases under `evals/agents/openagent/tests/10-execution-balance/` (positive & negative scenarios)
 
 ### Changed
-- Framework README updated with section documenting `ExecutionBalanceEvaluator` and violation codes.
+- Framework README updated with section documenting `ExecutionBalanceEvaluator` and violation codes
 
 ---
 
 ## Version Format
 
 ```
-v0.0.X
+v0.X.Y
 │ │ │
-│ │ └─ Patch version (increments with each release)
-│ └─── Minor version (feature additions)
-└───── Major version (breaking changes)
+│ │ └─ Patch version (bug fixes, minor changes)
+│ └─── Minor version (new features, non-breaking changes)
+└───── Major version (breaking changes, major milestones)
 ```
+
+### Version History
+- **0.5.0** - Category-based agent organization system
+- **0.3.1** - CI improvements
+- **0.0.2** - Execution balance evaluator

QUICK_START.md

@@ -203,7 +203,7 @@ npm run test:openagent:developer -- --debug
 npm run dashboard:open
 
 # 3. Iterate on agent prompts
-# Edit .opencode/agent/openagent.md
+# Edit .opencode/agent/core/openagent.md
 
 # 4. Re-run tests
 npm run test:openagent:developer

README.md

@@ -425,8 +425,12 @@ A: Yes! Use the installer's list feature to see all components:
 ```
 Or cherry-pick individual files with curl:
 ```bash
-curl -o ~/.opencode/agent/opencoder.md \
-  https://raw.githubusercontent.com/darrenhinde/OpenAgents/main/.opencode/agent/opencoder.md
+# Create category directory first
+mkdir -p ~/.opencode/agent/core
+
+# Download specific agent
+curl -o ~/.opencode/agent/core/opencoder.md \
+  https://raw.githubusercontent.com/darrenhinde/OpenAgents/main/.opencode/agent/core/opencoder.md
 ```
 
 ---
@@ -512,11 +516,21 @@ Read [Agent System Blueprint](docs/features/agent-system-blueprint.md) to learn:
 ### Project Structure
 ```
 .opencode/
-├── agent/              # AI agents
-│   ├── openagent.md
-│   ├── opencoder.md
-│   ├── system-builder.md
-│   └── subagents/      # Specialized helpers
+├── agent/              # AI agents (category-based)
+│   ├── core/                    # Core system agents
+│   │   ├── openagent.md        # Universal orchestrator
+│   │   ├── opencoder.md        # Development specialist
+│   │   └── system-builder.md   # System architect
+│   ├── development/            # Development specialists
+│   │   ├── frontend-specialist.md
+│   │   ├── backend-specialist.md
+│   │   └── devops-specialist.md
+│   ├── content/               # Content creation
+│   │   ├── copywriter.md
+│   │   └── technical-writer.md
+│   ├── data/                  # Data & analysis
+│   │   └── data-analyst.md
+│   └── subagents/             # Specialized helpers
 ├── command/            # Slash commands
 │   ├── commit.md
 │   └── optimize.md

VERSION

@@ -1 +1 @@
-0.3.1
+0.5.0

docs/agents/category-system.md

@@ -0,0 +1,442 @@
+# Category-Based Agent System
+
+**Version**: 2.0.0  
+**Status**: Active  
+**Last Updated**: 2025-12-09
+
+---
+
+## 🎯 Overview
+
+The category-based agent system organizes agents into logical categories, making it easier to discover, contribute, and maintain domain-specific agents.
+
+### Key Concepts
+
+**Three-Tier Hierarchy**:
+1. **Core Agents** - Primary agents users interact with (orchestrator, coder)
+2. **Category Agents** - Domain-specific specialists (frontend, copywriter, etc.)
+3. **Subagents** - Delegated specialists called by core/category agents (tester, reviewer, etc.)
+
+---
+
+## 📁 Directory Structure
+
+```
+.opencode/agent/
+├── core/                    # Core Agents (System-level)
+│   ├── openagent.md         # Universal coordinator
+│   ├── opencoder.md         # Development specialist
+│   └── system-builder.md    # System architect
+│
+├── development/             # Development Specialists
+│   ├── frontend-specialist.md
+│   ├── backend-specialist.md
+│   ├── devops-specialist.md
+│   └── codebase-agent.md
+│
+├── content/                 # Content Creation
+│   ├── copywriter.md
+│   └── technical-writer.md
+│
+├── data/                    # Data & Analysis
+│   └── data-analyst.md
+│
+├── product/                 # Product & Strategy
+│   └── (empty - ready for contributions)
+│
+├── learning/                # Education & Coaching
+│   └── (empty - ready for contributions)
+│
+└── subagents/              # Delegated Specialists
+    ├── code/               # Code-related
+    ├── core/               # Core workflow
+    ├── system-builder/     # System generation
+    └── utils/              # Utilities
+```
+
+---
+
+## 🔧 Using Category Agents
+
+### Installation
+
+```bash
+# Install all development agents
+./install.sh developer
+
+# Install specific profile
+./install.sh full
+```
+
+### Running Tests
+
+```bash
+cd evals/framework
+
+# Test core agent
+npm run eval:sdk -- --agent=core/openagent
+
+# Test category agent
+npm run eval:sdk -- --agent=development/frontend-specialist
+
+# Test subagent
+npm run eval:sdk -- --agent=subagents/code/tester
+```
+
+### Agent Invocation
+
+**Core Agents** - Direct invocation:
+```bash
+opencode --agent core/openagent
+opencode --agent core/opencoder
+```
+
+**Category Agents** - Direct invocation:
+```bash
+opencode --agent development/frontend-specialist
+opencode --agent content/copywriter
+```
+
+**Subagents** - Via task delegation:
+```javascript
+// From core or category agent
+task(
+  subagent_type="subagents/code/tester",
+  description="Write tests",
+  prompt="Create comprehensive tests for the authentication module"
+)
+```
+
+---
+
+## 📊 Categories
+
+### Core (`core/`)
+
+**Purpose**: System-level agents maintained by the repository
+
+**Agents**:
+- `core/openagent` - Universal task coordinator
+- `core/opencoder` - Development specialist
+- `core/system-builder` - System architect
+
+**When to use**: Primary agents for general tasks
+
+---
+
+### Development (`development/`)
+
+**Purpose**: Software development specialists
+
+**Agents**:
+- `development/frontend-specialist` - React, Vue, modern CSS
+- `development/backend-specialist` - APIs, databases, server-side
+- `development/devops-specialist` - CI/CD, infrastructure
+- `development/codebase-agent` - Multi-language implementation
+
+**When to use**: Domain-specific development tasks
+
+---
+
+### Content (`content/`)
+
+**Purpose**: Writing and content creation
+
+**Agents**:
+- `content/copywriter` - Marketing copy, brand messaging
+- `content/technical-writer` - Documentation, API docs
+
+**When to use**: Content creation and documentation
+
+---
+
+### Data (`data/`)
+
+**Purpose**: Data analysis and research
+
+**Agents**:
+- `data/data-analyst` - Data analysis, visualization, insights
+
+**When to use**: Data-driven tasks
+
+---
+
+### Product (`product/`)
+
+**Purpose**: Product management and strategy
+
+**Status**: Ready for contributions
+
+**Potential Agents**:
+- Product manager
+- User researcher
+- Business analyst
+
+---
+
+### Learning (`learning/`)
+
+**Purpose**: Education and coaching
+
+**Status**: Ready for contributions
+
+**Potential Agents**:
+- Tutor
+- CBT coach
+- Curriculum designer
+
+---
+
+## 🆚 Core vs Category vs Subagents
+
+### Core Agents
+
+**Characteristics**:
+- System-level, maintained by repository
+- General-purpose, work across domains
+- Primary entry points for users
+- Can delegate to category agents or subagents
+
+**Examples**: `core/openagent`, `core/opencoder`
+
+---
+
+### Category Agents
+
+**Characteristics**:
+- Domain-specific specialists
+- User-facing (can be invoked directly)
+- Community-contributed
+- Can delegate to subagents
+
+**Examples**: `development/frontend-specialist`, `content/copywriter`
+
+---
+
+### Subagents
+
+**Characteristics**:
+- Focused, single-purpose functionality
+- NOT directly invoked by users
+- Called via task delegation
+- Support core and category agents
+
+**Examples**: `subagents/code/tester`, `subagents/core/task-manager`
+
+---
+
+## 🔄 Backward Compatibility
+
+### Old Format Still Works
+
+The old flat structure is still supported:
+
+```bash
+# Old format (still works)
+npm run eval:sdk -- --agent=openagent
+npm run eval:sdk -- --agent=opencoder
+
+# New format (recommended)
+npm run eval:sdk -- --agent=core/openagent
+npm run eval:sdk -- --agent=core/opencoder
+```
+
+### Path Resolution
+
+The eval framework automatically resolves old agent names:
+- `openagent` → `core/openagent`
+- `opencoder` → `core/opencoder`
+- `system-builder` → `core/system-builder`
+
+### Deprecation Timeline
+
+- **v2.0.0** (current): New structure, old paths work with warnings
+- **v2.1.0**: Old paths still work, louder warnings
+- **v3.0.0**: Remove old paths (breaking change)
+
+---
+
+## 🤝 Contributing Category Agents
+
+See [ADDING_CATEGORY_AGENT.md](../contributing/ADDING_CATEGORY_AGENT.md) for detailed instructions.
+
+### Quick Start
+
+1. **Choose a category** (development, content, data, product, learning)
+2. **Create agent file**: `.opencode/agent/{category}/{agent-name}.md`
+3. **Add frontmatter** with metadata
+4. **Create tests**: `evals/agents/{category}/{agent-name}/`
+5. **Submit PR**
+
+### Agent File Template
+
+```markdown
+---
+id: agent-name
+name: Agent Name
+description: Brief description
+category: development
+type: standard
+version: 1.0.0
+author: your-name
+
+mode: primary
+model: anthropic/claude-sonnet-4-5
+temperature: 0.1
+
+tools:
+  read: true
+  write: true
+  edit: true
+  bash: false
+  glob: true
+  grep: true
+  task: true
+
+dependencies:
+  context:
+    - development/patterns
+  tools: []
+
+tags:
+  - development
+  - specialist
+---
+
+# Agent Name
+
+You are a specialist in...
+
+## Your Role
+
+[Define role and responsibilities]
+
+## Workflow
+
+1. **Analyze** - Understand the request
+2. **Plan** - Create implementation plan
+3. **Request Approval** - Present plan to user
+4. **Implement** - Execute following patterns
+5. **Validate** - Test and verify
+```
+
+---
+
+## 📚 Related Documentation
+
+- [Migration Guide](../guides/MIGRATION_V2.md) - Migrating from v1.x to v2.0
+- [Contributing Guide](../contributing/CONTRIBUTING.md) - General contribution guidelines
+- [Adding Category Agents](../contributing/ADDING_CATEGORY_AGENT.md) - Detailed agent creation guide
+- [Eval Framework](../../evals/framework/README.md) - Testing agents
+
+---
+
+## 🔍 Examples
+
+### Example 1: Using Frontend Specialist
+
+```bash
+# Install
+./install.sh developer
+
+# Test
+cd evals/framework
+npm run eval:sdk -- --agent=development/frontend-specialist
+
+# Use
+opencode --agent development/frontend-specialist
+```
+
+### Example 2: Creating a New Category Agent
+
+```bash
+# Create agent file
+vim .opencode/agent/product/product-manager.md
+
+# Create test structure
+mkdir -p evals/agents/product/product-manager/{config,tests}
+
+# Create smoke test
+vim evals/agents/product/product-manager/tests/smoke-test.yaml
+
+# Validate
+./scripts/registry/validate-agent-structure.sh
+
+# Test
+cd evals/framework
+npm run eval:sdk -- --agent=product/product-manager
+```
+
+### Example 3: Delegating to Subagent
+
+From a category agent:
+
+```javascript
+// Delegate test creation to tester subagent
+task(
+  subagent_type="subagents/code/tester",
+  description="Create tests",
+  prompt="Write comprehensive unit tests for the UserService class"
+)
+```
+
+---
+
+## ❓ FAQ
+
+### Q: Can I still use the old agent names?
+
+**A**: Yes! Old names like `openagent` and `opencoder` still work and will continue to work until v3.0.0.
+
+### Q: How do I know which category to use?
+
+**A**: Choose based on the agent's primary domain:
+- Code-related → `development/`
+- Writing-related → `content/`
+- Data-related → `data/`
+- Product-related → `product/`
+- Teaching-related → `learning/`
+
+### Q: Can an agent be in multiple categories?
+
+**A**: No, each agent belongs to one category. If an agent spans multiple domains, choose the primary domain or create a more general agent in `core/`.
+
+### Q: What's the difference between a category agent and a subagent?
+
+**A**: 
+- **Category agents** are user-facing and can be invoked directly
+- **Subagents** are internal and only called via task delegation
+
+### Q: How do I test my category agent?
+
+**A**: Create a test suite in `evals/agents/{category}/{agent-name}/` and run:
+```bash
+cd evals/framework
+npm run eval:sdk -- --agent={category}/{agent-name}
+```
+
+---
+
+## 🎓 Best Practices
+
+1. **Choose the right category** - Place agents in their primary domain
+2. **Follow naming conventions** - Use kebab-case for agent IDs
+3. **Write comprehensive tests** - At least a smoke test
+4. **Document dependencies** - List required context files
+5. **Keep agents focused** - One domain, one responsibility
+6. **Use subagents** - Delegate complex subtasks
+
+---
+
+## 📊 System Statistics
+
+- **Categories**: 6 (core, development, content, data, product, learning)
+- **Core Agents**: 3
+- **Category Agents**: 7
+- **Subagents**: 13
+- **Total Agents**: 23
+
+---
+
+**Last Updated**: 2025-12-09  
+**Version**: 2.0.0

docs/agents/openagent.md

@@ -1011,7 +1011,7 @@ When making follow-up requests, reference previous work:
 
 ### 8. Customize Delegation Thresholds
 
-You can adjust when OpenAgent delegates by modifying the criteria in `.opencode/agent/openagent.md`:
+You can adjust when OpenAgent delegates by modifying the criteria in `.opencode/agent/core/openagent.md`:
 
 **Current defaults**:
 - 4+ files → Delegate to task-manager
@@ -1197,7 +1197,7 @@ OpenAgent is your **intelligent universal agent** that:
 
 ## Configuration
 
-OpenAgent is configured in `.opencode/agent/openagent.md`. You can customize:
+OpenAgent is configured in `.opencode/agent/core/openagent.md`. You can customize:
 - Delegation thresholds (when to delegate vs execute directly)
 - Execution philosophy (universal agent approach)
 - Critical rules enforcement

docs/agents/opencoder.md

@@ -389,7 +389,7 @@ OpenCoder adapts to your language:
 
 ## Configuration
 
-OpenCoder is configured in `.opencode/agent/opencoder.md`. Default settings:
+OpenCoder is configured in `.opencode/agent/core/opencoder.md`. Default settings:
 
 ```yaml
 temperature: 0.1  # Deterministic, precise

docs/contributing/CONTRIBUTING.md

@@ -14,11 +14,27 @@ Thank you for your interest in contributing! This guide will help you add new co
 ```
 opencode-agents/
 ├── .opencode/
-│   ├── agent/              # Agents
-│   │   ├── openagent.md        # Main orchestrator (always default in PRs)
-│   │   ├── opencoder.md        # Development specialist
+│   ├── agent/              # Agents (category-based)
+│   │   ├── core/
+│   │   │   ├── openagent.md        # Universal orchestrator
+│   │   │   ├── opencoder.md        # Development specialist
+│   │   │   └── system-builder.md   # System architect
+│   │   ├── development/
+│   │   │   ├── frontend-specialist.md
+│   │   │   └── backend-specialist.md
+│   │   ├── content/
+│   │   │   └── copywriter.md
 │   │   └── subagents/          # Specialized subagents
 │   ├── prompts/            # Prompt library (variants and experiments)
+│   │   ├── core/
+│   │   │   ├── openagent/
+│   │   │   │   ├── gpt.md
+│   │   │   │   └── llama.md
+│   │   │   └── opencoder/
+│   │   │       └── gpt.md
+│   │   └── development/
+│   │       └── frontend-specialist/
+│   │           └── gpt.md
 │   ├── command/            # Slash commands
 │   ├── tool/               # Utility tools
 │   ├── plugin/             # Integrations
@@ -36,11 +52,17 @@ opencode-agents/
     └── guides/             # User guides
 ```
 
+> **Note**: Agent files now use category-based organization. Core agents are in `core/`, 
+> development specialists in `development/`, etc. When referencing agents, use the 
+> category prefix: `core/openagent`, `development/frontend-specialist`.
+
 ### Key Directories
 
-- **`.opencode/agent/`** - Main agent prompts (openagent.md, opencoder.md)
+- **`.opencode/agent/core/`** - Core system agents (openagent.md, opencoder.md, system-builder.md)
+- **`.opencode/agent/development/`** - Development specialist agents
+- **`.opencode/agent/content/`** - Content creation agents
 - **`.opencode/agent/subagents/`** - Specialized subagents
-- **`.opencode/prompts/`** - Library of prompt variants for different models
+- **`.opencode/prompts/`** - Library of prompt variants for different models (category-based)
 - **`evals/`** - Testing framework and test suites
 - **`scripts/`** - Automation and utility scripts
 - **`docs/`** - Documentation and guides
@@ -217,17 +239,17 @@ OpenCode uses a model-specific prompt library to support different AI models whi
 
 ```bash
 # Test a specific variant
-./scripts/prompts/test-prompt.sh openagent sonnet-4
+./scripts/prompts/test-prompt.sh core/openagent sonnet-4
 
 # View results
-cat .opencode/prompts/openagent/results/sonnet-4-results.json
+cat .opencode/prompts/core/openagent/results/sonnet-4-results.json
 ```
 
 #### Creating a New Variant
 
 1. **Copy the template:**
    ```bash
-   cp .opencode/prompts/openagent/TEMPLATE.md .opencode/prompts/openagent/my-variant.md
+   cp .opencode/prompts/core/openagent/TEMPLATE.md .opencode/prompts/core/openagent/my-variant.md
    ```
 
 2. **Edit your variant:**
@@ -237,11 +259,11 @@ cat .opencode/prompts/openagent/results/sonnet-4-results.json
 
 3. **Test it:**
    ```bash
-   ./scripts/prompts/test-prompt.sh openagent my-variant
+   ./scripts/prompts/test-prompt.sh core/openagent my-variant
    ```
 
 4. **Update the README:**
-   - Add your variant to the capabilities table in `.opencode/prompts/openagent/README.md`
+   - Add your variant to the capabilities table in `.opencode/prompts/core/openagent/README.md`
    - Document test results
    - Explain what it optimizes for
 
@@ -249,7 +271,7 @@ cat .opencode/prompts/openagent/results/sonnet-4-results.json
    - Include your variant file (e.g., `my-variant.md`)
    - Include updated README with results
    - **Do NOT change the default prompt**
-   - **Do NOT change `.opencode/agent/openagent.md`**
+   - **Do NOT change `.opencode/agent/core/openagent.md`**
 
 #### PR Requirements for Prompts
 
@@ -261,8 +283,8 @@ Before submitting a PR:
 ./scripts/prompts/validate-pr.sh
 
 # If validation fails, restore defaults
-./scripts/prompts/use-prompt.sh openagent default
-./scripts/prompts/use-prompt.sh opencoder default
+./scripts/prompts/use-prompt.sh core/openagent default
+./scripts/prompts/use-prompt.sh core/opencoder default
 ```
 
 #### Why This System?
@@ -280,19 +302,19 @@ When a variant proves superior:
 
 1. **Verify test results:**
    ```bash
-   cat .opencode/prompts/openagent/results/variant-results.json
+   cat .opencode/prompts/core/openagent/results/variant-results.json
    ```
 
 2. **Update agent file (canonical default):**
    ```bash
-   cp .opencode/prompts/openagent/variant.md .opencode/agent/openagent.md
+   cp .opencode/prompts/core/openagent/variant.md .opencode/agent/core/openagent.md
    ```
 
 3. **Update capabilities table** in README
 
 4. **Commit with clear message:**
    ```bash
-   git add .opencode/agent/openagent.md
+   git add .opencode/agent/core/openagent.md
    git commit -m "feat(openagent): promote variant to default - improved X by Y%"
    ```
 

docs/contributing/DEVELOPMENT.md

@@ -57,9 +57,16 @@ npm test
 ```
 opencode-agents/
 ├── .opencode/                    # OpenCode configuration
-│   ├── agent/                    # Agent prompts
-│   │   ├── openagent.md          # Main orchestrator (plan-first)
-│   │   ├── opencoder.md          # Development specialist
+│   ├── agent/                    # Agent prompts (category-based)
+│   │   ├── core/
+│   │   │   ├── openagent.md          # Universal orchestrator
+│   │   │   ├── opencoder.md          # Development specialist
+│   │   │   └── system-builder.md     # System architect
+│   │   ├── development/
+│   │   │   ├── frontend-specialist.md
+│   │   │   └── backend-specialist.md
+│   │   ├── content/
+│   │   │   └── copywriter.md
 │   │   └── subagents/            # Specialized subagents
 │   │       ├── code/             # Code-related subagents
 │   │       ├── core/             # Core functionality subagents
@@ -74,9 +81,12 @@ opencode-agents/
 │   │   ├── project/              # Project-specific context
 │   │   └── system-builder-templates/  # Templates
 │   ├── plugin/                   # Plugins and integrations
-│   ├── prompts/                  # Prompt library (model variants)
-│   │   ├── openagent/            # OpenAgent variants
-│   │   └── opencoder/            # OpenCoder variants
+│   ├── prompts/                  # Prompt library (model variants, category-based)
+│   │   ├── core/
+│   │   │   ├── openagent/            # OpenAgent variants
+│   │   │   └── opencoder/            # OpenCoder variants
+│   │   └── development/
+│   │       └── frontend-specialist/  # Frontend specialist variants
 │   └── tool/                     # Utility tools
 ├── evals/                        # Testing framework
 │   ├── agents/                   # Agent test suites
@@ -101,9 +111,12 @@ opencode-agents/
 ### Key Directories Explained
 
 #### `.opencode/agent/`
-Main agent prompts. These are the "brains" of the system:
-- **openagent.md** - Main orchestrator with plan-first workflow
-- **opencoder.md** - Development specialist for direct code execution
+Main agent prompts organized by category. These are the "brains" of the system:
+- **core/openagent.md** - Universal orchestrator with plan-first workflow
+- **core/opencoder.md** - Development specialist for direct code execution
+- **core/system-builder.md** - System architecture generator
+- **development/** - Development specialist agents (frontend, backend, devops)
+- **content/** - Content creation agents (copywriter, technical-writer)
 - **subagents/** - Specialized helpers for specific tasks
 
 #### `.opencode/command/`
@@ -117,9 +130,10 @@ Context files that agents load on-demand:
 - **project/** - Project-specific context (CLAUDE.md pattern)
 
 #### `.opencode/prompts/`
-Prompt library with model-specific variants:
+Prompt library with model-specific variants (category-based structure):
 - Allows experimentation without breaking main branch
 - Each variant has test results documented
+- Organized by category matching agent structure (core/, development/, etc.)
 
 #### `evals/`
 Comprehensive testing framework:
@@ -653,16 +667,16 @@ npm test -- --agent=my-agent --test=new-test-001
 
 ```bash
 # 1. Copy template
-cp .opencode/prompts/openagent/TEMPLATE.md .opencode/prompts/openagent/my-variant.md
+cp .opencode/prompts/core/openagent/TEMPLATE.md .opencode/prompts/core/openagent/my-variant.md
 
 # 2. Edit variant
-vim .opencode/prompts/openagent/my-variant.md
+vim .opencode/prompts/core/openagent/my-variant.md
 
 # 3. Test variant
-./scripts/prompts/test-prompt.sh openagent my-variant
+./scripts/prompts/test-prompt.sh core/openagent my-variant
 
 # 4. Update README with results
-vim .opencode/prompts/openagent/README.md
+vim .opencode/prompts/core/openagent/README.md
 ```
 
 ### Validate Before PR
@@ -737,8 +751,8 @@ make validate-registry
 - [Test Design Guide](../../evals/framework/docs/test-design-guide.md) - Writing effective tests
 
 ### Examples
-- [OpenAgent](../../.opencode/agent/openagent.md) - Main orchestrator example
-- [OpenCoder](../../.opencode/agent/opencoder.md) - Development specialist example
+- [OpenAgent](../../.opencode/agent/core/openagent.md) - Universal orchestrator example
+- [OpenCoder](../../.opencode/agent/core/opencoder.md) - Development specialist example
 - [Subagents](../../.opencode/agent/subagents/) - Specialized subagent examples
 - [Test Suites](../../evals/agents/) - Comprehensive test examples
 

docs/features/prompt-library-system.md

@@ -10,7 +10,7 @@ Status: ✅ Production Ready
 ## 📋 Quick Links
 
 - [Main Prompts README](../../.opencode/prompts/README.md)
-- [OpenAgent Variants](../../.opencode/prompts/openagent/README.md)
+- [OpenAgent Variants](../../.opencode/prompts/core/openagent/README.md)
 - [Eval Framework Guide](../../evals/EVAL_FRAMEWORK_GUIDE.md)
 - [Test Suite Validation](../../evals/TEST_SUITE_VALIDATION.md)
 
@@ -74,7 +74,7 @@ See the comprehensive documentation files:
    - Testing workflow
    - Advanced usage
 
-2. **[OpenAgent Variants README](../../.opencode/prompts/openagent/README.md)**
+2. **[OpenAgent Variants README](../../.opencode/prompts/core/openagent/README.md)**
    - Capabilities matrix
    - Variant details
    - Test results
@@ -123,8 +123,8 @@ See the comprehensive documentation files:
 ### Key Files
 
 **Prompt Variants:**
-- `.opencode/prompts/openagent/*.md` - Variant files
-- `.opencode/prompts/openagent/results/*.json` - Per-variant results
+- `.opencode/prompts/core/openagent/*.md` - Variant files
+- `.opencode/prompts/core/openagent/results/*.json` - Per-variant results
 
 **Test Suites:**
 - `evals/agents/openagent/config/*.json` - Suite definitions
@@ -163,7 +163,7 @@ npm run eval:sdk -- --agent=openagent --prompt-variant=llama --pattern="01-criti
 
 ```bash
 # 1. Copy template
-cp .opencode/prompts/openagent/TEMPLATE.md .opencode/prompts/openagent/my-variant.md
+cp .opencode/prompts/core/openagent/TEMPLATE.md .opencode/prompts/core/openagent/my-variant.md
 
 # 2. Edit metadata and content
 # 3. Test

docs/getting-started/collision-handling.md

@@ -129,8 +129,8 @@ Use when:
 ⚠ Found 8 file collision(s):
 
   Agents (2):
-    .opencode/agent/task-manager.md
-    .opencode/agent/opencoder.md
+    .opencode/agent/core/task-manager.md
+    .opencode/agent/core/opencoder.md
     
   Subagents (3):
     .opencode/agent/subagents/reviewer.md

evals/agents/_archive/README.md

@@ -0,0 +1,65 @@
+# Archived Eval Tests
+
+**Status**: Archived (Legacy Structure)  
+**Date Archived**: 2025-12-10  
+**Reason**: Migrated to category-based structure
+
+---
+
+## What's Here
+
+This directory contains the **legacy flat eval structure** that was used before the category-based agent system (v2.0.0).
+
+### Archived Directories:
+- `openagent/` - Legacy OpenAgent eval tests (14 test suites)
+- `opencoder/` - Legacy OpenCoder eval tests
+
+---
+
+## Current Structure
+
+The new category-based eval structure is located at:
+
+```
+evals/agents/
+├── core/
+│   ├── openagent/      # ← New location
+│   ├── opencoder/      # ← New location
+│   └── system-builder/
+├── development/
+│   ├── frontend-specialist/
+│   └── backend-specialist/
+└── content/
+    └── copywriter/
+```
+
+---
+
+## Why Archived?
+
+1. **Category-based organization** - Agents are now organized by domain (core, development, content, etc.)
+2. **Simplified structure** - New tests use standardized smoke tests
+3. **Backward compatibility** - Old tests preserved here for reference
+
+---
+
+## Using Archived Tests
+
+If you need to reference or migrate tests from the legacy structure:
+
+1. **View test structure**: Browse the archived directories
+2. **Migrate tests**: Copy relevant tests to new category-based locations
+3. **Update paths**: Change agent paths from `openagent` to `core/openagent`
+
+---
+
+## Migration Notes
+
+The legacy tests were comprehensive but used an older structure. New tests should:
+- Use category-based agent paths (`core/openagent`, not `openagent`)
+- Follow the standardized test format
+- Be placed in the appropriate category directory
+
+---
+
+**For questions about test migration, see**: `docs/contributing/CONTRIBUTING.md`

evals/agents/openagent/config/config.yaml → evals/agents/_archive/openagent/config/config.yaml

@@ -1,4 +1,10 @@
 # OpenAgent Evaluation Configuration
+# 
+# NOTE: This is the LEGACY test structure for backward compatibility.
+# New tests should use the category-based structure: evals/agents/core/openagent/
+# 
+# The agent path "openagent" is automatically resolved to "core/openagent"
+# for backward compatibility.
 
 agent: openagent
 agent_path: ../../../../.opencode/agent/openagent.md