refactor: simplify agent execution philosophy and reorganize context structure

Major Changes:
- Simplified OpenAgent execution philosophy (universal agent, delegate sparingly)
- Reorganized context into 3-tier structure: standards/, workflows/, system/
- Improved approval gate wording for clarity
- Enhanced .gitignore with comprehensive Node.js patterns
- Added comprehensive plugin development guide

Context Reorganization:
- Consolidated scattered files into organized structure with Quick Reference sections
- Emphasis on lazy loading for token efficiency (60-80% token savings)
- New standards: code.md, docs.md, tests.md, patterns.md, analysis.md
- New workflows: delegation.md, sessions.md, task-breakdown.md, review.md
- New system: context-guide.md (master reference)

Delegation Improvements:
- Removed complex XML-style routing rules
- Simplified to clear when/how structure with 7 delegation criteria
- Added Perspective and Simulation as delegation triggers
- Clearer delegation template and process

Documentation Enhancements:
- Added building-plugins.md (1,274 lines - comprehensive plugin guide)
- Updated how-context-works.md with research-backed architecture
- Enhanced slash-commands-and-subagents.md with path resolution findings

Content Preservation:
- context-discovery.md → system/context-guide.md + workflows/sessions.md
- context-management.md → workflows/sessions.md
- essential-patterns.md → standards/patterns.md
- session-management.md → workflows/sessions.md

.gitignore

@@ -37,6 +37,14 @@ Thumbs.db
 # Logs
 logs
 *.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+.pnpm-debug.log*
+
+# Diagnostic reports (https://nodejs.org/api/report.html)
+report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
 
 # Runtime data
 pids
@@ -44,13 +52,141 @@ pids
 *.seed
 *.pid.lock
 
+# Directory for instrumented libs generated by jscoverage/JSCover
+lib-cov
+
 # Coverage directory used by tools like istanbul
-coverage/
+coverage
+*.lcov
+
+# nyc test coverage
 .nyc_output
 
-# Temporary folders
+# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
+.grunt
+
+# Bower dependency directory (https://bower.io/)
+bower_components
+
+# node-waf configuration
+.lock-wscript
+
+# Compiled binary addons (https://nodejs.org/api/addons.html)
+build/Release
+
+# Dependency directories
+node_modules/
+jspm_packages/
+
+# Snowpack dependency directory (https://snowpack.dev/)
+web_modules/
+
+# TypeScript cache
+*.tsbuildinfo
+
+# Optional npm cache directory
+.npm
+
+# Optional eslint cache
+.eslintcache
+
+# Optional stylelint cache
+.stylelintcache
+
+# Microbundle cache
+.rpt2_cache/
+.rts2_cache_cjs/
+.rts2_cache_es/
+.rts2_cache_umd/
+
+# Optional REPL history
+.node_repl_history
+
+# Output of 'npm pack'
+*.tgz
+
+# Yarn Integrity file
+.yarn-integrity
+
+# dotenv environment variable files
+.env
+.env.development.local
+.env.test.local
+.env.production.local
+.env.local
+
+# parcel-bundler cache (https://parceljs.org/)
+.cache
+.parcel-cache
+
+# Next.js build output
+.next
+out
+
+# Nuxt.js build / generate output
+.nuxt
+dist
+
+# Gatsby files
+.cache/
+# Comment in the public line in if your project uses Gatsby and not Next.js
+# https://nextjs.org/blog/next-9-1#public-directory-support
+# public
+
+# vuepress build output
+.vuepress/dist
+
+# vuepress v2.x temp and cache directory
+.temp
+.cache
+
+# Docusaurus cache and generated files
+.docusaurus
+
+# Serverless directories
+.serverless/
+
+# FuseBox cache
+.fusebox/
+
+# DynamoDB Local files
+.dynamodb/
+
+# TernJS port file
+.tern-port
+
+# Stores VSCode versions used for testing VSCode extensions
+.vscode-test
+
+# yarn v2
+.yarn/cache
+.yarn/unplugged
+.yarn/build-state.yml
+.yarn/install-state.gz
+.pnp.*
+
+# macOS
+.DS_Store
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Temporary files
 tmp/
 temp/
+
+# Installation test artifacts
+.opencode.backup-*
+.opencode-test/
+.opencode-agents-version
+*.backup-*/
+
+# Test output
+/tmp/install-output.log
 .tmp/
 
 # Optional npm cache directory

.opencode/agent/openagent.md

@@ -27,7 +27,7 @@ permissions:
 
 <critical_rules priority="absolute" enforcement="strict">
   <rule id="approval_gate" scope="all_execution">
-    ALWAYS request approval before ANY execution (bash, write, edit, task delegation)
+    ALWAYS request approval before ANY execution (bash, write, edit, task delegation). Read and list operations do not require approval.
   </rule>
   <rule id="stop_on_failure" scope="validation">
     STOP immediately on test failures or errors - NEVER auto-fix
@@ -167,60 +167,58 @@ permissions:
   </stage>
 </workflow>
 
+<execution_philosophy>
+  You are a UNIVERSAL agent - handle most tasks directly.
+  
+  **Capabilities**: Write code, docs, tests, reviews, analysis, debugging, research, bash, file operations
+  
+  **Delegate only when**: 4+ files, specialized expertise needed, thorough multi-component review, complex dependencies, or user requests breakdown
+  
+  **Default**: Execute directly, fetch context files as needed (lazy), keep it simple, don't over-delegate
+  
+  **Delegation**: Create .tmp/sessions/{id}/context.md with requirements/decisions/files/instructions, reference static context, cleanup after
+</execution_philosophy>
+
 <delegation_rules id="delegation_rules">
-  <context_file_creation when="delegating">
-    Only create context file when BOTH:
-    - Delegating to a subagent AND
-    - Context is verbose (>2 sentences) OR risk of misinterpretation
+  
+  <when_to_delegate>
+    Delegate to general agent when ANY of these conditions:
     
-    See: .opencode/context/core/context-discovery.md for details
-  </context_file_creation>
-
-  <route agent="@subagents/core/task-manager" 
-         category="features"
-         when="3+_files OR 60+_min OR complex_dependencies OR explicit_request"
-         output=".tmp/sessions/{id}/tasks/{name}-tasks.md"
-         context_inheritance="true">
-    <example>User: "Build user authentication system"</example>
-  </route>
-
-  <route agent="@subagents/core/documentation"
-         category="documentation"
-         when="comprehensive_docs OR multi_page OR codebase_analysis OR explicit_request">
-    <example>User: "Create API documentation for all endpoints"</example>
-  </route>
-
-  <route agent="@subagents/utils/image-specialist"
-         category="images"
-         when="image_gen OR image_edit OR image_analysis"
-         availability="check_profile">
-    <example>User: "Generate a logo" or "Edit this image"</example>
-  </route>
-
-  <route agent="@subagents/code/reviewer"
-         category="review"
-         when="code_review OR security_analysis"
-         availability="check_profile">
-    <example>User: "Review this code for security issues"</example>
-  </route>
-
-  <route agent="@subagents/code/codebase-pattern-analyst"
-         category="patterns"
-         when="pattern_discovery OR how_do_we_questions"
-         availability="check_profile">
-    <example>User: "How do we handle pagination in this codebase?"</example>
-  </route>
-
-  <route agent="@subagents/code/*"
-         category="code"
-         when="code_specific_task"
-         availability="check_profile">
-    <example>User: "Write tests for this function"</example>
-  </route>
-
-  <direct_execution when="single_file OR simple_task_under_30min OR quick_edit OR explicit_openagent_request">
-    <example>User: "Create a README" or "Update this function"</example>
-  </direct_execution>
+    1. **Scale**: 4+ files to modify/create
+    2. **Expertise**: Needs specialized knowledge (security, algorithms, architecture, performance)
+    3. **Review**: Needs thorough review across multiple components
+    4. **Complexity**: Multi-step coordination with dependencies
+    5. **Perspective**: Need fresh eyes, alternative approaches, or different viewpoint
+    6. **Simulation**: Testing scenarios, edge cases, user behavior, what-if analysis
+    7. **User request**: User explicitly asks for breakdown/delegation
+    
+    Otherwise: Execute directly (you are universal, handle it)
+  </when_to_delegate>
+  
+  <how_to_delegate>
+    1. Create temp context: `.tmp/sessions/{timestamp}-{task-slug}/context.md`
+    2. Populate using template from .opencode/context/core/workflows/delegation.md
+    3. Delegate with context path and brief description
+    4. Cleanup after completion (ask user first)
+    
+    See .opencode/context/core/workflows/delegation.md for full template structure and process.
+  </how_to_delegate>
+  
+  <examples>
+    **Execute Directly:**
+    ✅ "Fix this bug" → Single file, clear fix
+    ✅ "Add input validation" → Straightforward enhancement
+    
+    **Delegate for Complexity:**
+    ⚠️ "Refactor data layer across 5 files" → Multi-file coordination
+    ⚠️ "Implement feature X with Y and Z components" → 4+ files, complex integration
+    
+    **Delegate for Perspective/Simulation:**
+    ⚠️ "Review this API design - what could go wrong?" → Fresh perspective needed
+    ⚠️ "Simulate edge cases for this algorithm" → Testing scenarios
+    ⚠️ "What are alternative approaches to solve X?" → Brainstorming alternatives
+  </examples>
+  
 </delegation_rules>
 
 <principles>
@@ -236,17 +234,36 @@ permissions:
   <transparent>Explain decisions, show reasoning when helpful</transparent>
 </principles>
 
-<references>
-  <session_management ref=".opencode/context/core/session-management.md">
-    Lazy initialization, session isolation, cleanup policy, error handling
-  </session_management>
-  <context_discovery ref=".opencode/context/core/context-discovery.md">
-    Dynamic context loading, manifest indexing, keyword search, delegation patterns
-  </context_discovery>
-  <context_management ref=".opencode/context/core/context-management.md">
-    Full context management strategy including session structure and workflows
-  </context_management>
-  <essential_patterns ref=".opencode/context/core/essential-patterns.md">
-    Core coding patterns, error handling, security, testing best practices
-  </essential_patterns>
-</references>
+<static_context>
+  Guidelines in .opencode/context/core/ - fetch when needed (WITHOUT @):
+  
+  **Standards** (quality guidelines + analysis):
+  - standards/code.md - Modular, functional code
+  - standards/docs.md - Documentation standards
+  - standards/tests.md - Testing standards
+  - standards/patterns.md - Core patterns
+  - standards/analysis.md - Analysis framework
+  
+  **Workflows** (process templates + review):
+  - workflows/delegation.md - Delegation template
+  - workflows/task-breakdown.md - Task breakdown
+  - workflows/sessions.md - Session lifecycle
+  - workflows/review.md - Code review guidelines
+  
+  See system/context-guide.md for full guide. Fetch only what's relevant - keeps prompts lean.
+</static_context>
+
+<critical_rules priority="absolute" enforcement="strict">
+  <rule id="approval_gate" scope="all_execution">
+    ALWAYS request approval before ANY execution (bash, write, edit, task delegation). Read and list operations do not require approval.
+  </rule>
+  <rule id="stop_on_failure" scope="validation">
+    STOP immediately on test failures or errors - NEVER auto-fix
+  </rule>
+  <rule id="report_first" scope="error_handling">
+    On failure: REPORT → PROPOSE FIX → REQUEST APPROVAL → FIX (never auto-fix)
+  </rule>
+  <rule id="confirm_cleanup" scope="session_management">
+    ALWAYS confirm before deleting session files or cleanup operations
+  </rule>
+</critical_rules>

.opencode/context/core/context-discovery.md

@@ -1,226 +0,0 @@
-# Context Discovery
-
-## Purpose
-
-**Dynamically load relevant context files when delegating to subagents**
-
-Allows subagents to discover and access context created earlier in the session, preventing information loss across delegation boundaries.
-
-## How It Works
-
-### 1. Context File Creation
-
-When creating a context file, add metadata to manifest:
-
-```json
-"context_files": {
-  "features/user-auth-context.md": {
-    "created": "2025-01-18T14:30:22Z",
-    "for": "@subagents/core/task-manager",
-    "keywords": ["user-auth", "authentication", "features"]
-  }
-}
-```
-
-**Metadata Fields**:
-- `created`: Timestamp of file creation
-- `for`: Target subagent (which agent will use this)
-- `keywords`: Array of searchable keywords for discovery
-
-### 2. Context Indexing
-
-Manifest maintains keyword index for fast lookup:
-
-```json
-"context_index": {
-  "user-auth": [
-    "features/user-auth-context.md",
-    "tasks/user-auth-tasks.md"
-  ],
-  "api": [
-    "documentation/api-docs-context.md"
-  ]
-}
-```
-
-**Index Structure**:
-- Key: Keyword (from context file metadata)
-- Value: Array of file paths containing that keyword
-
-### 3. Context Discovery Process
-
-When delegating to subagent:
-
-1. **Extract keywords** from user request or task context
-2. **Search manifest** `context_index` for matching keywords
-3. **Find related files** by category or keyword match
-4. **Pass file paths** to subagent in delegation prompt
-5. **Subagent reads** context files as needed
-
-### 4. Delegation Pattern
-
-**Context Reference Format**:
-```
-Related context available at: .tmp/sessions/{session-id}/features/user-auth-context.md
-```
-
-**Full Delegation Example**:
-```
-Delegating to @subagents/code/coder-agent:
-
-"Implement user authentication login component.
-
-Related context available at:
-- .tmp/sessions/20250118-143022-a4f2/features/user-auth-context.md
-- .tmp/sessions/20250118-143022-a4f2/tasks/user-auth-tasks.md
-
-Read these files for full context on requirements and task breakdown."
-```
-
-## When to Create Context Files
-
-**Only create when ALL of these apply**:
-- Delegating to a subagent
-- Context description is verbose (>2 sentences) OR
-- Risk of misinterpretation without detailed context
-
-**Don't create for**:
-- Simple, one-line instructions
-- Direct execution (no delegation)
-- Conversational questions
-
-## Context File Categories
-
-```
-features/     - Feature development context
-documentation/ - Documentation tasks
-code/         - Code-related tasks
-refactoring/  - Refactoring tasks
-testing/      - Testing tasks
-tasks/        - Task breakdowns created by task-manager
-general/      - General tasks that don't fit other categories
-```
-
-## Context File Template
-
-```markdown
-# Context: {Task Name}
-Session: {session-id}
-
-## Request Summary
-[Brief description of what needs to be done]
-
-## Background
-[Relevant context and information]
-
-## Expected Output
-[What the subagent should produce]
-
-## Constraints
-[Any limitations or requirements]
-
-## Related Context
-[Links to other context files if applicable]
-```
-
-## Discovery Strategies
-
-### By Keyword
-Search `context_index` for exact keyword matches:
-```
-User: "Add login validation"
-Keywords: ["login", "validation", "user-auth"]
-→ Finds: features/user-auth-context.md, tasks/user-auth-tasks.md
-```
-
-### By Category
-Search `context_files` for matching category:
-```
-Delegating to @documentation agent
-Category: "documentation"
-→ Finds all files in documentation/ folder
-```
-
-### By Target Agent
-Search `context_files` for files created for specific agent:
-```
-Delegating to @task-manager
-Filter: "for": "@subagents/core/task-manager"
-→ Finds all context files created for task-manager
-```
-
-## Example Workflow
-
-```
-1. User: "Build user authentication system"
-   → OpenAgent creates: features/user-auth-context.md
-   → Manifest updated with keywords: ["user-auth", "authentication", "features"]
-   → Delegates to @task-manager with context file path
-   
-2. Task-manager creates: tasks/user-auth-tasks.md
-   → Manifest updated with keywords: ["user-auth", "tasks", "breakdown"]
-   → Both files now indexed under "user-auth"
-   
-3. User: "Implement the login component"
-   → OpenAgent searches manifest for "user-auth" OR "login"
-   → Finds: features/user-auth-context.md, tasks/user-auth-tasks.md
-   → Delegates to @coder-agent with references to BOTH files
-   → Coder-agent reads both files to understand full context
-   
-4. User: "Add password reset feature"
-   → OpenAgent searches manifest for "user-auth" OR "password"
-   → Finds existing user-auth context
-   → Creates new: features/password-reset-context.md
-   → Links to existing user-auth context
-   → Delegates with all related context files
-```
-
-## Benefits
-
-✅ **No context loss**: Information persists across subagent calls
-✅ **Automatic discovery**: Related context found by keywords
-✅ **Flexible**: Subagents read only what they need
-✅ **Traceable**: Manifest shows all context relationships
-✅ **Scalable**: Works with multiple context files per session
-✅ **Reusable**: Later tasks can reference earlier context
-
-## Context Inheritance
-
-**Load related context files from manifest before delegating**
-
-When delegating to a subagent:
-1. Check if session exists
-2. Read manifest if available
-3. Search for related context by keyword/category
-4. Include relevant context file paths in delegation
-5. Subagent reads context files as first step
-
-This ensures subagents have full context from earlier in the session.
-
-## Error Handling
-
-### Manifest Not Found
-- Session not initialized yet
-- Continue without context discovery
-- Create new session if context file needed
-
-### Context File Missing
-- File was deleted or moved
-- Warn user about missing context
-- Continue with available context
-- Update manifest to remove missing file
-
-### Keyword Collision
-- Multiple files match same keyword
-- Include all matching files in delegation
-- Let subagent determine relevance
-- Consider more specific keywords in future
-
-## Best Practices
-
-1. **Use specific keywords**: "user-auth" better than "auth"
-2. **Include category in keywords**: ["features", "user-auth"]
-3. **Link related context**: Reference other context files
-4. **Update manifest immediately**: Don't delay indexing
-5. **Clean up stale context**: Remove when task complete
-6. **Validate file exists**: Before passing to subagent

.opencode/context/core/context-management.md

@@ -1,256 +0,0 @@
-# Context Management Strategy
-
-## Session-Based Isolation
-
-### Purpose
-Prevent concurrent agent instances from interfering with each other by using isolated session folders.
-
-### Session Structure
-```
-.tmp/sessions/{session-id}/{task-category}/{task-name}-context.md
-```
-
-### Session ID Format
-`{timestamp}-{random-4-chars}`
-
-Example: `20250118-143022-a4f2`
-
-### Session Manifest
-Each session has a manifest file tracking all context files:
-
-**Location**: `.tmp/sessions/{session-id}/.manifest.json`
-
-**Structure**:
-```json
-{
-  "session_id": "20250118-143022-a4f2",
-  "created_at": "2025-01-18T14:30:22Z",
-  "last_activity": "2025-01-18T14:35:10Z",
-  "context_files": {
-    "features/user-auth-context.md": {
-      "created": "2025-01-18T14:30:22Z",
-      "for": "@subagents/core/task-manager",
-      "keywords": ["user-auth", "authentication", "features"]
-    },
-    "tasks/user-auth-tasks.md": {
-      "created": "2025-01-18T14:32:15Z",
-      "for": "@subagents/core/task-manager",
-      "keywords": ["user-auth", "tasks", "breakdown"]
-    },
-    "documentation/api-docs-context.md": {
-      "created": "2025-01-18T14:35:10Z",
-      "for": "@subagents/core/documentation",
-      "keywords": ["api", "documentation"]
-    }
-  },
-  "context_index": {
-    "user-auth": [
-      "features/user-auth-context.md",
-      "tasks/user-auth-tasks.md"
-    ],
-    "api": [
-      "documentation/api-docs-context.md"
-    ]
-  }
-}
-```
-
-## Temporary Context Files
-
-### When to Create
-Only create context files when **ALL** of these apply:
-- Delegating to a subagent
-- Context description is verbose (>2 sentences) OR
-- Risk of misinterpretation without detailed context
-
-### File Structure
-```
-.tmp/sessions/{session-id}/{task-category}/{task-name}-context.md
-```
-
-### Categories
-- `features/` - Feature development context
-- `documentation/` - Documentation tasks
-- `code/` - Code-related tasks
-- `refactoring/` - Refactoring tasks
-- `testing/` - Testing tasks
-- `tasks/` - Task breakdowns created by task-manager
-- `general/` - General tasks that don't fit other categories
-
-### Examples
-```
-.tmp/sessions/20250118-143022-a4f2/features/user-auth-context.md
-.tmp/sessions/20250118-143022-a4f2/documentation/api-docs-context.md
-.tmp/sessions/20250118-150000-b7k9/code/database-refactor-context.md
-.tmp/sessions/20250118-151500-c3x8/testing/integration-tests-context.md
-```
-
-### File Contents
-```markdown
-# Context: {Task Name}
-Session: {session-id}
-
-## Request Summary
-[Brief description of what needs to be done]
-
-## Background
-[Relevant context and information]
-
-## Expected Output
-[What the subagent should produce]
-
-## Constraints
-[Any limitations or requirements]
-```
-
-## Cleanup Strategy
-
-### During Session
-1. Remove individual context files after task completion
-2. Update manifest to remove file entry
-3. Update `last_activity` timestamp
-
-### End of Session
-1. Remove entire session folder: `.tmp/sessions/{session-id}/`
-2. Only delete files tracked in current session's manifest
-
-### Stale Session Cleanup
-- Automatically clean sessions older than 24 hours with no activity
-- Check `last_activity` timestamp in manifest
-- Safe to run periodically without affecting active sessions
-
-### Manual Cleanup
-Users can safely delete:
-- Entire `.tmp/` folder anytime
-- Individual session folders
-- Stale sessions (check `last_activity` timestamp)
-
-## Concurrent Safety
-
-### Isolation Guarantees
-✅ Each agent instance has unique session ID
-✅ Context files are isolated per session
-✅ Manifest tracks only files created by this session
-✅ Cleanup only affects current session's files
-✅ No risk of deleting another instance's context
-
-### Best Practices
-1. **Generate session ID early** - At first context file creation
-2. **Track all files** - Add every context file to manifest
-3. **Update activity** - Touch `last_activity` on each operation
-4. **Clean up promptly** - Remove files after task completion
-5. **Only clean own files** - Never delete files outside current session
-
-## Dynamic Context Loading
-
-### Purpose
-Allow subagents to discover and load relevant context files created earlier in the session.
-
-### How It Works
-
-**1. Context File Creation**
-When creating a context file, add metadata to manifest:
-```json
-"context_files": {
-  "features/user-auth-context.md": {
-    "created": "2025-01-18T14:30:22Z",
-    "for": "@subagents/core/task-manager",
-    "keywords": ["user-auth", "authentication", "features"]
-  }
-}
-```
-
-**2. Context Indexing**
-Manifest maintains keyword index for fast lookup:
-```json
-"context_index": {
-  "user-auth": [
-    "features/user-auth-context.md",
-    "tasks/user-auth-tasks.md"
-  ]
-}
-```
-
-**3. Context Discovery**
-When delegating to subagent:
-1. Search manifest for related context files (by keyword/category)
-2. Pass relevant context file paths to subagent
-3. Subagent reads context files as needed
-
-**4. Delegation Pattern**
-```
-Delegating to @subagents/code/coder-agent:
-"Implement user authentication login component.
-
-Related context available at:
-- .tmp/sessions/20250118-143022-a4f2/features/user-auth-context.md
-- .tmp/sessions/20250118-143022-a4f2/tasks/user-auth-tasks.md
-
-Read these files for full context on requirements and task breakdown."
-```
-
-### Example Workflow
-
-```
-1. User: "Build user authentication system"
-   → OpenAgent creates: features/user-auth-context.md
-   → Delegates to @task-manager
-   
-2. Task-manager creates: tasks/user-auth-tasks.md
-   → Both files tracked in manifest with keyword "user-auth"
-   
-3. User: "Implement the login component"
-   → OpenAgent searches manifest for "user-auth" context
-   → Finds both context files
-   → Delegates to @coder-agent with references to both files
-   → Coder-agent reads files to understand full context
-```
-
-### Benefits
-- **No context loss**: Information persists across subagent calls
-- **Automatic discovery**: Related context found by keywords
-- **Flexible**: Subagents read only what they need
-- **Traceable**: Manifest shows all context relationships
-
----
-
-## Why This Approach?
-
-### Session Isolation
-- **Concurrent safety**: Multiple agents can run simultaneously
-- **No conflicts**: Each session has its own namespace
-- **Easy cleanup**: Delete entire session folder when done
-- **Traceable**: Manifest shows what belongs to each session
-
-### Dynamic Context
-- **Discoverable**: Context files indexed by keywords
-- **Reusable**: Later subagents can access earlier context
-- **Flexible**: Load only relevant context
-- **Persistent**: Context survives across subagent calls
-
-### Why `.tmp/sessions/`?
-- Standard `.tmp/` convention (commonly ignored)
-- `sessions/` subfolder makes purpose clear
-- Session ID provides unique namespace
-- Easy to identify and clean up stale sessions
-- Hidden folder (starts with `.`)
-
-## Example Workflow
-
-```bash
-# Agent Instance 1 starts
-Session ID: 20250118-143022-a4f2
-Creates: .tmp/sessions/20250118-143022-a4f2/features/user-auth-context.md
-
-# Agent Instance 2 starts (concurrent)
-Session ID: 20250118-143030-b7k9
-Creates: .tmp/sessions/20250118-143030-b7k9/features/payment-context.md
-
-# Both agents work independently without conflicts
-
-# Agent Instance 1 completes
-Deletes: .tmp/sessions/20250118-143022-a4f2/ (entire folder)
-
-# Agent Instance 2 continues unaffected
-Still has: .tmp/sessions/20250118-143030-b7k9/
-```

.opencode/context/core/standards/analysis.md

@@ -0,0 +1,150 @@
+# Analysis Guidelines
+
+## Quick Reference
+
+**Process**: Context → Gather → Patterns → Impact → Recommendations
+
+**Report Format**: Context, Findings, Patterns, Issues (🔴🟡🔵), Recommendations, Trade-offs, Next Steps
+
+**Be**: Thorough, Objective, Specific, Actionable
+
+**Checklist**: Context stated, Evidence gathered, Patterns identified, Issues prioritized, Recommendations specific, Trade-offs considered
+
+---
+
+## Purpose
+Framework for analyzing code, patterns, and technical issues systematically.
+
+## When to Use
+Reference this when:
+- Analyzing codebase patterns
+- Investigating bugs or issues
+- Evaluating architectural decisions
+- Assessing code quality
+- Researching solutions
+
+## Analysis Process
+
+### 1. Understand Context
+- What are we analyzing and why?
+- What's the goal or question?
+- What's the scope?
+- What constraints exist?
+
+### 2. Gather Information
+- Read relevant code / data points
+- Check documentation
+- Search for patterns
+- Review related issues
+- Examine dependencies
+
+### 3. Identify Patterns
+- What's consistent across the codebase?
+- What conventions are followed?
+- What patterns are repeated?
+- What's inconsistent or unusual?
+
+### 4. Assess Impact
+- What are the implications?
+- What are the trade-offs?
+- What could break?
+- What are the risks?
+
+### 5. Provide Recommendations
+- What should be done?
+- Why this approach?
+- What are alternatives?
+- What's the priority?
+
+## Analysis Report Format
+
+```markdown
+## Analysis: {Topic}
+
+**Context:** {What we're analyzing and why}
+
+**Findings:**
+- {Key finding 1}
+- {Key finding 2}
+- {Key finding 3}
+
+**Patterns Observed:**
+- {Pattern 1}: {Description}
+- {Pattern 2}: {Description}
+
+**Issues Identified:**
+- 🔴 Critical: {Issue requiring immediate attention}
+- 🟡 Warning: {Issue to address soon}
+- 🔵 Suggestion: {Nice-to-have improvement}
+
+**Recommendations:**
+1. {Recommendation 1} - {Why}
+2. {Recommendation 2} - {Why}
+
+**Trade-offs:**
+- {Approach A}: {Pros/Cons}
+- {Approach B}: {Pros/Cons}
+
+**Next Steps:**
+- {Action 1}
+- {Action 2}
+```
+
+## Common Analysis Types
+
+### Code Quality Analysis
+- Complexity (cyclomatic, cognitive)
+- Duplication
+- Test coverage
+- Documentation completeness
+- Naming consistency
+- Error handling patterns
+
+### Architecture Analysis
+- Module dependencies
+- Coupling and cohesion
+- Separation of concerns
+- Scalability considerations
+- Performance bottlenecks
+
+### Bug Investigation
+- Reproduce the issue
+- Identify root cause
+- Assess impact and severity
+- Propose fix with rationale
+- Consider edge cases
+
+### Pattern Discovery
+- Search for similar implementations
+- Identify common approaches
+- Document conventions
+- Note inconsistencies
+- Recommend standardization
+
+## Best Practices
+
+### Be Thorough
+- Check multiple examples
+- Consider edge cases
+- Look for exceptions
+- Verify assumptions
+
+### Be Objective
+- Base conclusions on evidence
+- Avoid assumptions
+- Consider multiple perspectives
+- Acknowledge limitations
+
+### Be Specific
+- Provide concrete examples
+- Include file names and line numbers
+- Show code snippets
+- Quantify when possible
+
+### Be Actionable
+- Clear recommendations
+- Prioritize findings
+- Explain rationale
+- Suggest next steps
+
+

.opencode/context/core/standards/code.md

@@ -0,0 +1,163 @@
+# Code Standards
+
+## Quick Reference
+
+**Core Philosophy**: Modular, Functional, Maintainable
+**Golden Rule**: If you can't easily test it, refactor it
+
+**Critical Patterns** (use these):
+- ✅ Pure functions (same input = same output, no side effects)
+- ✅ Immutability (create new data, don't modify)
+- ✅ Composition (build complex from simple)
+- ✅ Small functions (< 50 lines)
+- ✅ Explicit dependencies (dependency injection)
+
+**Anti-Patterns** (avoid these):
+- ❌ Mutation, side effects, deep nesting
+- ❌ God modules, global state, large functions
+
+---
+
+## Core Philosophy
+
+**Modular**: Everything is a component - small, focused, reusable
+**Functional**: Pure functions, immutability, composition over inheritance
+**Maintainable**: Self-documenting, testable, predictable
+
+## Principles
+
+### Modular Design
+- Single responsibility per module
+- Clear interfaces (explicit inputs/outputs)
+- Independent and composable
+- < 100 lines per component (ideally < 50)
+
+### Functional Approach
+- **Pure functions**: Same input = same output, no side effects
+- **Immutability**: Create new data, don't modify existing
+- **Composition**: Build complex from simple functions
+- **Declarative**: Describe what, not how
+
+### Component Structure
+```
+component/
+├── index.js      # Public interface
+├── core.js       # Core logic (pure functions)
+├── utils.js      # Helpers
+└── tests/        # Tests
+```
+
+## Patterns
+
+### Pure Functions
+```javascript
+// ✅ Pure
+const add = (a, b) => a + b;
+const formatUser = (user) => ({ ...user, fullName: `${user.firstName} ${user.lastName}` });
+
+// ❌ Impure (side effects)
+let total = 0;
+const addToTotal = (value) => { total += value; return total; };
+```
+
+### Immutability
+```javascript
+// ✅ Immutable
+const addItem = (items, item) => [...items, item];
+const updateUser = (user, changes) => ({ ...user, ...changes });
+
+// ❌ Mutable
+const addItem = (items, item) => { items.push(item); return items; };
+```
+
+### Composition
+```javascript
+// ✅ Compose small functions
+const processUser = pipe(validateUser, enrichUserData, saveUser);
+const isValidEmail = (email) => validateEmail(normalizeEmail(email));
+
+// ❌ Deep inheritance
+class ExtendedUserManagerWithValidation extends UserManager { }
+```
+
+### Declarative
+```javascript
+// ✅ Declarative
+const activeUsers = users.filter(u => u.isActive).map(u => u.name);
+
+// ❌ Imperative
+const names = [];
+for (let i = 0; i < users.length; i++) {
+  if (users[i].isActive) names.push(users[i].name);
+}
+```
+
+## Naming
+
+- **Files**: lowercase-with-dashes.js
+- **Functions**: verbPhrases (getUser, validateEmail)
+- **Predicates**: isValid, hasPermission, canAccess
+- **Variables**: descriptive (userCount not uc), const by default
+- **Constants**: UPPER_SNAKE_CASE
+
+## Error Handling
+
+```javascript
+// ✅ Explicit error handling
+function parseJSON(text) {
+  try {
+    return { success: true, data: JSON.parse(text) };
+  } catch (error) {
+    return { success: false, error: error.message };
+  }
+}
+
+// ✅ Validate at boundaries
+function createUser(userData) {
+  const validation = validateUserData(userData);
+  if (!validation.isValid) {
+    return { success: false, errors: validation.errors };
+  }
+  return { success: true, user: saveUser(userData) };
+}
+```
+
+## Dependency Injection
+
+```javascript
+// ✅ Dependencies explicit
+function createUserService(database, logger) {
+  return {
+    createUser: (userData) => {
+      logger.info('Creating user');
+      return database.insert('users', userData);
+    }
+  };
+}
+
+// ❌ Hidden dependencies
+import db from './database.js';
+function createUser(userData) { return db.insert('users', userData); }
+```
+
+## Anti-Patterns
+
+❌ **Mutation**: Modifying data in place
+❌ **Side effects**: console.log, API calls in pure functions
+❌ **Deep nesting**: Use early returns instead
+❌ **God modules**: Split into focused modules
+❌ **Global state**: Pass dependencies explicitly
+❌ **Large functions**: Keep < 50 lines
+
+## Best Practices
+
+✅ Pure functions whenever possible
+✅ Immutable data structures
+✅ Small, focused functions (< 50 lines)
+✅ Compose small functions into larger ones
+✅ Explicit dependencies (dependency injection)
+✅ Validate at boundaries
+✅ Self-documenting code
+✅ Test in isolation
+
+**Golden Rule**: If you can't easily test it, refactor it.

.opencode/context/core/standards/docs.md

@@ -0,0 +1,148 @@
+# Documentation Standards
+
+## Quick Reference
+
+**Golden Rule**: If users ask the same question twice, document it
+
+**Document** (✅ DO):
+- WHY decisions were made
+- Complex algorithms/logic
+- Public APIs, setup, common use cases
+
+**Don't Document** (❌ DON'T):
+- Obvious code (i++ doesn't need comment)
+- What code does (should be self-explanatory)
+
+**Principles**: Audience-focused, Show don't tell, Keep current
+
+---
+
+## Principles
+
+**Audience-focused**: Write for users (what/how), developers (why/when), contributors (setup/conventions)
+**Show, don't tell**: Code examples, real use cases, expected output
+**Keep current**: Update with code changes, remove outdated info, mark deprecations
+
+## README Structure
+
+```markdown
+# Project Name
+Brief description (1-2 sentences)
+
+## Features
+- Key feature 1
+- Key feature 2
+
+## Installation
+```bash
+npm install package-name
+```
+
+## Quick Start
+```javascript
+const result = doSomething();
+```
+
+## Usage
+[Detailed examples]
+
+## API Reference
+[If applicable]
+
+## Contributing
+[Link to CONTRIBUTING.md]
+
+## License
+[License type]
+```
+
+## Function Documentation
+
+```javascript
+/**
+ * Calculate total price including tax
+ * 
+ * @param {number} price - Base price
+ * @param {number} taxRate - Tax rate (0-1)
+ * @returns {number} Total with tax
+ * 
+ * @example
+ * calculateTotal(100, 0.1) // 110
+ */
+function calculateTotal(price, taxRate) {
+  return price * (1 + taxRate);
+}
+```
+
+## What to Document
+
+### ✅ DO
+- **WHY** decisions were made
+- Complex algorithms/logic
+- Non-obvious behavior
+- Public APIs
+- Setup/installation
+- Common use cases
+- Known limitations
+- Workarounds (with explanation)
+
+### ❌ DON'T
+- Obvious code (i++ doesn't need comment)
+- What code does (should be self-explanatory)
+- Redundant information
+- Outdated/incorrect info
+
+## Comments
+
+### Good
+```javascript
+// Calculate discount by tier (Bronze: 5%, Silver: 10%, Gold: 15%)
+const discount = getDiscountByTier(customer.tier);
+
+// HACK: API returns null instead of [], normalize it
+const items = response.items || [];
+
+// TODO: Use async/await when Node 18+ is minimum
+```
+
+### Bad
+```javascript
+// Increment i
+i++;
+
+// Get user
+const user = getUser();
+```
+
+## API Documentation
+
+```markdown
+### POST /api/users
+Create a new user
+
+**Request:**
+```json
+{ "name": "John", "email": "john@example.com" }
+```
+
+**Response:**
+```json
+{ "id": "123", "name": "John", "email": "john@example.com" }
+```
+
+**Errors:**
+- 400 - Invalid input
+- 409 - Email exists
+```
+
+## Best Practices
+
+✅ Explain WHY, not just WHAT
+✅ Include working examples
+✅ Show expected output
+✅ Cover error handling
+✅ Use consistent terminology
+✅ Keep structure predictable
+✅ Update when code changes
+
+**Golden Rule**: If users ask the same question twice, document it.

.opencode/context/core/essential-patterns.md

@@ -1,5 +1,17 @@
 # Essential Patterns - Core Knowledge Base
 
+## Quick Reference
+
+**Critical Patterns**: Error Handling, Validation, Security, Logging
+
+**ALWAYS**: Handle errors gracefully, validate input, use env vars for secrets
+
+**NEVER**: Expose sensitive info, hardcode credentials, skip input validation
+
+**Language-agnostic**: Apply to all programming languages
+
+---
+
 These are language-agnostic patterns that apply to all programming languages. Language-specific implementations are loaded from context files based on project detection.
 
 ## Error Handling Pattern

.opencode/context/core/standards/tests.md

@@ -0,0 +1,125 @@
+# Testing Standards
+
+## Quick Reference
+
+**Golden Rule**: If you can't test it easily, refactor it
+
+**AAA Pattern**: Arrange → Act → Assert
+
+**Test** (✅ DO):
+- Happy path, edge cases, error cases
+- Business logic, public APIs
+
+**Don't Test** (❌ DON'T):
+- Third-party libraries, framework internals
+- Simple getters/setters, private details
+
+**Coverage**: Critical (100%), High (90%+), Medium (80%+)
+
+---
+
+## Principles
+
+**Test behavior, not implementation**: Focus on what code does, not how
+**Keep tests simple**: One assertion per test, clear names, minimal setup
+**Independent tests**: No shared state, run in any order
+**Fast and reliable**: Quick execution, no flaky tests, deterministic
+
+## Test Structure (AAA Pattern)
+
+```javascript
+test('calculateTotal returns sum of item prices', () => {
+  // Arrange - Set up test data
+  const items = [{ price: 10 }, { price: 20 }, { price: 30 }];
+  
+  // Act - Execute code
+  const result = calculateTotal(items);
+  
+  // Assert - Verify result
+  expect(result).toBe(60);
+});
+```
+
+## What to Test
+
+### ✅ DO Test
+- Happy path (normal usage)
+- Edge cases (boundaries, empty, null, undefined)
+- Error cases (invalid input, failures)
+- Business logic (core functionality)
+- Public APIs (exported functions)
+
+### ❌ DON'T Test
+- Third-party libraries
+- Framework internals
+- Simple getters/setters
+- Private implementation details
+
+## Coverage Goals
+
+1. **Critical**: Business logic, data transformations (100%)
+2. **High**: Public APIs, user-facing features (90%+)
+3. **Medium**: Utilities, helpers (80%+)
+4. **Low**: Simple wrappers, configs (optional)
+
+## Testing Pure Functions
+
+```javascript
+function add(a, b) { return a + b; }
+
+test('add returns sum', () => {
+  expect(add(2, 3)).toBe(5);
+  expect(add(-1, 1)).toBe(0);
+  expect(add(0, 0)).toBe(0);
+});
+```
+
+## Testing with Dependencies
+
+```javascript
+// Testable with dependency injection
+function createUserService(database) {
+  return {
+    getUser: (id) => database.findById('users', id)
+  };
+}
+
+// Test with mock
+test('getUser retrieves from database', () => {
+  const mockDb = {
+    findById: jest.fn().mockReturnValue({ id: 1, name: 'John' })
+  };
+  
+  const service = createUserService(mockDb);
+  const user = service.getUser(1);
+  
+  expect(mockDb.findById).toHaveBeenCalledWith('users', 1);
+  expect(user).toEqual({ id: 1, name: 'John' });
+});
+```
+
+## Test Naming
+
+```javascript
+// ✅ Good: Descriptive, clear expectation
+test('calculateDiscount returns 10% off for premium users', () => {});
+test('validateEmail returns false for invalid format', () => {});
+test('createUser throws error when email exists', () => {});
+
+// ❌ Bad: Vague, unclear
+test('it works', () => {});
+test('test user', () => {});
+```
+
+## Best Practices
+
+✅ Test one thing per test
+✅ Use descriptive test names
+✅ Keep tests independent
+✅ Mock external dependencies
+✅ Test edge cases and errors
+✅ Make tests readable
+✅ Run tests frequently
+✅ Fix failing tests immediately
+
+**Golden Rule**: If you can't test it easily, refactor it.

.opencode/context/core/system/context-guide.md

@@ -0,0 +1,171 @@
+# Context System Guide
+
+## Quick Reference
+
+**Golden Rule**: Fetch context when needed, not before (lazy loading)
+
+**Key Principle**: Reference files WITHOUT @ symbol - agent fetches only when needed
+
+**Structure**: standards/ (quality + analysis), workflows/ (process + review), system/ (internals)
+
+**Session Location**: `.tmp/sessions/{timestamp}-{task-slug}/context.md`
+
+---
+
+## Overview
+
+Context files provide guidelines and templates for specific tasks. Use lazy loading (fetch when needed) to keep prompts lean.
+
+## Available Context Files
+
+All files are in `.opencode/context/core/` with organized subfolders:
+
+### Standards (Quality Guidelines + Analysis)
+- `.opencode/context/core/standards/code.md` - Modular, functional code principles
+- `.opencode/context/core/standards/docs.md` - Documentation standards
+- `.opencode/context/core/standards/tests.md` - Testing standards
+- `.opencode/context/core/standards/patterns.md` - Core patterns (error handling, security)
+- `.opencode/context/core/standards/analysis.md` - Analysis framework
+
+### Workflows (Process Templates + Review)
+- `.opencode/context/core/workflows/delegation.md` - Delegation template
+- `.opencode/context/core/workflows/task-breakdown.md` - Complex task breakdown
+- `.opencode/context/core/workflows/sessions.md` - Session lifecycle
+- `.opencode/context/core/workflows/review.md` - Code review guidelines
+
+## Lazy Loading (Recommended)
+
+Reference files **WITHOUT** `@` symbol - agent fetches only when needed:
+
+```markdown
+"Write code following .opencode/context/core/standards/code.md"
+"Review using .opencode/context/core/workflows/review.md"
+"Break down task using .opencode/context/core/workflows/task-breakdown.md"
+```
+
+**Benefits:**
+- No prompt bloat
+- Fetch only what's relevant
+- Faster for simple tasks
+- Agent decides when to load
+
+## When to Use Each File
+
+### .opencode/context/core/standards/code.md
+- Writing new code
+- Modifying existing code
+- Following modular/functional patterns
+- Making architectural decisions
+
+### .opencode/context/core/standards/docs.md
+- Writing README files
+- Creating API documentation
+- Adding code comments
+
+### .opencode/context/core/standards/tests.md
+- Writing new tests
+- Running test suites
+- Debugging test failures
+
+### .opencode/context/core/standards/patterns.md
+- Error handling
+- Security patterns
+- Common code patterns
+
+### .opencode/context/core/standards/analysis.md
+- Analyzing codebase patterns
+- Investigating bugs
+- Evaluating architecture
+
+### .opencode/context/core/workflows/delegation.md
+- Delegating to general agent
+- Creating task context
+- Multi-file coordination
+
+### .opencode/context/core/workflows/task-breakdown.md
+- Tasks with 4+ files
+- Estimated effort >60 minutes
+- Complex dependencies
+
+### .opencode/context/core/workflows/sessions.md
+- Session lifecycle
+- Cleanup procedures
+- Session isolation
+
+### .opencode/context/core/workflows/review.md
+- Reviewing code
+- Conducting code audits
+- Providing PR feedback
+
+## Temporary Context (Session-Specific)
+
+When delegating, create focused task context:
+
+**Location**: `.tmp/sessions/{timestamp}-{task-slug}/context.md`
+
+**Structure**:
+```markdown
+# Task Context: {Task Name}
+
+Session ID: {id}
+Created: {timestamp}
+Status: in_progress
+
+## Current Request
+{What user asked for}
+
+## Requirements
+- {requirement 1}
+- {requirement 2}
+
+## Decisions Made
+- {decision 1}
+
+## Files to Modify/Create
+- {file 1} - {purpose}
+
+## Static Context Available
+- .opencode/context/core/standards/code.md
+- .opencode/context/core/standards/tests.md
+
+## Constraints/Notes
+{Important context}
+
+## Progress
+- [ ] {task 1}
+- [ ] {task 2}
+
+---
+**Instructions for Subagent:**
+{Specific instructions}
+```
+
+## Session Management
+
+### Session Structure
+```
+.tmp/sessions/{session-id}/
+├── context.md          # Task context
+├── notes.md            # Working notes
+└── artifacts/          # Generated files
+```
+
+### Session ID Format
+`{timestamp}-{random-4-chars}`
+Example: `20250119-143022-a4f2`
+
+### Cleanup
+- Ask user before deleting session files
+- Remove after task completion
+- Keep if user wants to review
+
+## Best Practices
+
+✅ Use lazy loading (no @ symbol)
+✅ Fetch only relevant context
+✅ Create temp context when delegating
+✅ Clean up sessions after completion
+✅ Reference specific sections when possible
+✅ Keep temp context focused and concise
+
+**Golden Rule**: Fetch context when needed, not before.

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

@@ -0,0 +1,81 @@
+# Delegation Context Template
+
+## Quick Reference
+
+**Process**: Create context → Populate → Delegate → Cleanup
+
+**Location**: `.tmp/sessions/{timestamp}-{task-slug}/context.md`
+
+**Template Sections**: Request, Requirements, Decisions, Files, Static Context, Constraints, Progress, Instructions
+
+---
+
+Use this template when creating temporary context files for task delegation.
+
+## Template Structure
+
+**Location**: `.tmp/sessions/{timestamp}-{task-slug}/context.md`
+
+```markdown
+# Task Context: {Task Name}
+
+Session ID: {id}
+Created: {timestamp}
+Status: in_progress
+
+## Current Request
+{What user asked for}
+
+## Requirements
+- {requirement 1}
+- {requirement 2}
+
+## Decisions Made
+- {decision 1 - approach/constraints}
+- {decision 2}
+
+## Files to Modify/Create
+- {file 1} - {purpose}
+- {file 2} - {purpose}
+- {file 3} - {purpose}
+- {file 4} - {purpose}
+
+## Static Context Available
+- .opencode/context/core/standards/code.md (for code quality)
+- .opencode/context/core/standards/tests.md (for test requirements)
+- .opencode/context/core/{standards|workflows}/{other-relevant}.md
+
+## Constraints/Notes
+{Important context, preferences, compatibility}
+
+## Progress
+- [ ] {task 1}
+- [ ] {task 2}
+
+---
+**Instructions for Subagent:**
+{Specific instructions on what to do}
+```
+
+## Delegation Process
+
+**Step 1: Create temporary context**
+- Location: `.tmp/sessions/{timestamp}-{task-slug}/context.md`
+- Use template above
+
+**Step 2: Populate context file**
+- Fill in all sections with relevant details
+- Reference static context files (don't duplicate content)
+
+**Step 3: Delegate with context path**
+```
+Task: {brief description}
+Context: .tmp/sessions/{id}/context.md
+
+Read the context file for full details on requirements, decisions, and instructions.
+Reference static context files as needed (lazy load).
+```
+
+**Step 4: Cleanup after completion**
+- Ask user: "Task complete. Clean up session files at .tmp/sessions/{id}/?"
+- If approved: Delete session directory

.opencode/context/core/workflows/review.md

@@ -0,0 +1,134 @@
+# Code Review Guidelines
+
+## Quick Reference
+
+**Golden Rule**: Review code as you'd want yours reviewed - thoroughly but kindly
+
+**Checklist**: Functionality, Code Quality, Security, Testing, Performance, Maintainability
+
+**Report Format**: Summary, Assessment, Issues (🔴🟡🔵), Positive Observations, Recommendations
+
+**Principles**: Constructive, Thorough, Timely
+
+---
+
+## Principles
+
+**Constructive**: Focus on code not person, explain WHY, suggest improvements, acknowledge good practices
+**Thorough**: Check functionality not just style, consider edge cases, think maintainability, look for security
+**Timely**: Review promptly, don't block unnecessarily, prioritize critical issues
+
+## Review Checklist
+
+### Functionality
+- [ ] Does what it's supposed to do
+- [ ] Edge cases handled
+- [ ] Error cases handled
+- [ ] No obvious bugs
+
+### Code Quality
+- [ ] Clear, descriptive naming
+- [ ] Functions small and focused
+- [ ] No unnecessary complexity
+- [ ] Follows coding standards
+- [ ] DRY - no duplication
+
+### Security
+- [ ] Input validation present
+- [ ] No SQL injection vulnerabilities
+- [ ] No XSS vulnerabilities
+- [ ] No hardcoded secrets
+- [ ] Sensitive data handled properly
+- [ ] Auth/authorization appropriate
+
+### Testing
+- [ ] Tests present
+- [ ] Happy path covered
+- [ ] Edge cases covered
+- [ ] Error cases covered
+- [ ] All tests pass
+
+### Performance
+- [ ] No obvious performance issues
+- [ ] Efficient algorithms
+- [ ] No unnecessary operations
+- [ ] Resources properly managed
+
+### Maintainability
+- [ ] Easy to understand
+- [ ] Complex logic documented
+- [ ] Follows project conventions
+- [ ] Easy to modify/extend
+
+## Review Report Format
+
+```markdown
+## Code Review: {Feature/PR Name}
+
+**Summary:** {Brief overview}
+**Assessment:** Approve / Needs Work / Requires Changes
+
+---
+
+### Issues Found
+
+#### 🔴 Critical (Must Fix)
+- **File:** `src/auth.js:42`
+  **Issue:** Password stored in plain text
+  **Fix:** Hash password before storing
+
+#### 🟡 Warnings (Should Fix)
+- **File:** `src/user.js:15`
+  **Issue:** No input validation
+  **Fix:** Validate email format
+
+#### 🔵 Suggestions (Nice to Have)
+- **File:** `src/utils.js:28`
+  **Issue:** Could be more concise
+  **Fix:** Use array methods instead of loop
+
+---
+
+### Positive Observations
+- ✅ Good test coverage (95%)
+- ✅ Clear function names
+- ✅ Proper error handling
+
+---
+
+### Recommendations
+{Next steps, improvements, follow-up items}
+```
+
+## Common Issues
+
+### Security
+🔴 Hardcoded credentials
+🔴 SQL injection vulnerabilities
+🔴 Missing input validation
+🔴 Exposed sensitive data
+
+### Code Quality
+🟡 Large functions (>50 lines)
+🟡 Deep nesting (>3 levels)
+🟡 Code duplication
+🟡 Unclear naming
+
+### Testing
+🟡 Missing tests
+🟡 Low coverage (<80%)
+🟡 Flaky tests
+🟡 Tests testing implementation
+
+## Best Practices
+
+✅ Review within 24 hours
+✅ Provide specific, actionable feedback
+✅ Explain WHY, not just WHAT
+✅ Suggest alternatives
+✅ Acknowledge good work
+✅ Use severity levels (Critical/Warning/Suggestion)
+✅ Test the code if possible
+✅ Check for security issues first
+
+**Golden Rule**: Review code as you'd want yours reviewed - thoroughly but kindly.

.opencode/context/core/session-management.md

@@ -1,5 +1,17 @@
 # Session Management
 
+## Quick Reference
+
+**Key Principle**: Lazy initialization - only create when needed
+
+**Session ID**: `{timestamp}-{random-4-chars}` (e.g., `20250118-143022-a4f2`)
+
+**Cleanup**: Always ask user confirmation before deleting
+
+**Safety**: NEVER delete outside current session, ONLY delete tracked files, ALWAYS confirm
+
+---
+
 ## Lazy Initialization
 
 **Only create session when first context file needed**

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

@@ -0,0 +1,268 @@
+# Task Breakdown Guidelines
+
+## Quick Reference
+
+**When to Use**: 4+ files, >60 min effort, complex dependencies, multi-step coordination
+
+**Process**: Scope → Phases → Small Tasks (1-2h) → Dependencies → Estimates
+
+**Template Sections**: Overview, Prerequisites, Tasks (by Phase), Testing Strategy, Total Estimate, Notes
+
+**Best Practices**: Keep tasks small (1-2h), make dependencies clear, include verification, be realistic with estimates
+
+---
+
+## Purpose
+Framework for breaking down complex tasks into manageable, sequential subtasks.
+
+## When to Use
+Reference this when:
+- Task involves 4+ files
+- Estimated effort >60 minutes
+- Complex dependencies exist
+- Multi-step coordination needed
+- User requests task breakdown
+
+## Breakdown Process
+
+### 1. Understand the Full Scope
+- What's the complete requirement?
+- What are all the components needed?
+- What's the end goal?
+- What are the constraints?
+
+### 2. Identify Major Phases
+- What are the logical groupings?
+- What must happen first?
+- What can happen in parallel?
+- What depends on what?
+
+### 3. Break Into Small Tasks
+- Each task should be 1-2 hours max
+- Clear, actionable items
+- Independently completable
+- Easy to verify completion
+
+### 4. Define Dependencies
+- What must be done first?
+- What can be done in parallel?
+- What blocks what?
+- What's the critical path?
+
+### 5. Estimate Effort
+- Realistic time estimates
+- Include testing time
+- Account for unknowns
+- Add buffer for complexity
+
+## Breakdown Template
+
+```markdown
+# Task Breakdown: {Task Name}
+
+## Overview
+{1-2 sentence description of what we're building}
+
+## Prerequisites
+- [ ] {Prerequisite 1}
+- [ ] {Prerequisite 2}
+
+## Tasks
+
+### Phase 1: {Phase Name}
+**Goal:** {What this phase accomplishes}
+
+- [ ] **Task 1.1:** {Description}
+  - **Files:** {files to create/modify}
+  - **Estimate:** {time estimate}
+  - **Dependencies:** {none / task X}
+  - **Verification:** {how to verify it's done}
+
+- [ ] **Task 1.2:** {Description}
+  - **Files:** {files to create/modify}
+  - **Estimate:** {time estimate}
+  - **Dependencies:** {task 1.1}
+  - **Verification:** {how to verify it's done}
+
+### Phase 2: {Phase Name}
+**Goal:** {What this phase accomplishes}
+
+- [ ] **Task 2.1:** {Description}
+  - **Files:** {files to create/modify}
+  - **Estimate:** {time estimate}
+  - **Dependencies:** {phase 1 complete}
+  - **Verification:** {how to verify it's done}
+
+## Testing Strategy
+- [ ] Unit tests for {component}
+- [ ] Integration tests for {flow}
+- [ ] Manual testing: {scenarios}
+
+## Total Estimate
+**Time:** {X} hours
+**Complexity:** {Low / Medium / High}
+
+## Notes
+{Any important context, decisions, or considerations}
+```
+
+## Example Breakdown
+
+```markdown
+# Task Breakdown: User Authentication System
+
+## Overview
+Build authentication system with login, registration, and password reset.
+
+## Prerequisites
+- [ ] Database schema designed
+- [ ] Email service configured
+
+## Tasks
+
+### Phase 1: Core Authentication
+**Goal:** Basic login/logout functionality
+
+- [ ] **Task 1.1:** Create user model and database schema
+  - **Files:** `models/user.js`, `migrations/001_users.sql`
+  - **Estimate:** 1 hour
+  - **Dependencies:** none
+  - **Verification:** Can create user in database
+
+- [ ] **Task 1.2:** Implement password hashing
+  - **Files:** `utils/password.js`
+  - **Estimate:** 30 min
+  - **Dependencies:** Task 1.1
+  - **Verification:** Passwords are hashed, not plain text
+
+- [ ] **Task 1.3:** Create login endpoint
+  - **Files:** `routes/auth.js`, `controllers/auth.js`
+  - **Estimate:** 1.5 hours
+  - **Dependencies:** Task 1.1, 1.2
+  - **Verification:** Can login with valid credentials
+
+### Phase 2: Registration
+**Goal:** New user registration
+
+- [ ] **Task 2.1:** Create registration endpoint
+  - **Files:** `routes/auth.js`, `controllers/auth.js`
+  - **Estimate:** 1 hour
+  - **Dependencies:** Phase 1 complete
+  - **Verification:** Can create new user account
+
+- [ ] **Task 2.2:** Add email validation
+  - **Files:** `utils/validation.js`
+  - **Estimate:** 30 min
+  - **Dependencies:** Task 2.1
+  - **Verification:** Invalid emails rejected
+
+### Phase 3: Password Reset
+**Goal:** Users can reset forgotten passwords
+
+- [ ] **Task 3.1:** Generate reset tokens
+  - **Files:** `utils/tokens.js`
+  - **Estimate:** 1 hour
+  - **Dependencies:** Phase 1 complete
+  - **Verification:** Tokens generated and validated
+
+- [ ] **Task 3.2:** Create reset endpoints
+  - **Files:** `routes/auth.js`, `controllers/auth.js`
+  - **Estimate:** 1.5 hours
+  - **Dependencies:** Task 3.1
+  - **Verification:** Can request and complete password reset
+
+- [ ] **Task 3.3:** Send reset emails
+  - **Files:** `services/email.js`
+  - **Estimate:** 1 hour
+  - **Dependencies:** Task 3.2
+  - **Verification:** Reset emails sent successfully
+
+## Testing Strategy
+- [ ] Unit tests for password hashing
+- [ ] Unit tests for token generation
+- [ ] Integration tests for login flow
+- [ ] Integration tests for registration flow
+- [ ] Integration tests for password reset flow
+- [ ] Manual testing: Complete user journey
+
+## Total Estimate
+**Time:** 8.5 hours
+**Complexity:** Medium
+
+## Notes
+- Use bcrypt for password hashing (industry standard)
+- Reset tokens expire after 1 hour
+- Rate limit password reset requests
+- Email service must be configured before Phase 3
+```
+
+## Best Practices
+
+### Keep Tasks Small
+- 1-2 hours maximum per task
+- If larger, break it down further
+- Each task should be completable in one sitting
+
+### Make Dependencies Clear
+- Explicitly state what must be done first
+- Identify parallel work opportunities
+- Note blocking dependencies
+
+### Include Verification
+- How do you know the task is done?
+- What should work when complete?
+- How can it be tested?
+
+### Be Realistic with Estimates
+- Include time for testing
+- Account for unknowns
+- Add buffer for complexity
+- Better to overestimate than underestimate
+
+### Group Related Work
+- Organize by feature or component
+- Keep related tasks together
+- Make phases logical and cohesive
+
+## Common Patterns
+
+### Database-First Pattern
+1. Design schema
+2. Create migrations
+3. Build models
+4. Implement business logic
+5. Add API endpoints
+6. Write tests
+
+### Feature-First Pattern
+1. Define requirements
+2. Design interface
+3. Implement core logic
+4. Add error handling
+5. Write tests
+6. Document usage
+
+### Refactoring Pattern
+1. Add tests for existing behavior
+2. Refactor small section
+3. Verify tests still pass
+4. Repeat for next section
+5. Clean up and optimize
+6. Update documentation
+
+## Quick Reference
+
+**Good breakdown:**
+- Small, focused tasks (1-2 hours)
+- Clear dependencies
+- Realistic estimates
+- Verification criteria
+- Logical phases
+
+**Breakdown checklist:**
+- [ ] All requirements captured
+- [ ] Tasks are small and focused
+- [ ] Dependencies identified
+- [ ] Estimates are realistic
+- [ ] Testing included
+- [ ] Verification criteria clear

dev/ai-tools/opencode/how-context-works.md

@@ -59,6 +59,20 @@ your-repo/
 
 ## File References with `@` Symbol
 
+### Immediate vs. Lazy Loading
+
+**With `@` symbol** - **Immediate Loading**:
+- File is fetched and loaded right away
+- Content is immediately available to the agent
+- Use when context is always needed
+
+**Without `@` symbol** - **Lazy Loading**:
+- File is only fetched when the agent determines it's needed
+- Saves tokens if the agent can complete the task without it
+- Agent discovers and loads the file on-demand
+
+### Using the `@` Symbol
+
 **In commands and templates:**
 
 ```bash
@@ -82,6 +96,283 @@ your-repo/
 3. Otherwise → resolve relative to repo root (`Instance.worktree`)
 4. If not found → look for agent with that name
 
+### Best Practices for Lazy Loading (Without `@`)
+
+When referencing files without the `@` symbol, help the agent discover them by:
+
+**1. Provide clear file paths**
+```
+"Use the context from .opencode/command/commit.md if needed"
+```
+
+**2. Describe what's there** (so agent knows when to fetch)
+```
+"Check the commit command guidelines in .opencode/command/commit.md 
+when you need to understand our commit message format"
+```
+
+**3. Mention directory conventions**
+```
+"Command templates are in .opencode/command/ - reference them as needed"
+```
+
+**4. Reference by purpose, not just path**
+```
+"Follow our commit guidelines (available in the command directory) 
+when making commits"
+```
+
+### Example: Lazy Loading in Practice
+
+**Without `@` symbol (lazy loading):**
+```
+"Create a git commit. Our commit guidelines are in .opencode/command/commit.md - 
+check them if you need to understand our prefix conventions and message format."
+```
+
+This approach:
+- ✅ Agent knows the file exists and where it is
+- ✅ Agent knows WHEN it would be useful (for commit conventions)
+- ✅ Agent only reads it IF it needs that information
+- ✅ Saves tokens if the agent can complete the task without it
+
+**With `@` symbol (immediate loading):**
+```
+"Create a git commit following these guidelines: @.opencode/command/commit.md"
+```
+
+This approach:
+- ✅ File content is immediately available
+- ✅ Guaranteed the agent has the context
+- ⚠️ Uses tokens even if agent doesn't need it
+
+### When to Use Each Approach
+
+| Use `@` (Immediate) | Omit `@` (Lazy) |
+|---------------------|-----------------|
+| Context always required | Context might be needed |
+| Short, critical files | Large reference files |
+| Agent must follow exact format | Agent can infer or discover |
+| Templates and schemas | Documentation and guides |
+
+**Pro tip:** Modern agents are good at discovering needed files through `codebase_search` or exploring directories, but being explicit about important files helps ensure consistency.
+
+---
+
+## Research-Backed Context Architecture
+
+### Three-Layer Progressive Architecture
+
+Based on validated research from Stanford, Anthropic (2025), and recent AI agent engineering studies, effective context loading follows a three-layer progressive architecture:
+
+#### Layer 1: Static Base Context (First 15% of Prompt)
+
+This is your foundational layer, grounded in Stanford's position sensitivity research. **Critical instructions positioned early dramatically improve adherence.**
+
+**What goes here:**
+- Role definition (5-10%)
+- Critical rules (defined once, early positioning)
+- Task definition (clear objective)
+- Constraint summary (high-level "must/must-not")
+
+**Example:**
+```xml
+<role>Expert Prompt Architect</role>
+<critical_rules priority="absolute" enforcement="strict">
+  <rule id="position_sensitivity">Critical rules MUST be in first 15%</rule>
+  <rule id="nesting_limit">Max nesting: 4 levels</rule>
+</critical_rules>
+<execution_priority>
+  <tier level="1">Research patterns (non-negotiable)</tier>
+</execution_priority>
+```
+
+**Why this matters:** Research shows position sensitivity improves adherence across model sizes. Critical rules at the start are more reliably followed than rules buried later in the prompt.
+
+#### Layer 2: Lazy-Loaded Context (Just-in-Time Retrieval)
+
+This layer uses the "just-in-time" approach validated by Anthropic's 2025 research on effective context engineering for AI agents.
+
+> Rather than pre-processing all relevant data up front, agents built with the "just-in-time" approach maintain lightweight identifiers (file paths, stored queries, web links, etc.) and use these references to dynamically load data into context at runtime using tools.
+
+**Implementation:**
+```xml
+<context_sources>
+  <!-- Agent fetches these as needed, not embedded upfront -->
+  <standards>.opencode/context/core/standards/code.md</standards>
+  <practices>.opencode/context/core/practices/review.md</practices>
+  <workflows>.opencode/context/core/workflows/delegation.md</workflows>
+</context_sources>
+```
+
+**Key insight:** This enables **progressive disclosure**. Agents incrementally discover context through exploration:
+- File naming hints at purpose (`.../standards/code.md` vs `.../practices/review.md`)
+- File size signals complexity
+- Timestamps indicate recency
+- Folder structure provides hierarchical context
+
+**Token efficiency gain:**
+- Pre-loading all context: **2,000-5,000+ tokens**
+- Just-in-time loading: **300-1,000 tokens per file** (agents typically need 2-3 files, not 10)
+- **Net savings: 60-80% reduction in token usage**
+
+#### Layer 3: Dynamic Runtime Context (Execution-Time Loading)
+
+This layer handles long-horizon tasks and evolving context through compaction and memory strategies.
+
+**Implementation:**
+```xml
+<session_memory>
+  <!-- Agents write notes persisted outside context window -->
+  <!-- Read back in at later times for coherence -->
+  .opencode/sessions/[task-id].md
+</session_memory>
+
+<dynamic_context>
+  <!-- RAG retrieval results filtered for relevance -->
+  <!-- Tool execution outputs -->
+  <!-- Delegation context from prior agents -->
+</dynamic_context>
+```
+
+**Research backing:** For tasks spanning multiple turns:
+- **Compaction**: Summarize context nearing window limit, reinitiate with summary + critical details
+- **Structured note-taking**: Agent maintains notes in persistent memory (like session files), pulled back in later
+- **Progressive context assembly**: Each interaction yields context informing the next decision
+
+### Progressive Disclosure by Design
+
+Structure your context hierarchy so agents discover relevance layer-by-layer:
+
+```
+.opencode/context/core/
+├── standards/              ← Broad guidelines (agent starts here)
+│   ├── code.md            ← File naming hints: "code" standards
+│   ├── tests.md           ← "tests" = test-specific rules
+│   └── patterns.md        ← "patterns" = architectural patterns
+├── practices/              ← Execution-level practices
+│   ├── analysis.md        ← "analysis" = how to analyze
+│   └── review.md          ← "review" = code review criteria
+├── workflows/              ← Process templates
+│   ├── delegation.md      ← Delegation patterns
+│   ├── task-breakdown.md  ← Task analysis workflows
+│   └── sessions.md        ← Session management
+└── system/
+    └── context-guide.md   ← System internals
+```
+
+Each folder name signals purpose. Each file name within folders signals specific application. This is **progressive disclosure by design** - agents can navigate the hierarchy based on their current needs.
+
+### Long-Horizon Task Strategies
+
+For multi-hour tasks spanning context resets:
+
+**Compaction Strategy:**
+```xml
+<memory_strategy>
+  <!-- Before context reset: Agent summarizes work -->
+  <compaction>
+    Preserve: Architectural decisions, unresolved bugs, key insights
+    Discard: Redundant tool outputs, repeated attempts
+  </compaction>
+  
+  <!-- After reset: Agent reads notes and continues -->
+  <structured_notes path=".opencode/sessions/[id].md">
+    • Decisions made
+    • Current phase
+    • Next steps
+    • Unresolved issues
+  </structured_notes>
+</memory_strategy>
+```
+
+**Example:** Anthropic's Claude Code maintains precise tallies across thousands of steps using persistent notes - the same pattern your session files implement.
+
+### Anti-Patterns to Avoid
+
+Research identifies these common mistakes that reduce effectiveness:
+
+#### ❌ Anti-Pattern 1: Overload Static Context
+
+```xml
+<!-- DON'T DO THIS -->
+<prompt>
+  <all_standards><!-- 5000+ tokens of standards upfront --></all_standards>
+  <task>Fix typo in button</task>
+</prompt>
+```
+
+**Problems:**
+- Attention budget exhaustion (n² transformer relationships)
+- Reduced position sensitivity effectiveness (critical rules get buried)
+- Worse adherence to specific instructions
+
+**Solution:** Use lazy loading for large reference materials.
+
+#### ❌ Anti-Pattern 2: Deep Nesting
+
+```xml
+<!-- DON'T DO THIS -->
+<instructions>
+  <workflow>
+    <delegation>
+      <criteria>
+        <when>
+          <condition>
+            <!-- 6+ levels: breaks clarity -->
+```
+
+**Problem:** Nesting depth >4 levels reduces clarity significantly.
+
+**Solution:** Use attributes and flatter structures with max 4 levels.
+
+#### ❌ Anti-Pattern 3: Repeating Critical Rules
+
+```xml
+<!-- DON'T DO THIS -->
+<rule_1>Always request approval</rule_1>
+... 2000 tokens later ...
+<rule_2>Always get approval before execution</rule_2>
+... 3000 tokens later ...
+<rule_3>Approval must be obtained</rule_3>
+```
+
+**Problem:** Repetition causes ambiguity and wastes tokens.
+
+**Solution:** Define rules once in the first 15%, reference them with `@rule_id` elsewhere.
+
+### Token Efficiency Metrics
+
+Real-world measurements from production agent systems:
+
+| Approach | Token Cost | Files Loaded | Efficiency |
+|----------|-----------|--------------|------------|
+| Pre-load all context | 2,000-5,000+ | 10-15 files | Baseline |
+| Just-in-time loading | 300-1,000 | 2-3 files | **60-80% savings** |
+| With compaction | 500-1,500 | 3-5 files | **50-70% savings** |
+
+**Key insight:** Agents typically need only 2-3 context files per task, not the entire knowledge base.
+
+### Research Validation Summary
+
+| Pattern | Research Basis | Effect |
+|---------|----------------|--------|
+| **Position Sensitivity** | Stanford multi-instruction study | Improves adherence (varies by task/model) |
+| **Just-in-Time Loading** | Anthropic context engineering (2025) | 60-80% token reduction |
+| **Progressive Disclosure** | Anthropic agent research | Agents discover context incrementally |
+| **Nesting Depth ≤4** | Anthropic XML research | Reduces complexity, improves clarity |
+| **Compaction + Memory** | Anthropic long-horizon tasks | Maintains coherence across resets |
+
+### Research Sources
+
+- **Anthropic (2025)**: "Effective Context Engineering for AI Agents"
+- **Stanford**: Multi-instruction position sensitivity study
+- **Anthropic**: "XML Prompting as Grammar-Constrained Interaction" (ArXiv 2509.08182)
+- **ODSC (2025)**: "Building Dynamic In-Context Learning for Self-Optimizing Agents"
+- **ArXiv**: "Optimization of Retrieval-Augmented Generation Context with Outlier Detection" (2407.01403)
+
+---
+
 ## Custom Instruction Files
 
 **For arbitrary paths, use `instructions` field:**

dev/ai-tools/opencode/slash-commands-and-subagents.md

@@ -371,3 +371,168 @@ Task(
 - ✅ Test with: "Can you [task description]"
 
 That's it! Main agent reads AGENTS.md, sees the patterns, and knows how to invoke slash commands through subagents.
+
+---
+
+## Appendix: Path Resolution Test Findings
+
+**Date:** November 19, 2025  
+**Test Objective:** Verify path resolution behavior for portable agent installation strategy
+
+### 🔍 Discovery Phase Results
+
+#### OpenCode Directory Structure
+
+**Global Configuration:**
+- **Location:** `~/.config/opencode/`
+- **Contents:** `opencode.json`, `config.json`, plugins, providers
+- **Note:** No `agent/`, `command/`, or `context/` folders found in default installation
+
+**Authentication & Data:**
+- **Location:** `~/.local/share/opencode/`
+- **Contents:** `auth.json`, bin, log, project, snapshot, storage
+
+**Local Repository:**
+- **Location:** `.opencode/` (in git repository root)
+- **Structure:** `agent/`, `command/`, `context/`, `plugin/`, `tool/`
+
+#### Key Findings
+
+1. ✅ **Global config path confirmed:** `~/.config/opencode/`
+2. ✅ **Local structure confirmed:** `.opencode/` in repo root
+3. ⚠️ **Current agents don't use `@` references** - Context loaded via different mechanism
+4. ✅ **Context files exist** in `.opencode/context/` with subdirectories
+
+### 📊 Path Resolution Analysis
+
+#### From OpenCode Documentation
+
+**`@` Symbol Resolution Order:**
+1. Check if starts with `~/` → resolve to home directory
+2. Check if absolute path → use as-is
+3. Otherwise → resolve relative to repo root (`Instance.worktree`)
+4. If not found → look for agent with that name
+
+#### Implications for Installation
+
+**Local Installation (in repo):**
+```
+Repo structure:
+  .opencode/
+  ├── agent/security/scanner.md
+  └── context/security/patterns.md
+
+Reference: @.opencode/context/security/patterns.md
+Resolution: {repo-root}/.opencode/context/security/patterns.md ✅
+```
+
+**Global Installation:**
+```
+Global structure:
+  ~/.config/opencode/
+  ├── agent/security/scanner.md
+  └── context/security/patterns.md
+
+Reference: @.opencode/context/security/patterns.md
+Resolution: Tries to find .opencode/ relative to... what? ❌
+Problem: No "repo root" for global agents!
+```
+
+### 🎯 Path Pattern Testing
+
+#### Test Setup
+
+Created global test agent with three path patterns:
+
+```markdown
+# Pattern 1: With .opencode prefix
+@.opencode/context/test/global-test-data.md
+
+# Pattern 2: Without .opencode prefix  
+@context/test/global-test-data.md
+
+# Pattern 3: Explicit home path
+@~/.config/opencode/context/test/global-test-data.md
+```
+
+#### Expected Results (Based on Documentation)
+
+| Pattern | Local Install | Global Install | Notes |
+|---------|--------------|----------------|-------|
+| `@.opencode/context/file.md` | ✅ Works | ❌ Fails | No .opencode in global path |
+| `@context/file.md` | ❌ Fails | ❓ Unknown | Might resolve to ~/.config/opencode/context/ |
+| `@~/.config/opencode/context/file.md` | ❌ Fails | ✅ Works | Explicit path, but breaks local |
+
+#### Critical Issue
+
+**No single path pattern works for both local AND global installations!**
+
+This confirms our installation script approach is necessary.
+
+### ✅ Validated Assumptions
+
+1. ✅ **Global path is `~/.config/opencode/`** - Confirmed
+2. ✅ **Local path is `.opencode/`** - Confirmed  
+3. ✅ **Path transformation is required** - Confirmed (no universal pattern)
+4. ✅ **Context folder structure works** - Confirmed (exists in current repo)
+
+### ❌ Invalidated Assumptions
+
+1. ❌ **`@context/file.md` might work universally** - Unconfirmed, likely fails locally
+2. ❌ **Current agents use `@` references** - They don't (different loading mechanism)
+
+### 🔧 Installation Strategy Confirmation
+
+#### Source Code Convention
+
+**All context references MUST use:**
+```markdown
+@.opencode/context/{category}/{file}.md
+```
+
+#### Installation Script Transformation
+
+**Local Installation:**
+- Keep references as-is: `@.opencode/context/...`
+- Copy to: `{repo}/.opencode/`
+
+**Global Installation:**  
+- Transform: `@.opencode/context/` → `@~/.config/opencode/context/`
+- Copy to: `~/.config/opencode/`
+
+#### Transformation Rules
+
+```bash
+# For global installation
+sed 's|@\.opencode/context/|@~/.config/opencode/context/|g'
+
+# Also transform shell commands
+sed 's|\.opencode/context/|~/.config/opencode/context/|g'
+```
+
+### 🚨 Additional Considerations
+
+#### Shell Commands in Templates
+
+**Problem:** Commands like `!`ls .opencode/context/`` also need transformation
+
+**Solution:** Transform both `@` references AND bare paths in shell commands
+
+#### Context Cross-References
+
+**Problem:** Context files may reference other context files
+
+**Solution:** Transform context files too, not just agents/commands
+
+#### Platform Compatibility
+
+**macOS/Linux:** `~/.config/opencode/` ✅  
+**Windows:** Need to verify (likely `%APPDATA%\opencode` or similar)
+
+### 📝 Recommendations
+
+1. **Proceed with Installation Script Approach** - The two-tier distribution with path transformation is necessary and correct
+2. **Strict Convention Enforcement** - Create validation script to ensure all references follow `@.opencode/context/` pattern
+3. **Transform All File Types** - Agent files, command files, AND context files
+4. **Test on Actual OpenCode Installation** - Runtime testing would confirm edge cases
+5. **Platform-Specific Paths** - Verify global paths on Windows before production release