feat(lint): resolve all ESLint errors and complete compatibility layer (Issue #141) (#176)

* feat: implement compatibility layer foundation (Issue #141)

- Add TypeScript project setup with strict mode and Vitest
- Implement 20+ Zod validation schemas for OpenAgent format
- Create BaseAdapter abstract class with template method pattern
- Add context documentation for compatibility layer workflow
- Setup ESLint, TypeScript, and test configuration

Phase 1 Foundation: 50% complete (subtasks 01-03)
Related: #141

* feat: implement AgentLoader with TypeScript (Issue #141)

- Add AgentLoader class for loading OAC agent files
- Implement parseFrontmatter() for YAML extraction
- Add extractSections() for markdown parsing (skills, examples, commands, workflow)
- Create custom error classes: AgentLoadError, FrontmatterParseError, ValidationError
- Support single file and recursive directory loading
- Add metadata merging from agent-metadata.json
- Export convenience functions: loadAgent(), loadAgents()
- Full Zod schema validation with descriptive error messages
- 386 lines, type-safe with strict mode

Phase 1 Foundation: 66.7% complete (subtask 04/06)
Related: #141

* feat: implement AdapterRegistry with TypeScript (Issue #141)

- Add AdapterRegistry class for managing tool adapters
- Implement type-safe registration with Map<string, BaseAdapter>
- Add alias support for adapter names (case-insensitive)
- Create custom error class: AdapterRegistryError
- Implement methods: register(), get(), list(), has(), getAll(), unregister(), clear()
- Add capability-based adapter discovery: getCapabilities(), findByFeature()
- Export singleton registry instance and convenience functions
- Support lazy loading of built-in adapters (placeholder for Phase 2)
- 416 lines, fully type-safe with strict mode

Features:
- Duplicate registration prevention
- Alias conflict detection
- O(1) adapter lookup
- Sorted adapter listings
- Comprehensive JSDoc documentation

Phase 1 Foundation: 83.3% complete (subtask 05/06)
Related: #141

* feat: create main entry point index.ts (Issue #141)

- Add comprehensive barrel exports for public API
- Export all Zod schemas and TypeScript types
- Export AgentLoader class and convenience functions
- Export AdapterRegistry, singleton, and helpers
- Export error classes: AgentLoadError, FrontmatterParseError, ValidationError, AdapterRegistryError
- Export BaseAdapter for custom adapter creation
- Add package VERSION constant
- Include JSDoc documentation with usage examples
- Organized exports by category (types, core, adapters)
- 168 lines with comprehensive documentation

All exports:
- Types: All Zod schemas and inferred TypeScript types
- Core: AgentLoader, AdapterRegistry, registry singleton
- Adapters: BaseAdapter abstract class
- Errors: All custom error classes
- Utilities: Convenience functions (loadAgent, getAdapter, etc.)

Phase 1 Foundation: 100% COMPLETE! 🎉 (6/6 subtasks)
Related: #141

* feat: implement ClaudeAdapter with bidirectional conversion (Issue #141)

- Implement ClaudeAdapter extending BaseAdapter
- Support toOAC() conversion from Claude Code format to OAC
- Support fromOAC() conversion from OAC to Claude Code format
- Handle .claude/config.json for primary agents
- Handle .claude/agents/*.md for subagents with YAML frontmatter
- Map Claude Skills system to/from OAC contexts
- Map hooks (PreToolUse, PostToolUse, etc.) bidirectionally
- Degrade granular OAC permissions to Claude permissionMode
- Add warnings for unsupported features (temperature, maxSteps)
- Export ClaudeAdapter from main index.ts

Capabilities:
- supportsMultipleAgents: true
- supportsSkills: true
- supportsHooks: true
- supportsGranularPermissions: false (binary only)
- supportsTemperature: false
- Model ID mapping (claude-sonnet-4 <-> claude-sonnet-4-20250514)
- Tool access mapping (OAC ToolAccess <-> Claude tools array)

Subtask: compatibility-layer-141-07
Phase: 2 (Adapters Migration)

* feat: implement CursorAdapter with single-file format support (Issue #141)

- Implement CursorAdapter extending BaseAdapter
- Support toOAC() conversion from .cursorrules to OAC
- Support fromOAC() conversion from OAC to .cursorrules format
- Handle single-file limitation (no multiple agents)
- Implement mergeAgents() for combining multiple OAC agents
- Parse optional YAML frontmatter in .cursorrules
- Inline context files into .cursorrules content
- Add comprehensive warnings for lost features

Key limitations:
- supportsMultipleAgents: false (single .cursorrules file)
- supportsSkills: false (must inline content)
- supportsHooks: false (not supported by Cursor)
- supportsGranularPermissions: false (binary only)
- supportsTemperature: true (limited support)

Features:
- Model ID mapping (gpt-4, claude-3-opus, etc.)
- Tool access parsing and generation
- Context file inlining with references
- Multi-agent merge capability
- Frontmatter parsing for metadata

Export CursorAdapter from main index.ts

Subtask: compatibility-layer-141-08
Phase: 2 (Adapters Migration)

* feat: implement WindsurfAdapter with bidirectional conversion (Issue #141)

- Add WindsurfAdapter.ts (514 lines) extending BaseAdapter
- Support bidirectional OAC ↔ Windsurf JSON conversion
- Implement toOAC() for Windsurf config → OpenAgent parsing
- Implement fromOAC() for OpenAgent → Windsurf config generation
- Add temperature ↔ creativity setting mapping (low/medium/high)
- Add model ID mapping (claude-sonnet-4 ↔ claude-4-sonnet)
- Support multi-agent configuration via .windsurf/agents/
- Support context files via .windsurf/context/
- Implement binary permission mapping with degradation warnings
- Add priority level normalization (critical/high/medium/low → high/low)
- Export WindsurfAdapter in index.ts
- All adapters now complete: Claude, Cursor, Windsurf
- Compilation successful: 0 errors, 0 warnings

Phase 2 (Adapters): 50% complete (3/6 subtasks)
Total progress: 28.13% (9/32 subtasks)
Code stats: 3,333 lines TypeScript (Foundation + Adapters)

* docs: add compatibility layer context files and progress tracking (Issue #141)

- Add baseadapter-implementation.md with detailed adapter pattern and testing examples
- Add compatibility-layer-development.md with development workflow and best practices
- Add compatibility-layer-adapters.md lookup table with adapter specifications
- Add compatibility-layer-progress.md tracking Phase 1 completion and Phase 2 status
- Add compatibility-learnings.md documenting implementation learnings
- Update compatibility-layer.md with latest architecture insights

These context files support Phase 2 adapter unit testing and future adapter development.

* test: implement comprehensive unit tests for ClaudeAdapter (Issue #141 - Subtask 10)

Implemented 80 test cases covering:
- toOAC() parsing of config.json and agent.md (YAML frontmatter)
- fromOAC() conversion to config.json and agent.md formats
- Capabilities and feature validation
- Model, tool, skill, hook, and permission mapping
- Skill generation from contexts
- Edge cases and error handling
- Roundtrip conversion validation

Coverage achieved:
- 96.32% statements (target: 80%+) ✅
- 100% functions (target: 80%+) ✅
- 82.14% branches (target: 75%+) ✅

All test cases follow AAA pattern (Arrange-Act-Assert) and test standards
from .opencode/context/core/standards/test-coverage.md

* test: implement comprehensive unit tests for CursorAdapter (Issue #141 - Subtask 11)

Implemented 78 test cases covering:
- toOAC() parsing of plain .cursorrules and YAML frontmatter
- fromOAC() conversion to .cursorrules format
- Capabilities and feature validation
- Agent merging (CURSOR-SPECIFIC - unique feature)
- Model, tool mapping
- Context inlining
- Temperature and configuration handling
- Edge cases and error handling
- Roundtrip conversion validation

Coverage achieved:
- 98.55% statements (target: 80%+) ✅
- 100% functions (target: 80%+) ✅
- 89.65% branches (target: 75%+) ✅

Key test areas:
- Plain text .cursorrules parsing (no frontmatter)
- YAML frontmatter parsing with type coercion
- Agent merging (single, two, three+ agents)
- Tool union and temperature MAX behavior
- Context inlining with proper formatting
- Model mapping (Cursor ↔ OAC)

All test cases follow AAA pattern and test standards.

* test: implement comprehensive unit tests for WindsurfAdapter (Issue #141 - Subtask 12)

* feat: implement Phase 3 mappers and translation engine with tests (Issue #141)

- Add ToolMapper: maps tool names between OAC and Claude/Cursor/Windsurf
- Add PermissionMapper: translates granular to binary permissions
- Add ModelMapper: maps AI model IDs between platforms
- Add ContextMapper: maps context file paths between platforms
- Add CapabilityMatrix: feature compatibility analysis across platforms
- Add TranslationEngine: orchestrates all mappers for complete translation

Test coverage:
- ToolMapper: 100% statements, 100% branches
- PermissionMapper: 98% statements, 96% branches
- ModelMapper: 99% statements, 90% branches
- ContextMapper: 97% statements, 94% branches
- CapabilityMatrix: 99% statements, 96% branches
- TranslationEngine: 99% statements, 93% branches

Total: 485 tests passing (249 new tests added)

* docs: update Issue #141 context files to reflect Phase 3 completion

- Update progress from 28% to 59.4% (19/32 subtasks)
- Mark Phases 1-3 as complete (Foundation, Adapters, Mappers)
- Update code stats: 5,799 source lines, 6,322 test lines
- Add test coverage metrics: 485 tests, 97-100% on Phase 3
- Update structure with all implemented files
- Add executive summary for token-efficient context loading
- Document next steps: Phase 4 CLI implementation

* docs(context): harvest Claude Code docs and fix MVI compliance (Phase 1)

- Harvest external Claude Code documentation into context system:
  - hooks-system, agent-skills, subagents-system concepts
  - hook-events, skill-metadata, builtin-subagents lookups
  - Example files for hooks, skills, and subagents
  - Plugin architecture and migration guides

- Fix 6 critical MVI violations (files > 200 lines):
  - Split adding-agent.md → adding-agent-basics.md + adding-agent-testing.md
  - Split adding-skill.md → 3 files (basics, implementation, example)
  - Split task-delegation.md → 3 files (basics, specialists, caching)
  - Split external-libraries.md → 3 files (workflow, scenarios, faq)
  - Split design-assets.md → 4 files (images, icons, fonts, cdn)
  - Split navigation-design.md → 2 files (basics, templates)

- Update navigation files with new references
- Remove consumed source docs from to-be-consumed/

Total: 17 new files created, 6 large files replaced, 5 source docs consumed

* docs(context): MVI compliance Phase 2 - split large workflow and UI files

Split 3 large files into MVI-compliant modules (< 200 lines each):

- design-iteration.md (1058 lines) → 9 files:
  - design-iteration-overview.md (overview, when to use)
  - design-iteration-plan-file.md (mandatory plan template)
  - design-iteration-stage-layout.md (Stage 1)
  - design-iteration-stage-theme.md (Stage 2)
  - design-iteration-stage-animation.md (Stage 3)
  - design-iteration-stage-implementation.md (Stage 4)
  - design-iteration-visual-content.md (Image Specialist)
  - design-iteration-best-practices.md (quality, troubleshooting)
  - design-iteration-plan-iterations.md (managing iterations)

- animation-patterns.md (753 lines) → 6 files:
  - animation-basics.md (fundamentals, timing, easing)
  - animation-components.md (buttons, cards, modals)
  - animation-chat.md (message, typing animations)
  - animation-loading.md (skeleton, spinner, progress)
  - animation-forms.md (focus, validation, scroll)
  - animation-advanced.md (recipes, best practices)

- premium-dark-ui-quick-start.md (638 lines) → 4 files:
  - premium-dark-ui-colors.md (palette, typography, spacing)
  - premium-dark-ui-components.md (core building blocks)
  - premium-dark-ui-layouts.md (hero, features, CTA)
  - premium-dark-ui-advanced.md (animations, accessibility)

Updated navigation files with new references.

* feat(cli): implement CLI scaffolding with Commander.js (Issue #141 - Subtask 20)

- Add src/cli/index.ts: CLI entry point with convert, validate, migrate, info commands
- Add src/cli/types.ts: TypeScript type definitions for CLI options
- Add src/cli/utils.ts: Logging, spinner, and formatting utilities
- Add "type": "module" to package.json for ESM support
- Global options: --verbose, --quiet, --output-format (json|text)
- Commands are placeholders pending implementation in subtasks 21-24

* feat(cli): implement convert command with full format support (Issue #141 - Subtask 21)

- Add src/cli/commands/convert.ts: Complete convert command implementation
- Auto-detect input format from file path and content
- Support bidirectional conversion: OAC <-> Cursor/Claude/Windsurf
- Output to stdout by default, file with --output flag
- Display warnings for feature loss during conversion
- Enable registerBuiltInAdapters in AdapterRegistry
- Add public constructors to all adapters (CursorAdapter, ClaudeAdapter, WindsurfAdapter)
- Fix ESM imports: add .js extensions to all relative imports across codebase

All 485 tests passing.

* feat(cli): implement validate and info commands (Issue #141 - Subtasks 22, 24)

- validate: Checks agent compatibility with target format
  - Reports compatibility score (0-100%)
  - Lists preserved/degraded/lost features
  - Provides suggestions for unsupported features
  - Exit codes: 0=compatible, 1=partial, 2=incompatible
  - Supports --strict and --output-format json

- info: Displays tool capabilities and feature parity
  - Shows feature matrix for all platforms
  - Detailed view for single platform
  - Platform comparison with --compare
  - Documentation links
  - Supports --output-format json

* feat(cli): implement migrate command and add migration guides (Issue #141)

- Add migrate command for full project migration with batch conversion
- Support --dry-run, --force, and --out-dir options
- Generate migration reports with success/failure summaries
- Preserve directory structure in output

Documentation:
- Add 5 migration guides (cursor↔oac, claude↔oac, oac→windsurf)
- Add comprehensive feature-matrices.md with platform comparisons
- Document lossless vs lossy conversion impacts

Completes subtasks: 23, 26, 27, 28, 29, 30, 31

* test(cli): add comprehensive integration tests for all CLI commands (Issue #141)

- Add convert.test.ts with 23 tests for format conversions
- Add validate.test.ts with 21 tests for compatibility validation
- Add migrate.test.ts with 25 tests for batch migration
- Add info.test.ts with 30 tests for capability queries
- Add test fixtures for OAC, Cursor, and Claude formats
- Fix empty directory warning in migrate command

All 584 tests passing with full coverage of CLI modules.

Completes subtask 25

* docs: update README with comprehensive CLI and API documentation (Issue #141)

- Add complete CLI command reference with all options
- Add programmatic API usage examples
- Add feature parity matrix summary
- Add links to all migration guides
- Add architecture overview
- Add custom adapter creation guide

Completes subtask 32 - Feature #141 fully implemented

* docs: add visual examples and format improvements to README

- Add Cursor IDE screenshot (contextscout-cursor.png)
- Add Claude Code validation screenshot (claude-code-validation.png)
- Format code examples with consistent double quotes
- Align feature parity matrix table
- Add .cursorrules and bun.lock to .gitignore

* fix(lint): resolve all ESLint errors in compatibility layer

- Remove async from methods with no await expressions (toOAC, fromOAC, loadFromFile)
- Wrap Promise-returning methods with Promise.resolve/reject
- Fix unsafe type assertions (replace 'as any' with proper type validation)
- Add missing getConfigPath() method to WindsurfAdapter
- Validate AgentCategory enum values before assignment
- Fix return type compatibility issues

All 584 tests passing, 0 ESLint errors (7 acceptable warnings for missing callback return types)

* chore: update package.json author and contributors metadata

- Update author from string to object format with name and GitHub URL
- Add Alexander Daza as contributor with email and GitHub profile
- Maintain npm package.json standard format for author/contributors fields

.gitignore

@@ -207,3 +207,5 @@ tasks/
 
 # Claude Code integration generated files
 integrations/claude-code/converter/generated/
+.cursorrules
+bun.lock

.opencode/context/core/context-system/guides/navigation-design-basics.md

@@ -0,0 +1,131 @@
+# Guide: Designing Navigation Files
+
+**Purpose**: How to create token-efficient, scannable navigation files
+
+---
+
+## Prerequisites
+
+- Understand MVI principle (`context-system/standards/mvi.md`)
+- Know your category's organizational pattern
+- Have content files already created
+
+**Estimated time**: 15-20 min per navigation file
+
+---
+
+## Core Principles
+
+### 1. Token Efficiency
+**Goal**: 200-300 tokens per navigation file
+
+**How**:
+- Use ASCII trees (not verbose descriptions)
+- Use tables (not paragraphs)
+- Be concise (not comprehensive)
+
+### 2. Scannable Structure
+**Goal**: AI can find what it needs in <5 seconds
+
+**Format**:
+1. **Structure** (ASCII tree) - See what exists
+2. **Quick Routes** (table) - Jump to common tasks
+3. **By Concern/Type** (sections) - Browse by category
+
+### 3. Self-Contained
+**Include**: ✅ Paths | ✅ Brief descriptions (3-5 words) | ✅ When to use
+**Exclude**: ❌ File contents | ❌ Detailed explanations | ❌ Duplicates
+
+---
+
+## Steps
+
+### 1. Determine Navigation Type
+
+| Type | Path | Purpose |
+|------|------|---------|
+| Category-level | `{category}/navigation.md` | Overview of category |
+| Subcategory-level | `{category}/{sub}/navigation.md` | Files in subcategory |
+| Specialized | `{category}/{domain}-navigation.md` | Cross-cutting (e.g., ui-navigation.md) |
+
+### 2. Create Structure Section
+
+```markdown
+## Structure
+
+```
+openagents-repo/
+├── navigation.md
+├── quick-start.md
+├── concepts/
+│   └── subagent-testing-modes.md
+├── guides/
+│   ├── adding-agent.md
+│   └── testing-agent.md
+└── lookup/
+    └── commands.md
+```
+```
+
+**Token count**: ~50-100 tokens
+
+### 3. Create Quick Routes Table
+
+```markdown
+## Quick Routes
+
+| Task | Path |
+|------|------|
+| **Add agent** | `guides/adding-agent.md` |
+| **Test agent** | `guides/testing-agent.md` |
+| **Find files** | `lookup/file-locations.md` |
+```
+
+**Guidelines**: Use **bold** for tasks | Relative paths | 5-10 common tasks
+
+### 4. Create By Concern/Type Sections
+
+```markdown
+## By Type
+
+**Concepts** → Core ideas and principles
+**Guides** → Step-by-step workflows
+**Lookup** → Quick reference tables
+**Errors** → Troubleshooting
+```
+
+### 5. Add Related Context (Optional)
+
+```markdown
+## Related Context
+
+- **Core Standards** → `../core/standards/navigation.md`
+```
+
+### 6. Validate Token Count
+
+**Target**: 200-300 tokens
+
+```bash
+wc -w navigation.md  # Multiply by 1.3 for token estimate
+```
+
+---
+
+## Verification Checklist
+
+- [ ] Token count 200-300?
+- [ ] ASCII tree included?
+- [ ] Quick routes table?
+- [ ] By concern/type section?
+- [ ] Relative paths?
+- [ ] Descriptions 3-5 words?
+- [ ] No duplicate information?
+
+---
+
+## Related
+
+- `navigation-templates.md` - Ready-to-use templates
+- `../standards/mvi.md` - MVI principle
+- `../examples/navigation-examples.md` - More examples

.opencode/context/core/context-system/guides/navigation-design.md

@@ -1,431 +0,0 @@
-# Guide: Designing Navigation Files
-
-**Purpose**: How to create token-efficient, scannable navigation files
-
-**Last Updated**: 2026-01-08
-
----
-
-## Prerequisites
-
-- Understand MVI principle (context-system/standards/mvi.md)
-- Know your category's organizational pattern (function-based or concern-based)
-- Have content files already created
-
-**Estimated time**: 15-20 min per navigation file
-
----
-
-## Core Principles
-
-### 1. Token Efficiency
-**Goal**: 200-300 tokens per navigation file
-
-**Why**: 
-- Faster AI loading
-- Lower costs
-- Quicker decision-making
-
-**How**:
-- Use ASCII trees (not verbose descriptions)
-- Use tables (not paragraphs)
-- Be concise (not comprehensive)
-
----
-
-### 2. Scannable Structure
-**Goal**: AI can find what it needs in <5 seconds
-
-**Format**:
-1. **Structure** (ASCII tree) - See what exists
-2. **Quick Routes** (table) - Jump to common tasks
-3. **By Concern/Type** (sections) - Browse by category
-
----
-
-### 3. Self-Contained
-**Goal**: Navigation file answers "where do I go?"
-
-**Include**:
-- ✅ Paths to files
-- ✅ Brief descriptions (3-5 words)
-- ✅ When to use each file
-
-**Exclude**:
-- ❌ File contents (that's what the files are for)
-- ❌ Detailed explanations
-- ❌ Duplicate information
-
----
-
-## Steps
-
-### 1. Determine Navigation Type
-
-**Category-level navigation** (`{category}/navigation.md`):
-- Overview of entire category
-- Points to subcategories
-- Includes specialized navigation files
-
-**Subcategory-level navigation** (`{category}/{subcategory}/navigation.md`):
-- Overview of subcategory
-- Lists files in this subcategory
-- Points to related categories
-
-**Specialized navigation** (`{category}/{domain}-navigation.md`):
-- Cross-cutting concern (e.g., `ui-navigation.md`)
-- Spans multiple subcategories
-- Task-focused routes
-
----
-
-### 2. Create Structure Section
-
-**Format**: ASCII tree showing directory structure
-
-**Example** (Function-based):
-```markdown
-## Structure
-
-```
-openagents-repo/
-├── navigation.md
-├── quick-start.md
-│
-├── concepts/
-│   ├── navigation.md
-│   └── subagent-testing-modes.md
-│
-├── guides/
-│   ├── navigation.md
-│   ├── adding-agent.md
-│   └── testing-agent.md
-│
-└── lookup/
-    ├── navigation.md
-    └── commands.md
-```
-```
-
-**Example** (Concern-based):
-```markdown
-## Structure
-
-```
-development/
-├── navigation.md
-├── ui-navigation.md           # Specialized
-│
-├── principles/
-│   ├── clean-code.md
-│   └── api-design.md
-│
-├── frontend/
-│   ├── react/
-│   │   ├── hooks-patterns.md
-│   │   └── tanstack/
-│   │       └── query-patterns.md
-│   └── vue/
-│
-└── backend/
-    ├── api-patterns/
-    │   ├── rest-design.md
-    │   └── graphql-design.md
-    └── nodejs/
-```
-```
-
-**Token count**: ~50-100 tokens
-
----
-
-### 3. Create Quick Routes Table
-
-**Format**: Task → Path mapping
-
-**Example**:
-```markdown
-## Quick Routes
-
-| Task | Path |
-|------|------|
-| **Add agent** | `guides/adding-agent.md` |
-| **Test agent** | `guides/testing-agent.md` |
-| **Debug issue** | `guides/debugging-issues.md` |
-| **Find files** | `lookup/file-locations.md` |
-```
-
-**Guidelines**:
-- Use **bold** for task names
-- Use relative paths
-- 5-10 most common tasks
-- Order by frequency of use
-
-**Token count**: ~50-100 tokens
-
----
-
-### 4. Create By Concern/Type Sections
-
-**Format**: Group files by concern or type
-
-**Example** (Function-based):
-```markdown
-## By Type
-
-**Concepts** → Core ideas and principles
-**Guides** → Step-by-step workflows
-**Lookup** → Quick reference tables
-**Errors** → Troubleshooting
-```
-
-**Example** (Concern-based):
-```markdown
-## By Concern
-
-**Principles** → Universal development practices
-**Frontend** → React, Vue, state management
-**Backend** → APIs, Node.js, Python, auth
-**Data** → SQL, NoSQL, ORMs
-```
-
-**Token count**: ~50-100 tokens
-
----
-
-### 5. Add Related Context (Optional)
-
-**Format**: Links to related categories
-
-**Example**:
-```markdown
-## Related Context
-
-- **Core Standards** → `../core/standards/navigation.md`
-- **UI Patterns** → `../ui/navigation.md`
-```
-
-**Token count**: ~20-50 tokens
-
----
-
-### 6. Validate Token Count
-
-**Target**: 200-300 tokens
-
-**Check**:
-```bash
-# Count tokens (rough estimate: words * 1.3)
-wc -w navigation.md
-# Multiply by 1.3 for token estimate
-```
-
-**If over 300 tokens**:
-- Remove verbose descriptions
-- Shorten table entries
-- Remove less-used routes
-
----
-
-## Templates
-
-### Category Navigation Template
-
-```markdown
-# {Category} Navigation
-
-**Purpose**: [1 sentence]
-
----
-
-## Structure
-
-```
-{category}/
-├── navigation.md
-├── {subcategory}/
-│   ├── navigation.md
-│   └── {files}.md
-```
-
----
-
-## Quick Routes
-
-| Task | Path |
-|------|------|
-| **{Task 1}** | `{path}` |
-| **{Task 2}** | `{path}` |
-| **{Task 3}** | `{path}` |
-
----
-
-## By {Concern/Type}
-
-**{Section 1}** → {description}
-**{Section 2}** → {description}
-**{Section 3}** → {description}
-
----
-
-## Related Context
-
-- **{Category}** → `../{category}/navigation.md`
-```
-
-**Token count**: ~200-250 tokens
-
----
-
-### Specialized Navigation Template
-
-```markdown
-# {Domain} Navigation
-
-**Scope**: [What this covers]
-
----
-
-## Structure
-
-```
-{Relevant directories across multiple categories}
-```
-
----
-
-## Quick Routes
-
-| Task | Path |
-|------|------|
-| **{Task 1}** | `{path}` |
-| **{Task 2}** | `{path}` |
-
----
-
-## By {Framework/Approach}
-
-**{Tech 1}** → `{path}`
-**{Tech 2}** → `{path}`
-
----
-
-## Common Workflows
-
-**{Workflow 1}**:
-1. `{file1}` ({purpose})
-2. `{file2}` ({purpose})
-```
-
-**Token count**: ~250-300 tokens
-
----
-
-## Examples
-
-### Good Navigation (Token-Efficient)
-
-```markdown
-# Development Navigation
-
-**Purpose**: Software development across all stacks
-
----
-
-## Structure
-
-```
-development/
-├── navigation.md
-├── ui-navigation.md
-├── principles/
-├── frontend/
-├── backend/
-└── data/
-```
-
----
-
-## Quick Routes
-
-| Task | Path |
-|------|------|
-| **UI/Frontend** | `ui-navigation.md` |
-| **Backend/API** | `backend-navigation.md` |
-| **Clean code** | `principles/clean-code.md` |
-
----
-
-## By Concern
-
-**Principles** → Universal practices
-**Frontend** → React, Vue, state
-**Backend** → APIs, Node, auth
-**Data** → SQL, NoSQL, ORMs
-```
-
-**Token count**: ~180 tokens ✅
-
----
-
-### Bad Navigation (Too Verbose)
-
-```markdown
-# Development Navigation
-
-**Purpose**: This navigation file helps you find software development patterns, standards, and best practices across all technology stacks including frontend, backend, databases, and infrastructure.
-
----
-
-## Introduction
-
-The development category contains comprehensive guides and patterns for building modern applications. Whether you're working on frontend user interfaces, backend APIs, database integrations, or infrastructure setup, you'll find relevant context here.
-
----
-
-## Directory Structure
-
-The development category is organized into several subcategories:
-
-- **principles/** - This directory contains universal development principles that apply regardless of the technology stack you're using. Files include clean code practices, API design principles, and more.
-
-- **frontend/** - This directory contains frontend development patterns including React, Vue, and state management solutions.
-
-[... continues for 500+ tokens]
-```
-
-**Token count**: 500+ tokens ❌
-
----
-
-## Verification
-
-After creating navigation file:
-
-- [ ] Token count 200-300?
-- [ ] ASCII tree included?
-- [ ] Quick routes table included?
-- [ ] By concern/type section included?
-- [ ] Paths are relative?
-- [ ] Descriptions are 3-5 words?
-- [ ] No duplicate information?
-- [ ] Links to related context?
-
----
-
-## Troubleshooting
-
-| Issue | Solution |
-|-------|----------|
-| Too many tokens | Remove verbose descriptions, shorten table entries |
-| Hard to scan | Use tables instead of paragraphs |
-| Missing files | Add to structure section and quick routes |
-| Unclear paths | Use relative paths, add brief descriptions |
-
----
-
-## Related
-
-- `../standards/mvi.md` - Minimal Viable Information principle
-- `organizing-context.md` - How to choose organizational pattern
-- `../examples/navigation-examples.md` - More examples

.opencode/context/core/context-system/guides/navigation-templates.md

@@ -0,0 +1,183 @@
+# Navigation File Templates
+
+**Purpose**: Ready-to-use templates for navigation files
+
+---
+
+## Category Navigation Template
+
+```markdown
+# {Category} Navigation
+
+**Purpose**: [1 sentence]
+
+---
+
+## Structure
+
+```
+{category}/
+├── navigation.md
+├── {subcategory}/
+│   ├── navigation.md
+│   └── {files}.md
+```
+
+---
+
+## Quick Routes
+
+| Task | Path |
+|------|------|
+| **{Task 1}** | `{path}` |
+| **{Task 2}** | `{path}` |
+| **{Task 3}** | `{path}` |
+
+---
+
+## By {Concern/Type}
+
+**{Section 1}** → {description}
+**{Section 2}** → {description}
+**{Section 3}** → {description}
+
+---
+
+## Related Context
+
+- **{Category}** → `../{category}/navigation.md`
+```
+
+**Token count**: ~200-250 tokens
+
+---
+
+## Specialized Navigation Template
+
+```markdown
+# {Domain} Navigation
+
+**Scope**: [What this covers]
+
+---
+
+## Structure
+
+```
+{Relevant directories across multiple categories}
+```
+
+---
+
+## Quick Routes
+
+| Task | Path |
+|------|------|
+| **{Task 1}** | `{path}` |
+| **{Task 2}** | `{path}` |
+
+---
+
+## By {Framework/Approach}
+
+**{Tech 1}** → `{path}`
+**{Tech 2}** → `{path}`
+
+---
+
+## Common Workflows
+
+**{Workflow 1}**:
+1. `{file1}` ({purpose})
+2. `{file2}` ({purpose})
+```
+
+**Token count**: ~250-300 tokens
+
+---
+
+## Good Example (Token-Efficient)
+
+```markdown
+# Development Navigation
+
+**Purpose**: Software development across all stacks
+
+---
+
+## Structure
+
+```
+development/
+├── navigation.md
+├── ui-navigation.md
+├── principles/
+├── frontend/
+├── backend/
+└── data/
+```
+
+---
+
+## Quick Routes
+
+| Task | Path |
+|------|------|
+| **UI/Frontend** | `ui-navigation.md` |
+| **Backend/API** | `backend-navigation.md` |
+| **Clean code** | `principles/clean-code.md` |
+
+---
+
+## By Concern
+
+**Principles** → Universal practices
+**Frontend** → React, Vue, state
+**Backend** → APIs, Node, auth
+**Data** → SQL, NoSQL, ORMs
+```
+
+**Token count**: ~180 tokens ✅
+
+---
+
+## Bad Example (Too Verbose)
+
+```markdown
+# Development Navigation
+
+**Purpose**: This navigation file helps you find software development 
+patterns, standards, and best practices across all technology stacks 
+including frontend, backend, databases, and infrastructure.
+
+---
+
+## Introduction
+
+The development category contains comprehensive guides and patterns 
+for building modern applications. Whether you're working on frontend 
+user interfaces, backend APIs, database integrations...
+
+[... continues for 500+ tokens]
+```
+
+**Token count**: 500+ tokens ❌
+
+---
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| Too many tokens | Remove verbose descriptions, shorten entries |
+| Hard to scan | Use tables instead of paragraphs |
+| Missing files | Add to structure and quick routes |
+| Unclear paths | Use relative paths, add brief descriptions |
+
+---
+
+## Related
+
+- `navigation-design-basics.md` - Core principles and steps
+- `../standards/mvi.md` - MVI principle
+- `../examples/navigation-examples.md` - More examples

.opencode/context/core/guides/resuming-sessions.md

@@ -0,0 +1,320 @@
+# Guide: Resuming Multi-Session Tasks
+
+**Purpose**: How to resume work from previous sessions using session context and task files
+
+**Last Updated**: 2026-02-04
+
+---
+
+## When to Use This Guide
+
+- Continuing work after a break or interruption
+- Picking up a task from another agent or developer
+- Understanding what was done in a previous session
+- Avoiding duplicate work or lost progress
+
+---
+
+## Session File Structure
+
+```
+.tmp/
+├── sessions/                      # Session context
+│   └── {YYYY-MM-DD}-{task-slug}/
+│       ├── context.md             # Full task context
+│       └── PROGRESS.md            # Progress report
+│
+└── tasks/                         # Task breakdowns
+    └── {task-slug}/
+        ├── task.json              # Main task definition
+        └── subtask_NN.json        # Individual subtasks
+```
+
+---
+
+## Quick Resume Steps
+
+### 1. Find Your Session (30 seconds)
+
+```bash
+# List recent sessions
+ls -lt .tmp/sessions/ | head -5
+
+# Most recent session
+SESSION=$(ls -t .tmp/sessions/ | head -1)
+echo "Latest session: $SESSION"
+```
+
+---
+
+### 2. Read Progress Report (2 minutes)
+
+```bash
+# View progress
+cat .tmp/sessions/$SESSION/PROGRESS.md
+```
+
+**Look for**:
+- ✅ **Completed Work** - What's already done
+- 🔥 **Next Steps** - What to do next
+- 📊 **Overall Progress** - How much is complete
+- ⚠️ **Blockers** - Any issues to resolve
+
+---
+
+### 3. Check Task Context (3 minutes)
+
+```bash
+# View full context
+cat .tmp/sessions/$SESSION/context.md
+```
+
+**Key sections**:
+- **Current Request** - What was asked for
+- **Context Files** - Standards to follow (CRITICAL)
+- **Reference Files** - Existing code to read
+- **Components** - What needs to be built
+- **Exit Criteria** - When you're done
+
+---
+
+### 4. Review Subtasks (2 minutes)
+
+```bash
+# Find task directory
+TASK_DIR=.tmp/tasks/$(basename $SESSION | cut -d'-' -f4-)
+
+# List subtasks
+ls $TASK_DIR/subtask_*.json
+
+# View next subtask
+cat $TASK_DIR/subtask_04.json  # Example
+```
+
+**Subtask format**:
+```json
+{
+  "id": "04",
+  "name": "Migrate AgentLoader",
+  "description": "Create src/core/AgentLoader.ts with load/parse functions",
+  "estimated_hours": 1.5,
+  "status": "pending",
+  "dependencies": ["02"],
+  "context_files": ["...standards to load..."],
+  "acceptance_criteria": ["...checklist..."]
+}
+```
+
+---
+
+## Resume Workflow
+
+### Option 1: Continue from Last Checkpoint
+
+```bash
+# 1. Check what's done
+grep "✅" .tmp/sessions/$SESSION/PROGRESS.md
+
+# 2. Find next task
+grep "🔥 NEXT" .tmp/sessions/$SESSION/PROGRESS.md
+
+# 3. Tell the agent
+"Continue with subtask 04 from session $SESSION"
+```
+
+---
+
+### Option 2: Jump to Specific Phase
+
+```bash
+# 1. View phase structure
+cat .tmp/tasks/$TASK_DIR/task.json | jq '.phases'
+
+# 2. Find phase tasks
+cat .tmp/tasks/$TASK_DIR/task.json | jq '.phases[1]'  # Phase 2
+
+# 3. Tell the agent
+"Start Phase 2 - Adapters from session $SESSION"
+```
+
+---
+
+### Option 3: Review and Decide
+
+```bash
+# 1. Quick status
+cat .tmp/sessions/$SESSION/PROGRESS.md | grep -A5 "Overall Progress"
+
+# 2. View completed work
+cat .tmp/sessions/$SESSION/PROGRESS.md | grep -A20 "Completed Work"
+
+# 3. Discuss with agent
+"Show me the current status of session $SESSION and suggest next steps"
+```
+
+---
+
+## Key Files to Read
+
+### context.md (ALWAYS)
+
+**Why**: Contains standards you MUST follow
+
+```markdown
+## Context Files (Standards to Follow)
+- .opencode/context/core/standards/code-quality.md - CRITICAL
+- .opencode/context/core/standards/test-coverage.md - CRITICAL
+```
+
+**Before writing any code**, load these standards!
+
+---
+
+### PROGRESS.md (RECOMMENDED)
+
+**Why**: Shows exactly what's done and what's next
+
+**Key sections**:
+- **Overall Progress** - % complete, phases
+- **Completed Work** - Files created, tasks done
+- **Next Steps** - What to do immediately
+- **Blockers** - Issues to resolve
+
+---
+
+### subtask_NN.json (WHEN NEEDED)
+
+**Why**: Detailed task definition with acceptance criteria
+
+**Use when**:
+- Starting a new subtask
+- Need to know exact requirements
+- Want to see dependencies
+
+---
+
+## Common Scenarios
+
+### Scenario 1: "I don't remember where I was"
+
+```bash
+# Quick catch-up
+cat .tmp/sessions/$SESSION/PROGRESS.md | head -50
+# Read: Overall Progress + Completed Work + Next Steps
+```
+
+**Time**: 2 minutes
+
+---
+
+### Scenario 2: "What was I supposed to build?"
+
+```bash
+# Read original request
+cat .tmp/sessions/$SESSION/context.md | grep -A20 "Current Request"
+
+# Read components
+cat .tmp/sessions/$SESSION/context.md | grep -A30 "Components"
+```
+
+**Time**: 3 minutes
+
+---
+
+### Scenario 3: "What standards should I follow?"
+
+```bash
+# Read context files list
+cat .tmp/sessions/$SESSION/context.md | grep -A15 "Context Files"
+
+# Load the standards
+cat .opencode/context/core/standards/code-quality.md
+```
+
+**Time**: 5 minutes
+
+---
+
+### Scenario 4: "How do I know when I'm done?"
+
+```bash
+# Read exit criteria
+cat .tmp/sessions/$SESSION/context.md | grep -A20 "Exit Criteria"
+```
+
+**Time**: 1 minute
+
+---
+
+## Agent Instructions
+
+When resuming a session, tell the agent:
+
+```
+"Resume session: {SESSION_ID}"
+```
+
+Or more specific:
+
+```
+"Continue with subtask 04 from session 2026-02-04-compatibility-layer-141"
+```
+
+The agent should:
+1. ✅ Read context.md for standards
+2. ✅ Read PROGRESS.md for current state
+3. ✅ Load next subtask JSON
+4. ✅ Load required context files (from subtask.context_files)
+5. ✅ Propose next steps
+6. ✅ Request approval before executing
+
+---
+
+## Session Lifecycle
+
+### Active Session
+- Created when task starts
+- Updated after each subtask completes
+- Contains live progress tracking
+
+### Completed Session
+- All subtasks marked complete
+- Exit criteria met
+- Ready for archival
+
+### Archived Session
+- Moved to `.tmp/archive/sessions/{date}/`
+- Knowledge harvested to permanent context
+- Task JSONs can be deleted
+
+---
+
+## Cleanup Checklist
+
+After completing a session:
+
+- [ ] All exit criteria met?
+- [ ] Valuable knowledge harvested to context?
+- [ ] Session files archived?
+- [ ] Task JSONs cleaned up?
+- [ ] Temporary files deleted?
+
+---
+
+## Best Practices
+
+1. **Always read context.md first** - Contains critical standards
+2. **Check PROGRESS.md before asking** - Likely has the answer
+3. **Use subtask JSONs for detailed requirements** - Not just memory
+4. **Update PROGRESS.md after each task** - Keep it current
+5. **Archive when done** - Don't clutter workspace
+
+---
+
+## Reference
+
+- **Session Template**: `.tmp/sessions/{YYYY-MM-DD}-{task-slug}/`
+- **Task Template**: `.tmp/tasks/{task-slug}/`
+- **Related**:
+  - guides/compatibility-layer-workflow.md (example session)
+  - standards/code-quality.md (what to follow)

.opencode/context/core/navigation.md

@@ -28,6 +28,9 @@ core/
 │   ├── session-management.md
 │   └── design-iteration.md
 │
+├── guides/
+│   └── resuming-sessions.md      # NEW: Multi-session task resumption
+│
 ├── task-management/           # JSON-driven task tracking
 │   ├── navigation.md
 │   ├── standards/
@@ -61,6 +64,7 @@ core/
 | **Review code** | `workflows/code-review.md` |
 | **Delegate task** | `workflows/task-delegation.md` |
 | **Break down feature** | `workflows/feature-breakdown.md` |
+| **Resume session** | `guides/resuming-sessions.md` |
 | **Manage tasks** | `task-management/navigation.md` |
 | **Task CLI commands** | `task-management/lookup/task-commands.md` |
 | **Context system** | `context-system.md` |

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

@@ -0,0 +1,179 @@
+<!-- Context: workflows/design-iteration-best-practices | Priority: high | Version: 1.0 | Updated: 2025-12-09 -->
+# Design Iteration Best Practices
+
+## 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
+```
+
+---
+
+## 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](../../ui/web/design-systems.md)
+- [UI Styling Standards](../../ui/web/ui-styling-standards.md)
+- [Animation Patterns](../../ui/web/animation-patterns.md)
+- [ASCII Art Generator](https://www.asciiart.eu/)
+- [WCAG Contrast Checker](https://webaim.org/resources/contrastchecker/)
+
+---
+
+## Related Files
+
+- [Overview](./design-iteration-overview.md)
+- [Stage 4: Implementation](./design-iteration-stage-implementation.md)
+- [Plan Iterations](./design-iteration-plan-iterations.md)

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

@@ -0,0 +1,91 @@
+<!-- Context: workflows/design-iteration-overview | Priority: high | Version: 1.0 | Updated: 2025-12-09 -->
+# Design Iteration Workflow - Overview
+
+## 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
+
+---
+
+## When to Use This Workflow
+
+### Delegate to OpenFrontendSpecialist When:
+
+**✅ STRONGLY RECOMMENDED** to delegate for:
+- **New UI/UX design work** - Landing pages, dashboards, app interfaces
+- **Design system creation** - Component libraries, theme systems, style guides
+- **Complex layouts** - Multi-column grids, responsive designs, intricate structures
+- **Visual polish** - Animations, transitions, micro-interactions
+- **Brand-focused work** - Marketing pages, product showcases, hero sections
+- **Accessibility-critical UI** - Forms, navigation, interactive components
+
+**Why delegate?**
+- OpenFrontendSpecialist follows the 4-stage design workflow (Layout → Theme → Animation → Implementation)
+- Ensures thoughtful design decisions with approval gates
+- Produces polished, accessible, production-ready UI
+- Handles responsive design, OKLCH colors, semantic HTML
+- Creates single-file HTML prototypes for quick iteration
+
+### Execute Directly When:
+
+**⚠️ Simple cases only**:
+- Minor text/content updates to existing UI
+- Small CSS tweaks (colors, spacing, fonts)
+- Adding simple utility classes
+- Updating existing component props
+- Bug fixes in existing UI code
+
+### Delegation Pattern
+
+```javascript
+// For UI design work
+task(
+  subagent_type="OpenFrontendSpecialist",
+  description="Design {feature} UI",
+  prompt="Design a {feature} following the 4-stage workflow:
+  
+  Requirements:
+  - {requirement 1}
+  - {requirement 2}
+  
+  Context: {what this UI is for}
+  
+  Follow the design iteration workflow:
+  1. Layout (ASCII wireframe)
+  2. Theme (design system, colors)
+  3. Animation (micro-interactions)
+  4. Implementation (single HTML file)
+  
+  Request approval between each stage."
+)
+```
+
+### Example Scenarios
+
+| Scenario | Action | Why |
+|----------|--------|-----|
+| "Create a landing page for our SaaS product" | ✅ Delegate to OpenFrontendSpecialist | Complex UI design, needs 4-stage workflow |
+| "Design a user dashboard with charts" | ✅ Delegate to OpenFrontendSpecialist | Complex layout, visual design, interactions |
+| "Build a component library with our brand" | ✅ Delegate to OpenFrontendSpecialist | Design system work, requires theme expertise |
+| "Fix button color from blue to green" | ⚠️ Execute directly | Simple CSS change |
+| "Update hero text content" | ⚠️ Execute directly | Content update only |
+
+---
+
+## Related Files
+
+- [Design Plan File](./design-iteration-plan-file.md) - MANDATORY plan file template
+- [Stage 1: Layout](./design-iteration-stage-layout.md)
+- [Stage 2: Theme](./design-iteration-stage-theme.md)
+- [Stage 3: Animation](./design-iteration-stage-animation.md)
+- [Stage 4: Implementation](./design-iteration-stage-implementation.md)
+- [Visual Content Generation](./design-iteration-visual-content.md)
+- [Best Practices](./design-iteration-best-practices.md)
+- [Plan Iterations](./design-iteration-plan-iterations.md)

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

@@ -0,0 +1,182 @@
+<!-- Context: workflows/design-iteration-plan-file | Priority: high | Version: 1.0 | Updated: 2025-12-09 -->
+# Design Plan File (MANDATORY)
+
+**CRITICAL**: Before starting any design work, create a persistent design plan file.
+
+**Location**: `.tmp/design-plans/{project-name}-{feature-name}.md`
+
+**Purpose**: 
+- Preserve design decisions across stages
+- Allow user to review and edit the plan
+- Maintain context for subagent calls
+- Track design evolution and iterations
+
+**When to Create**: 
+- BEFORE Stage 1 (Layout Design)
+- After understanding user requirements
+- Before any design work begins
+
+## Template
+
+```markdown
+---
+project: {project-name}
+feature: {feature-name}
+created: {ISO timestamp}
+updated: {ISO timestamp}
+status: in_progress
+current_stage: layout
+---
+
+# Design Plan: {Feature Name}
+
+## User Requirements
+{What the user asked for - verbatim or close paraphrase}
+
+## Design Goals
+- {goal 1}
+- {goal 2}
+- {goal 3}
+
+## Target Audience
+{Who will use this UI}
+
+## Technical Constraints
+- Framework: {Next.js, React, etc.}
+- Responsive: {Yes/No}
+- Accessibility: {WCAG level}
+- Browser support: {Modern, IE11+, etc.}
+
+---
+
+## Stage 1: Layout Design
+
+### Status
+- [ ] Layout planned
+- [ ] ASCII wireframe created
+- [ ] User approved
+
+### Layout Structure
+{ASCII wireframe will be added here}
+
+### Component Breakdown
+{Component list will be added here}
+
+### User Feedback
+{User comments and requested changes}
+
+---
+
+## Stage 2: Theme Design
+
+### Status
+- [ ] Design system selected
+- [ ] Color palette chosen
+- [ ] Typography defined
+- [ ] User approved
+
+### Theme Details
+{Theme specifications will be added here}
+
+### User Feedback
+{User comments and requested changes}
+
+---
+
+## Stage 3: Animation Design
+
+### Status
+- [ ] Micro-interactions defined
+- [ ] Animation timing set
+- [ ] User approved
+
+### Animation Details
+{Animation specifications will be added here}
+
+### User Feedback
+{User comments and requested changes}
+
+---
+
+## Stage 4: Implementation
+
+### Status
+- [ ] HTML structure complete
+- [ ] CSS applied
+- [ ] Animations implemented
+- [ ] User approved
+
+### Output Files
+- HTML: {file path}
+- CSS: {file path}
+- Assets: {file paths}
+
+### User Feedback
+{Final comments and requested changes}
+
+---
+
+## Design Evolution
+
+### Iteration 1
+- Date: {timestamp}
+- Changes: {what changed}
+- Reason: {why it changed}
+
+### Iteration 2
+- Date: {timestamp}
+- Changes: {what changed}
+- Reason: {why it changed}
+```
+
+## Workflow Integration
+
+1. **Create plan file** → Write to `.tmp/design-plans/{name}.md`
+2. **Each stage** → Update plan file with decisions and user feedback
+3. **User approval** → Edit plan file with approved decisions
+4. **User requests changes** → Edit plan file with feedback, iterate
+5. **Subagent calls** → Pass plan file path for context preservation
+6. **Completion** → Plan file contains full design history
+
+## Benefits
+
+- ✅ Context preserved across subagent calls
+- ✅ User can review and edit plan directly
+- ✅ Design decisions documented
+- ✅ Easy to iterate and refine
+- ✅ Full design history tracked
+
+---
+
+## Stage 0: Create Design Plan (MANDATORY FIRST STEP)
+
+**Purpose**: Create persistent plan file before any design work
+
+**Process**:
+1. Understand user requirements
+2. Identify design goals and constraints
+3. Create plan file at `.tmp/design-plans/{project-name}-{feature-name}.md`
+4. Populate with user requirements and goals
+5. Present plan file location to user
+6. Proceed to Stage 1
+
+**Deliverable**: Design plan file created and initialized
+
+**Example**:
+```
+✅ Design plan created: .tmp/design-plans/saas-landing-page.md
+
+You can review and edit this file at any time. All design decisions will be tracked here.
+
+Ready to proceed to Stage 1 (Layout Design)?
+```
+
+**Approval Gate**: "Plan file created. Ready to start layout design?"
+
+---
+
+## Related Files
+
+- [Overview](./design-iteration-overview.md)
+- [Stage 1: Layout](./design-iteration-stage-layout.md)
+- [Plan Iterations](./design-iteration-plan-iterations.md)

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

@@ -0,0 +1,153 @@
+<!-- Context: workflows/design-iteration-plan-iterations | Priority: high | Version: 1.0 | Updated: 2025-12-09 -->
+# Handling Plan File Edits and Iterations
+
+## User Edits Plan File Directly
+
+**Scenario**: User opens `.tmp/design-plans/{name}.md` and makes changes
+
+**Process**:
+1. User edits plan file (changes requirements, adds constraints, modifies goals)
+2. User notifies agent: "I've updated the plan file"
+3. Agent reads updated plan file
+4. Agent identifies what changed
+5. Agent proposes how to incorporate changes
+6. Agent updates affected stages
+
+**Example**:
+```
+User: "I've updated the plan file - changed the color scheme to dark mode"
+
+Agent: 
+✅ Read updated plan: .tmp/design-plans/saas-landing-page.md
+
+Changes detected:
+- Color scheme: Light → Dark mode
+- Primary color: Blue → Purple
+
+This affects:
+- Stage 2 (Theme) - needs regeneration
+- Stage 4 (Implementation) - needs CSS update
+
+Would you like me to:
+1. Regenerate theme with dark mode
+2. Update implementation with new theme
+```
+
+---
+
+## Iteration Within a Stage
+
+**Scenario**: User requests changes during a stage
+
+**Process**:
+1. Agent presents stage output (e.g., layout wireframe)
+2. User requests changes: "Make the hero section taller"
+3. Agent updates plan file with feedback
+4. Agent makes changes
+5. Agent updates plan file with new iteration
+6. Agent presents updated output
+
+**Example**:
+```
+Stage 1 - Layout Design
+
+Agent: [presents wireframe]
+
+User: "Make the hero section taller and move CTA above the fold"
+
+Agent:
+✅ Updated plan file with feedback
+✅ Revised layout wireframe
+✅ Updated plan file with Iteration 2
+
+[presents updated wireframe]
+```
+
+---
+
+## Tracking Iterations in Plan File
+
+**Format**:
+```markdown
+## Design Evolution
+
+### Iteration 1 - Initial Layout
+- Date: 2026-01-30T10:00:00Z
+- Stage: Layout
+- Changes: Initial wireframe created
+- User feedback: "Hero section too short, CTA below fold"
+
+### Iteration 2 - Revised Layout
+- Date: 2026-01-30T10:15:00Z
+- Stage: Layout
+- Changes: Increased hero height from 400px to 600px, moved CTA above fold
+- User feedback: "Perfect! Approved."
+- Status: ✅ Approved
+
+### Iteration 3 - Theme Adjustment
+- Date: 2026-01-30T10:30:00Z
+- Stage: Theme
+- Changes: Changed from light to dark mode, primary color blue → purple
+- User feedback: "Love the dark mode!"
+- Status: ✅ Approved
+```
+
+---
+
+## Subagent Context Preservation
+
+**Problem**: Subagents lose context between calls
+
+**Solution**: Always pass plan file path
+
+**Pattern**:
+```javascript
+// When delegating to subagent
+task(
+  subagent_type="OpenFrontendSpecialist",
+  description="Implement Stage 4",
+  prompt="Load design plan from .tmp/design-plans/saas-landing-page.md
+  
+  Read the plan file for:
+  - All approved decisions from Stages 1-3
+  - User requirements and constraints
+  - Design evolution and iterations
+  
+  Implement Stage 4 (Implementation) following all approved decisions.
+  
+  Update the plan file with:
+  - Output file paths
+  - Implementation status
+  - Any issues encountered"
+)
+```
+
+---
+
+## Plan File as Single Source of Truth
+
+### Benefits
+
+- ✅ All design decisions in one place
+- ✅ User can review and edit anytime
+- ✅ Subagents have full context
+- ✅ Design history preserved
+- ✅ Easy to iterate and refine
+- ✅ No context loss between stages
+
+### Best Practices
+
+- Always read plan file at start of each stage
+- Update plan file after every user interaction
+- Track all iterations with timestamps
+- Document user feedback verbatim
+- Mark approved decisions clearly
+- Pass plan file path to all subagents
+
+---
+
+## Related Files
+
+- [Overview](./design-iteration-overview.md)
+- [Design Plan File](./design-iteration-plan-file.md)
+- [Best Practices](./design-iteration-best-practices.md)

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

@@ -0,0 +1,80 @@
+<!-- Context: workflows/design-iteration-stage-animation | Priority: high | Version: 1.0 | Updated: 2025-12-09 -->
+# Stage 3: Animation Design
+
+**Purpose**: Define micro-interactions and transitions
+
+## Process
+
+1. Read design plan file from `.tmp/design-plans/{name}.md`
+2. Review approved theme from Stage 2
+3. Identify key interactions (hover, click, scroll)
+4. Define animation timing and easing
+5. Plan loading states and transitions
+6. Document animations using micro-syntax
+7. **Update plan file** with animation specifications
+8. Present animation plan to user for approval
+9. **Update plan file** with user feedback and approval status
+
+## Deliverable
+
+- Animation specification in micro-syntax format
+- Updated plan file with Stage 3 complete
+
+## 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
+```
+
+## Best Practices
+
+✅ **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
+
+## Approval Gate
+
+"Are these animations appropriate for your design, or should we adjust?"
+
+---
+
+## Related Files
+
+- [Overview](./design-iteration-overview.md)
+- [Stage 2: Theme](./design-iteration-stage-theme.md)
+- [Stage 4: Implementation](./design-iteration-stage-implementation.md)
+- [Animation Patterns](../../ui/web/animation-patterns.md)

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

@@ -0,0 +1,157 @@
+<!-- Context: workflows/design-iteration-stage-implementation | Priority: high | Version: 1.0 | Updated: 2025-12-09 -->
+# Stage 4: Implementation
+
+**Purpose**: Generate complete HTML file with all components
+
+## Process
+
+1. Read design plan file from `.tmp/design-plans/{name}.md`
+2. Review all approved decisions from Stages 1-3
+3. Build individual UI components
+4. Integrate theme CSS
+5. Add animations and interactions
+6. Combine into single HTML file
+7. Test responsive behavior
+8. Save to design_iterations folder
+9. **Update plan file** with output file paths
+10. Present to user for review
+11. **Update plan file** with user feedback and final approval status
+
+## Deliverable
+
+- Complete HTML file with embedded or linked CSS
+- Updated plan file with Stage 4 complete and all output files documented
+
+## 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>
+```
+
+## Best Practices
+
+✅ **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)
+
+## Approval Gate
+
+"Please review the design. Would you like any changes or iterations?"
+
+---
+
+## Related Files
+
+- [Overview](./design-iteration-overview.md)
+- [Stage 3: Animation](./design-iteration-stage-animation.md)
+- [Best Practices](./design-iteration-best-practices.md)
+- [Iteration Process](./design-iteration-plan-iterations.md)

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

@@ -0,0 +1,115 @@
+<!-- Context: workflows/design-iteration-stage-layout | Priority: high | Version: 1.0 | Updated: 2025-12-09 -->
+# Stage 1: Layout Design
+
+**Purpose**: Define the structure and component hierarchy before visual design
+
+## Process
+
+1. Read design plan file from `.tmp/design-plans/{name}.md`
+2. Analyze user requirements from plan
+3. Identify core UI components
+4. Plan layout structure and responsive behavior
+5. Create ASCII wireframe
+6. **Update plan file** with layout structure and component breakdown
+7. Present to user for approval
+8. **Update plan file** with user feedback and approval status
+
+## Deliverable
+
+- ASCII wireframe with component breakdown
+- Updated plan file with Stage 1 complete
+
+## 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     │
+└─────────────────┘
+```
+
+## Best Practices
+
+✅ **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
+
+## Approval Gate
+
+"Would you like to proceed with this layout or need modifications?"
+
+---
+
+## Related Files
+
+- [Overview](./design-iteration-overview.md)
+- [Design Plan File](./design-iteration-plan-file.md)
+- [Stage 2: Theme](./design-iteration-stage-theme.md)

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

@@ -0,0 +1,84 @@
+<!-- Context: workflows/design-iteration-stage-theme | Priority: high | Version: 1.0 | Updated: 2025-12-09 -->
+# Stage 2: Theme Design
+
+**Purpose**: Define colors, typography, spacing, and visual style
+
+## Process
+
+1. Read design plan file from `.tmp/design-plans/{name}.md`
+2. Review approved layout from Stage 1
+3. Choose design system (neo-brutalism, modern dark, custom)
+4. Select color palette (avoid Bootstrap blue unless requested)
+5. Choose typography (Google Fonts)
+6. Define spacing and shadows
+7. Generate theme CSS file
+8. **Update plan file** with theme specifications
+9. Present theme to user for approval
+10. **Update plan file** with user feedback and approval status
+
+## Deliverable
+
+- CSS theme file saved to `design_iterations/theme_N.css`
+- Updated plan file with Stage 2 complete
+
+## 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.
+
+## Best Practices
+
+✅ **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)
+
+## Approval Gate
+
+"Does this theme match your vision, or would you like adjustments?"
+
+---
+
+## Related Files
+
+- [Overview](./design-iteration-overview.md)
+- [Stage 1: Layout](./design-iteration-stage-layout.md)
+- [Stage 3: Animation](./design-iteration-stage-animation.md)
+- [Design Systems Context](../../ui/web/design-systems.md)
+- [UI Styling Standards](../../ui/web/ui-styling-standards.md)

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

@@ -0,0 +1,110 @@
+<!-- Context: workflows/design-iteration-visual-content | Priority: medium | Version: 1.0 | Updated: 2025-12-09 -->
+# Visual Content Generation
+
+## When to Use Image Specialist
+
+Delegate to **Image Specialist** subagent when users request:
+
+- **Diagrams & Visualizations**: Architecture diagrams, flowcharts, system visualizations
+- **UI Mockups & Wireframes**: Visual mockups, design concepts, interface previews
+- **Graphics & Assets**: Social media graphics, promotional images, icons, illustrations
+- **Image Editing**: Photo enhancement, image modifications, visual adjustments
+
+## Invocation Pattern
+
+```javascript
+task(
+  subagent_type="Image Specialist",
+  description="Generate/edit visual content",
+  prompt="Context to load:
+          - .opencode/context/core/visual-development.md
+          
+          Task: [Specific visual requirement]
+          
+          Requirements:
+          - [Visual style/aesthetic]
+          - [Dimensions/format]
+          - [Key elements to include]
+          - [Color scheme/branding]
+          
+          Output: [Expected deliverable]"
+)
+```
+
+## Example Use Cases
+
+### Architecture Diagram
+
+```javascript
+task(
+  subagent_type="Image Specialist",
+  description="Generate microservices architecture diagram",
+  prompt="Create a diagram showing:
+          - 5 microservices (API Gateway, Auth, Orders, Payments, Notifications)
+          - Database connections
+          - Message queue (RabbitMQ)
+          - External services (Stripe, SendGrid)
+          
+          Style: Clean, professional, modern
+          Format: PNG, 1920x1080"
+)
+```
+
+### UI Mockup
+
+```javascript
+task(
+  subagent_type="Image Specialist",
+  description="Generate dashboard mockup",
+  prompt="Create a mockup for an analytics dashboard:
+          - Header with navigation
+          - 4 metric cards (Users, Revenue, Conversion, Retention)
+          - Line chart showing trends
+          - Data table below
+          
+          Style: Modern, dark theme, professional
+          Format: PNG, 1440x900"
+)
+```
+
+### Social Media Graphic
+
+```javascript
+task(
+  subagent_type="Image Specialist",
+  description="Generate product launch graphic",
+  prompt="Create a social media graphic announcing new feature:
+          - Bold headline: 'Introducing Real-Time Collaboration'
+          - Subtext: 'Work together, ship faster'
+          - Brand colors: #6366f1 (primary), #1e293b (dark)
+          - Include abstract collaboration visual
+          
+          Format: PNG, 1200x630 (Twitter/LinkedIn)"
+)
+```
+
+## Tools Required
+
+- **tool:gemini** - Gemini Nano Banana AI for image generation/editing
+- Automatically available in Developer profile
+
+## When NOT to Delegate
+
+**Use design-iteration workflow instead** when:
+- Creating interactive HTML/CSS designs
+- Building complete UI implementations
+- Iterating on existing HTML files
+- Need responsive, production-ready code
+
+**Use image-specialist** when:
+- Need static visual assets
+- Creating diagrams or illustrations
+- Generating mockups for presentation
+- Quick visual concepts without code
+
+---
+
+## Related Files
+
+- [Overview](./design-iteration-overview.md)
+- [Visual Development](../visual-development.md)

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

@@ -1,1058 +0,0 @@
-<!-- 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
-
----
-
-## When to Use This Workflow
-
-### Delegate to OpenFrontendSpecialist When:
-
-**✅ STRONGLY RECOMMENDED** to delegate for:
-- **New UI/UX design work** - Landing pages, dashboards, app interfaces
-- **Design system creation** - Component libraries, theme systems, style guides
-- **Complex layouts** - Multi-column grids, responsive designs, intricate structures
-- **Visual polish** - Animations, transitions, micro-interactions
-- **Brand-focused work** - Marketing pages, product showcases, hero sections
-- **Accessibility-critical UI** - Forms, navigation, interactive components
-
-**Why delegate?**
-- OpenFrontendSpecialist follows the 4-stage design workflow (Layout → Theme → Animation → Implementation)
-- Ensures thoughtful design decisions with approval gates
-- Produces polished, accessible, production-ready UI
-- Handles responsive design, OKLCH colors, semantic HTML
-- Creates single-file HTML prototypes for quick iteration
-
-### Execute Directly When:
-
-**⚠️ Simple cases only**:
-- Minor text/content updates to existing UI
-- Small CSS tweaks (colors, spacing, fonts)
-- Adding simple utility classes
-- Updating existing component props
-- Bug fixes in existing UI code
-
-### Delegation Pattern
-
-```javascript
-// For UI design work
-task(
-  subagent_type="OpenFrontendSpecialist",
-  description="Design {feature} UI",
-  prompt="Design a {feature} following the 4-stage workflow:
-  
-  Requirements:
-  - {requirement 1}
-  - {requirement 2}
-  
-  Context: {what this UI is for}
-  
-  Follow the design iteration workflow:
-  1. Layout (ASCII wireframe)
-  2. Theme (design system, colors)
-  3. Animation (micro-interactions)
-  4. Implementation (single HTML file)
-  
-  Request approval between each stage."
-)
-```
-
-### Example Scenarios
-
-| Scenario | Action | Why |
-|----------|--------|-----|
-| "Create a landing page for our SaaS product" | ✅ Delegate to OpenFrontendSpecialist | Complex UI design, needs 4-stage workflow |
-| "Design a user dashboard with charts" | ✅ Delegate to OpenFrontendSpecialist | Complex layout, visual design, interactions |
-| "Build a component library with our brand" | ✅ Delegate to OpenFrontendSpecialist | Design system work, requires theme expertise |
-| "Fix button color from blue to green" | ⚠️ Execute directly | Simple CSS change |
-| "Update hero text content" | ⚠️ Execute directly | Content update only |
-
----
-
-## Design Plan File (MANDATORY)
-
-**CRITICAL**: Before starting any design work, create a persistent design plan file.
-
-**Location**: `.tmp/design-plans/{project-name}-{feature-name}.md`
-
-**Purpose**: 
-- Preserve design decisions across stages
-- Allow user to review and edit the plan
-- Maintain context for subagent calls
-- Track design evolution and iterations
-
-**When to Create**: 
-- BEFORE Stage 1 (Layout Design)
-- After understanding user requirements
-- Before any design work begins
-
-**Template**:
-```markdown
----
-project: {project-name}
-feature: {feature-name}
-created: {ISO timestamp}
-updated: {ISO timestamp}
-status: in_progress
-current_stage: layout
----
-
-# Design Plan: {Feature Name}
-
-## User Requirements
-{What the user asked for - verbatim or close paraphrase}
-
-## Design Goals
-- {goal 1}
-- {goal 2}
-- {goal 3}
-
-## Target Audience
-{Who will use this UI}
-
-## Technical Constraints
-- Framework: {Next.js, React, etc.}
-- Responsive: {Yes/No}
-- Accessibility: {WCAG level}
-- Browser support: {Modern, IE11+, etc.}
-
----
-
-## Stage 1: Layout Design
-
-### Status
-- [ ] Layout planned
-- [ ] ASCII wireframe created
-- [ ] User approved
-
-### Layout Structure
-{ASCII wireframe will be added here}
-
-### Component Breakdown
-{Component list will be added here}
-
-### User Feedback
-{User comments and requested changes}
-
----
-
-## Stage 2: Theme Design
-
-### Status
-- [ ] Design system selected
-- [ ] Color palette chosen
-- [ ] Typography defined
-- [ ] User approved
-
-### Theme Details
-{Theme specifications will be added here}
-
-### User Feedback
-{User comments and requested changes}
-
----
-
-## Stage 3: Animation Design
-
-### Status
-- [ ] Micro-interactions defined
-- [ ] Animation timing set
-- [ ] User approved
-
-### Animation Details
-{Animation specifications will be added here}
-
-### User Feedback
-{User comments and requested changes}
-
----
-
-## Stage 4: Implementation
-
-### Status
-- [ ] HTML structure complete
-- [ ] CSS applied
-- [ ] Animations implemented
-- [ ] User approved
-
-### Output Files
-- HTML: {file path}
-- CSS: {file path}
-- Assets: {file paths}
-
-### User Feedback
-{Final comments and requested changes}
-
----
-
-## Design Evolution
-
-### Iteration 1
-- Date: {timestamp}
-- Changes: {what changed}
-- Reason: {why it changed}
-
-### Iteration 2
-- Date: {timestamp}
-- Changes: {what changed}
-- Reason: {why it changed}
-```
-
-**Workflow Integration**:
-1. **Create plan file** → Write to `.tmp/design-plans/{name}.md`
-2. **Each stage** → Update plan file with decisions and user feedback
-3. **User approval** → Edit plan file with approved decisions
-4. **User requests changes** → Edit plan file with feedback, iterate
-5. **Subagent calls** → Pass plan file path for context preservation
-6. **Completion** → Plan file contains full design history
-
-**Benefits**:
-- ✅ Context preserved across subagent calls
-- ✅ User can review and edit plan directly
-- ✅ Design decisions documented
-- ✅ Easy to iterate and refine
-- ✅ Full design history tracked
-
----
-
-## Workflow Stages
-
-### Stage 0: Create Design Plan (MANDATORY FIRST STEP)
-
-**Purpose**: Create persistent plan file before any design work
-
-**Process**:
-1. Understand user requirements
-2. Identify design goals and constraints
-3. Create plan file at `.tmp/design-plans/{project-name}-{feature-name}.md`
-4. Populate with user requirements and goals
-5. Present plan file location to user
-6. Proceed to Stage 1
-
-**Deliverable**: Design plan file created and initialized
-
-**Example**:
-```
-✅ Design plan created: .tmp/design-plans/saas-landing-page.md
-
-You can review and edit this file at any time. All design decisions will be tracked here.
-
-Ready to proceed to Stage 1 (Layout Design)?
-```
-
-**Approval Gate**: "Plan file created. Ready to start layout design?"
-
----
-
-### Stage 1: Layout Design
-
-**Purpose**: Define the structure and component hierarchy before visual design
-
-**Process**:
-1. Read design plan file from `.tmp/design-plans/{name}.md`
-2. Analyze user requirements from plan
-3. Identify core UI components
-4. Plan layout structure and responsive behavior
-5. Create ASCII wireframe
-6. **Update plan file** with layout structure and component breakdown
-7. Present to user for approval
-8. **Update plan file** with user feedback and approval status
-
-**Deliverable**: 
-- ASCII wireframe with component breakdown
-- Updated plan file with Stage 1 complete
-
-**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. Read design plan file from `.tmp/design-plans/{name}.md`
-2. Review approved layout from Stage 1
-3. Choose design system (neo-brutalism, modern dark, custom)
-4. Select color palette (avoid Bootstrap blue unless requested)
-5. Choose typography (Google Fonts)
-6. Define spacing and shadows
-7. Generate theme CSS file
-8. **Update plan file** with theme specifications
-9. Present theme to user for approval
-10. **Update plan file** with user feedback and approval status
-
-**Deliverable**: 
-- CSS theme file saved to `design_iterations/theme_N.css`
-- Updated plan file with Stage 2 complete
-
-**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. Read design plan file from `.tmp/design-plans/{name}.md`
-2. Review approved theme from Stage 2
-3. Identify key interactions (hover, click, scroll)
-4. Define animation timing and easing
-5. Plan loading states and transitions
-6. Document animations using micro-syntax
-7. **Update plan file** with animation specifications
-8. Present animation plan to user for approval
-9. **Update plan file** with user feedback and approval status
-
-**Deliverable**: 
-- Animation specification in micro-syntax format
-- Updated plan file with Stage 3 complete
-
-**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. Read design plan file from `.tmp/design-plans/{name}.md`
-2. Review all approved decisions from Stages 1-3
-3. Build individual UI components
-4. Integrate theme CSS
-5. Add animations and interactions
-6. Combine into single HTML file
-7. Test responsive behavior
-8. Save to design_iterations folder
-9. **Update plan file** with output file paths
-10. Present to user for review
-11. **Update plan file** with user feedback and final approval status
-
-**Deliverable**: 
-- Complete HTML file with embedded or linked CSS
-- Updated plan file with Stage 4 complete and all output files documented
-
-**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?"
-
----
-
-## Visual Content Generation
-
-### When to Use Image Specialist
-
-Delegate to **Image Specialist** subagent when users request:
-
-- **Diagrams & Visualizations**: Architecture diagrams, flowcharts, system visualizations
-- **UI Mockups & Wireframes**: Visual mockups, design concepts, interface previews
-- **Graphics & Assets**: Social media graphics, promotional images, icons, illustrations
-- **Image Editing**: Photo enhancement, image modifications, visual adjustments
-
-### Invocation Pattern
-
-```javascript
-task(
-  subagent_type="Image Specialist",
-  description="Generate/edit visual content",
-  prompt="Context to load:
-          - .opencode/context/core/visual-development.md
-          
-          Task: [Specific visual requirement]
-          
-          Requirements:
-          - [Visual style/aesthetic]
-          - [Dimensions/format]
-          - [Key elements to include]
-          - [Color scheme/branding]
-          
-          Output: [Expected deliverable]"
-)
-```
-
-### Example Use Cases
-
-**Architecture Diagram**:
-```javascript
-task(
-  subagent_type="Image Specialist",
-  description="Generate microservices architecture diagram",
-  prompt="Create a diagram showing:
-          - 5 microservices (API Gateway, Auth, Orders, Payments, Notifications)
-          - Database connections
-          - Message queue (RabbitMQ)
-          - External services (Stripe, SendGrid)
-          
-          Style: Clean, professional, modern
-          Format: PNG, 1920x1080"
-)
-```
-
-**UI Mockup**:
-```javascript
-task(
-  subagent_type="Image Specialist",
-  description="Generate dashboard mockup",
-  prompt="Create a mockup for an analytics dashboard:
-          - Header with navigation
-          - 4 metric cards (Users, Revenue, Conversion, Retention)
-          - Line chart showing trends
-          - Data table below
-          
-          Style: Modern, dark theme, professional
-          Format: PNG, 1440x900"
-)
-```
-
-**Social Media Graphic**:
-```javascript
-task(
-  subagent_type="Image Specialist",
-  description="Generate product launch graphic",
-  prompt="Create a social media graphic announcing new feature:
-          - Bold headline: 'Introducing Real-Time Collaboration'
-          - Subtext: 'Work together, ship faster'
-          - Brand colors: #6366f1 (primary), #1e293b (dark)
-          - Include abstract collaboration visual
-          
-          Format: PNG, 1200x630 (Twitter/LinkedIn)"
-)
-```
-
-### Tools Required
-
-- **tool:gemini** - Gemini Nano Banana AI for image generation/editing
-- Automatically available in Developer profile
-
-### When NOT to Delegate
-
-**Use design-iteration workflow instead** when:
-- Creating interactive HTML/CSS designs
-- Building complete UI implementations
-- Iterating on existing HTML files
-- Need responsive, production-ready code
-
-**Use image-specialist** when:
-- Need static visual assets
-- Creating diagrams or illustrations
-- Generating mockups for presentation
-- Quick visual concepts without code
-
----
-
-## 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."
-```
-
----
-
-## Handling Plan File Edits and Iterations
-
-### User Edits Plan File Directly
-
-**Scenario**: User opens `.tmp/design-plans/{name}.md` and makes changes
-
-**Process**:
-1. User edits plan file (changes requirements, adds constraints, modifies goals)
-2. User notifies agent: "I've updated the plan file"
-3. Agent reads updated plan file
-4. Agent identifies what changed
-5. Agent proposes how to incorporate changes
-6. Agent updates affected stages
-
-**Example**:
-```
-User: "I've updated the plan file - changed the color scheme to dark mode"
-
-Agent: 
-✅ Read updated plan: .tmp/design-plans/saas-landing-page.md
-
-Changes detected:
-- Color scheme: Light → Dark mode
-- Primary color: Blue → Purple
-
-This affects:
-- Stage 2 (Theme) - needs regeneration
-- Stage 4 (Implementation) - needs CSS update
-
-Would you like me to:
-1. Regenerate theme with dark mode
-2. Update implementation with new theme
-```
-
-### Iteration Within a Stage
-
-**Scenario**: User requests changes during a stage
-
-**Process**:
-1. Agent presents stage output (e.g., layout wireframe)
-2. User requests changes: "Make the hero section taller"
-3. Agent updates plan file with feedback
-4. Agent makes changes
-5. Agent updates plan file with new iteration
-6. Agent presents updated output
-
-**Example**:
-```
-Stage 1 - Layout Design
-
-Agent: [presents wireframe]
-
-User: "Make the hero section taller and move CTA above the fold"
-
-Agent:
-✅ Updated plan file with feedback
-✅ Revised layout wireframe
-✅ Updated plan file with Iteration 2
-
-[presents updated wireframe]
-```
-
-### Tracking Iterations in Plan File
-
-**Format**:
-```markdown
-## Design Evolution
-
-### Iteration 1 - Initial Layout
-- Date: 2026-01-30T10:00:00Z
-- Stage: Layout
-- Changes: Initial wireframe created
-- User feedback: "Hero section too short, CTA below fold"
-
-### Iteration 2 - Revised Layout
-- Date: 2026-01-30T10:15:00Z
-- Stage: Layout
-- Changes: Increased hero height from 400px to 600px, moved CTA above fold
-- User feedback: "Perfect! Approved."
-- Status: ✅ Approved
-
-### Iteration 3 - Theme Adjustment
-- Date: 2026-01-30T10:30:00Z
-- Stage: Theme
-- Changes: Changed from light to dark mode, primary color blue → purple
-- User feedback: "Love the dark mode!"
-- Status: ✅ Approved
-```
-
-### Subagent Context Preservation
-
-**Problem**: Subagents lose context between calls
-
-**Solution**: Always pass plan file path
-
-**Pattern**:
-```javascript
-// When delegating to subagent
-task(
-  subagent_type="OpenFrontendSpecialist",
-  description="Implement Stage 4",
-  prompt="Load design plan from .tmp/design-plans/saas-landing-page.md
-  
-  Read the plan file for:
-  - All approved decisions from Stages 1-3
-  - User requirements and constraints
-  - Design evolution and iterations
-  
-  Implement Stage 4 (Implementation) following all approved decisions.
-  
-  Update the plan file with:
-  - Output file paths
-  - Implementation status
-  - Any issues encountered"
-)
-```
-
-### Plan File as Single Source of Truth
-
-**Benefits**:
-- ✅ All design decisions in one place
-- ✅ User can review and edit anytime
-- ✅ Subagents have full context
-- ✅ Design history preserved
-- ✅ Easy to iterate and refine
-- ✅ No context loss between stages
-
-**Best Practices**:
-- Always read plan file at start of each stage
-- Update plan file after every user interaction
-- Track all iterations with timestamps
-- Document user feedback verbatim
-- Mark approved decisions clearly
-- Pass plan file path to all subagents
-
----
-
-## 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](../ui/web/design-systems.md)
-- [UI Styling Standards](../ui/web/ui-styling-standards.md)
-- [Animation Patterns](../ui/web/animation-patterns.md)
-- [Design Assets](../ui/web/design-assets.md)
-- [ASCII Art Generator](https://www.asciiart.eu/)
-- [WCAG Contrast Checker](https://webaim.org/resources/contrastchecker/)

.opencode/context/core/workflows/external-libraries-faq.md

@@ -0,0 +1,165 @@
+<!-- Context: workflows/external-libraries-faq | Priority: medium | Version: 1.0 | Updated: 2026-02-05 -->
+# External Libraries: FAQ
+
+**Purpose**: Troubleshooting and common questions about ExternalScout
+
+---
+
+## When exactly should I use ExternalScout?
+
+**ALWAYS when working with external packages.**
+
+**Triggers:**
+- User mentions library
+- `import`/`require` statements
+- package.json deps
+- Build errors
+- First-time setup
+- Version upgrades
+
+**Rule**: If it's not in `.opencode/context/`, use ExternalScout.
+
+---
+
+## What if I already know the library?
+
+**DON'T rely on training data - it's outdated.**
+
+Example: You think "I know Next.js, I'll use pages/"  
+Reality: Next.js 15 uses app/  
+Result: Broken code ❌
+
+**Always fetch current docs, even if you "know" the library.**
+
+---
+
+## How do I know if something is external?
+
+**External:** npm/pip/gem/cargo packages | Third-party frameworks | ORMs | Auth libraries | UI libraries
+
+**NOT external:** Your project's code | Project utilities | Internal modules
+
+**Check:** Is it in `package.json` dependencies? → External → Use ExternalScout
+
+---
+
+## Can I use both ContextScout and ExternalScout?
+
+**YES! Use both for most features.**
+
+```javascript
+// 1. ContextScout: Project standards
+task(subagent_type="ContextScout", ...)
+
+// 2. ExternalScout: Library docs  
+task(subagent_type="ExternalScout", ...)
+
+// 3. Combine: Implement using both
+```
+
+---
+
+## What if ExternalScout doesn't have the library?
+
+ExternalScout has two sources:
+1. **Context7 API** (primary): 50+ popular libraries
+2. **Official docs** (fallback): Any library with public docs
+
+If library not in Context7: Auto-fallback to official docs via webfetch.
+
+---
+
+## How do I write a good ExternalScout prompt?
+
+**Template:**
+```javascript
+task(
+  subagent_type="ExternalScout",
+  description="Fetch [Library] docs for [specific topic]",
+  prompt="Fetch current documentation for [Library]: [specific question]
+  
+  Focus on:
+  - [What you need - be specific]
+  - [Related features/APIs]
+  
+  Context: [What you're building]"
+)
+```
+
+**Good:** ✅ Specific | ✅ Focused (3-5 things) | ✅ Contextual
+**Bad:** ❌ Vague | ❌ Too broad | ❌ No context
+
+---
+
+## What if I get an error after using ExternalScout?
+
+**Process:**
+1. Read error message carefully
+2. ExternalScout again with specific error:
+```javascript
+task(
+  subagent_type="ExternalScout",
+  description="Fetch docs for error resolution",
+  prompt="Fetch [Library] docs: [error message]
+  Error: [paste actual error]
+  Focus on: Common causes | Solutions"
+)
+```
+3. Check install scripts (maybe setup incomplete)
+4. Verify versions (package.json vs docs)
+
+---
+
+## Do I need approval to use ExternalScout?
+
+**NO - ExternalScout is read-only, no approval required.**
+
+**Approval required:** ❌ Write code | ❌ Run commands | ❌ Install packages
+**No approval:** ✅ ContextScout | ✅ ExternalScout | ✅ Read files
+
+---
+
+## ContextScout vs ExternalScout?
+
+| Aspect | ContextScout | ExternalScout |
+|--------|--------------|---------------|
+| **Searches** | Internal project files | External documentation |
+| **Location** | `.opencode/context/` | Internet (Context7, docs) |
+| **Returns** | Project standards | Library APIs |
+| **Use for** | "How we do things here" | "How this library works" |
+| **Speed** | Fast (local) | Slower (network) |
+
+**Use both together for best results.**
+
+---
+
+## Quick Checklist
+
+Before implementing with external libraries:
+
+- [ ] Used ContextScout for project standards?
+- [ ] Checked for install scripts first?
+- [ ] Used ExternalScout for EACH external library?
+- [ ] Asked for installation steps?
+- [ ] Asked for current API patterns?
+- [ ] Read returned docs before coding?
+
+**All checked? → You're doing it right! ✅**
+
+---
+
+## Supported Libraries
+
+**See**: `.opencode/skill/context7/library-registry.md`
+
+**Categories:** Database/ORM | Auth | Frontend | Infrastructure | UI | State | Validation | Testing
+
+Not listed? ExternalScout can still fetch from official docs.
+
+---
+
+## Related
+
+- `external-libraries-workflow.md` - Core workflow
+- `external-libraries-scenarios.md` - Common scenarios
+- `.opencode/agent/subagents/core/externalscout.md` - ExternalScout agent

.opencode/context/core/workflows/external-libraries-scenarios.md

@@ -0,0 +1,130 @@
+<!-- Context: workflows/external-libraries-scenarios | Priority: medium | Version: 1.0 | Updated: 2026-02-05 -->
+# External Libraries: Common Scenarios
+
+**Purpose**: Real-world examples of using ExternalScout
+
+---
+
+## Scenario 1: New Build with External Packages
+
+**Example**: Next.js app with Drizzle + Better Auth
+
+**Process:**
+1. Check install scripts: `ls scripts/install/`
+2. Identify packages: Next.js, Drizzle ORM, Better Auth
+3. ExternalScout for each package
+4. Check requirements: PostgreSQL? Env vars?
+5. Verify version compatibility
+6. Implement following current docs
+7. Test integration points
+
+**ExternalScout calls:**
+```javascript
+// Drizzle ORM
+task(
+  subagent_type="ExternalScout",
+  description="Fetch Drizzle PostgreSQL setup",
+  prompt="Fetch Drizzle ORM docs: PostgreSQL setup w/ modular schemas
+  Focus on: Installation | DB connection | Schema patterns | Migrations
+  Context: Next.js commerce site w/ PostgreSQL"
+)
+
+// Next.js App Router
+task(
+  subagent_type="ExternalScout",
+  description="Fetch Next.js App Router docs",
+  prompt="Fetch Next.js docs: App Router w/ Server Actions
+  Focus on: Installation | Directory structure | Server Actions
+  Context: Commerce site w/ order processing"
+)
+```
+
+---
+
+## Scenario 2: Package Error During Build
+
+**Example**: `Error: Cannot find module 'drizzle-orm/pg-core'`
+
+**Process:**
+1. Identify package: Drizzle ORM
+2. ExternalScout: "Fetch Drizzle docs: PostgreSQL imports"
+3. Check current import patterns
+4. Verify package.json has correct deps
+5. Propose fix from current docs
+6. Request approval → Apply fix
+
+---
+
+## Scenario 3: First-Time Package Setup
+
+**Example**: Setting up TanStack Query in Next.js
+
+**Process:**
+1. Check install scripts
+2. ExternalScout: "Fetch TanStack Query docs: Next.js App Router setup"
+3. Get: Install steps | Peer deps | Config | Patterns
+4. If install script exists: Review → Run
+5. If no script: Follow docs for manual setup
+6. Implement → Test
+
+---
+
+## Scenario 4: Version Upgrade
+
+**Example**: Next.js 14 → 15
+
+**Process:**
+1. ExternalScout: "Fetch Next.js 15 docs: Breaking changes and migration"
+2. Review breaking changes
+3. Identify affected code
+4. Plan migration steps
+5. Request approval → Implement → Test
+
+---
+
+## Real-World Example: Auth Implementation
+
+**Task**: "Add authentication with Better Auth to Next.js commerce"
+
+```javascript
+// 1. ContextScout: Project standards
+task(
+  subagent_type="ContextScout",
+  description="Find auth standards",
+  prompt="Find context files: Auth patterns | Security standards"
+)
+// Returns: security-patterns.md, code-quality.md
+
+// 2. ExternalScout: Better Auth docs (MANDATORY)
+task(
+  subagent_type="ExternalScout",
+  description="Fetch Better Auth + Next.js docs",
+  prompt="Fetch Better Auth docs: Next.js App Router integration
+  Focus on: Installation | App Router setup | Drizzle adapter | Session mgmt
+  Context: Adding auth to Next.js commerce w/ Drizzle ORM"
+)
+// Returns: Installation | Integration patterns | Working examples
+
+// 3. Combine and implement
+// - Better Auth patterns (from ExternalScout)
+// - Security standards (from ContextScout)
+// = Secure, well-structured auth ✅
+```
+
+---
+
+## Error Handling Patterns
+
+| Error Type | Process |
+|------------|---------|
+| **Package Installation** | ExternalScout: installation docs → Verify package name/version → Check peer deps |
+| **Import/Module** | ExternalScout: import patterns → Check current API exports |
+| **API/Configuration** | ExternalScout: API docs → Check current signatures |
+| **Build Errors** | Identify package → ExternalScout: relevant docs → Check known issues |
+
+---
+
+## Related
+
+- `external-libraries-workflow.md` - Core workflow
+- `external-libraries-faq.md` - Troubleshooting FAQ

.opencode/context/core/workflows/external-libraries-workflow.md

@@ -0,0 +1,138 @@
+<!-- Context: workflows/external-libraries | Priority: high | Version: 2.1 | Updated: 2026-02-05 -->
+# Workflow: External Libraries
+
+**Purpose**: Fetch current documentation for external packages before implementation
+
+---
+
+## Quick Start
+
+**Golden Rule**: NEVER rely on training data for external libraries → ALWAYS fetch current docs
+
+**Process**: Detect package → Check install scripts → Use ExternalScout → Implement
+
+**When to use ExternalScout** (MANDATORY):
+- New builds with external packages
+- First-time package setup
+- Package/dependency errors
+- Version upgrades
+- ANY external library work
+
+---
+
+## Core Principle
+
+<rule id="external_docs_required" enforcement="strict">
+  Training data is OUTDATED for external libraries.
+  ALWAYS fetch current docs using ExternalScout before implementation.
+</rule>
+
+**Why:**
+- APIs change (new methods, deprecated features)
+- Configuration patterns evolve
+- Breaking changes happen frequently
+
+**Example:**
+```
+Training data (2023): Next.js 13 uses pages/ directory
+Current (2025): Next.js 15 uses app/ directory
+
+Training data = broken code ❌
+ExternalScout = working code ✅
+```
+
+---
+
+## Workflow Stages
+
+### 1. Detect External Package
+
+**Triggers**: User mentions library | package.json deps | import statements | build errors
+
+### 2. Check Install Scripts
+
+```bash
+ls scripts/install/ scripts/setup/ bin/install* setup.sh
+grep -r "postinstall\|preinstall" package.json
+```
+
+Read scripts if found: What does it do? Environment variables? Prerequisites?
+
+### 3. Fetch Current Documentation (MANDATORY)
+
+```javascript
+task(
+  subagent_type="ExternalScout",
+  description="Fetch [Library] docs for [topic]",
+  prompt="Fetch current documentation for [Library]: [specific question]
+  
+  Focus on:
+  - Installation and setup steps
+  - [Specific feature/API needed]
+  - Required environment variables
+  
+  Context: [What you're building]"
+)
+```
+
+### 4. Verify Compatibility
+
+Check: Version compatibility | Peer dependencies | Breaking changes
+
+### 5. Implement with Current Patterns
+
+- Use exact API signatures from docs
+- Follow current best practices
+- Use recommended config patterns
+
+### 6. Test Integration
+
+Verify: Package installs | Imports work | API calls match docs
+
+---
+
+## Decision Flow: ContextScout + ExternalScout
+
+```
+User Request: "Build Next.js commerce w/ Drizzle"
+                    ↓
+STEP 1: ContextScout → Search internal context
+                    ↓
+         Internal context found?
+                    ↓
+        YES → Use internal     NO → Is it external library?
+                                        ↓
+                               YES → STEP 2: ExternalScout (MANDATORY)
+                                        ↓
+                               STEP 3: Combine internal + external → Implement
+```
+
+| Scenario | ContextScout | ExternalScout |
+|----------|--------------|---------------|
+| Project coding standards | ✅ | ❌ |
+| External library setup | ❌ | ✅ MANDATORY |
+| Feature with external lib | ✅ standards | ✅ lib docs |
+
+---
+
+## Best Practices
+
+**Do ✅:**
+- Check install scripts first
+- Always fetch current docs
+- Verify versions match
+- Test integrations
+
+**Don't ❌:**
+- Assume APIs based on training data
+- Skip version checks
+- Ignore peer dependencies
+- Run install scripts blindly
+
+---
+
+## Related
+
+- `external-libraries-scenarios.md` - Common scenarios and examples
+- `external-libraries-faq.md` - Troubleshooting FAQ
+- `.opencode/agent/subagents/core/externalscout.md` - ExternalScout agent

.opencode/context/core/workflows/external-libraries.md

@@ -1,531 +0,0 @@
-<!-- Context: workflows/external-libraries | Priority: high | Version: 2.0 | Updated: 2026-01-28 -->
-# Workflow: External Libraries
-
-**Purpose**: Fetch current documentation for external packages before implementation
-
-**Last Updated**: 2026-01-28
-
----
-
-## Quick Start
-
-**Golden Rule**: NEVER rely on training data for external libraries → ALWAYS fetch current docs
-
-**Process**: Detect package → Check install scripts → Use ExternalScout → Implement
-
-**When to use ExternalScout** (MANDATORY):
-- New builds w/ external packages
-- First-time package setup
-- Package/dependency errors
-- Version upgrades
-- ANY external library work
-
----
-
-## Core Principle
-
-<rule id="external_docs_required" enforcement="strict">
-  Training data is OUTDATED for external libraries.
-  ALWAYS fetch current docs using ExternalScout before implementation.
-</rule>
-
-**Why**:
-- APIs change (new methods, deprecated features)
-- Configuration patterns evolve
-- Breaking changes happen frequently
-- Version-specific features differ
-
-**Example**:
-```
-Training data (2023): Next.js 13 uses pages/ directory
-Current (2025): Next.js 15 uses app/ directory (App Router)
-
-Training data = broken code ❌
-ExternalScout = working code ✅
-```
-
----
-
-## Workflow Stages
-
-### 1. Detect External Package
-
-**Triggers**: User mentions library | package.json deps | import statements | build errors | first-time setup
-
-**Action**: Identify which external packages involved
-
----
-
-### 2. Check Install Scripts (First-Time Builds)
-
-**Check for**:
-```bash
-# Look for install scripts
-ls scripts/install/ scripts/setup/ bin/install* setup.sh install.sh
-
-# Check package-specific requirements
-grep -r "postinstall\|preinstall" package.json
-```
-
-**Read scripts if found**:
-- What does it do?
-- Environment variables needed?
-- Prerequisites (database, services)?
-
-**Why**: Scripts may set up databases, generate files, configure services in specific order
-
----
-
-### 3. Fetch Current Documentation (MANDATORY)
-
-**Basic Pattern**:
-```javascript
-task(
-  subagent_type="ExternalScout",
-  description="Fetch [Library] docs for [topic]",
-  prompt="Fetch current documentation for [Library]: [specific question]
-  
-  Focus on:
-  - Installation and setup steps
-  - [Specific feature/API needed]
-  - [Integration requirements]
-  - Required environment variables
-  - Database/service setup
-  
-  Context: [What you're building]"
-)
-```
-
-**Real Examples**:
-
-**Drizzle ORM Setup**:
-```javascript
-task(
-  subagent_type="ExternalScout",
-  description="Fetch Drizzle PostgreSQL setup",
-  prompt="Fetch Drizzle ORM docs: PostgreSQL setup w/ modular schemas
-  
-  Focus on: Installation | DB connection | Schema patterns | Migrations | TypeScript config
-  Context: Next.js commerce site w/ PostgreSQL"
-)
-```
-
-**Next.js App Router**:
-```javascript
-task(
-  subagent_type="ExternalScout",
-  description="Fetch Next.js App Router docs",
-  prompt="Fetch Next.js docs: App Router w/ Server Actions
-  
-  Focus on: Installation | Directory structure | Server Actions | Data fetching | Route handlers
-  Context: Commerce site w/ order processing"
-)
-```
-
-**Better Auth Integration**:
-```javascript
-task(
-  subagent_type="ExternalScout",
-  description="Fetch Better Auth + Next.js integration",
-  prompt="Fetch Better Auth docs: Next.js App Router integration w/ Drizzle
-  
-  Focus on: Installation | App Router setup | Drizzle adapter | Session mgmt | Route protection
-  Context: Adding auth to Next.js commerce w/ Drizzle ORM"
-)
-```
-
-**ExternalScout Returns**:
-- Current, version-specific docs
-- Installation steps + required packages
-- Official API references
-- Working code examples
-- Current best practices
-- Integration patterns
-- Setup prerequisites
-- Environment variables
-- Common pitfalls + solutions
-
----
-
-### 4. Verify Compatibility
-
-**Check**: Version compatibility | Peer dependencies | Breaking changes | Platform requirements
-
-**If version mismatch**: Note in plan → Request approval for upgrade → Fetch docs for specific version
-
----
-
-### 5. Implement with Current Patterns
-
-**Apply docs**:
-- Use exact API signatures from docs
-- Follow current best practices
-- Use recommended config patterns
-- Implement error handling as documented
-
-**Don't**:
-- ❌ Assume API based on training data
-- ❌ Use deprecated patterns
-- ❌ Skip version-specific requirements
-- ❌ Ignore breaking changes
-
----
-
-### 6. Test Integration
-
-**Verify**: Package installs | Imports work | API calls match docs | Error handling | Integration w/ other packages
-
----
-
-## Decision Flow: ContextScout + ExternalScout
-
-```
-User Request: "Build Next.js commerce w/ Drizzle"
-                    ↓
-┌──────────────────────────────────────────────────┐
-│ STEP 1: ContextScout                             │
-│ → Search internal context (.opencode/context/)  │
-│ → Find project standards, patterns, workflows   │
-└──────────────────────────────────────────────────┘
-                    ↓
-         Internal context found?
-                    ↓
-        ┌───────────┴───────────┐
-       YES                      NO
-        │                        │
-        ↓                        ↓
-   Use internal          Is it external library?
-   context                       ↓
-                        ┌────────┴────────┐
-                       YES               NO
-                        │                 │
-                        ↓                 ↓
-              ┌─────────────────┐  Report: No context
-              │ STEP 2:         │  available
-              │ ExternalScout   │
-              │ (MANDATORY)     │
-              └─────────────────┘
-                        ↓
-              Fetch: Next.js docs
-                     Drizzle docs
-                     Integration patterns
-                        ↓
-              ┌─────────────────────────┐
-              │ STEP 3: Combine         │
-              │ Internal: Standards     │
-              │ External: Library docs  │
-              │ → Implement w/ both     │
-              └─────────────────────────┘
-```
-
-**When to Use Which**:
-
-| Scenario | ContextScout | ExternalScout | Both |
-|----------|--------------|---------------|------|
-| Project coding standards | ✅ | ❌ | ❌ |
-| External library setup | ❌ | ✅ MANDATORY | ❌ |
-| Project-specific patterns | ✅ | ❌ | ❌ |
-| External API usage | ❌ | ✅ MANDATORY | ❌ |
-| Feature w/ external lib | ✅ standards | ✅ lib docs | ✅ |
-| Package installation | ❌ | ✅ MANDATORY | ❌ |
-| Security patterns | ✅ | ❌ | ❌ |
-| External lib integration | ✅ project | ✅ lib docs | ✅ |
-
-**Key Principle**: ContextScout + ExternalScout = Complete Context
-- **ContextScout**: "How we do things in THIS project"
-- **ExternalScout**: "How to use THIS library (current version)"
-- **Combined**: "How to use THIS library following OUR standards"
-
----
-
-## Common Scenarios
-
-### Scenario 1: New Build w/ External Packages
-
-**Example**: Next.js app w/ Drizzle + Better Auth
-
-**Process**:
-1. Check install scripts: `ls scripts/install/ scripts/setup/`
-2. Identify packages: Next.js, Drizzle ORM, Better Auth
-3. ExternalScout for each: Installation | Setup | Integration
-4. Check requirements: PostgreSQL? Env vars? Services?
-5. Verify version compatibility
-6. Run install scripts (if exist) OR create setup from docs
-7. Implement following current docs
-8. Test integration points
-
----
-
-### Scenario 2: Package Error During Build
-
-**Example**: `Error: Cannot find module 'drizzle-orm/pg-core'`
-
-**Process**:
-1. Identify package: Drizzle ORM
-2. ExternalScout: "Fetch Drizzle docs: PostgreSQL setup and imports"
-3. Check current import patterns
-4. Verify package.json has correct deps
-5. Propose fix from current docs
-6. Request approval → Apply fix
-
----
-
-### Scenario 3: First-Time Package Setup
-
-**Example**: Setting up TanStack Query in Next.js
-
-**Process**:
-1. Check install scripts: `ls scripts/install/` | `grep -r "tanstack\|react-query" scripts/`
-2. ExternalScout: "Fetch TanStack Query docs: Installation, Next.js App Router setup w/ Server Components"
-3. Get: Install steps | Peer deps | Config files | Current patterns | Best practices
-4. If install script exists: Review → Run
-5. If no script: Follow docs for manual setup
-6. Implement → Test
-
----
-
-### Scenario 4: Version Upgrade
-
-**Example**: Next.js 14 → 15
-
-**Process**:
-1. ExternalScout: "Fetch Next.js 15 docs: Breaking changes and migration guide"
-2. Review breaking changes
-3. Identify affected code
-4. Plan migration steps
-5. Request approval → Implement → Test
-
----
-
-## Real-World Example: Auth Implementation
-
-**Task**: "Add authentication w/ Better Auth to Next.js commerce site"
-
-```javascript
-// 1. ContextScout: Project standards
-task(
-  subagent_type="ContextScout",
-  description="Find auth and security standards",
-  prompt="Find context files: Auth patterns | Security standards | Code quality | Project structure"
-)
-// Returns: security-patterns.md, code-quality.md
-
-// 2. ExternalScout: Better Auth docs (MANDATORY)
-task(
-  subagent_type="ExternalScout",
-  description="Fetch Better Auth + Next.js docs",
-  prompt="Fetch Better Auth docs: Next.js App Router integration
-  
-  Focus on: Installation | App Router setup | Session mgmt | Route protection | Drizzle adapter
-  Context: Adding auth to Next.js commerce w/ Drizzle ORM"
-)
-// Returns: Current installation | Integration patterns | Drizzle config | Working examples
-
-// 3. Combine and implement
-// - Better Auth patterns (from ExternalScout)
-// - Security standards (from ContextScout)
-// - Code quality standards (from ContextScout)
-// = Secure, well-structured auth implementation ✅
-```
-
----
-
-## Error Handling
-
-| Error Type | Process |
-|------------|---------|
-| **Package Installation** | ExternalScout: installation docs → Verify package name/version → Check peer deps → Propose fix w/ current steps |
-| **Import/Module** | ExternalScout: import patterns → Check current API exports → Verify import paths → Propose fix w/ current imports |
-| **API/Configuration** | ExternalScout: API docs → Check current signatures → Verify config format → Propose fix w/ current patterns |
-| **Build Errors** | Identify package → ExternalScout: relevant docs → Check known issues/breaking changes → Propose fix from current docs |
-
----
-
-## Best Practices
-
-**Do** ✅:
-- Check install scripts first on new builds
-- Always fetch current docs before implementing
-- Use ExternalScout proactively on new builds
-- Verify versions match (package.json vs docs)
-- Check breaking changes when upgrading
-- Read install scripts before running
-- Check prerequisites (databases, services, env vars)
-- Test integrations between packages
-- Cache useful docs in `.opencode/context/development/frameworks/` if frequently used
-
-**Don't** ❌:
-- Assume APIs based on training data
-- Skip version checks (breaking changes are common)
-- Ignore peer dependencies
-- Mix patterns from different versions
-- Run install scripts blindly
-- Skip environment setup
-
----
-
-## Troubleshooting FAQ
-
-### "When exactly should I use ExternalScout?"
-
-**ALWAYS use ExternalScout when working with external packages.**
-
-**Triggers**: User mentions library | `import`/`require` statements | package.json deps | build errors | first-time setup | version upgrades
-
-**Rule**: If it's not in `.opencode/context/`, use ExternalScout.
-
----
-
-### "What if I already know the library?"
-
-**DON'T rely on training data - it's outdated.**
-
-Example: You think "I know Next.js, I'll use pages/" → Reality: Next.js 15 uses app/ → Result: Broken code ❌
-
-**Always fetch current docs, even if you "know" the library.**
-
----
-
-### "How do I know if something is external?"
-
-**External libraries**: npm/pip/gem/cargo packages | Third-party frameworks | ORMs/databases | Auth libraries | UI libraries
-
-**NOT external**: Your project's code | Project utilities | Internal modules
-
-**Check**: Is it in `package.json` dependencies? → External → Use ExternalScout
-
----
-
-### "Can I use both ContextScout and ExternalScout?"
-
-**YES! Use both for most features.**
-
-```javascript
-// 1. ContextScout: Project standards
-task(subagent_type="ContextScout", ...)
-// Returns: code-quality.md, security-patterns.md
-
-// 2. ExternalScout: Library docs
-task(subagent_type="ExternalScout", ...)
-// Returns: Current Next.js docs, Drizzle docs
-
-// 3. Combine: Implement using both
-```
-
----
-
-### "What if ExternalScout doesn't have the library?"
-
-**ExternalScout has two sources**:
-1. **Context7 API** (primary): 50+ popular libraries
-2. **Official docs** (fallback): Any library w/ public docs
-
-**If library not in Context7**: Auto-fallback to official docs via webfetch
-
-**You don't need to worry - ExternalScout handles it.**
-
----
-
-### "How do I write a good ExternalScout prompt?"
-
-**Template**:
-```javascript
-task(
-  subagent_type="ExternalScout",
-  description="Fetch [Library] docs for [specific topic]",
-  prompt="Fetch current documentation for [Library]: [specific question]
-  
-  Focus on:
-  - [What you need - be specific]
-  - [Related features/APIs]
-  - [Integration requirements]
-  
-  Context: [What you're building]"
-)
-```
-
-**Good prompts**: ✅ Specific | ✅ Focused (3-5 things) | ✅ Contextual | ✅ Current
-
-**Bad prompts**: ❌ Vague | ❌ Too broad | ❌ No context
-
----
-
-### "What if I get an error after using ExternalScout?"
-
-**Normal - errors happen. Process**:
-1. Read error message carefully
-2. ExternalScout again w/ specific error:
-   ```javascript
-   task(
-     subagent_type="ExternalScout",
-     description="Fetch docs for error resolution",
-     prompt="Fetch [Library] docs: [error message]
-     
-     Error: [paste actual error]
-     Focus on: Common causes | Solutions | Correct API usage"
-   )
-   ```
-3. Check install scripts (maybe setup incomplete)
-4. Verify versions (package.json vs docs)
-
----
-
-### "Do I need approval to use ExternalScout?"
-
-**NO - ExternalScout is read-only, no approval required.**
-
-**Approval required**: ❌ Write code | ❌ Run commands | ❌ Install packages
-
-**Approval NOT required**: ✅ ContextScout | ✅ ExternalScout | ✅ Read files | ✅ Search code
-
----
-
-### "ContextScout vs ExternalScout?"
-
-| Aspect | ContextScout | ExternalScout |
-|--------|--------------|---------------|
-| **Searches** | Internal project files | External documentation |
-| **Location** | `.opencode/context/` | Internet (Context7, official docs) |
-| **Returns** | Project standards, patterns | Library APIs, installation |
-| **Use for** | "How we do things here" | "How this library works" |
-| **Tools** | glob, read, grep | webfetch, Context7 API |
-| **Speed** | Fast (local) | Slower (network) |
-| **Currency** | Static (project docs) | Live (current docs) |
-
-**Use both together for best results.**
-
----
-
-### "Quick Checklist: Am I doing it right?"
-
-Before implementing w/ external libraries:
-
-- [ ] Used ContextScout for project standards?
-- [ ] Checked for install scripts first?
-- [ ] Used ExternalScout for EACH external library?
-- [ ] Asked for installation steps in ExternalScout prompt?
-- [ ] Asked for current API patterns and examples?
-- [ ] Specified what I'm building (context)?
-- [ ] Read returned docs before coding?
-- [ ] Following both project standards AND library docs?
-
-**All checked? → You're doing it right! ✅**
-
----
-
-## Supported Libraries
-
-**See**: `.opencode/skill/context7/library-registry.md`
-
-**Categories**: Database/ORM (Drizzle, Prisma) | Auth (Better Auth, NextAuth, Clerk) | Frontend (Next.js, React, TanStack) | Infrastructure (Cloudflare, AWS, Vercel) | UI (Shadcn/ui, Radix, Tailwind) | State (Zustand, Jotai) | Validation (Zod, React Hook Form) | Testing (Vitest, Playwright)
-
-**Not listed?** ExternalScout can still fetch from official docs via webfetch
-
----
-
-## References
-
-- **ExternalScout Agent**: `.opencode/agent/subagents/core/externalscout.md`
-- **Library Registry**: `.opencode/skill/context7/library-registry.md`
-- **ContextScout Agent**: `.opencode/agent/subagents/core/contextscout.md`
-- **Code Standards**: `.opencode/context/core/standards/code-quality.md`

.opencode/context/core/workflows/navigation.md

@@ -9,10 +9,23 @@
 | File | Topic | Priority | Load When |
 |------|-------|----------|-----------|
 | `code-review.md` | Code review process | ⭐⭐⭐⭐ | Reviewing code |
-| `task-delegation.md` | Delegating to subagents | ⭐⭐⭐⭐ | Using task tool |
+| `task-delegation-basics.md` | Core delegation workflow | ⭐⭐⭐⭐ | Using task tool |
+| `task-delegation-specialists.md` | When to delegate to whom | ⭐⭐⭐⭐ | Choosing specialist |
+| `task-delegation-caching.md` | Context caching | ⭐⭐⭐ | Repeated tasks |
+| `external-libraries-workflow.md` | External library process | ⭐⭐⭐⭐ | External packages |
+| `external-libraries-scenarios.md` | Common scenarios | ⭐⭐⭐ | Examples needed |
+| `external-libraries-faq.md` | Troubleshooting | ⭐⭐⭐ | Errors/questions |
 | `feature-breakdown.md` | Breaking down features | ⭐⭐⭐⭐ | 4+ files, complex tasks |
 | `session-management.md` | Managing sessions | ⭐⭐⭐ | Session cleanup |
-| `design-iteration.md` | Design iteration process | ⭐⭐⭐ | Design work |
+| `design-iteration-overview.md` | Design workflow overview | ⭐⭐⭐⭐ | Starting design work |
+| `design-iteration-plan-file.md` | Design plan template | ⭐⭐⭐⭐ | Creating design plan |
+| `design-iteration-stage-layout.md` | Stage 1: Layout | ⭐⭐⭐ | Layout design |
+| `design-iteration-stage-theme.md` | Stage 2: Theme | ⭐⭐⭐ | Theme design |
+| `design-iteration-stage-animation.md` | Stage 3: Animation | ⭐⭐⭐ | Animation design |
+| `design-iteration-stage-implementation.md` | Stage 4: Implementation | ⭐⭐⭐ | Implementation |
+| `design-iteration-visual-content.md` | Visual content generation | ⭐⭐ | Image generation |
+| `design-iteration-best-practices.md` | Best practices & troubleshooting | ⭐⭐⭐ | Quality check |
+| `design-iteration-plan-iterations.md` | Plan file iterations | ⭐⭐⭐ | Managing iterations |
 
 ---
 
@@ -23,7 +36,12 @@
 2. Depends on: `../standards/code-quality.md`, `../standards/security-patterns.md`
 
 **For task delegation**:
-1. Load `task-delegation.md` (high)
+1. Load `task-delegation-basics.md` (high)
+2. Load `task-delegation-specialists.md` (when choosing agent)
+
+**For external libraries**:
+1. Load `external-libraries-workflow.md` (high)
+2. Reference `external-libraries-scenarios.md` for examples
 
 **For complex features**:
 1. Load `feature-breakdown.md` (high)

.opencode/context/core/workflows/task-delegation-basics.md

@@ -0,0 +1,138 @@
+<!-- Context: workflows/delegation | Priority: high | Version: 3.1 | Updated: 2026-02-05 -->
+# Delegation Context Template
+
+## Quick Reference
+
+**Process**: Discover → Propose → Approve → Init Session → Persist Context → Delegate → Cleanup
+
+**Location**: `.tmp/sessions/{YYYY-MM-DD}-{task-slug}/context.md`
+
+**Key Principle**: ContextScout discovers paths. The orchestrator persists them into context.md AFTER approval. Downstream agents read from context.md — no re-discovery.
+
+---
+
+## When to Create a Session
+
+Only create a session when:
+- User has **approved** the proposed approach (never before)
+- Task requires delegation to TaskManager or working agents
+- Task is complex enough to need shared context (4+ files, >60min)
+
+For simple tasks (1-3 files, direct execution): skip session creation entirely.
+
+---
+
+## The Flow
+
+```
+Stage 1: DISCOVER   → ContextScout finds paths (read-only, nothing written)
+Stage 2: PROPOSE    → Show user lightweight summary (nothing written)
+Stage 3: APPROVE    → User says yes. NOW we can write.
+Stage 4: INIT       → Create session dir + context.md (persist discovered paths here)
+Stage 5: DELEGATE   → Pass session path to TaskManager / working agents
+Stage 6: CLEANUP    → Ask user, then delete session dir
+```
+
+---
+
+## Template Structure
+
+**Location**: `.tmp/sessions/{YYYY-MM-DD}-{task-slug}/context.md`
+
+```markdown
+# Task Context: {Task Name}
+
+Session ID: {YYYY-MM-DD}-{task-slug}
+Created: {ISO timestamp}
+Status: in_progress
+
+## Current Request
+{What user asked for — verbatim or close paraphrase}
+
+## Context Files (Standards to Follow)
+Paths ContextScout discovered. Downstream agents load these for coding standards.
+- .opencode/context/core/standards/code-quality.md
+- {other paths}
+
+## Reference Files (Source Material)
+Project files relevant to the task — NOT standards.
+- {e.g. package.json}
+- {e.g. src/existing-module.ts}
+
+## External Context Fetched
+Live docs fetched via ExternalScout. Read-only cache.
+- `.tmp/external-context/{package}/{topic}.md` — {description}
+
+## Components
+- {Component 1} — {what it does}
+- {Component 2} — {what it does}
+
+## Constraints
+{Technical constraints, preferences, version requirements}
+
+## Exit Criteria
+- [ ] {specific completion condition}
+
+## Progress
+- [ ] Session initialized
+- [ ] Tasks created (if using TaskManager)
+- [ ] Implementation complete
+```
+
+---
+
+## Delegation Process
+
+**Step 1-3: Discover, Propose, Approve** (before any writes)
+- Call ContextScout, capture paths
+- Call ExternalScout if external libraries involved
+- Show user lightweight summary, wait for approval
+
+**Step 4: Init Session** (first writes, after approval)
+- Create `.tmp/sessions/{YYYY-MM-DD}-{task-slug}/`
+- Write `context.md` with discovered paths
+
+**Step 5: Delegate**
+```javascript
+task(
+  subagent_type="TaskManager",
+  description="{brief}",
+  prompt="Load context from .tmp/sessions/{session-id}/context.md
+          {specific instructions}"
+)
+```
+
+**Step 6: Cleanup**
+- Ask user: "Task complete. Clean up session files?"
+- If approved: Delete session directory
+
+---
+
+## Semantic Rules for Task JSONs
+
+| Field | Contains | Example |
+|-------|----------|---------|
+| `context_files` | **Standards only** | `.opencode/context/core/standards/code-quality.md` |
+| `reference_files` | **Source material only** | `src/auth/service.ts` |
+| `external_context` | **External docs only** (read-only) | `.tmp/external-context/drizzle/schemas.md` |
+
+**Never mix them.** Standards vs source material vs external docs.
+
+---
+
+## What Downstream Agents Expect
+
+| Agent | Reads | Does |
+|-------|-------|------|
+| **TaskManager** | `context.md` (full) | Extracts files, creates subtask JSONs |
+| **CoderAgent** | subtask JSON | Loads standards, references source, implements |
+| **TestEngineer** | session path | Writes tests against same standards |
+| **CodeReviewer** | session path | Reviews against applied standards |
+
+---
+
+## Related
+
+- `task-delegation-specialists.md` - When to delegate to which specialist
+- `task-delegation-caching.md` - Context caching for repeated patterns
+- `../context-system/standards/mvi.md` - MVI principle

.opencode/context/core/workflows/task-delegation-caching.md

@@ -0,0 +1,143 @@
+<!-- Context: workflows/delegation-caching | Priority: medium | Version: 1.0 | Updated: 2026-02-05 -->
+# Context Caching for Delegation
+
+**Purpose**: Cache discovered context to avoid re-discovery overhead in repeated tasks
+
+---
+
+## When to Cache
+
+Cache context when:
+- Same task type appears multiple times in session
+- Same context files needed repeatedly
+- Multiple subtasks use identical standards
+- Parallel tasks need same context
+
+---
+
+## Cache Structure
+
+```
+.tmp/sessions/{session-id}/
+├── context.md (main session context)
+├── .cache/
+│   ├── test-coverage.md (cached from .opencode/context/)
+│   ├── code-quality.md
+│   └── code-review.md
+└── .manifest.json (tracks cache status)
+```
+
+---
+
+## Cache Manifest
+
+```json
+{
+  "session_id": "2026-01-28-parallel-tests",
+  "created_at": "2026-01-28T14:30:22Z",
+  "cache": {
+    "test-coverage.md": {
+      "source": ".opencode/context/core/standards/test-coverage.md",
+      "cached_at": "2026-01-28T14:30:25Z",
+      "used_by": ["subtask_01", "subtask_02"],
+      "status": "valid"
+    }
+  }
+}
+```
+
+---
+
+## Invalidation Rules
+
+**Cache is INVALID when:**
+- Source file modified (check timestamp)
+- Session older than 24 hours
+- Context file version changed
+- User explicitly requests refresh
+
+**Cache is VALID when:**
+- Source timestamp matches
+- Session less than 24 hours old
+- No version changes
+- Multiple tasks in same session
+
+---
+
+## Implementation Pattern
+
+```javascript
+// Before delegating to subagent
+IF cache exists AND cache is valid:
+  USE cached context file
+  SKIP re-reading from .opencode/context/
+ELSE:
+  READ from .opencode/context/
+  CACHE the file
+```
+
+---
+
+## Example: Parallel Tasks
+
+```javascript
+session_id = "2026-01-28-parallel-tests"
+
+// Task 1: Write component A (parallel)
+task(
+  subagent_type="CoderAgent",
+  description="Write component A",
+  prompt="Load context from .tmp/sessions/{session_id}/context.md
+          Use cached context if available at .cache/"
+)
+
+// Task 2: Write component B (parallel)  
+task(
+  subagent_type="CoderAgent",
+  description="Write component B",
+  prompt="Load context from .tmp/sessions/{session_id}/context.md
+          Use cached context if available at .cache/"
+)
+
+// Result: Task 1 caches context, Task 2 uses cache (faster)
+```
+
+---
+
+## Cache Effectiveness
+
+Track metrics:
+```json
+{
+  "cache_stats": {
+    "total_reads": 15,
+    "cache_hits": 9,
+    "cache_misses": 6,
+    "hit_rate": "60%"
+  }
+}
+```
+
+---
+
+## Best Practices
+
+✅ **Do:**
+- Cache context for repeated task types
+- Validate cache before using
+- Invalidate when source changes
+- Monitor hit rate
+- Clean up cache with session
+
+❌ **Don't:**
+- Cache external context (always fetch fresh)
+- Cache for single-task sessions (overhead not worth it)
+- Ignore invalidation rules
+- Mix cached and fresh context in same task
+
+---
+
+## Related
+
+- `task-delegation-basics.md` - Core delegation workflow
+- `task-delegation-specialists.md` - When to delegate

.opencode/context/core/workflows/task-delegation-specialists.md

@@ -0,0 +1,130 @@
+<!-- Context: workflows/delegation-specialists | Priority: high | Version: 1.0 | Updated: 2026-02-05 -->
+# When to Delegate to Specialists
+
+**Purpose**: Guidance on when to delegate to specific specialist agents
+
+---
+
+## OpenFrontendSpecialist - UI/UX Design
+
+**✅ DELEGATE when:**
+- Creating new UI/UX designs (landing pages, dashboards)
+- Building design systems (components, themes, style guides)
+- Complex layouts requiring responsive design
+- Visual polish (animations, transitions, micro-interactions)
+- Brand-focused pages (marketing, product showcases)
+- Accessibility-critical UI
+
+**Delegation pattern:**
+```javascript
+task(
+  subagent_type="OpenFrontendSpecialist",
+  description="Design {feature} UI",
+  prompt="Load context from .tmp/sessions/{session-id}/context.md
+  
+  Design {feature} following 4-stage workflow:
+  1. Stage 0: Create design plan file (MANDATORY FIRST)
+  2. Stage 1: Layout (ASCII wireframe)
+  3. Stage 2: Theme (design system, colors)
+  4. Stage 3: Animation (micro-interactions)
+  5. Stage 4: Implementation (single HTML file)
+  
+  Request approval between stages."
+)
+```
+
+**Why?** Follows structured 4-stage workflow with approval gates, produces polished UI.
+
+---
+
+## TestEngineer - Test Authoring
+
+**✅ DELEGATE when:**
+- Writing comprehensive test suites
+- TDD workflows (tests before implementation)
+- Complex test scenarios (edge cases, error handling)
+- Integration tests across multiple components
+
+**Delegation pattern:**
+```javascript
+task(
+  subagent_type="TestEngineer",
+  description="Write tests for {feature}",
+  prompt="Load context from .tmp/sessions/{session-id}/context.md
+  
+  Write comprehensive tests for {feature}
+  Files to test: {file list}
+  Follow test coverage standards from context."
+)
+```
+
+---
+
+## CodeReviewer - Quality Assurance
+
+**✅ DELEGATE when:**
+- Reviewing complex implementations
+- Security-critical code review
+- Pre-merge quality checks
+- Architecture validation
+
+**Delegation pattern:**
+```javascript
+task(
+  subagent_type="CodeReviewer",
+  description="Review {feature}",
+  prompt="Load context from .tmp/sessions/{session-id}/context.md
+  
+  Review {feature} against standards
+  Files: {file list}
+  Focus: security, performance, maintainability"
+)
+```
+
+---
+
+## CoderAgent - Focused Implementation
+
+**✅ DELEGATE when:**
+- Implementing atomic subtasks from TaskManager
+- Isolated feature work (single component/module)
+- Following specific implementation specs
+
+**Delegation pattern:**
+```javascript
+task(
+  subagent_type="CoderAgent",
+  description="Implement {subtask}",
+  prompt="Load context from .tmp/sessions/{session-id}/context.md
+  
+  Implement subtask: {description}
+  Follow implementation spec exactly.
+  Mark subtask complete when done."
+)
+```
+
+---
+
+## Decision Matrix
+
+| Scenario | Agent | Why |
+|----------|-------|-----|
+| New landing page | OpenFrontendSpecialist | 4-stage design workflow |
+| Test suite for auth | TestEngineer | Comprehensive coverage |
+| Security review | CodeReviewer | Security focus |
+| Single API endpoint | CoderAgent | Focused implementation |
+| Complex multi-file feature | TaskManager → CoderAgent | Breakdown then implement |
+
+---
+
+## Key Principle
+
+**TestEngineer and CodeReviewer should ALWAYS receive session context path.** This ensures they review against the same standards used during implementation.
+
+---
+
+## Related
+
+- `task-delegation-basics.md` - Core delegation workflow
+- `task-delegation-caching.md` - Context caching
+- `design-iteration.md` - OpenFrontendSpecialist workflow

.opencode/context/core/workflows/task-delegation.md

@@ -1,460 +0,0 @@
-<!-- Context: workflows/delegation | Priority: high | Version: 3.0 | Updated: 2026-01-28 -->
-# Delegation Context Template
-
-## Quick Reference
-
-**Process**: Discover → Propose → Approve → Init Session → Persist Context → Delegate → Cleanup
-
-**Location**: `.tmp/sessions/{YYYY-MM-DD}-{task-slug}/context.md`
-
-**Key Principle**: ContextScout discovers paths. The orchestrator persists them into context.md AFTER approval. Downstream agents read from context.md — no re-discovery.
-
----
-
-## When to Create a Session
-
-Only create a session when:
-- User has **approved** the proposed approach (never before)
-- Task requires delegation to TaskManager or working agents
-- Task is complex enough to need shared context (4+ files, >60min)
-
-For simple tasks (1-3 files, direct execution): skip session creation entirely.
-
----
-
-## The Flow
-
-```
-Stage 1: DISCOVER   → ContextScout finds paths (read-only, nothing written)
-Stage 2: PROPOSE    → Show user lightweight summary (nothing written)
-Stage 3: APPROVE    → User says yes. NOW we can write.
-Stage 4: INIT       → Create session dir + context.md (persist discovered paths here)
-Stage 5: DELEGATE   → Pass session path to TaskManager / working agents
-Stage 6: CLEANUP    → Ask user, then delete session dir
-```
-
----
-
-## Template Structure
-
-**Location**: `.tmp/sessions/{YYYY-MM-DD}-{task-slug}/context.md`
-
-```markdown
-# Task Context: {Task Name}
-
-Session ID: {YYYY-MM-DD}-{task-slug}
-Created: {ISO timestamp}
-Status: in_progress
-
-## Current Request
-{What user asked for — verbatim or close paraphrase}
-
-## Context Files (Standards to Follow)
-These are the paths ContextScout discovered. Downstream agents load these for coding standards, patterns, and conventions.
-- .opencode/context/core/standards/code-quality.md
-- .opencode/context/core/standards/test-coverage.md
-- {other paths discovered by ContextScout}
-
-## Reference Files (Source Material to Look At)
-These are project files relevant to the task — NOT standards. Downstream agents reference these to understand existing code, config, or structure.
-- {e.g. package.json}
-- {e.g. src/existing-module.ts}
-
-## External Context Fetched
-These are live documentation files fetched from external libraries via ExternalScout. Subagents should reference these instead of re-fetching.
-- `.tmp/external-context/{package-name}/{topic}.md` — {description}
-- `.tmp/external-context/{package-name}/{topic}.md` — {description}
-
-**Important**: These files are read-only and cached for reference. Do not modify them.
-
-## Components
-{The functional units identified during proposal}
-- {Component 1} — {what it does}
-- {Component 2} — {what it does}
-
-## Constraints
-{Technical constraints, preferences, compatibility notes, version requirements}
-
-## Exit Criteria
-- [ ] {specific, measurable completion condition}
-- [ ] {specific, measurable completion condition}
-
-## Progress
-- [ ] Session initialized
-- [ ] Tasks created (if using TaskManager)
-- [ ] Implementation complete
-- [ ] Tests passing
-- [ ] Handoff complete
-```
-
----
-
-## Delegation Process
-
-**Step 1: Discover** (before approval)
-- Call ContextScout. Capture the returned file paths.
-- Call ExternalScout if external libraries involved.
-- Do NOT write anything to disk.
-
-**Step 2: Propose** (before approval)
-- Show user a lightweight summary of approach + discovered context.
-- Do NOT create session or plan docs.
-
-**Step 3: Approve** (gate)
-- Wait for explicit user approval.
-- If rejected or redirected → back to Step 1.
-
-**Step 4: Init Session** (first writes, only after approval)
-- Create `.tmp/sessions/{YYYY-MM-DD}-{task-slug}/`
-- Write `context.md` using the template above.
-- **CRITICAL**: Populate `## Context Files` with the paths ContextScout discovered in Step 1. This is the handoff point — if you skip this, downstream agents lose the context.
-- Populate `## Reference Files` with any project source files relevant to the task.
-
-**Step 5: Delegate with context path**
-```
-task(
-  subagent_type="TaskManager",  // or CoderAgent, TestEngineer, etc.
-  description="{brief description}",
-  prompt="Load context from .tmp/sessions/{session-id}/context.md
-
-          Read the context file for full requirements, standards, and constraints.
-          {specific instructions for this subagent}"
-)
-```
-
-**Step 6: Cleanup after completion**
-- Ask user: "Task complete. Clean up session files at `.tmp/sessions/{session-id}/`?"
-- If approved: Delete session directory.
-
----
-
-## Semantic Rules for Task JSONs
-
-When TaskManager creates subtask JSONs, it MUST follow these rules:
-
-| Field | Contains | Example |
-|-------|----------|---------|
-| `context_files` | **Standards only** — paths to coding conventions, patterns, security rules | `.opencode/context/core/standards/code-quality.md` |
-| `reference_files` | **Source material only** — project files to look at for existing patterns | `src/auth/existing-service.ts`, `package.json` |
-| `external_context` | **External docs only** — cached documentation from external libraries (read-only) | `.tmp/external-context/drizzle-orm/modular-schemas.md` |
-
-**Never mix them.** A downstream agent reading `context_files` expects "rules to follow." A downstream agent reading `reference_files` expects "files to understand." A downstream agent reading `external_context` expects "cached external docs to reference" (read-only). Mixing them causes confusion about what to follow vs. what to reference vs. what to read.
-
----
-
-## What Downstream Agents Expect
-
-| Agent | What it reads | What it does with it |
-|-------|---------------|---------------------|
-| **TaskManager** | `context.md` (full session) | Extracts context_files + reference_files + external_context, puts them into subtask JSONs |
-| **CoderAgent** | subtask JSON (`context_files` + `reference_files` + `external_context`) | Loads standards, references source files, reads external docs, implements |
-| **TestEngineer** | session `context.md` path (passed in prompt) | Knows what standards were applied, reads external context, writes tests accordingly |
-| **CodeReviewer** | session `context.md` path (passed in prompt) | Knows what standards were applied, reviews against them, considers external context |
-| **OpenFrontendSpecialist** | session `context.md` path (passed in prompt) | Follows 4-stage design workflow (Layout → Theme → Animation → Implementation) |
-
-**Key**: 
-- TestEngineer and CodeReviewer should ALWAYS receive the session context path when delegated. This way they review against the same standards that were used during implementation — not whatever they independently discover.
-- All agents should read `external_context` files to understand external library patterns and requirements — this avoids re-fetching and ensures consistency.
-- **OpenFrontendSpecialist should be used for UI/UX design work** - See `workflows/design-iteration.md` for when to delegate vs execute directly.
-
----
-
-## When to Delegate to Specialists
-
-### OpenFrontendSpecialist - UI/UX Design
-
-**✅ STRONGLY RECOMMENDED to delegate when:**
-- Creating new UI/UX designs (landing pages, dashboards, app interfaces)
-- Building design systems (component libraries, themes, style guides)
-- Complex layouts requiring responsive design
-- Visual polish work (animations, transitions, micro-interactions)
-- Brand-focused pages (marketing, product showcases)
-- Accessibility-critical UI (forms, navigation, interactive components)
-
-**Delegation pattern:**
-```javascript
-task(
-  subagent_type="OpenFrontendSpecialist",
-  description="Design {feature} UI",
-  prompt="Load context from .tmp/sessions/{session-id}/context.md
-  
-  Design a {feature} following the 4-stage workflow:
-  
-  CRITICAL: Create design plan file at .tmp/design-plans/{project}-{feature}.md BEFORE starting
-  
-  Stages:
-  1. Stage 0: Create design plan file (MANDATORY FIRST)
-  2. Stage 1: Layout (ASCII wireframe) → Update plan file
-  3. Stage 2: Theme (design system, colors) → Update plan file
-  4. Stage 3: Animation (micro-interactions) → Update plan file
-  5. Stage 4: Implementation (single HTML file) → Update plan file
-  
-  Requirements:
-  - {requirement 1}
-  - {requirement 2}
-  
-  Plan file preserves context across stages and allows user to review/edit.
-  Request approval between each stage.
-  Update plan file after each stage and user feedback."
-)
-```
-
-**Why delegate?**
-- Follows structured 4-stage design workflow with approval gates
-- Produces polished, accessible, production-ready UI
-- Handles responsive design, OKLCH colors, semantic HTML
-- Creates single-file HTML prototypes for quick iteration
-
-**See**: `workflows/design-iteration.md` for full workflow details
-
-### TestEngineer - Test Authoring
-
-**Delegate when:**
-- Writing comprehensive test suites
-- TDD workflows (tests before implementation)
-- Complex test scenarios (edge cases, error handling)
-- Integration tests across multiple components
-
-**Delegation pattern:**
-```javascript
-task(
-  subagent_type="TestEngineer",
-  description="Write tests for {feature}",
-  prompt="Load context from .tmp/sessions/{session-id}/context.md
-  
-  Write comprehensive tests for {feature}
-  
-  Files to test:
-  - {file 1}
-  - {file 2}
-  
-  Follow test coverage standards from context."
-)
-```
-
-### CodeReviewer - Quality Assurance
-
-**Delegate when:**
-- Reviewing complex implementations
-- Security-critical code review
-- Pre-merge quality checks
-- Architecture validation
-
-**Delegation pattern:**
-```javascript
-task(
-  subagent_type="CodeReviewer",
-  description="Review {feature} implementation",
-  prompt="Load context from .tmp/sessions/{session-id}/context.md
-  
-  Review {feature} implementation against standards
-  
-  Files to review:
-  - {file 1}
-  - {file 2}
-  
-  Focus on: security, performance, maintainability"
-)
-```
-
-### CoderAgent - Focused Implementation
-
-**Delegate when:**
-- Implementing atomic subtasks from TaskManager
-- Isolated feature work (single component/module)
-- Following specific implementation specs
-
-**Delegation pattern:**
-```javascript
-task(
-  subagent_type="CoderAgent",
-  description="Implement {subtask}",
-  prompt="Load context from .tmp/sessions/{session-id}/context.md
-  
-  Implement subtask: {subtask description}
-  
-  Follow the implementation spec exactly.
-  Mark subtask as complete when done."
-)
-```
-
----
-
-## Context Caching for Repeated Patterns
-
-For repeated task types (e.g., "write tests", "code review", "documentation"), cache discovered context to avoid re-discovery overhead.
-
-### When to Cache
-
-Cache context when:
-- Same task type appears multiple times in a session
-- Same context files are needed repeatedly
-- Multiple subtasks use identical standards
-- Parallel tasks need the same context
-
-### Cache Structure
-
-```
-.tmp/sessions/{session-id}/
-├── context.md (main session context)
-├── .cache/
-│   ├── test-coverage.md (cached from .opencode/context/core/standards/test-coverage.md)
-│   ├── code-quality.md (cached from .opencode/context/core/standards/code-quality.md)
-│   └── code-review.md (cached from .opencode/context/core/workflows/code-review.md)
-└── .manifest.json (tracks cache status)
-```
-
-### Cache Manifest
-
-```json
-{
-  "session_id": "2026-01-28-parallel-tests",
-  "created_at": "2026-01-28T14:30:22Z",
-  "cache": {
-    "test-coverage.md": {
-      "source": ".opencode/context/core/standards/test-coverage.md",
-      "cached_at": "2026-01-28T14:30:25Z",
-      "used_by": ["subtask_01", "subtask_02", "subtask_03"],
-      "status": "valid"
-    },
-    "code-quality.md": {
-      "source": ".opencode/context/core/standards/code-quality.md",
-      "cached_at": "2026-01-28T14:30:26Z",
-      "used_by": ["subtask_01", "subtask_02"],
-      "status": "valid"
-    }
-  }
-}
-```
-
-### Cache Invalidation Rules
-
-Cache is INVALID when:
-- Source file has been modified (check timestamp)
-- Session is older than 24 hours
-- Context file version has changed
-- User explicitly requests cache refresh
-
-Cache is VALID when:
-- Source file timestamp matches cached timestamp
-- Session is less than 24 hours old
-- No version changes detected
-- Multiple tasks in same session use same context
-
-### Implementation Pattern
-
-**Step 1: Check Cache**
-```javascript
-// Before delegating to subagent
-IF cache exists AND cache is valid:
-  USE cached context file
-  SKIP re-reading from .opencode/context/
-ELSE:
-  READ from .opencode/context/
-  CACHE the file
-```
-
-**Step 2: Cache Hit Example**
-```
-Session: 2026-01-28-parallel-tests
-
-Task 1: Write component A
-  → Load test-coverage.md (CACHE MISS)
-  → Cache it at .tmp/sessions/.../cache/test-coverage.md
-  
-Task 2: Write component B
-  → Load test-coverage.md (CACHE HIT)
-  → Use cached version (faster)
-  
-Task 3: Write tests
-  → Load test-coverage.md (CACHE HIT)
-  → Use cached version (faster)
-```
-
-**Step 3: Cache Miss Example**
-```
-Session: 2026-01-28-parallel-tests
-
-Task 1: Write code
-  → Load code-quality.md (CACHE MISS)
-  → Cache it
-  
-Task 2: Code review
-  → Load code-review.md (CACHE MISS)
-  → Cache it
-  
-Task 3: Write more code
-  → Load code-quality.md (CACHE HIT)
-  → Use cached version
-```
-
-### Benefits
-
-- **Faster execution**: Avoid re-reading same files
-- **Reduced I/O**: Fewer file system operations
-- **Better performance**: Especially for parallel tasks
-- **Consistent context**: All tasks use same version
-
-### Example: Parallel Tasks with Caching
-
-```javascript
-// Session initialization
-session_id = "2026-01-28-parallel-tests"
-context_cache = {}
-
-// Task 1: Write component A (parallel)
-task(
-  subagent_type="CoderAgent",
-  description="Write component A",
-  prompt="Load context from .tmp/sessions/{session_id}/context.md
-          Use cached context if available at .tmp/sessions/{session_id}/.cache/"
-)
-
-// Task 2: Write component B (parallel)
-task(
-  subagent_type="CoderAgent",
-  description="Write component B",
-  prompt="Load context from .tmp/sessions/{session_id}/context.md
-          Use cached context if available at .tmp/sessions/{session_id}/.cache/"
-)
-
-// Task 3: Write tests (depends on 1+2)
-task(
-  subagent_type="TestEngineer",
-  description="Write tests",
-  prompt="Load context from .tmp/sessions/{session_id}/context.md
-          Use cached context if available at .tmp/sessions/{session_id}/.cache/"
-)
-
-// Result: Tasks 1 & 2 cache context, Task 3 uses cache (faster)
-```
-
-### Monitoring Cache
-
-Track cache effectiveness:
-```json
-{
-  "cache_stats": {
-    "total_reads": 15,
-    "cache_hits": 9,
-    "cache_misses": 6,
-    "hit_rate": "60%",
-    "time_saved": "2.3 seconds"
-  }
-}
-```
-
-### Best Practices
-
-✅ **Do**:
-- Cache context for repeated task types
-- Validate cache before using
-- Invalidate cache when source changes
-- Monitor cache hit rate
-- Clean up cache with session
-
-❌ **Don't**:
-- Cache external context (always fetch fresh)
-- Cache for single-task sessions (overhead not worth it)
-- Ignore cache invalidation rules
-- Mix cached and fresh context in same task

.opencode/context/openagents-repo/concepts/agent-skills.md

@@ -0,0 +1,59 @@
+# Agent Skills
+
+**Purpose**: Markdown files that teach Claude how to do specific tasks
+
+---
+
+## Core Concept
+
+A Skill is a `SKILL.md` file that teaches Claude specialized knowledge. Skills are **model-invoked**: Claude automatically applies them based on task context matching the description field.
+
+---
+
+## Key Points
+
+- Skills live in `~/.claude/skills/` (personal) or `.claude/skills/` (project)
+- Each skill needs a directory with `SKILL.md` inside
+- Name and description in YAML frontmatter are required
+- Claude loads only name/description at startup (lazy loading)
+- Full content loaded when skill is activated
+
+---
+
+## Skill File Format
+
+```yaml
+---
+name: explaining-code
+description: Explains code with diagrams and analogies. Use when explaining how code works.
+---
+
+When explaining code, always include:
+1. **Start with an analogy**: Compare to everyday life
+2. **Draw a diagram**: ASCII art for flow/structure
+3. **Walk through the code**: Step-by-step
+4. **Highlight a gotcha**: Common mistakes
+```
+
+---
+
+## Where Skills Live
+
+| Location | Path | Scope |
+|----------|------|-------|
+| Enterprise | Managed settings | All org users |
+| Personal | `~/.claude/skills/` | You, all projects |
+| Project | `.claude/skills/` | Anyone in repo |
+| Plugin | Plugin's `skills/` | Plugin users |
+
+Priority: Enterprise > Personal > Project > Plugin
+
+---
+
+## Related
+
+- `../guides/creating-skills.md` - How to create skills
+- `../lookup/skill-metadata.md` - Metadata fields
+- `../lookup/skills-comparison.md` - Skills vs other options
+
+**Reference**: https://docs.anthropic.com/en/docs/claude-code/skills

.opencode/context/openagents-repo/concepts/compatibility-layer.md

@@ -0,0 +1,128 @@
+# Concept: Compatibility Layer Architecture
+
+**Purpose**: Enable bidirectional translation between OpenAgents Control and other AI coding tools
+
+**Last Updated**: 2026-02-04
+
+---
+
+## Core Idea
+
+Adapter pattern that translates agent configurations between OAC format and tool-specific formats (Cursor IDE, Claude Code, Windsurf). Enables seamless migration and multi-tool workflows through bidirectional mapping with graceful degradation.
+
+---
+
+## Key Components
+
+**Adapters**: Tool-specific translation classes inheriting from BaseAdapter
+- ClaudeAdapter - Claude Code format (.claude/config.json + skills)
+- CursorAdapter - Cursor IDE format (.cursorrules single file)
+- WindsurfAdapter - Windsurf format (.windsurf/agents/)
+
+**Mappers**: Pure functions for feature translation
+- ToolMapper - Tool name mapping (bash → terminal, task → delegate)
+- PermissionMapper - Permission translation with degradation
+- ModelMapper - Model ID mapping with fallbacks
+- ContextMapper - Context file path translation
+
+**Core Services**:
+- AgentLoader - Parse OAC markdown files with YAML frontmatter
+- AdapterRegistry - Register and retrieve adapters
+- TranslationEngine - Orchestrate bidirectional conversion
+- CapabilityMatrix - Track feature parity across tools
+
+---
+
+## Architecture Pattern
+
+```
+OAC Agent File (.md)
+  ↓ (parse)
+AgentLoader → OpenAgent object (validated with Zod)
+  ↓ (convert)
+BaseAdapter.fromOAC()
+  ↓ (map features)
+Mappers (tools, permissions, models, contexts)
+  ↓ (output)
+Tool-specific config files
+```
+
+**Reverse direction**: Tool config → toOAC() → OpenAgent → OAC .md file
+
+---
+
+## Design Principles
+
+- **Bidirectional**: Convert OAC → Tool AND Tool → OAC where possible
+- **Graceful Degradation**: Map unsupported features to closest equivalent with warnings
+- **Pure Mappers**: All mapping functions are pure (no side effects)
+- **Template Method**: BaseAdapter defines algorithm, subclasses fill details
+- **Validation First**: Zod schemas validate before/after conversion
+
+---
+
+## Feature Parity
+
+| Feature | OAC | Claude | Cursor | Windsurf |
+|---------|-----|--------|--------|----------|
+| Multiple agents | ✅ | ✅ | ❌ Single | ✅ |
+| Granular permissions | ✅ | ⚠️ Simplified | ❌ | ⚠️ Partial |
+| Temperature | ✅ | ❌ | ⚠️ Partial | ⚠️ Partial |
+| Skills | ✅ | ✅ | ❌ | ⚠️ Partial |
+| Hooks | ✅ | ✅ | ❌ | ❌ |
+| Context files | ✅ | ✅ Skills | ✅ .cursorrules | ✅ |
+
+---
+
+## Quick Example
+
+```typescript
+// Load OAC agent
+const agent = await AgentLoader.loadAgent('.opencode/agent/openagent.md')
+
+// Get Claude adapter
+const adapter = AdapterRegistry.get('claude')
+
+// Convert to Claude format
+const result = await adapter.fromOAC(agent)
+
+// Outputs: .claude/config.json, .claude/skills/[...]
+console.log(result.configs) // Array of files to write
+console.log(result.warnings) // Feature degradation warnings
+```
+
+---
+
+## Common Challenges
+
+**Single-File Tools** (Cursor): Merge multiple OAC agents into one .cursorrules file
+**Permission Mapping**: OAC granular permissions → simplified tool permissions
+**Model IDs**: Different tools use different model identifiers (requires mapping table)
+**Context Paths**: OAC uses .opencode/context/, tools use various paths
+
+---
+
+## Implementation Status
+
+**Issue #141**: https://github.com/darrenhinde/OpenAgentsControl/issues/141
+
+**Progress**: 28.13% (9/32 subtasks)
+- ✅ Phase 1 (Foundation): 100% complete - 1,475 lines
+- ⬅️ Phase 2 (Adapters): 50% complete - 1,858 lines (implementations done, tests pending)
+- 📝 Phase 3 (Mappers): 0% - Pending
+- 📝 Phase 4 (CLI): 0% - Pending
+- 📝 Phase 5 (Documentation): 0% - Pending
+
+**Location**: `packages/compatibility-layer/src/`
+
+---
+
+## Reference
+
+- **Related**: 
+  - examples/baseadapter-implementation.md
+  - guides/compatibility-layer-development.md
+  - lookup/compatibility-layer-adapters.md
+  - lookup/compatibility-layer-progress.md
+  - lookup/compatibility-learnings.md
+  - lookup/tool-feature-parity.md

.opencode/context/openagents-repo/concepts/hooks-system.md

@@ -0,0 +1,64 @@
+# Hooks System
+
+**Purpose**: User-defined shell commands that execute at Claude Code lifecycle points
+
+---
+
+## Core Concept
+
+Hooks provide **deterministic control** over Claude Code's behavior. Unlike prompting (which suggests), hooks **guarantee** certain actions happen at specific points in the workflow.
+
+---
+
+## Key Points
+
+- Hooks are shell commands triggered by events
+- Run automatically during agent loop with your credentials
+- Can block operations (exit code 2), allow silently, or provide feedback
+- Configure in `settings.json` or plugin's `hooks/hooks.json`
+- Matchers filter which tools/events trigger the hook
+
+---
+
+## Common Use Cases
+
+| Use Case | Event | Example |
+|----------|-------|---------|
+| Auto-format | `PostToolUse` | Run prettier after Edit/Write |
+| Notifications | `Notification` | Desktop alert when input needed |
+| File protection | `PreToolUse` | Block edits to .env files |
+| Logging | `PreToolUse` | Track all bash commands |
+| Feedback | `PostToolUse` | Lint check after code changes |
+
+---
+
+## Quick Example
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [{
+      "matcher": "Bash",
+      "hooks": [{
+        "type": "command",
+        "command": "jq -r '.tool_input.command' >> ~/.claude/bash-log.txt"
+      }]
+    }]
+  }
+}
+```
+
+---
+
+## Security Warning
+
+Hooks run with your credentials. Malicious hooks can exfiltrate data. Always review hook implementations before adding them.
+
+---
+
+## Related
+
+- `../lookup/hook-events.md` - All hook events
+- `../examples/hooks/` - Hook examples
+
+**Reference**: https://docs.anthropic.com/en/docs/claude-code/hooks

.opencode/context/openagents-repo/concepts/subagents-system.md

@@ -0,0 +1,58 @@
+# Subagents System
+
+**Purpose**: Specialized AI assistants with own context window for task-specific workflows
+
+---
+
+## Core Concept
+
+Subagents are isolated AI assistants that handle specific tasks. Each runs in its own context with custom system prompt, specific tool access, and independent permissions. When Claude encounters a matching task, it delegates to the subagent.
+
+---
+
+## Key Benefits
+
+- **Preserve context**: Keep exploration/implementation out of main conversation
+- **Enforce constraints**: Limit which tools subagent can use
+- **Reuse configs**: User-level subagents work across projects
+- **Specialize behavior**: Focused prompts for specific domains
+- **Control costs**: Route to faster/cheaper models (Haiku)
+
+---
+
+## How Delegation Works
+
+1. Claude analyzes task description and subagent descriptions
+2. Matches task to appropriate subagent
+3. Delegates work to subagent's isolated context
+4. Subagent works independently
+5. Returns results to main conversation
+
+---
+
+## Subagent Locations
+
+| Location | Scope | Priority |
+|----------|-------|----------|
+| `--agents` CLI flag | Current session | 1 (highest) |
+| `.claude/agents/` | Current project | 2 |
+| `~/.claude/agents/` | All your projects | 3 |
+| Plugin's `agents/` | Plugin users | 4 (lowest) |
+
+---
+
+## Key Constraints
+
+- Subagents cannot spawn other subagents
+- Background subagents auto-deny permissions not pre-approved
+- MCP tools not available in background subagents
+
+---
+
+## Related
+
+- `../lookup/builtin-subagents.md` - Built-in subagents
+- `../guides/creating-subagents.md` - Creation guide
+- `../lookup/subagent-frontmatter.md` - Configuration
+
+**Reference**: https://docs.anthropic.com/en/docs/claude-code/sub-agents

.opencode/context/openagents-repo/errors/skills-errors.md

@@ -0,0 +1,102 @@
+# Skills Troubleshooting
+
+**Purpose**: Common skill issues and solutions
+
+---
+
+## Skill Not Triggering
+
+**Symptom**: Claude doesn't use your skill when expected
+
+**Cause**: Description doesn't match user requests
+
+**Solution**: Write specific descriptions with trigger terms:
+```yaml
+# Bad
+description: Helps with documents
+
+# Good  
+description: Extract text from PDF files, fill forms, merge documents. Use when working with PDFs, forms, or document extraction.
+```
+
+**Tip**: Include keywords users would naturally say
+
+---
+
+## Skill Doesn't Load
+
+**Check file path**:
+| Type | Correct Path |
+|------|--------------|
+| Personal | `~/.claude/skills/my-skill/SKILL.md` |
+| Project | `.claude/skills/my-skill/SKILL.md` |
+| Plugin | `skills/my-skill/SKILL.md` |
+
+**Check YAML syntax**:
+- First line must be `---` (no blank lines before)
+- End frontmatter with `---`
+- Use spaces, not tabs
+
+**Debug**: Run `claude --debug` to see loading errors
+
+---
+
+## Skill Has Errors
+
+**Dependencies not installed**: 
+- List required packages in description
+- User must install before skill works
+
+**Script permissions**:
+```bash
+chmod +x scripts/*.py
+```
+
+**Path format**: Use forward slashes (Unix style)
+
+---
+
+## Multiple Skills Conflict
+
+**Symptom**: Claude uses wrong skill
+
+**Cause**: Similar descriptions
+
+**Solution**: Make descriptions distinct:
+```yaml
+# Skill 1
+description: Analyze sales data in Excel files and CRM exports
+
+# Skill 2  
+description: Analyze log files and system metrics
+```
+
+---
+
+## Plugin Skills Not Appearing
+
+**Solution**: Clear cache and reinstall
+```bash
+rm -rf ~/.claude/plugins/cache
+# Restart Claude Code
+/plugin install plugin-name@marketplace
+```
+
+**Verify structure**:
+```
+my-plugin/
+├── .claude-plugin/
+│   └── plugin.json
+└── skills/
+    └── my-skill/
+        └── SKILL.md
+```
+
+---
+
+## Related
+
+- `../concepts/agent-skills.md` - Skills overview
+- `../guides/creating-skills.md` - Creation guide
+
+**Reference**: https://docs.anthropic.com/en/docs/claude-code/skills

.opencode/context/openagents-repo/examples/baseadapter-implementation.md

@@ -0,0 +1,158 @@
+# Example: BaseAdapter Implementation Pattern
+
+**Purpose**: Template method pattern for AI tool adapters
+
+**Last Updated**: 2026-02-04
+
+---
+
+## Core Pattern
+
+**Template Method**: BaseAdapter defines algorithm structure, subclasses implement tool-specific details
+
+---
+
+## BaseAdapter Structure
+
+```typescript
+export abstract class BaseAdapter {
+  abstract name: string
+  abstract displayName: string
+  
+  // Must implement
+  abstract toOAC(source: string): Promise<OpenAgent>
+  abstract fromOAC(agent: OpenAgent): Promise<ConversionResult>
+  abstract getConfigPath(): string
+  abstract getCapabilities(): ToolCapabilities
+  abstract validateConversion(agent: OpenAgent): string[]
+  
+  // Shared utilities
+  supportsFeature(feature: keyof ToolCapabilities): boolean
+  warn(message: string): void
+  createSuccessResult(configs, warnings): ConversionResult
+  safeParseJSON(content, filename): unknown | null
+  unsupportedFeatureWarning(feature, value): string
+  degradedFeatureWarning(feature, from, to): string
+}
+```
+
+---
+
+## Implementation Example
+
+```typescript
+export class WindsurfAdapter extends BaseAdapter {
+  name = 'windsurf'
+  displayName = 'Windsurf'
+  
+  async toOAC(source: string): Promise<OpenAgent> {
+    const config = this.safeParseJSON(source, 'config.json')
+    return {
+      frontmatter: {
+        name: config.name,
+        model: this.mapWindsurfModelToOAC(config.model),
+        tools: this.parseWindsurfTools(config.tools),
+        temperature: this.mapCreativityToTemperature(config.creativity)
+      },
+      systemPrompt: config.systemPrompt,
+      contexts: []
+    }
+  }
+  
+  async fromOAC(agent: OpenAgent): Promise<ConversionResult> {
+    const warnings: string[] = []
+    
+    // Warn on unsupported features
+    if (agent.frontmatter.hooks) {
+      warnings.push(this.unsupportedFeatureWarning('hooks', 'lost'))
+    }
+    
+    const config = {
+      name: agent.frontmatter.name,
+      model: this.mapOACModelToWindsurf(agent.frontmatter.model),
+      creativity: this.mapTemperatureToCreativity(agent.frontmatter.temperature)
+    }
+    
+    return this.createSuccessResult([
+      { fileName: '.windsurf/config.json', content: JSON.stringify(config) }
+    ], warnings)
+  }
+  
+  getCapabilities(): ToolCapabilities {
+    return {
+      supportsMultipleAgents: true,
+      supportsHooks: false,
+      supportsTemperature: true // via creativity
+    }
+  }
+}
+```
+
+---
+
+## Key Methods
+
+### toOAC()
+Parse tool format → OpenAgent object
+- Parse source (JSON/YAML)
+- Map fields
+- Validate with Zod
+- Return OpenAgent
+
+### fromOAC()
+Convert OpenAgent → tool format
+- Validate input
+- Map fields
+- Detect unsupported features → warnings
+- Generate config files
+
+### getCapabilities()
+Declare supported features (used for validation)
+
+---
+
+## Utility Usage
+
+```typescript
+// Safe parsing
+const config = this.safeParseJSON(content, 'config.json')
+
+// Feature checks
+if (this.supportsFeature('supportsTemperature')) {
+  config.temperature = agent.frontmatter.temperature
+}
+
+// Warnings
+if (!this.supportsFeature('supportsHooks')) {
+  warnings.push(this.unsupportedFeatureWarning('hooks'))
+}
+
+// Results
+return this.createSuccessResult([{ fileName, content }], warnings)
+```
+
+---
+
+## Design Principles
+
+1. **Template Method** - Base defines structure, subs fill details
+2. **Pure toOAC/fromOAC** - Deterministic conversion
+3. **Capabilities First** - Declare support upfront
+4. **Graceful Degradation** - Warn, don't fail
+5. **Validate Early** - Check before converting
+
+---
+
+## Reference
+
+**Implementation**: `packages/compatibility-layer/src/adapters/BaseAdapter.ts`
+
+**Concrete Adapters**:
+- ClaudeAdapter.ts (600 lines)
+- CursorAdapter.ts (554 lines)
+- WindsurfAdapter.ts (514 lines)
+
+**Related**:
+- concepts/compatibility-layer.md
+- guides/compatibility-layer-development.md
+- lookup/compatibility-layer-adapters.md

.opencode/context/openagents-repo/examples/baseadapter-pattern.md

@@ -0,0 +1,194 @@
+# Example: BaseAdapter Implementation Pattern
+
+**Purpose**: Template Method pattern for AI coding tool adapters
+
+**Last Updated**: 2026-02-04
+
+---
+
+## Core Pattern
+
+Template Method: BaseAdapter defines algorithm structure, subclasses implement tool-specific details.
+
+---
+
+## BaseAdapter Structure
+
+```typescript
+export abstract class BaseAdapter {
+  abstract name: string
+  abstract displayName: string
+  
+  // Must implement
+  abstract toOAC(source: string): Promise<OpenAgent>
+  abstract fromOAC(agent: OpenAgent): Promise<ConversionResult>
+  abstract getConfigPath(): string
+  abstract getCapabilities(): ToolCapabilities
+  abstract validateConversion(agent: OpenAgent): string[]
+  
+  // Shared utilities
+  supportsFeature(feature: keyof ToolCapabilities): boolean
+  warn(message: string): void
+  createSuccessResult(configs, warnings): ConversionResult
+  safeParseJSON(content, filename): unknown | null
+}
+```
+
+---
+
+## ClaudeAdapter Example
+
+```typescript
+export class ClaudeAdapter extends BaseAdapter {
+  name = 'claude'
+  displayName = 'Claude Code'
+  
+  async toOAC(source: string): Promise<OpenAgent> {
+    const config = this.safeParseJSON(source, 'config.json')
+    return {
+      frontmatter: {
+        name: config.name,
+        mode: config.mode || 'primary',
+        model: this.mapModel(config.model),
+        tools: config.tools,
+        skills: config.skills?.map(s => ({ name: s }))
+      },
+      systemPrompt: config.systemPrompt || ''
+    }
+  }
+  
+  async fromOAC(agent: OpenAgent): Promise<ConversionResult> {
+    const warnings: string[] = []
+    
+    // Warn on unsupported features
+    if (agent.frontmatter.temperature) {
+      warnings.push(this.unsupportedFeatureWarning('temperature'))
+    }
+    
+    const config = {
+      name: agent.frontmatter.name,
+      model: agent.frontmatter.model,
+      systemPrompt: agent.systemPrompt,
+      tools: agent.frontmatter.tools
+    }
+    
+    return this.createSuccessResult([
+      { fileName: '.claude/config.json', content: JSON.stringify(config) }
+    ], warnings)
+  }
+  
+  getConfigPath() { return '.claude/' }
+  
+  getCapabilities(): ToolCapabilities {
+    return {
+      supportsMultipleAgents: true,
+      supportsSkills: true,
+      supportsHooks: true,
+      supportsTemperature: false
+    }
+  }
+  
+  validateConversion(agent: OpenAgent): string[] {
+    return agent.frontmatter.name ? [] : ['Agent name required']
+  }
+}
+```
+
+---
+
+## Key Methods
+
+### toOAC()
+Parse tool format → OpenAgent object
+
+**Steps**: Parse source → Map fields → Validate with Zod → Return
+
+---
+
+### fromOAC()
+Convert OpenAgent → tool format
+
+**Steps**: Validate → Map fields → Detect unsupported features → Generate warnings → Create files
+
+---
+
+### getCapabilities()
+Declare supported features
+
+```typescript
+{
+  supportsMultipleAgents: boolean
+  supportsSkills: boolean
+  supportsHooks: boolean
+  supportsGranularPermissions: boolean
+  supportsTemperature: boolean
+}
+```
+
+---
+
+## Utility Usage
+
+```typescript
+// Safe parsing
+const config = this.safeParseJSON(content, 'config.json')
+
+// Feature checks
+if (this.supportsFeature('supportsTemperature')) {
+  config.temperature = agent.frontmatter.temperature
+}
+
+// Warnings
+if (!this.supportsFeature('supportsHooks')) {
+  warnings.push(this.unsupportedFeatureWarning('hooks'))
+}
+
+// Results
+return this.createSuccessResult([{ fileName: 'config.json', content }], warnings)
+```
+
+---
+
+## Design Principles
+
+1. **Template Method** - Base defines structure, subs fill details
+2. **Pure toOAC/fromOAC** - Deterministic conversion
+3. **Capabilities First** - Declare support upfront
+4. **Graceful Degradation** - Warn, don't fail
+5. **Validate Early** - Check before converting
+
+---
+
+## Testing Pattern
+
+```typescript
+describe('ClaudeAdapter', () => {
+  it('converts OAC to Claude', async () => {
+    const agent: OpenAgent = { /* ... */ }
+    const result = await adapter.fromOAC(agent)
+    
+    expect(result.success).toBe(true)
+    expect(result.configs[0].fileName).toBe('.claude/config.json')
+  })
+  
+  it('warns on unsupported temperature', async () => {
+    const agent: OpenAgent = { frontmatter: { temperature: 0.7 } }
+    const result = await adapter.fromOAC(agent)
+    
+    expect(result.warnings).toContainEqual(
+      expect.stringContaining('temperature')
+    )
+  })
+})
+```
+
+---
+
+## Reference
+
+- **Implementation**: `packages/compatibility-layer/src/adapters/BaseAdapter.ts`
+- **Adapters**: `ClaudeAdapter.ts`, `CursorAdapter.ts`, `WindsurfAdapter.ts`
+- **Related**:
+  - concepts/compatibility-layer.md
+  - examples/zod-schema-migration.md
+  - guides/compatibility-layer-workflow.md

.opencode/context/openagents-repo/examples/hooks/formatting-hook.md

@@ -0,0 +1,58 @@
+# Code Formatting Hook
+
+**Purpose**: Auto-format files after Claude edits them
+
+---
+
+## TypeScript/Prettier Hook
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [{
+      "matcher": "Edit|Write",
+      "hooks": [{
+        "type": "command",
+        "command": "jq -r '.tool_input.file_path' | { read file_path; if echo \"$file_path\" | grep -q '\\.ts$'; then npx prettier --write \"$file_path\"; fi; }"
+      }]
+    }]
+  }
+}
+```
+
+---
+
+## How It Works
+
+1. Triggers after Edit or Write tool completes
+2. Extracts file path from JSON input via jq
+3. Checks if file is `.ts` extension
+4. Runs prettier on matching files
+
+---
+
+## Variations
+
+**Go files**:
+```bash
+if echo "$file_path" | grep -q '\\.go$'; then gofmt -w "$file_path"; fi
+```
+
+**Python files**:
+```bash
+if echo "$file_path" | grep -q '\\.py$'; then black "$file_path"; fi
+```
+
+**Multiple extensions**:
+```bash
+if echo "$file_path" | grep -qE '\\.(ts|tsx|js|jsx)$'; then npx prettier --write "$file_path"; fi
+```
+
+---
+
+## Related
+
+- `../../lookup/hook-events.md` - Hook events reference
+- `./protection-hook.md` - File protection example
+
+**Reference**: https://docs.anthropic.com/en/docs/claude-code/hooks

.opencode/context/openagents-repo/examples/hooks/markdown-formatter.md

@@ -0,0 +1,85 @@
+# Markdown Formatter Hook
+
+**Purpose**: Auto-fix markdown formatting issues after file edits
+
+---
+
+## Configuration
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [{
+      "matcher": "Edit|Write",
+      "hooks": [{
+        "type": "command",
+        "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/markdown_formatter.py"
+      }]
+    }]
+  }
+}
+```
+
+---
+
+## Python Script
+
+```python
+#!/usr/bin/env python3
+import json, sys, re, os
+
+def detect_language(code):
+    s = code.strip()
+    if re.search(r'^\s*[{\[]', s):
+        try:
+            json.loads(s)
+            return 'json'
+        except: pass
+    if re.search(r'^\s*def\s+\w+\s*\(', s, re.M):
+        return 'python'
+    if re.search(r'\b(function\s+\w+|const\s+\w+\s*=)', s):
+        return 'javascript'
+    if re.search(r'\b(SELECT|INSERT|UPDATE)\s+', s, re.I):
+        return 'sql'
+    return 'text'
+
+def format_markdown(content):
+    def add_lang(match):
+        indent, info, body, closing = match.groups()
+        if not info.strip():
+            return f"{indent}```{detect_language(body)}\n{body}{closing}\n"
+        return match.group(0)
+    
+    pattern = r'(?ms)^([ \t]{0,3})```([^\n]*)\n(.*?)(\n\1```)\s*$'
+    content = re.sub(pattern, add_lang, content)
+    return re.sub(r'\n{3,}', '\n\n', content).rstrip() + '\n'
+
+# Main
+data = json.load(sys.stdin)
+path = data.get('tool_input', {}).get('file_path', '')
+if path.endswith(('.md', '.mdx')) and os.path.exists(path):
+    with open(path, 'r') as f:
+        content = f.read()
+    formatted = format_markdown(content)
+    if formatted != content:
+        with open(path, 'w') as f:
+            f.write(formatted)
+        print(f"✓ Fixed formatting in {path}")
+```
+
+---
+
+## What It Fixes
+
+- Unlabeled code blocks → detects language
+- Excessive blank lines → max 2 consecutive
+- Trailing whitespace
+
+---
+
+## Related
+
+- `../../lookup/hook-events.md` - Hook events
+- `./formatting-hook.md` - Code formatting
+
+**Reference**: https://docs.anthropic.com/en/docs/claude-code/hooks

.opencode/context/openagents-repo/examples/hooks/protection-hook.md

@@ -0,0 +1,72 @@
+# File Protection Hook
+
+**Purpose**: Block edits to sensitive files
+
+---
+
+## Configuration
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [{
+      "matcher": "Edit|Write",
+      "hooks": [{
+        "type": "command",
+        "command": "python3 -c \"import json, sys; data=json.load(sys.stdin); path=data.get('tool_input',{}).get('file_path',''); sys.exit(2 if any(p in path for p in ['.env', 'package-lock.json', '.git/']) else 0)\""
+      }]
+    }]
+  }
+}
+```
+
+---
+
+## How It Works
+
+1. Triggers BEFORE Edit or Write tool executes
+2. Reads file path from JSON input
+3. Checks against protected patterns
+4. Exit code 2 blocks the operation
+5. Claude receives feedback about blocked file
+
+---
+
+## Protected Patterns
+
+Default patterns to block:
+- `.env` - Environment secrets
+- `package-lock.json` - Dependency locks
+- `.git/` - Git internals
+- `credentials.json` - API keys
+- `*.pem`, `*.key` - Private keys
+
+---
+
+## Custom Protection Script
+
+```python
+#!/usr/bin/env python3
+import json, sys
+
+PROTECTED = ['.env', 'package-lock.json', '.git/', 
+             'credentials', '.pem', '.key', 'secrets']
+
+data = json.load(sys.stdin)
+path = data.get('tool_input', {}).get('file_path', '')
+
+if any(p in path for p in PROTECTED):
+    print(f"Blocked: {path} is protected", file=sys.stderr)
+    sys.exit(2)
+
+sys.exit(0)
+```
+
+---
+
+## Related
+
+- `../../lookup/hook-events.md` - Hook events reference
+- `./formatting-hook.md` - Auto-format example
+
+**Reference**: https://docs.anthropic.com/en/docs/claude-code/hooks

.opencode/context/openagents-repo/examples/skills/multi-file-skill.md

@@ -0,0 +1,79 @@
+# Multi-File Skill Structure
+
+**Purpose**: Example of a skill with supporting files and scripts
+
+---
+
+## Directory Structure
+
+```
+pdf-processing/
+├── SKILL.md              # Overview and quick start
+├── FORMS.md              # Form field mappings
+├── REFERENCE.md          # API details
+└── scripts/
+    ├── fill_form.py      # Utility to populate forms
+    └── validate.py       # Check PDFs for required fields
+```
+
+---
+
+## SKILL.md
+
+```yaml
+---
+name: pdf-processing
+description: Extract text, fill forms, merge PDFs. Use when working with PDF files.
+allowed-tools: Read, Bash(python:*)
+---
+
+# PDF Processing
+
+## Quick start
+
+Extract text:
+```python
+import pdfplumber
+with pdfplumber.open("doc.pdf") as pdf:
+    text = pdf.pages[0].extract_text()
+```
+
+For form filling, see [FORMS.md](FORMS.md).
+For detailed API reference, see [REFERENCE.md](REFERENCE.md).
+
+## Requirements
+
+```bash
+pip install pypdf pdfplumber
+```
+```
+
+---
+
+## Key Patterns
+
+1. **Keep SKILL.md concise** (<500 lines)
+2. **Reference supporting files** with markdown links
+3. **One level deep** - link directly, avoid nested references
+4. **Scripts are executed, not loaded** - saves context tokens
+
+---
+
+## Script Usage
+
+In SKILL.md, tell Claude to run (not read):
+```markdown
+Run the validation script:
+python scripts/validate.py input.pdf
+```
+
+Output goes to Claude, script content stays out of context.
+
+---
+
+## Related
+
+- `../concepts/agent-skills.md` - Skills overview
+- `../../lookup/skill-metadata.md` - Metadata fields
+
+**Reference**: https://docs.anthropic.com/en/docs/claude-code/skills

.opencode/context/openagents-repo/examples/subagents/code-reviewer.md

@@ -0,0 +1,70 @@
+# Code Reviewer Subagent
+
+**Purpose**: Read-only subagent example for code review
+
+---
+
+## Configuration
+
+```yaml
+---
+name: code-reviewer
+description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
+tools: Read, Grep, Glob, Bash
+model: inherit
+---
+
+You are a senior code reviewer ensuring high standards of code quality and security.
+
+When invoked:
+1. Run git diff to see recent changes
+2. Focus on modified files
+3. Begin review immediately
+
+Review checklist:
+- Code is clear and readable
+- Functions and variables are well-named
+- No duplicated code
+- Proper error handling
+- No exposed secrets or API keys
+- Input validation implemented
+- Good test coverage
+- Performance considerations addressed
+
+Provide feedback organized by priority:
+- Critical issues (must fix)
+- Warnings (should fix)
+- Suggestions (consider improving)
+
+Include specific examples of how to fix issues.
+```
+
+---
+
+## Key Design Decisions
+
+| Decision | Rationale |
+|----------|-----------|
+| No Edit/Write | Read-only ensures review doesn't modify code |
+| `model: inherit` | Uses same model as main conversation |
+| Bash included | Allows running git diff |
+| Proactive description | Claude uses it automatically after code changes |
+
+---
+
+## Usage
+
+```
+Use the code-reviewer subagent to review my recent changes
+```
+
+Or Claude delegates automatically when code is modified.
+
+---
+
+## Related
+
+- `./debugger.md` - Debugger subagent (with edit access)
+- `../../guides/creating-subagents.md` - Creation guide
+
+**Reference**: https://docs.anthropic.com/en/docs/claude-code/sub-agents

.opencode/context/openagents-repo/examples/subagents/db-validator.md

@@ -0,0 +1,84 @@
+# DB Query Validator Subagent
+
+**Purpose**: Subagent with conditional tool validation via hooks
+
+---
+
+## Configuration
+
+```yaml
+---
+name: db-reader
+description: Execute read-only database queries. Use when analyzing data or generating reports.
+tools: Bash
+hooks:
+  PreToolUse:
+    - matcher: "Bash"
+      hooks:
+        - type: command
+          command: "./scripts/validate-readonly-query.sh"
+---
+
+You are a database analyst with read-only access. Execute SELECT queries to answer questions about the data.
+
+When asked to analyze data:
+1. Identify which tables contain the relevant data
+2. Write efficient SELECT queries with appropriate filters
+3. Present results clearly with context
+
+You cannot modify data. If asked to INSERT, UPDATE, DELETE, or modify schema, explain that you only have read access.
+```
+
+---
+
+## Validation Script
+
+```bash
+#!/bin/bash
+# ./scripts/validate-readonly-query.sh
+
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
+
+if [ -z "$COMMAND" ]; then
+  exit 0
+fi
+
+# Block write operations (case-insensitive)
+if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE|REPLACE|MERGE)\b' > /dev/null; then
+  echo "Blocked: Write operations not allowed. Use SELECT queries only." >&2
+  exit 2
+fi
+
+exit 0
+```
+
+Make executable: `chmod +x ./scripts/validate-readonly-query.sh`
+
+---
+
+## How It Works
+
+1. Subagent has Bash access
+2. PreToolUse hook intercepts every Bash command
+3. Script checks for SQL write keywords
+4. Exit 2 blocks operation, stderr fed to Claude
+5. Exit 0 allows operation
+
+---
+
+## Key Pattern
+
+Use hooks for **conditional validation** when:
+- Tool access is needed but constrained
+- Rules are dynamic/complex
+- You need finer control than `tools` field provides
+
+---
+
+## Related
+
+- `../../lookup/hook-events.md` - Hook reference
+- `../../concepts/hooks-system.md` - Hooks overview
+
+**Reference**: https://docs.anthropic.com/en/docs/claude-code/sub-agents

.opencode/context/openagents-repo/examples/subagents/debugger.md

@@ -0,0 +1,77 @@
+# Debugger Subagent
+
+**Purpose**: Full-access subagent for debugging and fixing issues
+
+---
+
+## Configuration
+
+```yaml
+---
+name: debugger
+description: Debugging specialist for errors, test failures, and unexpected behavior. Use proactively when encountering any issues.
+tools: Read, Edit, Bash, Grep, Glob
+---
+
+You are an expert debugger specializing in root cause analysis.
+
+When invoked:
+1. Capture error message and stack trace
+2. Identify reproduction steps
+3. Isolate the failure location
+4. Implement minimal fix
+5. Verify solution works
+
+Debugging process:
+- Analyze error messages and logs
+- Check recent code changes
+- Form and test hypotheses
+- Add strategic debug logging
+- Inspect variable states
+
+For each issue, provide:
+- Root cause explanation
+- Evidence supporting the diagnosis
+- Specific code fix
+- Testing approach
+- Prevention recommendations
+
+Focus on fixing the underlying issue, not the symptoms.
+```
+
+---
+
+## Key Design Decisions
+
+| Decision | Rationale |
+|----------|-----------|
+| Edit included | Debugger needs to fix code |
+| Model not specified | Defaults to Sonnet |
+| Proactive description | Auto-triggers on errors |
+
+---
+
+## Comparison with Code Reviewer
+
+| Aspect | Code Reviewer | Debugger |
+|--------|---------------|----------|
+| Edit access | ❌ No | ✓ Yes |
+| Purpose | Review quality | Fix issues |
+| Output | Feedback | Fixes |
+
+---
+
+## Usage
+
+```
+Use the debugger subagent to fix this failing test
+```
+
+---
+
+## Related
+
+- `./code-reviewer.md` - Read-only reviewer
+- `./db-validator.md` - Constrained access example
+
+**Reference**: https://docs.anthropic.com/en/docs/claude-code/sub-agents

.opencode/context/openagents-repo/examples/zod-schema-migration.md

@@ -0,0 +1,188 @@
+# Example: Zod Schema Migration Pattern
+
+**Purpose**: Migrate TypeScript definitions to runtime-validated Zod schemas
+
+**Last Updated**: 2026-02-04
+
+---
+
+## Why Zod?
+
+**Benefits**: Runtime validation + single source of truth + better error messages
+
+---
+
+## Basic Pattern
+
+```typescript
+// BEFORE: .d.ts interface
+interface AgentFrontmatter {
+  name: string
+  mode: 'primary' | 'subagent' | 'all'
+  temperature?: number
+}
+
+// AFTER: Zod schema
+import { z } from 'zod'
+
+export const AgentFrontmatterSchema = z.object({
+  name: z.string(),
+  mode: z.enum(['primary', 'subagent', 'all']),
+  temperature: z.number().min(0).max(2).optional()
+})
+
+export type AgentFrontmatter = z.infer<typeof AgentFrontmatterSchema>
+```
+
+---
+
+## Complex Schema
+
+```typescript
+// Granular permissions
+export const GranularPermissionSchema = z.object({
+  allow: z.array(z.string()).optional(),
+  deny: z.array(z.string()).optional(),
+  ask: z.array(z.string()).optional()
+})
+
+export const PermissionRuleSchema = z.union([
+  z.literal('allow'),
+  z.literal('deny'),
+  z.boolean(),
+  GranularPermissionSchema
+])
+
+export const ToolAccessSchema = z.object({
+  read: PermissionRuleSchema.optional(),
+  write: PermissionRuleSchema.optional(),
+  bash: PermissionRuleSchema.optional()
+})
+
+export type ToolAccess = z.infer<typeof ToolAccessSchema>
+```
+
+---
+
+## Validation Usage
+
+```typescript
+// Strict parsing (throws on invalid)
+const frontmatter = AgentFrontmatterSchema.parse(data)
+
+// Safe parsing (returns result object)
+const result = AgentFrontmatterSchema.safeParse(data)
+
+if (result.success) {
+  console.log(result.data)  // Typed correctly
+} else {
+  console.error(result.error.errors)  // Detailed errors
+}
+```
+
+---
+
+## Common Patterns
+
+### Enums
+```typescript
+export const ModeSchema = z.enum(['primary', 'subagent']).default('primary')
+```
+
+### Arrays
+```typescript
+export const SkillSchema = z.union([
+  z.string(),                    // "skill-name"
+  z.object({ name: z.string() }) // { name, config }
+])
+export const SkillsSchema = z.array(SkillSchema).optional()
+```
+
+### Records
+```typescript
+export const MetadataSchema = z.record(z.unknown())  // { [key: string]: any }
+```
+
+### Optionals
+```typescript
+z.string().optional()        // string | undefined
+z.number().default(0.7)      // number with default
+```
+
+---
+
+## Full Example: OpenAgent
+
+```typescript
+export const OpenAgentSchema = z.object({
+  frontmatter: AgentFrontmatterSchema,
+  metadata: AgentMetadataSchema.optional(),
+  systemPrompt: z.string(),
+  contexts: z.array(ContextReferenceSchema).optional()
+})
+
+export type OpenAgent = z.infer<typeof OpenAgentSchema>
+```
+
+---
+
+## Migration Checklist
+
+- [ ] `interface` → `z.object()`
+- [ ] `type X = Y | Z` → `z.union([...])`
+- [ ] `?` optional → `.optional()`
+- [ ] Add constraints (`.min()`, `.max()`)
+- [ ] Export schema AND type
+- [ ] Test with valid/invalid data
+
+---
+
+## Testing
+
+```typescript
+describe('AgentFrontmatterSchema', () => {
+  it('validates correct data', () => {
+    expect(() => AgentFrontmatterSchema.parse({
+      name: 'TestAgent',
+      mode: 'primary'
+    })).not.toThrow()
+  })
+  
+  it('rejects invalid mode', () => {
+    expect(() => AgentFrontmatterSchema.parse({
+      name: 'Test',
+      mode: 'invalid'
+    })).toThrow()
+  })
+  
+  it('rejects out-of-range temperature', () => {
+    expect(() => AgentFrontmatterSchema.parse({
+      name: 'Test',
+      temperature: 5.0  // Max 2.0
+    })).toThrow()
+  })
+})
+```
+
+---
+
+## Key Schemas (Compatibility Layer)
+
+**20+ schemas migrated**:
+- `OpenAgentSchema` - Complete agent
+- `AgentFrontmatterSchema` - YAML frontmatter
+- `ToolAccessSchema` - Tool permissions
+- `PermissionRuleSchema` - Permission types
+- `SkillReferenceSchema` - Skill definitions
+- `HookDefinitionSchema` - Hook configs
+
+---
+
+## Reference
+
+- **Implementation**: `packages/compatibility-layer/src/types.ts` (315 lines)
+- **Original**: `packages/compatibility-layer/dist/src/types.d.ts` (679 lines)
+- **Zod Docs**: https://zod.dev
+- **Related**:
+  - examples/baseadapter-pattern.md
+  - concepts/compatibility-layer.md

.opencode/context/openagents-repo/guides/adding-agent-basics.md

@@ -0,0 +1,154 @@
+# Guide: Adding a New Agent (Basics)
+
+**Prerequisites**: Load `core-concepts/agents.md` first  
+**Purpose**: Create and register a new agent in 4 steps
+
+---
+
+## Overview
+
+Adding a new agent involves:
+1. Creating the agent file
+2. Creating test structure
+3. Updating the registry
+4. Validating everything works
+
+**Time**: ~15-20 minutes
+
+---
+
+## Step 1: Create Agent File
+
+### Choose Category
+
+```bash
+# Available categories:
+# - core/          (system agents)
+# - development/   (dev specialists)
+# - content/       (content creators)
+# - data/          (data analysts)
+# - product/       (product managers)
+# - learning/      (educators)
+```
+
+### Create File with Frontmatter
+
+```bash
+touch .opencode/agent/{category}/{agent-name}.md
+```
+
+```markdown
+---
+description: "Brief description of what this agent does"
+category: "{category}"
+type: "agent"
+tags: ["tag1", "tag2"]
+dependencies: []
+---
+
+# Agent Name
+
+**Purpose**: What this agent does
+
+## Focus
+- Key responsibility 1
+- Key responsibility 2
+
+## Workflow
+1. Step 1
+2. Step 2
+
+## Constraints
+- Constraint 1
+- Constraint 2
+```
+
+---
+
+## Step 2: Create Test Structure
+
+```bash
+# Create directories
+mkdir -p evals/agents/{category}/{agent-name}/{config,tests}
+
+# Create config
+cat > evals/agents/{category}/{agent-name}/config/config.yaml << 'EOF'
+agent: {category}/{agent-name}
+model: anthropic/claude-sonnet-4-5
+timeout: 60000
+suites:
+  - smoke
+EOF
+
+# Create smoke test
+cat > evals/agents/{category}/{agent-name}/tests/smoke-test.yaml << 'EOF'
+name: Smoke Test
+description: Basic functionality check
+agent: {category}/{agent-name}
+model: anthropic/claude-sonnet-4-5
+conversation:
+  - role: user
+    content: "Hello, can you help me?"
+expectations:
+  - type: no_violations
+EOF
+```
+
+---
+
+## Step 3: Update Registry
+
+```bash
+# Dry run first
+./scripts/registry/auto-detect-components.sh --dry-run
+
+# Add to registry
+./scripts/registry/auto-detect-components.sh --auto-add
+
+# Verify
+cat registry.json | jq '.components.agents[] | select(.id == "{agent-name}")'
+```
+
+---
+
+## Step 4: Validate
+
+```bash
+# Validate registry
+./scripts/registry/validate-registry.sh
+
+# Run smoke test
+cd evals/framework
+npm run eval:sdk -- --agent={category}/{agent-name} --pattern="smoke-test.yaml"
+
+# Test installation
+REGISTRY_URL="file://$(pwd)/registry.json" ./install.sh --list
+```
+
+---
+
+## Checklist
+
+- [ ] Agent file created with proper frontmatter
+- [ ] Test structure created (config + smoke test)
+- [ ] Registry updated via auto-detect
+- [ ] Registry validation passes
+- [ ] Smoke test passes
+- [ ] Agent appears in `./install.sh --list`
+
+---
+
+## Next Steps
+
+- **Add more tests** → `adding-agent-testing.md`
+- **Test thoroughly** → `testing-agent.md`
+- **Debug issues** → `debugging.md`
+
+---
+
+## Related
+
+- `core-concepts/agents.md` - Agent concepts
+- `adding-agent-testing.md` - Additional test patterns
+- `testing-agent.md` - Testing guide
+- `creating-subagents.md` - Claude Code subagents (different system)

.opencode/context/openagents-repo/guides/adding-agent-testing.md

@@ -0,0 +1,143 @@
+# Guide: Adding Agent Tests
+
+**Prerequisites**: Load `adding-agent-basics.md` first  
+**Purpose**: Additional test patterns for agents
+
+---
+
+## Additional Test Types
+
+### Approval Gate Test
+
+```yaml
+# evals/agents/{category}/{agent-name}/tests/approval-gate.yaml
+name: Approval Gate Test
+description: Verify agent requests approval before execution
+agent: {category}/{agent-name}
+model: anthropic/claude-sonnet-4-5
+conversation:
+  - role: user
+    content: "Create a new file called test.js"
+expectations:
+  - type: specific_evaluator
+    evaluator: approval_gate
+    should_pass: true
+```
+
+### Context Loading Test
+
+```yaml
+# evals/agents/{category}/{agent-name}/tests/context-loading.yaml
+name: Context Loading Test
+description: Verify agent loads required context
+agent: {category}/{agent-name}
+model: anthropic/claude-sonnet-4-5
+conversation:
+  - role: user
+    content: "Write a new function"
+expectations:
+  - type: context_loaded
+    contexts: ["core/standards/code-quality.md"]
+```
+
+---
+
+## Complete Example: API Specialist
+
+```bash
+# 1. Create agent file
+cat > .opencode/agent/development/api-specialist.md << 'EOF'
+---
+description: "Expert in REST and GraphQL API design"
+category: "development"
+type: "agent"
+tags: ["api", "rest", "graphql"]
+dependencies: ["subagent:tester"]
+---
+
+# API Specialist
+
+**Purpose**: Design and implement robust APIs
+
+## Focus
+- REST API design
+- GraphQL schemas
+- API documentation
+- Authentication/authorization
+
+## Workflow
+1. Analyze requirements
+2. Design API structure
+3. Implement endpoints
+4. Add tests
+5. Document API
+
+## Constraints
+- Follow REST best practices
+- Use proper HTTP methods
+- Include error handling
+- Add comprehensive tests
+EOF
+
+# 2. Create test structure
+mkdir -p evals/agents/development/api-specialist/{config,tests}
+
+cat > evals/agents/development/api-specialist/config/config.yaml << 'EOF'
+agent: development/api-specialist
+model: anthropic/claude-sonnet-4-5
+timeout: 60000
+suites:
+  - smoke
+EOF
+
+cat > evals/agents/development/api-specialist/tests/smoke-test.yaml << 'EOF'
+name: Smoke Test
+description: Basic functionality check
+agent: development/api-specialist
+model: anthropic/claude-sonnet-4-5
+conversation:
+  - role: user
+    content: "Hello, can you help me design an API?"
+expectations:
+  - type: no_violations
+EOF
+
+# 3. Update registry
+./scripts/registry/auto-detect-components.sh --auto-add
+
+# 4. Validate
+./scripts/registry/validate-registry.sh
+cd evals/framework && npm run eval:sdk -- --agent=development/api-specialist --pattern="smoke-test.yaml"
+```
+
+---
+
+## Common Issues
+
+| Problem | Solution |
+|---------|----------|
+| Auto-detect doesn't find agent | Check frontmatter is valid YAML |
+| Registry validation fails | Verify file path is correct |
+| Test fails unexpectedly | Load `debugging.md` for troubleshooting |
+
+---
+
+## Claude Code Subagent (Optional)
+
+For Claude Code-only helpers, create a project subagent:
+
+- **Path**: `.claude/agents/{subagent-name}.md`
+- **Required**: `name`, `description` frontmatter
+- **Optional**: `tools`, `disallowedTools`, `permissionMode`, `skills`, `hooks`
+- **Reload**: restart Claude Code or run `/agents`
+
+See `creating-subagents.md` for Claude Code subagent details.
+
+---
+
+## Related
+
+- `adding-agent-basics.md` - Basic agent creation
+- `testing-agent.md` - Testing guide
+- `debugging.md` - Troubleshooting
+- `creating-subagents.md` - Claude Code subagents

.opencode/context/openagents-repo/guides/adding-agent.md

@@ -1,338 +0,0 @@
-# Guide: Adding a New Agent
-
-**Prerequisites**: Load `core-concepts/agents.md` first  
-**Purpose**: Step-by-step workflow for adding a new agent
-
----
-
-## Overview
-
-Adding a new agent involves:
-1. Creating the agent file
-2. Creating test structure
-3. Updating the registry
-4. Validating everything works
-
-**Time**: ~15-20 minutes
-
----
-
-## Step 1: Create Agent File
-
-### Choose Category
-
-```bash
-# Available categories:
-# - core/          (system agents)
-# - development/   (dev specialists)
-# - content/       (content creators)
-# - data/          (data analysts)
-# - product/       (product managers)
-# - learning/      (educators)
-```
-
-### Create File
-
-```bash
-# Create agent file
-touch .opencode/agent/{category}/{agent-name}.md
-```
-
-### Add Frontmatter and Content
-
-```markdown
----
-description: "Brief description of what this agent does"
-category: "{category}"
-type: "agent"
-tags: ["tag1", "tag2"]
-dependencies: []
----
-
-# Agent Name
-
-**Purpose**: What this agent does
-
-## Focus
-
-- Key responsibility 1
-- Key responsibility 2
-- Key responsibility 3
-
-## Workflow
-
-1. Step 1
-2. Step 2
-3. Step 3
-
-## Constraints
-
-- Constraint 1
-- Constraint 2
-```
-
----
-
-## Optional: Claude Code Subagent
-
-If you want a Claude Code-only helper for this repo, create a project subagent:
-
-- Path: `.claude/agents/{subagent-name}.md`
-- Required frontmatter: `name`, `description`
-- Optional: `tools`, `disallowedTools`, `permissionMode`, `skills`, `hooks`
-- Reload: restart Claude Code or run `/agents`
-
-For full Claude Code subagent details, see `../to-be-consumed/claude-code-docs/create-subagents.md`.
-
----
-
-## Step 2: Create Test Structure
-
-### Create Directories
-
-```bash
-mkdir -p evals/agents/{category}/{agent-name}/{config,tests}
-```
-
-### Create Config File
-
-```bash
-cat > evals/agents/{category}/{agent-name}/config/config.yaml << 'EOF'
-agent: {category}/{agent-name}
-model: anthropic/claude-sonnet-4-5
-timeout: 60000
-suites:
-  - smoke
-EOF
-```
-
-### Create Smoke Test
-
-```bash
-cat > evals/agents/{category}/{agent-name}/tests/smoke-test.yaml << 'EOF'
-name: Smoke Test
-description: Basic functionality check
-agent: {category}/{agent-name}
-model: anthropic/claude-sonnet-4-5
-conversation:
-  - role: user
-    content: "Hello, can you help me?"
-expectations:
-  - type: no_violations
-EOF
-```
-
----
-
-## Step 3: Update Registry
-
-### Auto-Detect
-
-```bash
-# Dry run first (see what would be added)
-./scripts/registry/auto-detect-components.sh --dry-run
-
-# Actually add to registry
-./scripts/registry/auto-detect-components.sh --auto-add
-```
-
-### Verify Registry Entry
-
-```bash
-# Check registry
-cat registry.json | jq '.components.agents[] | select(.id == "{agent-name}")'
-```
-
----
-
-## Step 4: Validate
-
-### Validate Registry
-
-```bash
-./scripts/registry/validate-registry.sh
-```
-
-### Run Smoke Test
-
-```bash
-cd evals/framework
-npm run eval:sdk -- --agent={category}/{agent-name} --pattern="smoke-test.yaml"
-```
-
-### Test Installation
-
-```bash
-# Test with local registry
-REGISTRY_URL="file://$(pwd)/registry.json" ./install.sh --list
-```
-
----
-
-## Step 5: Add Additional Tests (Optional)
-
-### Approval Gate Test
-
-```bash
-cat > evals/agents/{category}/{agent-name}/tests/approval-gate.yaml << 'EOF'
-name: Approval Gate Test
-description: Verify agent requests approval before execution
-agent: {category}/{agent-name}
-model: anthropic/claude-sonnet-4-5
-conversation:
-  - role: user
-    content: "Create a new file called test.js"
-expectations:
-  - type: specific_evaluator
-    evaluator: approval_gate
-    should_pass: true
-EOF
-```
-
-### Context Loading Test
-
-```bash
-cat > evals/agents/{category}/{agent-name}/tests/context-loading.yaml << 'EOF'
-name: Context Loading Test
-description: Verify agent loads required context
-agent: {category}/{agent-name}
-model: anthropic/claude-sonnet-4-5
-conversation:
-  - role: user
-    content: "Write a new function"
-expectations:
-  - type: context_loaded
-    contexts: ["core/standards/code-quality.md"]
-EOF
-```
-
----
-
-## Complete Example
-
-### Example: Adding `api-specialist`
-
-```bash
-# 1. Create agent file
-cat > .opencode/agent/development/api-specialist.md << 'EOF'
----
-description: "Expert in REST and GraphQL API design"
-category: "development"
-type: "agent"
-tags: ["api", "rest", "graphql"]
-dependencies: ["subagent:tester"]
----
-
-# API Specialist
-
-**Purpose**: Design and implement robust APIs
-
-## Focus
-- REST API design
-- GraphQL schemas
-- API documentation
-- Authentication/authorization
-
-## Workflow
-1. Analyze requirements
-2. Design API structure
-3. Implement endpoints
-4. Add tests
-5. Document API
-
-## Constraints
-- Follow REST best practices
-- Use proper HTTP methods
-- Include error handling
-- Add comprehensive tests
-EOF
-
-# 2. Create test structure
-mkdir -p evals/agents/development/api-specialist/{config,tests}
-
-cat > evals/agents/development/api-specialist/config/config.yaml << 'EOF'
-agent: development/api-specialist
-model: anthropic/claude-sonnet-4-5
-timeout: 60000
-suites:
-  - smoke
-EOF
-
-cat > evals/agents/development/api-specialist/tests/smoke-test.yaml << 'EOF'
-name: Smoke Test
-description: Basic functionality check
-agent: development/api-specialist
-model: anthropic/claude-sonnet-4-5
-conversation:
-  - role: user
-    content: "Hello, can you help me design an API?"
-expectations:
-  - type: no_violations
-EOF
-
-# 3. Update registry
-./scripts/registry/auto-detect-components.sh --auto-add
-
-# 4. Validate
-./scripts/registry/validate-registry.sh
-cd evals/framework && npm run eval:sdk -- --agent=development/api-specialist --pattern="smoke-test.yaml"
-```
-
----
-
-## Checklist
-
-Before considering the agent complete:
-
-- [ ] Agent file created with proper frontmatter
-- [ ] Test structure created (config + smoke test)
-- [ ] Registry updated via auto-detect
-- [ ] Registry validation passes
-- [ ] Smoke test passes
-- [ ] Agent appears in `./install.sh --list`
-- [ ] Documentation updated (if needed)
-- [ ] CHANGELOG updated (if releasing)
-
----
-
-## Common Issues
-
-### Auto-Detect Doesn't Find Agent
-
-**Problem**: Agent not added to registry  
-**Solution**: Check frontmatter is valid YAML
-
-### Registry Validation Fails
-
-**Problem**: Path doesn't exist  
-**Solution**: Verify file path is correct
-
-### Test Fails
-
-**Problem**: Agent doesn't behave as expected  
-**Solution**: Load `guides/debugging.md` for troubleshooting
-
----
-
-## Next Steps
-
-After adding agent:
-1. **Test thoroughly** → Load `guides/testing-agent.md`
-2. **Add more tests** → Approval gate, context loading, etc.
-3. **Update docs** → Add to README or docs/
-4. **Create PR** → Submit for review
-
----
-
-## Related Files
-
-- **Agent concepts**: `core-concepts/agents.md`
-- **Testing guide**: `guides/testing-agent.md`
-- **Registry guide**: `guides/updating-registry.md`
-- **Debugging**: `guides/debugging.md`
-- **Claude Code subagents**: `../to-be-consumed/claude-code-docs/create-subagents.md`
-
----
-
-**Last Updated**: 2026-01-13  
-**Version**: 0.5.1

.opencode/context/openagents-repo/guides/adding-skill-basics.md

@@ -0,0 +1,147 @@
+# Guide: Adding an OpenCode Skill (Basics)
+
+**Prerequisites**: Load `plugins/context/capabilities/events_skills.md` first  
+**Purpose**: Create an OpenCode skill directory and SKILL.md file
+
+**Note**: This is for **OpenCode skills** (internal system). For **Claude Code Skills**, see `creating-skills.md`.
+
+---
+
+## Overview
+
+Adding an OpenCode skill involves:
+1. Creating skill directory structure
+2. Creating SKILL.md file
+3. Creating router script (optional)
+4. Creating CLI implementation (optional)
+5. Registering in registry (optional)
+6. Testing
+
+**Time**: ~10-15 minutes
+
+---
+
+## Step 1: Create Skill Directory
+
+### Choose Skill Name
+
+- **kebab-case**: `task-management`, `brand-guidelines`
+- **Descriptive**: Clear indication of what skill provides
+- **Short**: Max 3-4 words
+
+### Create Structure
+
+```bash
+mkdir -p .opencode/skill/{skill-name}/scripts
+```
+
+**Standard structure**:
+```
+.opencode/skill/{skill-name}/
+├── SKILL.md              # Required: Main skill documentation
+├── router.sh             # Optional: CLI router script
+└── scripts/
+    └── skill-cli.ts      # Optional: CLI tool implementation
+```
+
+---
+
+## Step 2: Create SKILL.md
+
+### Frontmatter
+
+```markdown
+---
+name: {skill-name}
+description: Brief description of what the skill provides
+---
+
+# Skill Name
+
+**Purpose**: What this skill helps users do
+
+## What I do
+
+- Feature 1
+- Feature 2
+- Feature 3
+
+## How to use me
+
+### Basic Commands
+
+```bash
+npx ts-node .opencode/skill/{skill-name}/scripts/skill-cli.ts command1
+```
+
+### Command Reference
+
+| Command | Description |
+|---------|-------------|
+| `command1` | What command1 does |
+| `command2` | What command2 does |
+```
+
+### Claude Code Skills (Optional)
+
+For Claude Code Skills (`.claude/skills/`), add extra frontmatter:
+- `allowed-tools` - Tool restrictions
+- `context` + `agent` - Run in forked subagent
+- `hooks` - Lifecycle events
+- `user-invocable` - Hide from slash menu
+
+See `creating-skills.md` for Claude Code Skills details.
+
+---
+
+## Step 3: Create Router Script (Optional)
+
+For CLI-based skills:
+
+```bash
+#!/bin/bash
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+if [ $# -eq 0 ]; then
+    echo "Usage: bash router.sh <command> [options]"
+    exit 1
+fi
+
+COMMAND="$1"
+shift
+
+case "$COMMAND" in
+    help|--help|-h)
+        echo "{Skill Name} - Description"
+        echo "Commands: command1, command2, help"
+        ;;
+    command1|command2)
+        npx ts-node "$SCRIPT_DIR/scripts/skill-cli.ts" "$COMMAND" "$@"
+        ;;
+    *)
+        echo "Unknown command: $COMMAND"
+        exit 1
+        ;;
+esac
+```
+
+```bash
+chmod +x .opencode/skill/{skill-name}/router.sh
+```
+
+---
+
+## Next Steps
+
+- **CLI Implementation** → `adding-skill-implementation.md`
+- **Complete Example** → `adding-skill-example.md`
+- **Claude Code Skills** → `creating-skills.md`
+
+---
+
+## Related
+
+- `creating-skills.md` - Claude Code Skills (different system)
+- `adding-skill-implementation.md` - CLI and registry
+- `adding-skill-example.md` - Task-management example
+- `plugins/context/capabilities/events_skills.md` - Skills Plugin

.opencode/context/openagents-repo/guides/adding-skill-example.md

@@ -0,0 +1,167 @@
+# Example: Task-Management Skill
+
+**Purpose**: Complete example of creating an OpenCode skill
+
+---
+
+## Directory Structure
+
+```bash
+mkdir -p .opencode/skill/task-management/scripts
+```
+
+```
+.opencode/skill/task-management/
+├── SKILL.md
+├── router.sh
+└── scripts/
+    └── task-cli.ts
+```
+
+---
+
+## SKILL.md
+
+```markdown
+---
+name: task-management
+description: Task management CLI for tracking feature subtasks
+---
+
+# Task Management Skill
+
+**Purpose**: Track and manage feature subtasks
+
+## What I do
+
+- Track task progress
+- Show next eligible tasks
+- Identify blocked tasks
+- Mark completion
+- Validate task integrity
+
+## Usage
+
+```bash
+# Show all task statuses
+npx ts-node .opencode/skill/task-management/scripts/task-cli.ts status
+
+# Show next eligible tasks
+npx ts-node .opencode/skill/task-management/scripts/task-cli.ts next
+
+# Mark complete
+npx ts-node .opencode/skill/task-management/scripts/task-cli.ts complete <feature> <seq> "summary"
+```
+```
+
+---
+
+## router.sh
+
+```bash
+#!/bin/bash
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+case "$1" in
+    help|--help|-h)
+        echo "Task Management Skill"
+        echo "Usage: bash router.sh <command>"
+        echo "Commands: status, next, blocked, complete, validate"
+        ;;
+    status|next|blocked|validate)
+        npx ts-node "$SCRIPT_DIR/scripts/task-cli.ts" "$@"
+        ;;
+    complete)
+        npx ts-node "$SCRIPT_DIR/scripts/task-cli.ts" "$@"
+        ;;
+    *)
+        echo "Unknown command: $1"
+        bash "$0" help
+        ;;
+esac
+```
+
+---
+
+## task-cli.ts (Excerpt)
+
+```typescript
+#!/usr/bin/env ts-node
+
+interface Task {
+  id: string
+  status: 'pending' | 'in_progress' | 'completed'
+  title: string
+}
+
+async function main() {
+  const command = process.argv[2] || 'help'
+  
+  switch (command) {
+    case 'status':
+      await showStatus()
+      break
+    case 'next':
+      await showNext()
+      break
+    case 'complete':
+      const [, , , feature, seq, summary] = process.argv
+      await markComplete(feature, seq, summary)
+      break
+    default:
+      showHelp()
+  }
+}
+
+async function showStatus() {
+  // Implementation
+  console.log('Task status...')
+}
+
+async function showNext() {
+  // Implementation
+  console.log('Next tasks...')
+}
+
+async function markComplete(feature: string, seq: string, summary: string) {
+  // Implementation
+  console.log(`Completing ${feature} ${seq}: ${summary}`)
+}
+
+function showHelp() {
+  console.log(`
+Task Management CLI
+
+Commands:
+  status              Show all task statuses
+  next                Show next eligible tasks
+  blocked             Show blocked tasks
+  complete <f> <s>    Mark task complete
+  validate            Validate task integrity
+`)
+}
+
+main().catch(console.error)
+```
+
+---
+
+## Integration with Agents
+
+Skills integrate with agents via:
+- Event hooks (`tool.execute.before`, `tool.execute.after`)
+- Skill content injection into conversation
+- Output enhancement
+
+Example agent prompt invoking skill:
+```
+Use the task-management skill to show current task status
+```
+
+---
+
+## Related
+
+- `adding-skill-basics.md` - Directory and SKILL.md setup
+- `adding-skill-implementation.md` - CLI and registry
+- `plugins/context/capabilities/events_skills.md` - Skills Plugin

.opencode/context/openagents-repo/guides/adding-skill-implementation.md

@@ -0,0 +1,167 @@
+# Guide: OpenCode Skill Implementation
+
+**Prerequisites**: Load `adding-skill-basics.md` first  
+**Purpose**: CLI implementation, registry, and testing for OpenCode skills
+
+---
+
+## CLI Implementation
+
+### Basic Structure
+
+```typescript
+#!/usr/bin/env ts-node
+// CLI implementation for {skill-name} skill
+
+interface Args {
+  command: string
+  [key: string]: any
+}
+
+async function main() {
+  const args = parseArgs()
+  
+  switch (args.command) {
+    case 'command1':
+      await handleCommand1(args)
+      break
+    case 'command2':
+      await handleCommand2(args)
+      break
+    case 'help':
+    default:
+      showHelp()
+  }
+}
+
+function parseArgs(): Args {
+  const args = process.argv.slice(2)
+  return {
+    command: args[0] || 'help',
+    ...parseOptions(args.slice(1))
+  }
+}
+
+async function handleCommand1(args: Args) {
+  console.log('Running command1...')
+}
+
+function showHelp() {
+  console.log(`
+{Skill Name}
+
+Usage: npx ts-node scripts/skill-cli.ts <command> [options]
+
+Commands:
+  command1    Description
+  command2    Description
+  help        Show this help
+`)
+}
+
+main().catch(console.error)
+```
+
+---
+
+## Register in Registry (Optional)
+
+### Add to Components
+
+```json
+{
+  "skills": [
+    {
+      "id": "{skill-name}",
+      "name": "Skill Name",
+      "type": "skill",
+      "path": ".opencode/skill/{skill-name}/SKILL.md",
+      "description": "Brief description",
+      "tags": ["tag1", "tag2"],
+      "dependencies": []
+    }
+  ]
+}
+```
+
+### Add to Profiles
+
+```json
+{
+  "profiles": {
+    "essential": {
+      "components": [
+        "skill:{skill-name}"
+      ]
+    }
+  }
+}
+```
+
+---
+
+## Testing
+
+### Test CLI Commands
+
+```bash
+# Test help
+bash .opencode/skill/{skill-name}/router.sh help
+
+# Test commands
+bash .opencode/skill/{skill-name}/router.sh command1 --option value
+
+# Test with npx
+npx ts-node .opencode/skill/{skill-name}/scripts/skill-cli.ts help
+```
+
+### Test OpenCode Integration
+
+1. Call skill via OpenCode
+2. Verify event hooks fire correctly
+3. Check conversation history for skill content
+4. Verify output enhancement works
+
+---
+
+## Best Practices
+
+### Keep Skills Focused
+- ✅ Task management skill → Tracks tasks
+- ❌ Task management + code generation + testing → Too broad
+
+### Clear Documentation
+- Provide usage examples
+- Document all commands
+- Include expected outputs
+
+### Error Handling
+- Handle missing arguments gracefully
+- Provide helpful error messages
+- Validate inputs before processing
+
+### Performance
+- Use efficient algorithms
+- Cache when appropriate
+- Avoid unnecessary file operations
+
+---
+
+## Checklist
+
+- [ ] `.opencode/skill/{skill-name}/SKILL.md` created
+- [ ] `.opencode/skill/{skill-name}/router.sh` created (if CLI-based)
+- [ ] Router script is executable (`chmod +x`)
+- [ ] Registry updated (if needed)
+- [ ] Profile updated (if needed)
+- [ ] All commands tested
+- [ ] Documentation complete
+
+---
+
+## Related
+
+- `adding-skill-basics.md` - Directory and SKILL.md setup
+- `adding-skill-example.md` - Complete example
+- `creating-skills.md` - Claude Code Skills
+- `plugins/context/capabilities/events_skills.md` - Skills Plugin

.opencode/context/openagents-repo/guides/adding-skill.md

@@ -1,456 +0,0 @@
-# Guide: Adding a New Skill
-
-**Prerequisites**: Load `plugins/context/capabilities/events_skills.md` first  
-**Purpose**: Step-by-step workflow for adding a new skill  
-**Related**: See `plugins/context/architecture/overview.md` for plugin concepts
-
----
-
-## Overview
-
-Adding a new skill involves:
-1. Creating the skill directory structure
-2. Creating the SKILL.md file
-3. Creating the router script (for CLI-based skills)
-4. Creating skill content/scripts
-5. Registering the skill (if needed)
-6. Testing the skill
-
-**Time**: ~10-15 minutes
-
----
-
-## Step 1: Create Skill Directory
-
-### Choose Skill Name
-
-Skill names should be:
-- **kebab-case**: `task-management`, `brand-guidelines`, `api-reference`
-- **Descriptive**: Clear indication of what the skill provides
-- **Short**: Avoid overly long names (max 3-4 words)
-
-### Create Directory Structure
-
-```bash
-# Create skill directory
-mkdir -p .opencode/skill/{skill-name}
-
-# Create subdirectories as needed
-mkdir -p .opencode/skill/{skill-name}/scripts
-```
-
-### Standard Skill Structure
-
-```
-.opencode/skill/{skill-name}/
-├── SKILL.md              # Required: Main skill documentation
-├── router.sh             # Optional: CLI router script
-└── scripts/
-    └── skill-cli.ts      # Optional: CLI tool implementation
-```
-
----
-
-## Step 2: Create SKILL.md
-
-The SKILL.md file is required and provides skill documentation and integration details.
-
-### Optional: Claude Code Skills
-
-Claude Code Skills live in `.claude/skills/{skill-name}/SKILL.md` and support extra frontmatter:
-- `allowed-tools` for tool restrictions
-- `context` + `agent` to run in a forked subagent
-- `hooks` for lifecycle events
-- `user-invocable` to hide from slash menu
-
-Keep descriptions keyword-rich so auto-discovery triggers reliably. See `../to-be-consumed/claude-code-docs/agent-skills.md` for full details.
-
-### SKILL.md Frontmatter
-
-```markdown
----
-name: {skill-name}
-description: Brief description of what the skill provides
----
-
-# Skill Name
-
-**Purpose**: What this skill helps users do
-
-## What I do
-
-- Feature 1
-- Feature 2
-- Feature 3
-
-## How to use me
-
-### Basic Commands
-
-```bash
-# Example command 1
-npx ts-node .opencode/skill/{skill-name}/scripts/skill-cli.ts command1
-
-# Example command 2
-npx ts-node .opencode/skill/{skill-name}/scripts/skill-cli.ts command2
-```
-
-### Command Reference
-
-| Command | Description |
-|---------|-------------|
-| `command1` | What command1 does |
-| `command2` | What command2 does |
-
-## Examples
-
-### Example 1
-
-```
-$ npx ts-node .opencode/skill/{skill-name}/scripts/skill-cli.ts example
-
-Expected output or behavior
-```
-
-## Architecture
-
-```
-.opencode/
-└── skill/
-    └── {skill-name}/
-        ├── SKILL.md              # This file
-        ├── router.sh             # CLI router
-        └── scripts/
-            └── skill-cli.ts      # CLI implementation
-```
-
-## Integration
-
-### With Agents
-
-This skill integrates with agents by:
-- Description of how agents use the skill
-- Example agent prompt that invokes the skill
-
-### With OpenCode Events
-
-The skill uses OpenCode event hooks:
-- `tool.execute.before` - For [what it does]
-- `tool.execute.after` - For [what it does]
-
----
-
-## Step 3: Create Router Script (Optional)
-
-For CLI-based skills, create a router.sh script:
-
-```bash
-#!/bin/bash
-# Router script for {skill-name} skill
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-
-# Default to help if no arguments
-if [ $# -eq 0 ]; then
-    echo "Usage: bash router.sh <command> [options]"
-    echo "Run 'bash router.sh help' for more information"
-    exit 1
-fi
-
-COMMAND="$1"
-shift
-
-# Route to appropriate script
-case "$COMMAND" in
-    help|--help|-h)
-        echo "{Skill Name} - Skill Description"
-        echo ""
-        echo "Usage: bash router.sh <command> [options]"
-        echo ""
-        echo "Commands:"
-        echo "  command1    Description of command1"
-        echo "  command2    Description of command2"
-        echo "  help        Show this help message"
-        ;;
-    command1)
-        npx ts-node "$SCRIPT_DIR/scripts/skill-cli.ts" command1 "$@"
-        ;;
-    command2)
-        npx ts-node "$SCRIPT_DIR/scripts/skill-cli.ts" command2 "$@"
-        ;;
-    *)
-        echo "Unknown command: $COMMAND"
-        echo "Run 'bash router.sh help' for available commands"
-        exit 1
-        ;;
-esac
-```
-
-### Make Router Executable
-
-```bash
-chmod +x .opencode/skill/{skill-name}/router.sh
-```
-
----
-
-## Step 4: Create CLI Implementation
-
-### Basic CLI Structure
-
-```typescript
-#!/usr/bin/env ts-node
-// CLI implementation for {skill-name} skill
-
-interface Args {
-  command: string
-  [key: string]: any
-}
-
-async function main() {
-  const args = parseArgs()
-  
-  switch (args.command) {
-    case 'command1':
-      await handleCommand1(args)
-      break
-    case 'command2':
-      await handleCommand2(args)
-      break
-    case 'help':
-    default:
-      showHelp()
-  }
-}
-
-function parseArgs(): Args {
-  const args = process.argv.slice(2)
-  return {
-    command: args[0] || 'help',
-    ...parseOptions(args.slice(1))
-  }
-}
-
-async function handleCommand1(args: Args) {
-  // Implementation
-  console.log('Running command1...')
-}
-
-function showHelp() {
-  console.log(`
-{ Skill Name }
-
-Usage: npx ts-node scripts/skill-cli.ts <command> [options]
-
-Commands:
-  command1    Description of command1
-  command2    Description of command2
-  help        Show this help message
-
-Options:
-  --option1   Description of option1
-  --option2   Description of option2
-`)
-}
-
-main().catch(console.error)
-```
-
----
-
-## Step 5: Register in Registry (Optional)
-
-If the skill should be included in profiles, add it to `registry.json`:
-
-### Add to Components
-
-```json
-{
-  "skills": [
-    {
-      "id": "{skill-name}",
-      "name": "Skill Name",
-      "type": "skill",
-      "path": ".opencode/skill/{skill-name}/SKILL.md",
-      "description": "Brief description",
-      "tags": ["tag1", "tag2"],
-      "dependencies": []
-    }
-  ]
-}
-```
-
-### Add to Profiles
-
-```json
-{
-  "profiles": {
-    "essential": {
-      "components": [
-        "skill:{skill-name}"
-      ]
-    }
-  }
-}
-```
-
----
-
-## Step 6: Test the Skill
-
-### Test CLI Commands
-
-```bash
-# Test help
-bash .opencode/skill/{skill-name}/router.sh help
-
-# Test command1
-bash .opencode/skill/{skill-name}/router.sh command1 --option value
-
-# Test with npx
-npx ts-node .opencode/skill/{skill-name}/scripts/skill-cli.ts help
-```
-
-### Test OpenCode Integration
-
-If the skill uses OpenCode events:
-1. Call the skill via OpenCode
-2. Verify event hooks fire correctly
-3. Check conversation history for skill content injection
-4. Verify output enhancement works
-
----
-
-## Example: Creating Task-Management Skill
-
-### Directory Creation
-
-```bash
-mkdir -p .opencode/skill/task-management/scripts
-```
-
-### SKILL.md
-
-```markdown
----
-name: task-management
-description: Task management CLI for tracking feature subtasks
----
-
-# Task Management Skill
-
-**Purpose**: Track and manage feature subtasks
-
-## What I do
-
-- Track task progress
-- Show next eligible tasks
-- Identify blocked tasks
-- Mark completion
-- Validate task integrity
-
-## Usage
-
-```bash
-# Show all task statuses
-npx ts-node .opencode/skill/task-management/scripts/task-cli.ts status
-
-# Show next eligible tasks
-npx ts-node .opencode/skill/task-management/scripts/task-cli.ts next
-
-# Mark complete
-npx ts-node .opencode/skill/task-management/scripts/task-cli.ts complete <feature> <seq> "summary"
-```
-
-### router.sh
-
-```bash
-#!/bin/bash
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-
-case "$1" in
-    help|--help|-h)
-        echo "Task Management Skill"
-        echo "Usage: bash router.sh <command>"
-        echo "Commands: status, next, blocked, complete, validate"
-        ;;
-    status|next|blocked|validate)
-        npx ts-node "$SCRIPT_DIR/scripts/task-cli.ts" "$@"
-        ;;
-    complete)
-        npx ts-node "$SCRIPT_DIR/scripts/task-cli.ts" "$@"
-        ;;
-    *)
-        echo "Unknown command: $1"
-        bash router.sh help
-        ;;
-esac
-```
-
----
-
-## Best Practices
-
-### 1. Keep Skills Focused
-
-Each skill should do one thing well:
-- ✅ Task management skill → Tracks tasks
-- ❌ Task management + code generation + testing → Too broad
-
-### 2. Clear Documentation
-
-- Provide usage examples
-- Document all commands
-- Include expected outputs
-- Explain integration points
-
-### 3. Error Handling
-
-- Handle missing arguments gracefully
-- Provide helpful error messages
-- Validate inputs before processing
-
-### 4. Performance
-
-- Use efficient algorithms
-- Cache when appropriate
-- Avoid unnecessary file operations
-
-### 5. Testing
-
-- Test all commands
-- Test error conditions
-- Verify integration with OpenCode
-
----
-
-## Quick Reference
-
-### File Checklist
-
-- [ ] `.opencode/skill/{skill-name}/SKILL.md` created
-- [ ] `.opencode/skill/{skill-name}/router.sh` created (if CLI-based)
-- [ ] `.opencode/skill/{skill-name}/scripts/skill-cli.ts` created (if CLI-based)
-- [ ] Router script is executable (`chmod +x`)
-- [ ] Registry updated (if needed)
-- [ ] Profile updated (if needed)
-- [ ] All commands tested
-- [ ] Documentation complete
-
-### Command Reference
-
-| Command | Purpose |
-|---------|---------|
-| `mkdir -p .opencode/skill/{name}` | Create skill directory |
-| `chmod +x router.sh` | Make router executable |
-| `npx ts-node scripts/cli.ts help` | Test CLI help |
-
----
-
-## Related Documentation
-
-- **Skills Plugin**: `plugins/context/capabilities/events_skills.md`
-- **Plugin Overview**: `plugins/context/architecture/overview.md`
-- **Event System**: `plugins/context/capabilities/events.md`
-- **Adding Agents**: `guides/adding-agent.md`
-- **Claude Code Skills**: `../to-be-consumed/claude-code-docs/agent-skills.md`

.opencode/context/openagents-repo/guides/compatibility-layer-development.md

@@ -0,0 +1,165 @@
+# Guide: Compatibility Layer Development Workflow
+
+**Purpose**: Step-by-step workflow for developing compatibility layer features
+
+**Last Updated**: 2026-02-04
+
+---
+
+## Core Workflow
+
+Development follows a structured 6-stage approach:
+
+```
+1. Discover (Context)
+   ↓
+2. Propose (Approval)
+   ↓
+3. Init Session (Setup)
+   ↓
+4. Plan (Breakdown)
+   ↓
+5. Execute (Implement)
+   ↓
+6. Validate & Handoff
+```
+
+---
+
+## Stage 1: Discover
+
+**Goal**: Understand requirements before implementation
+
+**Actions**:
+1. Use `ContextScout` to discover relevant context files
+2. For external packages: Check install scripts first, then use `ExternalScout`
+3. Read context standards (code-quality.md is MANDATORY)
+
+**No files created** - Read-only exploration
+
+---
+
+## Stage 2: Propose
+
+**Goal**: Get user approval BEFORE any file creation
+
+**Present lightweight summary**:
+- What we're building (1-2 sentences)
+- Components list
+- Approach (direct execution vs delegation)
+- Context discovered
+
+**Wait for user approval** before proceeding
+
+---
+
+## Stage 3: Init Session
+
+**Goal**: Create session and persist context (ONLY after approval)
+
+**Actions**:
+1. Create session directory: `.tmp/sessions/{YYYY-MM-DD}-{task-slug}/`
+2. Write `context.md` with:
+   - Task requirements
+   - Context files (standards to follow)
+   - Reference files (source material)
+   - Components
+   - Exit criteria
+
+**This becomes single source of truth for all agents**
+
+---
+
+## Stage 4: Plan
+
+**Decision**: Simple vs Complex?
+
+**Simple** (1-3 files, <30min):
+- Skip TaskManager
+- Execute directly in Stage 5
+
+**Complex** (4+ files, >60min):
+- Delegate to `TaskManager`
+- Creates `.tmp/tasks/{feature}/task.json` + subtasks
+- Present plan for confirmation
+
+---
+
+## Stage 5: Execute
+
+**Incremental approach** (one component at a time):
+
+1. **Plan Component** (if using component-planning):
+   - Create `component-{name}.md`
+   - Request approval for design
+
+2. **Execute**:
+   - Load context from session
+   - Implement → Validate → Mark complete
+   - If delegating: Pass subtask JSON to `CoderAgent`
+
+3. **Integrate**:
+   - Verify integration with previous components
+
+**Critical**: Never implement entire plan at once
+
+---
+
+## Stage 6: Validate & Handoff
+
+**Actions**:
+1. Run full system integration tests
+2. Delegate to `TestEngineer` or `CodeReviewer` (pass session context)
+3. Summarize what was built
+4. Ask user to clean up `.tmp` files
+
+---
+
+## Key Principles
+
+**Context First**: Load standards BEFORE coding
+**Approval Gates**: Never execute without approval
+**Incremental**: One step at a time, validate each
+**Stop on Failure**: Report → Propose fix → Request approval → Then fix
+
+---
+
+## Example: Adapter Implementation
+
+```
+1. Discover:
+   - ContextScout finds baseadapter-pattern.md
+   - Load code-quality.md standards
+
+2. Propose:
+   "Implement WindsurfAdapter (514 lines)
+    - Bidirectional conversion
+    - Extends BaseAdapter
+    - JSON config format"
+   
+3. Init Session:
+   Create .tmp/sessions/2026-02-04-windsurf-adapter/
+   Write context.md with standards + references
+
+4. Plan:
+   Simple (1 file) → Skip TaskManager
+
+5. Execute:
+   - Create WindsurfAdapter.ts
+   - Implement toOAC(), fromOAC()
+   - Export in index.ts
+   - npm run build (validate)
+
+6. Validate:
+   - Compilation: ✅ 0 errors
+   - Ready for unit tests (next phase)
+```
+
+---
+
+## Reference
+
+**Related**:
+- standards/code-quality.md (MANDATORY before coding)
+- concepts/compatibility-layer.md
+- examples/baseadapter-implementation.md

.opencode/context/openagents-repo/guides/compatibility-layer-workflow.md

@@ -0,0 +1,212 @@
+# Guide: Compatibility Layer Development Workflow
+
+**Purpose**: Step-by-step process for extending the compatibility layer to support new AI coding tools
+
+**Last Updated**: 2026-02-05
+
+---
+
+## When to Use This Guide
+
+- Adding support for a new AI coding tool (e.g., Codeium, GitHub Copilot)
+- Extending existing adapter capabilities
+- Understanding the development phases for compatibility work
+
+---
+
+## Development Phases
+
+### Phase 1: Foundation ✅ COMPLETE
+
+**Objective**: Set up project infrastructure and core types
+
+1. **Project Setup** (1.5h) ✅
+   - Create `packages/compatibility-layer/package.json`
+   - Configure TypeScript with strict mode
+   - Set up Vitest with 80%+ coverage thresholds
+
+2. **Type System** (1.5h) ✅
+   - Create `src/types.ts` with Zod schemas
+   - Define `OpenAgentSchema`, `AgentFrontmatterSchema`
+   - Export TypeScript types with `z.infer<>`
+
+3. **Base Adapter** (1.5h) ✅
+   - Create `src/adapters/BaseAdapter.ts` abstract class
+   - Define abstract methods: `toOAC()`, `fromOAC()`, `getCapabilities()`
+
+4. **Agent Loader** (1.5h) ✅
+   - Create `src/core/AgentLoader.ts`
+   - Use gray-matter for YAML frontmatter parsing
+
+5. **Adapter Registry** (1h) ✅
+   - Create `src/core/AdapterRegistry.ts`
+   - Implement registry pattern with `Map<string, BaseAdapter>`
+
+6. **Public API** (1h) ✅
+   - Create `src/index.ts`
+   - Export all public APIs
+
+**Result**: 1,475 lines TypeScript, 0 compilation errors
+
+---
+
+### Phase 2: Adapter Migration ✅ COMPLETE
+
+**Objective**: Migrate existing adapters to TypeScript
+
+7. **Claude Adapter** (3h) ✅ - 600 lines
+8. **Cursor Adapter** (3h) ✅ - 554 lines
+9. **Windsurf Adapter** (3h) ✅ - 514 lines
+10. **ClaudeAdapter Tests** ✅ - 80 tests, 96% coverage
+11. **CursorAdapter Tests** ✅ - 78 tests, 99% coverage
+12. **WindsurfAdapter Tests** ✅ - 78 tests, 99% coverage
+
+**Result**: 1,858 lines TypeScript, 236 tests passing
+
+---
+
+### Phase 3: Mappers & Translation ✅ COMPLETE
+
+**Objective**: Implement feature mapping logic
+
+13. **Tool Mapper** ✅ - 308 lines, 34 tests, 100% coverage
+14. **Permission Mapper** ✅ - 354 lines, 37 tests, 98% coverage
+15. **Model Mapper** ✅ - 413 lines, 37 tests, 99% coverage
+16. **Context Mapper** ✅ - 384 lines, 51 tests, 97% coverage
+17. **Capability Matrix** ✅ - 559 lines, 43 tests, 99% coverage
+18. **Translation Engine** ✅ - 453 lines, 47 tests, 99% coverage
+19. **Mapper Tests** ✅ - 249 tests total
+
+**Result**: 2,471 lines TypeScript, 249 tests passing
+
+---
+
+### Phase 4: CLI Tool ⬅️ NEXT
+
+**Objective**: Build command-line interface
+
+20. **CLI Scaffolding** (1.5h)
+    - Create `src/cli/index.ts` with Commander.js
+    - Define commands: convert, validate, migrate, info
+    - Set up chalk for colored output, ora for spinners
+
+21. **Convert Command** (2h)
+    - Implement `commands/convert.ts`
+    - Usage: `oac-compat convert --from oac --to claude agent.md`
+    - Support batch conversion
+
+22. **Validate Command** (1.5h)
+    - Implement `commands/validate.ts`
+    - Check compatibility before conversion
+    - Report warnings and incompatibilities
+
+23. **Migrate Command** (2h)
+    - Implement `commands/migrate.ts`
+    - Migrate entire projects (all agents + context)
+    - Generate migration report
+
+24. **Info Command** (1h)
+    - Implement `commands/info.ts`
+    - Show tool capabilities and feature matrices
+    - Display adapter list
+
+25. **CLI Integration Tests** (2h)
+    - Test each command end-to-end
+    - Test error handling
+    - Test output formatting
+
+---
+
+### Phase 5: Documentation
+
+**Objective**: Create migration guides and API docs
+
+26-30. **Migration Guides** (4h total)
+    - `docs/migration-guides/cursor-to-oac.md`
+    - `docs/migration-guides/claude-to-oac.md`
+    - `docs/migration-guides/oac-to-cursor.md`
+    - `docs/migration-guides/oac-to-claude.md`
+    - `docs/migration-guides/oac-to-windsurf.md`
+
+31. **Feature Matrices** (1h)
+    - Generate comparison tables
+    - Document degradation patterns
+
+32. **API Documentation** (1h)
+    - Document programmatic API usage
+    - Add examples for each adapter
+
+---
+
+## Adding a New Tool Adapter
+
+### Step-by-Step
+
+1. **Research Tool Format**
+   - Study tool's configuration file structure
+   - Identify supported features
+   - Note limitations vs OAC
+
+2. **Create Adapter Class**
+   ```typescript
+   export class NewToolAdapter extends BaseAdapter {
+     name = 'newtool'
+     displayName = 'New Tool'
+     
+     async toOAC(source: string): Promise<OpenAgent> { /* ... */ }
+     async fromOAC(agent: OpenAgent): Promise<ConversionResult> { /* ... */ }
+     getConfigPath(): string { /* ... */ }
+     getCapabilities(): ToolCapabilities { /* ... */ }
+     validateConversion(agent: OpenAgent): string[] { /* ... */ }
+   }
+   ```
+
+3. **Use Existing Mappers**
+   - ToolMapper for tool name translation
+   - PermissionMapper for permission translation
+   - ModelMapper for model ID translation
+   - ContextMapper for context path translation
+
+4. **Register Adapter**
+   ```typescript
+   AdapterRegistry.register(new NewToolAdapter())
+   ```
+
+5. **Write Tests** (Target: 80%+ coverage)
+
+6. **Update Documentation**
+
+---
+
+## Success Criteria
+
+**Phase 1-3** ✅ ACHIEVED:
+- [x] All files compile without errors
+- [x] Zod schemas validate correctly
+- [x] All 3 adapters migrated to TypeScript
+- [x] Unit tests pass with 80%+ coverage
+- [x] All mappers are pure functions
+- [x] Graceful degradation works
+
+**Phase 4** (upcoming):
+- [ ] CLI commands work end-to-end
+- [ ] Error handling is comprehensive
+- [ ] Output is user-friendly
+
+**Phase 5** (upcoming):
+- [ ] Migration guides cover all tools
+- [ ] API docs are complete
+- [ ] Examples demonstrate usage
+
+---
+
+## Reference
+
+- **Issue**: https://github.com/darrenhinde/OpenAgentsControl/issues/141
+- **Branch**: `devalexanderdaza/issue141`
+- **Location**: `packages/compatibility-layer/`
+
+**Related**:
+- lookup/compatibility-layer-progress.md
+- lookup/compatibility-layer-adapters.md
+- lookup/compatibility-layer-structure.md

.opencode/context/openagents-repo/guides/creating-skills.md

@@ -0,0 +1,81 @@
+# Creating Skills
+
+**Purpose**: Step-by-step guide to create Agent Skills
+
+---
+
+## Quickstart
+
+1. **Create directory**:
+   ```bash
+   mkdir -p ~/.claude/skills/my-skill
+   ```
+
+2. **Create SKILL.md** with frontmatter:
+   ```yaml
+   ---
+   name: my-skill
+   description: What it does and when to use it
+   ---
+   
+   Instructions for Claude...
+   ```
+
+3. **Verify**: Ask Claude "What Skills are available?"
+
+4. **Test**: Ask Claude something matching the description
+
+---
+
+## Writing Good Descriptions
+
+The description determines when Claude uses the skill. Include:
+- **What it does**: List specific capabilities
+- **When to use**: Include trigger terms users would say
+
+```yaml
+# Bad
+description: Helps with documents
+
+# Good
+description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
+```
+
+---
+
+## Progressive Disclosure
+
+Keep `SKILL.md` under 500 lines. Use supporting files for details:
+
+```
+my-skill/
+├── SKILL.md         # Overview (required)
+├── reference.md     # Detailed docs (loaded when needed)
+├── examples.md      # Usage examples
+└── scripts/
+    └── helper.py    # Utility script (executed, not loaded)
+```
+
+Reference in SKILL.md:
+```markdown
+For complete API details, see [reference.md](reference.md)
+```
+
+---
+
+## Key Points
+
+- Skills are loaded automatically (no restart needed)
+- Use `claude --debug` to see loading errors
+- Skills cannot spawn subagents
+- Use allowed-tools to restrict capabilities
+
+---
+
+## Related
+
+- `../concepts/agent-skills.md` - Skills overview
+- `../lookup/skill-metadata.md` - All metadata fields
+- `../examples/skills/` - Example skills
+
+**Reference**: https://docs.anthropic.com/en/docs/claude-code/skills

.opencode/context/openagents-repo/guides/creating-subagents.md

@@ -0,0 +1,73 @@
+# Creating Subagents
+
+**Purpose**: Step-by-step guide to create custom subagents
+
+---
+
+## Interactive Method (/agents)
+
+1. Run `/agents` in Claude Code
+2. Select **Create new agent**
+3. Choose scope: **User-level** or **Project-level**
+4. Select **Generate with Claude** and describe the subagent
+5. Select tools (or keep all)
+6. Choose model
+7. Pick a color
+8. Save - available immediately
+
+---
+
+## Manual Method (Markdown File)
+
+Create file at `~/.claude/agents/` (personal) or `.claude/agents/` (project):
+
+```markdown
+---
+name: code-reviewer
+description: Reviews code for quality and best practices
+tools: Read, Glob, Grep
+model: sonnet
+---
+
+You are a code reviewer. Analyze code and provide specific, 
+actionable feedback on quality, security, and best practices.
+```
+
+Restart session or use `/agents` to load.
+
+---
+
+## CLI Method (JSON)
+
+```bash
+claude --agents '{
+  "code-reviewer": {
+    "description": "Expert code reviewer",
+    "prompt": "You are a senior code reviewer...",
+    "tools": ["Read", "Grep", "Glob", "Bash"],
+    "model": "sonnet"
+  }
+}'
+```
+
+Session-only, not saved to disk.
+
+---
+
+## Key Points
+
+- Filename becomes subagent name (without `.md`)
+- Description determines when Claude delegates
+- Body becomes system prompt
+- Subagents only get their system prompt, not full Claude Code prompt
+- Include "use proactively" in description for automatic delegation
+
+---
+
+## Related
+
+- `../concepts/subagents-system.md` - Subagents overview
+- `../lookup/subagent-frontmatter.md` - All configuration fields
+- `../examples/subagents/` - Example subagents
+
+**Reference**: https://docs.anthropic.com/en/docs/claude-code/sub-agents

.opencode/context/openagents-repo/guides/navigation.md

@@ -18,9 +18,12 @@ openagents-repo/guides/
 
 | Task | Path |
 |------|------|
-| **Adding agents** | `./adding-agent.md` |
+| **Adding agents (basics)** | `./adding-agent-basics.md` |
+| **Adding agents (tests)** | `./adding-agent-testing.md` |
+| **Adding OpenCode skills** | `./adding-skill-basics.md` |
+| **Creating Claude Code skills** | `./creating-skills.md` |
+| **Creating Claude Code subagents** | `./creating-subagents.md` |
 | **Testing subagents** | `./testing-subagents.md` |
-| **View all guides** | `./` |
 
 ---
 

.opencode/context/openagents-repo/lookup/builtin-subagents.md

@@ -0,0 +1,71 @@
+# Built-in Subagents
+
+**Purpose**: Quick reference for Claude Code's default subagents
+
+---
+
+## Explore
+
+**Model**: Haiku (fast, low-latency)
+**Tools**: Read-only (denied Write, Edit)
+**Purpose**: File discovery, code search, codebase exploration
+
+Thoroughness levels:
+- `quick` - Targeted lookups
+- `medium` - Balanced exploration
+- `very thorough` - Comprehensive analysis
+
+---
+
+## Plan
+
+**Model**: Inherits from main conversation
+**Tools**: Read-only (denied Write, Edit)
+**Purpose**: Codebase research for planning
+
+Used during plan mode to gather context before presenting a plan. Cannot spawn other subagents.
+
+---
+
+## general-purpose
+
+**Model**: Inherits from main conversation
+**Tools**: All tools
+**Purpose**: Complex research, multi-step operations, code modifications
+
+Used when task requires both exploration AND modification, complex reasoning, or multiple dependent steps.
+
+---
+
+## Other Built-in Agents
+
+| Agent | Model | Purpose |
+|-------|-------|---------|
+| Bash | Inherits | Terminal commands in separate context |
+| statusline-setup | Sonnet | Configure status line (`/statusline`) |
+| Claude Code Guide | Haiku | Questions about Claude Code features |
+
+---
+
+## Disabling Subagents
+
+In settings or CLI:
+```json
+{
+  "permissions": {
+    "deny": ["Task(Explore)", "Task(my-custom-agent)"]
+  }
+}
+```
+
+Or: `claude --disallowedTools "Task(Explore)"`
+
+---
+
+## Related
+
+- `../concepts/subagents-system.md` - Subagents overview
+- `../guides/creating-subagents.md` - Custom subagents
+- `../lookup/subagent-frontmatter.md` - Configuration
+
+**Reference**: https://docs.anthropic.com/en/docs/claude-code/sub-agents

.opencode/context/openagents-repo/lookup/compatibility-layer-adapters.md

@@ -0,0 +1,156 @@
+# Lookup: Compatibility Layer Adapters
+
+**Purpose**: Quick reference for implemented adapter details
+
+**Last Updated**: 2026-02-05
+
+---
+
+## Adapter Summary
+
+| Adapter | Lines | Tests | Coverage | Status |
+|---------|-------|-------|----------|--------|
+| **ClaudeAdapter** | 600 | 80 | 96% | ✅ Complete |
+| **CursorAdapter** | 554 | 78 | 99% | ✅ Complete |
+| **WindsurfAdapter** | 514 | 78 | 99% | ✅ Complete |
+
+**Total**: 1,858 lines of TypeScript, 236 tests
+
+---
+
+## ClaudeAdapter
+
+**Format**: `.claude/config.json` (primary), `.claude/agents/*.md` (subagents)
+
+**Capabilities**:
+- ✅ Multiple agents
+- ✅ Skills system
+- ✅ Hooks (5 types: PreToolUse, PostToolUse, PermissionRequest, AgentStart, AgentEnd)
+- ⚠️ Binary permissions (granular → degraded)
+- ❌ Temperature not supported
+
+**Key Mappings**:
+- Model: `claude-sonnet-4` ↔ `claude-sonnet-4-20250514`
+- Permissions: Granular OAC → `permissionMode` (default/acceptEdits/dontAsk/bypassPermissions)
+- Contexts → Skills system
+
+**Tests**: 80 tests covering toOAC(), fromOAC(), roundtrip, error handling
+
+---
+
+## CursorAdapter
+
+**Format**: `.cursorrules` (single file in project root)
+
+**Capabilities**:
+- ❌ Single agent only (multi-agent → merged)
+- ❌ No Skills system (contexts → inlined)
+- ❌ No Hooks
+- ⚠️ Binary permissions only
+- ✅ Temperature support (limited)
+
+**Key Features**:
+- `mergeAgents()` method for multi-agent → single-file conversion
+- Optional YAML frontmatter
+- Context inlining with references
+
+**Key Mappings**:
+- Model: `claude-sonnet-4` → `claude-3-sonnet` (fallback to v3)
+- Multiple agents → Merged with section headers
+
+**Tests**: 78 tests covering toOAC(), fromOAC(), merging, error handling
+
+---
+
+## WindsurfAdapter
+
+**Format**: `.windsurf/config.json`, `.windsurf/agents/*.json`
+
+**Capabilities**:
+- ✅ Multiple agents (`.windsurf/agents/`)
+- ⚠️ Partial Skills (→ context references)
+- ❌ No Hooks
+- ⚠️ Binary permissions only
+- ✅ Temperature via creativity setting
+
+**Key Mappings**:
+- Model: `claude-sonnet-4` ↔ `claude-4-sonnet`
+- Temperature ↔ Creativity: `≤0.4 → low`, `≤0.8 → medium`, `>0.8 → high`
+- Priority: `critical/high → high`, `medium/low → low`
+- Skills → Context file references in `.windsurf/context/`
+
+**Tests**: 78 tests covering toOAC(), fromOAC(), creativity mapping, error handling
+
+---
+
+## Mappers (Phase 3 ✅)
+
+All mappers are pure functions used by adapters and TranslationEngine:
+
+| Mapper | Lines | Tests | Coverage | Purpose |
+|--------|-------|-------|----------|---------|
+| **ToolMapper** | 308 | 34 | 100% | Tool name mapping (bash↔terminal, etc.) |
+| **PermissionMapper** | 354 | 37 | 98% | Granular↔binary permissions |
+| **ModelMapper** | 413 | 37 | 99% | Model ID mapping with fallbacks |
+| **ContextMapper** | 384 | 51 | 97% | Context path mapping between platforms |
+
+---
+
+## Core Services (Phase 3 ✅)
+
+| Service | Lines | Tests | Coverage | Purpose |
+|---------|-------|-------|----------|---------|
+| **CapabilityMatrix** | 559 | 43 | 99% | Feature compatibility analysis |
+| **TranslationEngine** | 453 | 47 | 99% | Orchestrates all mappers |
+
+---
+
+## Common Patterns
+
+### Bidirectional Conversion
+All 3 adapters support:
+- `toOAC()`: Tool format → OpenAgent
+- `fromOAC()`: OpenAgent → Tool format
+
+### Graceful Degradation
+All adapters warn when features are lost:
+- Granular permissions → Binary on/off
+- Unsupported features → Warning messages
+- Feature loss → Clear user notifications
+
+### Type Safety
+- All extend `BaseAdapter`
+- Full TypeScript strict mode
+- Zod schema validation
+- 0 compilation errors
+
+---
+
+## Feature Parity Matrix
+
+| Feature | OAC | Claude | Cursor | Windsurf |
+|---------|-----|--------|--------|----------|
+| Multiple Agents | ✅ | ✅ | ❌ | ✅ |
+| Granular Permissions | ✅ | ❌ | ❌ | ❌ |
+| Ask Permissions | ✅ | ❌ | ❌ | ❌ |
+| Hooks | ✅ | ✅ | ❌ | ❌ |
+| Skills | ✅ | ✅ | ❌ | ⚠️ |
+| External Context | ✅ | ✅ | ❌ | ✅ |
+| Context Priority | ✅ | ❌ | ❌ | ❌ |
+| Temperature | ✅ | ❌ | ⚠️ | ✅ |
+| Model Selection | ✅ | ✅ | ✅ | ✅ |
+| Task Delegation | ✅ | ✅ | ❌ | ⚠️ |
+
+Legend: ✅ Full support, ⚠️ Partial support, ❌ Not supported
+
+---
+
+## Reference
+
+**Implementation**: `packages/compatibility-layer/src/adapters/`
+**Issue**: https://github.com/darrenhinde/OpenAgentsControl/issues/141
+
+**Related**:
+- lookup/compatibility-layer-progress.md
+- lookup/compatibility-layer-structure.md
+- guides/compatibility-layer-workflow.md

.opencode/context/openagents-repo/lookup/compatibility-layer-progress.md

@@ -0,0 +1,161 @@
+# Lookup: Compatibility Layer Progress
+
+**Purpose**: Quick reference for Issue #141 development progress
+
+**Last Updated**: 2026-02-05
+
+---
+
+## Current Status
+
+**Overall Progress**: 59.4% (19/32 subtasks completed)
+
+```
+Phase 1 (Foundation):     ████████████████████ 100% (6/6) ✅
+Phase 2 (Adapters):       ████████████████████ 100% (6/6) ✅
+Phase 3 (Mappers):        ████████████████████ 100% (7/7) ✅
+Phase 4 (CLI):            ░░░░░░░░░░░░░░░░░░░░   0% (0/6) ⬅️ NEXT
+Phase 5 (Documentation):  ░░░░░░░░░░░░░░░░░░░░   0% (0/7)
+```
+
+---
+
+## Phase Breakdown
+
+### Phase 1: Foundation (100% ✅)
+**Time**: 7.5h / 8h estimated
+
+- ✅ Subtask 01: Project Setup
+- ✅ Subtask 02: Migrate types.ts (315 lines)
+- ✅ Subtask 03: Create BaseAdapter (190 lines)
+- ✅ Subtask 04: Migrate AgentLoader (386 lines)
+- ✅ Subtask 05: Migrate AdapterRegistry (416 lines)
+- ✅ Subtask 06: Create index.ts (168 lines)
+
+**Total**: 1,475 lines TypeScript
+
+---
+
+### Phase 2: Adapters (100% ✅)
+**Time**: ~12h
+
+- ✅ Subtask 07: ClaudeAdapter (600 lines)
+- ✅ Subtask 08: CursorAdapter (554 lines)
+- ✅ Subtask 09: WindsurfAdapter (514 lines)
+- ✅ Subtask 10: ClaudeAdapter tests (80 tests)
+- ✅ Subtask 11: CursorAdapter tests (78 tests)
+- ✅ Subtask 12: WindsurfAdapter tests (78 tests)
+
+**Total**: 1,858 lines TypeScript (adapters) + 236 tests
+
+---
+
+### Phase 3: Mappers & Translation (100% ✅)
+**Time**: ~10h
+
+- ✅ Subtask 13: ToolMapper (308 lines, 34 tests)
+- ✅ Subtask 14: PermissionMapper (354 lines, 37 tests)
+- ✅ Subtask 15: ModelMapper (413 lines, 37 tests)
+- ✅ Subtask 16: ContextMapper (384 lines, 51 tests)
+- ✅ Subtask 17: CapabilityMatrix (559 lines, 43 tests)
+- ✅ Subtask 18: TranslationEngine (453 lines, 47 tests)
+- ✅ Subtask 19: Mapper & Core Tests (249 tests total)
+
+**Total**: 2,471 lines TypeScript + 249 tests
+
+---
+
+### Phase 4: CLI (0% ⬅️ NEXT)
+**Estimated**: 8h
+
+- 📝 Subtask 20: CLI Scaffolding (Commander.js setup)
+- 📝 Subtask 21: Convert Command
+- 📝 Subtask 22: Validate Command
+- 📝 Subtask 23: Migrate Command
+- 📝 Subtask 24: Info Command
+- 📝 Subtask 25: CLI Integration Tests
+
+---
+
+### Phase 5: Documentation (0%)
+**Estimated**: 6h
+
+- 📝 Subtask 26-30: Migration Guides (5 guides)
+- 📝 Subtask 31: Feature Matrices
+- 📝 Subtask 32: API Documentation
+
+---
+
+## Code Stats
+
+| Category | Lines | Files |
+|----------|-------|-------|
+| Source Code | 5,799 | 14 |
+| Test Code | 6,322 | 9 |
+| **Total** | **12,121** | **23** |
+
+### By Phase
+
+| Phase | Source Lines | Tests |
+|-------|-------------|-------|
+| Phase 1 (Foundation) | 1,475 | - |
+| Phase 2 (Adapters) | 1,858 | 236 |
+| Phase 3 (Mappers) | 2,471 | 249 |
+| **Total** | **5,804** | **485** |
+
+---
+
+## Test Coverage
+
+**485 tests passing** ✅
+
+| Module | Statements | Branches | Functions |
+|--------|-----------|----------|-----------|
+| Adapters | 97-99% | 82-93% | 95-100% |
+| Mappers | 97-100% | 90-100% | 100% |
+| Core (Matrix/Engine) | 98-99% | 93-96% | 100% |
+
+---
+
+## Commits (Issue #141)
+
+| Commit | Phase | Description |
+|--------|-------|-------------|
+| `0b98cbd` | 1 | Foundation implementation |
+| `340d144` | 1 | AgentLoader |
+| `81c2f65` | 1 | AdapterRegistry |
+| `175eac8` | 1 | index.ts entry point |
+| `d38dc27` | 2 | ClaudeAdapter |
+| `7695696` | 2 | CursorAdapter |
+| `71fa384` | 2 | WindsurfAdapter |
+| `a9176c9` | 2 | ClaudeAdapter tests |
+| `713fd09` | 2 | CursorAdapter tests |
+| `0b93a47` | 2 | WindsurfAdapter tests |
+| `99eba67` | 3 | Mappers, Matrix, Engine + tests |
+
+---
+
+## Next Steps
+
+1. **Phase 4**: CLI Tool Implementation
+   - Create `src/cli/index.ts` with Commander.js
+   - Implement convert, validate, migrate, info commands
+   - Add CLI integration tests
+
+2. **Phase 5**: Documentation
+   - Migration guides for all tool combinations
+   - Feature matrices
+   - API documentation
+
+---
+
+## Reference
+
+**Issue**: https://github.com/darrenhinde/OpenAgentsControl/issues/141
+**Branch**: `devalexanderdaza/issue141`
+**Location**: `packages/compatibility-layer/`
+
+**Related**:
+- lookup/compatibility-layer-adapters.md
+- lookup/compatibility-layer-structure.md
+- guides/compatibility-layer-workflow.md

.opencode/context/openagents-repo/lookup/compatibility-layer-structure.md

@@ -0,0 +1,168 @@
+# Lookup: Compatibility Layer File Structure
+
+**Purpose**: Quick reference for where files go in the compatibility-layer package
+
+**Last Updated**: 2026-02-05
+
+---
+
+## Package Location
+
+```
+packages/compatibility-layer/
+```
+
+---
+
+## Directory Structure (Current State)
+
+```
+compatibility-layer/
+├── package.json              # Dependencies, scripts
+├── tsconfig.json             # TypeScript config (strict, ES2022)
+├── vitest.config.ts          # Test config (80% coverage threshold)
+├── README.md                 # Package documentation
+│
+├── src/                      # Source code (5,799 lines)
+│   ├── types.ts              # Zod schemas + type exports (315 lines) ✅
+│   ├── index.ts              # Public API exports (335 lines) ✅
+│   │
+│   ├── adapters/             # Tool adapters ✅ COMPLETE
+│   │   ├── BaseAdapter.ts    # Abstract base class (190 lines)
+│   │   ├── ClaudeAdapter.ts  # Claude Code adapter (600 lines)
+│   │   ├── CursorAdapter.ts  # Cursor IDE adapter (554 lines)
+│   │   └── WindsurfAdapter.ts # Windsurf adapter (514 lines)
+│   │
+│   ├── core/                 # Core services ✅ COMPLETE
+│   │   ├── AgentLoader.ts    # Load/parse OAC agents (386 lines)
+│   │   ├── AdapterRegistry.ts # Adapter management (416 lines)
+│   │   ├── CapabilityMatrix.ts # Feature parity tracking (559 lines)
+│   │   └── TranslationEngine.ts # Conversion orchestration (453 lines)
+│   │
+│   ├── mappers/              # Feature mappers ✅ COMPLETE
+│   │   ├── ToolMapper.ts     # Tool name mapping (308 lines)
+│   │   ├── PermissionMapper.ts # Permission translation (354 lines)
+│   │   ├── ModelMapper.ts    # Model ID mapping (413 lines)
+│   │   └── ContextMapper.ts  # Context path mapping (384 lines)
+│   │
+│   └── cli/                  # Command-line interface 📝 TODO
+│       ├── index.ts          # CLI entry point
+│       └── commands/
+│           ├── convert.ts    # Convert command
+│           ├── validate.ts   # Validate command
+│           ├── migrate.ts    # Migrate command
+│           └── info.ts       # Info command
+│
+├── tests/                    # Test files (6,322 lines, 485 tests)
+│   └── unit/
+│       ├── adapters/         # Adapter tests ✅ COMPLETE
+│       │   ├── ClaudeAdapter.test.ts (80 tests)
+│       │   ├── CursorAdapter.test.ts (78 tests)
+│       │   └── WindsurfAdapter.test.ts (78 tests)
+│       ├── mappers/          # Mapper tests ✅ COMPLETE
+│       │   ├── ToolMapper.test.ts (34 tests)
+│       │   ├── PermissionMapper.test.ts (37 tests)
+│       │   ├── ModelMapper.test.ts (37 tests)
+│       │   └── ContextMapper.test.ts (51 tests)
+│       └── core/             # Core tests ✅ COMPLETE
+│           ├── CapabilityMatrix.test.ts (43 tests)
+│           └── TranslationEngine.test.ts (47 tests)
+│
+├── docs/                     # Documentation 📝 TODO
+│   ├── migration-guides/     # Migration instructions
+│   ├── feature-matrices/     # Feature comparison tables
+│   └── api/                  # API documentation
+│
+└── dist/                     # Compiled output (auto-generated)
+```
+
+---
+
+## Implementation Status
+
+### ✅ Complete (Phases 1-3)
+
+| File | Lines | Tests | Coverage |
+|------|-------|-------|----------|
+| types.ts | 315 | - | - |
+| index.ts | 335 | - | - |
+| BaseAdapter.ts | 190 | - | 92% |
+| ClaudeAdapter.ts | 600 | 80 | 96% |
+| CursorAdapter.ts | 554 | 78 | 99% |
+| WindsurfAdapter.ts | 514 | 78 | 99% |
+| AgentLoader.ts | 386 | - | 0%* |
+| AdapterRegistry.ts | 416 | - | 0%* |
+| CapabilityMatrix.ts | 559 | 43 | 99% |
+| TranslationEngine.ts | 453 | 47 | 99% |
+| ToolMapper.ts | 308 | 34 | 100% |
+| PermissionMapper.ts | 354 | 37 | 98% |
+| ModelMapper.ts | 413 | 37 | 99% |
+| ContextMapper.ts | 384 | 51 | 97% |
+
+*AgentLoader and AdapterRegistry are tested indirectly via adapters
+
+### 📝 Pending (Phase 4-5)
+
+| File | Purpose | Phase |
+|------|---------|-------|
+| cli/index.ts | CLI entry point | 4 |
+| cli/commands/convert.ts | Convert command | 4 |
+| cli/commands/validate.ts | Validate command | 4 |
+| cli/commands/migrate.ts | Migrate command | 4 |
+| cli/commands/info.ts | Info command | 4 |
+| docs/migration-guides/*.md | Migration guides | 5 |
+| docs/api/*.md | API documentation | 5 |
+
+---
+
+## Dependencies
+
+### Production
+
+| Package | Purpose | Version |
+|---------|---------|---------|
+| zod | Schema validation | ^3.22.0 |
+| js-yaml | YAML parsing | ^4.1.0 |
+| gray-matter | Frontmatter extraction | ^4.0.3 |
+
+### Development
+
+| Package | Purpose | Version |
+|---------|---------|---------|
+| typescript | TypeScript compiler | ^5.4.0 |
+| vitest | Test framework | ^1.6.1 |
+| @vitest/coverage-v8 | Coverage reporting | ^1.6.1 |
+
+### CLI (Phase 4 - to be added)
+
+| Package | Purpose | Version |
+|---------|---------|---------|
+| commander | CLI framework | ^11.1.0 |
+| chalk | Terminal colors | ^5.3.0 |
+| ora | Loading spinners | ^7.0.1 |
+
+---
+
+## Scripts
+
+```json
+{
+  "build": "tsc",
+  "build:watch": "tsc --watch",
+  "test": "vitest run",
+  "test:watch": "vitest",
+  "test:coverage": "vitest run --coverage"
+}
+```
+
+---
+
+## Reference
+
+- **Issue**: https://github.com/darrenhinde/OpenAgentsControl/issues/141
+- **Branch**: `devalexanderdaza/issue141`
+
+**Related**:
+- lookup/compatibility-layer-progress.md
+- lookup/compatibility-layer-adapters.md
+- guides/compatibility-layer-workflow.md

.opencode/context/openagents-repo/lookup/compatibility-layer-summary.md

@@ -0,0 +1,97 @@
+# Compatibility Layer - Executive Summary
+
+**Issue**: #141 | **Branch**: `devalexanderdaza/issue141` | **Updated**: 2026-02-05
+
+---
+
+## Quick Status
+
+```
+Progress: ████████████░░░░░░░░ 59.4% (19/32 subtasks)
+
+✅ Phase 1: Foundation    - 6/6 complete
+✅ Phase 2: Adapters      - 6/6 complete  
+✅ Phase 3: Mappers       - 7/7 complete
+⬅️ Phase 4: CLI          - 0/6 pending (NEXT)
+📝 Phase 5: Documentation - 0/7 pending
+```
+
+---
+
+## Codebase Stats
+
+| Metric | Value |
+|--------|-------|
+| Source Lines | 5,799 (14 files) |
+| Test Lines | 6,322 (9 files) |
+| Tests | 485 passing |
+| Coverage | 97-100% on Phase 3 |
+
+---
+
+## What's Implemented
+
+### Adapters (3)
+- `ClaudeAdapter` - .claude/ format ↔ OAC
+- `CursorAdapter` - .cursorrules ↔ OAC  
+- `WindsurfAdapter` - .windsurf/ ↔ OAC
+
+### Mappers (4)
+- `ToolMapper` - bash↔terminal, task↔delegate
+- `PermissionMapper` - granular↔binary
+- `ModelMapper` - model IDs with fallbacks
+- `ContextMapper` - context paths between platforms
+
+### Core (2)
+- `CapabilityMatrix` - feature compatibility analysis
+- `TranslationEngine` - orchestrates all mappers
+
+---
+
+## What's Next
+
+**Phase 4: CLI Tool** (8h estimated)
+1. CLI scaffolding (Commander.js)
+2. `convert` command
+3. `validate` command
+4. `migrate` command
+5. `info` command
+6. Integration tests
+
+---
+
+## Key Commands
+
+```bash
+# Work directory
+cd packages/compatibility-layer
+
+# Build & Test
+npm run build      # Compile TypeScript
+npx vitest run     # Run all tests
+npx vitest run --coverage  # With coverage
+
+# Git
+git log --oneline -5  # Recent commits
+```
+
+---
+
+## Feature Parity
+
+| Feature | OAC | Claude | Cursor | Windsurf |
+|---------|:---:|:------:|:------:|:--------:|
+| Multi-Agent | ✅ | ✅ | ❌ | ✅ |
+| Hooks | ✅ | ✅ | ❌ | ❌ |
+| Granular Perms | ✅ | ❌ | ❌ | ❌ |
+| Skills | ✅ | ✅ | ❌ | ⚠️ |
+| Temperature | ✅ | ❌ | ⚠️ | ✅ |
+
+---
+
+## Reference Files
+
+- Progress: `lookup/compatibility-layer-progress.md`
+- Structure: `lookup/compatibility-layer-structure.md`
+- Adapters: `lookup/compatibility-layer-adapters.md`
+- Workflow: `guides/compatibility-layer-workflow.md`

.opencode/context/openagents-repo/lookup/compatibility-learnings.md

@@ -0,0 +1,161 @@
+# Lookup: Compatibility Layer Key Learnings
+
+**Purpose**: Important insights from Phase 1-3 development
+
+**Last Updated**: 2026-02-05
+
+---
+
+## TypeScript & Architecture
+
+**TypeScript strict mode works perfectly**
+- Zero compilation errors across all 14 source files
+- Type safety catches conversion errors early
+- Zod + TypeScript prevent runtime issues
+
+**Adapter pattern scales beautifully**
+- 3 adapters, 0 duplication, consistent API
+- Template method pattern enables reuse
+- BaseAdapter provides robust foundation
+
+**Project structure is clean**
+- Modular organization enables parallel development
+- Function-based folders improve discoverability
+- Barrel exports provide clean public API
+
+---
+
+## Code Quality
+
+**Zod schemas are comprehensive**
+- All 20+ schemas validated and working
+- Runtime validation prevents bad data
+- Type inference from schemas reduces duplication
+
+**Pure functions enable testing**
+- All mappers are pure functions (ToolMapper, PermissionMapper, etc.)
+- Easy to test in isolation
+- Deterministic conversion
+- 97-100% coverage achieved on mappers
+
+**Registry pattern is powerful**
+- Map-based storage + aliases = great DX
+- O(1) adapter lookup
+- Type-safe registration
+
+---
+
+## Development Process
+
+**Context loading matters**
+- Reading standards BEFORE coding prevents rework
+- ContextScout saves discovery time
+- Persistent session context enables handoffs
+
+**Approval gates prevent mistakes**
+- User confirmation before destructive ops
+- Incremental execution catches issues early
+- Stop on failure prevents cascading errors
+
+**Phase completion tracking**
+- Phase 1: ✅ 100% (Foundation)
+- Phase 2: ✅ 100% (Adapters + Tests)
+- Phase 3: ✅ 100% (Mappers + Tests)
+- Overall: 59.4% complete (19/32 subtasks)
+
+---
+
+## Feature Implementation
+
+**Bidirectional conversion is achievable**
+- All 3 adapters support roundtrip (OAC ↔ Tool ↔ OAC)
+- Lossy conversions handled with clear warnings
+- Feature parity matrix guides expectations
+
+**Graceful degradation works**
+- Clear warnings guide users on feature loss
+- Binary permissions instead of failing
+- Temperature ↔ Creativity mapping (approximate but functional)
+
+**Translation Engine orchestration**
+- Coordinates all mappers for complete translation
+- Collects warnings from all components
+- Provides preview/compatibility analysis
+
+---
+
+## Technical Wins
+
+**Type-safe mappers prevent bugs**
+- Model ID mapping with fallbacks
+- Permission degradation with warnings
+- Priority normalization handles edge cases
+
+**Error handling is robust**
+- Custom error classes per module
+- Descriptive error messages
+- Validation at boundaries
+
+**Build system is solid**
+- TypeScript compilation fast (~1s)
+- All 485 tests pass
+- Coverage exceeds 80% on tested modules
+
+---
+
+## Test Coverage Summary
+
+| Category | Tests | Coverage |
+|----------|-------|----------|
+| Adapters | 236 | 97-99% |
+| Mappers | 159 | 97-100% |
+| Core | 90 | 98-99% |
+| **Total** | **485** | **>80%** |
+
+---
+
+## What Worked Well
+
+✅ Loading context before implementation  
+✅ Approval gates for safety  
+✅ Incremental execution (one step at a time)  
+✅ Template method pattern for adapters  
+✅ Pure functions for all mappers  
+✅ Zod validation throughout  
+✅ Comprehensive test coverage  
+✅ Conventional commits tracking
+
+---
+
+## What to Improve
+
+⚠️ Could add integration tests earlier  
+⚠️ Feature parity matrix could be auto-generated  
+⚠️ CLI tool would help during development  
+⚠️ AgentLoader/AdapterRegistry need direct unit tests
+
+---
+
+## Remaining Work
+
+**Phase 4 (CLI)**: 6 subtasks
+- CLI scaffolding with Commander.js
+- convert, validate, migrate, info commands
+- Integration tests
+
+**Phase 5 (Documentation)**: 7 subtasks
+- 5 migration guides
+- Feature matrices
+- API documentation
+
+---
+
+## Reference
+
+**Issue**: https://github.com/darrenhinde/OpenAgentsControl/issues/141
+**Branch**: `devalexanderdaza/issue141`
+
+**Related**:
+- lookup/compatibility-layer-progress.md
+- lookup/compatibility-layer-structure.md
+- guides/compatibility-layer-workflow.md

.opencode/context/openagents-repo/lookup/hook-events.md

@@ -0,0 +1,64 @@
+# Hook Events Reference
+
+**Purpose**: Quick reference for all Claude Code hook events
+
+---
+
+## Available Events
+
+| Event | When It Fires | Can Block? |
+|-------|---------------|------------|
+| `PreToolUse` | Before tool calls | Yes (exit 2) |
+| `PostToolUse` | After tool calls complete | No |
+| `PermissionRequest` | Permission dialog shown | Yes (allow/deny) |
+| `UserPromptSubmit` | User submits prompt | No |
+| `Notification` | Claude sends notification | No |
+| `Stop` | Claude finishes responding | No |
+| `SubagentStop` | Subagent task completes | No |
+| `PreCompact` | Before compact operation | No |
+| `SessionStart` | New/resumed session | No |
+| `SessionEnd` | Session ends | No |
+
+---
+
+## Matcher Syntax
+
+- `"Bash"` - Match specific tool
+- `"Edit|Write"` - Match multiple tools (OR)
+- `"*"` - Match all tools
+- `""` - Match all (for Notification)
+
+---
+
+## Exit Codes
+
+| Code | Behavior |
+|------|----------|
+| 0 | Success, continue execution |
+| 1 | Error logged, continue execution |
+| 2 | **Block operation**, feed stderr to Claude |
+
+---
+
+## Input/Output
+
+Hooks receive JSON via stdin:
+```json
+{
+  "tool_name": "Bash",
+  "tool_input": { "command": "ls -la" },
+  "session_id": "...",
+  "transcript_path": "..."
+}
+```
+
+Output to stderr is fed back to Claude when blocking (exit 2).
+
+---
+
+## Related
+
+- `../concepts/hooks-system.md` - Hooks overview
+- `../examples/hooks/` - Hook examples
+
+**Reference**: https://docs.anthropic.com/en/docs/claude-code/hooks

.opencode/context/openagents-repo/lookup/skill-metadata.md

@@ -0,0 +1,74 @@
+# Skill Metadata Fields
+
+**Purpose**: Quick reference for SKILL.md frontmatter fields
+
+---
+
+## Required Fields
+
+| Field | Description |
+|-------|-------------|
+| `name` | Unique identifier (lowercase, hyphens, max 64 chars) |
+| `description` | What skill does and when to use (max 1024 chars) |
+
+---
+
+## Optional Fields
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `allowed-tools` | All | Tools Claude can use without permission |
+| `model` | Conversation | Model to use (e.g., `claude-sonnet-4-20250514`) |
+| `context` | - | Set to `fork` for isolated sub-agent context |
+| `agent` | `general-purpose` | Agent type when `context: fork` |
+| `hooks` | - | Lifecycle hooks (`PreToolUse`, `PostToolUse`, `Stop`) |
+| `user-invocable` | `true` | Show in slash command menu |
+| `disable-model-invocation` | `false` | Block programmatic invocation |
+
+---
+
+## allowed-tools Syntax
+
+```yaml
+# Comma-separated
+allowed-tools: Read, Grep, Glob
+
+# YAML list
+allowed-tools:
+  - Read
+  - Grep
+  - Glob
+```
+
+---
+
+## hooks Syntax
+
+```yaml
+hooks:
+  PreToolUse:
+    - matcher: "Bash"
+      hooks:
+        - type: command
+          command: "./scripts/validate.sh"
+          once: true  # Run only once per session
+```
+
+---
+
+## Visibility Control
+
+| Setting | Slash Menu | Skill Tool | Auto-discovery |
+|---------|------------|------------|----------------|
+| Default | ✓ | ✓ | ✓ |
+| `user-invocable: false` | ✗ | ✓ | ✓ |
+| `disable-model-invocation: true` | ✓ | ✗ | ✓ |
+
+---
+
+## Related
+
+- `../concepts/agent-skills.md` - Skills overview
+- `../guides/creating-skills.md` - Creation guide
+
+**Reference**: https://docs.anthropic.com/en/docs/claude-code/skills

.opencode/context/openagents-repo/lookup/skills-comparison.md

@@ -0,0 +1,64 @@
+# Skills vs Other Options
+
+**Purpose**: When to use Skills versus other Claude Code customizations
+
+---
+
+## Comparison Table
+
+| Option | When It Runs | Best For |
+|--------|--------------|----------|
+| **Skills** | Claude chooses when relevant | Specialized knowledge (review standards, patterns) |
+| **Slash commands** | You type `/command` | Reusable prompts (`/deploy staging`) |
+| **CLAUDE.md** | Every conversation | Project-wide instructions |
+| **Subagents** | Claude delegates or you invoke | Isolated context, different tools |
+| **Hooks** | Specific tool events | Auto-format, logging, protection |
+| **MCP servers** | Claude calls as needed | External tools and data sources |
+
+---
+
+## Key Distinctions
+
+### Skills vs Slash Commands
+- **Skills**: Claude decides when to use based on task
+- **Commands**: You explicitly type `/command`
+
+### Skills vs Subagents
+- **Skills**: Add knowledge to current conversation
+- **Subagents**: Separate context with own tools/permissions
+
+### Skills vs MCP
+- **Skills**: Tell Claude *how* to use tools
+- **MCP**: *Provide* the tools themselves
+
+### Skills vs CLAUDE.md
+- **Skills**: Loaded only when relevant
+- **CLAUDE.md**: Always loaded into every conversation
+
+---
+
+## Decision Guide
+
+**Use Skills when**:
+- Teaching domain-specific knowledge
+- Defining review/coding standards
+- Want Claude to decide when to apply
+
+**Use Subagents when**:
+- Need tool isolation
+- Task produces verbose output
+- Want separate context window
+
+**Use CLAUDE.md when**:
+- Rules apply to ALL interactions
+- Project-wide coding standards
+
+---
+
+## Related
+
+- `../concepts/agent-skills.md` - Skills overview
+- `../concepts/subagents-system.md` - Subagents overview
+- `../../standards/subagent-structure.md` - Subagent patterns
+
+**Reference**: https://docs.anthropic.com/en/docs/claude-code/skills

.opencode/context/openagents-repo/lookup/subagent-frontmatter.md

@@ -0,0 +1,83 @@
+# Subagent Frontmatter
+
+**Purpose**: Quick reference for subagent configuration fields
+
+---
+
+## Required Fields
+
+| Field | Description |
+|-------|-------------|
+| `name` | Unique identifier (lowercase, hyphens) |
+| `description` | When Claude should delegate to this subagent |
+
+---
+
+## Optional Fields
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `tools` | All | Tools subagent can use |
+| `disallowedTools` | - | Tools to deny (removed from list) |
+| `model` | `sonnet` | Model: `sonnet`, `opus`, `haiku`, `inherit` |
+| `permissionMode` | `default` | Permission handling mode |
+| `skills` | - | Skills to load into context |
+| `hooks` | - | Lifecycle hooks for this subagent |
+
+---
+
+## Permission Modes
+
+| Mode | Behavior |
+|------|----------|
+| `default` | Standard permission checking |
+| `acceptEdits` | Auto-accept file edits |
+| `dontAsk` | Auto-deny permission prompts |
+| `bypassPermissions` | Skip all permission checks |
+| `plan` | Read-only exploration |
+
+⚠️ `bypassPermissions` is dangerous - skips all checks
+
+---
+
+## Hooks Syntax
+
+```yaml
+hooks:
+  PreToolUse:
+    - matcher: "Bash"
+      hooks:
+        - type: command
+          command: "./scripts/validate.sh"
+  PostToolUse:
+    - matcher: "Edit|Write"
+      hooks:
+        - type: command
+          command: "./scripts/lint.sh"
+```
+
+---
+
+## Example
+
+```yaml
+---
+name: debugger
+description: Debugging specialist for errors and test failures
+tools: Read, Edit, Bash, Grep, Glob
+model: inherit
+permissionMode: default
+---
+
+You are an expert debugger...
+```
+
+---
+
+## Related
+
+- `../concepts/subagents-system.md` - Subagents overview
+- `../guides/creating-subagents.md` - Creation guide
+- `../lookup/builtin-subagents.md` - Built-in subagents
+
+**Reference**: https://docs.anthropic.com/en/docs/claude-code/sub-agents

.opencode/context/openagents-repo/lookup/tool-feature-parity.md

@@ -0,0 +1,133 @@
+# Lookup: Tool Feature Parity Matrix
+
+**Purpose**: Quick reference for feature support across AI coding tools
+
+**Last Updated**: 2026-02-04
+
+---
+
+## Feature Comparison
+
+### Core Features
+
+| Feature | OAC | Claude Code | Cursor IDE | Windsurf | Notes |
+|---------|-----|-------------|------------|----------|-------|
+| **Multiple agents** | ✅ Yes | ✅ Yes | ❌ Single only | ✅ Yes | Cursor requires merged config |
+| **Agent modes** | ✅ primary/subagent | ✅ Yes | ❌ No | ⚠️ Partial | OAC has explicit mode field |
+| **Temperature control** | ✅ 0.0-2.0 | ❌ No | ⚠️ Limited | ⚠️ Limited | Maps to creativity settings |
+| **Model selection** | ✅ Full control | ✅ Yes | ✅ Yes | ✅ Yes | Different ID formats |
+| **Context files** | ✅ .opencode/context/ | ✅ Skills system | ✅ .cursorrules | ✅ Yes | Path mapping required |
+
+### Tool Permissions
+
+| Tool Access | OAC | Claude Code | Cursor IDE | Windsurf |
+|-------------|-----|-------------|------------|----------|
+| **read** | ✅ Granular | ⚠️ Binary on/off | ⚠️ Binary | ⚠️ Binary |
+| **write** | ✅ Granular | ⚠️ Binary | ⚠️ Binary | ⚠️ Binary |
+| **edit** | ✅ Granular | ⚠️ Binary | ⚠️ Binary | ⚠️ Binary |
+| **bash** | ✅ Granular | ✅ Yes | ✅ Yes | ✅ Yes |
+| **task** | ✅ Delegation | ✅ Yes | ❌ No | ⚠️ Limited |
+| **grep/glob** | ✅ Separate | ✅ Yes | ✅ Yes | ✅ Yes |
+
+**Legend**: ✅ Full support | ⚠️ Partial/degraded | ❌ Not supported
+
+### Advanced Features
+
+| Feature | OAC | Claude Code | Cursor IDE | Windsurf |
+|---------|-----|-------------|------------|----------|
+| **Skills system** | ✅ Yes | ✅ Yes | ❌ No | ⚠️ Partial |
+| **Hooks** | ✅ 5 types | ✅ Yes | ❌ No | ❌ No |
+| **Dependencies** | ✅ Explicit | ✅ Yes | ❌ No | ⚠️ Partial |
+| **Priority levels** | ✅ 4 levels | ⚠️ 2 levels | ❌ No | ⚠️ 2 levels |
+| **Agent categories** | ✅ 8 types | ⚠️ Limited | ❌ No | ⚠️ Limited |
+
+---
+
+## Hook Event Support
+
+| Event | OAC | Claude Code | Cursor | Windsurf |
+|-------|-----|-------------|--------|----------|
+| PreToolUse | ✅ | ✅ | ❌ | ❌ |
+| PostToolUse | ✅ | ✅ | ❌ | ❌ |
+| PermissionRequest | ✅ | ✅ | ❌ | ❌ |
+| AgentStart | ✅ | ✅ | ❌ | ❌ |
+| AgentEnd | ✅ | ✅ | ❌ | ❌ |
+
+---
+
+## Permission Granularity Mapping
+
+### OAC → Other Tools (Degradation)
+
+```
+OAC Granular Permission:
+{
+  allow: ["src/**/*.ts"],
+  deny: ["src/secrets/**"],
+  ask: ["package.json"]
+}
+
+↓ Maps to ↓
+
+Claude: tools.write = true (with warnings in skills)
+Cursor: Full write access (no granularity)
+Windsurf: Basic allow/deny (ask → deny)
+```
+
+---
+
+## Model ID Mapping
+
+| OAC Model ID | Claude Code | Cursor IDE | Windsurf |
+|--------------|-------------|------------|----------|
+| claude-sonnet-4 | claude-sonnet-4-20250514 | claude-sonnet-4 | claude-4-sonnet |
+| gpt-4 | N/A | gpt-4 | gpt-4 |
+| gpt-4-turbo | N/A | gpt-4-turbo | gpt-4-turbo |
+
+---
+
+## Configuration File Paths
+
+| Tool | Primary Config | Context/Skills | Agents |
+|------|----------------|----------------|--------|
+| **OAC** | .opencode/agent/ | .opencode/context/ | .opencode/agent/*.md |
+| **Claude** | .claude/config.json | .claude/skills/ | .claude/agents/ |
+| **Cursor** | .cursorrules | (inline) | Single file only |
+| **Windsurf** | .windsurf/config.json | .windsurf/context/ | .windsurf/agents/ |
+
+---
+
+## Conversion Compatibility
+
+### OAC → Claude Code
+- ✅ Full feature preservation
+- ⚠️ Temperature ignored (not supported)
+- ✅ Hooks preserved
+- ✅ Skills map 1:1
+
+### OAC → Cursor IDE
+- ⚠️ Multiple agents → merged single file
+- ❌ Hooks lost
+- ❌ Skills → inline context
+- ⚠️ Granular permissions → binary
+
+### OAC → Windsurf
+- ✅ Multiple agents preserved
+- ⚠️ Temperature → creativity setting
+- ❌ Hooks lost
+- ⚠️ Skills → partial mapping
+
+### Reverse Conversions
+- Claude → OAC: ✅ High fidelity
+- Cursor → OAC: ⚠️ Limited (single agent)
+- Windsurf → OAC: ⚠️ Partial feature loss
+
+---
+
+## Reference
+
+- **Implementation**: `packages/compatibility-layer/src/mappers/`
+- **Related**:
+  - concepts/compatibility-layer.md
+  - examples/baseadapter-pattern.md
+  - guides/compatibility-layer-workflow.md

.opencode/context/openagents-repo/navigation.md

@@ -2,7 +2,7 @@
 
 **Purpose**: Context files specific to the OpenAgents Control repository
 
-**Last Updated**: 2026-01-31
+**Last Updated**: 2026-02-04
 
 ---
 
@@ -11,11 +11,11 @@
 | Function | Files | Purpose |
 |----------|-------|---------|
 | **Standards** | 2 files | Agent creation standards |
-| **Concepts** | 2 files | Core ideas and principles |
-| **Examples** | 1 file | Working code samples |
-| **Guides** | 10 files | Step-by-step workflows |
-| **Lookup** | 4 files | Quick reference tables |
-| **Errors** | 1 file | Common issues + solutions |
+| **Concepts** | 6 files | Core ideas and principles |
+| **Examples** | 9 files | Working code samples |
+| **Guides** | 14 files | Step-by-step workflows |
+| **Lookup** | 11 files | Quick reference tables |
+| **Errors** | 2 files | Common issues + solutions |
 
 ---
 
@@ -34,9 +34,13 @@
 
 | File | Topic | Priority |
 |------|-------|----------|
+| `concepts/compatibility-layer.md` | Adapter pattern for AI coding tools | ⭐⭐⭐⭐⭐ |
 | `concepts/subagent-testing-modes.md` | Standalone vs delegation testing | ⭐⭐⭐⭐⭐ |
+| `concepts/hooks-system.md` | User-defined lifecycle commands | ⭐⭐⭐⭐ |
+| `concepts/agent-skills.md` | Skills that teach Claude tasks | ⭐⭐⭐⭐ |
+| `concepts/subagents-system.md` | Specialized AI assistants | ⭐⭐⭐⭐ |
 
-**When to read**: Before testing any subagent
+**When to read**: Before testing any subagent or working with tool adapters
 
 ---
 
@@ -44,9 +48,11 @@
 
 | File | Topic | Priority |
 |------|-------|----------|
+| `examples/baseadapter-pattern.md` | Template Method pattern for tool adapters | ⭐⭐⭐⭐⭐ |
+| `examples/zod-schema-migration.md` | Migrating TypeScript to Zod schemas | ⭐⭐⭐⭐ |
 | `examples/subagent-prompt-structure.md` | Optimized subagent prompt template | ⭐⭐⭐⭐ |
 
-**When to read**: When creating or optimizing subagent prompts
+**When to read**: When creating adapters, schemas, or optimizing subagent prompts
 
 ---
 
@@ -54,8 +60,13 @@
 
 | File | Topic | Priority |
 |------|-------|----------|
+| `guides/compatibility-layer-workflow.md` | Developing compatibility layer for AI tools | ⭐⭐⭐⭐⭐ |
 | `guides/testing-subagents.md` | How to test subagents standalone | ⭐⭐⭐⭐⭐ |
-| `guides/adding-agent.md` | How to add new agents | ⭐⭐⭐⭐ |
+| `guides/adding-agent-basics.md` | How to add new agents (basics) | ⭐⭐⭐⭐ |
+| `guides/adding-agent-testing.md` | How to add agent tests | ⭐⭐⭐⭐ |
+| `guides/adding-skill-basics.md` | How to add OpenCode skills | ⭐⭐⭐⭐ |
+| `guides/creating-skills.md` | How to create Claude Code skills | ⭐⭐⭐⭐ |
+| `guides/creating-subagents.md` | How to create Claude Code subagents | ⭐⭐⭐⭐ |
 | `guides/testing-agent.md` | How to test agents | ⭐⭐⭐⭐ |
 | `guides/external-libraries-workflow.md` | How to handle external library dependencies | ⭐⭐⭐⭐ |
 | `guides/github-issues-workflow.md` | How to work with GitHub issues and project board | ⭐⭐⭐⭐ |
@@ -73,11 +84,18 @@
 
 | File | Topic | Priority |
 |------|-------|----------|
+| `lookup/tool-feature-parity.md` | AI coding tool feature comparison | ⭐⭐⭐⭐⭐ |
+| `lookup/compatibility-layer-structure.md` | Compatibility package file structure | ⭐⭐⭐⭐⭐ |
 | `lookup/subagent-test-commands.md` | Subagent testing commands | ⭐⭐⭐⭐⭐ |
+| `lookup/hook-events.md` | All hook events reference | ⭐⭐⭐⭐ |
+| `lookup/skill-metadata.md` | SKILL.md frontmatter fields | ⭐⭐⭐⭐ |
+| `lookup/skills-comparison.md` | Skills vs other options | ⭐⭐⭐⭐ |
+| `lookup/builtin-subagents.md` | Default subagents (Explore, Plan) | ⭐⭐⭐⭐ |
+| `lookup/subagent-frontmatter.md` | Subagent configuration fields | ⭐⭐⭐⭐ |
 | `lookup/file-locations.md` | Where files are located | ⭐⭐⭐⭐ |
 | `lookup/commands.md` | Available slash commands | ⭐⭐⭐ |
 
-**When to read**: Quick command lookups
+**When to read**: Quick command lookups and feature comparisons
 
 ---
 
@@ -86,6 +104,7 @@
 | File | Topic | Priority |
 |------|-------|----------|
 | `errors/tool-permission-errors.md` | Tool permission issues | ⭐⭐⭐⭐⭐ |
+| `errors/skills-errors.md` | Skills not triggering/loading | ⭐⭐⭐⭐ |
 
 **When to read**: When tests fail with permission errors
 
@@ -116,7 +135,7 @@
 1. Load `standards/agent-frontmatter.md` (valid YAML frontmatter)
 2. Load `standards/subagent-structure.md` (file structure)
 3. Load `core-concepts/agents.md` (understand system)
-4. Load `guides/adding-agent.md` (step-by-step)
+4. Load `guides/adding-agent-basics.md` (step-by-step)
 5. **If using external libraries**: Load `guides/external-libraries-workflow.md` (fetch docs)
 6. Load `examples/subagent-prompt-structure.md` (if subagent)
 7. Load `guides/testing-agent.md` (validate)
@@ -153,7 +172,7 @@ All files follow MVI principle (<200 lines):
 - `../core/context-system/` - Context management system
 - `quick-start.md` - 2-minute repo orientation
 - `../content-creation/navigation.md` - Content creation principles
-- `../to-be-consumed/claude-code-docs/plugins.md` - Claude Code extension docs
+- `plugins/context/context-overview.md` - Plugin system context
 
 ---
 

.opencode/context/openagents-repo/plugins/context/concepts/plugin-architecture.md

@@ -0,0 +1,47 @@
+# Plugin Architecture
+
+**Purpose**: Extend Claude Code with slash commands, agents, Skills, hooks, and MCP servers
+
+---
+
+## Core Concept
+
+Plugins are directories containing a manifest (`.claude-plugin/plugin.json`) plus optional components (commands, agents, skills, hooks). They enable sharing functionality across projects and teams with namespaced commands.
+
+**Key Difference**:
+- **Standalone** (`.claude/`): Personal workflows, short names like `/hello`
+- **Plugins**: Shareable, versioned, namespaced like `/plugin-name:hello`
+
+---
+
+## Key Points
+
+- Plugin manifest at `.claude-plugin/plugin.json` defines identity (name, description, version)
+- Name field becomes namespace prefix for all slash commands
+- Components live at plugin root, NOT inside `.claude-plugin/`
+- Load with `--plugin-dir ./my-plugin` for testing
+- Multiple plugins can be loaded simultaneously
+
+---
+
+## Quick Example
+
+```json
+// .claude-plugin/plugin.json
+{
+  "name": "my-plugin",
+  "description": "A greeting plugin",
+  "version": "1.0.0",
+  "author": { "name": "Your Name" }
+}
+```
+
+---
+
+## Related
+
+- `../guides/creating-plugins.md` - How to create plugins
+- `../lookup/plugin-structure.md` - Directory structure
+- `../../guides/adding-skill.md` - Adding skills to plugins
+
+**Reference**: https://docs.anthropic.com/en/docs/claude-code/plugins

.opencode/context/openagents-repo/plugins/context/context-overview.md

@@ -20,6 +20,13 @@ Deep dives into specific plugin features.
 Guidelines and troubleshooting.
 - [Best Practices](./reference/best-practices.md): Message injection workarounds, security, and performance.
 
+### 🧩 Claude Code Plugins (External)
+Claude Code plugin system documentation (harvested from external docs).
+- [Concepts: Plugin Architecture](./concepts/plugin-architecture.md): Core concepts and structure
+- [Guides: Creating Plugins](./guides/creating-plugins.md): Step-by-step creation
+- [Guides: Migrating to Plugins](./guides/migrating-to-plugins.md): Convert standalone to plugin
+- [Lookup: Plugin Structure](./lookup/plugin-structure.md): Directory reference
+
 ## 🚀 How to use this library
 If you are asking an AI to build a new feature:
 1. **For a new tool**: Provide `architecture/overview.md` and `capabilities/tools.md`.

.opencode/context/openagents-repo/plugins/context/guides/creating-plugins.md

@@ -0,0 +1,61 @@
+# Creating Plugins
+
+**Purpose**: Step-by-step guide to create Claude Code plugins
+
+---
+
+## Quickstart Workflow
+
+1. **Create directory**: `mkdir my-plugin`
+2. **Create manifest**: `mkdir my-plugin/.claude-plugin`
+3. **Add plugin.json** with name, description, version
+4. **Add commands**: `mkdir my-plugin/commands` → add `.md` files
+5. **Test**: `claude --plugin-dir ./my-plugin`
+6. **Use**: `/my-plugin:command-name`
+
+---
+
+## Key Points
+
+- Filename becomes command name (e.g., `hello.md` → `/plugin:hello`)
+- Use `$ARGUMENTS` placeholder for user input
+- Use `$1`, `$2` for individual arguments
+- Restart Claude Code to pick up changes
+- Load multiple: `claude --plugin-dir ./one --plugin-dir ./two`
+
+---
+
+## Command File Format
+
+```markdown
+---
+description: Greet the user with a personalized message
+---
+
+# Hello Command
+
+Greet the user named "$ARGUMENTS" warmly.
+```
+
+---
+
+## Adding Components
+
+| Component | Location | Purpose |
+|-----------|----------|---------|
+| Commands | `commands/*.md` | Slash commands |
+| Agents | `agents/*.md` | Custom subagents |
+| Skills | `skills/*/SKILL.md` | Agent capabilities |
+| Hooks | `hooks/hooks.json` | Event handlers |
+| MCP | `.mcp.json` | External tools |
+| LSP | `.lsp.json` | Code intelligence |
+
+---
+
+## Related
+
+- `../concepts/plugin-architecture.md` - Architecture overview
+- `../lookup/plugin-structure.md` - Full directory structure
+- `./migrating-to-plugins.md` - Convert standalone to plugin
+
+**Reference**: https://docs.anthropic.com/en/docs/claude-code/plugins

.opencode/context/openagents-repo/plugins/context/guides/migrating-to-plugins.md

@@ -0,0 +1,65 @@
+# Migrating Standalone to Plugin
+
+**Purpose**: Convert `.claude/` configurations into shareable plugins
+
+---
+
+## Migration Steps
+
+1. **Create plugin structure**:
+   ```bash
+   mkdir -p my-plugin/.claude-plugin
+   ```
+
+2. **Create manifest** (`my-plugin/.claude-plugin/plugin.json`):
+   ```json
+   {
+     "name": "my-plugin",
+     "description": "Migrated from standalone",
+     "version": "1.0.0"
+   }
+   ```
+
+3. **Copy components**:
+   ```bash
+   cp -r .claude/commands my-plugin/
+   cp -r .claude/agents my-plugin/
+   cp -r .claude/skills my-plugin/
+   ```
+
+4. **Migrate hooks** (from `settings.json` to `hooks/hooks.json`):
+   ```bash
+   mkdir my-plugin/hooks
+   # Copy hooks object from settings.json
+   ```
+
+5. **Test**: `claude --plugin-dir ./my-plugin`
+
+---
+
+## What Changes
+
+| Standalone | Plugin |
+|------------|--------|
+| One project only | Shareable via marketplaces |
+| Files in `.claude/` | Files in `plugin-name/` |
+| Hooks in `settings.json` | Hooks in `hooks/hooks.json` |
+| Manual copy to share | Install with `/plugin install` |
+
+---
+
+## Key Points
+
+- Plugin commands are namespaced (`/plugin:cmd` vs `/cmd`)
+- Hook format is identical between settings.json and hooks.json
+- Remove original `.claude/` files after verifying migration
+- Plugin version takes precedence when loaded
+
+---
+
+## Related
+
+- `../lookup/plugin-structure.md` - Directory structure
+- `../concepts/plugin-architecture.md` - Architecture
+
+**Reference**: https://docs.anthropic.com/en/docs/claude-code/plugins

.opencode/context/openagents-repo/plugins/context/lookup/plugin-structure.md

@@ -0,0 +1,62 @@
+# Plugin Directory Structure
+
+**Purpose**: Quick reference for plugin file organization
+
+---
+
+## Standard Layout
+
+```
+my-plugin/
+├── .claude-plugin/          # REQUIRED - manifest only
+│   └── plugin.json          # Plugin identity
+│
+├── commands/                # Slash commands as .md files
+│   └── hello.md
+│
+├── agents/                  # Custom subagent definitions
+│   └── reviewer.md
+│
+├── skills/                  # Agent Skills
+│   └── code-review/
+│       └── SKILL.md
+│
+├── hooks/                   # Event handlers
+│   └── hooks.json
+│
+├── .mcp.json               # MCP server configs
+└── .lsp.json               # LSP server configs
+```
+
+---
+
+## Critical Rules
+
+- Only `plugin.json` goes inside `.claude-plugin/`
+- All other directories at plugin root level
+- Never put commands/, agents/, skills/ inside .claude-plugin/
+
+---
+
+## Manifest Schema
+
+```json
+{
+  "name": "plugin-name",        // Required: namespace prefix
+  "description": "What it does", // Required: shown in manager
+  "version": "1.0.0",           // Required: semver
+  "author": { "name": "You" },  // Optional
+  "homepage": "https://...",    // Optional
+  "repository": "https://...",  // Optional
+  "license": "MIT"              // Optional
+}
+```
+
+---
+
+## Related
+
+- `../concepts/plugin-architecture.md` - Architecture
+- `../guides/creating-plugins.md` - Creation guide
+
+**Reference**: https://docs.anthropic.com/en/docs/claude-code/plugins-reference

.opencode/context/to-be-consumed/claude-code-docs/agent-skills.md

@@ -1,565 +0,0 @@
-# Agent Skills
-
-> Create, manage, and share Skills to extend Claude's capabilities in Claude Code.
-
-This guide shows you how to create, use, and manage Agent Skills in Claude Code. For background on how Skills work across Claude products, see [What are Skills?](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview).
-
-A Skill is a markdown file that teaches Claude how to do something specific: reviewing PRs using your team's standards, generating commit messages in your preferred format, or querying your company's database schema. When you ask Claude something that matches a Skill's purpose, Claude automatically applies it.
-
-## Create your first Skill
-
-This example creates a personal Skill that teaches Claude to explain code using visual diagrams and analogies. Unlike Claude's default explanations, this Skill ensures every explanation includes an ASCII diagram and a real-world analogy.
-
-<Steps>
-  <Step title="Check available Skills">
-    Before creating a Skill, see what Skills Claude already has access to:
-
-    ```
-    What Skills are available?
-    ```
-
-    Claude will list any Skills currently loaded. You may see none, or you may see Skills from plugins or your organization.
-  </Step>
-
-  <Step title="Create the Skill directory">
-    Create a directory for the Skill in your personal Skills folder. Personal Skills are available across all your projects. (You can also create [project Skills](#where-skills-live) in `.claude/skills/` to share with your team.)
-
-    ```bash  theme={null}
-    mkdir -p ~/.claude/skills/explaining-code
-    ```
-  </Step>
-
-  <Step title="Write SKILL.md">
-    Every Skill needs a `SKILL.md` file. The file starts with YAML metadata between `---` markers and must include a `name` and `description`, followed by Markdown instructions that Claude follows when the Skill is active.
-
-    The `description` is especially important, because Claude uses it to decide when to apply the Skill.
-
-    Create `~/.claude/skills/explaining-code/SKILL.md`:
-
-    ```yaml  theme={null}
-    ---
-    name: explaining-code
-    description: Explains code with visual diagrams and analogies. Use when explaining how code works, teaching about a codebase, or when the user asks "how does this work?"
-    ---
-
-    When explaining code, always include:
-
-    1. **Start with an analogy**: Compare the code to something from everyday life
-    2. **Draw a diagram**: Use ASCII art to show the flow, structure, or relationships
-    3. **Walk through the code**: Explain step-by-step what happens
-    4. **Highlight a gotcha**: What's a common mistake or misconception?
-
-    Keep explanations conversational. For complex concepts, use multiple analogies.
-    ```
-  </Step>
-
-  <Step title="Load and verify the Skill">
-    Skills are automatically loaded when created or modified. Verify the Skill appears in the list:
-
-    ```
-    What Skills are available?
-    ```
-
-    You should see `explaining-code` in the list with its description.
-  </Step>
-
-  <Step title="Test the Skill">
-    Open any file in your project and ask Claude a question that matches the Skill's description:
-
-    ```
-    How does this code work?
-    ```
-
-    Claude should ask to use the `explaining-code` Skill, then include an analogy and ASCII diagram in its explanation. If the Skill doesn't trigger, try rephrasing to include more keywords from the description, like "explain how this works."
-  </Step>
-</Steps>
-
-The rest of this guide covers how Skills work, configuration options, and troubleshooting.
-
-## How Skills work
-
-Skills are **model-invoked**: Claude decides which Skills to use based on your request. You don't need to explicitly call a Skill. Claude automatically applies relevant Skills when your request matches their description.
-
-When you send a request, Claude follows these steps to find and use relevant Skills:
-
-<Steps>
-  <Step title="Discovery">
-    At startup, Claude loads only the name and description of each available Skill. This keeps startup fast while giving Claude enough context to know when each Skill might be relevant.
-  </Step>
-
-  <Step title="Activation">
-    When your request matches a Skill's description, Claude asks to use the Skill. You'll see a confirmation prompt before the full `SKILL.md` is loaded into context. Since Claude reads these descriptions to find relevant Skills, [write descriptions](#skill-not-triggering) that include keywords users would naturally say.
-  </Step>
-
-  <Step title="Execution">
-    Claude follows the Skill's instructions, loading referenced files or running bundled scripts as needed.
-  </Step>
-</Steps>
-
-### Where Skills live
-
-Where you store a Skill determines who can use it:
-
-| Location   | Path                                             | Applies to                        |
-| :--------- | :----------------------------------------------- | :-------------------------------- |
-| Enterprise | See [managed settings](/en/iam#managed-settings) | All users in your organization    |
-| Personal   | `~/.claude/skills/`                              | You, across all projects          |
-| Project    | `.claude/skills/`                                | Anyone working in this repository |
-| Plugin     | Bundled with [plugins](/en/plugins)              | Anyone with the plugin installed  |
-
-If two Skills have the same name, the higher row wins: managed overrides personal, personal overrides project, and project overrides plugin.
-
-### When to use Skills versus other options
-
-Claude Code offers several ways to customize behavior. The key difference: **Skills are triggered automatically by Claude** based on your request, while slash commands require you to type `/command` explicitly.
-
-| Use this                                 | When you want to...                                                        | When it runs                               |
-| :--------------------------------------- | :------------------------------------------------------------------------- | :----------------------------------------- |
-| **Skills**                               | Give Claude specialized knowledge (e.g., "review PRs using our standards") | Claude chooses when relevant               |
-| **[Slash commands](/en/slash-commands)** | Create reusable prompts (e.g., `/deploy staging`)                          | You type `/command` to run it              |
-| **[CLAUDE.md](/en/memory)**              | Set project-wide instructions (e.g., "use TypeScript strict mode")         | Loaded into every conversation             |
-| **[Subagents](/en/sub-agents)**          | Delegate tasks to a separate context with its own tools                    | Claude delegates, or you invoke explicitly |
-| **[Hooks](/en/hooks)**                   | Run scripts on events (e.g., lint on file save)                            | Fires on specific tool events              |
-| **[MCP servers](/en/mcp)**               | Connect Claude to external tools and data sources                          | Claude calls MCP tools as needed           |
-
-**Skills vs. subagents**: Skills add knowledge to the current conversation. Subagents run in a separate context with their own tools. Use Skills for guidance and standards; use subagents when you need isolation or different tool access.
-
-**Skills vs. MCP**: Skills tell Claude *how* to use tools; MCP *provides* the tools. For example, an MCP server connects Claude to your database, while a Skill teaches Claude your data model and query patterns.
-
-<Note>
-  For a deep dive into the architecture and real-world applications of Agent Skills, read [Equipping agents for the real world with Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills).
-</Note>
-
-## Configure Skills
-
-This section covers Skill file structure, supporting files, tool restrictions, and distribution options.
-
-### Write SKILL.md
-
-The `SKILL.md` file is the only required file in a Skill. It has two parts: YAML metadata (the section between `---` markers) at the top, and Markdown instructions that tell Claude how to use the Skill:
-
-```yaml  theme={null}
----
-name: your-skill-name
-description: Brief description of what this Skill does and when to use it
----
-
-# Your Skill Name
-
-## Instructions
-Provide clear, step-by-step guidance for Claude.
-
-## Examples
-Show concrete examples of using this Skill.
-```
-
-#### Available metadata fields
-
-You can use the following fields in the YAML frontmatter:
-
-| Field            | Required | Description                                                                                                                                                                                                                                                                                       |
-| :--------------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `name`           | Yes      | Skill name. Must use lowercase letters, numbers, and hyphens only (max 64 characters). Should match the directory name.                                                                                                                                                                           |
-| `description`    | Yes      | What the Skill does and when to use it (max 1024 characters). Claude uses this to decide when to apply the Skill.                                                                                                                                                                                 |
-| `allowed-tools`  | No       | Tools Claude can use without asking permission when this Skill is active. Supports comma-separated values or YAML-style lists. See [Restrict tool access](#restrict-tool-access-with-allowed-tools).                                                                                              |
-| `model`          | No       | [Model](https://docs.claude.com/en/docs/about-claude/models/overview) to use when this Skill is active (e.g., `claude-sonnet-4-20250514`). Defaults to the conversation's model.                                                                                                                  |
-| `context`        | No       | Set to `fork` to run the Skill in a forked sub-agent context with its own conversation history.                                                                                                                                                                                                   |
-| `agent`          | No       | Specify which [agent type](/en/sub-agents#built-in-subagents) to use when `context: fork` is set (e.g., `Explore`, `Plan`, `general-purpose`, or a custom agent name from `.claude/agents/`). Defaults to `general-purpose` if not specified. Only applicable when combined with `context: fork`. |
-| `hooks`          | No       | Define hooks scoped to this Skill's lifecycle. Supports `PreToolUse`, `PostToolUse`, and `Stop` events.                                                                                                                                                                                           |
-| `user-invocable` | No       | Controls whether the Skill appears in the slash command menu. Does not affect the [`Skill` tool](/en/slash-commands#skill-tool) or automatic discovery. Defaults to `true`. See [Control Skill visibility](#control-skill-visibility).                                                            |
-
-See the [best practices guide](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/best-practices) for complete authoring guidance including validation rules.
-
-### Update or delete a Skill
-
-To update a Skill, edit its `SKILL.md` file directly. To remove a Skill, delete its directory. Changes take effect immediately.
-
-### Add supporting files with progressive disclosure
-
-Skills share Claude's context window with conversation history, other Skills, and your request. To keep context focused, use **progressive disclosure**: put essential information in `SKILL.md` and detailed reference material in separate files that Claude reads only when needed.
-
-This approach lets you bundle comprehensive documentation, examples, and scripts without consuming context upfront. Claude loads additional files only when the task requires them.
-
-<Tip>Keep `SKILL.md` under 500 lines for optimal performance. If your content exceeds this, split detailed reference material into separate files.</Tip>
-
-#### Example: multi-file Skill structure
-
-Claude discovers supporting files through links in your `SKILL.md`. The following example shows a Skill with detailed documentation in separate files and utility scripts that Claude can execute without reading:
-
-```
-my-skill/
-├── SKILL.md (required - overview and navigation)
-├── reference.md (detailed API docs - loaded when needed)
-├── examples.md (usage examples - loaded when needed)
-└── scripts/
-    └── helper.py (utility script - executed, not loaded)
-```
-
-The `SKILL.md` file references these supporting files so Claude knows they exist:
-
-````markdown  theme={null}
-## Overview
-
-[Essential instructions here]
-
-## Additional resources
-
-- For complete API details, see [reference.md](reference.md)
-- For usage examples, see [examples.md](examples.md)
-
-## Utility scripts
-
-To validate input files, run the helper script. It checks for required fields and returns any validation errors:
-```bash
-python scripts/helper.py input.txt
-```
-````
-
-<Tip>Keep references one level deep. Link directly from `SKILL.md` to reference files. Deeply nested references (file A links to file B which links to file C) may result in Claude partially reading files.</Tip>
-
-**Bundle utility scripts for zero-context execution.** Scripts in your Skill directory can be executed without loading their contents into context. Claude runs the script and only the output consumes tokens. This is useful for:
-
-* Complex validation logic that would be verbose to describe in prose
-* Data processing that's more reliable as tested code than generated code
-* Operations that benefit from consistency across uses
-
-In `SKILL.md`, tell Claude to run the script rather than read it:
-
-```markdown  theme={null}
-Run the validation script to check the form:
-python scripts/validate_form.py input.pdf
-```
-
-For complete guidance on structuring Skills, see the [best practices guide](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/best-practices#progressive-disclosure-patterns).
-
-### Restrict tool access with allowed-tools
-
-Use the `allowed-tools` frontmatter field to limit which tools Claude can use when a Skill is active. You can specify tools as a comma-separated string or a YAML list:
-
-```yaml  theme={null}
----
-name: reading-files-safely
-description: Read files without making changes. Use when you need read-only file access.
-allowed-tools: Read, Grep, Glob
----
-```
-
-Or use YAML-style lists for better readability:
-
-```yaml  theme={null}
----
-name: reading-files-safely
-description: Read files without making changes. Use when you need read-only file access.
-allowed-tools:
-  - Read
-  - Grep
-  - Glob
----
-```
-
-When this Skill is active, Claude can only use the specified tools (Read, Grep, Glob) without needing to ask for permission. This is useful for:
-
-* Read-only Skills that shouldn't modify files
-* Skills with limited scope: for example, only data analysis, no file writing
-* Security-sensitive workflows where you want to restrict capabilities
-
-If `allowed-tools` is omitted, the Skill doesn't restrict tools. Claude uses its standard permission model and may ask you to approve tool usage.
-
-<Note>
-  `allowed-tools` is only supported for Skills in Claude Code.
-</Note>
-
-### Run Skills in a forked context
-
-Use `context: fork` to run a Skill in an isolated sub-agent context with its own conversation history. This is useful for Skills that perform complex multi-step operations without cluttering the main conversation:
-
-```yaml  theme={null}
----
-name: code-analysis
-description: Analyze code quality and generate detailed reports
-context: fork
----
-```
-
-### Define hooks for Skills
-
-Skills can define hooks that run during the Skill's lifecycle. Use the `hooks` field to specify `PreToolUse`, `PostToolUse`, or `Stop` handlers:
-
-```yaml  theme={null}
----
-name: secure-operations
-description: Perform operations with additional security checks
-hooks:
-  PreToolUse:
-    - matcher: "Bash"
-      hooks:
-        - type: command
-          command: "./scripts/security-check.sh $TOOL_INPUT"
-          once: true
----
-```
-
-The `once: true` option runs the hook only once per session. After the first successful execution, the hook is removed.
-
-Hooks defined in a Skill are scoped to that Skill's execution and are automatically cleaned up when the Skill finishes.
-
-See [Hooks](/en/hooks) for the complete hook configuration format.
-
-### Control Skill visibility
-
-Skills can be invoked in three ways:
-
-1. **Manual invocation**: You type `/skill-name` in the prompt
-2. **Programmatic invocation**: Claude calls it via the [`Skill` tool](/en/slash-commands#skill-tool)
-3. **Automatic discovery**: Claude reads the Skill's description and loads it when relevant to the conversation
-
-The `user-invocable` field controls only manual invocation. When set to `false`, the Skill is hidden from the slash command menu but Claude can still invoke it programmatically or discover it automatically.
-
-To block programmatic invocation via the `Skill` tool, use `disable-model-invocation: true` instead.
-
-#### When to use each setting
-
-| Setting                          | Slash menu | `Skill` tool | Auto-discovery | Use case                                                        |
-| :------------------------------- | :--------- | :----------- | :------------- | :-------------------------------------------------------------- |
-| `user-invocable: true` (default) | Visible    | Allowed      | Yes            | Skills you want users to invoke directly                        |
-| `user-invocable: false`          | Hidden     | Allowed      | Yes            | Skills that Claude can use but users shouldn't invoke manually  |
-| `disable-model-invocation: true` | Visible    | Blocked      | Yes            | Skills you want users to invoke but not Claude programmatically |
-
-#### Example: model-only Skill
-
-Set `user-invocable: false` to hide a Skill from the slash menu while still allowing Claude to invoke it programmatically:
-
-```yaml  theme={null}
----
-name: internal-review-standards
-description: Apply internal code review standards when reviewing pull requests
-user-invocable: false
----
-```
-
-With this setting, users won't see the Skill in the `/` menu, but Claude can still invoke it via the `Skill` tool or discover it automatically based on context.
-
-### Skills and subagents
-
-There are two ways Skills and subagents can work together:
-
-#### Give a subagent access to Skills
-
-[Subagents](/en/sub-agents) do not automatically inherit Skills from the main conversation. To give a custom subagent access to specific Skills, list them in the subagent's `skills` field:
-
-```yaml  theme={null}
-# .claude/agents/code-reviewer.md
----
-name: code-reviewer
-description: Review code for quality and best practices
-skills: pr-review, security-check
----
-```
-
-The full content of each listed Skill is injected into the subagent's context at startup, not just made available for invocation. If the `skills` field is omitted, no Skills are loaded for that subagent.
-
-<Note>
-  Built-in agents (Explore, Plan, general-purpose) do not have access to your Skills. Only custom subagents you define in `.claude/agents/` with an explicit `skills` field can use Skills.
-</Note>
-
-#### Run a Skill in a subagent context
-
-Use `context: fork` and `agent` to run a Skill in a forked subagent with its own separate context. See [Run Skills in a forked context](#run-skills-in-a-forked-context) for details.
-
-### Distribute Skills
-
-You can share Skills in several ways:
-
-* **Project Skills**: Commit `.claude/skills/` to version control. Anyone who clones the repository gets the Skills.
-* **Plugins**: To share Skills across multiple repositories, create a `skills/` directory in your [plugin](/en/plugins) with Skill folders containing `SKILL.md` files. Distribute through a [plugin marketplace](/en/plugin-marketplaces).
-* **Managed**: Administrators can deploy Skills organization-wide through [managed settings](/en/iam#managed-settings). See [Where Skills live](#where-skills-live) for managed Skill paths.
-
-## Examples
-
-These examples show common Skill patterns, from minimal single-file Skills to multi-file Skills with supporting documentation and scripts.
-
-### Simple Skill (single file)
-
-A minimal Skill needs only a `SKILL.md` file with frontmatter and instructions. This example helps Claude generate commit messages by examining staged changes:
-
-```
-commit-helper/
-└── SKILL.md
-```
-
-```yaml  theme={null}
----
-name: generating-commit-messages
-description: Generates clear commit messages from git diffs. Use when writing commit messages or reviewing staged changes.
----
-
-# Generating Commit Messages
-
-## Instructions
-
-1. Run `git diff --staged` to see changes
-2. I'll suggest a commit message with:
-   - Summary under 50 characters
-   - Detailed description
-   - Affected components
-
-## Best practices
-
-- Use present tense
-- Explain what and why, not how
-```
-
-### Use multiple files
-
-For complex Skills, use progressive disclosure to keep the main `SKILL.md` focused while providing detailed documentation in supporting files. This PDF processing Skill includes reference docs, utility scripts, and uses `allowed-tools` to restrict Claude to specific tools:
-
-```
-pdf-processing/
-├── SKILL.md              # Overview and quick start
-├── FORMS.md              # Form field mappings and filling instructions
-├── REFERENCE.md          # API details for pypdf and pdfplumber
-└── scripts/
-    ├── fill_form.py      # Utility to populate form fields
-    └── validate.py       # Checks PDFs for required fields
-```
-
-**`SKILL.md`**:
-
-````yaml  theme={null}
----
-name: pdf-processing
-description: Extract text, fill forms, merge PDFs. Use when working with PDF files, forms, or document extraction. Requires pypdf and pdfplumber packages.
-allowed-tools: Read, Bash(python:*)
----
-
-# PDF Processing
-
-## Quick start
-
-Extract text:
-```python
-import pdfplumber
-with pdfplumber.open("doc.pdf") as pdf:
-    text = pdf.pages[0].extract_text()
-```
-
-For form filling, see [FORMS.md](FORMS.md).
-For detailed API reference, see [REFERENCE.md](REFERENCE.md).
-
-## Requirements
-
-Packages must be installed in your environment:
-```bash
-pip install pypdf pdfplumber
-```
-````
-
-<Note>
-  If your Skill requires external packages, list them in the description. Packages must be installed in your environment before Claude can use them.
-</Note>
-
-## Troubleshooting
-
-### View and test Skills
-
-To see which Skills Claude has access to, ask Claude a question like "What Skills are available?" Claude loads all available Skill names and descriptions into the context window when a conversation starts, so it can list the Skills it currently has access to.
-
-To test a specific Skill, ask Claude to do a task that matches the Skill's description. For example, if your Skill has the description "Reviews pull requests for code quality", ask Claude to "Review the changes in my current branch." Claude automatically uses the Skill when the request matches its description.
-
-### Skill not triggering
-
-The description field is how Claude decides whether to use your Skill. Vague descriptions like "Helps with documents" don't give Claude enough information to match your Skill to relevant requests.
-
-A good description answers two questions:
-
-1. **What does this Skill do?** List the specific capabilities.
-2. **When should Claude use it?** Include trigger terms users would mention.
-
-```yaml  theme={null}
-description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
-```
-
-This description works because it names specific actions (extract, fill, merge) and includes keywords users would say (PDF, forms, document extraction).
-
-### Skill doesn't load
-
-**Check the file path.** Skills must be in the correct directory with the exact filename `SKILL.md` (case-sensitive):
-
-| Type       | Path                                                                    |
-| :--------- | :---------------------------------------------------------------------- |
-| Personal   | `~/.claude/skills/my-skill/SKILL.md`                                    |
-| Project    | `.claude/skills/my-skill/SKILL.md`                                      |
-| Enterprise | See [Where Skills live](#where-skills-live) for platform-specific paths |
-| Plugin     | `skills/my-skill/SKILL.md` inside the plugin directory                  |
-
-**Check the YAML syntax.** Invalid YAML in the frontmatter prevents the Skill from loading. The frontmatter must start with `---` on line 1 (no blank lines before it), end with `---` before the Markdown content, and use spaces for indentation (not tabs).
-
-**Run debug mode.** Use `claude --debug` to see Skill loading errors.
-
-### Skill has errors
-
-**Check dependencies are installed.** If your Skill uses external packages, they must be installed in your environment before Claude can use them.
-
-**Check script permissions.** Scripts need execute permissions: `chmod +x scripts/*.py`
-
-**Check file paths.** Use forward slashes (Unix style) in all paths. Use `scripts/helper.py`, not `scripts\helper.py`.
-
-### Multiple Skills conflict
-
-If Claude uses the wrong Skill or seems confused between similar Skills, the descriptions are probably too similar. Make each description distinct by using specific trigger terms.
-
-For example, instead of two Skills with "data analysis" in both descriptions, differentiate them: one for "sales data in Excel files and CRM exports" and another for "log files and system metrics". The more specific your trigger terms, the easier it is for Claude to match the right Skill to your request.
-
-### Plugin Skills not appearing
-
-**Symptom**: You installed a plugin from a marketplace, but its Skills don't appear when you ask Claude "What Skills are available?"
-
-**Solution**: Clear the plugin cache and reinstall:
-
-```bash  theme={null}
-rm -rf ~/.claude/plugins/cache
-```
-
-Then restart Claude Code and reinstall the plugin:
-
-```shell  theme={null}
-/plugin install plugin-name@marketplace-name
-```
-
-This forces Claude Code to re-download and re-register the plugin's Skills.
-
-**If Skills still don't appear**, verify the plugin's directory structure is correct. Skills must be in a `skills/` directory at the plugin root:
-
-```
-my-plugin/
-├── .claude-plugin/
-│   └── plugin.json
-└── skills/
-    └── my-skill/
-        └── SKILL.md
-```
-
-## Next steps
-
-<CardGroup cols={2}>
-  <Card title="Authoring best practices" icon="lightbulb" href="https://docs.claude.com/en/docs/agents-and-tools/agent-skills/best-practices">
-    Write Skills that Claude can use effectively
-  </Card>
-
-  <Card title="Agent Skills overview" icon="book" href="https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview">
-    Learn how Skills work across Claude products
-  </Card>
-
-  <Card title="Use Skills in the Agent SDK" icon="cube" href="https://docs.claude.com/en/docs/agent-sdk/skills">
-    Use Skills programmatically with TypeScript and Python
-  </Card>
-
-  <Card title="Get started with Agent Skills" icon="rocket" href="https://docs.claude.com/en/docs/agents-and-tools/agent-skills/quickstart">
-    Create your first Skill
-  </Card>
-</CardGroup>
-
-
----
-
-> To find navigation and other pages in this documentation, fetch the llms.txt file at: https://code.claude.com/docs/llms.txt

.opencode/context/to-be-consumed/claude-code-docs/create-subagents.md

@@ -1,716 +0,0 @@
-# Create custom subagents
-
-> Create and use specialized AI subagents in Claude Code for task-specific workflows and improved context management.
-
-Subagents are specialized AI assistants that handle specific types of tasks. Each subagent runs in its own context window with a custom system prompt, specific tool access, and independent permissions. When Claude encounters a task that matches a subagent's description, it delegates to that subagent, which works independently and returns results.
-
-Subagents help you:
-
-* **Preserve context** by keeping exploration and implementation out of your main conversation
-* **Enforce constraints** by limiting which tools a subagent can use
-* **Reuse configurations** across projects with user-level subagents
-* **Specialize behavior** with focused system prompts for specific domains
-* **Control costs** by routing tasks to faster, cheaper models like Haiku
-
-Claude uses each subagent's description to decide when to delegate tasks. When you create a subagent, write a clear description so Claude knows when to use it.
-
-Claude Code includes several built-in subagents like **Explore**, **Plan**, and **general-purpose**. You can also create custom subagents to handle specific tasks. This page covers the [built-in subagents](#built-in-subagents), [how to create your own](#quickstart-create-your-first-subagent), [full configuration options](#configure-subagents), [patterns for working with subagents](#work-with-subagents), and [example subagents](#example-subagents).
-
-## Built-in subagents
-
-Claude Code includes built-in subagents that Claude automatically uses when appropriate. Each inherits the parent conversation's permissions with additional tool restrictions.
-
-<Tabs>
-  <Tab title="Explore">
-    A fast, read-only agent optimized for searching and analyzing codebases.
-
-    * **Model**: Haiku (fast, low-latency)
-    * **Tools**: Read-only tools (denied access to Write and Edit tools)
-    * **Purpose**: File discovery, code search, codebase exploration
-
-    Claude delegates to Explore when it needs to search or understand a codebase without making changes. This keeps exploration results out of your main conversation context.
-
-    When invoking Explore, Claude specifies a thoroughness level: **quick** for targeted lookups, **medium** for balanced exploration, or **very thorough** for comprehensive analysis.
-  </Tab>
-
-  <Tab title="Plan">
-    A research agent used during [plan mode](/en/common-workflows#use-plan-mode-for-safe-code-analysis) to gather context before presenting a plan.
-
-    * **Model**: Inherits from main conversation
-    * **Tools**: Read-only tools (denied access to Write and Edit tools)
-    * **Purpose**: Codebase research for planning
-
-    When you're in plan mode and Claude needs to understand your codebase, it delegates research to the Plan subagent. This prevents infinite nesting (subagents cannot spawn other subagents) while still gathering necessary context.
-  </Tab>
-
-  <Tab title="General-purpose">
-    A capable agent for complex, multi-step tasks that require both exploration and action.
-
-    * **Model**: Inherits from main conversation
-    * **Tools**: All tools
-    * **Purpose**: Complex research, multi-step operations, code modifications
-
-    Claude delegates to general-purpose when the task requires both exploration and modification, complex reasoning to interpret results, or multiple dependent steps.
-  </Tab>
-
-  <Tab title="Other">
-    Claude Code includes additional helper agents for specific tasks. These are typically invoked automatically, so you don't need to use them directly.
-
-    | Agent             | Model    | When Claude uses it                                      |
-    | :---------------- | :------- | :------------------------------------------------------- |
-    | Bash              | Inherits | Running terminal commands in a separate context          |
-    | statusline-setup  | Sonnet   | When you run `/statusline` to configure your status line |
-    | Claude Code Guide | Haiku    | When you ask questions about Claude Code features        |
-  </Tab>
-</Tabs>
-
-Beyond these built-in subagents, you can create your own with custom prompts, tool restrictions, permission modes, hooks, and skills. The following sections show how to get started and customize subagents.
-
-## Quickstart: create your first subagent
-
-Subagents are defined in Markdown files with YAML frontmatter. You can [create them manually](#write-subagent-files) or use the `/agents` slash command.
-
-This walkthrough guides you through creating a user-level subagent with the `/agent` command. The subagent reviews code and suggests improvements for the codebase.
-
-<Steps>
-  <Step title="Open the subagents interface">
-    In Claude Code, run:
-
-    ```
-    /agents
-    ```
-  </Step>
-
-  <Step title="Create a new user-level agent">
-    Select **Create new agent**, then choose **User-level**. This saves the subagent to `~/.claude/agents/` so it's available in all your projects.
-  </Step>
-
-  <Step title="Generate with Claude">
-    Select **Generate with Claude**. When prompted, describe the subagent:
-
-    ```
-    A code improvement agent that scans files and suggests improvements
-    for readability, performance, and best practices. It should explain
-    each issue, show the current code, and provide an improved version.
-    ```
-
-    Claude generates the system prompt and configuration. Press `e` to open it in your editor if you want to customize it.
-  </Step>
-
-  <Step title="Select tools">
-    For a read-only reviewer, deselect everything except **Read-only tools**. If you keep all tools selected, the subagent inherits all tools available to the main conversation.
-  </Step>
-
-  <Step title="Select model">
-    Choose which model the subagent uses. For this example agent, select **Sonnet**, which balances capability and speed for analyzing code patterns.
-  </Step>
-
-  <Step title="Choose a color">
-    Pick a background color for the subagent. This helps you identify which subagent is running in the UI.
-  </Step>
-
-  <Step title="Save and try it out">
-    Save the subagent. It's available immediately (no restart needed). Try it:
-
-    ```
-    Use the code-improver agent to suggest improvements in this project
-    ```
-
-    Claude delegates to your new subagent, which scans the codebase and returns improvement suggestions.
-  </Step>
-</Steps>
-
-You now have a subagent you can use in any project on your machine to analyze codebases and suggest improvements.
-
-You can also create subagents manually as Markdown files, define them via CLI flags, or distribute them through plugins. The following sections cover all configuration options.
-
-## Configure subagents
-
-### Use the /agents command
-
-The `/agents` command provides an interactive interface for managing subagents. Run `/agents` to:
-
-* View all available subagents (built-in, user, project, and plugin)
-* Create new subagents with guided setup or Claude generation
-* Edit existing subagent configuration and tool access
-* Delete custom subagents
-* See which subagents are active when duplicates exist
-
-This is the recommended way to create and manage subagents. For manual creation or automation, you can also add subagent files directly.
-
-### Choose the subagent scope
-
-Subagents are Markdown files with YAML frontmatter. Store them in different locations depending on scope. When multiple subagents share the same name, the higher-priority location wins.
-
-| Location                     | Scope                   | Priority    | How to create                         |
-| :--------------------------- | :---------------------- | :---------- | :------------------------------------ |
-| `--agents` CLI flag          | Current session         | 1 (highest) | Pass JSON when launching Claude Code  |
-| `.claude/agents/`            | Current project         | 2           | Interactive or manual                 |
-| `~/.claude/agents/`          | All your projects       | 3           | Interactive or manual                 |
-| Plugin's `agents/` directory | Where plugin is enabled | 4 (lowest)  | Installed with [plugins](/en/plugins) |
-
-**Project subagents** (`.claude/agents/`) are ideal for subagents specific to a codebase. Check them into version control so your team can use and improve them collaboratively.
-
-**User subagents** (`~/.claude/agents/`) are personal subagents available in all your projects.
-
-**CLI-defined subagents** are passed as JSON when launching Claude Code. They exist only for that session and aren't saved to disk, making them useful for quick testing or automation scripts:
-
-```bash  theme={null}
-claude --agents '{
-  "code-reviewer": {
-    "description": "Expert code reviewer. Use proactively after code changes.",
-    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
-    "tools": ["Read", "Grep", "Glob", "Bash"],
-    "model": "sonnet"
-  }
-}'
-```
-
-The `--agents` flag accepts JSON with the same fields as [frontmatter](#supported-frontmatter-fields). Use `prompt` for the system prompt (equivalent to the markdown body in file-based subagents). See the [CLI reference](/en/cli-reference#agents-flag-format) for the full JSON format.
-
-**Plugin subagents** come from [plugins](/en/plugins) you've installed. They appear in `/agents` alongside your custom subagents. See the [plugin components reference](/en/plugins-reference#agents) for details on creating plugin subagents.
-
-### Write subagent files
-
-Subagent files use YAML frontmatter for configuration, followed by the system prompt in Markdown:
-
-<Note>
-  Subagents are loaded at session start. If you create a subagent by manually adding a file, restart your session or use `/agents` to load it immediately.
-</Note>
-
-```markdown  theme={null}
----
-name: code-reviewer
-description: Reviews code for quality and best practices
-tools: Read, Glob, Grep
-model: sonnet
----
-
-You are a code reviewer. When invoked, analyze the code and provide
-specific, actionable feedback on quality, security, and best practices.
-```
-
-The frontmatter defines the subagent's metadata and configuration. The body becomes the system prompt that guides the subagent's behavior. Subagents receive only this system prompt (plus basic environment details like working directory), not the full Claude Code system prompt.
-
-#### Supported frontmatter fields
-
-The following fields can be used in the YAML frontmatter. Only `name` and `description` are required.
-
-| Field             | Required | Description                                                                                                                                                                                                  |
-| :---------------- | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `name`            | Yes      | Unique identifier using lowercase letters and hyphens                                                                                                                                                        |
-| `description`     | Yes      | When Claude should delegate to this subagent                                                                                                                                                                 |
-| `tools`           | No       | [Tools](#available-tools) the subagent can use. Inherits all tools if omitted                                                                                                                                |
-| `disallowedTools` | No       | Tools to deny, removed from inherited or specified list                                                                                                                                                      |
-| `model`           | No       | [Model](#choose-a-model) to use: `sonnet`, `opus`, `haiku`, or `inherit`. Defaults to `sonnet`                                                                                                               |
-| `permissionMode`  | No       | [Permission mode](#permission-modes): `default`, `acceptEdits`, `dontAsk`, `bypassPermissions`, or `plan`                                                                                                    |
-| `skills`          | No       | [Skills](/en/skills) to load into the subagent's context at startup. The full skill content is injected, not just made available for invocation. Subagents don't inherit skills from the parent conversation |
-| `hooks`           | No       | [Lifecycle hooks](#define-hooks-for-subagents) scoped to this subagent                                                                                                                                       |
-
-### Choose a model
-
-The `model` field controls which [AI model](/en/model-config) the subagent uses:
-
-* **Model alias**: Use one of the available aliases: `sonnet`, `opus`, or `haiku`
-* **inherit**: Use the same model as the main conversation (useful for consistency)
-* **Omitted**: If not specified, uses the default model configured for subagents (`sonnet`)
-
-### Control subagent capabilities
-
-You can control what subagents can do through tool access, permission modes, and conditional rules.
-
-#### Available tools
-
-Subagents can use any of Claude Code's [internal tools](/en/settings#tools-available-to-claude). By default, subagents inherit all tools from the main conversation, including MCP tools.
-
-To restrict tools, use the `tools` field (allowlist) or `disallowedTools` field (denylist):
-
-```yaml  theme={null}
----
-name: safe-researcher
-description: Research agent with restricted capabilities
-tools: Read, Grep, Glob, Bash
-disallowedTools: Write, Edit
----
-```
-
-#### Permission modes
-
-The `permissionMode` field controls how the subagent handles permission prompts. Subagents inherit the permission context from the main conversation but can override the mode.
-
-| Mode                | Behavior                                                           |
-| :------------------ | :----------------------------------------------------------------- |
-| `default`           | Standard permission checking with prompts                          |
-| `acceptEdits`       | Auto-accept file edits                                             |
-| `dontAsk`           | Auto-deny permission prompts (explicitly allowed tools still work) |
-| `bypassPermissions` | Skip all permission checks                                         |
-| `plan`              | Plan mode (read-only exploration)                                  |
-
-<Warning>
-  Use `bypassPermissions` with caution. It skips all permission checks, allowing the subagent to execute any operation without approval.
-</Warning>
-
-If the parent uses `bypassPermissions`, this takes precedence and cannot be overridden.
-
-#### Conditional rules with hooks
-
-For more dynamic control over tool usage, use `PreToolUse` hooks to validate operations before they execute. This is useful when you need to allow some operations of a tool while blocking others.
-
-This example creates a subagent that only allows read-only database queries. The `PreToolUse` hook runs the script specified in `command` before each Bash command executes:
-
-```yaml  theme={null}
----
-name: db-reader
-description: Execute read-only database queries
-tools: Bash
-hooks:
-  PreToolUse:
-    - matcher: "Bash"
-      hooks:
-        - type: command
-          command: "./scripts/validate-readonly-query.sh"
----
-```
-
-Claude Code [passes hook input as JSON](/en/hooks#pretooluse-input) via stdin to hook commands. The validation script reads this JSON, extracts the Bash command, and [exits with code 2](/en/hooks#exit-code-2-behavior) to block write operations:
-
-```bash  theme={null}
-#!/bin/bash
-# ./scripts/validate-readonly-query.sh
-
-INPUT=$(cat)
-COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
-
-# Block SQL write operations (case-insensitive)
-if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE)\b' > /dev/null; then
-  echo "Blocked: Only SELECT queries are allowed" >&2
-  exit 2
-fi
-
-exit 0
-```
-
-See [Hook input](/en/hooks#pretooluse-input) for the complete input schema and [exit codes](/en/hooks#exit-codes) for how exit codes affect behavior.
-
-#### Disable specific subagents
-
-You can prevent Claude from using specific subagents by adding them to the `deny` array in your [settings](/en/settings#permission-settings). Use the format `Task(subagent-name)` where `subagent-name` matches the subagent's name field.
-
-```json  theme={null}
-{
-  "permissions": {
-    "deny": ["Task(Explore)", "Task(my-custom-agent)"]
-  }
-}
-```
-
-This works for both built-in and custom subagents. You can also use the `--disallowedTools` CLI flag:
-
-```bash  theme={null}
-claude --disallowedTools "Task(Explore)"
-```
-
-See [IAM documentation](/en/iam#tool-specific-permission-rules) for more details on permission rules.
-
-### Define hooks for subagents
-
-Subagents can define [hooks](/en/hooks) that run during the subagent's lifecycle. There are two ways to configure hooks:
-
-1. **In the subagent's frontmatter**: Define hooks that run only while that subagent is active
-2. **In `settings.json`**: Define hooks that run in the main session when subagents start or stop
-
-#### Hooks in subagent frontmatter
-
-Define hooks directly in the subagent's markdown file. These hooks only run while that specific subagent is active and are cleaned up when it finishes.
-
-| Event         | Matcher input | When it fires                   |
-| :------------ | :------------ | :------------------------------ |
-| `PreToolUse`  | Tool name     | Before the subagent uses a tool |
-| `PostToolUse` | Tool name     | After the subagent uses a tool  |
-| `Stop`        | (none)        | When the subagent finishes      |
-
-This example validates Bash commands with the `PreToolUse` hook and runs a linter after file edits with `PostToolUse`:
-
-```yaml  theme={null}
----
-name: code-reviewer
-description: Review code changes with automatic linting
-hooks:
-  PreToolUse:
-    - matcher: "Bash"
-      hooks:
-        - type: command
-          command: "./scripts/validate-command.sh $TOOL_INPUT"
-  PostToolUse:
-    - matcher: "Edit|Write"
-      hooks:
-        - type: command
-          command: "./scripts/run-linter.sh"
----
-```
-
-`Stop` hooks in frontmatter are automatically converted to `SubagentStop` events.
-
-#### Project-level hooks for subagent events
-
-Configure hooks in `settings.json` that respond to subagent lifecycle events in the main session. Use the `matcher` field to target specific agent types by name.
-
-| Event           | Matcher input   | When it fires                    |
-| :-------------- | :-------------- | :------------------------------- |
-| `SubagentStart` | Agent type name | When a subagent begins execution |
-| `SubagentStop`  | Agent type name | When a subagent completes        |
-
-This example runs setup and cleanup scripts only when the `db-agent` subagent starts and stops:
-
-```json  theme={null}
-{
-  "hooks": {
-    "SubagentStart": [
-      {
-        "matcher": "db-agent",
-        "hooks": [
-          { "type": "command", "command": "./scripts/setup-db-connection.sh" }
-        ]
-      }
-    ],
-    "SubagentStop": [
-      {
-        "matcher": "db-agent",
-        "hooks": [
-          { "type": "command", "command": "./scripts/cleanup-db-connection.sh" }
-        ]
-      }
-    ]
-  }
-}
-```
-
-See [Hooks](/en/hooks) for the complete hook configuration format.
-
-## Work with subagents
-
-### Understand automatic delegation
-
-Claude automatically delegates tasks based on the task description in your request, the `description` field in subagent configurations, and current context. To encourage proactive delegation, include phrases like "use proactively" in your subagent's description field.
-
-You can also request a specific subagent explicitly:
-
-```
-Use the test-runner subagent to fix failing tests
-Have the code-reviewer subagent look at my recent changes
-```
-
-### Run subagents in foreground or background
-
-Subagents can run in the foreground (blocking) or background (concurrent):
-
-* **Foreground subagents** block the main conversation until complete. Permission prompts and clarifying questions (like [`AskUserQuestion`](/en/settings#tools-available-to-claude)) are passed through to you.
-* **Background subagents** run concurrently while you continue working. They inherit the parent's permissions and auto-deny anything not pre-approved. If a background subagent needs a permission it doesn't have or needs to ask clarifying questions, that tool call fails but the subagent continues. MCP tools are not available in background subagents.
-
-If a background subagent fails due to missing permissions, you can [resume it](#resume-subagents) in the foreground to retry with interactive prompts.
-
-Claude decides whether to run subagents in the foreground or background based on the task. You can also:
-
-* Ask Claude to "run this in the background"
-* Press **Ctrl+B** to background a running task
-
-To disable all background task functionality, set the `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` environment variable to `1`. See [Environment variables](/en/settings#environment-variables).
-
-### Common patterns
-
-#### Isolate high-volume operations
-
-One of the most effective uses for subagents is isolating operations that produce large amounts of output. Running tests, fetching documentation, or processing log files can consume significant context. By delegating these to a subagent, the verbose output stays in the subagent's context while only the relevant summary returns to your main conversation.
-
-```
-Use a subagent to run the test suite and report only the failing tests with their error messages
-```
-
-#### Run parallel research
-
-For independent investigations, spawn multiple subagents to work simultaneously:
-
-```
-Research the authentication, database, and API modules in parallel using separate subagents
-```
-
-Each subagent explores its area independently, then Claude synthesizes the findings. This works best when the research paths don't depend on each other.
-
-<Warning>
-  When subagents complete, their results return to your main conversation. Running many subagents that each return detailed results can consume significant context.
-</Warning>
-
-#### Chain subagents
-
-For multi-step workflows, ask Claude to use subagents in sequence. Each subagent completes its task and returns results to Claude, which then passes relevant context to the next subagent.
-
-```
-Use the code-reviewer subagent to find performance issues, then use the optimizer subagent to fix them
-```
-
-### Choose between subagents and main conversation
-
-Use the **main conversation** when:
-
-* The task needs frequent back-and-forth or iterative refinement
-* Multiple phases share significant context (planning → implementation → testing)
-* You're making a quick, targeted change
-* Latency matters. Subagents start fresh and may need time to gather context
-
-Use **subagents** when:
-
-* The task produces verbose output you don't need in your main context
-* You want to enforce specific tool restrictions or permissions
-* The work is self-contained and can return a summary
-
-Consider [Skills](/en/skills) instead when you want reusable prompts or workflows that run in the main conversation context rather than isolated subagent context.
-
-<Note>
-  Subagents cannot spawn other subagents. If your workflow requires nested delegation, use [Skills](/en/skills) or [chain subagents](#chain-subagents) from the main conversation.
-</Note>
-
-### Manage subagent context
-
-#### Resume subagents
-
-Each subagent invocation creates a new instance with fresh context. To continue an existing subagent's work instead of starting over, ask Claude to resume it.
-
-Resumed subagents retain their full conversation history, including all previous tool calls, results, and reasoning. The subagent picks up exactly where it stopped rather than starting fresh.
-
-When a subagent completes, Claude receives its agent ID. To resume a subagent, ask Claude to continue the previous work:
-
-```
-Use the code-reviewer subagent to review the authentication module
-[Agent completes]
-
-Continue that code review and now analyze the authorization logic
-[Claude resumes the subagent with full context from previous conversation]
-```
-
-You can also ask Claude for the agent ID if you want to reference it explicitly, or find IDs in the transcript files at `~/.claude/projects/{project}/{sessionId}/subagents/`. Each transcript is stored as `agent-{agentId}.jsonl`.
-
-For programmatic usage, see [Subagents in the Agent SDK](/en/agent-sdk/subagents).
-
-Subagent transcripts persist independently of the main conversation:
-
-* **Main conversation compaction**: When the main conversation compacts, subagent transcripts are unaffected. They're stored in separate files.
-* **Session persistence**: Subagent transcripts persist within their session. You can [resume a subagent](#resume-subagents) after restarting Claude Code by resuming the same session.
-* **Automatic cleanup**: Transcripts are cleaned up based on the `cleanupPeriodDays` setting (default: 30 days).
-
-#### Auto-compaction
-
-Subagents support automatic compaction using the same logic as the main conversation. When a subagent's context approaches its limit, Claude Code summarizes older messages to free up space while preserving important context.
-
-Compaction events are logged in subagent transcript files:
-
-```json  theme={null}
-{
-  "type": "system",
-  "subtype": "compact_boundary",
-  "compactMetadata": {
-    "trigger": "auto",
-    "preTokens": 167189
-  }
-}
-```
-
-The `preTokens` value shows how many tokens were used before compaction occurred.
-
-## Example subagents
-
-These examples demonstrate effective patterns for building subagents. Use them as starting points, or generate a customized version with Claude.
-
-<Tip>
-  **Best practices:**
-
-  * **Design focused subagents:** each subagent should excel at one specific task
-  * **Write detailed descriptions:** Claude uses the description to decide when to delegate
-  * **Limit tool access:** grant only necessary permissions for security and focus
-  * **Check into version control:** share project subagents with your team
-</Tip>
-
-### Code reviewer
-
-A read-only subagent that reviews code without modifying it. This example shows how to design a focused subagent with limited tool access (no Edit or Write) and a detailed prompt that specifies exactly what to look for and how to format output.
-
-```markdown  theme={null}
----
-name: code-reviewer
-description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
-tools: Read, Grep, Glob, Bash
-model: inherit
----
-
-You are a senior code reviewer ensuring high standards of code quality and security.
-
-When invoked:
-1. Run git diff to see recent changes
-2. Focus on modified files
-3. Begin review immediately
-
-Review checklist:
-- Code is clear and readable
-- Functions and variables are well-named
-- No duplicated code
-- Proper error handling
-- No exposed secrets or API keys
-- Input validation implemented
-- Good test coverage
-- Performance considerations addressed
-
-Provide feedback organized by priority:
-- Critical issues (must fix)
-- Warnings (should fix)
-- Suggestions (consider improving)
-
-Include specific examples of how to fix issues.
-```
-
-### Debugger
-
-A subagent that can both analyze and fix issues. Unlike the code reviewer, this one includes Edit because fixing bugs requires modifying code. The prompt provides a clear workflow from diagnosis to verification.
-
-```markdown  theme={null}
----
-name: debugger
-description: Debugging specialist for errors, test failures, and unexpected behavior. Use proactively when encountering any issues.
-tools: Read, Edit, Bash, Grep, Glob
----
-
-You are an expert debugger specializing in root cause analysis.
-
-When invoked:
-1. Capture error message and stack trace
-2. Identify reproduction steps
-3. Isolate the failure location
-4. Implement minimal fix
-5. Verify solution works
-
-Debugging process:
-- Analyze error messages and logs
-- Check recent code changes
-- Form and test hypotheses
-- Add strategic debug logging
-- Inspect variable states
-
-For each issue, provide:
-- Root cause explanation
-- Evidence supporting the diagnosis
-- Specific code fix
-- Testing approach
-- Prevention recommendations
-
-Focus on fixing the underlying issue, not the symptoms.
-```
-
-### Data scientist
-
-A domain-specific subagent for data analysis work. This example shows how to create subagents for specialized workflows outside of typical coding tasks. It explicitly sets `model: sonnet` for more capable analysis.
-
-```markdown  theme={null}
----
-name: data-scientist
-description: Data analysis expert for SQL queries, BigQuery operations, and data insights. Use proactively for data analysis tasks and queries.
-tools: Bash, Read, Write
-model: sonnet
----
-
-You are a data scientist specializing in SQL and BigQuery analysis.
-
-When invoked:
-1. Understand the data analysis requirement
-2. Write efficient SQL queries
-3. Use BigQuery command line tools (bq) when appropriate
-4. Analyze and summarize results
-5. Present findings clearly
-
-Key practices:
-- Write optimized SQL queries with proper filters
-- Use appropriate aggregations and joins
-- Include comments explaining complex logic
-- Format results for readability
-- Provide data-driven recommendations
-
-For each analysis:
-- Explain the query approach
-- Document any assumptions
-- Highlight key findings
-- Suggest next steps based on data
-
-Always ensure queries are efficient and cost-effective.
-```
-
-### Database query validator
-
-A subagent that allows Bash access but validates commands to permit only read-only SQL queries. This example shows how to use `PreToolUse` hooks for conditional validation when you need finer control than the `tools` field provides.
-
-```markdown  theme={null}
----
-name: db-reader
-description: Execute read-only database queries. Use when analyzing data or generating reports.
-tools: Bash
-hooks:
-  PreToolUse:
-    - matcher: "Bash"
-      hooks:
-        - type: command
-          command: "./scripts/validate-readonly-query.sh"
----
-
-You are a database analyst with read-only access. Execute SELECT queries to answer questions about the data.
-
-When asked to analyze data:
-1. Identify which tables contain the relevant data
-2. Write efficient SELECT queries with appropriate filters
-3. Present results clearly with context
-
-You cannot modify data. If asked to INSERT, UPDATE, DELETE, or modify schema, explain that you only have read access.
-```
-
-Claude Code [passes hook input as JSON](/en/hooks#pretooluse-input) via stdin to hook commands. The validation script reads this JSON, extracts the command being executed, and checks it against a list of SQL write operations. If a write operation is detected, the script [exits with code 2](/en/hooks#exit-code-2-behavior) to block execution and returns an error message to Claude via stderr.
-
-Create the validation script anywhere in your project. The path must match the `command` field in your hook configuration:
-
-```bash  theme={null}
-#!/bin/bash
-# Blocks SQL write operations, allows SELECT queries
-
-# Read JSON input from stdin
-INPUT=$(cat)
-
-# Extract the command field from tool_input using jq
-COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
-
-if [ -z "$COMMAND" ]; then
-  exit 0
-fi
-
-# Block write operations (case-insensitive)
-if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE|REPLACE|MERGE)\b' > /dev/null; then
-  echo "Blocked: Write operations not allowed. Use SELECT queries only." >&2
-  exit 2
-fi
-
-exit 0
-```
-
-Make the script executable:
-
-```bash  theme={null}
-chmod +x ./scripts/validate-readonly-query.sh
-```
-
-The hook receives JSON via stdin with the Bash command in `tool_input.command`. Exit code 2 blocks the operation and feeds the error message back to Claude. See [Hooks](/en/hooks#exit-codes) for details on exit codes and [Hook input](/en/hooks#pretooluse-input) for the complete input schema.
-
-## Next steps
-
-Now that you understand subagents, explore these related features:
-
-* [Distribute subagents with plugins](/en/plugins) to share subagents across teams or projects
-* [Run Claude Code programmatically](/en/headless) with the Agent SDK for CI/CD and automation
-* [Use MCP servers](/en/mcp) to give subagents access to external tools and data
-
-
----
-
-> To find navigation and other pages in this documentation, fetch the llms.txt file at: https://code.claude.com/docs/llms.txt

.opencode/context/to-be-consumed/claude-code-docs/hooks.md

@@ -1,338 +0,0 @@
-# Get started with Claude Code hooks
-
-> Learn how to customize and extend Claude Code's behavior by registering shell commands
-
-Claude Code hooks are user-defined shell commands that execute at various points
-in Claude Code's lifecycle. Hooks provide deterministic control over Claude
-Code's behavior, ensuring certain actions always happen rather than relying on
-the LLM to choose to run them.
-
-<Tip>
-  For reference documentation on hooks, see [Hooks reference](/en/hooks).
-</Tip>
-
-Example use cases for hooks include:
-
-* **Notifications**: Customize how you get notified when Claude Code is awaiting
-  your input or permission to run something.
-* **Automatic formatting**: Run `prettier` on .ts files, `gofmt` on .go files,
-  etc. after every file edit.
-* **Logging**: Track and count all executed commands for compliance or
-  debugging.
-* **Feedback**: Provide automated feedback when Claude Code produces code that
-  does not follow your codebase conventions.
-* **Custom permissions**: Block modifications to production files or sensitive
-  directories.
-
-By encoding these rules as hooks rather than prompting instructions, you turn
-suggestions into app-level code that executes every time it is expected to run.
-
-<Warning>
-  You must consider the security implication of hooks as you add them, because hooks run automatically during the agent loop with your current environment's credentials.
-  For example, malicious hooks code can exfiltrate your data. Always review your hooks implementation before registering them.
-
-  For full security best practices, see [Security Considerations](/en/hooks#security-considerations) in the hooks reference documentation.
-</Warning>
-
-## Hook Events Overview
-
-Claude Code provides several hook events that run at different points in the
-workflow:
-
-* **PreToolUse**: Runs before tool calls (can block them)
-* **PermissionRequest**: Runs when a permission dialog is shown (can allow or deny)
-* **PostToolUse**: Runs after tool calls complete
-* **UserPromptSubmit**: Runs when the user submits a prompt, before Claude processes it
-* **Notification**: Runs when Claude Code sends notifications
-* **Stop**: Runs when Claude Code finishes responding
-* **SubagentStop**: Runs when subagent tasks complete
-* **PreCompact**: Runs before Claude Code is about to run a compact operation
-* **SessionStart**: Runs when Claude Code starts a new session or resumes an existing session
-* **SessionEnd**: Runs when Claude Code session ends
-
-Each event receives different data and can control Claude's behavior in
-different ways.
-
-## Quickstart
-
-In this quickstart, you'll add a hook that logs the shell commands that Claude
-Code runs.
-
-### Prerequisites
-
-Install `jq` for JSON processing in the command line.
-
-### Step 1: Open hooks configuration
-
-Run the `/hooks` [slash command](/en/slash-commands) and select
-the `PreToolUse` hook event.
-
-`PreToolUse` hooks run before tool calls and can block them while providing
-Claude feedback on what to do differently.
-
-### Step 2: Add a matcher
-
-Select `+ Add new matcher…` to run your hook only on Bash tool calls.
-
-Type `Bash` for the matcher.
-
-<Note>You can use `*` to match all tools.</Note>
-
-### Step 3: Add the hook
-
-Select `+ Add new hook…` and enter this command:
-
-```bash  theme={null}
-jq -r '"\(.tool_input.command) - \(.tool_input.description // "No description")"' >> ~/.claude/bash-command-log.txt
-```
-
-### Step 4: Save your configuration
-
-For storage location, select `User settings` since you're logging to your home
-directory. This hook will then apply to all projects, not just your current
-project.
-
-Then press `Esc` until you return to the REPL. Your hook is now registered.
-
-### Step 5: Verify your hook
-
-Run `/hooks` again or check `~/.claude/settings.json` to see your configuration:
-
-```json  theme={null}
-{
-  "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "Bash",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "jq -r '\"\\(.tool_input.command) - \\(.tool_input.description // \"No description\")\"' >> ~/.claude/bash-command-log.txt"
-          }
-        ]
-      }
-    ]
-  }
-}
-```
-
-### Step 6: Test your hook
-
-Ask Claude to run a simple command like `ls` and check your log file:
-
-```bash  theme={null}
-cat ~/.claude/bash-command-log.txt
-```
-
-You should see entries like:
-
-```
-ls - Lists files and directories
-```
-
-## More Examples
-
-<Note>
-  For a complete example implementation, see the [bash command validator example](https://github.com/anthropics/claude-code/blob/main/examples/hooks/bash_command_validator_example.py) in our public codebase.
-</Note>
-
-### Code Formatting Hook
-
-Automatically format TypeScript files after editing:
-
-```json  theme={null}
-{
-  "hooks": {
-    "PostToolUse": [
-      {
-        "matcher": "Edit|Write",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "jq -r '.tool_input.file_path' | { read file_path; if echo \"$file_path\" | grep -q '\\.ts$'; then npx prettier --write \"$file_path\"; fi; }"
-          }
-        ]
-      }
-    ]
-  }
-}
-```
-
-### Markdown Formatting Hook
-
-Automatically fix missing language tags and formatting issues in markdown files:
-
-```json  theme={null}
-{
-  "hooks": {
-    "PostToolUse": [
-      {
-        "matcher": "Edit|Write",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/markdown_formatter.py"
-          }
-        ]
-      }
-    ]
-  }
-}
-```
-
-Create `.claude/hooks/markdown_formatter.py` with this content:
-
-````python  theme={null}
-#!/usr/bin/env python3
-"""
-Markdown formatter for Claude Code output.
-Fixes missing language tags and spacing issues while preserving code content.
-"""
-import json
-import sys
-import re
-import os
-
-def detect_language(code):
-    """Best-effort language detection from code content."""
-    s = code.strip()
-    
-    # JSON detection
-    if re.search(r'^\s*[{\[]', s):
-        try:
-            json.loads(s)
-            return 'json'
-        except:
-            pass
-    
-    # Python detection
-    if re.search(r'^\s*def\s+\w+\s*\(', s, re.M) or \
-       re.search(r'^\s*(import|from)\s+\w+', s, re.M):
-        return 'python'
-    
-    # JavaScript detection  
-    if re.search(r'\b(function\s+\w+\s*\(|const\s+\w+\s*=)', s) or \
-       re.search(r'=>|console\.(log|error)', s):
-        return 'javascript'
-    
-    # Bash detection
-    if re.search(r'^#!.*\b(bash|sh)\b', s, re.M) or \
-       re.search(r'\b(if|then|fi|for|in|do|done)\b', s):
-        return 'bash'
-    
-    # SQL detection
-    if re.search(r'\b(SELECT|INSERT|UPDATE|DELETE|CREATE)\s+', s, re.I):
-        return 'sql'
-        
-    return 'text'
-
-def format_markdown(content):
-    """Format markdown content with language detection."""
-    # Fix unlabeled code fences
-    def add_lang_to_fence(match):
-        indent, info, body, closing = match.groups()
-        if not info.strip():
-            lang = detect_language(body)
-            return f"{indent}```{lang}\n{body}{closing}\n"
-        return match.group(0)
-    
-    fence_pattern = r'(?ms)^([ \t]{0,3})```([^\n]*)\n(.*?)(\n\1```)\s*$'
-    content = re.sub(fence_pattern, add_lang_to_fence, content)
-    
-    # Fix excessive blank lines (only outside code fences)
-    content = re.sub(r'\n{3,}', '\n\n', content)
-    
-    return content.rstrip() + '\n'
-
-# Main execution
-try:
-    input_data = json.load(sys.stdin)
-    file_path = input_data.get('tool_input', {}).get('file_path', '')
-    
-    if not file_path.endswith(('.md', '.mdx')):
-        sys.exit(0)  # Not a markdown file
-    
-    if os.path.exists(file_path):
-        with open(file_path, 'r', encoding='utf-8') as f:
-            content = f.read()
-        
-        formatted = format_markdown(content)
-        
-        if formatted != content:
-            with open(file_path, 'w', encoding='utf-8') as f:
-                f.write(formatted)
-            print(f"✓ Fixed markdown formatting in {file_path}")
-    
-except Exception as e:
-    print(f"Error formatting markdown: {e}", file=sys.stderr)
-    sys.exit(1)
-````
-
-Make the script executable:
-
-```bash  theme={null}
-chmod +x .claude/hooks/markdown_formatter.py
-```
-
-This hook automatically:
-
-* Detects programming languages in unlabeled code blocks
-* Adds appropriate language tags for syntax highlighting
-* Fixes excessive blank lines while preserving code content
-* Only processes markdown files (`.md`, `.mdx`)
-
-### Custom Notification Hook
-
-Get desktop notifications when Claude needs input:
-
-```json  theme={null}
-{
-  "hooks": {
-    "Notification": [
-      {
-        "matcher": "",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "notify-send 'Claude Code' 'Awaiting your input'"
-          }
-        ]
-      }
-    ]
-  }
-}
-```
-
-### File Protection Hook
-
-Block edits to sensitive files:
-
-```json  theme={null}
-{
-  "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "Edit|Write",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "python3 -c \"import json, sys; data=json.load(sys.stdin); path=data.get('tool_input',{}).get('file_path',''); sys.exit(2 if any(p in path for p in ['.env', 'package-lock.json', '.git/']) else 0)\""
-          }
-        ]
-      }
-    ]
-  }
-}
-```
-
-## Learn more
-
-* For reference documentation on hooks, see [Hooks reference](/en/hooks).
-* For comprehensive security best practices and safety guidelines, see [Security Considerations](/en/hooks#security-considerations) in the hooks reference documentation.
-* For troubleshooting steps and debugging techniques, see [Debugging](/en/hooks#debugging) in the hooks reference
-  documentation.
-
-
----
-
-> To find navigation and other pages in this documentation, fetch the llms.txt file at: https://code.claude.com/docs/llms.txt

.opencode/context/to-be-consumed/claude-code-docs/navigation.md

@@ -1,36 +0,0 @@
-# Claude Code Documentation
-
-**Purpose**: External documentation for Claude Code to be integrated into main context
-
----
-
-## Structure
-
-```
-to-be-consumed/claude-code-docs/
-├── navigation.md (this file)
-└── [external documentation files]
-```
-
----
-
-## Quick Routes
-
-| Task | Path |
-|------|------|
-| **View docs** | `./` |
-| **To-be-consumed** | `../navigation.md` |
-
----
-
-## By Type
-
-**External Docs** → Documentation from external sources  
-**To Be Integrated** → Content awaiting integration into main context
-
----
-
-## Related Context
-
-- **To-be-consumed Navigation** → `../navigation.md`
-- **Development** → `../../development/navigation.md`

.opencode/context/to-be-consumed/claude-code-docs/plugins.md

@@ -1,413 +0,0 @@
-# Create plugins
-
-> Create custom plugins to extend Claude Code with slash commands, agents, hooks, Skills, and MCP servers.
-
-Plugins let you extend Claude Code with custom functionality that can be shared across projects and teams. This guide covers creating your own plugins with slash commands, agents, Skills, hooks, and MCP servers.
-
-Looking to install existing plugins? See [Discover and install plugins](/en/discover-plugins). For complete technical specifications, see [Plugins reference](/en/plugins-reference).
-
-## When to use plugins vs standalone configuration
-
-Claude Code supports two ways to add custom slash commands, agents, and hooks:
-
-| Approach                                                    | Slash command names  | Best for                                                                                        |
-| :---------------------------------------------------------- | :------------------- | :---------------------------------------------------------------------------------------------- |
-| **Standalone** (`.claude/` directory)                       | `/hello`             | Personal workflows, project-specific customizations, quick experiments                          |
-| **Plugins** (directories with `.claude-plugin/plugin.json`) | `/plugin-name:hello` | Sharing with teammates, distributing to community, versioned releases, reusable across projects |
-
-**Use standalone configuration when**:
-
-* You're customizing Claude Code for a single project
-* The configuration is personal and doesn't need to be shared
-* You're experimenting with slash commands or hooks before packaging them
-* You want short slash command names like `/hello` or `/review`
-
-**Use plugins when**:
-
-* You want to share functionality with your team or community
-* You need the same slash commands/agents across multiple projects
-* You want version control and easy updates for your extensions
-* You're distributing through a marketplace
-* You're okay with namespaced slash commands like `/my-plugin:hello` (namespacing prevents conflicts between plugins)
-
-<Tip>
-  Start with standalone configuration in `.claude/` for quick iteration, then [convert to a plugin](#convert-existing-configurations-to-plugins) when you're ready to share.
-</Tip>
-
-## Quickstart
-
-This quickstart walks you through creating a plugin with a custom slash command. You'll create a manifest (the configuration file that defines your plugin), add a slash command, and test it locally using the `--plugin-dir` flag.
-
-### Prerequisites
-
-* Claude Code [installed and authenticated](/en/quickstart#step-1-install-claude-code)
-* Claude Code version 1.0.33 or later (run `claude --version` to check)
-
-<Note>
-  If you don't see the `/plugin` command, update Claude Code to the latest version. See [Troubleshooting](/en/troubleshooting) for upgrade instructions.
-</Note>
-
-### Create your first plugin
-
-<Steps>
-  <Step title="Create the plugin directory">
-    Every plugin lives in its own directory containing a manifest and your custom commands, agents, or hooks. Create one now:
-
-    ```bash  theme={null}
-    mkdir my-first-plugin
-    ```
-  </Step>
-
-  <Step title="Create the plugin manifest">
-    The manifest file at `.claude-plugin/plugin.json` defines your plugin's identity: its name, description, and version. Claude Code uses this metadata to display your plugin in the plugin manager.
-
-    Create the `.claude-plugin` directory inside your plugin folder:
-
-    ```bash  theme={null}
-    mkdir my-first-plugin/.claude-plugin
-    ```
-
-    Then create `my-first-plugin/.claude-plugin/plugin.json` with this content:
-
-    ```json my-first-plugin/.claude-plugin/plugin.json theme={null}
-    {
-    "name": "my-first-plugin",
-    "description": "A greeting plugin to learn the basics",
-    "version": "1.0.0",
-    "author": {
-    "name": "Your Name"
-    }
-    }
-    ```
-
-    | Field         | Purpose                                                                                                                |
-    | :------------ | :--------------------------------------------------------------------------------------------------------------------- |
-    | `name`        | Unique identifier and slash command namespace. Slash commands are prefixed with this (e.g., `/my-first-plugin:hello`). |
-    | `description` | Shown in the plugin manager when browsing or installing plugins.                                                       |
-    | `version`     | Track releases using [semantic versioning](/en/plugins-reference#version-management).                                  |
-    | `author`      | Optional. Helpful for attribution.                                                                                     |
-
-    For additional fields like `homepage`, `repository`, and `license`, see the [full manifest schema](/en/plugins-reference#plugin-manifest-schema).
-  </Step>
-
-  <Step title="Add a slash command">
-    Slash commands are Markdown files in the `commands/` directory. The filename becomes the slash command name, prefixed with the plugin's namespace (`hello.md` in a plugin named `my-first-plugin` creates `/my-first-plugin:hello`). The Markdown content tells Claude how to respond when someone runs the slash command.
-
-    Create a `commands` directory in your plugin folder:
-
-    ```bash  theme={null}
-    mkdir my-first-plugin/commands
-    ```
-
-    Then create `my-first-plugin/commands/hello.md` with this content:
-
-    ```markdown my-first-plugin/commands/hello.md theme={null}
-    ---
-    description: Greet the user with a friendly message
-    ---
-
-    # Hello Command
-
-    Greet the user warmly and ask how you can help them today.
-    ```
-  </Step>
-
-  <Step title="Test your plugin">
-    Run Claude Code with the `--plugin-dir` flag to load your plugin:
-
-    ```bash  theme={null}
-    claude --plugin-dir ./my-first-plugin
-    ```
-
-    Once Claude Code starts, try your new command:
-
-    ```shell  theme={null}
-    /my-first-plugin:hello
-    ```
-
-    You'll see Claude respond with a greeting. Run `/help` to see your command listed under the plugin namespace.
-
-    <Note>
-      **Why namespacing?** Plugin slash commands are always namespaced (like `/greet:hello`) to prevent conflicts when multiple plugins have commands with the same name.
-
-      To change the namespace prefix, update the `name` field in `plugin.json`.
-    </Note>
-  </Step>
-
-  <Step title="Add slash command arguments">
-    Make your slash command dynamic by accepting user input. The `$ARGUMENTS` placeholder captures any text the user provides after the slash command.
-
-    Update your `hello.md` file:
-
-    ```markdown my-first-plugin/commands/hello.md theme={null}
-    ---
-    description: Greet the user with a personalized message
-    ---
-
-    # Hello Command
-
-    Greet the user named "$ARGUMENTS" warmly and ask how you can help them today. Make the greeting personal and encouraging.
-    ```
-
-    Restart Claude Code to pick up the changes, then try the command with your name:
-
-    ```shell  theme={null}
-    /my-first-plugin:hello Alex
-    ```
-
-    Claude will greet you by name. For more argument options like `$1`, `$2` for individual parameters, see [Slash commands](/en/slash-commands).
-  </Step>
-</Steps>
-
-You've successfully created and tested a plugin with these key components:
-
-* **Plugin manifest** (`.claude-plugin/plugin.json`): describes your plugin's metadata
-* **Commands directory** (`commands/`): contains your custom slash commands
-* **Command arguments** (`$ARGUMENTS`): captures user input for dynamic behavior
-
-<Tip>
-  The `--plugin-dir` flag is useful for development and testing. When you're ready to share your plugin with others, see [Create and distribute a plugin marketplace](/en/plugin-marketplaces).
-</Tip>
-
-## Plugin structure overview
-
-You've created a plugin with a slash command, but plugins can include much more: custom agents, Skills, hooks, MCP servers, and LSP servers.
-
-<Warning>
-  **Common mistake**: Don't put `commands/`, `agents/`, `skills/`, or `hooks/` inside the `.claude-plugin/` directory. Only `plugin.json` goes inside `.claude-plugin/`. All other directories must be at the plugin root level.
-</Warning>
-
-| Directory         | Location    | Purpose                                         |
-| :---------------- | :---------- | :---------------------------------------------- |
-| `.claude-plugin/` | Plugin root | Contains only `plugin.json` manifest (required) |
-| `commands/`       | Plugin root | Slash commands as Markdown files                |
-| `agents/`         | Plugin root | Custom agent definitions                        |
-| `skills/`         | Plugin root | Agent Skills with `SKILL.md` files              |
-| `hooks/`          | Plugin root | Event handlers in `hooks.json`                  |
-| `.mcp.json`       | Plugin root | MCP server configurations                       |
-| `.lsp.json`       | Plugin root | LSP server configurations for code intelligence |
-
-<Note>
-  **Next steps**: Ready to add more features? Jump to [Develop more complex plugins](#develop-more-complex-plugins) to add agents, hooks, MCP servers, and LSP servers. For complete technical specifications of all plugin components, see [Plugins reference](/en/plugins-reference).
-</Note>
-
-## Develop more complex plugins
-
-Once you're comfortable with basic plugins, you can create more sophisticated extensions.
-
-### Add Skills to your plugin
-
-Plugins can include [Agent Skills](/en/skills) to extend Claude's capabilities. Skills are model-invoked: Claude automatically uses them based on the task context.
-
-Add a `skills/` directory at your plugin root with Skill folders containing `SKILL.md` files:
-
-```
-my-plugin/
-├── .claude-plugin/
-│   └── plugin.json
-└── skills/
-    └── code-review/
-        └── SKILL.md
-```
-
-Each `SKILL.md` needs frontmatter with `name` and `description` fields, followed by instructions:
-
-```yaml  theme={null}
----
-name: code-review
-description: Reviews code for best practices and potential issues. Use when reviewing code, checking PRs, or analyzing code quality.
----
-
-When reviewing code, check for:
-1. Code organization and structure
-2. Error handling
-3. Security concerns
-4. Test coverage
-```
-
-After installing the plugin, restart Claude Code to load the Skills. For complete Skill authoring guidance including progressive disclosure and tool restrictions, see [Agent Skills](/en/skills).
-
-### Add LSP servers to your plugin
-
-<Tip>
-  For common languages like TypeScript, Python, and Rust, install the pre-built LSP plugins from the official marketplace. Create custom LSP plugins only when you need support for languages not already covered.
-</Tip>
-
-LSP (Language Server Protocol) plugins give Claude real-time code intelligence. If you need to support a language that doesn't have an official LSP plugin, you can create your own by adding an `.lsp.json` file to your plugin:
-
-```json .lsp.json theme={null}
-{
-  "go": {
-    "command": "gopls",
-    "args": ["serve"],
-    "extensionToLanguage": {
-      ".go": "go"
-    }
-  }
-}
-```
-
-Users installing your plugin must have the language server binary installed on their machine.
-
-For complete LSP configuration options, see [LSP servers](/en/plugins-reference#lsp-servers).
-
-### Organize complex plugins
-
-For plugins with many components, organize your directory structure by functionality. For complete directory layouts and organization patterns, see [Plugin directory structure](/en/plugins-reference#plugin-directory-structure).
-
-### Test your plugins locally
-
-Use the `--plugin-dir` flag to test plugins during development. This loads your plugin directly without requiring installation.
-
-```bash  theme={null}
-claude --plugin-dir ./my-plugin
-```
-
-As you make changes to your plugin, restart Claude Code to pick up the updates. Test your plugin components:
-
-* Try your commands with `/command-name`
-* Check that agents appear in `/agents`
-* Verify hooks work as expected
-
-<Tip>
-  You can load multiple plugins at once by specifying the flag multiple times:
-
-  ```bash  theme={null}
-  claude --plugin-dir ./plugin-one --plugin-dir ./plugin-two
-  ```
-</Tip>
-
-### Debug plugin issues
-
-If your plugin isn't working as expected:
-
-1. **Check the structure**: Ensure your directories are at the plugin root, not inside `.claude-plugin/`
-2. **Test components individually**: Check each command, agent, and hook separately
-3. **Use validation and debugging tools**: See [Debugging and development tools](/en/plugins-reference#debugging-and-development-tools) for CLI commands and troubleshooting techniques
-
-### Share your plugins
-
-When your plugin is ready to share:
-
-1. **Add documentation**: Include a `README.md` with installation and usage instructions
-2. **Version your plugin**: Use [semantic versioning](/en/plugins-reference#version-management) in your `plugin.json`
-3. **Create or use a marketplace**: Distribute through [plugin marketplaces](/en/plugin-marketplaces) for installation
-4. **Test with others**: Have team members test the plugin before wider distribution
-
-Once your plugin is in a marketplace, others can install it using the instructions in [Discover and install plugins](/en/discover-plugins).
-
-<Note>
-  For complete technical specifications, debugging techniques, and distribution strategies, see [Plugins reference](/en/plugins-reference).
-</Note>
-
-## Convert existing configurations to plugins
-
-If you already have custom commands, Skills, or hooks in your `.claude/` directory, you can convert them into a plugin for easier sharing and distribution.
-
-### Migration steps
-
-<Steps>
-  <Step title="Create the plugin structure">
-    Create a new plugin directory:
-
-    ```bash  theme={null}
-    mkdir -p my-plugin/.claude-plugin
-    ```
-
-    Create the manifest file at `my-plugin/.claude-plugin/plugin.json`:
-
-    ```json my-plugin/.claude-plugin/plugin.json theme={null}
-    {
-      "name": "my-plugin",
-      "description": "Migrated from standalone configuration",
-      "version": "1.0.0"
-    }
-    ```
-  </Step>
-
-  <Step title="Copy your existing files">
-    Copy your existing configurations to the plugin directory:
-
-    ```bash  theme={null}
-    # Copy commands
-    cp -r .claude/commands my-plugin/
-
-    # Copy agents (if any)
-    cp -r .claude/agents my-plugin/
-
-    # Copy skills (if any)
-    cp -r .claude/skills my-plugin/
-    ```
-  </Step>
-
-  <Step title="Migrate hooks">
-    If you have hooks in your settings, create a hooks directory:
-
-    ```bash  theme={null}
-    mkdir my-plugin/hooks
-    ```
-
-    Create `my-plugin/hooks/hooks.json` with your hooks configuration. Copy the `hooks` object from your `.claude/settings.json` or `settings.local.json`—the format is the same:
-
-    ```json my-plugin/hooks/hooks.json theme={null}
-    {
-      "hooks": {
-        "PostToolUse": [
-          {
-            "matcher": "Write|Edit",
-            "hooks": [{ "type": "command", "command": "npm run lint:fix $FILE" }]
-          }
-        ]
-      }
-    }
-    ```
-  </Step>
-
-  <Step title="Test your migrated plugin">
-    Load your plugin to verify everything works:
-
-    ```bash  theme={null}
-    claude --plugin-dir ./my-plugin
-    ```
-
-    Test each component: run your commands, check agents appear in `/agents`, and verify hooks trigger correctly.
-  </Step>
-</Steps>
-
-### What changes when migrating
-
-| Standalone (`.claude/`)       | Plugin                           |
-| :---------------------------- | :------------------------------- |
-| Only available in one project | Can be shared via marketplaces   |
-| Files in `.claude/commands/`  | Files in `plugin-name/commands/` |
-| Hooks in `settings.json`      | Hooks in `hooks/hooks.json`      |
-| Must manually copy to share   | Install with `/plugin install`   |
-
-<Note>
-  After migrating, you can remove the original files from `.claude/` to avoid duplicates. The plugin version will take precedence when loaded.
-</Note>
-
-## Next steps
-
-Now that you understand Claude Code's plugin system, here are suggested paths for different goals:
-
-### For plugin users
-
-* [Discover and install plugins](/en/discover-plugins): browse marketplaces and install plugins
-* [Configure team marketplaces](/en/discover-plugins#configure-team-marketplaces): set up repository-level plugins for your team
-
-### For plugin developers
-
-* [Create and distribute a marketplace](/en/plugin-marketplaces): package and share your plugins
-* [Plugins reference](/en/plugins-reference): complete technical specifications
-* Dive deeper into specific plugin components:
-  * [Slash commands](/en/slash-commands): command development details
-  * [Subagents](/en/sub-agents): agent configuration and capabilities
-  * [Agent Skills](/en/skills): extend Claude's capabilities
-  * [Hooks](/en/hooks): event handling and automation
-  * [MCP](/en/mcp): external tool integration
-
-
----
-
-> To find navigation and other pages in this documentation, fetch the llms.txt file at: https://code.claude.com/docs/llms.txt

.opencode/context/ui/web/animation-advanced.md

@@ -0,0 +1,200 @@
+<!-- Context: ui/web/animation-advanced | Priority: medium | Version: 1.0 | Updated: 2025-12-09 -->
+# Advanced Animation Patterns
+
+Recipes, best practices, micro-interactions, and accessibility considerations.
+
+---
+
+## 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)
+
+---
+
+## Related Files
+
+- [Animation Basics](./animation-basics.md) - Fundamentals
+- [UI Animations](./animation-ui.md) - Common UI patterns
+- [Loading Animations](./animation-loading.md) - Loading states

.opencode/context/ui/web/animation-basics.md

@@ -0,0 +1,94 @@
+<!-- Context: ui/web/animation-basics | Priority: high | Version: 1.0 | Updated: 2025-12-09 -->
+# Animation Basics
+
+## 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`
+
+---
+
+## Related Files
+
+- [UI Animations](./animation-ui.md) - Common UI patterns
+- [Loading Animations](./animation-loading.md) - Loading states
+- [Advanced Animations](./animation-advanced.md) - Recipes & best practices

.opencode/context/ui/web/animation-chat.md

@@ -0,0 +1,113 @@
+<!-- Context: ui/web/animation-chat | Priority: medium | Version: 1.0 | Updated: 2025-12-09 -->
+# Chat UI Animation Patterns
+
+Animation patterns for message entrances, typing indicators, and chat interactions.
+
+---
+
+## 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-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
+```
+
+---
+
+## Chat Message Micro-Interactions
+
+```css
+/* Message hover */
+.message:hover {
+  transform: translateY(-2px);
+  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1);
+  transition: all 200ms ease-out;
+}
+
+/* Message selection */
+.message.selected {
+  background-color: var(--accent);
+  transform: scale(1.02);
+  transition: all 200ms ease-out;
+}
+```
+
+**Micro-syntax**:
+```
+msgHover: 200ms [Y0→-2, shadow↗]
+msgSelect: 200ms [bg→accent, S1→1.02]
+```
+
+---
+
+## Related Files
+
+- [Animation Basics](./animation-basics.md) - Fundamentals
+- [Component Animations](./animation-components.md) - UI components
+- [Loading Animations](./animation-loading.md) - Loading states

.opencode/context/ui/web/animation-components.md

@@ -0,0 +1,137 @@
+<!-- Context: ui/web/animation-components | Priority: high | Version: 1.0 | Updated: 2025-12-09 -->
+# Component Animation Patterns
+
+Animation patterns for buttons, cards, modals, dropdowns, and sidebars.
+
+---
+
+## Button Interactions
+
+```css
+.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);
+}
+.button:active {
+  transform: scale(0.95);
+  transition: transform 100ms ease-in;
+}
+
+@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
+.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);
+}
+.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
+.modal-backdrop { animation: fadeIn 300ms ease-out; }
+@keyframes fadeIn { from { opacity: 0; } to { opacity: 1; } }
+
+.modal { animation: slideUp 350ms ease-out; }
+@keyframes slideUp {
+  from { transform: translateY(40px); opacity: 0; }
+  to { transform: translateY(0); opacity: 1; }
+}
+
+.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 {
+  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 { animation: slideInLeft 350ms ease-out; }
+@keyframes slideInLeft {
+  from { transform: translateX(-280px); opacity: 0; }
+  to { transform: translateX(0); opacity: 1; }
+}
+
+.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]
+```
+
+---
+
+## Related Files
+
+- [Animation Basics](./animation-basics.md) - Fundamentals
+- [Chat Animations](./animation-chat.md) - Message patterns
+- [Loading Animations](./animation-loading.md) - Loading states

.opencode/context/ui/web/animation-forms.md

@@ -0,0 +1,121 @@
+<!-- Context: ui/web/animation-forms | Priority: medium | Version: 1.0 | Updated: 2025-12-09 -->
+# Form Animation Patterns
+
+Animation patterns for form inputs, validation states, and scroll 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]
+```
+
+---
+
+## Scroll Animations
+
+### Scroll-Triggered Fade In
+
+```css
+.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
+html {
+  scroll-behavior: smooth;
+}
+
+.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]
+```
+
+---
+
+## Related Files
+
+- [Animation Basics](./animation-basics.md) - Fundamentals
+- [UI Animations](./animation-ui.md) - Common UI patterns
+- [Loading Animations](./animation-loading.md) - Loading states

.opencode/context/ui/web/animation-loading.md

@@ -0,0 +1,118 @@
+<!-- Context: ui/web/animation-loading | Priority: medium | Version: 1.0 | Updated: 2025-12-09 -->
+# Loading State Animations
+
+Animation patterns for skeleton screens, spinners, progress bars, and status indicators.
+
+---
+
+## 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%]
+```
+
+---
+
+## 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]
+```
+
+---
+
+## Related Files
+
+- [Animation Basics](./animation-basics.md) - Fundamentals
+- [Form Animations](./animation-forms.md) - Form patterns
+- [Advanced Animations](./animation-advanced.md) - Recipes & best practices

.opencode/context/ui/web/animation-patterns.md

@@ -1,753 +0,0 @@
-<!-- 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/ui/web/cdn-resources.md

@@ -0,0 +1,149 @@
+<!-- Context: ui/web/cdn | Priority: medium | Version: 1.0 | Updated: 2026-02-05 -->
+# CDN Resources
+
+**Purpose**: Common CDN libraries for frontend development
+
+---
+
+## CSS Frameworks
+
+### Tailwind CSS
+```html
+<script src="https://cdn.tailwindcss.com"></script>
+```
+
+### Flowbite
+```html
+<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
+```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>
+```
+
+---
+
+## JavaScript Libraries
+
+### Alpine.js
+```html
+<script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3.x.x/dist/cdn.min.js"></script>
+```
+
+### HTMX
+```html
+<script src="https://unpkg.com/htmx.org@1.9.10"></script>
+```
+
+### Chart.js
+```html
+<script src="https://cdn.jsdelivr.net/npm/chart.js@4.4.0/dist/chart.umd.min.js"></script>
+```
+
+---
+
+## Animation Libraries
+
+### Animate.css
+```html
+<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/animate.css/4.1.1/animate.min.css">
+```
+
+### AOS (Animate On Scroll)
+```html
+<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>
+```
+
+---
+
+## Video Placeholders
+
+```html
+<!-- Sample video -->
+<video class="w-full rounded-lg" controls>
+  <source src="https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4" type="video/mp4">
+</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>
+```
+
+---
+
+## Best Practices
+
+### Version Pinning
+```html
+<!-- Good: Specific version -->
+<script src="https://unpkg.com/lucide@0.294.0/dist/umd/lucide.min.js"></script>
+
+<!-- Risky: Latest version -->
+<script src="https://unpkg.com/lucide@latest/dist/umd/lucide.min.js"></script>
+```
+
+### Integrity Hashes
+```html
+<script 
+  src="https://cdn.jsdelivr.net/npm/alpinejs@3.13.3/dist/cdn.min.js" 
+  integrity="sha384-..." 
+  crossorigin="anonymous"
+></script>
+```
+
+---
+
+## File Naming Conventions
+
+**Design Files:**
+- Initial: `{name}_1.html` (e.g., `table_1.html`)
+- Iterations: `{name}_1_1.html`, `{name}_1_2.html`
+- Themes: `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`
+
+---
+
+## Project Structure
+
+```
+design_iterations/
+├── theme_1.css
+├── ui_1.html
+├── ui_1_1.html (iteration)
+├── dashboard_1.html
+└── assets/
+    ├── images/
+    ├── icons/
+    └── fonts/
+```
+
+---
+
+## Accessibility Checklist
+
+**Images:**
+- [ ] All images have alt text
+- [ ] Decorative images have `alt=""` and `role="presentation"`
+- [ ] Complex images have figcaption
+
+**Icons:**
+- [ ] Icon-only buttons have `aria-label`
+- [ ] Decorative icons have `aria-hidden="true"`
+- [ ] Icons with text are hidden from screen readers
+
+---
+
+## Related
+
+- `images-guide.md` - Image guidelines
+- `icons-guide.md` - Icon systems
+- `fonts-guide.md` - Font loading

.opencode/context/ui/web/design-assets.md

@@ -1,567 +0,0 @@
-<!-- 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/ui/web/design/guides/premium-dark-ui-advanced.md

@@ -0,0 +1,145 @@
+# Premium Dark UI - Advanced
+
+Animations, accessibility, and checklists for premium dark UI.
+
+---
+
+## Animations
+
+### Hover Effects
+
+```tsx
+// Card hover
+<div className="transition-all duration-300 hover:scale-[1.02]">
+  Card content
+</div>
+
+// Button hover
+<button className="transition-colors duration-200 hover:bg-[#6bb890]">
+  Button
+</button>
+
+// Image hover
+<img className="transition-transform duration-700 hover:scale-105" />
+```
+
+### Scroll Reveal
+
+```tsx
+// npm install react-intersection-observer
+import { useInView } from 'react-intersection-observer'
+
+function Component() {
+  const { ref, inView } = useInView({ triggerOnce: true, threshold: 0.1 })
+  
+  return (
+    <div 
+      ref={ref}
+      className={`transition-all duration-700 ${
+        inView ? 'opacity-100 translate-y-0' : 'opacity-0 translate-y-8'
+      }`}
+    >
+      Content
+    </div>
+  )
+}
+```
+
+---
+
+## Accessibility
+
+### Color Contrast
+
+- White on `#0a0f0d`: 21:1 (AAA) ✅
+- `slate-300` on `#0a0f0d`: 12.6:1 (AAA) ✅
+- `#80cca5` on `#0a0f0d`: 7.8:1 (AAA) ✅
+
+### Focus States
+
+```tsx
+<button className="focus:ring-2 focus:ring-[#80cca5] focus:outline-none">
+  Button
+</button>
+```
+
+### Semantic HTML
+
+```tsx
+<nav>
+  <ul>
+    <li><a href="#">Link</a></li>
+  </ul>
+</nav>
+```
+
+---
+
+## Quick Wins (Instant Premium Feel)
+
+1. Replace all backgrounds with `#0a0f0d`
+2. Use only white and slate-300 for text
+3. Make all CTAs `#80cca5` green
+4. Add backdrop-blur-xl to all cards
+5. Use rounded-2xl for cards, rounded-full for buttons
+6. Add one radial glow to hero section
+7. Increase padding (py-24 for sections, p-8 for cards)
+8. Add hover effects to all interactive elements
+
+---
+
+## Common Mistakes
+
+❌ **DON'T**:
+- Use light backgrounds (`bg-white`, `bg-slate-100`)
+- Use `dark:` variants (this is dark-only)
+- Mix multiple accent colors
+- Use high-opacity glass (`bg-white/50`)
+- Skip backdrop blur on glass elements
+- Use small padding (looks cramped)
+- Forget hover states
+- Ignore mobile layout
+
+✅ **DO**:
+- Stick to the color palette
+- Use consistent spacing (multiples of 4)
+- Add subtle animations
+- Test on mobile first
+- Keep glass opacity low
+- Use radial glows sparingly
+- Maintain high contrast for text
+
+---
+
+## Final Checklist
+
+Before launching, verify:
+
+- [ ] All backgrounds are `#0a0f0d` or `black`
+- [ ] All headings are `text-white`
+- [ ] All body text is `text-slate-300`
+- [ ] All CTAs are `#80cca5` green
+- [ ] All cards have `backdrop-blur-xl`
+- [ ] All cards use `bg-white/[0.02]`
+- [ ] All buttons have hover states
+- [ ] All forms have focus states
+- [ ] Spacing uses multiples of 4
+- [ ] Mobile layout tested
+- [ ] Radial glows are subtle (not overwhelming)
+- [ ] No light mode variants (`dark:`)
+- [ ] Contrast ratios meet WCAG AA minimum
+
+---
+
+**Time to premium**: 30-60 minutes
+**Maintenance**: Easy (4 components, 1 color palette)
+**Scalability**: High (reusable components)
+
+---
+
+## Related Files
+
+- [Colors & Typography](./premium-dark-ui-colors.md)
+- [Components](./premium-dark-ui-components.md)
+- [Layouts](./premium-dark-ui-layouts.md)
+- [Full System Guide](./premium-dark-ui-system.md)

.opencode/context/ui/web/design/guides/premium-dark-ui-colors.md

@@ -0,0 +1,164 @@
+# Premium Dark UI - Colors & Typography
+
+Quick reference for colors, spacing, and typography in premium dark UI.
+
+---
+
+## Color Palette
+
+```css
+/* Backgrounds */
+--bg-deep-dark: #0a0f0d;      /* Main background */
+--bg-black: #000000;           /* Alternate sections */
+
+/* Text */
+--text-heading: #ffffff;       /* Headings */
+--text-body: #cbd5e1;          /* Body (slate-300) */
+--text-muted: #94a3b8;         /* Muted (slate-400) */
+
+/* Accent */
+--accent: #80cca5;             /* Green - CTAs, links, highlights */
+--accent-hover: #6bb890;       /* Hover state */
+
+/* Glass */
+--glass-bg: rgba(255, 255, 255, 0.02);
+--glass-border: rgba(255, 255, 255, 0.1);
+```
+
+**Rule**: Use ONLY these colors. No exceptions.
+
+---
+
+## Spacing System
+
+```css
+/* Use these values ONLY */
+py-4   /* 16px - Small spacing */
+py-8   /* 32px - Medium spacing */
+py-12  /* 48px - Large spacing */
+py-24  /* 96px - Section spacing */
+
+px-4   /* 16px - Mobile padding */
+px-8   /* 32px - Card padding */
+px-12  /* 48px - Large card padding */
+
+gap-4  /* 16px - Small gaps */
+gap-8  /* 32px - Medium gaps */
+gap-12 /* 48px - Large gaps */
+
+mb-4   /* 16px - Small margin bottom */
+mb-6   /* 24px - Medium margin bottom */
+mb-8   /* 32px - Large margin bottom */
+mb-16  /* 64px - Section margin bottom */
+```
+
+**Rule**: Stick to multiples of 4 (4, 8, 12, 16, 24, 32, 48, 64, 96).
+
+---
+
+## Typography Scale
+
+```tsx
+// Page Title (H1)
+<h1 className="text-4xl md:text-6xl font-bold text-white mb-8">
+  Page Title
+</h1>
+
+// Section Title (H2)
+<h2 className="text-3xl md:text-5xl font-bold text-white mb-6">
+  Section Title <span className="text-[#80cca5]">Accent</span>
+</h2>
+
+// Subsection (H3)
+<h3 className="text-2xl md:text-4xl font-bold text-white mb-4">
+  Subsection
+</h3>
+
+// Body Text
+<p className="text-lg text-slate-300 mb-4">
+  Body text goes here
+</p>
+
+// Muted Text
+<p className="text-sm text-slate-400">
+  Secondary information
+</p>
+
+// Accent Text
+<p className="text-lg font-semibold text-[#80cca5]">
+  Call to action text
+</p>
+```
+
+---
+
+## Buttons & Links
+
+```tsx
+// Primary CTA Button
+<button className="
+  px-8 py-4 
+  rounded-full 
+  bg-[#80cca5] 
+  hover:bg-[#6bb890] 
+  text-white 
+  font-semibold 
+  transition-all 
+  shadow-lg 
+  hover:shadow-xl
+">
+  Primary Action
+</button>
+
+// Secondary Button
+<button className="
+  px-6 py-3 
+  rounded-full 
+  bg-white/[0.02] 
+  border border-white/10 
+  hover:border-[#80cca5]/30 
+  text-white 
+  font-medium 
+  transition-all
+">
+  Secondary Action
+</button>
+
+// Link
+<a href="#" className="text-[#80cca5] hover:text-[#6bb890] transition-colors">
+  Link Text
+</a>
+```
+
+---
+
+## Form Inputs
+
+```tsx
+// Text Input
+<input 
+  type="text"
+  className="
+    w-full px-4 py-3 rounded-lg 
+    border border-[#80cca5]/20 
+    bg-slate-900/50 
+    text-white 
+    placeholder:text-slate-500 
+    focus:ring-2 focus:ring-[#80cca5] focus:border-transparent
+  "
+  placeholder="Enter text"
+/>
+
+// Label
+<label className="text-slate-200 font-medium mb-2 block">
+  Field Label
+</label>
+```
+
+---
+
+## Related Files
+
+- [Components](./premium-dark-ui-components.md)
+- [Layouts](./premium-dark-ui-layouts.md)
+- [Advanced](./premium-dark-ui-advanced.md)

.opencode/context/ui/web/design/guides/premium-dark-ui-components.md

@@ -0,0 +1,142 @@
+# Premium Dark UI - Core Components
+
+The 4 building blocks for premium dark UI.
+
+---
+
+## A. Section Wrapper
+
+```tsx
+// PremiumSection.tsx
+export function PremiumSection({ children, withGlow = true }) {
+  return (
+    <section className="relative py-24 px-4 bg-[#0a0f0d] overflow-hidden">
+      {withGlow && (
+        <div 
+          className="absolute top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2 w-[600px] h-[600px] pointer-events-none"
+          style={{
+            background: 'radial-gradient(circle, rgba(128, 204, 165, 0.15) 0%, transparent 70%)',
+            opacity: 0.15
+          }}
+        />
+      )}
+      <div className="max-w-7xl mx-auto relative z-10">
+        {children}
+      </div>
+    </section>
+  )
+}
+```
+
+---
+
+## B. Glass Card
+
+```tsx
+// PremiumCard.tsx
+export function PremiumCard({ children, className = "" }) {
+  return (
+    <div className={`
+      p-8 rounded-2xl 
+      bg-white/[0.02] 
+      border border-white/10 
+      backdrop-blur-xl 
+      shadow-2xl 
+      transition-all duration-300
+      hover:bg-white/[0.04] 
+      hover:border-[#80cca5]/30
+      ${className}
+    `}>
+      {children}
+    </div>
+  )
+}
+```
+
+---
+
+## C. Heading
+
+```tsx
+// PremiumHeading.tsx
+export function PremiumHeading({ children, accent, as: Tag = 'h2' }) {
+  return (
+    <Tag className="text-3xl md:text-5xl font-bold text-white mb-6">
+      {children}
+      {accent && <span className="text-[#80cca5]"> {accent}</span>}
+    </Tag>
+  )
+}
+```
+
+---
+
+## D. Radial Glow
+
+```tsx
+// RadialGlow.tsx
+export function RadialGlow({ className = "" }) {
+  return (
+    <div 
+      className={`absolute -translate-x-1/2 -translate-y-1/2 w-[600px] h-[600px] pointer-events-none ${className}`}
+      style={{
+        background: 'radial-gradient(circle, rgba(128, 204, 165, 0.15) 0%, transparent 70%)',
+        opacity: 0.15
+      }}
+    />
+  )
+}
+```
+
+---
+
+## Glassmorphism Rules
+
+✅ **DO**:
+- Use `bg-white/[0.02]` for card backgrounds
+- Add `backdrop-blur-xl` for blur effect
+- Use `border-white/10` for subtle borders
+- Keep opacity LOW (0.02 to 0.04)
+- Layer multiple glass surfaces
+
+❌ **DON'T**:
+- Use high opacity (breaks glass effect)
+- Skip backdrop blur (looks flat)
+- Use on light backgrounds (invisible)
+- Overuse (reserve for cards/panels)
+
+---
+
+## Radial Glow Usage
+
+### When to Use:
+- ✅ Hero sections (large, centered)
+- ✅ Important CTAs (behind forms)
+- ✅ Section breaks (corner glows)
+- ❌ Every section (overwhelming)
+- ❌ Small components (too subtle)
+
+### Sizes:
+- **Small**: 400px (subtle accent)
+- **Medium**: 600px (default)
+- **Large**: 800px (hero sections)
+
+### Positioning:
+```tsx
+// Centered
+<RadialGlow className="top-1/2 left-1/2" />
+
+// Top-left
+<RadialGlow className="top-0 left-0" />
+
+// Bottom-right
+<RadialGlow className="bottom-0 right-0" />
+```
+
+---
+
+## Related Files
+
+- [Colors & Typography](./premium-dark-ui-colors.md)
+- [Layouts](./premium-dark-ui-layouts.md)
+- [Advanced](./premium-dark-ui-advanced.md)

.opencode/context/ui/web/design/guides/premium-dark-ui-layouts.md

@@ -0,0 +1,173 @@
+# Premium Dark UI - Layouts
+
+Common layout patterns for premium dark UI.
+
+---
+
+## Hero Section
+
+```tsx
+<PremiumSection>
+  <div className="max-w-4xl mx-auto text-center">
+    <PremiumHeading as="h1" accent="AI">
+      Build Production
+    </PremiumHeading>
+    <p className="text-xl text-slate-300 mb-8">
+      Your subtitle goes here
+    </p>
+    <button className="px-8 py-4 rounded-full bg-[#80cca5] hover:bg-[#6bb890] text-white font-semibold transition-all shadow-lg">
+      Get Started
+    </button>
+  </div>
+</PremiumSection>
+```
+
+---
+
+## Feature Grid
+
+```tsx
+<PremiumSection>
+  <div className="text-center mb-16">
+    <PremiumHeading accent="Features">
+      Powerful
+    </PremiumHeading>
+  </div>
+  <div className="grid md:grid-cols-3 gap-8">
+    {features.map((feature) => (
+      <PremiumCard key={feature.id}>
+        <Icon className="size-12 text-[#80cca5] mb-4" />
+        <h3 className="text-xl font-bold text-white mb-2">
+          {feature.title}
+        </h3>
+        <p className="text-slate-300">
+          {feature.description}
+        </p>
+      </PremiumCard>
+    ))}
+  </div>
+</PremiumSection>
+```
+
+---
+
+## CTA Section
+
+```tsx
+<PremiumSection>
+  <div className="max-w-3xl mx-auto">
+    <div className="text-center mb-12">
+      <PremiumHeading accent="Started">
+        Get
+      </PremiumHeading>
+      <p className="text-xl text-slate-300">
+        Join thousands of users
+      </p>
+    </div>
+    <PremiumCard className="p-8 md:p-12">
+      <form className="space-y-6">
+        <input 
+          type="email"
+          placeholder="you@example.com"
+          className="w-full px-4 py-3 rounded-lg border border-[#80cca5]/20 bg-slate-900/50 text-white placeholder:text-slate-500 focus:ring-2 focus:ring-[#80cca5] focus:border-transparent"
+        />
+        <button className="w-full px-8 py-4 rounded-full bg-[#80cca5] hover:bg-[#6bb890] text-white font-semibold transition-all">
+          Sign Up
+        </button>
+      </form>
+    </PremiumCard>
+  </div>
+</PremiumSection>
+```
+
+---
+
+## Responsive Design
+
+```tsx
+// Mobile: Stack, Desktop: Grid
+<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-8">
+  {/* Items */}
+</div>
+
+// Mobile: Full width, Desktop: Constrained
+<div className="w-full lg:max-w-4xl mx-auto">
+  {/* Content */}
+</div>
+
+// Mobile: Small text, Desktop: Large text
+<h2 className="text-3xl md:text-5xl">
+  Responsive Heading
+</h2>
+
+// Mobile: Center, Desktop: Left
+<div className="text-center lg:text-left">
+  {/* Content */}
+</div>
+```
+
+**Breakpoints**:
+- `sm`: 640px (tablets)
+- `md`: 768px (tablets/small laptops)
+- `lg`: 1024px (laptops)
+- `xl`: 1280px (desktops)
+
+---
+
+## Starter Template
+
+```tsx
+export default function Page() {
+  return (
+    <div className="min-h-screen bg-[#0a0f0d]">
+      {/* Hero */}
+      <PremiumSection>
+        <div className="max-w-4xl mx-auto text-center">
+          <PremiumHeading as="h1" accent="Premium">
+            Your
+          </PremiumHeading>
+          <p className="text-xl text-slate-300 mb-8">Subtitle here</p>
+          <button className="px-8 py-4 rounded-full bg-[#80cca5] hover:bg-[#6bb890] text-white font-semibold">
+            Get Started
+          </button>
+        </div>
+      </PremiumSection>
+
+      {/* Features */}
+      <PremiumSection>
+        <div className="text-center mb-16">
+          <PremiumHeading accent="Features">Amazing</PremiumHeading>
+        </div>
+        <div className="grid md:grid-cols-3 gap-8">
+          <PremiumCard>
+            <h3 className="text-xl font-bold text-white mb-2">Feature 1</h3>
+            <p className="text-slate-300">Description</p>
+          </PremiumCard>
+          {/* More cards */}
+        </div>
+      </PremiumSection>
+
+      {/* CTA */}
+      <PremiumSection>
+        <div className="max-w-3xl mx-auto text-center">
+          <PremiumHeading accent="Started">Get</PremiumHeading>
+          <PremiumCard className="p-8 md:p-12">
+            <form className="space-y-6">
+              <input type="email" placeholder="you@example.com" className="w-full px-4 py-3 rounded-lg border border-[#80cca5]/20 bg-slate-900/50 text-white" />
+              <button className="w-full px-8 py-4 rounded-full bg-[#80cca5] text-white font-semibold">Sign Up</button>
+            </form>
+          </PremiumCard>
+        </div>
+      </PremiumSection>
+    </div>
+  )
+}
+```
+
+---
+
+## Related Files
+
+- [Colors & Typography](./premium-dark-ui-colors.md)
+- [Components](./premium-dark-ui-components.md)
+- [Advanced](./premium-dark-ui-advanced.md)

.opencode/context/ui/web/design/guides/premium-dark-ui-quick-start.md

@@ -1,638 +0,0 @@
-# Premium Dark UI - Quick Start Guide
-
-**Goal**: Create a sophisticated, modern dark website with glassmorphism and depth.
-
-**Time to implement**: 30-60 minutes
-
----
-
-## 1. COLOR PALETTE (Copy This)
-
-```css
-/* Backgrounds */
---bg-deep-dark: #0a0f0d;      /* Main background */
---bg-black: #000000;           /* Alternate sections */
-
-/* Text */
---text-heading: #ffffff;       /* Headings */
---text-body: #cbd5e1;          /* Body (slate-300) */
---text-muted: #94a3b8;         /* Muted (slate-400) */
-
-/* Accent */
---accent: #80cca5;             /* Green - CTAs, links, highlights */
---accent-hover: #6bb890;       /* Hover state */
-
-/* Glass */
---glass-bg: rgba(255, 255, 255, 0.02);
---glass-border: rgba(255, 255, 255, 0.1);
-```
-
-**Rule**: Use ONLY these colors. No exceptions.
-
----
-
-## 2. CORE COMPONENTS (4 Building Blocks)
-
-### A. Section Wrapper
-
-```tsx
-// PremiumSection.tsx
-export function PremiumSection({ children, withGlow = true }) {
-  return (
-    <section className="relative py-24 px-4 bg-[#0a0f0d] overflow-hidden">
-      {withGlow && (
-        <div 
-          className="absolute top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2 w-[600px] h-[600px] pointer-events-none"
-          style={{
-            background: 'radial-gradient(circle, rgba(128, 204, 165, 0.15) 0%, transparent 70%)',
-            opacity: 0.15
-          }}
-        />
-      )}
-      <div className="max-w-7xl mx-auto relative z-10">
-        {children}
-      </div>
-    </section>
-  )
-}
-```
-
-### B. Glass Card
-
-```tsx
-// PremiumCard.tsx
-export function PremiumCard({ children, className = "" }) {
-  return (
-    <div className={`
-      p-8 rounded-2xl 
-      bg-white/[0.02] 
-      border border-white/10 
-      backdrop-blur-xl 
-      shadow-2xl 
-      transition-all duration-300
-      hover:bg-white/[0.04] 
-      hover:border-[#80cca5]/30
-      ${className}
-    `}>
-      {children}
-    </div>
-  )
-}
-```
-
-### C. Heading
-
-```tsx
-// PremiumHeading.tsx
-export function PremiumHeading({ children, accent, as: Tag = 'h2' }) {
-  return (
-    <Tag className="text-3xl md:text-5xl font-bold text-white mb-6">
-      {children}
-      {accent && <span className="text-[#80cca5]"> {accent}</span>}
-    </Tag>
-  )
-}
-```
-
-### D. Radial Glow
-
-```tsx
-// RadialGlow.tsx
-export function RadialGlow({ className = "" }) {
-  return (
-    <div 
-      className={`absolute -translate-x-1/2 -translate-y-1/2 w-[600px] h-[600px] pointer-events-none ${className}`}
-      style={{
-        background: 'radial-gradient(circle, rgba(128, 204, 165, 0.15) 0%, transparent 70%)',
-        opacity: 0.15
-      }}
-    />
-  )
-}
-```
-
----
-
-## 3. SPACING SYSTEM
-
-```css
-/* Use these values ONLY */
-py-4   /* 16px - Small spacing */
-py-8   /* 32px - Medium spacing */
-py-12  /* 48px - Large spacing */
-py-24  /* 96px - Section spacing */
-
-px-4   /* 16px - Mobile padding */
-px-8   /* 32px - Card padding */
-px-12  /* 48px - Large card padding */
-
-gap-4  /* 16px - Small gaps */
-gap-8  /* 32px - Medium gaps */
-gap-12 /* 48px - Large gaps */
-
-mb-4   /* 16px - Small margin bottom */
-mb-6   /* 24px - Medium margin bottom */
-mb-8   /* 32px - Large margin bottom */
-mb-16  /* 64px - Section margin bottom */
-```
-
-**Rule**: Stick to multiples of 4 (4, 8, 12, 16, 24, 32, 48, 64, 96).
-
----
-
-## 4. TYPOGRAPHY SCALE
-
-```tsx
-// Page Title (H1)
-<h1 className="text-4xl md:text-6xl font-bold text-white mb-8">
-  Page Title
-</h1>
-
-// Section Title (H2)
-<h2 className="text-3xl md:text-5xl font-bold text-white mb-6">
-  Section Title <span className="text-[#80cca5]">Accent</span>
-</h2>
-
-// Subsection (H3)
-<h3 className="text-2xl md:text-4xl font-bold text-white mb-4">
-  Subsection
-</h3>
-
-// Body Text
-<p className="text-lg text-slate-300 mb-4">
-  Body text goes here
-</p>
-
-// Muted Text
-<p className="text-sm text-slate-400">
-  Secondary information
-</p>
-
-// Accent Text
-<p className="text-lg font-semibold text-[#80cca5]">
-  Call to action text
-</p>
-```
-
----
-
-## 5. BUTTONS & LINKS
-
-```tsx
-// Primary CTA Button
-<button className="
-  px-8 py-4 
-  rounded-full 
-  bg-[#80cca5] 
-  hover:bg-[#6bb890] 
-  text-white 
-  font-semibold 
-  transition-all 
-  shadow-lg 
-  hover:shadow-xl
-">
-  Primary Action
-</button>
-
-// Secondary Button
-<button className="
-  px-6 py-3 
-  rounded-full 
-  bg-white/[0.02] 
-  border border-white/10 
-  hover:border-[#80cca5]/30 
-  text-white 
-  font-medium 
-  transition-all
-">
-  Secondary Action
-</button>
-
-// Link
-<a href="#" className="text-[#80cca5] hover:text-[#6bb890] transition-colors">
-  Link Text
-</a>
-```
-
----
-
-## 6. FORM INPUTS
-
-```tsx
-// Text Input
-<input 
-  type="text"
-  className="
-    w-full 
-    px-4 py-3 
-    rounded-lg 
-    border border-[#80cca5]/20 
-    bg-slate-900/50 
-    text-white 
-    placeholder:text-slate-500 
-    focus:ring-2 
-    focus:ring-[#80cca5] 
-    focus:border-transparent
-  "
-  placeholder="Enter text"
-/>
-
-// Textarea
-<textarea 
-  className="
-    w-full 
-    px-4 py-3 
-    rounded-lg 
-    border border-[#80cca5]/20 
-    bg-slate-900/50 
-    text-white 
-    placeholder:text-slate-500 
-    focus:ring-2 
-    focus:ring-[#80cca5] 
-    focus:border-transparent 
-    resize-none
-  "
-  rows={4}
-/>
-
-// Label
-<label className="text-slate-200 font-medium mb-2 block">
-  Field Label
-</label>
-```
-
----
-
-## 7. COMMON LAYOUTS
-
-### Hero Section
-
-```tsx
-<PremiumSection>
-  <div className="max-w-4xl mx-auto text-center">
-    <PremiumHeading as="h1" accent="AI">
-      Build Production
-    </PremiumHeading>
-    <p className="text-xl text-slate-300 mb-8">
-      Your subtitle goes here
-    </p>
-    <button className="px-8 py-4 rounded-full bg-[#80cca5] hover:bg-[#6bb890] text-white font-semibold transition-all shadow-lg">
-      Get Started
-    </button>
-  </div>
-</PremiumSection>
-```
-
-### Feature Grid
-
-```tsx
-<PremiumSection>
-  <div className="text-center mb-16">
-    <PremiumHeading accent="Features">
-      Powerful
-    </PremiumHeading>
-  </div>
-  <div className="grid md:grid-cols-3 gap-8">
-    {features.map((feature) => (
-      <PremiumCard key={feature.id}>
-        <Icon className="size-12 text-[#80cca5] mb-4" />
-        <h3 className="text-xl font-bold text-white mb-2">
-          {feature.title}
-        </h3>
-        <p className="text-slate-300">
-          {feature.description}
-        </p>
-      </PremiumCard>
-    ))}
-  </div>
-</PremiumSection>
-```
-
-### CTA Section
-
-```tsx
-<PremiumSection>
-  <div className="max-w-3xl mx-auto">
-    <div className="text-center mb-12">
-      <PremiumHeading accent="Started">
-        Get
-      </PremiumHeading>
-      <p className="text-xl text-slate-300">
-        Join thousands of users
-      </p>
-    </div>
-    <PremiumCard className="p-8 md:p-12">
-      <form className="space-y-6">
-        <input 
-          type="email"
-          placeholder="you@example.com"
-          className="w-full px-4 py-3 rounded-lg border border-[#80cca5]/20 bg-slate-900/50 text-white placeholder:text-slate-500 focus:ring-2 focus:ring-[#80cca5] focus:border-transparent"
-        />
-        <button className="w-full px-8 py-4 rounded-full bg-[#80cca5] hover:bg-[#6bb890] text-white font-semibold transition-all">
-          Sign Up
-        </button>
-      </form>
-    </PremiumCard>
-  </div>
-</PremiumSection>
-```
-
----
-
-## 8. GLASSMORPHISM RULES
-
-✅ **DO**:
-- Use `bg-white/[0.02]` for card backgrounds
-- Add `backdrop-blur-xl` for blur effect
-- Use `border-white/10` for subtle borders
-- Keep opacity LOW (0.02 to 0.04)
-- Layer multiple glass surfaces
-
-❌ **DON'T**:
-- Use high opacity (breaks glass effect)
-- Skip backdrop blur (looks flat)
-- Use on light backgrounds (invisible)
-- Overuse (reserve for cards/panels)
-
-**Example**:
-```tsx
-<div className="bg-white/[0.02] border border-white/10 backdrop-blur-xl">
-  Glass content
-</div>
-```
-
----
-
-## 9. RADIAL GLOW USAGE
-
-### When to Use:
-- ✅ Hero sections (large, centered)
-- ✅ Important CTAs (behind forms)
-- ✅ Section breaks (corner glows)
-- ❌ Every section (overwhelming)
-- ❌ Small components (too subtle)
-
-### Sizes:
-- **Small**: 400px (subtle accent)
-- **Medium**: 600px (default)
-- **Large**: 800px (hero sections)
-
-### Positioning:
-```tsx
-// Centered
-<RadialGlow className="top-1/2 left-1/2" />
-
-// Top-left
-<RadialGlow className="top-0 left-0" />
-
-// Bottom-right
-<RadialGlow className="bottom-0 right-0" />
-```
-
----
-
-## 10. RESPONSIVE DESIGN
-
-```tsx
-// Mobile: Stack, Desktop: Grid
-<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-8">
-  {/* Items */}
-</div>
-
-// Mobile: Full width, Desktop: Constrained
-<div className="w-full lg:max-w-4xl mx-auto">
-  {/* Content */}
-</div>
-
-// Mobile: Small text, Desktop: Large text
-<h2 className="text-3xl md:text-5xl">
-  Responsive Heading
-</h2>
-
-// Mobile: Center, Desktop: Left
-<div className="text-center lg:text-left">
-  {/* Content */}
-</div>
-```
-
-**Breakpoints**:
-- `sm`: 640px (tablets)
-- `md`: 768px (tablets/small laptops)
-- `lg`: 1024px (laptops)
-- `xl`: 1280px (desktops)
-
----
-
-## 11. ANIMATIONS
-
-### Hover Effects
-
-```tsx
-// Card hover
-<div className="transition-all duration-300 hover:scale-[1.02]">
-  Card content
-</div>
-
-// Button hover
-<button className="transition-colors duration-200 hover:bg-[#6bb890]">
-  Button
-</button>
-
-// Image hover
-<img className="transition-transform duration-700 hover:scale-105" />
-```
-
-### Scroll Reveal (Optional)
-
-```tsx
-// Install: npm install react-intersection-observer
-import { useInView } from 'react-intersection-observer'
-
-function Component() {
-  const { ref, inView } = useInView({ triggerOnce: true, threshold: 0.1 })
-  
-  return (
-    <div 
-      ref={ref}
-      className={`transition-all duration-700 ${
-        inView ? 'opacity-100 translate-y-0' : 'opacity-0 translate-y-8'
-      }`}
-    >
-      Content
-    </div>
-  )
-}
-```
-
----
-
-## 12. ACCESSIBILITY CHECKLIST
-
-✅ **Color Contrast**:
-- White on `#0a0f0d`: 21:1 (AAA) ✅
-- `slate-300` on `#0a0f0d`: 12.6:1 (AAA) ✅
-- `#80cca5` on `#0a0f0d`: 7.8:1 (AAA) ✅
-
-✅ **Focus States**:
-```tsx
-<button className="focus:ring-2 focus:ring-[#80cca5] focus:outline-none">
-  Button
-</button>
-```
-
-✅ **Semantic HTML**:
-```tsx
-<nav>
-  <ul>
-    <li><a href="#">Link</a></li>
-  </ul>
-</nav>
-```
-
-✅ **Alt Text**:
-```tsx
-<img src="..." alt="Descriptive text" />
-```
-
----
-
-## 13. QUICK WINS (Instant Premium Feel)
-
-1. **Replace all backgrounds** with `#0a0f0d`
-2. **Use only white and slate-300** for text
-3. **Make all CTAs** `#80cca5` green
-4. **Add backdrop-blur-xl** to all cards
-5. **Use rounded-2xl** for cards, `rounded-full` for buttons
-6. **Add one radial glow** to hero section
-7. **Increase padding** (py-24 for sections, p-8 for cards)
-8. **Add hover effects** to all interactive elements
-
----
-
-## 14. COMMON MISTAKES TO AVOID
-
-❌ **Don't**:
-- Use light backgrounds (`bg-white`, `bg-slate-100`)
-- Use `dark:` variants (this is dark-only)
-- Mix multiple accent colors
-- Use high-opacity glass (`bg-white/50`)
-- Skip backdrop blur on glass elements
-- Use small padding (looks cramped)
-- Forget hover states
-- Ignore mobile layout
-
-✅ **Do**:
-- Stick to the color palette
-- Use consistent spacing (multiples of 4)
-- Add subtle animations
-- Test on mobile first
-- Keep glass opacity low
-- Use radial glows sparingly
-- Maintain high contrast for text
-
----
-
-## 15. COPY-PASTE STARTER TEMPLATE
-
-```tsx
-import React from 'react'
-
-// 1. Copy the 4 core components (Section A-D above)
-// 2. Use this page structure:
-export default function Page() {
-  return (
-    <div className="min-h-screen bg-[#0a0f0d]">
-      {/* Hero */}
-      <PremiumSection>
-        <div className="max-w-4xl mx-auto text-center">
-          <PremiumHeading as="h1" accent="Premium">
-            Your
-          </PremiumHeading>
-          <p className="text-xl text-slate-300 mb-8">
-            Subtitle goes here
-          </p>
-          <button className="px-8 py-4 rounded-full bg-[#80cca5] hover:bg-[#6bb890] text-white font-semibold transition-all shadow-lg">
-            Get Started
-          </button>
-        </div>
-      </PremiumSection>
-
-      {/* Features */}
-      <PremiumSection>
-        <div className="text-center mb-16">
-          <PremiumHeading accent="Features">
-            Amazing
-          </PremiumHeading>
-        </div>
-        <div className="grid md:grid-cols-3 gap-8">
-          <PremiumCard>
-            <h3 className="text-xl font-bold text-white mb-2">Feature 1</h3>
-            <p className="text-slate-300">Description</p>
-          </PremiumCard>
-          <PremiumCard>
-            <h3 className="text-xl font-bold text-white mb-2">Feature 2</h3>
-            <p className="text-slate-300">Description</p>
-          </PremiumCard>
-          <PremiumCard>
-            <h3 className="text-xl font-bold text-white mb-2">Feature 3</h3>
-            <p className="text-slate-300">Description</p>
-          </PremiumCard>
-        </div>
-      </PremiumSection>
-
-      {/* CTA */}
-      <PremiumSection>
-        <div className="max-w-3xl mx-auto text-center">
-          <PremiumHeading accent="Started">
-            Get
-          </PremiumHeading>
-          <PremiumCard className="p-8 md:p-12">
-            <form className="space-y-6">
-              <input 
-                type="email"
-                placeholder="you@example.com"
-                className="w-full px-4 py-3 rounded-lg border border-[#80cca5]/20 bg-slate-900/50 text-white placeholder:text-slate-500 focus:ring-2 focus:ring-[#80cca5] focus:border-transparent"
-              />
-              <button className="w-full px-8 py-4 rounded-full bg-[#80cca5] hover:bg-[#6bb890] text-white font-semibold transition-all">
-                Sign Up
-              </button>
-            </form>
-          </PremiumCard>
-        </div>
-      </PremiumSection>
-    </div>
-  )
-}
-```
-
----
-
-## 16. FINAL CHECKLIST
-
-Before launching, verify:
-
-- [ ] All backgrounds are `#0a0f0d` or `black`
-- [ ] All headings are `text-white`
-- [ ] All body text is `text-slate-300`
-- [ ] All CTAs are `#80cca5` green
-- [ ] All cards have `backdrop-blur-xl`
-- [ ] All cards use `bg-white/[0.02]`
-- [ ] All buttons have hover states
-- [ ] All forms have focus states
-- [ ] Spacing uses multiples of 4
-- [ ] Mobile layout tested
-- [ ] Radial glows are subtle (not overwhelming)
-- [ ] No light mode variants (`dark:`)
-- [ ] Contrast ratios meet WCAG AA minimum
-
----
-
-## DONE! 🎉
-
-You now have everything needed to create a premium dark UI.
-
-**Time to premium**: 30-60 minutes
-**Maintenance**: Easy (4 components, 1 color palette)
-**Scalability**: High (reusable components)
-
-**Questions?** Reference the full guide: `.opencode/context/ui/web/design/guides/premium-dark-ui-system.md`

.opencode/context/ui/web/fonts-guide.md

@@ -0,0 +1,118 @@
+<!-- Context: ui/web/fonts | Priority: medium | Version: 1.0 | Updated: 2026-02-05 -->
+# Font Loading
+
+**Purpose**: Guidelines for loading and using web fonts
+
+---
+
+## Quick Reference
+
+**Recommended**: Google Fonts with preconnect
+
+```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">
+```
+
+---
+
+## Google Fonts (Recommended)
+
+### Basic Loading
+```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">
+```
+
+### Multiple Fonts
+```html
+<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">
+```
+
+### CSS Usage
+```css
+body {
+  font-family: 'Inter', sans-serif;
+}
+
+code, pre {
+  font-family: 'JetBrains Mono', monospace;
+}
+```
+
+---
+
+## Popular Font Combinations
+
+### Modern UI
+```html
+<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
+```html
+<link href="https://fonts.googleapis.com/css2?family=Roboto:wght@400;500;700&family=Roboto+Mono:wght@400;500&display=swap" rel="stylesheet">
+```
+
+### Editorial
+```html
+<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
+```html
+<link href="https://fonts.googleapis.com/css2?family=Poppins:wght@400;500;600;700&family=Space+Mono:wght@400;700&display=swap" rel="stylesheet">
+```
+
+---
+
+## Performance Optimization
+
+### Subset Fonts
+```html
+<!-- 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
+```html
+<link rel="preload" href="/fonts/inter-var.woff2" as="font" type="font/woff2" crossorigin>
+```
+
+### Self-Hosted Fonts
+```html
+<style>
+  @font-face {
+    font-family: 'Inter';
+    src: url('/fonts/inter-var.woff2') format('woff2');
+    font-weight: 100 900;
+    font-display: swap;
+  }
+</style>
+```
+
+---
+
+## Best Practices
+
+**Do ✅:**
+- Use `font-display: swap` (included in Google Fonts URL)
+- Preconnect to font servers
+- Limit to 2-3 font families
+- Subset when possible
+- Preload critical fonts
+
+**Don't ❌:**
+- Load too many font weights
+- Use fonts synchronously (blocking)
+- Load fonts you don't need
+
+---
+
+## Related
+
+- `images-guide.md` - Image guidelines
+- `icons-guide.md` - Icon systems
+- `cdn-resources.md` - CDN libraries

.opencode/context/ui/web/icons-guide.md

@@ -0,0 +1,144 @@
+<!-- Context: ui/web/icons | Priority: medium | Version: 1.0 | Updated: 2026-02-05 -->
+# Icon Systems
+
+**Purpose**: Guidelines for using icon libraries
+
+---
+
+## Quick Reference
+
+| Library | Loading | Recommended For |
+|---------|---------|-----------------|
+| Lucide | CDN script | Default choice |
+| Heroicons | Inline SVG | Tailwind projects |
+| Font Awesome | CDN CSS | Brand icons |
+
+---
+
+## Lucide Icons (Recommended Default)
+
+### Loading
+```html
+<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
+<i data-lucide="home"></i>
+<i data-lucide="user"></i>
+<i data-lucide="settings"></i>
+<i data-lucide="heart" class="w-6 h-6 text-red-500"></i>
+
+<script>lucide.createIcons();</script>
+```
+
+### Common Icons
+```
+Navigation: home, menu, x, chevron-down, arrow-left, arrow-right
+User: user, user-plus, users, user-check
+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
+
+### Usage (Inline SVG)
+```html
+<!-- Outline (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 1h3..." />
+</svg>
+
+<!-- Solid (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 7..." />
+</svg>
+```
+
+---
+
+## Font Awesome
+
+### Loading
+```html
+<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.0/css/all.min.css">
+```
+
+### Usage
+```html
+<!-- Solid -->
+<i class="fas fa-home"></i>
+<i class="fas fa-user"></i>
+
+<!-- Regular -->
+<i class="far fa-heart"></i>
+
+<!-- Brands -->
+<i class="fab fa-github"></i>
+<i class="fab fa-twitter"></i>
+
+<!-- Sizing -->
+<i class="fas fa-home fa-2x"></i>
+```
+
+---
+
+## Accessibility Best Practices
+
+```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>
+
+<!-- Decorative icon -->
+<div>
+  <i data-lucide="star" aria-hidden="true"></i>
+  <span>Featured</span>
+</div>
+
+<!-- Screen reader text -->
+<button>
+  <i data-lucide="search" aria-hidden="true"></i>
+  <span class="sr-only">Search</span>
+</button>
+```
+
+---
+
+## Custom 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>
+```
+
+---
+
+## Related
+
+- `images-guide.md` - Image guidelines
+- `fonts-guide.md` - Font loading
+- `cdn-resources.md` - CDN libraries

.opencode/context/ui/web/images-guide.md

@@ -0,0 +1,127 @@
+<!-- Context: ui/web/images | Priority: medium | Version: 1.0 | Updated: 2026-02-05 -->
+# Image Guidelines
+
+**Purpose**: Guidelines for placeholder and responsive images
+
+---
+
+## Quick Reference
+
+**Rule**: NEVER make up image URLs. Always use known placeholder services.
+
+| Service | Best For | URL Pattern |
+|---------|----------|-------------|
+| Unsplash | Real photos | `source.unsplash.com/random/WxH/?category` |
+| Placehold.co | Simple placeholders | `placehold.co/WxH` |
+| Picsum | Random photos | `picsum.photos/W/H` |
+
+---
+
+## Unsplash (Recommended)
+
+### Random Images
+```html
+<img src="https://source.unsplash.com/random/1200x800" alt="Random">
+<img src="https://source.unsplash.com/random/1200x800/?nature" alt="Nature">
+<img src="https://source.unsplash.com/random/1200x800/?technology" alt="Tech">
+```
+
+### Categories
+- 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
+<img src="https://images.unsplash.com/photo-1506905925346-21bda4d32df4" alt="Mountain">
+```
+
+---
+
+## Placehold.co
+
+```html
+<!-- Basic -->
+<img src="https://placehold.co/800x600" alt="Placeholder">
+
+<!-- Custom colors -->
+<img src="https://placehold.co/800x600/EEE/31343C" alt="Placeholder">
+
+<!-- With text -->
+<img src="https://placehold.co/800x600?text=Product+Image" alt="Product">
+
+<!-- Formats -->
+<img src="https://placehold.co/800x600.webp" alt="WebP">
+```
+
+---
+
+## Picsum Photos
+
+```html
+<img src="https://picsum.photos/800/600" alt="Random">
+<img src="https://picsum.photos/id/237/800/600" alt="Specific">
+<img src="https://picsum.photos/800/600?grayscale" alt="Grayscale">
+<img src="https://picsum.photos/800/600?blur=2" alt="Blurred">
+```
+
+---
+
+## Responsive Images
+
+```html
+<!-- 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, 50vw"
+  alt="Nature"
+  loading="lazy"
+>
+
+<!-- Picture element -->
+<picture>
+  <source srcset="url-1200" media="(min-width: 1024px)">
+  <source srcset="url-800" media="(min-width: 768px)">
+  <img src="url-400" alt="Responsive" loading="lazy">
+</picture>
+
+<!-- Background -->
+<div 
+  class="bg-cover bg-center"
+  style="background-image: url('https://source.unsplash.com/random/1200x800/?workspace')"
+  role="img"
+  aria-label="Workspace"
+></div>
+```
+
+---
+
+## Optimization
+
+```html
+<!-- Lazy loading -->
+<img src="image.jpg" loading="lazy" alt="Description">
+
+<!-- Modern formats with fallback -->
+<picture>
+  <source srcset="image.webp" type="image/webp">
+  <img src="image.jpg" alt="Description">
+</picture>
+```
+
+---
+
+## Related
+
+- `icons-guide.md` - Icon systems
+- `fonts-guide.md` - Font loading
+- `cdn-resources.md` - CDN libraries

.opencode/context/ui/web/navigation.md

@@ -12,11 +12,19 @@
 
 | File | Description | Priority |
 |------|-------------|----------|
-| [animation-patterns.md](animation-patterns.md) | CSS animations, transitions, micro-interactions | high |
+| [animation-basics.md](animation-basics.md) | Animation fundamentals, timing, easing | high |
+| [animation-components.md](animation-components.md) | Button, card, modal, dropdown animations | high |
+| [animation-chat.md](animation-chat.md) | Chat UI and message animations | medium |
+| [animation-loading.md](animation-loading.md) | Skeleton, spinner, progress animations | medium |
+| [animation-forms.md](animation-forms.md) | Form input and validation animations | medium |
+| [animation-advanced.md](animation-advanced.md) | Recipes, best practices, accessibility | medium |
 | [ui-styling-standards.md](ui-styling-standards.md) | CSS frameworks, Tailwind patterns, styling best practices | high |
 | [react-patterns.md](react-patterns.md) | Modern React patterns, hooks, component design | high |
 | [design-systems.md](design-systems.md) | Design system principles and component libraries | medium |
-| [design-assets.md](design-assets.md) | Icons, fonts, images, and asset management | medium |
+| [images-guide.md](images-guide.md) | Placeholder and responsive images | medium |
+| [icons-guide.md](icons-guide.md) | Icon systems (Lucide, Heroicons, FA) | medium |
+| [fonts-guide.md](fonts-guide.md) | Font loading and optimization | medium |
+| [cdn-resources.md](cdn-resources.md) | CDN libraries and resources | medium |
 
 ### Subcategories
 
@@ -34,8 +42,10 @@
 3. Reference `animation-patterns.md` (if animations needed)
 
 ### For animation work:
-1. Load `animation-patterns.md` (CSS animations, transitions)
-2. Reference `design/` subcategory for advanced patterns
+1. Load `animation-basics.md` (fundamentals, timing, easing)
+2. Load `animation-components.md` (UI component animations)
+3. Reference `animation-chat.md` for chat UI patterns
+4. Reference `animation-advanced.md` for recipes and accessibility
 
 ### For scroll animations:
 1. Navigate to `design/` subcategory
@@ -59,10 +69,10 @@ This subcategory covers:
 
 ## File Summaries
 
-### animation-patterns.md
-CSS animations, micro-interactions, and UI transitions. Covers timing standards, easing functions, button/card interactions, modals, loading states, and accessibility.
+### animation-basics.md, animation-components.md, animation-chat.md, animation-loading.md, animation-forms.md, animation-advanced.md
+CSS animations, micro-interactions, and UI transitions split into focused modules.
 
-**Key topics**: Animation micro-syntax, 60fps performance, reduced motion, chat UI animations
+**Key topics**: Animation micro-syntax, 60fps performance, reduced motion, chat UI animations, component patterns
 
 ### ui-styling-standards.md
 CSS framework usage, Tailwind CSS patterns, responsive design, and styling best practices.
@@ -79,10 +89,10 @@ Design system principles, component libraries, and maintaining consistency acros
 
 **Key topics**: Design tokens, component APIs, documentation, versioning
 
-### design-assets.md
-Managing icons, fonts, images, and other design assets in web applications.
+### images-guide.md, icons-guide.md, fonts-guide.md, cdn-resources.md
+Managing design assets in web applications - split into focused guides.
 
-**Key topics**: Icon libraries (Lucide, Font Awesome), web fonts, image optimization
+**Key topics**: Placeholder images, icon libraries (Lucide, Heroicons), web fonts, CDN resources
 
 ---
 
@@ -101,6 +111,6 @@ Managing icons, fonts, images, and other design assets in web applications.
 ---
 
 ## Statistics
-- Core files: 5
+- Core files: 8
 - Subcategories: 1 (design/)
-- **Total context files**: 5 + design subcategory
+- **Total context files**: 8 + design subcategory

packages/compatibility-layer/.eslintrc.json

@@ -0,0 +1,25 @@
+{
+  "parser": "@typescript-eslint/parser",
+  "parserOptions": {
+    "ecmaVersion": 2022,
+    "sourceType": "module",
+    "project": "./tsconfig.json"
+  },
+  "extends": [
+    "eslint:recommended",
+    "plugin:@typescript-eslint/recommended",
+    "plugin:@typescript-eslint/recommended-requiring-type-checking"
+  ],
+  "plugins": ["@typescript-eslint"],
+  "rules": {
+    "@typescript-eslint/explicit-function-return-type": "warn",
+    "@typescript-eslint/no-unused-vars": ["error", { "argsIgnorePattern": "^_" }],
+    "@typescript-eslint/no-explicit-any": "warn",
+    "no-console": ["warn", { "allow": ["warn", "error", "log"] }]
+  },
+  "env": {
+    "node": true,
+    "es2022": true
+  },
+  "ignorePatterns": ["**/__tests__/**", "**/*.test.ts", "**/*.spec.ts"]
+}

packages/compatibility-layer/.gitignore

@@ -0,0 +1,35 @@
+# Dependencies
+node_modules/
+
+# Build output
+dist/
+*.tsbuildinfo
+
+# Coverage
+coverage/
+.nyc_output/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Environment
+.env
+.env.local
+.env.*.local
+
+# Testing
+.vitest/

packages/compatibility-layer/README.md

@@ -0,0 +1,368 @@
+# @openagents-control/compatibility-layer
+
+> Compatibility layer for converting OpenAgents Control agents to/from other AI coding tools
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.4-blue)](https://www.typescriptlang.org/)
+[![Node](https://img.shields.io/badge/Node-%3E%3D18-green)](https://nodejs.org/)
+
+## Overview
+
+This package provides bidirectional conversion between OpenAgents Control (OAC) agent format and various AI coding tools:
+
+- **Cursor IDE** - VSCode-based AI editor with `.cursorrules`
+  [![Cursor IDE](./docs/migration-guides/contextscout-cursor.png)](./docs/migration-guides/oac-to-cursor.md)
+- **Claude Code** - Anthropic's official CLI with `config.json` and `agents/*.md`
+  [![Claude Code](./docs/migration-guides/claude-code-validation.png)](./docs/migration-guides/oac-to-claude.md)
+- **Windsurf** - AI-powered development environment with JSON config
+
+## Features
+
+- ✅ **Bidirectional conversion** - Convert OAC ↔ Tool formats
+- ✅ **Feature parity tracking** - Know what's supported in each tool
+- ✅ **Graceful degradation** - Handle unsupported features with warnings
+- ✅ **CLI tool** - Easy conversion from command line
+- ✅ **Batch migration** - Migrate entire projects at once
+- ✅ **Type-safe** - Full TypeScript with Zod validation
+- ✅ **Extensible** - Plugin architecture for new tools
+
+## Installation
+
+```bash
+# npm
+npm install @openagents-control/compatibility-layer
+
+# pnpm
+pnpm add @openagents-control/compatibility-layer
+```
+
+## Quick Start
+
+### CLI Usage
+
+```bash
+# Convert a single file
+oac-compat convert agent.md -f cursor -o .cursorrules
+
+# Convert with auto-detection of source format
+oac-compat convert .cursorrules -f oac -o agent.md
+
+# Validate compatibility before conversion
+oac-compat validate agent.md -t claude --strict
+
+# Migrate entire project
+oac-compat migrate ./agents -f claude --out-dir ./output
+
+# Preview migration without writing files
+oac-compat migrate ./agents -f windsurf --dry-run
+
+# Show platform capabilities
+oac-compat info cursor
+
+# Compare two platforms
+oac-compat info cursor --compare claude
+```
+
+### Programmatic Usage
+
+```typescript
+import {
+  loadAgent,
+  getAdapter,
+  translate,
+  analyzeCompatibility,
+} from "@openagents-control/compatibility-layer";
+
+// Load an OAC agent
+const agent = await loadAgent("./agent.md");
+
+// Check compatibility with target platform
+const compatibility = analyzeCompatibility(agent, "cursor");
+console.log("Compatible:", compatibility.compatible);
+console.log("Warnings:", compatibility.warnings);
+console.log("Blockers:", compatibility.blockers);
+
+// Convert to another format
+const adapter = getAdapter("claude");
+const result = await adapter.fromOAC(agent);
+
+if (result.success) {
+  for (const config of result.configs) {
+    console.log(`File: ${config.fileName}`);
+    console.log(config.content);
+  }
+}
+
+// Or use the translate function for quick conversion
+const translated = translate(agent, "cursor");
+```
+
+## CLI Commands
+
+### `convert` - Convert a single file
+
+```bash
+oac-compat convert <input> -f <format> [options]
+
+Options:
+  -f, --format <format>   Target format (oac, cursor, claude, windsurf)
+  -o, --output <path>     Output file path (stdout if omitted)
+  --from <format>         Source format (auto-detect if omitted)
+  --force                 Overwrite existing output file
+```
+
+### `validate` - Check compatibility
+
+```bash
+oac-compat validate <input> -t <format> [options]
+
+Options:
+  -t, --target <format>   Target format to validate against
+  --strict                Enable strict validation mode
+```
+
+### `migrate` - Batch migration
+
+```bash
+oac-compat migrate <source-dir> -f <format> [options]
+
+Options:
+  -f, --format <format>   Target format
+  -o, --out-dir <path>    Output directory
+  --dry-run               Preview without writing files
+  --force                 Overwrite existing files
+```
+
+### `info` - Platform information
+
+```bash
+oac-compat info [platform] [options]
+
+Options:
+  -d, --detailed          Show detailed capability information
+  -c, --compare <other>   Compare with another platform
+```
+
+### Global Options
+
+```bash
+-v, --verbose             Enable verbose output
+-q, --quiet               Suppress all output except errors
+--output-format <format>  Output format (text, json)
+```
+
+## Feature Parity Matrix
+
+| Feature              | OAC      | Cursor     | Claude | Windsurf |
+| -------------------- | -------- | ---------- | ------ | -------- |
+| **Config Format**    | YAML+MD  | Plain text | JSON   | JSON     |
+| **Multiple Agents**  | ✅       | ❌         | ✅     | ✅       |
+| **Tool Permissions** | Granular | Binary     | Binary | Binary   |
+| **Temperature**      | ✅       | ❌         | ❌     | ✅       |
+| **Skills/Contexts**  | ✅       | ❌         | ✅     | ⚠️       |
+| **Hooks**            | ✅       | ❌         | ✅     | ❌       |
+| **Model Selection**  | ✅       | ✅         | ✅     | ✅       |
+
+See [Feature Matrices](docs/feature-matrices.md) for detailed comparison.
+
+## Migration Guides
+
+- [Cursor → OAC](docs/migration-guides/cursor-to-oac.md) - Import from Cursor
+- [Claude → OAC](docs/migration-guides/claude-to-oac.md) - Import from Claude Code
+- [OAC → Cursor](docs/migration-guides/oac-to-cursor.md) - Export to Cursor
+- [OAC → Claude](docs/migration-guides/oac-to-claude.md) - Export to Claude Code
+- [OAC → Windsurf](docs/migration-guides/oac-to-windsurf.md) - Export to Windsurf
+
+## API Reference
+
+### Agent Loading
+
+```typescript
+import {
+  loadAgent,
+  loadAgents,
+  AgentLoader,
+} from "@openagents-control/compatibility-layer";
+
+// Load single agent
+const agent = await loadAgent("./agent.md");
+
+// Load all agents from directory
+const agents = await loadAgents("./agents/");
+
+// Using the loader class
+const loader = new AgentLoader();
+const agent = await loader.loadFromFile("./agent.md");
+```
+
+### Adapter Registry
+
+```typescript
+import {
+  registry,
+  getAdapter,
+  listAdapters,
+} from "@openagents-control/compatibility-layer";
+
+// Get adapter by name
+const adapter = getAdapter("cursor");
+
+// List all adapters
+const names = listAdapters(); // ['cursor', 'claude', 'windsurf']
+
+// Get all capabilities
+const capabilities = getAllCapabilities();
+```
+
+### Translation Engine
+
+```typescript
+import {
+  translate,
+  previewTranslation,
+  TranslationEngine,
+} from "@openagents-control/compatibility-layer";
+
+// Quick translate
+const result = translate(agent, "cursor");
+
+// Preview without converting
+const preview = previewTranslation(agent, "claude");
+console.log("Features lost:", preview.featuresLost);
+console.log("Features gained:", preview.featuresGained);
+
+// Using the engine for more control
+const engine = new TranslationEngine();
+const result = engine.translate(agent, "windsurf", {
+  preserveComments: true,
+  strictMode: false,
+});
+```
+
+### Mappers
+
+```typescript
+import {
+  mapToolFromOAC,
+  mapModelFromOAC,
+  mapPermissionsFromOAC,
+  mapContextPathFromOAC,
+} from "@openagents-control/compatibility-layer";
+
+// Map tool names
+mapToolFromOAC("bash", "cursor"); // { name: 'terminal', exact: true }
+
+// Map model identifiers
+mapModelFromOAC("claude-sonnet-4", "cursor"); // { id: 'claude-3-sonnet', exact: true }
+
+// Map permissions
+mapPermissionsFromOAC({ bash: { "*": "allow" } }, "claude");
+// { permissions: { bash: true }, warnings: [...] }
+```
+
+## Architecture
+
+```
+src/
+├── types.ts              # Zod schemas and TypeScript types
+├── index.ts              # Public API exports
+├── core/
+│   ├── AgentLoader.ts    # OAC agent file parser
+│   ├── AdapterRegistry.ts # Adapter management
+│   ├── CapabilityMatrix.ts # Feature compatibility
+│   └── TranslationEngine.ts # Orchestrates conversion
+├── adapters/
+│   ├── BaseAdapter.ts    # Abstract base class
+│   ├── CursorAdapter.ts  # Cursor IDE adapter
+│   ├── ClaudeAdapter.ts  # Claude Code adapter
+│   └── WindsurfAdapter.ts # Windsurf adapter
+├── mappers/
+│   ├── ToolMapper.ts     # Tool name translation
+│   ├── ModelMapper.ts    # Model ID translation
+│   ├── PermissionMapper.ts # Permission translation
+│   └── ContextMapper.ts  # Context path translation
+└── cli/
+    ├── index.ts          # CLI entry point
+    ├── types.ts          # CLI types
+    ├── utils.ts          # CLI utilities
+    └── commands/
+        ├── convert.ts    # convert command
+        ├── validate.ts   # validate command
+        ├── migrate.ts    # migrate command
+        └── info.ts       # info command
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run tests
+npm test
+
+# Test with coverage
+npm run test:coverage
+
+# Watch mode for development
+npm run build:watch
+
+# Lint
+npm run lint
+npm run lint:fix
+```
+
+## Creating Custom Adapters
+
+```typescript
+import {
+  BaseAdapter,
+  OpenAgent,
+  ConversionResult,
+  ToolCapabilities,
+} from "@openagents-control/compatibility-layer";
+
+class MyToolAdapter extends BaseAdapter {
+  readonly name = "my-tool";
+  readonly displayName = "My Tool";
+  readonly version = "1.0.0";
+
+  getCapabilities(): ToolCapabilities {
+    return {
+      supportsMultiAgent: false,
+      supportsSkills: false,
+      supportsHooks: false,
+      supportsGranularPermissions: false,
+      configFormat: "json",
+    };
+  }
+
+  async toOAC(source: string): Promise<OpenAgent> {
+    // Parse source and return OpenAgent
+  }
+
+  async fromOAC(agent: OpenAgent): Promise<ConversionResult> {
+    // Convert OpenAgent to your format
+    return {
+      success: true,
+      configs: [{ fileName: "config.json", content: "...", encoding: "utf-8" }],
+      warnings: [],
+    };
+  }
+}
+
+// Register the adapter
+import { registry } from "@openagents-control/compatibility-layer";
+registry.register(new MyToolAdapter());
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](../../CONTRIBUTING.md) for guidelines.
+
+## License
+
+MIT © OpenAgents Control Contributors

packages/compatibility-layer/docs/feature-matrices.md

@@ -0,0 +1,193 @@
+# Feature Compatibility Matrices
+
+Comprehensive comparison of feature support across OpenAgents Control (OAC), Claude Code, Cursor IDE, and Windsurf platforms. Use these matrices to understand conversion impact before migrating agent configurations.
+
+---
+
+## Quick Reference - Platform Support Summary
+
+| Platform | Config Format | Structure | Multiple Agents | Skills | Hooks | Granular Perms |
+|----------|---------------|-----------|-----------------|--------|-------|----------------|
+| **OAC** | Markdown+YAML | Directory | ✅ | ✅ | ✅ | ✅ |
+| **Claude Code** | JSON/Markdown | Directory | ✅ | ✅ | ✅ | ❌ |
+| **Cursor IDE** | Plain text | Single file | ❌ | ❌ | ❌ | ❌ |
+| **Windsurf** | JSON | Directory | ✅ | ⚠️ | ❌ | ❌ |
+
+**Legend:** ✅ Full support | ⚠️ Partial support | ❌ Not supported
+
+---
+
+## Detailed Matrices
+
+### Tool/Permission Capabilities
+
+| Feature | OAC | Claude Code | Cursor IDE | Windsurf |
+|---------|-----|-------------|------------|----------|
+| **bash/shell execution** | ✅ | ✅ | ✅ | ✅ |
+| **file read** | ✅ | ✅ | ✅ | ✅ |
+| **file write** | ✅ | ✅ | ✅ | ✅ |
+| **file edit/patch** | ✅ | ✅ | ✅ | ✅ |
+| **glob search** | ✅ | ✅ | ✅ | ✅ |
+| **grep content search** | ✅ | ✅ | ✅ | ✅ |
+| **task delegation** | ✅ | ✅ | ❌ | ⚠️ |
+| **granular permissions** | ✅ | ❌ | ❌ | ❌ |
+| **ask permissions** | ✅ | ❌ | ❌ | ❌ |
+| **path pattern rules** | ✅ | ❌ | ❌ | ⚠️ |
+
+**Notes:**
+- Cursor has no task delegation - all work happens in a single agent
+- All platforms reduce OAC granular permissions (allow/deny/ask per path) to binary on/off
+- Windsurf's delegation is limited compared to Claude's full subagent system
+
+---
+
+### Configuration Features
+
+| Feature | OAC | Claude Code | Cursor IDE | Windsurf |
+|---------|-----|-------------|------------|----------|
+| **custom model selection** | ✅ | ✅ | ✅ | ✅ |
+| **temperature control** | ✅ | ❌ | ⚠️ | ⚠️ |
+| **maxSteps limit** | ✅ | ❌ | ❌ | ❌ |
+| **agent disable/hidden** | ✅ | ⚠️ | ❌ | ⚠️ |
+| **custom prompts** | ✅ | ✅ | ✅ | ✅ |
+| **version metadata** | ✅ | ⚠️ | ❌ | ⚠️ |
+| **author metadata** | ✅ | ⚠️ | ❌ | ⚠️ |
+| **tags** | ✅ | ❌ | ❌ | ⚠️ |
+
+**Notes:**
+- Claude does not support temperature configuration
+- Cursor has limited temperature range support
+- Windsurf maps temperature to "creativity" setting (low/medium/high)
+- maxSteps is OAC-exclusive
+
+---
+
+### Context/Memory Features
+
+| Feature | OAC | Claude Code | Cursor IDE | Windsurf |
+|---------|-----|-------------|------------|----------|
+| **external context files** | ✅ | ✅ | ❌ | ✅ |
+| **context priority levels** | ✅ | ❌ | ❌ | ❌ |
+| **context subdirectories** | ✅ | ✅ | ❌ | ✅ |
+| **skills/modules system** | ✅ | ✅ | ❌ | ⚠️ |
+| **context descriptions** | ✅ | ⚠️ | ❌ | ⚠️ |
+| **dependency declarations** | ✅ | ✅ | ❌ | ⚠️ |
+
+**Notes:**
+- Cursor requires all context to be inline in `.cursorrules`
+- OAC supports 4 priority levels: critical, high, medium, low
+- Windsurf only supports high/low priority (medium/critical get degraded)
+- Skills in Windsurf become basic context file references
+
+---
+
+### Agent/Mode Features
+
+| Feature | OAC | Claude Code | Cursor IDE | Windsurf |
+|---------|-----|-------------|------------|----------|
+| **multiple agents** | ✅ | ✅ | ❌ | ✅ |
+| **primary/subagent modes** | ✅ | ✅ | ❌ | ⚠️ |
+| **agent categories** | ✅ | ⚠️ | ❌ | ⚠️ |
+| **event hooks** | ✅ | ✅ | ❌ | ❌ |
+| **hook matchers** | ✅ | ✅ | ❌ | ❌ |
+| **priority levels** | ✅ (4) | ⚠️ (2) | ❌ | ⚠️ (2) |
+
+**Notes:**
+- Cursor merges all agents into a single `.cursorrules` file
+- Hook events supported by Claude: PreToolUse, PostToolUse, PermissionRequest, AgentStart, AgentEnd
+- Windsurf has limited mode distinction
+
+---
+
+## Conversion Impact
+
+### Lossless Conversions
+
+These conversions preserve all features without degradation:
+
+| From | To | Notes |
+|------|-----|-------|
+| Cursor | OAC | Full upgrade - gains all OAC features |
+| Cursor | Claude | Gains hooks, skills, multiple agents |
+| Cursor | Windsurf | Gains multiple agents, contexts |
+| Claude | OAC | Full upgrade - gains granular permissions, temperature |
+| Windsurf | OAC | Full upgrade - gains hooks, granular permissions |
+
+---
+
+### Lossy Conversions
+
+These conversions result in feature loss or degradation:
+
+| From | To | What's Lost/Degraded |
+|------|-----|---------------------|
+| OAC | Claude | Temperature, maxSteps, granular permissions → binary |
+| OAC | Cursor | **Significant loss**: hooks, skills, multiple agents, contexts (inline only), granular permissions |
+| OAC | Windsurf | Hooks, granular permissions, context priority (4→2 levels), temperature → creativity |
+| Claude | Cursor | **Significant loss**: hooks, skills, multiple agents, contexts |
+| Claude | Windsurf | Hooks, temperature |
+| Windsurf | Cursor | Multiple agents merged, skills lost, contexts inline only |
+| Windsurf | Claude | Temperature mapping may be imprecise |
+
+---
+
+## Platform-Specific Notes
+
+### OpenAgents Control (OAC)
+- **Config location**: `.opencode/agent/` directory
+- **Format**: Markdown files with YAML frontmatter
+- **Strengths**: Full feature support, granular permissions, 4-level priorities
+- **Best for**: Complex multi-agent workflows requiring fine-grained control
+
+### Claude Code
+- **Config location**: `.claude/` directory
+- **Primary config**: `.claude/config.json` or `.claude/agents/*.md`
+- **Strengths**: Full hooks support, skills system, multiple agents
+- **Limitations**: No temperature control, binary permissions only
+- **Permission modes**: default, acceptEdits, dontAsk, bypassPermissions
+
+### Cursor IDE
+- **Config location**: `.cursorrules` (single file in project root)
+- **Format**: Plain text with optional YAML frontmatter
+- **Strengths**: Simple setup, universal tool support
+- **Limitations**: Single agent only, no external contexts, no hooks/skills
+- **Best for**: Simple, single-purpose project rules
+
+### Windsurf
+- **Config location**: `.windsurf/` directory
+- **Primary config**: `.windsurf/config.json`
+- **Strengths**: Multiple agents, context files, creativity settings
+- **Limitations**: No hooks, binary permissions, 2-level priority only
+- **Temperature mapping**: `≤0.4` → low, `0.4-0.8` → medium, `>0.8` → high
+
+---
+
+## Version Compatibility
+
+| Package Version | OAC Schema | Claude Support | Cursor Support | Windsurf Support |
+|-----------------|------------|----------------|----------------|------------------|
+| 1.0.x | v1.0 | ✅ Full | ✅ Full | ✅ Full |
+
+### Model Mappings
+
+| OAC Model ID | Claude Code | Cursor IDE | Windsurf |
+|--------------|-------------|------------|----------|
+| `claude-sonnet-4` | `claude-sonnet-4-20250514` | `claude-sonnet-4` | `claude-4-sonnet` |
+| `claude-opus-4` | `claude-opus-4-20250514` | `claude-opus-4` | `claude-4-opus` |
+| `claude-3.5-sonnet` | `claude-3-5-sonnet-20241022` | `claude-3.5-sonnet` | `claude-3-5-sonnet` |
+| `gpt-4` | — | `gpt-4` | `gpt-4` |
+| `gpt-4-turbo` | — | `gpt-4-turbo` | `gpt-4-turbo` |
+| `gpt-4o` | — | `gpt-4o` | `gpt-4o` |
+
+### Tool Name Mappings
+
+| OAC Tool | Claude Code | Cursor IDE | Windsurf |
+|----------|-------------|------------|----------|
+| `bash` | `Bash` | `terminal` | `shell` |
+| `read` | `Read` | `file_read` | `read_file` |
+| `write` | `Write` | `file_write` | `write_file` |
+| `edit` | `Edit` | `file_edit` | `edit_file` |
+| `glob` | `Glob` | `file_search` | `find_files` |
+| `grep` | `Grep` | `content_search` | `search_content` |
+| `task` | `Task` | ❌ (unsupported) | `delegate` |
+| `patch` | `Edit` | `file_edit` | `edit_file` |

packages/compatibility-layer/docs/migration-guides/claude-to-oac.md

@@ -0,0 +1,606 @@
+# Migrating from Claude Code to OAC
+
+> Convert your `.claude/` configuration to OpenAgents Control format and gain temperature control, maxSteps limits, and granular per-path permissions.
+
+## Overview
+
+Claude Code uses `.claude/config.json` for primary agents and `.claude/agents/*.md` for subagents. OAC provides all Claude Code capabilities plus temperature control, step limits, and granular permissions that Claude's binary permission modes can't express.
+
+## Prerequisites
+
+**Required:**
+- Node.js >= 18
+- npm or pnpm
+
+**Install the compatibility layer:**
+
+```bash
+npm install @openagents-control/compatibility-layer
+```
+
+## Quick Migration
+
+**One command conversion:**
+
+```bash
+oac-compat convert .claude/config.json -f oac -o agent.md
+```
+
+For subagents:
+
+```bash
+oac-compat convert .claude/agents/code-reviewer.md -f oac -o .opencode/agent/code-reviewer.md
+```
+
+**Verify the result:**
+
+```bash
+oac-compat validate agent.md
+```
+
+## Step-by-Step Manual Migration
+
+### 1. Claude Code Structure
+
+Claude Code uses a directory-based structure:
+
+```
+.claude/
+├── config.json           # Primary agent configuration
+├── agents/               # Subagent definitions
+│   ├── code-reviewer.md
+│   └── doc-writer.md
+└── skills/               # Context injection
+    └── project-context/
+        └── SKILL.md
+```
+
+**Primary agent (config.json):**
+
+```json
+{
+  "name": "main-agent",
+  "description": "Primary development assistant",
+  "systemPrompt": "You are a senior developer.",
+  "model": "claude-sonnet-4-20250514",
+  "tools": ["Read", "Write", "Bash"],
+  "permissionMode": "default",
+  "skills": ["project-context"],
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write",
+        "hooks": [{ "type": "command", "command": "npm run lint" }]
+      }
+    ]
+  }
+}
+```
+
+**Subagent (agents/code-reviewer.md):**
+
+```yaml
+---
+name: "code-reviewer"
+description: "Reviews code for quality"
+tools: "Read, Grep, Glob"
+model: "sonnet"
+permissionMode: "default"
+---
+
+You are a code reviewer. Analyze code for:
+- Best practices
+- Performance issues
+- Security vulnerabilities
+```
+
+### 2. OAC Agent Structure
+
+OAC agents use markdown with YAML frontmatter:
+
+```yaml
+---
+name: main-agent
+description: Primary development assistant
+mode: primary
+model: claude-sonnet-4
+temperature: 0.7
+maxSteps: 50
+tools:
+  read: true
+  write: true
+  bash: true
+permission:
+  write:
+    "/src/**": allow
+    "/config/**": ask
+    "/**": deny
+skills:
+  - context-manager
+hooks:
+  - event: PreToolUse
+    matchers:
+      - "write"
+    commands:
+      - type: command
+        command: "npm run lint"
+---
+
+# Main Agent
+
+You are a senior developer.
+
+## Guidelines
+
+- Write clean, maintainable code
+- Follow project conventions
+```
+
+### 3. Key Differences
+
+| Aspect | Claude Code | OAC |
+|--------|-------------|-----|
+| **Config location** | `.claude/` directory | `.opencode/agent/` directory |
+| **Primary config** | `config.json` (JSON) | `agent.md` (YAML frontmatter) |
+| **Subagent format** | Markdown with YAML | Markdown with YAML |
+| **Model IDs** | `claude-sonnet-4-20250514` | `claude-sonnet-4` |
+| **Tools format** | Array: `["Read", "Write"]` | Object: `{ read: true, write: true }` |
+| **Permissions** | Binary modes only | Granular per-path rules |
+| **Temperature** | Not supported | Full control (0.0-2.0) |
+| **Max steps** | Not supported | Configurable limit |
+| **Skills path** | `.claude/skills/` | `.opencode/skill/` |
+
+### 4. Feature Mapping
+
+| Claude Code Feature | OAC Equivalent | Notes |
+|---------------------|----------------|-------|
+| `name` | `frontmatter.name` | Direct mapping |
+| `description` | `frontmatter.description` | Direct mapping |
+| `systemPrompt` | Body content (markdown) | Becomes structured markdown |
+| `model: "claude-sonnet-4-20250514"` | `model: claude-sonnet-4` | Simplified ID |
+| `model: "sonnet"` | `model: claude-sonnet-4` | Alias resolved |
+| `model: "opus"` | `model: claude-opus-4` | Alias resolved |
+| `model: "haiku"` | `model: claude-haiku-4` | Alias resolved |
+| `tools: ["Read", "Write"]` | `tools: { read: true, write: true }` | Object format |
+| `permissionMode: "default"` | `permission: { ... }` | Granular rules available |
+| `permissionMode: "bypassPermissions"` | `permission: { "*": "allow" }` | Full access |
+| `permissionMode: "dontAsk"` | `permission: { "*": "deny" }` | Auto-deny |
+| `skills: ["name"]` | `skills: [name]` | Direct mapping |
+| `hooks.PreToolUse` | `hooks: [{ event: PreToolUse }]` | Array format |
+| (not available) | `frontmatter.temperature` | New capability |
+| (not available) | `frontmatter.maxSteps` | New capability |
+| (not available) | Granular path permissions | New capability |
+
+### 5. Common Patterns
+
+#### Pattern 1: Primary Agent Config
+
+**Before (Claude Code - config.json):**
+
+```json
+{
+  "name": "typescript-dev",
+  "description": "TypeScript development assistant",
+  "systemPrompt": "You are a senior TypeScript developer. Follow strict mode. Write tests.",
+  "model": "claude-sonnet-4-20250514",
+  "tools": ["Read", "Write", "Edit", "Bash"],
+  "permissionMode": "default"
+}
+```
+
+**After (OAC):**
+
+```yaml
+---
+name: typescript-dev
+description: TypeScript development assistant
+mode: primary
+model: claude-sonnet-4
+temperature: 0.7
+tools:
+  read: true
+  write: true
+  edit: true
+  bash: true
+permission:
+  write:
+    "/src/**": allow
+    "/tests/**": allow
+    "/**": ask
+---
+
+# TypeScript Developer
+
+You are a senior TypeScript developer.
+
+## Guidelines
+
+- Follow strict mode
+- Write tests for all code
+- Use type-safe patterns
+```
+
+---
+
+#### Pattern 2: Subagent Migration
+
+**Before (Claude Code - agents/code-reviewer.md):**
+
+```yaml
+---
+name: "code-reviewer"
+description: "Reviews code for quality and best practices"
+tools: "Read, Grep, Glob"
+model: "sonnet"
+permissionMode: "default"
+---
+
+You are a code reviewer. Focus on:
+- Code quality
+- Performance issues
+- Security vulnerabilities
+```
+
+**After (OAC):**
+
+```yaml
+---
+name: code-reviewer
+description: Reviews code for quality and best practices
+mode: subagent
+model: claude-sonnet-4
+tools:
+  read: true
+  grep: true
+  glob: true
+  write: false
+  edit: false
+  bash: false
+---
+
+# Code Reviewer
+
+You are a code reviewer.
+
+## Focus Areas
+
+- Code quality and maintainability
+- Performance issues and bottlenecks
+- Security vulnerabilities and risks
+
+## Output Format
+
+Provide findings as:
+1. **Issue**: Description
+2. **Location**: File and line
+3. **Severity**: High/Medium/Low
+4. **Recommendation**: Fix suggestion
+```
+
+---
+
+#### Pattern 3: Hooks Migration
+
+**Before (Claude Code - config.json hooks):**
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write",
+        "hooks": [{ "type": "command", "command": "npm run lint:check" }]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [{ "type": "command", "command": "echo 'Executing bash...'" }]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [{ "type": "command", "command": "npm run test:affected" }]
+      }
+    ]
+  }
+}
+```
+
+**After (OAC):**
+
+```yaml
+---
+name: validated-dev
+description: Developer with validation hooks
+mode: primary
+hooks:
+  - event: PreToolUse
+    matchers:
+      - "write"
+    commands:
+      - type: command
+        command: "npm run lint:check"
+  - event: PreToolUse
+    matchers:
+      - "bash"
+    commands:
+      - type: command
+        command: "echo 'Executing bash...'"
+  - event: PostToolUse
+    matchers:
+      - "*"
+    commands:
+      - type: command
+        command: "npm run test:affected"
+---
+```
+
+---
+
+#### Pattern 4: Skills to Contexts Migration
+
+**Before (Claude Code - .claude/skills/api-docs/SKILL.md):**
+
+```yaml
+---
+name: api-docs
+description: API documentation context
+---
+
+# API Documentation
+
+This skill provides API documentation context.
+
+Load from: `docs/api/`
+```
+
+**After (OAC contexts):**
+
+```yaml
+---
+name: api-aware-agent
+description: Agent with API documentation context
+mode: primary
+---
+
+# API-Aware Agent
+
+<!-- Contexts auto-loaded from .opencode/context/ -->
+```
+
+With context file `.opencode/context/api-docs.md`:
+
+```yaml
+---
+path: docs/api/
+priority: high
+description: API documentation for reference
+---
+
+# API Documentation Context
+
+Reference these docs when working with API endpoints.
+```
+
+---
+
+#### Pattern 5: Granular Permissions (OAC Exclusive)
+
+Claude Code only supports binary permission modes. OAC enables per-path rules:
+
+**Claude Code (limited):**
+
+```json
+{
+  "permissionMode": "default"
+}
+```
+
+**OAC (granular):**
+
+```yaml
+---
+name: safe-developer
+description: Developer with path-based permissions
+mode: primary
+permission:
+  write:
+    "/src/**": allow
+    "/tests/**": allow
+    "/docs/**": allow
+    "/config/**": ask
+    "/package.json": ask
+    "/.env*": deny
+    "/**": deny
+  bash:
+    "npm run *": allow
+    "git *": allow
+    "rm *": deny
+    "*": ask
+---
+```
+
+### 6. Limitations
+
+Features that don't fully translate between formats:
+
+| Feature | Claude Code | OAC | Migration Notes |
+|---------|-------------|-----|-----------------|
+| Temperature | Not supported | Full support | Set desired value after migration |
+| Max steps | Not supported | Configurable | Add limit after migration |
+| Granular permissions | Binary modes | Per-path rules | Expand after migration |
+| Permission mode `acceptEdits` | Supported | No direct equivalent | Use `permission: { edit: "allow" }` |
+| Skill directory structure | `.claude/skills/` | `.opencode/skill/` | Move and rename |
+| Agent directory | `.claude/agents/` | `.opencode/agent/` | Move and rename |
+
+### 7. Validation
+
+**Validate your migrated agent:**
+
+```bash
+# Check OAC format validity
+oac-compat validate agent.md
+
+# Compare capabilities
+oac-compat info --tool claude
+oac-compat info --tool oac
+
+# Test round-trip conversion
+oac-compat convert agent.md -f claude -o .claude/config.test.json
+```
+
+**Programmatic validation:**
+
+```typescript
+import { loadAgent, validateAgent } from '@openagents-control/compatibility-layer';
+
+const agent = await loadAgent('./agent.md');
+const errors = validateAgent(agent);
+
+if (errors.length === 0) {
+  console.log('Agent is valid!');
+} else {
+  console.error('Validation errors:', errors);
+}
+```
+
+**Verify feature preservation:**
+
+```typescript
+import { ClaudeAdapter } from '@openagents-control/compatibility-layer';
+
+const adapter = new ClaudeAdapter();
+const capabilities = adapter.getCapabilities();
+
+console.log('Claude supports:');
+console.log('- Multiple agents:', capabilities.supportsMultipleAgents);
+console.log('- Skills:', capabilities.supportsSkills);
+console.log('- Hooks:', capabilities.supportsHooks);
+console.log('- Temperature:', capabilities.supportsTemperature); // false
+console.log('- Max steps:', capabilities.supportsMaxSteps);       // false
+console.log('- Granular perms:', capabilities.supportsGranularPermissions); // false
+```
+
+## Troubleshooting
+
+### Model ID not recognized
+
+**Symptom:** Model defaults to `sonnet` or conversion warning appears.
+
+**Cause:** Claude Code uses full version IDs like `claude-sonnet-4-20250514`.
+
+**Fix:** OAC uses simplified model IDs:
+
+| Claude Code | OAC |
+|-------------|-----|
+| `claude-sonnet-4-20250514` | `claude-sonnet-4` |
+| `claude-opus-4` | `claude-opus-4` |
+| `claude-haiku-4` | `claude-haiku-4` |
+| `sonnet` | `claude-sonnet-4` |
+| `opus` | `claude-opus-4` |
+| `haiku` | `claude-haiku-4` |
+
+---
+
+### Tools array not converting
+
+**Symptom:** Tools show as all disabled or wrong format.
+
+**Cause:** Claude uses capitalized array format; OAC uses lowercase object format.
+
+**Fix:** Convert manually:
+
+```json
+// Claude Code
+"tools": ["Read", "Write", "Bash"]
+```
+
+```yaml
+# OAC
+tools:
+  read: true
+  write: true
+  bash: true
+  edit: false
+  grep: false
+  glob: false
+```
+
+---
+
+### Permission mode warning
+
+**Symptom:** Warning about permission degradation.
+
+**Cause:** Claude's `permissionMode` is binary; can't express granular rules.
+
+**Fix:** After migration, expand to granular permissions:
+
+```yaml
+# Instead of permissionMode: "default"
+permission:
+  write:
+    "/src/**": allow
+    "/config/**": ask
+    "/**": deny
+  bash:
+    "npm *": allow
+    "git *": allow
+    "*": ask
+```
+
+---
+
+### Hooks not triggering
+
+**Symptom:** Hooks defined but not executing.
+
+**Cause:** Hook event names or matchers may differ.
+
+**Fix:** Verify hook format:
+
+```yaml
+hooks:
+  - event: PreToolUse    # Exact event name
+    matchers:
+      - "write"          # Lowercase tool name
+      - "edit"
+    commands:
+      - type: command
+        command: "npm run lint"
+```
+
+Valid events: `PreToolUse`, `PostToolUse`, `PermissionRequest`, `AgentStart`, `AgentEnd`
+
+---
+
+### Skills not found
+
+**Symptom:** Skills referenced but not loading.
+
+**Cause:** Different directory structure between Claude Code and OAC.
+
+**Fix:** Move skills to OAC location:
+
+```bash
+# Claude Code location
+.claude/skills/my-skill/SKILL.md
+
+# OAC location
+.opencode/skill/my-skill/SKILL.md
+```
+
+Update skill references in agent:
+
+```yaml
+skills:
+  - my-skill  # Name matches directory
+```
+
+## Next Steps
+
+- **[OAC Agent Configuration](../configuration/agent-format.md)** - Deep dive into OAC format
+- **[Granular Permissions](../features/permissions.md)** - Per-path permission rules
+- **[Skills System](../features/skills.md)** - Dynamic skill loading
+- **[Hooks Reference](../features/hooks.md)** - Event-driven automation
+- **[OAC → Claude Migration](./oac-to-claude.md)** - Reverse migration guide

packages/compatibility-layer/docs/migration-guides/cursor-to-oac.md

@@ -0,0 +1,480 @@
+# Migrating from Cursor to OAC
+
+> Convert your `.cursorrules` to OpenAgents Control format and unlock Skills, Hooks, multi-agent support, and granular permissions.
+
+## Overview
+
+**Why migrate?**
+
+| Feature | Cursor | OAC |
+|---------|--------|-----|
+| Multiple agents | Single file only | Unlimited agents |
+| Skills system | Not supported | Full support |
+| Hooks | Not supported | Event-driven hooks |
+| Permissions | Binary (on/off) | Granular (allow/deny/ask per path) |
+| Contexts | Inline only | External context files |
+
+OAC provides a superset of Cursor's capabilities while maintaining backward compatibility.
+
+## Prerequisites
+
+**Required:**
+- Node.js >= 18
+- npm or pnpm
+
+**Install the compatibility layer:**
+
+```bash
+npm install @openagents-control/compatibility-layer
+```
+
+## Quick Migration
+
+**One command conversion:**
+
+```bash
+oac-compat convert .cursorrules -f oac -o agent.md
+```
+
+This reads your `.cursorrules` file and generates an OAC-compatible `agent.md`.
+
+**Verify the result:**
+
+```bash
+oac-compat validate agent.md
+```
+
+## Step-by-Step Manual Migration
+
+### 1. Cursor Rules Structure
+
+Cursor uses a single `.cursorrules` file in the project root. Two formats are supported:
+
+**Plain text format:**
+
+```
+You are a senior TypeScript developer.
+Always use strict mode.
+Prefer functional programming patterns.
+Write comprehensive tests for all code.
+```
+
+**Frontmatter format (optional):**
+
+```yaml
+---
+name: typescript-dev
+description: TypeScript development assistant
+model: gpt-4
+temperature: 0.7
+---
+
+You are a senior TypeScript developer.
+Always use strict mode.
+Prefer functional programming patterns.
+Write comprehensive tests for all code.
+```
+
+### 2. OAC Agent Structure
+
+OAC agents use markdown with YAML frontmatter:
+
+```yaml
+---
+name: typescript-dev
+description: TypeScript development assistant
+mode: primary
+model: gpt-4
+temperature: 0.7
+tools:
+  read: true
+  write: true
+  edit: true
+  bash: true
+  grep: true
+  glob: true
+---
+
+# TypeScript Developer
+
+You are a senior TypeScript developer.
+
+## Guidelines
+
+- Always use strict mode
+- Prefer functional programming patterns
+- Write comprehensive tests for all code
+
+## Skills
+
+<!-- Skills can be loaded dynamically -->
+
+## Contexts
+
+<!-- External context files for domain knowledge -->
+```
+
+### 3. Key Differences
+
+| Aspect | Cursor | OAC |
+|--------|--------|-----|
+| **File format** | `.cursorrules` (plain/YAML) | `.md` with YAML frontmatter |
+| **Location** | Project root | `.opencode/agent/` directory |
+| **Multiple agents** | Not supported | Full support |
+| **Tool config** | Implicit or comma-separated | Explicit object with booleans |
+| **Permissions** | Binary only | Granular rules per path |
+| **Context handling** | Inline in prompt | External files with priority |
+| **Skills** | Not supported | Dynamic skill loading |
+| **Hooks** | Not supported | Event-driven lifecycle hooks |
+
+### 4. Feature Mapping
+
+| Cursor Feature | OAC Equivalent | Notes |
+|----------------|----------------|-------|
+| `name` | `frontmatter.name` | Direct mapping |
+| `description` | `frontmatter.description` | Direct mapping |
+| `model: gpt-4` | `frontmatter.model: gpt-4` | Direct mapping |
+| `model: claude-3-opus` | `frontmatter.model: claude-opus-3` | Model ID normalized |
+| `model: claude-3-sonnet` | `frontmatter.model: claude-sonnet-3` | Model ID normalized |
+| `model: claude-3-haiku` | `frontmatter.model: claude-haiku-3` | Model ID normalized |
+| `temperature` | `frontmatter.temperature` | Direct mapping |
+| `tools: "read, write"` | `tools: { read: true, write: true }` | Object format |
+| Plain text body | `systemPrompt` | Becomes the agent prompt |
+| (not available) | `frontmatter.mode` | Set to `primary` or `subagent` |
+| (not available) | `frontmatter.skills` | Add skill references |
+| (not available) | `frontmatter.hooks` | Add lifecycle hooks |
+| (not available) | `frontmatter.permission` | Add granular permissions |
+| (not available) | `contexts` | Add external context files |
+
+### 5. Common Patterns
+
+#### Pattern 1: Basic Rules
+
+**Before (Cursor):**
+
+```
+You are a helpful coding assistant.
+Follow best practices for clean code.
+Always explain your changes.
+```
+
+**After (OAC):**
+
+```yaml
+---
+name: code-assistant
+description: Helpful coding assistant
+mode: primary
+---
+
+# Code Assistant
+
+You are a helpful coding assistant.
+
+## Guidelines
+
+- Follow best practices for clean code
+- Always explain your changes
+```
+
+---
+
+#### Pattern 2: Tool Configuration
+
+**Before (Cursor):**
+
+```yaml
+---
+name: restricted-agent
+tools: read, grep, glob
+---
+
+You can only read and search files.
+Do not modify any files.
+```
+
+**After (OAC):**
+
+```yaml
+---
+name: restricted-agent
+description: Read-only agent for code analysis
+mode: primary
+tools:
+  read: true
+  grep: true
+  glob: true
+  write: false
+  edit: false
+  bash: false
+---
+
+# Restricted Agent
+
+You can only read and search files.
+
+## Restrictions
+
+- Read files: ALLOWED
+- Search files: ALLOWED  
+- Modify files: DENIED
+- Execute commands: DENIED
+```
+
+---
+
+#### Pattern 3: Model Configuration
+
+**Before (Cursor):**
+
+```yaml
+---
+name: creative-writer
+model: claude-3-opus
+temperature: 0.9
+---
+
+Write creative and engaging documentation.
+```
+
+**After (OAC):**
+
+```yaml
+---
+name: creative-writer
+description: Creative documentation writer
+mode: primary
+model: claude-opus-3
+temperature: 0.9
+tools:
+  read: true
+  write: true
+  edit: true
+---
+
+# Creative Writer
+
+Write creative and engaging documentation.
+
+## Style Guidelines
+
+- Use vivid language
+- Include examples
+- Make content accessible
+```
+
+> **Note:** Claude model IDs are normalized (`claude-3-opus` → `claude-opus-3`).
+
+---
+
+#### Pattern 4: Adding OAC-Exclusive Features
+
+After migrating, enhance your agent with OAC-exclusive features:
+
+**Add Skills:**
+
+```yaml
+---
+name: full-stack-dev
+description: Full-stack development assistant
+mode: primary
+skills:
+  - context-manager
+  - task-management
+---
+```
+
+**Add Hooks:**
+
+```yaml
+---
+name: validated-writer
+description: Writer with validation hooks
+mode: primary
+hooks:
+  - event: PreToolUse
+    matchers:
+      - "write"
+      - "edit"
+    commands:
+      - type: command
+        command: "npm run lint:check"
+---
+```
+
+**Add Granular Permissions:**
+
+```yaml
+---
+name: safe-modifier
+description: Agent with path-based permissions
+mode: primary
+permission:
+  write:
+    "/src/**": allow
+    "/tests/**": allow
+    "/config/**": ask
+    "/**": deny
+---
+```
+
+**Add Contexts:**
+
+```yaml
+---
+name: context-aware
+description: Agent with external context files
+mode: primary
+---
+
+# Context-Aware Agent
+
+<!-- Contexts loaded automatically -->
+```
+
+With context files in `.opencode/context/`:
+
+```
+.opencode/context/
+├── core/
+│   ├── architecture.md
+│   └── conventions.md
+└── domain/
+    └── business-rules.md
+```
+
+### 6. Limitations
+
+Features that don't exist in Cursor (gained during migration):
+
+| Feature | Cursor | OAC | Workaround |
+|---------|--------|-----|------------|
+| Multiple agents | Single file | Unlimited | Create separate agent files |
+| Skills system | None | Full support | Inline skill content in prompt |
+| Hooks | None | Event-driven | Manual validation steps |
+| Granular permissions | Binary | Per-path rules | Document restrictions in prompt |
+| External contexts | None | Priority-based | Inline context in prompt |
+| Subagent mode | None | Delegation support | Use primary mode only |
+| Max steps | None | Configurable | Not available in Cursor |
+
+### 7. Validation
+
+**Validate your migrated agent:**
+
+```bash
+# Check OAC format validity
+oac-compat validate agent.md
+
+# Compare capabilities
+oac-compat info --tool cursor
+oac-compat info --tool oac
+
+# Test round-trip conversion
+oac-compat convert agent.md -f cursor -o .cursorrules.test
+```
+
+**Programmatic validation:**
+
+```typescript
+import { loadAgent, validateAgent } from '@openagents-control/compatibility-layer';
+
+const agent = await loadAgent('./agent.md');
+const errors = validateAgent(agent);
+
+if (errors.length === 0) {
+  console.log('Agent is valid!');
+} else {
+  console.error('Validation errors:', errors);
+}
+```
+
+## Troubleshooting
+
+### Frontmatter not parsing
+
+**Symptom:** Agent name shows as `cursor-agent` instead of your custom name.
+
+**Cause:** Frontmatter must have exact format with `---` delimiters.
+
+**Fix:**
+
+```yaml
+---
+name: my-agent
+---
+
+Content here...
+```
+
+Not:
+
+```yaml
+---
+name: my-agent
+Content here...
+```
+
+---
+
+### Model not recognized
+
+**Symptom:** Model defaults to `gpt-4`.
+
+**Cause:** Cursor model IDs differ from OAC.
+
+**Fix:** Use OAC model IDs:
+
+| Cursor | OAC |
+|--------|-----|
+| `claude-3-opus` | `claude-opus-3` |
+| `claude-3-sonnet` | `claude-sonnet-3` |
+| `claude-3-haiku` | `claude-haiku-3` |
+| `gpt-4` | `gpt-4` |
+| `gpt-4-turbo` | `gpt-4-turbo` |
+| `gpt-4o` | `gpt-4o` |
+
+---
+
+### Tools not working
+
+**Symptom:** Agent can't use expected tools.
+
+**Cause:** Tools must be explicitly enabled in OAC.
+
+**Fix:** Add tools to frontmatter:
+
+```yaml
+tools:
+  read: true
+  write: true
+  edit: true
+  bash: true
+  grep: true
+  glob: true
+```
+
+---
+
+### Content appears duplicated
+
+**Symptom:** System prompt contains frontmatter text.
+
+**Cause:** Frontmatter delimiters missing or malformed.
+
+**Fix:** Ensure proper YAML frontmatter format:
+
+```yaml
+---
+name: agent-name
+---
+
+Content starts here (not in frontmatter).
+```
+
+## Next Steps
+
+- **[OAC Agent Configuration](../configuration/agent-format.md)** - Deep dive into OAC format
+- **[Skills System](../features/skills.md)** - Learn to use dynamic skills
+- **[Hooks Reference](../features/hooks.md)** - Event-driven automation
+- **[Multi-Agent Setup](../features/multi-agent.md)** - Configure agent delegation
+- **[OAC → Cursor Migration](./oac-to-cursor.md)** - Reverse migration guide