fix(context): Add frontmatter to context files with missing metadata (#97)

* feat(context): Add project intelligence system

- Add project-intelligence.md standard (what & why)
- Add project-intelligence-management.md guide (how to manage)
- Add project-intelligence/ folder with 6 context files:
  - navigation.md (quick overview & routes)
  - business-domain.md (business context, users, value)
  - technical-domain.md (stack, architecture, decisions)
  - business-tech-bridge.md (business → technical mapping)
  - decisions-log.md (decision history with context)
  - living-notes.md (active issues, debt, questions)
- Update standards navigation with new entries
- Register all new contexts in registry.json

This enables projects to document and maintain business + technical
context for quick onboarding and lasting project understanding.

* fix(registry): Add project-intelligence to profiles

- Add context:project-intelligence/* to developer, business, full, and advanced profiles
- Ensures project intelligence contexts are included when these profiles are selected

This complements commit c731328 which added the context entries.

* docs(core): refine project intelligence system and deprecate legacy context

* feat(claude): simplify Claude Code integration with unified installer

- Create single install-claude.sh script that auto-converts and installs
- Remove redundant bootstrap-install.sh and install.sh scripts
- Delete stale plugin/ directory (now auto-generated from .opencode/)
- Add Claude Code documentation (agent-skills, create-subagents, hooks, plugins)
- Add installation profiles (essential, developer, business, full, advanced)
- Update README with Claude Code beta feature documentation
- Add component-planning.md workflow context
- Clean up demo files (assets/, src/)
- Update registry with new context entries
- Add gitignore rule for converter/generated/

The new installer:
- Converts agents automatically from .opencode/agent/
- Installs fresh converted agents to ~/.claude/plugins/
- Single command: ./integrations/claude-code/install-claude.sh

* fix: update README to use new install-claude.sh script

The Claude Code integration now uses the unified install-claude.sh script
instead of the removed bootstrap-install.sh and install.sh scripts.

* fix(context): Add frontmatter to context files with missing metadata

- Add YAML frontmatter with description to system-builder-templates
- Add frontmatter to ui/web/design context files
- Fixes validation warnings in validate-component.sh

* fix(registry): Remove orphaned context entries for deleted files

- Remove copywriting-frameworks entry (file moved to content-creation/principles/)
- Remove tone-voice entry (file moved to content-creation/principles/)

.gitignore

@@ -204,3 +204,6 @@ evals/results/*
 
 # User-generated task files
 tasks/
+
+# Claude Code integration generated files
+integrations/claude-code/converter/generated/

.opencode/agent/core/opencoder.md

@@ -22,6 +22,8 @@ dependencies:
   
   # Context files
   - context:core/standards/code
+  - context:core/workflows/task-delegation
+  - context:core/workflows/component-planning
 
 tools:
   task: true
@@ -149,90 +151,45 @@ Code Standards
 </delegation_rules>
 
 <workflow>
-  <stage id="1" name="Analyze" required="true">
-    Assess task complexity, scope, and delegation criteria
-  </stage>
-
-  <stage id="1.5" name="Discover" required="true">
-    Use ContextScout to discover relevant context files, patterns, and standards BEFORE planning.
-    
-    Why: You cannot plan effectively without knowing the project's standards and existing patterns.
+  <stage id="1" name="ContextDiscovery" required="true">
+    1. Use `ContextScout` to discover relevant project files.
+    2. MANDATORY: Read `.opencode/context/core/standards/code-quality.md`.
+    3. Read `.opencode/context/core/workflows/component-planning.md`.
     
-    task(
-      subagent_type="ContextScout",
-      description="Find context for {task-type}",
-      prompt="Search for context files related to: {task description}..."
-    )
-    
-    <checkpoint>Context discovered and understood</checkpoint>
+    *Constraint: You cannot create a valid plan until you have read the standards.*
   </stage>
 
-  <stage id="2" name="Plan" required="true" enforce="@approval_gate">
-    Create step-by-step implementation plan BASED ON discovered context.
-    Present plan to user
-    Request approval BEFORE any implementation
-    
-    <format>
-## Implementation Plan
-[Step-by-step breakdown]
-
-**Estimated:** [time/complexity]
-**Files affected:** [count]
-**Approval needed before proceeding. Please review and confirm.**
-    </format>
+  <stage id="2" name="MasterPlanning" required="true" enforce="@approval_gate">
+    1. Create a session directory: `.tmp/sessions/{YYYY-MM-DD}-{task-slug}/`
+    2. **Decompose** the request into functional Components (Auth, DB, UI, etc.).
+    3. Create `master-plan.md` following the `component-planning.md` standard.
+       - Define Architecture.
+       - List Components in dependency order.
+    4. Present `master-plan.md` for approval.
   </stage>
 
-  <stage id="3" name="LoadContext" required="true" enforce="@critical_context_requirement">
-    BEFORE implementation, ensure all required context is loaded:
+  <stage id="3" name="ComponentExecutionLoop" when="approved" enforce="@incremental_execution">
+    *Repeat for each Component in Master Plan:*
     
-    1. Load required context files (if not already loaded during discovery):
-       - Code tasks → Read .opencode/context/core/standards/code-quality.md (MANDATORY)
-       - Load all files discovered by ContextScout in priority order
+    1. **Plan Component**:
+       - Create `component-{name}.md` with detailed Interface, Tests, and Tasks.
+       - Request approval for this specific component's design.
        
-    2. Apply standards to implementation
-    
-    <checkpoint>Context files loaded</checkpoint>
-  </stage>
-
-  <stage id="4" name="Execute" when="approved" enforce="@incremental_execution">
-    Implement ONE step at a time (never all at once)
-    
-    After each increment:
-    - Use appropriate runtime (node/bun for TS/JS, python, go run, cargo run)
-    - Run type checks if applicable (tsc, mypy, go build, cargo check)
-    - Run linting if configured (eslint, pylint, golangci-lint, clippy)
-    - Run build checks
-    - Execute relevant tests
-    
-    For simple tasks, optionally delegate to `CoderAgent`
-    Use Test-Driven Development when tests/ directory is available
-    
-    <format>
-## Implementing Step [X]: [Description]
-[Code implementation]
-[Validation results: type check ✓, lint ✓, tests ✓]
-
-**Ready for next step or feedback**
-    </format>
-  </stage>
-
-  <stage id="5" name="Validate" enforce="@stop_on_failure">
-    Check quality → Verify complete → Test if applicable
-    
-    <on_failure enforce="@report_first">
-      STOP → Report error → Propose fix → Request approval → Fix → Re-validate
-      NEVER auto-fix without approval
-    </on_failure>
+    2. **Execute Component**:
+       - Load tasks from `component-{name}.md` into `TodoWrite`.
+       - Execute loop: `TodoRead` -> Implement -> Validate -> `TodoWrite`.
+       - If complex, delegate to `CoderAgent` passing `component-{name}.md`.
+       
+    3. **Integrate**:
+       - Mark component complete in `master-plan.md`.
+       - Verify integration with previous components.
   </stage>
 
-  <stage id="6" name="Handoff" when="complete">
-    When implementation complete and user approves:
-    
-    Emit handoff recommendations:
-    - `TestEngineer` - For comprehensive test coverage
-    - `DocWriter` - For documentation generation
-    
-    Update task status and mark completed sections with checkmarks
+  <stage id="4" name="ValidationAndHandoff" enforce="@stop_on_failure">
+    1. Verify all components in `master-plan.md` are complete.
+    2. Run full system integration tests.
+    3. Ask user to clean up `.tmp` files.
+    4. Suggest `DocWriter` or `TestEngineer`.
   </stage>
 </workflow>
 

.opencode/agent/eval-runner.md

@@ -1,34 +1,216 @@
 ---
 # OpenCode Agent Configuration
-id: eval-runner
-name: Eval Runner
-description: "Test harness for evaluation framework - DO NOT USE DIRECTLY"
-category: testing
-type: utility
+id: opencoder
+name: OpenCoder
+description: "Multi-language implementation agent for modular and functional development"
+category: core
+type: core
 version: 1.0.0
 author: opencode
-mode: subagent
-temperature: 0.2
+mode: primary
+temperature: 0.1
+
+# Dependencies
+dependencies:
+  # Subagents for delegation
+  - subagent:documentation
+  - subagent:coder-agent
+  - subagent:tester
+  - subagent:reviewer
+  - subagent:build-agent
+  - subagent:contextscout
+  
+  # Context files
+  - context:core/standards/code
+  - context:core/workflows/task-delegation
+  - context:core/workflows/component-planning
+
+tools:
+  task: true
+  read: true
+  edit: true
+  write: true
+  grep: true
+  glob: true
+  bash: true
+  patch: true
+permissions:
+  bash:
+    "rm -rf *": "ask"
+    "sudo *": "deny"
+    "chmod *": "ask"
+    "curl *": "ask"
+    "wget *": "ask"
+    "docker *": "ask"
+    "kubectl *": "ask"
+  edit:
+    "**/*.env*": "deny"
+    "**/*.key": "deny"
+    "**/*.secret": "deny"
+    "node_modules/**": "deny"
+    "**/__pycache__/**": "deny"
+    "**/*.pyc": "deny"
+    ".git/**": "deny"
+
+# Tags
+tags:
+  - development
+  - coding
+  - implementation
 ---
 
-# Eval Runner - Test Harness
+# Development Agent
+Always start with phrase "DIGGING IN..."
+
+<critical_context_requirement>
+PURPOSE: Context files contain project-specific coding standards that ensure consistency, 
+quality, and alignment with established patterns. Without loading context first, 
+you will create code that doesn't match the project's conventions.
+
+BEFORE any code implementation (write/edit), ALWAYS load required context files:
+- Code tasks → .opencode/context/core/standards/code-quality.md (MANDATORY)
+- Language-specific patterns if available
+
+WHY THIS MATTERS:
+- Code without standards/code-quality.md → Inconsistent patterns, wrong architecture
+- Skipping context = wasted effort + rework
+
+CONSEQUENCE OF SKIPPING: Work that doesn't match project standards = wasted effort
+</critical_context_requirement>
+
+<critical_rules priority="absolute" enforcement="strict">
+  <rule id="approval_gate" scope="all_execution">
+    Request approval before ANY implementation (write, edit, bash). Read/list/glob/grep or using ContextScout for discovery don't require approval.
+    ALWAYS use ContextScout for discovery before implementation, before doing your own discovery.
+  </rule>
+  
+  <rule id="stop_on_failure" scope="validation">
+    STOP on test fail/build errors - NEVER auto-fix without approval
+  </rule>
+  
+  <rule id="report_first" scope="error_handling">
+    On fail: REPORT error → PROPOSE fix → REQUEST APPROVAL → Then fix (never auto-fix)
+  </rule>
+  
+  <rule id="incremental_execution" scope="implementation">
+    Implement ONE step at a time, validate each step before proceeding
+  </rule>
+</critical_rules>
+
+## Available Subagents (invoke via task tool)
+
+- `ContextScout` - Discover context files BEFORE coding (saves time!)
+- `CoderAgent` - Simple implementations
+- `TestEngineer` - Testing after implementation
+- `DocWriter` - Documentation generation
+
+**Invocation syntax**:
+```javascript
+task(
+  subagent_type="ContextScout",
+  description="Brief description",
+  prompt="Detailed instructions for the subagent"
+)
+```
+
+Focus:
+You are a coding specialist focused on writing clean, maintainable, and scalable code. Your role is to implement applications following a strict plan-and-approve workflow using modular and functional programming principles.
+
+Adapt to the project's language based on the files you encounter (TypeScript, Python, Go, Rust, etc.).
+
+Core Responsibilities
+Implement applications with focus on:
+
+- Modular architecture design
+- Functional programming patterns where appropriate
+- Type-safe implementations (when language supports it)
+- Clean code principles
+- SOLID principles adherence
+- Scalable code structures
+- Proper separation of concerns
+
+Code Standards
+
+- Write modular, functional code following the language's conventions
+- Follow language-specific naming conventions
+- Add minimal, high-signal comments only
+- Avoid over-complication
+- Prefer declarative over imperative patterns
+- Use proper type systems when available
+
+<delegation_rules>
+  <delegate_when>
+    <condition id="simple_task" trigger="focused_implementation" action="delegate_to_coder_agent">
+      For simple, focused implementations to save time
+    </condition>
+  </delegate_when>
+  
+  <execute_directly_when>
+    <condition trigger="single_file_simple_change">1-3 files, straightforward implementation</condition>
+  </execute_directly_when>
+</delegation_rules>
 
-**⚠️ DO NOT USE THIS AGENT DIRECTLY ⚠️**
+<workflow>
+  <stage id="1" name="ContextDiscovery" required="true">
+    1. Use `ContextScout` to discover relevant project files.
+    2. MANDATORY: Read `.opencode/context/core/standards/code-quality.md`.
+    3. Read `.opencode/context/core/workflows/component-planning.md`.
+    
+    *Constraint: You cannot create a valid plan until you have read the standards.*
+  </stage>
 
-This agent is a test harness used by the OpenCode evaluation framework.
+  <stage id="2" name="MasterPlanning" required="true" enforce="@approval_gate">
+    1. Create a session directory: `.tmp/sessions/{YYYY-MM-DD}-{task-slug}/`
+    2. **Decompose** the request into functional Components (Auth, DB, UI, etc.).
+    3. Create `master-plan.md` following the `component-planning.md` standard.
+       - Define Architecture.
+       - List Components in dependency order.
+    4. Present `master-plan.md` for approval.
+  </stage>
 
-## Purpose
+  <stage id="3" name="ComponentExecutionLoop" when="approved" enforce="@incremental_execution">
+    *Repeat for each Component in Master Plan:*
+    
+    1. **Plan Component**:
+       - Create `component-{name}.md` with detailed Interface, Tests, and Tasks.
+       - Request approval for this specific component's design.
+       
+    2. **Execute Component**:
+       - Load tasks from `component-{name}.md` into `TodoWrite`.
+       - Execute loop: `TodoRead` -> Implement -> Validate -> `TodoWrite`.
+       - If complex, delegate to `CoderAgent` passing `component-{name}.md`.
+       
+    3. **Integrate**:
+       - Mark component complete in `master-plan.md`.
+       - Verify integration with previous components.
+  </stage>
 
-This file is **dynamically replaced** during test runs:
-- Before tests: Replaced with target agent's prompt (e.g., openagent, opencoder)
-- During tests: Acts as the target agent
-- After tests: Restored to this default state
+  <stage id="4" name="ValidationAndHandoff" enforce="@stop_on_failure">
+    1. Verify all components in `master-plan.md` are complete.
+    2. Run full system integration tests.
+    3. Ask user to clean up `.tmp` files.
+    4. Suggest `DocWriter` or `TestEngineer`.
+  </stage>
+</workflow>
 
-## Configuration
+<execution_philosophy>
+  Development specialist with strict quality gates and context awareness.
+  
+  **Approach**: Plan → Approve → Load Context → Execute Incrementally → Validate → Handoff
+  **Mindset**: Quality over speed, consistency over convenience
+  **Safety**: Context loading, approval gates, stop on failure, incremental execution
+</execution_philosophy>
 
-- **ID**: eval-runner
-- **Mode**: subagent (test harness only)
-- **Status**: Template - will be overwritten during test runs
+<constraints enforcement="absolute">
+  These constraints override all other considerations:
+  
+  1. NEVER execute write/edit without loading required context first
+  2. NEVER skip approval gate - always request approval before implementation
+  3. NEVER auto-fix errors - always report first and request approval
+  4. NEVER implement entire plan at once - always incremental, one step at a time
+  5. ALWAYS validate after each step (type check, lint, test)
+  
+  If you find yourself violating these rules, STOP and correct course.
+</constraints>
 
-If you see this prompt during a test run, something went wrong with the test setup.
 

.opencode/context/content/README.md

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

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

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

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

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

.opencode/context/core/workflows/component-planning.md

@@ -0,0 +1,96 @@
+<!-- Context: workflows/component-planning | Priority: high | Version: 1.0 -->
+
+# Component-Based Planning Workflow
+
+## Overview
+This workflow replaces "Monolithic Planning" (planning everything at once) with "Iterative Component Planning". It is designed for complex features that require breaking down into functional units.
+
+## Core Philosophy
+**"Plan the System, Build the Component."**
+Don't try to write a detailed plan for the entire system upfront. Create a high-level roadmap, then zoom in to plan one component in detail before executing it.
+
+## The Two-Level Plan Structure
+
+### Level 1: The Master Plan (Roadmap)
+**File:** `.tmp/sessions/{id}/master-plan.md`
+**Purpose:** High-level architecture and dependency graph.
+**Content:**
+- System Architecture Diagram (ASCII)
+- List of Components (e.g., Auth, Database, API, UI)
+- Dependency Order (What must be built first?)
+- Global Standards/Decisions
+
+### Level 2: The Component Plan (Active Spec)
+**File:** `.tmp/sessions/{id}/component-{name}.md`
+**Purpose:** Detailed execution steps for the *current* focus.
+**Content:**
+- **Interface Definition**: Types, function signatures, API contracts.
+- **Test Strategy**: What specific cases will be tested?
+- **Task List**: Atomic steps (Create file, Write test, Implement logic).
+- **Verification**: How do we know this component is done?
+
+---
+
+## Workflow Steps
+
+### Phase 1: System Design (The Master Plan)
+1.  **Analyze**: Understand the full feature request.
+2.  **Decompose**: Break the system into functional Components (e.g., "User Service", "Email Worker", "Frontend Form").
+3.  **Draft Master Plan**: Create `master-plan.md`.
+4.  **Approve**: Get user buy-in on the architecture and order.
+
+### Phase 2: Component Execution Loop
+*Repeat this for each component in the Master Plan:*
+
+1.  **Select Component**: Pick the next unblocked component.
+2.  **Draft Component Plan**: Create `component-{name}.md`.
+    *   Define the *exact* interface/types first.
+    *   List the atomic implementation steps.
+3.  **Approve**: Show the detailed component plan to the user.
+4.  **Execute**:
+    *   Load `component-{name}.md` into `TodoWrite`.
+    *   Implement -> Validate -> Check off.
+5.  **Integrate**: Update `master-plan.md` to mark component as complete.
+
+---
+
+## When to Use This
+- **Complex Features**: >3 files, multiple layers (DB + API + UI).
+- **Unknowns**: When later parts of the system depend on earlier decisions.
+- **Large Scope**: Anything taking >2 hours.
+
+## Example Master Plan (`master-plan.md`)
+
+```markdown
+# Master Plan: E-Commerce Checkout
+
+## Architecture
+[Cart] -> [Order Service] -> [Payment Gateway]
+                       -> [Inventory Service]
+
+## Component Order
+1. [ ] **Inventory Service** (Check stock)
+2. [ ] **Order Service** (Create order record)
+3. [ ] **Payment Integration** (Stripe)
+4. [ ] **Checkout UI** (React components)
+```
+
+## Example Component Plan (`component-inventory.md`)
+
+```markdown
+# Component: Inventory Service
+
+## Interface
+```typescript
+interface InventoryManager {
+  checkStock(sku: string): Promise<boolean>;
+  reserve(sku: string, quantity: number): Promise<void>;
+}
+```
+
+## Tasks
+- [ ] Define `InventoryManager` interface in `src/types.ts`
+- [ ] Create mock implementation for tests
+- [ ] Implement `checkStock` logic with DB query
+- [ ] Add unit tests for race conditions
+```

.opencode/context/openagents-repo/core-concepts/agents.md

@@ -158,6 +158,19 @@ Agents:
 
 ---
 
+## Claude Code Interop (Optional)
+
+OpenAgents can pair with Claude Code for local workflows and distribution:
+
+- **Subagents**: Project helpers in `.claude/agents/`
+- **Skills**: Auto-invoked guidance in `.claude/skills/`
+- **Hooks**: Shell commands on lifecycle events (use sparingly)
+- **Plugins**: Share agents/skills/hooks across projects
+
+Use this when you want Claude Code to follow OpenAgents standards or to ship reusable helpers.
+
+---
+
 ## Path Resolution
 
 The system supports multiple path formats for backward compatibility:
@@ -343,8 +356,12 @@ Before execution:
 - **Testing agents**: `guides/testing-agent.md`
 - **Category system**: `core-concepts/categories.md`
 - **File locations**: `lookup/file-locations.md`
+- **Claude Code subagents**: `../to-be-consumed/claude-code-docs/create-subagents.md`
+- **Claude Code skills**: `../to-be-consumed/claude-code-docs/agent-skills.md`
+- **Claude Code hooks**: `../to-be-consumed/claude-code-docs/hooks.md`
+- **Claude Code plugins**: `../to-be-consumed/claude-code-docs/plugins.md`
 
 ---
 
-**Last Updated**: 2025-12-10  
-**Version**: 0.5.0
+**Last Updated**: 2026-01-13  
+**Version**: 0.5.1

.opencode/context/openagents-repo/core-concepts/categories.md

@@ -53,7 +53,10 @@ Categories are domain-based groupings that organize agents, context files, and t
 - copywriter, technical-writer
 
 **Context**:
-- copywriting-frameworks.md, tone-voice.md
+- copywriting-frameworks.md
+- tone-voice.md
+- audience-targeting.md
+- hooks.md
 
 **When to use**: Writing, documentation, marketing
 
@@ -437,8 +440,9 @@ evals/agents/development/
 - **Adding categories**: `guides/add-category.md`
 - **Agent concepts**: `core-concepts/agents.md`
 - **File locations**: `lookup/file-locations.md`
+- **Content creation principles**: `../content-creation/principles/navigation.md`
 
 ---
 
-**Last Updated**: 2025-12-10  
-**Version**: 0.5.0
+**Last Updated**: 2026-01-13  
+**Version**: 0.5.1

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

@@ -73,6 +73,19 @@ dependencies: []
 
 ---
 
+## 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
@@ -317,8 +330,9 @@ After adding agent:
 - **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**: 2025-12-10  
-**Version**: 0.5.0
+**Last Updated**: 2026-01-13  
+**Version**: 0.5.1

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

@@ -55,6 +55,16 @@ mkdir -p .opencode/skill/{skill-name}/scripts
 
 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
@@ -443,3 +453,4 @@ Each skill should do one thing well:
 - **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/navigation.md

@@ -2,7 +2,7 @@
 
 **Purpose**: Context files specific to the OpenAgents repository
 
-**Last Updated**: 2026-01-07
+**Last Updated**: 2026-01-13
 
 ---
 
@@ -127,6 +127,8 @@ All files follow MVI principle (<200 lines):
 - `../core/` - Core system context (standards, patterns)
 - `../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
 
 ---
 

.opencode/context/openagents-repo/quick-start.md

@@ -53,6 +53,8 @@ Before working on this repo, understand these 4 systems:
 | Debug issue | `guides/debugging.md` |
 | Find files | `lookup/file-locations.md` |
 | Create release | `guides/creating-release.md` |
+| Write content or copy | `core-concepts/categories.md` + `../content-creation/principles/navigation.md` |
+| Use Claude Code helpers | `core-concepts/agents.md` + `guides/adding-agent.md` + `../to-be-consumed/claude-code-docs/create-subagents.md` |
 
 ---
 
@@ -163,5 +165,5 @@ opencode-agents/
 
 ---
 
-**Last Updated**: 2025-12-10  
-**Version**: 0.5.0
+**Last Updated**: 2026-01-13  
+**Version**: 0.5.1

.opencode/context/system-builder-templates/SYSTEM-BUILDER-GUIDE.md

@@ -1,3 +1,7 @@
+---
+description: "Complete guide for using the /build-context-system command to create custom context-aware AI systems"
+---
+
 # System Builder Guide
 
 Complete guide for using the `/build-context-system` command to create custom context-aware AI systems.
@@ -5,6 +9,7 @@ Complete guide for using the `/build-context-system` command to create custom co
 ## Overview
 
 The system builder creates complete `.opencode` folder architectures tailored to your domain and use cases. It follows research-backed patterns from Stanford and Anthropic for optimal AI agent performance.
+---
 
 ## Quick Start
 

.opencode/context/system-builder-templates/navigation.md

@@ -1,7 +1,11 @@
+---
+description: "Overview of available templates for generating context-aware AI systems"
+---
+
 # System Builder Templates
 
 This directory contains reusable templates for generating context-aware AI systems.
-
+---
 ## Template Categories
 
 ### Agent Templates

.opencode/context/system-builder-templates/orchestrator-template.md

@@ -1,3 +1,7 @@
+---
+description: "Template for generating main orchestrator agents for context-aware AI systems"
+---
+
 # Orchestrator Agent Template
 
 This template is used to generate main orchestrator agents for context-aware AI systems.

.opencode/context/system-builder-templates/subagent-template.md

@@ -1,3 +1,7 @@
+---
+description: "Template for generating specialized subagent files for context-aware AI systems"
+---
+
 # Subagent Template
 
 This template is used to generate specialized subagent files.

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

@@ -0,0 +1,565 @@
+# 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

@@ -0,0 +1,716 @@
+# 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

@@ -0,0 +1,338 @@
+# 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/plugins.md

@@ -0,0 +1,413 @@
+# 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/design/examples/scrollytelling-headphone.md

@@ -1,3 +1,7 @@
+---
+description: "Full Next.js implementation of scroll-linked image sequence animation"
+---
+
 # Example: Scrollytelling Headphone Animation
 
 **Purpose**: Full Next.js implementation of scroll-linked image sequence animation

.opencode/context/ui/web/design/guides/building-scrollytelling-pages.md

@@ -1,3 +1,7 @@
+---
+description: "Step-by-step implementation of scroll-linked image sequence animations"
+---
+
 # Guide: Building Scrollytelling Pages
 
 **Purpose**: Step-by-step implementation of scroll-linked image sequence animations

.opencode/context/ui/web/design/lookup/scroll-animation-prompts.md

@@ -1,3 +1,7 @@
+---
+description: "AI prompts for generating start/end frames and video sequences for scrollytelling"
+---
+
 # Lookup: Scroll Animation Image Generation Prompts
 
 **Purpose**: AI prompts for generating start/end frames and video sequences for scrollytelling

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

@@ -1,3 +1,7 @@
+---
+description: "Advanced web UI patterns - scroll animations, visual effects, and interactive design"
+---
+
 # Web Design Patterns
 
 **Purpose**: Advanced web UI patterns - scroll animations, visual effects, and interactive design

.opencode/profiles/advanced/profile.json

@@ -0,0 +1,61 @@
+{
+  "name": "Advanced (Meta-Level)",
+  "description": "Full installation plus System Builder for creating custom AI architectures. For power users and contributors.",
+  "components": [
+    "agent:openagent",
+    "agent:opencoder",
+    "agent:system-builder",
+    "agent:repo-manager",
+    "agent:eval-runner",
+    "agent:frontend-specialist",
+    "agent:backend-specialist",
+    "agent:devops-specialist",
+    "agent:codebase-agent",
+    "agent:copywriter",
+    "agent:technical-writer",
+    "agent:data-analyst",
+    "subagent:task-manager",
+    "subagent:documentation",
+    "subagent:coder-agent",
+    "subagent:reviewer",
+    "subagent:tester",
+    "subagent:build-agent",
+    "subagent:codebase-pattern-analyst",
+    "subagent:image-specialist",
+    "subagent:context-retriever",
+    "subagent:contextscout",
+    "skill:task-management",
+    "subagent:domain-analyzer",
+    "subagent:agent-generator",
+    "subagent:context-organizer",
+    "subagent:workflow-designer",
+    "subagent:command-creator",
+    "command:test",
+    "command:commit",
+    "command:context",
+    "command:clean",
+    "command:optimize",
+    "command:prompt-enhancer",
+    "command:worktrees",
+    "command:build-context-system",
+    "command:validate-repo",
+    "tool:env",
+    "tool:gemini",
+    "plugin:notify",
+    "plugin:telegram-bot",
+    "plugin:telegram-notify",
+    "context:essential-patterns",
+    "context:project-context",
+    "context:quick-start",
+    "context:core/*",
+    "context:project-intelligence/*",
+    "context:to-be-consumed/*",
+    "context:adding-skill",
+    "config:env-example",
+    "config:readme"
+  ],
+  "additionalPaths": [
+    ".Building/",
+    ".github/workflows/"
+  ]
+}

.opencode/profiles/business/profile.json

@@ -0,0 +1,32 @@
+{
+  "name": "Business",
+  "description": "Business process automation, content creation, and visual workflows. Includes image generation, notifications, and documentation tools.",
+  "components": [
+    "agent:openagent",
+    "agent:copywriter",
+    "agent:technical-writer",
+    "agent:data-analyst",
+    "subagent:task-manager",
+    "subagent:contextscout",
+    "subagent:documentation",
+    "subagent:image-specialist",
+    "skill:task-management",
+    "command:context",
+    "command:clean",
+    "command:prompt-enhancer",
+    "tool:env",
+    "tool:gemini",
+    "plugin:notify",
+    "plugin:telegram-bot",
+    "plugin:telegram-notify",
+    "context:essential-patterns",
+    "context:project-context",
+    "context:quick-start",
+    "context:core/*",
+    "context:project-intelligence/*",
+    "context:to-be-consumed/*",
+    "context:adding-skill",
+    "config:env-example",
+    "config:readme"
+  ]
+}

.opencode/profiles/developer/profile.json

@@ -0,0 +1,38 @@
+{
+  "name": "Developer",
+  "description": "Complete software development environment with code generation, testing, review, and build tools. Recommended for most developers.",
+  "badge": "RECOMMENDED",
+  "components": [
+    "agent:openagent",
+    "agent:opencoder",
+    "agent:frontend-specialist",
+    "agent:backend-specialist",
+    "agent:devops-specialist",
+    "agent:codebase-agent",
+    "subagent:task-manager",
+    "subagent:documentation",
+    "subagent:coder-agent",
+    "subagent:reviewer",
+    "subagent:tester",
+    "subagent:build-agent",
+    "subagent:codebase-pattern-analyst",
+    "subagent:contextscout",
+    "skill:task-management",
+    "command:commit",
+    "command:test",
+    "command:context",
+    "command:clean",
+    "command:optimize",
+    "command:validate-repo",
+    "tool:env",
+    "context:essential-patterns",
+    "context:project-context",
+    "context:quick-start",
+    "context:core/*",
+    "context:project-intelligence/*",
+    "context:to-be-consumed/*",
+    "context:adding-skill",
+    "config:env-example",
+    "config:readme"
+  ]
+}

.opencode/profiles/essential/profile.json

@@ -0,0 +1,29 @@
+{
+  "name": "Essential (Minimal)",
+  "description": "Minimal starter kit - universal agent with core subagents. Great for learning the system or lightweight tasks. Upgrade to Developer or Business for full features.",
+  "components": [
+    "agent:openagent",
+    "subagent:task-manager",
+    "subagent:contextscout",
+    "subagent:documentation",
+    "skill:task-management",
+    "command:context",
+    "command:clean",
+    "tool:env",
+    "context:essential-patterns",
+    "context:project-context",
+    "context:quick-start",
+    "context:standards-code",
+    "context:standards-patterns",
+    "context:standards-tests",
+    "context:standards-docs",
+    "context:standards-analysis",
+    "context:workflows-delegation",
+    "context:session-management",
+    "context:feature-breakdown",
+    "context:workflows-review",
+    "context:system-context-guide",
+    "context:adding-skill",
+    "config:env-example"
+  ]
+}

.opencode/profiles/full/profile.json

@@ -0,0 +1,48 @@
+{
+  "name": "Full",
+  "description": "Everything included - all agents, subagents, tools, and plugins for maximum functionality.",
+  "components": [
+    "agent:openagent",
+    "agent:opencoder",
+    "agent:eval-runner",
+    "agent:frontend-specialist",
+    "agent:backend-specialist",
+    "agent:devops-specialist",
+    "agent:codebase-agent",
+    "agent:copywriter",
+    "agent:technical-writer",
+    "agent:data-analyst",
+    "subagent:task-manager",
+    "subagent:documentation",
+    "subagent:coder-agent",
+    "subagent:reviewer",
+    "subagent:tester",
+    "subagent:build-agent",
+    "subagent:codebase-pattern-analyst",
+    "subagent:contextscout",
+    "skill:task-management",
+    "subagent:image-specialist",
+    "command:test",
+    "command:commit",
+    "command:context",
+    "command:clean",
+    "command:optimize",
+    "command:prompt-enhancer",
+    "command:worktrees",
+    "command:validate-repo",
+    "tool:env",
+    "tool:gemini",
+    "plugin:notify",
+    "plugin:telegram-bot",
+    "plugin:telegram-notify",
+    "context:essential-patterns",
+    "context:project-context",
+    "context:quick-start",
+    "context:core/*",
+    "context:project-intelligence/*",
+    "context:to-be-consumed/*",
+    "context:adding-skill",
+    "config:env-example",
+    "config:readme"
+  ]
+}

README.md

@@ -391,6 +391,86 @@ cp env.example .env
 
 **Get API key:** https://makersuite.google.com/app/apikey
 
+### 🤖 Use with Claude Code (Beta)
+
+> **⚠️ Beta Feature** - This integration allows Claude Code to understand and use OpenAgents standards. Works with Claude Code v2.1.6+
+
+OpenAgents includes a bridge that makes Claude Code automatically load context files and follow your coding patterns.
+
+<details>
+<summary><b>For This Repository (Contributors)</b></summary>
+
+If you're working **on** this repository and want Claude Code to understand OpenAgents:
+
+```bash
+cd /path/to/opencode-agents
+claude
+```
+
+Claude will automatically:
+- Load the `openagents-standards` Skill
+- Use `context-scout` to find relevant context files
+- Apply OpenAgents standards to any task
+
+**If it doesn't auto-trigger**, restart Claude Code and start your request with:
+```
+[Use OpenAgents standards]
+```
+
+</details>
+
+<details>
+<summary><b>For Your Own OpenAgents Projects</b></summary>
+
+If you've set up OpenAgents in your own project and want Claude Code support:
+
+```bash
+# One-line installer (recommended)
+curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgents/main/integrations/claude-code/install-claude.sh | bash
+
+# Use with Claude Code
+claude --plugin-dir ~/.claude/plugins/openagents-bridge
+```
+
+**Prereqs**: `git`, `bash`, `node`
+
+**Verify Claude Code**:
+```bash
+claude --version
+```
+
+**Manual install (if you already cloned this repo):**
+```bash
+cd /path/to/opencode-agents/integrations/claude-code
+./install-claude.sh
+```
+
+**How it works:**
+- The installer automatically converts your `.opencode/` files to Claude format
+- Converts agents, subagents, and creates context-scout skill
+- Claude automatically discovers and follows your patterns
+- No duplication - works with your existing OpenAgents setup
+
+</details>
+
+<details>
+<summary><b>CLI Reference</b></summary>
+
+| Command | Description |
+|---------|-------------|
+| `claude` | Start interactive session |
+| `claude "request"` | One-shot request |
+| `claude --plugin-dir ~/.claude/plugins/openagents-bridge` | Load with OpenAgents plugin |
+| `claude --print-plugins` | Show loaded plugins |
+| `claude --debug` | Debug mode (shows plugin loading) |
+
+**Manual workaround** if plugin doesn't trigger:
+```
+"Load context from .opencode/context/ then help me create a new agent"
+```
+
+</details>
+
 ---
 
 ## Common Questions

assets/.gitignore

@@ -1,6 +0,0 @@
-# Ignore generated images but keep directory structure
-images/*/
-!images/.gitkeep
-
-# Allow specific important images if needed
-# !images/examples/

assets/images/.gitkeep

@@ -1 +0,0 @@
-# Keep this directory in git

evals/agents/core/opencoder/tests/workflow-test.yaml

@@ -0,0 +1,38 @@
+id: workflow-test
+name: "Workflow Test: Component Planning"
+description: |
+  Tests the Component-Based Planning workflow.
+  
+  Expected workflow:
+  1. Agent receives coding request.
+  2. Agent loads context (standards + component-planning).
+  3. Agent creates master-plan.md.
+  4. Agent requests approval.
+
+category: developer
+agent: core/opencoder
+model: anthropic/claude-sonnet-4-5
+
+prompt: "Create a simple Python script that prints 'Hello World' and a test for it."
+
+behavior:
+  requiresApproval: false
+  minToolCalls: 2
+
+expectations:
+  - type: context_loaded
+    contexts: 
+      - core/standards/code-quality.md
+      - core/workflows/component-planning.md
+  - type: tool_usage
+    tools: ["write", "todowrite"]
+    min_count: 1
+
+approvalStrategy:
+  type: auto-approve
+
+timeout: 300000
+
+tags:
+  - workflow
+  - planning

evals/results/latest.json

@@ -1,16 +1,16 @@
 {
   "meta": {
-    "timestamp": "2026-01-11T21:13:52.792Z",
-    "agent": "task-manager",
-    "model": "opencode/minimax-m2.1-free",
+    "timestamp": "2026-01-17T20:39:20.106Z",
+    "agent": "core/opencoder",
+    "model": "opencode/grok-code-fast",
     "framework_version": "0.1.0",
-    "git_commit": "c8733ee"
+    "git_commit": "76e875b"
   },
   "summary": {
     "total": 1,
     "passed": 0,
     "failed": 1,
-    "duration_ms": 62017,
+    "duration_ms": 122016,
     "pass_rate": 0
   },
   "by_category": {
@@ -21,38 +21,36 @@
   },
   "tests": [
     {
-      "id": "core-task-manager-smoke-test",
+      "id": "workflow-test",
       "category": "developer",
       "passed": false,
-      "duration_ms": 62017,
-      "events": 32,
+      "duration_ms": 122016,
+      "events": 81,
       "approvals": 0,
       "violations": {
         "total": 4,
-        "errors": 3,
-        "warnings": 1,
+        "errors": 4,
+        "warnings": 0,
         "details": [
           {
             "type": "missing-approval",
             "severity": "error",
-            "message": "Execution tool 'write' called without requesting approval",
-            "expected": true
+            "message": "Execution tool 'task' called without requesting approval"
           },
           {
-            "type": "missing-approval",
+            "type": "wrong-context-file",
             "severity": "error",
-            "message": "Execution tool 'task' called without requesting approval",
-            "expected": true
+            "message": "Task type 'delegation' requires context file(s): .opencode/context/core/workflows/delegation.md or workflows/delegation.md or delegation.md. Loaded: /Users/darrenhinde/Documents/GitHub/Claude-agents/.opencode/context/core/standards/code-quality.md, /Users/darrenhinde/Documents/GitHub/Claude-agents/.opencode/context/development/clean-code.md, /Users/darrenhinde/Documents/GitHub/Claude-agents/.opencode/context/core/standards/test-coverage.md"
           },
           {
-            "type": "insufficient-read",
-            "severity": "warning",
-            "message": "Read/execution ratio < 1 (0.50)"
+            "type": "execution-before-read",
+            "severity": "error",
+            "message": "A modification tool was executed without prior read operations"
           },
           {
-            "type": "missing-required-tool",
+            "type": "missing-approval-request",
             "severity": "error",
-            "message": "Required tool 'bash' was not used"
+            "message": "Agent did not request approval before executing"
           }
         ]
       }

integrations/claude-code/README.md

@@ -0,0 +1,205 @@
+# OpenAgents ↔ Claude Code Integration
+
+A bridge that allows Claude Code to use OpenAgents standards and context files.
+
+## Overview
+
+This integration provides two-way compatibility between OpenAgents and Claude Code:
+
+1. **Auto-Convert**: Convert OpenAgents to Claude Code format for distribution
+2. **Local Adapter**: Immediate context-aware behavior when using Claude in this repo
+
+## Directory Structure
+
+```
+integrations/claude-code/
+├── converter/           # Scripts to convert OpenAgents → Claude format
+│   └── src/
+│       └── convert-agents.js
+├── generated/           # Output of conversion (gitignored)
+│   ├── agents/
+│   └── skills/
+├── plugin/              # Final plugin files for distribution
+│   ├── agents/
+│   ├── skills/
+│   └── .claude-plugin/
+│       └── plugin.json
+├── bootstrap-install.sh # One-line installer (downloads bundle)
+└── install.sh           # Install script for distribution
+```
+
+## Quick Start
+
+### For This Repository (Local Adapter)
+
+Just run Claude in this repository:
+
+```bash
+cd /path/to/opencode-agents
+claude
+```
+
+Claude will automatically:
+- Load the `openagents-standards` Skill
+- Use `context-scout` to find relevant context in `.opencode/context/`
+- Apply OpenAgents standards to any task
+
+<details>
+<summary><strong>⚠️ Claude CLI Workaround</strong></summary>
+
+If Claude doesn't auto-load the local adapter when run in this repository:
+
+1. **Restart Claude Code** after any changes to `.claude/`
+2. **Explicitly reference the context** in your request:
+   ```
+   "Load context from .claude/skills/openagents-standards/SKILL.md and .claude/agents/context-scout.md, then help me create a new agent"
+   ```
+3. **Manual trigger** - if the Skill doesn't auto-trigger, start your request with:
+   ```
+   [Use OpenAgents standards]
+   ```
+   This will activate the context loading workflow.
+
+**Known Issue**: Skills auto-trigger based on Claude's heuristic. If it doesn't trigger:
+- The `context-scout` subagent will still be available
+- You can call it manually: `task(subagent_type="context-scout", ...)`
+- Claude will still follow OpenAgents patterns if you reference `.opencode/context/` files in your prompt
+
+</details>
+
+### Install Claude CLI (if needed)
+
+**macOS**:
+```bash
+brew install claude
+```
+
+**npm**:
+```bash
+npm install -g @anthropic-ai/claude-code
+```
+
+**Verify**:
+```bash
+claude --version
+```
+
+## For Distribution (Auto-Convert)
+
+### One-Line Install (Recommended)
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgents/main/integrations/claude-code/bootstrap-install.sh | bash
+```
+
+**Prereqs**: `git`, `bash`
+
+**Verify Claude Code**:
+```bash
+claude --version
+```
+
+This downloads the Claude integration bundle and runs the plugin installer.
+
+### Step 1: Run the Converter
+
+```bash
+cd integrations/claude-code/converter
+node src/convert-agents.js
+```
+
+This generates Claude-ready files in `integrations/claude-code/generated/`.
+
+### Step 2: Install for Personal Use
+
+```bash
+cd integrations/claude-code
+./install.sh
+```
+
+This copies the plugin to `~/.claude/plugins/openagents-bridge/`.
+
+### Step 3: Use with Claude Code
+
+**With plugin (recommended for distributed use)**:
+```bash
+claude --plugin-dir ~/.claude/plugins/openagents-bridge
+```
+
+**Without plugin (manual mode)**:
+```bash
+# Set environment variable to load context files
+export OPENAGENTS_CONTEXT_PATH=.opencode/context
+
+# Run Claude with context loaded from your prompt
+claude
+```
+
+<details>
+<summary><strong>💡 CLI Tips</strong></summary>
+
+- **Check loaded plugins**: `claude --print-plugins`
+- **Debug mode**: `claude --debug` (shows plugin loading)
+- **One-shot mode**: `claude "your request" --print-only`
+- **Session history**: Check `~/.claude/sessions/` for logs
+
+</details>
+
+## How It Works
+
+### Context Discovery
+
+1. **Skill Triggers**: The `openagents-standards` Skill automatically activates when you ask Claude to do anything.
+2. **Subagent Call**: Claude calls `context-scout` to find relevant files in `.opencode/context/`.
+3. **Standards Loading**: Claude reads the discovered files and applies OpenAgents standards.
+
+### Agent Conversion
+
+The converter maps OpenAgents frontmatter to Claude format:
+
+| OpenAgents Field | Claude Field |
+|------------------|--------------|
+| `id` | `name` |
+| `description` | `description` |
+| `tools` / `permissions` | `tools` |
+| `model` | `model` |
+| `mode: subagent` | `permissionMode: plan` |
+
+## Adding New Agents
+
+### For Local Use
+
+Add to `.opencode/agent/{category}/{agent}.md`. The local adapter in `.claude/` will pick it up on restart.
+
+### For Distribution
+
+1. Add to `.opencode/agent/{category}/{agent}.md`
+2. Run: `cd integrations/claude-code/converter && node src/convert-agents.js`
+3. The converted agent appears in `integrations/claude-code/generated/agents/`
+
+## Files to Commit
+
+- `.claude/` - Local adapter (committed)
+- `integrations/claude-code/converter/src/convert-agents.js` - Converter script (committed)
+- `integrations/claude-code/install.sh` - Install script (committed)
+
+## Files to GitIgnore
+
+- `integrations/claude-code/generated/` - Generated files (ignored)
+- `integrations/claude-code/plugin/` - Build output (ignored)
+
+## Requirements
+
+- Node.js 18+
+- Claude Code v2.1.6+
+
+## CLI Reference
+
+| Command | Description |
+|---------|-------------|
+| `claude` | Start interactive session |
+| `claude "request"` | One-shot request |
+| `claude --plugin-dir ~/.claude/plugins/openagents-bridge` | Load with plugin |
+| `claude --print-plugins` | Show loaded plugins |
+| `claude --debug` | Debug mode |
+| `claude --version` | Show version |

integrations/claude-code/converter/src/convert-agents.js

@@ -0,0 +1,233 @@
+#!/usr/bin/env node
+
+/**
+ * convert-agents.js
+ * Converts OpenAgents to Claude Code format
+ *
+ * Usage: node convert-agents.js [--watch]
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Configuration - Use absolute paths from the script location
+const SCRIPT_DIR = __dirname;
+const REPO_ROOT = path.resolve(path.join(SCRIPT_DIR, '../../../../'));
+const SOURCE_DIR = path.join(REPO_ROOT, '.opencode/agent');
+const OUTPUT_DIR = path.join(SCRIPT_DIR, '../generated');
+
+const CLAUDE_AGENTS_DIR = path.join(OUTPUT_DIR, 'agents');
+const CLAUDE_SKILLS_DIR = path.join(OUTPUT_DIR, 'skills');
+
+// Claude frontmatter fields (subset of OpenCode)
+const CLAUDE_FIELDS = ['name', 'description', 'tools', 'model', 'permissionMode', 'skills', 'hooks'];
+
+console.log('🚀 OpenAgents → Claude Code Converter');
+console.log(`   Source: ${SOURCE_DIR}`);
+console.log(`   Output: ${OUTPUT_DIR}\n`);
+
+/**
+ * Parses YAML frontmatter from markdown
+ */
+function parseFrontmatter(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+  if (!match) return { frontmatter: null, content };
+  
+  const yaml = match[1];
+  const body = match[2];
+  
+  const frontmatter = {};
+  yaml.split('\n').forEach(line => {
+    const colonIndex = line.indexOf(':');
+    if (colonIndex > -1) {
+      const key = line.slice(0, colonIndex).trim();
+      let value = line.slice(colonIndex + 1).trim();
+      
+      // Parse arrays
+      if (value.startsWith('[') && value.endsWith(']')) {
+        value = value.slice(1, -1).split(',').map(v => v.trim().replace(/"/g, ''));
+      }
+      
+      frontmatter[key] = value;
+    }
+  });
+  
+  return { frontmatter, body };
+}
+
+/**
+ * Converts OpenCode frontmatter to Claude format
+ */
+function convertFrontmatter(ocFrontmatter) {
+  const claude = {};
+  
+  // Map OpenCode fields to Claude fields
+  claude.name = ocFrontmatter.id || ocFrontmatter.name;
+  claude.description = ocFrontmatter.description;
+  
+  // Map tools from OpenCode permissions to Claude
+  if (ocFrontmatter.tools) {
+    claude.tools = ocFrontmatter.tools;
+  } else if (ocFrontmatter.permissions) {
+    // Extract allowed tools from permissions block
+    const tools = [];
+    if (ocFrontmatter.permissions.read) tools.push('Read');
+    if (ocFrontmatter.permissions.grep) tools.push('Grep');
+    if (ocFrontmatter.permissions.glob) tools.push('Glob');
+    if (ocFrontmatter.permissions.edit) tools.push('Edit');
+    if (ocFrontmatter.permissions.write) tools.push('Write');
+    if (ocFrontmatter.permissions.bash) tools.push('Bash');
+    claude.tools = tools.join(', ');
+  }
+  
+  // Map model
+  claude.model = mapModel(ocFrontmatter.model);
+  
+  // Map permissionMode (default to 'default' if not specified)
+  claude.permissionMode = ocFrontmatter.mode === 'subagent' ? 'plan' : 'default';
+  
+  return claude;
+}
+
+/**
+ * Maps OpenCode model names to Claude model aliases
+ */
+function mapModel(model) {
+  const modelMap = {
+    'opencode/grok-code': 'sonnet',
+    'opencode/grok': 'opus',
+    'gpt-4': 'sonnet',
+    'gpt-4o': 'sonnet',
+    'haiku': 'haiku',
+  };
+  return modelMap[model] || 'sonnet';
+}
+
+/**
+ * Generates Claude markdown from converted data
+ */
+function generateClaudeMarkdown(claudeFrontmatter, body) {
+  const fm = Object.entries(claudeFrontmatter)
+    .map(([key, value]) => {
+      if (Array.isArray(value)) {
+        return `${key}: [${value.map(v => `"${v}"`).join(', ')}]`;
+      }
+      return `${key}: "${value}"`;
+    })
+    .join('\n');
+  
+  return `---\n${fm}\n---\n\n${body}`;
+}
+
+/**
+ * Recursively finds all .md files in a directory
+ */
+function findMarkdownFiles(dir, files = []) {
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      findMarkdownFiles(fullPath, files);
+    } else if (entry.name.endsWith('.md')) {
+      files.push(fullPath);
+    }
+  }
+  
+  return files;
+}
+
+/**
+ * Processes a single agent file
+ */
+function processAgent(filePath) {
+  const content = fs.readFileSync(filePath, 'utf8');
+  const { frontmatter, body } = parseFrontmatter(content);
+  
+  if (!frontmatter) {
+    console.log(`⚠️  Skipping ${filePath} (no frontmatter)`);
+    return;
+  }
+  
+  const claudeFrontmatter = convertFrontmatter(frontmatter);
+  const claudeMarkdown = generateClaudeMarkdown(claudeFrontmatter, body);
+  
+  // Determine output path
+  const relativePath = path.relative(SOURCE_DIR, filePath);
+  const outputPath = path.join(CLAUDE_AGENTS_DIR, relativePath);
+  
+  // Ensure output directory exists
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  
+  fs.writeFileSync(outputPath, claudeMarkdown);
+  console.log(`✅ Converted: ${relativePath}`);
+}
+
+/**
+ * Main conversion function
+ */
+function convert() {
+  // Clean output directories
+  if (fs.existsSync(CLAUDE_AGENTS_DIR)) fs.rmSync(CLAUDE_AGENTS_DIR, { recursive: true });
+  if (fs.existsSync(CLAUDE_SKILLS_DIR)) fs.rmSync(CLAUDE_SKILLS_DIR, { recursive: true });
+  
+  fs.mkdirSync(CLAUDE_AGENTS_DIR, { recursive: true });
+  fs.mkdirSync(path.join(CLAUDE_SKILLS_DIR, 'openagents-standards'), { recursive: true });
+  
+  console.log('📦 Converting agents...\n');
+  
+  // Process category agents
+  const agentFiles = findMarkdownFiles(SOURCE_DIR);
+  agentFiles.forEach(processAgent);
+  
+  // Create default context-scout subagent
+  const contextScoutContent = `---
+name: context-scout
+description: Discovers and recommends OpenAgents context files using glob, read, and grep tools. Use when you need to find OpenAgents standards, guides, or domain knowledge in the .opencode/context directory.
+tools: Read, Grep, Glob
+model: haiku
+permissionMode: plan
+---
+
+# ContextScout
+
+You discover and recommend relevant OpenAgents context files from \`.opencode/context/\` based on the user's request.
+
+## Your Process
+
+1. Use \`Glob\` to find files in \`.opencode/context/\`.
+2. Use \`Read\` or \`Grep\` to verify relevance.
+3. Return file paths with brief descriptions.
+`;
+
+  fs.writeFileSync(
+    path.join(CLAUDE_AGENTS_DIR, 'context-scout.md'),
+    contextScoutContent
+  );
+  
+  // Create openagents-standards skill
+  const skillContent = `---
+name: openagents-standards
+description: Automatically triggers before any task to ensure OpenAgents standards and context are loaded. Use when the user asks to create, modify, or analyze anything in this repository.
+---
+
+# OpenAgents Standards Loader
+
+Before proceeding with the user's request:
+
+1. Call the \`context-scout\` subagent with the user's request to find relevant OpenAgents context files.
+2. Read the returned "Critical" and "High" priority files.
+3. Apply the OpenAgents standards found to your work.
+`;
+
+  fs.writeFileSync(
+    path.join(CLAUDE_SKILLS_DIR, 'openagents-standards/SKILL.md'),
+    skillContent
+  );
+  
+  console.log('\n✨ Conversion complete!');
+  console.log(`   Output: ${OUTPUT_DIR}`);
+}
+
+// Run conversion
+convert();

integrations/claude-code/install-claude.sh

@@ -0,0 +1,111 @@
+#!/usr/bin/env bash
+#
+# install-claude.sh
+# Installs OpenAgents to Claude Code with automatic conversion
+#
+
+set -euo pipefail
+
+# Colors
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+RED='\033[0;31m'
+NC='\033[0m' # No Color
+
+# Determine paths
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+OPENCODE_DIR="$REPO_ROOT/.opencode/agent"
+CONVERTER_DIR="$SCRIPT_DIR/converter"
+PLUGIN_DEST="$HOME/.claude/plugins/openagents-bridge"
+NODE_BIN="${NODE_BIN:-node}"
+
+echo -e "${GREEN}🚀 OpenAgents → Claude Code Installer${NC}"
+echo -e "   Source: $OPENCODE_DIR"
+echo -e "   Destination: $PLUGIN_DEST"
+echo ""
+
+# Check prerequisites
+check_prereqs() {
+    local missing=()
+
+    # Check for node
+    if ! command -v "$NODE_BIN" >/dev/null 2>&1; then
+        missing+=("$NODE_BIN")
+    fi
+
+    # Check for bash
+    if ! command -v bash >/dev/null 2>&1; then
+        missing+=("bash")
+    fi
+
+    if [ ${#missing[@]} -gt 0 ]; then
+        echo -e "${RED}✗ Missing required commands: ${missing[*]}${NC}" >&2
+        echo -e "  Install Node.js: https://nodejs.org/" >&2
+        exit 1
+    fi
+}
+
+# Run converter
+run_converter() {
+    echo -e "${YELLOW}🔄 Converting agents to Claude format...${NC}"
+    cd "$CONVERTER_DIR"
+
+    if ! "$NODE_BIN" src/convert-agents.js 2>&1 | grep -q "Conversion complete"; then
+        echo -e "${RED}✗ Conversion failed${NC}" >&2
+        exit 1
+    fi
+
+    echo -e "${GREEN}✅ Conversion complete${NC}"
+}
+
+# Install plugin
+install_plugin() {
+    echo -e "${YELLOW}📦 Installing plugin...${NC}"
+
+    # Create destination
+    mkdir -p "$HOME/.claude/plugins"
+
+    # Remove old installation
+    if [ -d "$PLUGIN_DEST" ]; then
+        echo "🗑️  Removing old installation..."
+        rm -rf "$PLUGIN_DEST"
+    fi
+
+    # Copy from generated (always fresh conversion)
+    cp -r "$CONVERTER_DIR/generated" "$PLUGIN_DEST"
+
+    echo -e "${GREEN}✅ Installation complete${NC}"
+}
+
+# Verify installation
+verify() {
+    if [ ! -f "$PLUGIN_DEST/agents/core/openagent.md" ]; then
+        echo -e "${RED}✗ Installation verification failed${NC}" >&2
+        echo "  Expected: $PLUGIN_DEST/agents/core/openagent.md" >&2
+        exit 1
+    fi
+
+    echo ""
+    echo -e "${GREEN}✨ Installation successful!${NC}"
+    echo ""
+    echo "To use with Claude Code:"
+    echo "   claude --plugin-dir $PLUGIN_DEST"
+    echo ""
+    echo "Or add to your Claude Code settings for automatic loading:"
+    echo '   { "plugins": ["openagents-bridge"] }'
+    echo ""
+    echo "Verify Claude Code installation:"
+    echo "   claude --version"
+}
+
+# Main workflow
+main() {
+    check_prereqs
+    run_converter
+    install_plugin
+    verify
+}
+
+# Allow specifying custom Node.js binary via NODE_BIN environment variable
+main "$@"

registry.json

@@ -2401,6 +2401,88 @@
         ],
         "dependencies": [],
         "category": "standard"
+      },
+      {
+        "id": "claude-agent-skills",
+        "name": "Claude Agent Skills",
+        "type": "context",
+        "path": ".opencode/context/to-be-consumed/claude-code-docs/agent-skills.md",
+        "description": "Claude Code: Agent Skills Documentation",
+        "tags": [
+          "claude",
+          "skills",
+          "docs"
+        ],
+        "dependencies": [],
+        "category": "standard"
+      },
+      {
+        "id": "claude-create-subagents",
+        "name": "Claude Create Subagents",
+        "type": "context",
+        "path": ".opencode/context/to-be-consumed/claude-code-docs/create-subagents.md",
+        "description": "Claude Code: Creating Subagents",
+        "tags": [
+          "claude",
+          "subagents",
+          "docs"
+        ],
+        "dependencies": [],
+        "category": "standard"
+      },
+      {
+        "id": "claude-hooks",
+        "name": "Claude Hooks",
+        "type": "context",
+        "path": ".opencode/context/to-be-consumed/claude-code-docs/hooks.md",
+        "description": "Claude Code: Hooks Documentation",
+        "tags": [
+          "claude",
+          "hooks",
+          "docs"
+        ],
+        "dependencies": [],
+        "category": "standard"
+      },
+      {
+        "id": "claude-plugins",
+        "name": "Claude Plugins",
+        "type": "context",
+        "path": ".opencode/context/to-be-consumed/claude-code-docs/plugins.md",
+        "description": "Claude Code: Plugins Documentation",
+        "tags": [
+          "claude",
+          "plugins",
+          "docs"
+        ],
+        "dependencies": [],
+        "category": "standard"
+      },
+      {
+        "id": "workflows-delegation",
+        "name": "Delegation Workflow",
+        "type": "context",
+        "path": ".opencode/context/core/workflows/delegation.md",
+        "description": "Delegation Workflow (Symlink)",
+        "tags": [
+          "workflows",
+          "delegation"
+        ],
+        "dependencies": [],
+        "category": "standard"
+      },
+      {
+        "id": "workflows-review",
+        "name": "Review Workflow",
+        "type": "context",
+        "path": ".opencode/context/core/workflows/review.md",
+        "description": "Review Workflow (Symlink)",
+        "tags": [
+          "workflows",
+          "review"
+        ],
+        "dependencies": [],
+        "category": "standard"
       }
     ],
     "config": [
@@ -2496,6 +2578,7 @@
         "context:quick-start",
         "context:core/*",
         "context:project-intelligence/*",
+        "context:to-be-consumed/*",
         "context:adding-skill",
         "config:env-example",
         "config:readme"
@@ -2527,6 +2610,7 @@
         "context:quick-start",
         "context:core/*",
         "context:project-intelligence/*",
+        "context:to-be-consumed/*",
         "context:adding-skill",
         "config:env-example",
         "config:readme"
@@ -2574,6 +2658,7 @@
         "context:quick-start",
         "context:core/*",
         "context:project-intelligence/*",
+        "context:to-be-consumed/*",
         "context:adding-skill",
         "config:env-example",
         "config:readme"
@@ -2630,6 +2715,7 @@
         "context:quick-start",
         "context:core/*",
         "context:project-intelligence/*",
+        "context:to-be-consumed/*",
         "context:adding-skill",
         "config:env-example",
         "config:readme"

scripts/bridge/sync-to-claude.sh

@@ -0,0 +1,38 @@
+#!/bin/bash
+
+# sync-to-claude.sh
+# Syncs OpenCode Agents to Claude Code plugin directory
+
+SOURCE_DIR=".opencode/agent"
+DEST_DIR=".opencode/integrations/claude-code/agents"
+CLAUDE_DIR=".claude/plugins/openagent"
+
+echo "🚀 Starting OpenBridge Sync..."
+
+# Ensure destination exists
+mkdir -p "$DEST_DIR"
+
+# 1. Sync Subagents (Core logic)
+echo "📦 Syncing subagents..."
+cp .opencode/agent/subagents/core/*.md "$DEST_DIR/" 2>/dev/null
+
+# 2. Sync Category Agents (Convert to Claude Subagents)
+# Note: We rename them to be flatter for Claude's /agents menu
+echo "🤖 Syncing category agents..."
+find "$SOURCE_DIR" -maxdepth 2 -name "*.md" -not -path "*/subagents/*" | while read -r agent; do
+    filename=$(basename "$agent")
+    # Add Claude-specific frontmatter if missing (simple approach)
+    # Claude needs name and description in frontmatter
+    cp "$agent" "$DEST_DIR/$filename"
+done
+
+# 3. Installation - Link to .claude directory for immediate use
+echo "🔗 Installing plugin to .claude/plugins/openagent..."
+mkdir -p .claude/plugins
+# Use a symbolic link so changes in integrations/ are reflected
+rm -rf "$CLAUDE_DIR"
+ln -s "$(pwd)/.opencode/integrations/claude-code" "$CLAUDE_DIR"
+
+echo "✅ Sync complete!"
+echo "💡 To use in Claude Code, run: claude"
+echo "   Claude will now automatically use 'context-scout' and apply 'repo-standards'."

src/calculator.js

@@ -1,34 +0,0 @@
-/**
- * Calculator Module
- * Pure functions for basic arithmetic operations
- */
-
-/**
- * Adds two numbers
- * @param {number} a - First number
- * @param {number} b - Second number
- * @returns {number} Sum of a and b
- */
-const add = (a, b) => a + b;
-
-/**
- * Subtracts second number from first number
- * @param {number} a - Number to subtract from
- * @param {number} b - Number to subtract
- * @returns {number} Difference of a and b
- */
-const subtract = (a, b) => a - b;
-
-/**
- * Multiplies two numbers
- * @param {number} a - First number
- * @param {number} b - Second number
- * @returns {number} Product of a and b
- */
-const multiply = (a, b) => a * b;
-
-module.exports = {
-  add,
-  subtract,
-  multiply,
-};

src/models/User.js

@@ -1,39 +0,0 @@
-/**
- * User model with name and email properties
- */
-class User {
-  /**
-   * Creates a new User instance
-   * @param {string} name - User's name
-   * @param {string} email - User's email address
-   */
-  constructor(name, email) {
-    this.name = name;
-    this.email = email;
-  }
-
-  /**
-   * Returns a plain object representation of the user
-   * @returns {Object} User data as plain object
-   */
-  toObject() {
-    return {
-      name: this.name,
-      email: this.email
-    };
-  }
-
-  /**
-   * Creates a new User with updated properties (immutable update)
-   * @param {Object} updates - Properties to update
-   * @returns {User} New User instance with updates applied
-   */
-  update(updates) {
-    return new User(
-      updates.name ?? this.name,
-      updates.email ?? this.email
-    );
-  }
-}
-
-module.exports = User;