old4ever/local-cal
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: install openagent opencode

Browse Source 
Signed-off-by: Dmytro Stanchiev <git@dmytros.dev>
This commit is contained in:
Dmytro Stanchiev
2026-04-07 11:31:26 -04:00
parent b4c03ff25e
commit c2263602c4
204 changed files with 38010 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

39
.opencode/context/core/config/navigation.md Normal file
View File

@@ -0,0 +1,39 @@
<!-- Context: core/navigation | Priority: critical | Version: 1.0 | Updated: 2026-02-15 -->
# Core Configuration
**Purpose**: Configuration standards and patterns for the context system
---
## Structure
```
core/config/
├── navigation.md (this file)
└── [configuration files]
```
---
## Quick Routes
| Task | Path |
|------|------|
| **View configuration** | `../config/` |
| **Core standards** | `../standards/navigation.md` |
| **System guides** | `../system/navigation.md` |
---
## By Type
**Configuration Files** → Settings and configuration patterns for the context system
---
## Related Context
- **Core Standards** → `../standards/navigation.md`
- **Core System** → `../system/navigation.md`
- **Core Navigation** → `../navigation.md`

7
.opencode/context/core/config/paths.json Normal file
View File

@@ -0,0 +1,7 @@
{
"description": "Additional context file paths - agents load this via @ reference for dynamic pathing",
"paths": {
"local": ".opencode/context",
"global": "~/.config/opencode/context"
}
}

450
.opencode/context/core/context-system.md Normal file
View File

@@ -0,0 +1,450 @@
<!-- Context: core/context-system | Priority: critical | Version: 1.0 | Updated: 2026-02-15 -->
# Context System
**Purpose**: Minimal, concern-based knowledge organization for AI agents
**Last Updated**: 2026-01-08
---
## Core Principles
### 1. Minimal Viable Information (MVI)
Extract only core concepts (1-3 sentences), key points (3-5 bullets), minimal example, and reference link.
**Goal**: Scannable in <30 seconds. Reference full docs, don't duplicate them.
### 2. Concern-Based Structure
Organize by **what you're doing** (concern), then by **how you're doing it** (approach/tech):
**Two organizational patterns**:
#### Pattern A: Function-Based (for repository-specific context)
```
category/
├── navigation.md
├── concepts/ # What it is
├── examples/ # Working code
├── guides/ # How to do it
├── lookup/ # Quick reference
└── errors/ # Common issues
```
**Use when**: Content is repository-specific (e.g., `openagents-repo/`)
#### Pattern B: Concern-Based (for development context)
```
category/
├── navigation.md
├── {concern}/ # Organize by what you're doing
│ ├── navigation.md
│ ├── {approach}/ # Then by approach/tech
│ │ ├── navigation.md
│ │ └── {files}.md
```
**Use when**: Content spans multiple technologies (e.g., `development/`)
**Examples**:
- `development/backend/api-patterns/` - Concern: backend, Approach: API patterns
- `development/backend/nodejs/` - Concern: backend, Tech: Node.js
- `development/frontend/react/` - Concern: frontend, Tech: React
### 3. Token-Efficient Navigation
Every category/subcategory has `navigation.md` with:
- **ASCII tree** for quick structure scan (~50 tokens)
- **Quick routes table** for common tasks (~100 tokens)
- **By concern/type** sections (~50 tokens)
- **Total**: ~200-300 tokens per navigation file
**Why**: Faster loading, less cost, quicker AI decisions
### 4. Specialized Navigation Files
For cross-cutting concerns, create specialized navigation:
- `development/ui-navigation.md` - Spans frontend/ + ui/
- `development/backend-navigation.md` - Covers APIs, auth, middleware
- `development/fullstack-navigation.md` - Common tech stacks
**Why**: Real workflows don't fit neat categories
### 5. Self-Describing Filenames
Filenames should tell you what's inside:
- ❌ `code.md` → ✅ `code-quality.md`
- ❌ `tests.md` → ✅ `test-coverage.md`
- ❌ `review.md` → ✅ `code-review.md`
**Why**: No need to open files to understand content
### 6. Knowledge Harvesting
Extract valuable context from AI summaries/overviews, then delete them. Workspace stays clean, knowledge persists.
### 5. Technology Context Organization
**Purpose**: Ensure consistent placement of new technologies (frameworks, libraries, tools) to maintain discoverability.
**Frameworks vs Architectural Layers**:
- **Full-Stack Frameworks** (e.g., Tanstack Start, Next.js): Add under `development/frameworks/{tech}/`. These are "meta-frameworks" that span multiple layers.
- **Specialized Concerns** (e.g., AI, Data): Add under `development/{concern}/{tech}/`.
- **Layer-Specific Tech** (e.g., React, Node.js): Add under `development/{frontend|backend}/{tech}/`.
**Decision Process**:
1. Is it a full-stack framework? → `development/frameworks/`
2. Is it a specialized domain (AI, Data)? → `development/{domain}/`
3. Is it layer-specific? → `development/{frontend|backend}/`
---
## Directory Patterns
### Pattern A: Function-Based (Repository-Specific)
**Use for**: Repository-specific context (e.g., `openagents-repo/`)
```
.opencode/context/{category}/
├── navigation.md # Fast, token-efficient navigation
├── quick-start.md # Optional: 2-minute orientation
│
├── core-concepts/ # Foundational concepts (optional)
│ ├── navigation.md
│ └── {concept}.md
│
├── concepts/ # What it is
│ ├── navigation.md
│ └── {concept}.md
│
├── examples/ # Working code
│ ├── navigation.md
│ └── {example}.md
│
├── guides/ # How to do it
│ ├── navigation.md
│ └── {guide}.md
│
├── lookup/ # Quick reference
│ ├── navigation.md
│ └── {lookup}.md
│
└── errors/ # Common issues
├── navigation.md
└── {error}.md
```
---
### Pattern B: Concern-Based (Development Context)
**Use for**: Multi-technology development context (e.g., `development/`)
```
.opencode/context/{category}/
├── navigation.md # Main navigation
├── {concern}-navigation.md # Specialized navigation (optional)
│
├── principles/ # Universal principles (optional)
│ ├── navigation.md
│ └── {principle}.md
│
├── {concern}/ # Organize by concern
│ ├── navigation.md
│ │
│ ├── {approach}/ # Then by approach
│ │ ├── navigation.md
│ │ └── {pattern}.md
│ │
│ └── {tech}/ # Or by tech
│ ├── navigation.md
│ └── {pattern}.md
```
**Example**:
```
development/
├── navigation.md
├── ui-navigation.md # Specialized
├── backend-navigation.md # Specialized
├── fullstack-navigation.md # Specialized
│
├── principles/ # Universal
│ ├── clean-code.md
│ └── api-design.md
│
├── frontend/ # Concern
│ ├── react/ # Tech
│ │ ├── hooks-patterns.md
│ │ └── tanstack/ # Sub-tech
│ │ ├── query-patterns.md
│ │ └── router-patterns.md
│ └── vue/ # Tech
│
├── backend/ # Concern
│ ├── api-patterns/ # Approach
│ │ ├── rest-design.md
│ │ └── graphql-design.md
│ ├── nodejs/ # Tech
│ └── authentication/ # Functional concern
│
└── data/ # Concern
├── sql-patterns/ # Approach
└── orm-patterns/ # Approach
```
---
## Navigation File Format
### Token-Efficient Template
```markdown
# {Category} Navigation
**Purpose**: [1 sentence]
---
## Structure
```
{category}/
├── navigation.md
├── {subcategory}/
│ ├── navigation.md
│ └── {files}.md
```
---
## Quick Routes
| Task | Path |
|------|------|
| **{Task 1}** | `{path}` |
| **{Task 2}** | `{path}` |
---
## By {Concern/Type}
**{Section 1}** → {description}
**{Section 2}** → {description}
```
**Target**: 200-300 tokens
---
## Organizing Principles
### 1. Core Standards (Universal)
Location: `.opencode/context/core/standards/`
**Purpose**: Universal standards that apply to ALL development
**Content**:
- Code quality principles (all languages)
- Test coverage standards
- Documentation standards
- Security patterns
- Code analysis approaches
**Used by**: All agents, all projects
**Effect on other categories**:
- Other categories can reference these standards
- Users can edit core standards to affect context flow globally
- Development-specific standards go in `development/principles/`
---
### 2. Development Principles vs Core Standards
| Location | Scope | Examples |
|----------|-------|----------|
| `core/standards/` | **Universal** (all projects, all languages) | Code quality, testing, docs, security |
| `development/principles/` | **Development-specific** (software engineering) | Clean code, API design, error handling |
**Both exist**: Core standards are universal, development principles are domain-specific
---
### 3. Data Context Location
**Decision**: Data patterns live in `development/data/` (not top-level)
**Rationale**: Data layer is part of development workflow
**Structure**:
```
development/data/
├── navigation.md
├── sql-patterns/
├── nosql-patterns/
└── orm-patterns/
```
**Top-level `data/` category**: Reserved for data engineering/analytics (different concern)
---
### 4. Specialized Navigation Strategy
**Full-stack navigation includes**:
- Quick routes (table format)
- Common stack patterns (MERN, T3, etc.)
**Example**:
```markdown
## Quick Routes
| Task | Path |
|------|------|
| **Frontend** | `ui-navigation.md` |
## Common Stacks
### MERN Stack
Frontend: development/frontend/react/
Backend: development/backend/nodejs/
Data: development/data/nosql-patterns/mongodb.md
```
---
## Operations
### Harvest (`/context harvest`)
**Purpose**: Extract knowledge from summary files → permanent context, then clean up.
**Process**:
1. Scan for patterns: `*OVERVIEW.md`, `*SUMMARY.md`, `SESSION-*.md`, `CONTEXT-*.md`
2. Analyze content:
- Design decisions → `concepts/`
- Solutions/patterns → `examples/`
- Workflows → `guides/`
- Errors encountered → `errors/`
- Reference data → `lookup/`
3. Present approval UI (letter-based: `A B C` or `all`)
4. Extract + minimize (apply MVI)
5. Archive/delete summaries
6. Report results
---
### Extract (`/context extract`)
**Purpose**: Extract context from docs/code/URLs.
**Process**:
1. Read source
2. Extract core concepts (1-3 sentences each)
3. Find minimal examples
4. Identify workflows (numbered steps)
5. Build lookup tables
6. Capture errors/gotchas
7. Create references
**Output**: Follow MVI template
---
### Organize (`/context organize`)
**Purpose**: Restructure existing files into appropriate pattern.
**Process**:
1. Scan category
2. Determine pattern (function-based or concern-based)
3. Create missing directories
4. Move/refactor files
5. Update navigation.md
6. Fix references
---
### Update (`/context update`)
**Purpose**: Update context when APIs/frameworks change.
**Process**:
1. Identify what changed
2. Find affected files
3. Update concepts, examples, guides, lookups
4. Add migration notes to errors/
5. Validate references
---
## File Naming Conventions
### Navigation Files
- `navigation.md` - Main navigation for category/subcategory
- `{domain}-navigation.md` - Specialized cross-cutting navigation
### Content Files
- Use descriptive names: `code-quality.md` not `code.md`
- Include type when helpful: `rest-design.md`, `jwt-patterns.md`
- Use kebab-case: `scroll-linked-animations.md`
---
## Extraction Rules
### ✅ Extract:
- Core concepts (minimal)
- Essential patterns
- Step-by-step workflows
- Critical errors
- Quick reference data
- Links to detailed docs
### ❌ Don't Extract:
- Verbose explanations
- Complete API docs
- Implementation details
- Historical context
- Marketing content
- Duplicate info
---
## Success Criteria
✅ **Minimal** - Core info only, <200 lines per file
✅ **Navigable** - navigation.md at every level
✅ **Organized** - Appropriate pattern (function-based or concern-based)
✅ **Token-efficient** - Navigation files ~200-300 tokens
✅ **Self-describing** - Filenames tell you what's inside
✅ **Referenceable** - Links to full docs
✅ **Searchable** - Easy to find via navigation
✅ **Maintainable** - Easy to update
---
## Related Documentation
- `context-system/guides/navigation-design.md` - How to create navigation files
- `context-system/guides/organizing-context.md` - How to choose organizational pattern
- `context-system/examples/navigation-examples.md` - Good navigation examples
- `context-system/standards/templates.md` - File templates
---
## Quick Commands
```bash
/context # Quick scan, suggest actions
/context harvest # Clean up summaries → permanent context
/context extract {source} # From docs/code/URLs
/context organize {category} # Restructure flat files → function folders
/context update {what} # When APIs/frameworks change
/context migrate # Move global project-intelligence → local project
/context create {category} # Create new context category
/context error {error} # Add recurring error to knowledge base
/context compact {file} # Minimize verbose file to MVI format
/context map [category] # View context structure
/context validate # Check integrity, references, sizes
```
**All operations show a preview of what will be created/moved/deleted before asking for approval.**

87
.opencode/context/core/context-system/CHANGELOG.md Normal file
View File

@@ -0,0 +1,87 @@
<!-- Context: core/CHANGELOG | Priority: low | Version: 1.0 | Updated: 2026-02-15 -->
# Context System Changelog
**Purpose**: Track major changes to the context system
---
## 2026-01-08: Navigation System Redesign
### Major Changes
1. **Renamed README.md → navigation.md**
- More descriptive filename
- Better discoverability
- Self-describing purpose
2. **Added Concern-Based Organization Pattern**
- Pattern A: Function-Based (repository-specific)
- Pattern B: Concern-Based (multi-technology)
- Hybrid approach supported
3. **Token-Efficient Navigation**
- Target: 200-300 tokens per navigation file
- ASCII trees for structure
- Tables for quick routes
- Concise descriptions (3-5 words)
4. **Specialized Navigation Files**
- Cross-cutting concerns (e.g., `ui-navigation.md`)
- Task-focused routes
- Workflow-oriented
5. **Self-Describing Filenames**
- `code.md` → `code-quality.md`
- `tests.md` → `test-coverage.md`
- `review.md` → `code-review.md`
### New Documentation
**Created**:
- `guides/navigation-design.md` - How to create navigation files
- `guides/organizing-context.md` - How to choose organizational pattern
- `examples/navigation-examples.md` - Real-world examples
**Updated**:
- `context-system.md` - Added concern-based pattern, navigation principles
- `standards/templates.md` - Added navigation templates
### Organizational Decisions
1. **Core Standards (Universal)**
- Location: `core/standards/`
- Scope: All projects, all languages
- Users can edit to affect global context flow
2. **Development Principles (Domain-Specific)**
- Location: `development/principles/`
- Scope: Software engineering
- Both core standards and dev principles exist
3. **Data Context**
- Location: `development/data/` (not top-level)
- Rationale: Data layer is part of development workflow
4. **Specialized Navigation**
- Includes quick routes + common patterns
- Example: `fullstack-navigation.md` shows MERN, T3 stacks
### Migration Path
**Phase 0**: ✅ Update context system documentation (DONE)
**Phase 1**: Rename navigation files, update core/
**Phase 2**: Restructure development/ category
**Phase 3**: Organize New-context-to-sort/
**Phase 4**: Update all references
---
## Previous Changes
### 2026-01-06: Initial Context System
- Established MVI principle
- Created function-based structure
- Added file templates
- Defined operations (harvest, extract, organize, update)

493
.opencode/context/core/context-system/examples/navigation-examples.md Normal file
View File

@@ -0,0 +1,493 @@
<!-- Context: core/navigation-examples | Priority: high | Version: 1.0 | Updated: 2026-02-15 -->
# Examples: Navigation Files
**Purpose**: Real-world examples of good navigation files
**Last Updated**: 2026-01-08
---
## Example 1: Category Navigation (Function-Based)
**File**: `openagents-repo/navigation.md`
**Pattern**: Function-Based (repository-specific)
**Token count**: ~250 tokens
```markdown
# OpenAgents Control Repository Navigation
**Purpose**: Navigate OpenAgents Control repository context
---
## Structure
```
openagents-repo/
├── navigation.md
├── quick-start.md
│
├── core-concepts/
│ ├── agent-architecture.md
│ ├── eval-framework.md
│ └── registry-system.md
│
├── guides/
│ ├── adding-agent.md
│ ├── testing-agent.md
│ └── debugging-issues.md
│
├── lookup/
│ ├── commands.md
│ └── file-locations.md
│
└── errors/
└── tool-permission-errors.md
```
---
## Quick Routes
| Task | Path |
|------|------|
| **New here** | `quick-start.md` |
| **Add agent** | `guides/adding-agent.md` |
| **Test agent** | `guides/testing-agent.md` |
| **Debug issue** | `guides/debugging-issues.md` |
| **Find files** | `lookup/file-locations.md` |
| **Fix error** | `errors/tool-permission-errors.md` |
---
## By Type
**Core Concepts** → Foundational understanding (agents, evals, registry)
**Guides** → Step-by-step workflows
**Lookup** → Quick reference tables
**Errors** → Troubleshooting
```
**Why this works**:
- ✅ Token-efficient (~250 tokens)
- ✅ ASCII tree shows structure
- ✅ Quick routes for common tasks
- ✅ Organized by information type
---
## Example 2: Category Navigation (Concern-Based)
**File**: `development/navigation.md`
**Pattern**: Concern-Based (multi-technology)
**Token count**: ~280 tokens
```markdown
# Development Navigation
**Purpose**: Software development across all stacks
---
## Structure
```
development/
├── navigation.md
├── ui-navigation.md # Specialized
├── backend-navigation.md # Specialized
│
├── principles/
│ ├── clean-code.md
│ └── api-design.md
│
├── frontend/
│ ├── react/
│ └── vue/
│
├── backend/
│ ├── api-patterns/
│ ├── nodejs/
│ └── authentication/
│
└── data/
├── sql-patterns/
└── orm-patterns/
```
---
## Quick Routes
| Task | Path |
|------|------|
| **UI/Frontend** | `ui-navigation.md` |
| **Backend/API** | `backend-navigation.md` |
| **Clean code** | `principles/clean-code.md` |
| **API design** | `principles/api-design.md` |
---
## By Concern
**Principles** → Universal development practices
**Frontend** → React, Vue, state management
**Backend** → APIs, Node.js, Python, auth
**Data** → SQL, NoSQL, ORMs
```
**Why this works**:
- ✅ Token-efficient (~280 tokens)
- ✅ Shows specialized navigation files
- ✅ Organized by concern (frontend, backend, data)
- ✅ Points to specialized navigation for complex workflows
---
## Example 3: Specialized Navigation
**File**: `development/ui-navigation.md`
**Pattern**: Cross-cutting (spans multiple categories)
**Token count**: ~270 tokens
```markdown
# UI Development Navigation
**Scope**: Frontend code + visual design
---
## Structure
```
Frontend Code (development/frontend/):
├── react/
│ ├── hooks-patterns.md
│ ├── component-architecture.md
│ └── tanstack/
│ ├── query-patterns.md
│ └── router-patterns.md
└── vue/
Visual Design (ui/web/):
├── animation-patterns.md
├── ui-styling-standards.md
└── design-systems.md
```
---
## Quick Routes
| Task | Path |
|------|------|
| **React patterns** | `frontend/react/hooks-patterns.md` |
| **TanStack Query** | `frontend/react/tanstack/query-patterns.md` |
| **Animations** | `../../ui/web/animation-patterns.md` |
| **Styling** | `../../ui/web/ui-styling-standards.md` |
---
## By Framework
**React** → `frontend/react/`
**Vue** → `frontend/vue/`
**TanStack** → `frontend/react/tanstack/`
## By Concern
**Code patterns** → `development/frontend/`
**Visual design** → `ui/web/`
```
**Why this works**:
- ✅ Token-efficient (~270 tokens)
- ✅ Spans multiple categories (development/ + ui/)
- ✅ Task-focused (UI development)
- ✅ Shows both code and design paths
---
## Example 4: Subcategory Navigation
**File**: `development/backend/navigation.md`
**Pattern**: Concern-based subcategory
**Token count**: ~240 tokens
```markdown
# Backend Development Navigation
**Scope**: Server-side, APIs, databases, auth
---
## Structure
```
backend/
├── navigation.md
│
├── api-patterns/
│ ├── rest-design.md
│ ├── graphql-design.md
│ └── grpc-patterns.md
│
├── nodejs/
│ ├── express-patterns.md
│ └── fastify-patterns.md
│
├── python/
│ └── fastapi-patterns.md
│
└── authentication/
├── jwt-patterns.md
└── oauth-patterns.md
```
---
## Quick Routes
| Task | Path |
|------|------|
| **REST API** | `api-patterns/rest-design.md` |
| **GraphQL** | `api-patterns/graphql-design.md` |
| **Node.js** | `nodejs/express-patterns.md` |
| **Auth (JWT)** | `authentication/jwt-patterns.md` |
---
## By Approach
**REST** → `api-patterns/rest-design.md`
**GraphQL** → `api-patterns/graphql-design.md`
## By Language
**Node.js** → `nodejs/`
**Python** → `python/`
```
**Why this works**:
- ✅ Token-efficient (~240 tokens)
- ✅ Organized by approach first (REST, GraphQL)
- ✅ Then by tech (Node.js, Python)
- ✅ Functional concerns separate (authentication/)
---
## Example 5: Full-Stack Navigation
**File**: `development/fullstack-navigation.md`
**Pattern**: Workflow-focused
**Token count**: ~300 tokens
```markdown
# Full-Stack Development Navigation
**Scope**: End-to-end application development
---
## Common Stacks
### MERN (MongoDB, Express, React, Node)
```
Frontend: development/frontend/react/
Backend: development/backend/nodejs/express-patterns.md
Data: development/data/nosql-patterns/mongodb.md
API: development/backend/api-patterns/rest-design.md
```
### T3 Stack (Next.js, tRPC, Prisma, Tailwind)
```
Frontend: development/frontend/react/ + ui/web/ui-styling-standards.md
Backend: development/backend/nodejs/ + api-patterns/trpc-patterns.md
Data: development/data/orm-patterns/prisma.md
```
---
## Quick Routes
| Layer | Navigate To |
|-------|-------------|
| **Frontend** | `ui-navigation.md` |
| **Backend** | `backend-navigation.md` |
| **Data** | `data/navigation.md` |
---
## Common Workflows
**New API endpoint**:
1. `principles/api-design.md` (principles)
2. `backend/api-patterns/rest-design.md` (approach)
3. `backend/nodejs/express-patterns.md` (implementation)
**New React feature**:
1. `frontend/react/component-architecture.md` (structure)
2. `frontend/react/hooks-patterns.md` (logic)
3. `ui/web/ui-styling-standards.md` (styling)
```
**Why this works**:
- ✅ Token-efficient (~300 tokens)
- ✅ Shows common tech stacks
- ✅ Workflow-focused (how to build features)
- ✅ Points to layer-specific navigation
---
## Example 6: Minimal Navigation
**File**: `content/navigation.md`
**Pattern**: Simple category (few files)
**Token count**: ~150 tokens
```markdown
# Content Navigation
**Purpose**: Copywriting and content creation
---
## Structure
```
content/
├── navigation.md
├── copywriting-frameworks.md
└── tone-voice.md
```
---
## Quick Routes
| Task | Path |
|------|------|
| **Write copy** | `copywriting-frameworks.md` |
| **Set tone** | `tone-voice.md` |
---
## Files
**copywriting-frameworks.md** → AIDA, PAS, persuasive writing
**tone-voice.md** → Brand voice, tone guidelines
```
**Why this works**:
- ✅ Token-efficient (~150 tokens)
- ✅ Simple structure (only 2 files)
- ✅ No unnecessary complexity
- ✅ Clear and scannable
---
## Anti-Patterns (What NOT to Do)
### ❌ Too Verbose
```markdown
# Development Navigation
**Purpose**: This comprehensive navigation file is designed to help you navigate the extensive collection of software development patterns, standards, and best practices that we have carefully curated across all technology stacks including frontend frameworks like React and Vue, backend technologies such as Node.js and Python, database systems both SQL and NoSQL, and infrastructure tools for deployment and operations.
## Introduction
The development category represents a significant portion of our context system...
[Continues for 800+ tokens]
```
**Problems**:
- ❌ 800+ tokens (should be 200-300)
- ❌ Verbose explanations (should be concise)
- ❌ Hard to scan (should use tables/trees)
---
### ❌ Missing Structure
```markdown
# Development Navigation
Here are the files:
- clean-code.md
- api-design.md
- react-patterns.md
- express-patterns.md
```
**Problems**:
- ❌ No ASCII tree (hard to see hierarchy)
- ❌ No quick routes (hard to find tasks)
- ❌ No organization (just a list)
---
### ❌ Too Detailed
```markdown
# Development Navigation
## React Patterns
### Hooks
React hooks allow you to use state and lifecycle features in functional components. The most common hooks are:
1. useState - For managing component state
- Syntax: const [state, setState] = useState(initialValue)
- Example: const [count, setCount] = useState(0)
2. useEffect - For side effects
[... continues with full documentation]
```
**Problems**:
- ❌ Contains file contents (should just point to files)
- ❌ Duplicates information (should reference, not repeat)
- ❌ Too detailed (navigation, not documentation)
---
## Key Takeaways
### ✅ Good Navigation Files
1. **Token-efficient** (200-300 tokens)
2. **Scannable** (ASCII trees, tables)
3. **Task-focused** (quick routes)
4. **Organized** (by concern/type)
5. **Concise** (3-5 word descriptions)
### ❌ Bad Navigation Files
1. **Verbose** (500+ tokens)
2. **Hard to scan** (paragraphs)
3. **Unfocused** (no clear routes)
4. **Unorganized** (just lists)
5. **Detailed** (duplicates content)
---
## Related
- `../guides/navigation-design.md` - How to create navigation files
- `../guides/organizing-context.md` - How to choose organizational pattern
- `../standards/mvi.md` - Minimal Viable Information principle

122
.opencode/context/core/context-system/guides/compact.md Normal file
View File

@@ -0,0 +1,122 @@
<!-- Context: core/compact | Priority: high | Version: 1.1 | Updated: 2026-02-15 -->
# Context Compaction (Minimization)
**Purpose**: Compress verbose content into minimal viable information
**Last Updated**: 2026-02-15
---
## Core Idea
Transform verbose explanations → core concepts following MVI principle.
**Formula**: Verbose Content → Core Concept (1-3 sentences) → Key Points (3-5 bullets) → Minimal Example (<10 lines) → Reference Link → Compact File
---
## 5 Compression Techniques
### 1. Extract Core Concept
**From**: Paragraphs → **To**: 1-3 sentences
**Rule**: If you can't explain it in 3 sentences, simplify further.
### 2. Bulletize Key Points
**From**: Long paragraphs → **To**: 3-5 bullet points
**Rule**: Each bullet = one key fact. No sub-bullets.
### 3. Minimize Examples
**From**: Full implementations → **To**: Smallest working example (<10 lines)
**Rule**: Show the simplest case. Link to full examples.
### 4. Replace Repetition with References
**From**: Same info repeated → **To**: Define once, reference with links
**Rule**: Say it once in concepts/, reference everywhere else.
### 5. Convert Prose to Tables
**From**: Paragraphs listing things → **To**: Scannable tables
**Rule**: If listing >3 items, use a table or bullets.
---
## Compaction Checklist
- [ ] Core concept is 1-3 sentences?
- [ ] Key points are 3-5 bullets (no sub-bullets)?
- [ ] Example is <10 lines of code?
- [ ] No repeated explanations?
- [ ] Reference link added for deep dive?
- [ ] File is under line limit?
- [ ] Can be scanned in <30 seconds?
---
## Common Bloat Patterns to Remove
| Bloat Type | ❌ Avoid | ✅ Use Instead |
|------------|---------|---------------|
| Over-Explaining | "This is important because it allows you to manage state in a more efficient way..." | "Manages state efficiently" |
| Historical Context | "Before React 16.8, we used class components..." | Skip history unless critical |
| Multiple Examples | Example 1, 2, 3, 4... | ONE simple example + link |
| Implementation Details | "The internal implementation uses a fiber architecture..." | Skip internals, show usage |
---
## Target Line Counts
| File Type | Target | Max |
|-----------|--------|-----|
| Concept | 40-60 | 100 |
| Example | 30-50 | 80 |
| Guide | 60-100 | 150 |
| Lookup | 20-40 | 100 |
| Error | 50-80 | 150 |
**Philosophy**: If you hit max lines, split into multiple files or reference external docs.
---
## The 30-Second Rule
<rule id="thirty_second_rule" enforcement="strict">
Every context file must be scannable in <30 seconds.
</rule>
**Test**: Can someone unfamiliar explain it back in 30 seconds?
---
## Quick Example
**Before (150 lines)**: Long authentication system explanation with edge cases, examples, etc.
**After (45 lines)**:
```markdown
# Concept: Authentication
**Core Idea**: JWT-based stateless auth. Token in httpOnly cookie, verified on every request.
**Key Points**:
- Token has userId + role claims
- Expires in 1 hour (refresh token for renewal)
- Stored in httpOnly cookie (XSS protection)
- Verified via middleware on protected routes
**Quick Example**:
```js
const token = jwt.sign({ userId: 123 }, SECRET, { expiresIn: '1h' })
res.cookie('auth', token, { httpOnly: true })
```
**Reference**: https://docs.company.com/auth
**Related**: examples/jwt-auth.md, errors/auth-errors.md
```
---
## Related
- mvi.md - MVI principle
- harvest.md - When to compact
- templates.md - Standard formats

173
.opencode/context/core/context-system/guides/creation.md Normal file
View File

@@ -0,0 +1,173 @@
<!-- Context: core/creation | Priority: high | Version: 1.1 | Updated: 2026-02-15 -->
# Context File Creation Standards
**Purpose**: Ensure all context files follow the same format and structure
**Last Updated**: 2026-02-15
---
## Critical Rules
<critical_rules priority="absolute" enforcement="strict">
<rule id="size_limit">Files MUST be under line limits (see below)</rule>
<rule id="mvi_required">All files MUST follow MVI principle</rule>
<rule id="function_placement">Files MUST be in correct folder</rule>
<rule id="navigation_update">MUST update navigation.md when creating files</rule>
</critical_rules>
---
## Creation Workflow
### 1. Determine Function
Ask: Is this a concept, example, guide, lookup, or error?
→ Place in correct folder
### 2. Apply Template
Use standard template for file type (see templates.md)
### 3. Apply MVI
- Core: 1-3 sentences
- Key points: 3-5 bullets
- Example: <10 lines
- Reference: Link to docs
### 4. Validate Size
Ensure file under limit. If not, split or reference external.
### 5. Add Cross-References
Link to related concepts/, examples/, guides/, errors/
### 6. Update Navigation
Add entry to navigation.md in parent directory
---
## File Naming Conventions
| Type | Format | Example |
|------|--------|---------|
| Concept | `{concept-name}.md` | `authentication.md` |
| Example | `{example-name}.md` | `jwt-example.md` |
| Guide | `{action-name}.md` | `creating-agents.md` |
| Lookup | `{reference-name}.md` | `commands.md` |
| Error | `{error-category}.md` | `auth-errors.md` |
**Rules**:
- Use kebab-case (lowercase with hyphens)
- Be descriptive but concise
- Avoid redundant category in name (not `concept-authentication.md`)
---
## Standard Metadata (Frontmatter)
```html
<!-- Context: {path} | Priority: {level} | Version: {X.Y} | Updated: {YYYY-MM-DD} -->
```
**Priority levels**: critical, high, medium, low
**When to use**:
- critical: Core system files, always needed
- high: Frequently referenced, important patterns
- medium: Useful but not essential
- low: Nice-to-have, rarely needed
---
## File Size Limits
| File Type | Max Lines |
|-----------|-----------|
| Concept | 100 |
| Example | 80 |
| Guide | 150 |
| Lookup | 100 |
| Error | 150 |
**Enforcement**: Strict. If over limit, split into multiple files or reference external docs.
---
## Cross-Reference Guidelines
**Format**: `See {type}/{filename}.md for {what}`
**Examples**:
- `See concepts/authentication.md for JWT details`
- `See examples/jwt-example.md for working code`
- `See errors/auth-errors.md for troubleshooting`
**Best practices**:
- Link to related concepts
- Link to examples from guides
- Link to errors from guides
- Create bidirectional links when relevant
---
## Navigation Update Process
When creating a file, update parent `navigation.md`:
```markdown
| File | Description | Priority |
|------|-------------|----------|
| new-file.md | Brief description | high |
```
**Keep navigation**:
- Alphabetical within priority groups
- Grouped by priority (critical → high → medium → low)
- Descriptions <10 words
---
## Validation Before Commit
- [ ] File under line limit?
- [ ] MVI format applied?
- [ ] Frontmatter added?
- [ ] In correct folder?
- [ ] Navigation.md updated?
- [ ] Cross-references added?
- [ ] Can be scanned in <30 seconds?
---
## Common Creation Mistakes
| Mistake | Fix |
|---------|-----|
| File too long | Split into multiple files or compress |
| Missing frontmatter | Add HTML comment at top |
| Wrong folder | Move to correct function folder |
| No cross-references | Add links to related files |
| Verbose explanations | Apply MVI compression |
| Missing from navigation | Update navigation.md |
---
## Template Selection
| File Type | Template | Use When |
|-----------|----------|----------|
| Concept | Concept template | Explaining what something is |
| Example | Example template | Showing working code |
| Guide | Guide template | Step-by-step instructions |
| Lookup | Lookup template | Quick reference data |
| Error | Error template | Troubleshooting issues |
See templates.md for full templates.
---
## Related
- templates.md - File templates
- mvi.md - MVI principle
- compact.md - Compression techniques
- structure.md - Directory structure

133
.opencode/context/core/context-system/guides/navigation-design-basics.md Normal file
View File

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

185
.opencode/context/core/context-system/guides/navigation-templates.md Normal file
View File

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

152
.opencode/context/core/context-system/guides/organizing-context.md Normal file
View File

@@ -0,0 +1,152 @@
<!-- Context: core/organizing-context | Priority: high | Version: 1.1 | Updated: 2026-02-15 -->
# Guide: Organizing Context by Concern
**Purpose**: How to choose and apply the right organizational pattern
**Last Updated**: 2026-02-15
---
## Two Organizational Patterns
### Pattern A: Function-Based
**Use for**: Repository-specific context
**Structure**: Organize by what the information does
```
{repo}/
├── concepts/ # What it is
├── examples/ # Working code
├── guides/ # How to do it
├── lookup/ # Quick reference
└── errors/ # Troubleshooting
```
**Example**: `openagents-repo/`
---
### Pattern B: Concern-Based
**Use for**: Multi-technology development context
**Structure**: Organize by what you're doing (concern), then how (approach/tech)
```
{concern}/
├── {approach}/ # How you're doing it
└── {tech}/ # What you're using
```
**Example**: `development/frontend/react/`, `ui/web/design/`
---
## Decision Tree
| Question | Answer | Use Pattern |
|----------|--------|-------------|
| Is this repository-specific? | YES | **Pattern A** (Function-Based) |
| Does content span multiple technologies? | YES | **Pattern B** (Concern-Based) |
| Single domain/technology? | YES | **Pattern A** (Function-Based) |
---
## Quick Steps to Organize
### 1. Audit Existing Content
- List all files
- Identify natural groupings
- Note overlaps/duplicates
### 2. Choose Pattern
- Use decision tree above
- Consider future growth
- Check existing patterns in `.opencode/context/`
### 3. Create Directory Structure
```bash
mkdir -p {category}/{subcategory}
```
### 4. Move Files
- Move files to new structure
- Keep filenames descriptive
- Follow naming conventions
### 5. Create Navigation Files
- Add `navigation.md` to each directory
- Follow navigation template (see navigation-templates.md)
- Keep to 200-300 tokens
### 6. Update References
- Update links in moved files
- Update parent navigation.md
- Test navigation paths
---
## Pattern Examples
### Function-Based (openagents-repo/)
```
openagents-repo/
├── concepts/agents.md
├── examples/subagent-example.md
├── guides/creating-agents.md
├── lookup/commands.md
└── errors/tool-errors.md
```
### Concern-Based (development/)
```
development/
├── frontend/
│ ├── react/
│ └── vue/
├── backend/
│ ├── node/
│ └── python/
└── data/
└── postgres/
```
### Hybrid (ui/)
```
ui/
├── web/
│ ├── design/
│ ├── animation/
│ └── react-patterns.md
└── terminal/
└── cli-design.md
```
---
## Verification Checklist
- [ ] Every directory has navigation.md?
- [ ] Navigation files follow template?
- [ ] All files have frontmatter?
- [ ] Links updated and working?
- [ ] Pattern is consistent?
- [ ] Files under line limits?
---
## Troubleshooting
| Issue | Solution |
|-------|----------|
| File fits multiple categories | Choose primary purpose, reference from others |
| Too many files in one directory | Create subcategories |
| Unclear hierarchy | Use concern-based pattern |
| Navigation too complex | Simplify structure, use specialized navigation |
---
## Related
- structure.md - Directory structure standards
- navigation-templates.md - Navigation file templates
- creation.md - Creating new context files

573
.opencode/context/core/context-system/guides/workflows.md Normal file
View File

@@ -0,0 +1,573 @@
<!-- Context: core/workflows | Priority: high | Version: 1.0 | Updated: 2026-02-15 -->
# Context Operation Workflows
**Purpose**: Detailed interactive workflows for all context operations
**Last Updated**: 2026-01-06
---
## Extract Workflow (Interactive)
### Stage 1: Read Source
```
/context extract from https://react.dev/hooks
↓
Agent: "Reading source (8,500 lines)...
Analyzing content for extractable items..."
```
### Stage 2: Analyze & Categorize
```
Agent: "Analysis complete.
Found 12 core concepts:
- useState (state management)
- useEffect (side effects)
- useContext (context consumption)
... (9 more)
Found 8 common errors:
- Hooks called conditionally
- Hooks in loops
- Hooks outside components
... (5 more)
Found 3 workflows:
- Setting up custom hooks
- Debugging hook issues
- Testing components with hooks"
```
### Stage 3: Select Category (APPROVAL REQUIRED)
```
Agent: "Which category should this go in?
[1] development/
[2] core/
[3] Create new category: ___
Select items to extract:
Concepts:
✓ [A] useState
✓ [B] useEffect
✓ [C] useContext
... [D-L] (9 more)
Errors:
✓ [M] Hooks called conditionally
✓ [N] Hooks in loops
... [O-T] (6 more)
Guides:
✓ [U] Setting up custom hooks
✓ [V] Debugging hook issues
✓ [W] Testing components
Type items (A B M or 'all') + category (1/2/3):"
User: "all 1"
```
### Stage 4: Preview (APPROVAL REQUIRED)
```
Agent: "Would create in development/:
concepts/use-state.md (45 lines)
concepts/use-effect.md (52 lines)
concepts/use-context.md (38 lines)
... (9 more concept files)
errors/react-hooks-errors.md (124 lines)
- 8 errors grouped in one file
guides/custom-hooks.md (87 lines)
guides/debugging-hooks.md (65 lines)
guides/testing-hooks.md (72 lines)
Total: 15 files, ~850 lines
Preview specific file? (type filename or 'skip')
Approve? (yes/no/preview):"
User: "preview use-state.md"
Agent: [Shows first 30 lines of use-state.md]
User: "yes"
```
### Stage 5-7: Create, Update, Report
```
Agent: "Creating files...
✅ Extracted 20 items into development/
📄 Created 15 files
📊 Updated development/README.md
Files created:
- development/concepts/ (12 files)
- development/errors/react-hooks-errors.md
- development/guides/ (3 files)"
```
---
## Organize Workflow (Interactive)
### Stage 1-2: Scan & Categorize
```
/context organize development/
↓
Agent: "Scanning development/ (23 files, flat structure)...
Categorizing by function..."
```
### Stage 3: Resolve Conflicts (APPROVAL REQUIRED)
```
Agent: "Categorization plan:
Clear categorization (18 files):
concepts/ (8 files):
✓ authentication.md → concepts/authentication.md
✓ state-management.md → concepts/state-management.md
✓ caching.md → concepts/caching.md
... (5 more)
examples/ (5 files):
✓ jwt-example.md → examples/jwt-example.md
✓ hooks-example.md → examples/hooks-example.md
... (3 more)
guides/ (5 files):
✓ setting-up-auth.md → guides/setting-up-auth.md
... (4 more)
Ambiguous files (5 - need your input):
[?] api-design.md (contains concepts AND step-by-step guide)
Content: Explains REST principles (concept) + how to design endpoints (guide)
→ [A] Split into:
concepts/api-design.md (REST principles)
guides/api-design-guide.md (how to design)
→ [B] Keep as concepts/api-design.md (primary: concepts)
→ [C] Keep as guides/api-design.md (primary: guide)
[?] error-handling.md (contains guide AND error examples)
Content: How to handle errors (guide) + common error patterns (errors)
→ [D] Split into:
guides/error-handling.md (how to handle)
errors/common-errors.md (error patterns)
→ [E] Keep as guides/error-handling.md
→ [F] Keep as errors/error-handling.md
[?] testing-patterns.md (contains concepts AND examples)
→ [G] Split into concepts/ + examples/
→ [H] Keep as concepts/testing-patterns.md
→ [I] Keep as examples/testing-patterns.md
Conflicts (2):
[!] authentication.md → concepts/auth.md
Target concepts/auth.md already exists (120 lines)
→ [J] Merge authentication.md into existing auth.md
→ [K] Rename to concepts/authentication-v2.md
→ [L] Skip (keep flat)
[!] jwt-example.md → examples/jwt.md
Target examples/jwt.md already exists (65 lines)
→ [M] Merge jwt-example.md into existing jwt.md
→ [N] Rename to examples/jwt-example-v2.md
→ [O] Skip (keep flat)
Select resolutions (A D G J M or 'auto' for AI suggestions):"
User: "A D G J M"
```
### Stage 4: Preview (APPROVAL REQUIRED)
```
Agent: "Preview of changes:
CREATE directories:
development/concepts/
development/examples/
development/guides/
development/lookup/
development/errors/
MOVE files (18):
authentication.md → concepts/authentication.md
state-management.md → concepts/state-management.md
... (16 more)
SPLIT files (3):
api-design.md →
concepts/api-design.md (concepts section)
guides/api-design-guide.md (guide section)
error-handling.md →
guides/error-handling.md (guide section)
errors/common-errors.md (error examples)
testing-patterns.md →
concepts/testing-patterns.md (concepts)
examples/testing-examples.md (examples)
MERGE files (2):
authentication.md → concepts/auth.md (merge content)
jwt-example.md → examples/jwt.md (merge content)
UPDATE:
development/README.md (create navigation tables)
Fix 47 internal references
Dry-run? (yes/no/show-diff):"
User: "dry-run"
Agent: [Simulates changes without executing, shows what would happen]
User: "yes"
```
### Stage 5-8: Backup, Execute, Update, Report
```
Agent: "Creating backup...
💾 Backup: .tmp/backup/organize-development-2026-01-06-143022/
Executing changes...
✅ Organized 23 files into function folders
📁 Created 5 new folders
🔀 Split 3 ambiguous files
🔗 Fixed 47 references
📊 Updated development/README.md
Rollback available at: .tmp/backup/organize-development-2026-01-06-143022/"
```
---
## Update Workflow (Interactive)
### Stage 1: Identify Changes (APPROVAL REQUIRED)
```
/context update for Next.js 15
↓
Agent: "What changed in Next.js 15?
[A] API changes
[B] Deprecations
[C] New features
[D] Breaking changes
[E] Other (describe)
Select all that apply (A B C D or describe):"
User: "A C D"
Agent: "Please describe the changes:
API changes: ___
New features: ___
Breaking changes: ___"
User: "API changes: App router is now default
New features: New metadata API, Server Actions stable
Breaking changes: Pages router requires explicit opt-in"
```
### Stage 2: Find Affected Files
```
Agent: "Searching for files referencing Next.js...
Found 5 files with 17 references:
📄 concepts/routing.md (3 references, 145 lines)
📄 examples/app-router-example.md (7 references, 78 lines)
📄 guides/setting-up-nextjs.md (2 references, 132 lines)
📄 errors/nextjs-errors.md (1 reference, 98 lines)
📄 lookup/nextjs-commands.md (4 references, 54 lines)
Total impact: 17 references across 5 files"
```
### Stage 3: Preview Changes (APPROVAL REQUIRED)
```
Agent: "Proposed updates:
━━━ concepts/routing.md ━━━
Line 15:
- App router is optional (use pages/ or app/ directory)
+ App router is now default in Next.js 15 (pages/ still supported with opt-in)
Line 42:
+ ## Metadata API (New in v15)
+
+ Next.js 15 introduces new metadata API for SEO optimization.
+ Replaces Head component with metadata exports.
Line 87:
- **Reference**: https://nextjs.org/docs/app
+ **Reference**: https://nextjs.org/docs/15/app
━━━ examples/app-router-example.md ━━━
Line 8:
- // Optional: use app router
+ // Default in Next.js 15+
Line 23:
+ // New: Metadata API
+ export const metadata = {
+ title: 'My App',
+ description: 'App description'
+ }
━━━ guides/setting-up-nextjs.md ━━━
Line 45:
- 3. Choose router: pages/ or app/
+ 3. App router is default (use --pages flag for pages router)
━━━ errors/nextjs-errors.md ━━━
Line 67:
+ ## Migration: Next.js 14 → 15
+
+ **Breaking Changes**:
+ - App router is now default
+ - Pages router requires explicit opt-in
+
+ **Migration Steps**:
+ 1. Update to Next.js 15: `bun --bun install next@15`
+ 2. For pages router: Add `pages: true` to next.config.js
+ 3. Update metadata: Replace Head with metadata exports
+
+ **Reference**: https://nextjs.org/docs/15/upgrade-guide
━━━ lookup/nextjs-commands.md ━━━
Line 12:
- bunx --bun create-next-app@latest
+ bunx --bun create-next-app@latest # App router default
+ bunx --bun create-next-app@latest --pages # Pages router
Preview next file? (yes/no/show-all)
Approve changes? (yes/no/edit):"
User: "edit"
Agent: "Line-by-line approval mode.
concepts/routing.md - Line 15 change?
- App router is optional (use pages/ or app/ directory)
+ App router is now default in Next.js 15 (pages/ still supported with opt-in)
Approve? (yes/no/modify):"
User: "yes"
[... continues for each change ...]
```
### Stage 4-8: Backup, Update, Add Migration, Validate, Report
```
Agent: "Creating backup...
💾 Backup: .tmp/backup/update-nextjs-2026-01-06-143530/
Updating files...
✅ Updated 5 files
📝 Modified 17 references
🔄 Added migration notes to errors/nextjs-errors.md
🔗 Validated all references (0 broken links)
Summary of changes:
- concepts/routing.md: 3 updates (145 → 162 lines)
- examples/app-router-example.md: 4 updates (78 → 89 lines)
- guides/setting-up-nextjs.md: 1 update (132 → 133 lines)
- errors/nextjs-errors.md: Added migration section (98 → 125 lines)
- lookup/nextjs-commands.md: 2 updates (54 → 56 lines)
All files still under 200 line limit ✓
Rollback available at: .tmp/backup/update-nextjs-2026-01-06-143530/"
```
---
## Error Workflow (Interactive)
### Stage 1: Search Existing
```
/context error for "Cannot read property 'map' of undefined"
↓
Agent: "Searching existing errors for similar issues...
Found 1 similar error:
📄 development/errors/react-errors.md (Line 45)
## Error: Cannot read property 'X' of undefined
Covers: General undefined property access in React
Frequency: common
Found 2 related errors:
📄 development/errors/react-errors.md
## Error: Cannot read property 'length' of undefined
## Error: Undefined is not an object"
```
### Stage 2: Check Duplication (APPROVAL REQUIRED)
```
Agent: "Options:
[A] Add as new error to react-errors.md
(Specific case: 'map' on undefined array)
[B] Update existing 'Cannot read property X' error
(Add 'map' as common example)
[C] Skip (already covered sufficiently)
Which framework/category?
[1] React (react-errors.md)
[2] JavaScript (js-errors.md)
[3] General (common-errors.md)
[4] Create new: ___
Select option + category (e.g., 'B 1'):"
User: "B 1"
```
### Stage 3: Preview (APPROVAL REQUIRED)
```
Agent: "Would update development/errors/react-errors.md:
Current (Line 45):
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
## Error: Cannot read property 'X' of undefined
**Symptom**:
```
TypeError: Cannot read property 'X' of undefined
```
**Cause**: Attempting to access property on undefined/null object.
**Solution**:
1. Add null check before accessing property
2. Use optional chaining (?.)
3. Provide default value
**Code**:
```jsx
// ❌ Before
const value = obj.property
// ✅ After
const value = obj?.property ?? 'default'
```
**Prevention**: Always validate data exists before accessing
**Frequency**: common
**Reference**: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Errors/Cant_access_property
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Proposed update:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
## Error: Cannot read property 'X' of undefined
**Symptom**:
```
TypeError: Cannot read property 'X' of undefined
TypeError: Cannot read property 'map' of undefined ← NEW
TypeError: Cannot read property 'length' of undefined ← NEW
```
**Cause**: Attempting to access property on undefined/null object.
Common with array methods (map, filter) when data hasn't loaded. ← NEW
**Solution**:
1. Add null check before accessing property
2. Use optional chaining (?.)
3. Provide default value (especially for arrays) ← UPDATED
**Code**:
```jsx
// ❌ Before
const value = obj.property
const items = data.map(item => item.name) ← NEW
// ✅ After
const value = obj?.property ?? 'default'
const items = (data || []).map(item => item.name) ← NEW
// Or with optional chaining:
const items = data?.map(item => item.name) ?? [] ← NEW
```
**Prevention**: Always validate data exists before accessing.
For arrays, provide empty array default. ← UPDATED
**Frequency**: common
**Reference**: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Errors/Cant_access_property
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
File size: 98 lines → 105 lines (under 150 limit ✓)
Approve? (yes/no/edit):"
User: "yes"
```
### Stage 4-6: Add, Update, Report
```
Agent: "Updating development/errors/react-errors.md...
✅ Updated error in development/errors/react-errors.md
🔗 Cross-referenced with 2 related errors
📊 File size: 105 lines (under 150 limit)
Changes:
- Added 'map' and 'length' to symptom examples
- Updated cause to mention array methods
- Added array-specific code examples
- Updated prevention guidance"
```
---
## Common Patterns
### Approval Gates
All operations with `enforce="@critical_rules.approval_gate"` MUST:
1. Show clear preview of what will happen
2. Wait for explicit user input
3. Provide options (yes/no/edit/preview/dry-run)
4. Never proceed without confirmation
### Conflict Resolution
When conflicts detected:
1. Present all options clearly
2. Use letter-based selection (A/B/C)
3. Show impact of each option
4. Allow user to choose resolution
### Previews
All previews should show:
1. What will be created/modified/deleted
2. File sizes (before → after)
3. Line-by-line diffs for updates
4. Validation status (under limits, no broken links)
### Backups
Operations that modify files MUST:
1. Create backup before changes
2. Store in `.tmp/backup/{operation}-{topic}-{timestamp}/`
3. Report backup location
4. Keep backups for rollback
---
## Related
- context.md - Main command interface
- harvest.md - Harvest workflow details
- mvi-principle.md - What to extract
- compact.md - How to minimize

53
.opencode/context/core/context-system/navigation.md Normal file
View File

@@ -0,0 +1,53 @@
<!-- Context: core/navigation | Priority: critical | Version: 1.0 | Updated: 2026-02-15 -->
# Context System
**Purpose**: Documentation for the context system architecture and operations
---
## Structure
```
core/context-system/
├── navigation.md (this file)
├── examples/
│ └── navigation.md
├── guides/
│ └── navigation.md
├── operations/
│ └── navigation.md
├── standards/
│ └── navigation.md
└── [overview files]
```
---
## Quick Routes
| Task | Path |
|------|------|
| **Understand context system** | `../context-system.md` |
| **Operations & procedures** | `operations/navigation.md` |
| **Implementation guides** | `guides/navigation.md` |
| **Standards & templates** | `standards/navigation.md` |
| **Examples** | `examples/navigation.md` |
| **Migrate global → local** | `operations/migrate.md` |
---
## By Type
**Examples** → Working examples of navigation files
**Guides** → Step-by-step guides for working with context
**Operations** → How to operate and maintain the context system
**Standards** → Templates and standards for context files
---
## Related Context
- **Core Navigation** → `../navigation.md`
- **Core Standards** → `../standards/navigation.md`
- **Core System** → `../system/navigation.md`

275
.opencode/context/core/context-system/operations/error.md Normal file
View File

@@ -0,0 +1,275 @@
<!-- Context: core/error | Priority: medium | Version: 1.0 | Updated: 2026-02-15 -->
# Error Operation
**Purpose**: Add recurring errors to knowledge base with deduplication
**Last Updated**: 2026-01-06
---
## When to Use
- Encountered same error multiple times
- Want to document solution for team
- Building error knowledge base
- Preventing repeated debugging
---
## 6-Stage Workflow
### Stage 1: Search Existing
**Action**: Search for similar/related errors
**Process**:
1. Search error message across all errors/ files
2. Find similar errors (fuzzy matching)
3. Find related errors (same category)
**Format**:
```
Searching for: "Cannot read property 'map' of undefined"
Found 1 similar error:
📄 development/errors/react-errors.md (Line 45)
## Error: Cannot read property 'X' of undefined
Covers: General undefined property access
Frequency: common
Found 2 related errors:
📄 development/errors/react-errors.md
## Error: Cannot read property 'length' of undefined
## Error: Undefined is not an object
```
---
### Stage 2: Check Duplication (APPROVAL REQUIRED)
**Action**: Present deduplication options
**Format**:
```
Options:
[A] Add as new error to react-errors.md
(Specific case: 'map' on undefined array)
[B] Update existing 'Cannot read property X' error
(Add 'map' as common example)
[C] Skip (already covered sufficiently)
Which framework/category?
[1] React (react-errors.md)
[2] JavaScript (js-errors.md)
[3] General (common-errors.md)
[4] Create new: ___
Select option + category (e.g., 'B 1'):
```
**Validation**: MUST wait for user input
---
### Stage 3: Preview (APPROVAL REQUIRED)
**Action**: Show full error entry before adding
**Format**:
```
Would update development/errors/react-errors.md:
Current (Line 45):
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
## Error: Cannot read property 'X' of undefined
**Symptom**:
```
TypeError: Cannot read property 'X' of undefined
```
**Cause**: Attempting to access property on undefined/null object.
**Solution**:
1. Add null check
2. Use optional chaining (?.)
3. Provide default value
**Code**:
```jsx
// ❌ Before
const value = obj.property
// ✅ After
const value = obj?.property ?? 'default'
```
**Prevention**: Always validate data exists
**Frequency**: common
**Reference**: [Link]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Proposed update:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
## Error: Cannot read property 'X' of undefined
**Symptom**:
```
TypeError: Cannot read property 'X' of undefined
TypeError: Cannot read property 'map' of undefined ← NEW
TypeError: Cannot read property 'length' of undefined ← NEW
```
**Cause**: Attempting to access property on undefined/null object.
Common with array methods (map, filter) when data hasn't loaded. ← NEW
**Solution**:
1. Add null check
2. Use optional chaining (?.)
3. Provide default value (especially for arrays) ← UPDATED
**Code**:
```jsx
// ❌ Before
const value = obj.property
const items = data.map(item => item.name) ← NEW
// ✅ After
const value = obj?.property ?? 'default'
const items = (data || []).map(item => item.name) ← NEW
```
**Prevention**: Always validate data exists. For arrays, provide empty array default. ← UPDATED
**Frequency**: common
**Reference**: [Link]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
File size: 98 lines → 105 lines (under 150 limit ✓)
Approve? (yes/no/edit):
```
**Edit mode**: Allow modification before adding
**Validation**: MUST get approval before proceeding
---
### Stage 4: Add/Update
**Action**: Add or update error entry
**Process**:
1. Add/update error in target file
2. Follow error template format
3. Maintain file size <150 lines
4. Update "Last Updated" date
**Template Format**:
```markdown
## Error: {Name}
**Symptom**: [Error message]
**Cause**: [Why - 1-2 sentences]
**Solution**: [Steps]
**Code**: [Before/After example]
**Prevention**: [How to avoid]
**Frequency**: common/occasional/rare
**Reference**: [Link]
```
---
### Stage 5: Update Navigation
**Action**: Update README.md and add cross-references
**Process**:
1. Update README.md if new file created
2. Add cross-references to related errors
3. Link from related concepts/examples
---
### Stage 6: Report
**Action**: Show results
**Format**:
```
✅ Added error to {category}/errors/{file}.md
🔗 Cross-referenced with X related errors
📊 Updated README.md (if needed)
Changes:
- Updated existing error entry
- Added 'map' and 'length' examples
- File size: 105 lines (under 150 limit)
```
---
## Deduplication Strategy
### Similar Errors
Same root cause, different manifestations
→ **Update existing** to include new examples
### Related Errors
Different causes, same category
→ **Cross-reference** between errors
### Duplicate Errors
Exact same error already documented
→ **Skip** (already covered)
### New Errors
Unique error not yet documented
→ **Add as new** error entry
---
## Error Grouping
Group errors by framework/topic in single file:
- `react-errors.md` - All React errors
- `nextjs-errors.md` - All Next.js errors
- `auth-errors.md` - All authentication errors
**Don't create**: One file per error (too granular)
---
## Examples
### Add New Error
```bash
/context error for "hooks can only be called inside components"
```
### Add Common Error
```bash
/context error for "Cannot read property 'map' of undefined"
```
### Add Framework Error
```bash
/context error for "Hydration failed in Next.js"
```
---
## Success Criteria
- [ ] Searched for similar errors?
- [ ] Deduplication options presented?
- [ ] Preview shown?
- [ ] User approved?
- [ ] Error follows template format?
- [ ] File size <150 lines?
- [ ] Cross-references added?
- [ ] README.md updated (if new file)?
---
## Related
- standards/templates.md - Error template format
- guides/workflows.md - Interactive examples

202
.opencode/context/core/context-system/operations/extract.md Normal file
View File

@@ -0,0 +1,202 @@
<!-- Context: core/extract | Priority: medium | Version: 1.0 | Updated: 2026-02-15 -->
# Extract Operation
**Purpose**: Extract context from docs, code, or URLs into organized context files
**Last Updated**: 2026-01-06
---
## When to Use
- Extracting from documentation (React docs, API docs, etc.)
- Extracting from codebase (patterns, conventions)
- Extracting from URLs (blog posts, guides)
- Creating initial context for new topics
---
## 7-Stage Workflow
### Stage 1: Read Source
```
/context extract from https://react.dev/hooks
↓
Agent: "Reading source (8,500 lines)...
Analyzing content for extractable items..."
```
**Action**: Read and analyze source material
---
### Stage 2: Analyze & Categorize
**Action**: Extract and categorize content by function
**Categorization**:
- Design decisions → `concepts/`
- Working code → `examples/`
- Step-by-step workflows → `guides/`
- Reference data (commands, paths) → `lookup/`
- Errors/gotchas → `errors/`
**Output**: List of extractable items with previews
---
### Stage 3: Select Category (APPROVAL REQUIRED)
**Action**: User chooses target category and items
**Format**:
```
Found 12 extractable items from {source}:
Concepts (8):
✓ [A] useState - State management hook
✓ [B] useEffect - Side effects hook
... (6 more)
Errors (4):
✓ [I] Hooks called conditionally
✓ [J] Hooks in loops
... (2 more)
Which category?
[1] development/
[2] core/
[3] Create new category: ___
Select items (A B I or 'all') + category (1/2/3):
```
**Validation**: MUST wait for user input before proceeding
---
### Stage 4: Preview (APPROVAL REQUIRED)
**Action**: Show what will be created, check for conflicts
**Format**:
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Extraction Plan: development/
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
CREATE (new files):
concepts/use-state.md (45 lines)
concepts/use-effect.md (52 lines)
concepts/use-context.md (38 lines)
... (6 more)
guides/custom-hooks.md (87 lines)
guides/debugging-hooks.md (65 lines)
ADD TO (existing files):
errors/react-hooks-errors.md (98 → 124 lines)
+ 4 new error entries
⚠️ CONFLICT (file already exists):
concepts/use-memo.md already exists (42 lines)
Options:
[A] Skip — keep existing file
[B] Overwrite — replace with extracted version
[C] Merge — add new content to existing file (42 → 58 lines)
Choose [A/B/C]: _
NAVIGATION UPDATE:
development/navigation.md
+ 9 new entries in Concepts table
+ 2 new entries in Guides table
+ 1 updated entry in Errors table
Total: 12 files, ~650 lines
Preview content? (type filename, 'all' for batch, or 'skip')
Approve? [y/n/edit]: _
```
**If user types 'all'**: Show first 10 lines of each file in sequence
**If user types filename**: Show full content of that file
**If user types 'skip'**: Proceed to approval
**Validation**: MUST get approval before proceeding
---
### Stage 5: Create
**Action**: Create files in function folders
**Process**:
1. Apply MVI format (1-3 sentences, 3-5 key points, minimal example)
2. Create files in correct function folders
3. Ensure all files <200 lines
4. Add cross-references
**Enforcement**: `@critical_rules.mvi_strict` + `@critical_rules.function_structure`
---
### Stage 6: Update Navigation (preview included in Stage 4)
**Action**: Update navigation.md and add cross-references
**Process**:
1. Update category navigation.md with new files (as previewed in Stage 4)
2. Add priority levels (critical/high/medium/low)
3. Add cross-references between related files
4. Update "Last Updated" dates
---
### Stage 7: Report
**Action**: Show comprehensive results
**Format**:
```
✅ Extracted X items into {category}
📄 Created Y files
📊 Updated {category}/README.md
Files created:
- {category}/concepts/ (N files)
- {category}/examples/ (N files)
- {category}/errors/ (N files)
```
---
## Examples
### Extract from URL
```bash
/context extract from https://react.dev/hooks
```
### Extract from Local Docs
```bash
/context extract from docs/api.md
/context extract from docs/architecture/
```
### Extract from Code
```bash
/context extract from src/utils/
```
---
## Success Criteria
- [ ] All files <200 lines?
- [ ] MVI format applied (1-3 sentences, 3-5 points, example, reference)?
- [ ] Files in correct function folders?
- [ ] README.md updated?
- [ ] Cross-references added?
- [ ] User approved before creation?
---
## Related
- standards/mvi.md - What to extract
- guides/compact.md - How to minimize
- guides/workflows.md - Interactive examples

342
.opencode/context/core/context-system/operations/harvest.md Normal file
View File

@@ -0,0 +1,342 @@
<!-- Context: core/harvest | Priority: medium | Version: 1.0 | Updated: 2026-02-15 -->
# Context Harvest Operation
**Purpose**: Extract knowledge from AI summaries → permanent context, then clean workspace
**Last Updated**: 2026-01-06
---
## Core Problem
AI agents create summary files (OVERVIEW.md, SESSION-*.md, SUMMARY.md) that contain valuable knowledge but clutter the workspace. These files "plague" the codebase.
**Solution**: Harvest the knowledge → permanent context, then delete the summaries.
---
## Auto-Detection Patterns
<rule id="summary_patterns" enforcement="strict">
Harvest automatically detects these patterns:
Filename patterns:
- *OVERVIEW.md
- *SUMMARY.md
- SESSION-*.md
- CONTEXT-*.md
- *NOTES.md
Location patterns:
- Files in .tmp/ directory
- Files with "Summary", "Overview", "Session" in title
- Files >2KB in root directory (likely summaries)
</rule>
---
## 6-Stage Workflow
<workflow id="harvest" enforce="@critical_rules">
### Stage 1: Scan
**Action**: Find all summary files in workspace
**Process**:
1. Search for auto-detection patterns
2. Check .tmp/ directory
3. List files with sizes
4. Sort by modification date (newest first)
**Output**: List of candidate files
**Example**:
```
Found 3 summary documents:
1. CONTEXT-SYSTEM-OVERVIEW.md (4.2 KB, modified 1 hour ago)
2. SESSION-auth-work.md (1.8 KB, modified today)
3. .tmp/IMPLEMENTATION-NOTES.md (800 bytes, modified today)
```
---
### Stage 2: Analyze
**Action**: Categorize content by function
**Mapping Rules**:
| Content Type | Target Folder | How to Identify |
|--------------|---------------|-----------------|
| Design decisions | `concepts/` | "We decided to...", "Architecture", "Pattern" |
| Solutions/patterns | `examples/` | Code snippets, "Here's how we..." |
| Workflows | `guides/` | Numbered steps, "How to...", "Setup" |
| Errors encountered | `errors/` | Error messages, "Fixed issue", "Gotcha" |
| Reference data | `lookup/` | Tables, lists, paths, commands |
**Process**:
1. Read each file
2. Identify valuable sections (skip planning/conversation)
3. Categorize by function
4. Determine target file path
5. Generate preview (first 60 chars)
**Output**: Categorized items with letter IDs
---
### Stage 3: Approve (CRITICAL)
**Action**: Present approval UI with letter-based selection
<rule id="approval_gate" enforcement="strict">
ALWAYS show approval UI before extracting/deleting.
NEVER auto-harvest without user confirmation.
</rule>
**Format**:
```
### CONTEXT-SYSTEM-OVERVIEW.md (4.2 KB)
✓ [A] Design: Function-based context organization
→ Would add to: core/concepts/context-organization.md
Preview: "Organize by function (concepts/, examples/...)..."
✓ [B] Pattern: Minimal Viable Information
→ Would add to: core/concepts/mvi-principle.md
Preview: "Extract core only (1-3 sentences), 3-5 key points..."
✓ [C] Workflow: Harvesting summary documents
→ Would create: core/guides/harvesting.md
Preview: "Scan for summaries → Extract → Approve → Delete"
✗ [D] Skip: Planning discussion notes (temporary knowledge)
---
### SESSION-auth-work.md (1.8 KB)
✓ [E] Error: JWT token expiration not handled
→ Would add to: development/errors/auth-errors.md
Preview: "Symptom: 401 after 1 hour. Cause: No refresh flow..."
✓ [F] Example: JWT refresh token implementation
→ Would create: development/examples/jwt-refresh.md
Preview: "Store refresh token → Check expiry → Request new..."
---
### .tmp/IMPLEMENTATION-NOTES.md (800 bytes)
✗ [G] Skip: Duplicate info (already in development/concepts/api-design.md)
---
**Quick options**:
- Type 'A B C E F' - Approve specific items
- Type 'all' - Approve all ✓ items (A B C E F)
- Type 'none' - Skip harvesting, delete files anyway
- Type 'cancel' - Keep files, don't harvest
```
**Validation**:
- MUST wait for user input
- MUST not proceed without approval
- If user types 'cancel', stop immediately
**Output**: List of approved items
---
### Stage 4: Extract
**Action**: Extract and minimize approved items
<rule id="extraction" enforce="@mvi_principle">
Apply MVI to all extracted content:
- Core concept: 1-3 sentences
- Key points: 3-5 bullets
- Minimal example: <10 lines
- Reference link: to original source
- Files: <200 lines each
</rule>
**Process**:
1. For each approved item:
- Extract core content
- Apply MVI minimization (see compact.md)
- Generate preview of final content
2. Show extraction preview (APPROVAL REQUIRED):
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Extraction Preview
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[A] → core/concepts/context-organization.md (CREATE, 45 lines)
┌─────────────────────────────────────────────────────────┐
│ # Concept: Context Organization │
│ │
│ **Purpose**: Function-based knowledge organization │
│ │
│ ## Core Concept │
│ Organize context by function: concepts/, examples/... │
│ ... │
└─────────────────────────────────────────────────────────┘
[E] → development/errors/auth-errors.md (ADD to existing, 98 → 112 lines)
┌─────────────────────────────────────────────────────────┐
│ + ## Error: JWT Token Expiration Not Handled │
│ + │
│ + **Symptom**: 401 after 1 hour │
│ + **Cause**: No refresh token flow │
│ + ... │
└─────────────────────────────────────────────────────────┘
... ({remaining_count} more items)
Show all? [y/n] | Approve extraction? [y/n/edit]: _
```
3. On approval:
- Write files to disk
- Add cross-references
- Update navigation.md maps
**Output**: List of created/updated files
---
### Stage 5: Cleanup (APPROVAL REQUIRED)
**Action**: Archive or delete source summary files
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Cleanup: Source Files
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Successfully harvested from:
CONTEXT-SYSTEM-OVERVIEW.md (4.2 KB)
SESSION-auth-work.md (1.8 KB)
Skipped (no valuable content):
.tmp/IMPLEMENTATION-NOTES.md (800 bytes)
How should we handle these source files?
1. Archive (safe) — move to .tmp/archive/harvested/{date}/
→ Can restore later if needed
2. Delete — permanently remove harvested files
→ Frees disk space, no undo
3. Keep — leave source files in place
→ No cleanup, files remain where they are
Choose [1/2/3] (default: 1): _
```
<rule id="cleanup_safety" enforcement="strict">
ONLY cleanup files that had content successfully harvested.
If extraction failed, keep the original file.
</rule>
**Output**: Cleanup report
---
### Stage 6: Report
**Action**: Show comprehensive results summary
**Format**:
```
✅ Harvested 5 items into permanent context:
- Added to core/concepts/context-organization.md
- Added to core/concepts/mvi-principle.md
- Created core/guides/harvesting.md
- Added to development/errors/auth-errors.md
- Created development/examples/jwt-refresh.md
🗑️ Cleaned up workspace:
- Archived: CONTEXT-SYSTEM-OVERVIEW.md → .tmp/archive/harvested/2026-01-06/
- Archived: SESSION-auth-work.md → .tmp/archive/harvested/2026-01-06/
- Deleted: .tmp/IMPLEMENTATION-NOTES.md (no valuable content)
📊 Updated navigation maps:
- .opencode/context/core/navigation.md
- .opencode/context/development/navigation.md
💾 Disk space freed: 6.8 KB
```
</workflow>
---
## Usage Examples
### Scan entire workspace
```bash
/context harvest
```
### Scan specific directory
```bash
/context harvest .tmp/
/context harvest docs/sessions/
```
### Harvest specific file
```bash
/context harvest OVERVIEW.md
/context harvest SESSION-2026-01-06.md
```
---
## Smart Content Detection
### ✅ Extract (Valuable Knowledge)
- Design decisions ("We chose X because...")
- Patterns that worked ("This pattern solved...")
- Errors encountered + solutions
- API changes ("Updated from v1 to v2...")
- Performance findings ("Optimization reduced...")
- Core concepts explained
### ❌ Skip (Temporary/Noise)
- Planning discussion ("Should we...?", "Maybe try...")
- Conversational notes ("I think...", "We talked about...")
- Duplicate info (already in context)
- TODO lists (move to task system instead)
- Timestamps and session metadata
---
## Safety Features
1. **Approval gate** - Never auto-delete without confirmation
2. **Archive by default** - Move to .tmp/archive/, not permanent delete
3. **Validation** - Check file sizes, structure before committing
4. **Rollback** - Can restore from archive if needed
5. **Dry run** - Show what would happen before doing it
---
## Success Criteria
After harvest operation:
- [ ] Valuable knowledge extracted to permanent context?
- [ ] All extracted files <200 lines?
- [ ] Files in correct function folders?
- [ ] navigation.md navigation updated?
- [ ] Summary files archived/deleted?
- [ ] Workspace cleaner than before?
- [ ] No knowledge lost?
---
## Related
- compact.md - How to minimize extracted content
- mvi-principle.md - What to extract
- structure.md - Where files go
- creation.md - File creation rules

223
.opencode/context/core/context-system/operations/migrate.md Normal file
View File

@@ -0,0 +1,223 @@
<!-- Context: core/migrate | Priority: medium | Version: 1.0 | Updated: 2026-02-15 -->
# Context Migrate Operation
**Purpose**: Copy context files from global (`~/.config/opencode/context/`) to local (`.opencode/context/`) so they're project-specific and git-committed.
**Last Updated**: 2026-02-06
---
## Core Problem
Users who installed OAC globally have project-intelligence files at `~/.config/opencode/context/project-intelligence/`. These files are project-specific patterns but aren't committed to git or shared with the team.
**Solution**: Migrate project-intelligence from global → local, so patterns are version-controlled and team-shared.
---
## 4-Stage Workflow
<workflow id="migrate" enforce="@critical_rules">
### Stage 1: Detect Sources
Scan for context files in the global config directory:
```
Scanning global context...
Global location: ~/.config/opencode/context/
Found:
project-intelligence/
technical-domain.md (1.2 KB, Version: 1.3)
navigation.md (800 bytes, Version: 1.0)
business-domain.md (1.5 KB, Version: 1.1)
Local location: .opencode/context/
Status: No local project-intelligence/ found
```
**If no global context found:**
```
No global context found at ~/.config/opencode/context/
Nothing to migrate. Use /add-context to create project intelligence.
```
→ Exit
**If no global project-intelligence found (but other global context exists):**
```
Global context found at ~/.config/opencode/context/ but no project-intelligence/ directory.
Only project-intelligence files are migrated (project-specific patterns).
Core standards stay in global (they're universal, not project-specific).
Nothing to migrate. Use /add-context to create project intelligence.
```
→ Exit
---
### Stage 2: Check for Conflicts
If local `.opencode/context/project-intelligence/` already exists:
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Conflict: Local project-intelligence already exists
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Global files: Local files:
technical-domain.md technical-domain.md
Version: 1.3, Updated: 2026-01-15 Version: 1.0, Updated: 2026-02-01
navigation.md navigation.md
Version: 1.0, Updated: 2026-01-10 Version: 1.0, Updated: 2026-02-01
business-domain.md (not present locally)
Version: 1.1, Updated: 2026-01-12
Options:
1. Skip existing — only copy files that don't exist locally
→ Will copy: business-domain.md
→ Will skip: technical-domain.md, navigation.md (local kept)
2. Overwrite all — replace local with global versions
→ Will overwrite: technical-domain.md, navigation.md
→ Will copy: business-domain.md
→ Local backup created first
3. Cancel
Choose [1/2/3]: _
```
**If user chooses 2 (Overwrite), show content diff first:**
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Diff: technical-domain.md
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Local (current): Global (incoming):
Version: 1.0 Version: 1.3
Tech Stack: Next.js 14 Tech Stack: Next.js 15 ← different
API: basic validation API: Zod validation ← different
Component: same Component: same
Naming: same Naming: same
Show full diff? [y/n]: _
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Backup local files to .tmp/backup/migrate-{timestamp}/ before overwriting?
[y/n] (default: y): _
```
If no conflicts → proceed directly to Stage 3.
---
### Stage 3: Approval & Copy
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Migration Plan
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Will copy from: ~/.config/opencode/context/project-intelligence/
Will copy to: .opencode/context/project-intelligence/
Files to copy:
✓ technical-domain.md (1.2 KB)
✓ navigation.md (800 bytes)
✓ business-domain.md (1.5 KB)
After migration:
→ Local files committed to git = team gets your patterns
→ Agents load local (overrides global)
→ Global files remain as fallback for other projects
Proceed? [y/n]: _
```
**Actions on approval:**
1. Create `.opencode/context/project-intelligence/` if it doesn't exist
2. Copy each file from global → local
3. Validate copied files (frontmatter, MVI compliance)
---
### Stage 4: Cleanup & Confirmation
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Migration Complete
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Copied 3 files to .opencode/context/project-intelligence/
✓ technical-domain.md
✓ navigation.md
✓ business-domain.md
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Clean up global project-intelligence?
The global files are no longer needed for THIS project (local takes priority).
Keeping them means they still apply as fallback to other projects.
1. Keep global files (safe default)
2. Remove global project-intelligence/ (only affects this user)
Choose [1/2] (default: 1): _
```
**If user chooses 2 (Remove):**
- Delete `~/.config/opencode/context/project-intelligence/` only
- Do NOT touch `~/.config/opencode/context/core/` or any other global context
</workflow>
---
## What Gets Migrated
| Migrated (project-specific) | NOT Migrated (universal) |
|---|---|
| `project-intelligence/` | `core/standards/` |
| `project-intelligence/technical-domain.md` | `core/context-system/` |
| `project-intelligence/business-domain.md` | `core/workflows/` |
| `project-intelligence/navigation.md` | `core/guides/` |
| `project-intelligence/decisions-log.md` | Any other `core/` files |
| `project-intelligence/living-notes.md` | |
**Rationale**: Project intelligence is project-specific (YOUR tech stack, YOUR patterns). Core standards are universal (code quality, documentation standards) and should stay global.
---
## Error Handling
**Permission denied:**
```
Error: Cannot write to .opencode/context/project-intelligence/
Check directory permissions and try again.
```
**Global path not found:**
```
No global OpenCode config found at ~/.config/opencode/
If you installed to a custom location, set OPENCODE_INSTALL_DIR:
export OPENCODE_INSTALL_DIR=/your/custom/path
/context migrate
```
---
## Related
- `/add-context` — Create new project intelligence (interactive wizard)
- `/context harvest` — Extract knowledge from summaries
- Context path resolution: `.opencode/context/core/system/context-paths.md`

224
.opencode/context/core/context-system/operations/organize.md Normal file
View File

@@ -0,0 +1,224 @@
<!-- Context: core/organize | Priority: medium | Version: 1.0 | Updated: 2026-02-15 -->
# Organize Operation
**Purpose**: Restructure flat context files into function-based folder structure
**Last Updated**: 2026-01-06
---
## When to Use
- Migrating from flat structure to function-based
- Cleaning up disorganized context directories
- Splitting ambiguous files into proper categories
- Resolving duplicate/conflicting files
---
## 8-Stage Workflow
### Stage 1: Scan
**Action**: Scan category for all files and detect structure
**Output**: List of files with current structure type (flat vs organized)
---
### Stage 2: Categorize
**Action**: Categorize each file by function
**Categorization Rules**:
- Explains concept? → `concepts/`
- Shows working code? → `examples/`
- Step-by-step instructions? → `guides/`
- Reference data (tables, commands)? → `lookup/`
- Errors/issues? → `errors/`
**Output**: Categorization plan with flagged ambiguous files
---
### Stage 3: Resolve Conflicts (APPROVAL REQUIRED)
**Action**: Present categorization plan and handle conflicts
**Format**:
```
Organizing {category}/ (23 files, flat structure)
Clear categorization (18 files):
concepts/ (8):
✓ authentication.md → concepts/authentication.md
examples/ (5):
✓ jwt-example.md → examples/jwt-example.md
Ambiguous files (5 - need your input):
[?] api-design.md (contains concepts AND steps)
→ [A] Split: concepts/api-design.md + guides/api-design-guide.md
→ [B] Keep as concepts/api-design.md
→ [C] Keep as guides/api-design.md
Conflicts (2):
[!] authentication.md → concepts/auth.md
Target already exists (120 lines)
→ [J] Merge into existing
→ [K] Rename to concepts/authentication-v2.md
→ [L] Skip (keep flat)
Select resolutions (A J or 'auto'):
```
**Validation**: MUST wait for user input
---
### Stage 4: Preview (APPROVAL REQUIRED)
**Action**: Show preview of all changes
**Format**:
```
Preview changes:
CREATE directories:
{category}/concepts/
{category}/examples/
{category}/guides/
{category}/lookup/
{category}/errors/
MOVE files (18):
authentication.md → concepts/authentication.md
... (17 more)
SPLIT files (3):
api-design.md → concepts/api-design.md + guides/api-design-guide.md
MERGE files (2):
authentication.md → concepts/auth.md (merge content)
UPDATE:
{category}/README.md
Fix 47 internal references
Dry-run? (yes/no/show-diff):
```
**Dry-run**: Simulates changes without executing
**Validation**: MUST get approval before proceeding
---
### Stage 5: Backup
**Action**: Create backup before making changes
**Location**: `.tmp/backup/organize-{category}-{timestamp}/`
**Purpose**: Enable rollback if needed
---
### Stage 6: Execute
**Action**: Perform the reorganization
**Process**:
1. Create function folders
2. Move files to correct locations
3. Split ambiguous files if requested
4. Merge conflicts if requested
---
### Stage 7: Update
**Action**: Update navigation and fix references
**Process**:
1. Update README.md with navigation tables
2. Fix all internal references to moved files
3. Validate all links work
4. Update "Last Updated" dates
---
### Stage 8: Report
**Action**: Show comprehensive results
**Format**:
```
✅ Organized X files into function folders
📁 Created Y new folders
🔀 Split Z ambiguous files
🔗 Fixed N references
💾 Backup: .tmp/backup/organize-{category}-{timestamp}/
Rollback available if needed.
```
---
## Conflict Resolution
### Ambiguous Files
File fits multiple categories (e.g., has concepts AND steps)
**Options**:
- Split into multiple files (recommended)
- Keep in primary category
- User decides which is primary
### Duplicate Targets
Target file already exists
**Options**:
- Merge content into existing file
- Rename to avoid conflict (e.g., -v2)
- Skip (keep in flat structure)
### Auto-Resolution
Agent suggests best option based on:
- File size
- Content analysis
- Existing structure
---
## Examples
### Organize Flat Directory
```bash
/context organize development/
```
### Dry-Run First
```bash
/context organize development/ --dry-run
```
### Organize Multiple
```bash
/context organize development/
/context organize core/
```
---
## Success Criteria
- [ ] All files in function folders (not flat)?
- [ ] Ambiguous files resolved?
- [ ] Conflicts handled?
- [ ] README.md created/updated?
- [ ] All references fixed?
- [ ] Backup created?
- [ ] User approved changes?
---
## Related
- standards/structure.md - Folder organization rules
- guides/workflows.md - Interactive examples

237
.opencode/context/core/context-system/operations/update.md Normal file
View File

@@ -0,0 +1,237 @@
<!-- Context: core/update | Priority: medium | Version: 1.0 | Updated: 2026-02-15 -->
# Update Operation
**Purpose**: Update context when APIs, frameworks, or contracts change
**Last Updated**: 2026-01-06
---
## When to Use
- Framework version updates (Next.js 14 → 15)
- API changes (breaking changes, deprecations)
- New features added to existing topics
- Migration guides needed
---
## 8-Stage Workflow
### Stage 1: Identify Changes (APPROVAL REQUIRED)
**Action**: User describes what changed
**Format**:
```
What changed in {topic}?
[A] API changes
[B] Deprecations
[C] New features
[D] Breaking changes
[E] Other (describe)
Select all that apply (A B C D or describe):
```
**Follow-up**: Get specific details for each selected type
**Validation**: MUST get user input before proceeding
---
### Stage 2: Find Affected Files
**Action**: Search for files referencing the topic
**Process**:
1. Grep for topic references across all context
2. Count references per file
3. Show impact analysis
**Format**:
```
Found 5 files referencing {topic}:
📄 concepts/routing.md (3 references, 145 lines)
📄 examples/app-router-example.md (7 references, 78 lines)
📄 guides/setting-up-nextjs.md (2 references, 132 lines)
📄 errors/nextjs-errors.md (1 reference, 98 lines)
📄 lookup/nextjs-commands.md (4 references, 54 lines)
Total impact: 17 references across 5 files
```
---
### Stage 3: Preview Changes (APPROVAL REQUIRED)
**Action**: Show line-by-line diff for each file
**Format**:
```
Proposed updates:
━━━ concepts/routing.md ━━━
Line 15:
- App router is optional (use pages/ or app/)
+ App router is now default in Next.js 15 (pages/ still supported)
Line 42:
+ ## Metadata API (New in v15)
+ Next.js 15 introduces new metadata API...
━━━ examples/app-router-example.md ━━━
Line 8:
- // Optional: use app router
+ // Default in Next.js 15+
Preview next file? (yes/no/show-all)
Approve changes? (yes/no/edit):
```
**Edit mode**: Line-by-line approval for each change
**Validation**: MUST get approval before proceeding
---
### Stage 4: Backup
**Action**: Create backup before updating
**Location**: `.tmp/backup/update-{topic}-{timestamp}/`
**Purpose**: Enable rollback if updates cause issues
---
### Stage 5: Update Files
**Action**: Apply approved changes
**Process**:
1. Update concepts, examples, guides, lookups
2. Maintain MVI format (<200 lines)
3. Update "Last Updated" dates
4. Preserve file structure
**Enforcement**: `@critical_rules.mvi_strict`
---
### Stage 6: Add Migration Notes
**Action**: Add migration guide to errors/
**Format**:
```markdown
## Migration: {Old Version} → {New Version}
**Breaking Changes**:
- Change 1
- Change 2
**Migration Steps**:
1. Step 1
2. Step 2
**Reference**: [Link to changelog]
```
**Location**: `{category}/errors/{topic}-errors.md`
---
### Stage 7: Validate
**Action**: Check all references and links
**Checks**:
- All internal references still work
- No broken links
- All files still <200 lines
- MVI format maintained
---
### Stage 8: Report
**Action**: Show comprehensive results
**Format**:
```
✅ Updated X files
📝 Modified Y references
🔄 Added migration notes to errors/
💾 Backup: .tmp/backup/update-{topic}-{timestamp}/
Summary of changes:
- concepts/routing.md: 2 updates (145 → 162 lines)
- examples/app-router-example.md: 4 updates (78 → 89 lines)
- guides/setting-up-nextjs.md: 1 update (132 → 133 lines)
All files still under 200 line limit ✓
Rollback available if needed.
```
---
## Change Types
### API Changes
- Method signatures changed
- Parameters added/removed
- Return types changed
### Deprecations
- Features marked deprecated
- Replacement APIs available
- Timeline for removal
### New Features
- New capabilities added
- New APIs introduced
- New patterns available
### Breaking Changes
- Incompatible changes
- Migration required
- Old code won't work
---
## Examples
### Framework Update
```bash
/context update for Next.js 15
/context update for React 19
```
### API Changes
```bash
/context update for Stripe API v2024
/context update for OpenAI API breaking changes
```
### Library Update
```bash
/context update for Tailwind CSS v4
```
---
## Success Criteria
- [ ] User described changes?
- [ ] All affected files found?
- [ ] Diff preview shown?
- [ ] User approved changes?
- [ ] Backup created?
- [ ] Migration notes added?
- [ ] All references validated?
- [ ] All files still <200 lines?
---
## Related
- guides/workflows.md - Interactive diff examples
- standards/mvi.md - Maintain MVI format
- operations/error.md - Adding migration notes

145
.opencode/context/core/context-system/standards/codebase-references.md Normal file
View File

@@ -0,0 +1,145 @@
<!-- Context: core/codebase-references | Priority: critical | Version: 1.0 | Updated: 2026-02-15 -->
# Codebase References
**Purpose**: Link context files to actual code implementation
**Last Updated**: 2026-01-27
---
## Core Principle
<rule id="link_to_code" enforcement="critical">
ALL context files SHOULD include `📂 Codebase References` section linking to relevant code.
Use sections that apply to your context type (not all files need all sections).
</rule>
**Why**: Agents need to find actual implementation, not just read about it.
---
## Section Types (Use What's Relevant)
### Business Domain Context
```markdown
**Business Logic**: (MOST IMPORTANT for business domains)
- `src/orders/rules/validation-rules.ts` - Order validation business rules
**Implementation**:
- `src/orders/order-processor.ts` - Main order processing logic
**Models/Types**:
- `src/orders/models/order.model.ts` - Order data model
**Tests**:
- `src/orders/__tests__/processor.test.ts` - Order processing tests
**Configuration**:
- `config/orders.config.ts` - Order processing config
```
### Technical/Code Context
```markdown
**Implementation**: (MOST IMPORTANT for technical contexts)
- `src/auth/jwt-handler.ts` - JWT authentication implementation
**Examples**:
- `src/auth/examples/jwt-example.ts` - Working JWT example
**Types**:
- `src/auth/types/jwt-payload.ts` - JWT payload types
**Tests**:
- `src/auth/__tests__/jwt.test.ts` - JWT tests
```
### Standards/Quality Context
```markdown
**Validation/Enforcement**: (MOST IMPORTANT for standards)
- `scripts/validate-code-quality.ts` - Code quality validator
- `eslint.config.js` - ESLint rules
**Examples**:
- `examples/good-code.ts` - Good code example
- `examples/bad-code.ts` - Anti-pattern example
**Tests**:
- `tests/code-quality.test.ts` - Quality validation tests
```
### Operational Context
```markdown
**Scripts/Tools**: (MOST IMPORTANT for operations)
- `scripts/deploy.sh` - Deployment script
- `scripts/monitor.ts` - Monitoring setup
**Configuration**:
- `config/deployment.config.ts` - Deployment configuration
- `.github/workflows/deploy.yml` - CI/CD workflow
```
---
## Rules
<rule id="path_format" enforcement="strict">
1. Use project-relative paths (src/..., not /Users/...)
2. Use forward slashes (/)
3. Include file extension (.ts, .js, .sh)
4. Brief description (3-10 words) for each file
5. Verify files exist (warn if not found)
6. Use relevant sections only (not all files need all sections)
</rule>
---
## Examples
**Business Context**:
```markdown
## 📂 Codebase References
**Business Logic**:
- `src/payments/rules/validation-rules.ts` - Card validation rules
- `src/payments/rules/fraud-detection.ts` - Fraud detection logic
**Implementation**:
- `src/payments/payment-processor.ts` - Main payment processing
**Tests**:
- `src/payments/__tests__/processor.test.ts` - Payment tests
```
**Technical Context**:
```markdown
## 📂 Codebase References
**Implementation**:
- `src/auth/jwt-handler.ts` - JWT authentication
**Examples**:
- `examples/jwt-auth.ts` - Working example
**Tests**:
- `src/auth/__tests__/jwt.test.ts` - JWT tests
```
---
## Validation
- [ ] Has "📂 Codebase References" section?
- [ ] Most important section for context type included?
- [ ] Paths are project-relative?
- [ ] Paths include extensions?
- [ ] Each path has 3-10 word description?
---
## Related
- frontmatter.md - Frontmatter format
- templates.md - File templates
- structure.md - File organization
- templates/ - File templates with codebase references

64
.opencode/context/core/context-system/standards/frontmatter.md Normal file
View File

@@ -0,0 +1,64 @@
# Frontmatter Format
**Purpose**: HTML comment frontmatter format for all context files
**Last Updated**: 2026-01-27
---
## Format
<rule id="frontmatter_required" enforcement="strict">
ALL context files MUST start with:
```markdown
<!-- Context: {category}/{function} | Priority: {level} | Version: X.Y | Updated: YYYY-MM-DD -->
```
</rule>
---
## Components
**Category/Function**: `{category}/{function}`
- Examples: `ecommerce/concepts`, `development/examples`, `core/standards`
- Category = domain (ecommerce, payments, development)
- Function = file type (concepts, examples, guides, lookup, errors)
**Priority**: `critical` | `high` | `medium` | `low`
- critical: 80% of use cases (business logic, core concepts)
- high: 15% of use cases (common workflows, examples)
- medium: 4% of use cases (edge cases)
- low: 1% of use cases (rare scenarios)
**Version**: `X.Y` (start 1.0, increment on changes)
**Updated**: `YYYY-MM-DD` (ISO 8601, must match metadata section)
---
## Examples
```markdown
<!-- Context: ecommerce/concepts | Priority: critical | Version: 1.0 | Updated: 2026-01-27 -->
<!-- Context: payments/guides | Priority: high | Version: 1.2 | Updated: 2026-01-27 -->
<!-- Context: development/examples | Priority: medium | Version: 1.0 | Updated: 2026-01-27 -->
```
---
## Validation
- [ ] Frontmatter is first line?
- [ ] Format exact: `<!-- Context: ... -->`?
- [ ] Priority is critical|high|medium|low?
- [ ] Version is X.Y?
- [ ] Date is YYYY-MM-DD?
---
## Related
- structure.md - File organization
- templates.md - File templates
- codebase-references.md - Linking to code

151
.opencode/context/core/context-system/standards/mvi.md Normal file
View File

@@ -0,0 +1,151 @@
<!-- Context: core/mvi | Priority: critical | Version: 1.0 | Updated: 2026-02-15 -->
# MVI Principle (Minimal Viable Information)
**Purpose**: Extract only core concepts, not verbose explanations
**Last Updated**: 2026-01-06
---
## Core Idea
Extract the **minimum information** needed for an AI agent to understand and use a concept:
- Core concept (1-3 sentences)
- Key points (3-5 bullets)
- Minimal working example
- Reference link to full docs
**Goal**: Scannable in <30 seconds. Reference full docs, don't duplicate them.
---
## The Formula
```
Core Concept (1-3 sentences)
↓
Key Points (3-5 bullets)
↓
Quick Example (5-10 lines)
↓
Reference Link (full docs)
↓
Related Files (cross-refs)
```
---
## What to Extract ✅
- **Core definitions** - What it is (1-3 sentences)
- **Key properties** - Essential characteristics (3-5 bullets)
- **Minimal example** - Simplest working code (5-10 lines)
- **Common patterns** - How it's typically used (2-3 bullets)
- **Critical gotchas** - Must-know issues (1-2 bullets)
- **Reference links** - Where to learn more
---
## What to Skip ❌
- **Verbose explanations** - Link to docs instead
- **Complete API docs** - Summarize + reference
- **Implementation details** - Show minimal example + reference
- **Historical context** - Unless critical to understanding
- **Marketing content** - Just the facts
- **Duplicate information** - Say it once, reference elsewhere
---
## Example: JWT Authentication
### ❌ Too Verbose (400+ lines)
```markdown
# JWT Authentication
JSON Web Tokens (JWT) are an open standard (RFC 7519) that defines
a compact and self-contained way for securely transmitting information
between parties as a JSON object. This information can be verified and
trusted because it is digitally signed. JWTs can be signed using a
secret (with the HMAC algorithm) or a public/private key pair using RSA
or ECDSA.
[... 400 more lines of explanation, examples, edge cases ...]
```
### ✅ MVI Compliant (~50 lines)
```markdown
# Concept: JWT Authentication
**Core Idea**: Stateless authentication using JSON Web Tokens signed
with a secret key. Token contains user data (payload) that server can
trust because signature is verified.
**Key Points**:
- Token has 3 parts: header.payload.signature (Base64 encoded)
- Server verifies signature to trust payload without database lookup
- No session storage needed (stateless)
- Tokens expire (include `exp` claim)
- Store in httpOnly cookie or Authorization header
**Quick Example**:
```js
// Sign token
const token = jwt.sign(
{ userId: 123, role: 'admin' },
SECRET_KEY,
{ expiresIn: '1h' }
)
// Verify token
const decoded = jwt.verify(token, SECRET_KEY)
console.log(decoded.userId) // 123
```
**Reference**: https://jwt.io/introduction
**Related**:
- examples/jwt-auth-example.md
- guides/implementing-jwt.md
- errors/auth-errors.md
```
---
## File Size Limits
<rule id="size_limits" enforcement="strict">
- Concept files: max 100 lines
- Example files: max 80 lines
- Guide files: max 150 lines
- Lookup files: max 100 lines
- Error files: max 150 lines
- README files: max 100 lines
</rule>
**Why**: Forces brevity. If you need more, split into multiple files or reference external docs.
---
## Validation Checklist
Before creating a context file, verify:
- [ ] Core concept is 1-3 sentences?
- [ ] Key points are 3-5 bullets?
- [ ] Example is <10 lines of code?
- [ ] Reference link is included?
- [ ] File is <200 lines total?
- [ ] Can be scanned in <30 seconds?
If any answer is "no", apply more compression.
---
## Related
- structure.md - Where files go
- compact.md - How to minimize
- templates.md - Standard formats
- creation.md - File creation rules

240
.opencode/context/core/context-system/standards/structure.md Normal file
View File

@@ -0,0 +1,240 @@
<!-- Context: core/structure | Priority: critical | Version: 1.0 | Updated: 2026-02-15 -->
# Context Structure
**Purpose**: Function-based folder organization for easy discovery
**Last Updated**: 2026-01-06
---
## Core Structure
<rule id="function_structure" enforcement="strict">
ALWAYS organize by function (what info does), not just by topic.
Required folders:
- concepts/ - Core ideas, definitions, "what is it?"
- examples/ - Minimal working code
- guides/ - Step-by-step workflows
- lookup/ - Quick reference tables, commands, paths
- errors/ - Common issues, gotchas, fixes
</rule>
```
.opencode/context/{category}/
├── navigation.md # Navigation map (REQUIRED)
├── concepts/ # What it is
│ └── {topic}.md
├── examples/ # Working code
│ └── {example}.md
├── guides/ # How to do it
│ └── {guide}.md
├── lookup/ # Quick reference
│ └── {reference}.md
└── errors/ # Common issues
└── {framework}.md
```
---
## Folder Purposes
### concepts/
**Purpose**: Core ideas, definitions, "what is it?"
**Contains**:
- Fundamental concepts
- Design patterns
- Architecture decisions
- System principles
**Examples**:
- `concepts/authentication.md`
- `concepts/state-management.md`
- `concepts/mvi-principle.md`
---
### examples/
**Purpose**: Minimal working code examples
**Contains**:
- Code snippets that work as-is
- Minimal reproductions
- Common patterns in action
**Examples**:
- `examples/jwt-auth-example.md`
- `examples/react-hooks-example.md`
- `examples/api-call-example.md`
**Rule**: Examples should be <30 lines of code, fully functional
---
### guides/
**Purpose**: Step-by-step workflows, "how to do X"
**Contains**:
- Numbered procedures
- Setup instructions
- Implementation workflows
- Migration guides
**Examples**:
- `guides/setting-up-auth.md`
- `guides/deploying-api.md`
- `guides/migrating-to-v2.md`
**Rule**: Steps should be actionable (not theoretical)
---
### lookup/
**Purpose**: Quick reference tables, commands, paths
**Contains**:
- Command lists
- File locations
- API endpoints
- Configuration options
- Keyboard shortcuts
**Examples**:
- `lookup/cli-commands.md`
- `lookup/file-locations.md`
- `lookup/api-endpoints.md`
**Rule**: Must be in table/list format (scannable)
---
### errors/
**Purpose**: Common errors, gotchas, edge cases
**Contains**:
- Error messages + fixes
- Common pitfalls
- Edge cases
- Troubleshooting
**Examples**:
- `errors/react-errors.md`
- `errors/nextjs-build-errors.md`
- `errors/auth-errors.md`
**Rule**: Group by framework/topic, not one file per error
---
## navigation.md Requirement
<rule id="readme_required" enforcement="strict">
Every context category MUST have navigation.md at its root with:
1. Purpose (1-2 sentences)
2. Navigation tables for each function folder
3. Priority levels (critical/high/medium/low)
4. Loading strategy (what to load for common tasks)
</rule>
**Example**:
```markdown
# Development Context
**Purpose**: Core development patterns, errors, and examples
---
## Quick Navigation
### Concepts
| File | Description | Priority |
|------|-------------|----------|
| concepts/auth.md | Authentication patterns | critical |
### Examples
| File | Description | Priority |
|------|-------------|----------|
| examples/jwt.md | JWT auth example | high |
### Errors
| File | Description | Priority |
|------|-------------|----------|
| errors/react.md | Common React errors | high |
---
## Loading Strategy
**For auth work**:
1. Load concepts/auth.md
2. Load examples/jwt.md
3. Reference guides/setup-auth.md if needed
```
---
## Categorization Rules
When organizing a file, ask:
| Question | Folder |
|----------|--------|
| Does it explain **what** something is? | `concepts/` |
| Does it show **working code**? | `examples/` |
| Does it explain **how to do** something? | `guides/` |
| Is it **quick reference** data? | `lookup/` |
| Does it document an **error/issue**? | `errors/` |
---
## Anti-Patterns ❌
### ❌ Flat Structure
```
development/
├── authentication.md
├── jwt-example.md
├── setting-up-auth.md
├── auth-errors.md
└── api-endpoints.md
```
**Problem**: Hard to discover. Is authentication.md a concept or guide?
### ✅ Function-Based
```
development/
├── navigation.md
├── concepts/
│ └── authentication.md
├── examples/
│ └── jwt-example.md
├── guides/
│ └── setting-up-auth.md
├── lookup/
│ └── api-endpoints.md
└── errors/
└── auth-errors.md
```
**Benefit**: Instantly know file purpose by location
---
## Validation
Before committing context structure:
- [ ] All categories have navigation.md?
- [ ] Files are in function folders (not flat)?
- [ ] README has navigation tables?
- [ ] Priority levels assigned?
- [ ] Loading strategy documented?
---
## Related
- mvi-principle.md - What to extract
- templates.md - File formats
- creation.md - How to create files

396
.opencode/context/core/context-system/standards/templates.md Normal file
View File

@@ -0,0 +1,396 @@
# Context File Templates
**Purpose**: Standard formats for all context file types
**Last Updated**: 2026-01-06
---
## Template Selection
| Type | Max Lines | Required Sections |
|------|-----------|-------------------|
| Concept | 100 | Purpose, Core Idea (1-3 sentences), Key Points (3-5), Example (<10 lines), Reference, Related |
| Example | 80 | Purpose, Use Case, Code (10-30 lines), Explanation, Related |
| Guide | 150 | Purpose, Prerequisites, Steps (4-7), Verification, Related |
| Lookup | 100 | Purpose, Tables/Lists, Commands, Related |
| Error | 150 | Purpose, Per-error: Symptom, Cause, Solution, Prevention, Reference, Related |
| README | 100 | Purpose, Navigation tables (all 5 folders), Loading Strategy, Statistics |
---
## 1. Concept Template
```markdown
<!-- Context: {category}/concepts | Priority: {critical|high|medium|low} | Version: 1.0 | Updated: YYYY-MM-DD -->
# Concept: {Name}
**Purpose**: [1 sentence]
**Last Updated**: {YYYY-MM-DD}
## Core Idea
[1-3 sentences]
## Key Points
- Point 1
- Point 2
- Point 3
## When to Use
- Use case 1
- Use case 2
## Quick Example
```lang
[<10 lines]
```
## 📂 Codebase References
**Business Logic** (if business domain):
- `path/to/rules.ts` - {3-10 word description}
**Implementation**:
- `path/to/main.ts` - {3-10 word description}
**Models/Types**:
- `path/to/model.ts` - {3-10 word description}
**Tests**:
- `path/to/test.ts` - {3-10 word description}
## Deep Dive
**Reference**: [Link or "See implementation above"]
## Related
- concepts/x.md
- examples/y.md
```
---
## 2. Example Template
```markdown
<!-- Context: {category}/examples | Priority: {high|medium} | Version: 1.0 | Updated: YYYY-MM-DD -->
# Example: {What It Shows}
**Purpose**: [1 sentence]
**Last Updated**: {YYYY-MM-DD}
## Use Case
[2-3 sentences]
## Code
```lang
[10-30 lines]
```
## Explanation
1. Step 1
2. Step 2
3. Step 3
**Key points**:
- Detail 1
- Detail 2
## 📂 Codebase References
**Full Implementation**:
- `path/to/real-implementation.ts` - {Production version}
**Related Code**:
- `path/to/helper.ts` - {Helper utilities}
**Tests**:
- `path/to/test.ts` - {Tests demonstrating pattern}
## Related
- concepts/x.md
```
---
## 3. Guide Template
```markdown
<!-- Context: {category}/guides | Priority: {critical|high|medium} | Version: 1.0 | Updated: YYYY-MM-DD -->
# Guide: {Action}
**Purpose**: [1 sentence]
**Last Updated**: {YYYY-MM-DD}
## Prerequisites
- Requirement 1
- Requirement 2
**Estimated time**: X min
## Steps
### 1. {Step}
```bash
{command}
```
**Expected**: [result]
**Implementation**: `path/to/step.ts`
### 2. {Step}
[Repeat 4-7 steps]
## Verification
```bash
{verify command}
```
## 📂 Codebase References
**Workflow Orchestration**:
- `path/to/workflow.ts` - {Main workflow coordinator}
**Business Logic** (if applicable):
- `path/to/rules.ts` - {Process validation rules}
**Integration Points**:
- `path/to/api-client.ts` - {External integration}
**Tests**:
- `path/to/workflow.test.ts` - {End-to-end tests}
## Troubleshooting
| Issue | Solution |
|-------|----------|
| Problem | Fix |
## Related
- concepts/x.md
```
---
## 4. Lookup Template
```markdown
<!-- Context: {category}/lookup | Priority: {high|medium} | Version: 1.0 | Updated: YYYY-MM-DD -->
# Lookup: {Reference Type}
**Purpose**: Quick reference for {desc}
**Last Updated**: {YYYY-MM-DD}
## {Section}
| Item | Value | Desc | Code |
|------|-------|------|------|
| x | y | z | `path/to/file.ts` |
## Commands
```bash
# Description
{command}
```
## Paths
```
{path} - {desc}
```
## 📂 Codebase References
**Validation/Enforcement**:
- `path/to/validator.ts` - {Validation logic}
**Configuration**:
- `path/to/config.ts` - {Configuration settings}
**Tests**:
- `path/to/test.ts` - {Validation tests}
## Related
- concepts/x.md
```
---
## 5. Error Template
```markdown
<!-- Context: {category}/errors | Priority: {high|medium} | Version: 1.0 | Updated: YYYY-MM-DD -->
# Errors: {Framework}
**Purpose**: Common errors for {framework}
**Last Updated**: {YYYY-MM-DD}
## Error: {Name}
**Symptom**:
```
{error message}
```
**Cause**: [1-2 sentences]
**Solution**:
1. Step 1
2. Step 2
**Code**:
```lang
// ❌ Before
{bad}
// ✅ After
{fixed}
```
**Prevention**: [how to avoid]
**Frequency**: common/occasional/rare
**Code References**:
- Error thrown: `path/to/error-source.ts`
- Error handler: `path/to/error-handler.ts`
- Prevention: `path/to/validator.ts`
---
[Repeat for 5-10 errors]
## 📂 Codebase References
**Error Definitions**:
- `path/to/error-types.ts` - {Error class definitions}
**Error Handling**:
- `path/to/error-handler.ts` - {Error handler}
**Prevention Logic**:
- `path/to/validator.ts` - {Validation preventing errors}
**Tests**:
- `path/to/error-handling.test.ts` - {Error handling tests}
## Related
- concepts/x.md
```
---
## 6. Navigation Template (Replaces README.md)
**Note**: Use `navigation.md` instead of `README.md` for better discoverability
**Target**: 200-300 tokens
```markdown
# {Category} Navigation
**Purpose**: [1 sentence]
---
## Structure
```
{category}/
├── navigation.md
├── {subcategory}/
│ ├── navigation.md
│ └── {files}.md
```
---
## Quick Routes
| Task | Path |
|------|------|
| **{Task 1}** | `{path}` |
| **{Task 2}** | `{path}` |
| **{Task 3}** | `{path}` |
---
## By {Concern/Type}
**{Section 1}** → {description}
**{Section 2}** → {description}
**{Section 3}** → {description}
---
## Related Context
- **{Category}** → `../{category}/navigation.md`
```
---
## 7. Specialized Navigation Template
**Use for**: Cross-cutting concerns (e.g., `ui-navigation.md`)
**Target**: 250-300 tokens
```markdown
# {Domain} Navigation
**Scope**: [What this covers]
---
## Structure
```
{Relevant directories across multiple categories}
```
---
## Quick Routes
| Task | Path |
|------|------|
| **{Task 1}** | `{path}` |
| **{Task 2}** | `{path}` |
---
## By {Framework/Approach}
**{Tech 1}** → `{path}`
**{Tech 2}** → `{path}`
---
## Common Workflows
**{Workflow 1}**:
1. `{file1}` ({purpose})
2. `{file2}` ({purpose})
```
---
## All Templates Must Have
1. Title with type prefix (# Concept:, # Example:, etc.)
2. **Purpose** (1 sentence)
3. **Last Updated** (YYYY-MM-DD)
4. **Related** section (cross-references)
---
## Validation
- [ ] Correct template for file type?
- [ ] Has required sections?
- [ ] Under max line limit?
- [ ] Cross-references added?
- [ ] Added to README.md?
---
## Related
- creation.md - When to use each template
- mvi-principle.md - How to fill templates
- compact.md - How to stay under limits

210
.opencode/context/core/essential-patterns.md Normal file
View File

@@ -0,0 +1,210 @@
<!-- Context: core/essential-patterns | Priority: critical | Version: 1.0 | Updated: 2026-02-15 -->
# Essential Patterns - Core Development Guidelines
## Quick Reference
**Core Philosophy**: Modular, Functional, Maintainable
**Critical Patterns**: Error Handling, Validation, Security, Logging, Pure Functions
**ALWAYS**: Handle errors gracefully, validate input, use env vars for secrets, write pure functions
**NEVER**: Expose sensitive info, hardcode credentials, skip input validation, mutate state
**Language-agnostic**: Apply to all programming languages
---
## Overview
This file provides essential development patterns that apply across all programming languages. For detailed standards, see:
- `standards/code-quality.md` - Modular, functional code patterns
- `standards/security-patterns.md` - Language-agnostic patterns
- `standards/test-coverage.md` - Testing standards
- `standards/documentation.md` - Documentation standards
- `standards/code-analysis.md` - Analysis framework
---
## Core Philosophy
**Modular**: Everything is a component - small, focused, reusable
**Functional**: Pure functions, immutability, composition over inheritance
**Maintainable**: Self-documenting, testable, predictable
---
## Critical Patterns
### 1. Pure Functions
**ALWAYS** write pure functions:
- Same input = same output
- No side effects
- No mutation of external state
- Predictable and testable
### 2. Error Handling
**ALWAYS** handle errors gracefully:
- Catch specific errors, not generic ones
- Log errors with context
- Return meaningful error messages
- Don't expose internal implementation details
- Use language-specific error handling mechanisms (try/catch, Result, error returns)
### 3. Input Validation
**ALWAYS** validate input data:
- Check for null/nil/None values
- Validate data types
- Validate data ranges and constraints
- Sanitize user input
- Return clear validation error messages
### 4. Security
**NEVER** expose sensitive information:
- Don't log passwords, tokens, or API keys
- Use environment variables for secrets
- Sanitize all user input
- Use parameterized queries (prevent SQL injection)
- Validate and escape output (prevent XSS)
### 5. Logging
**USE** consistent logging levels:
- **Debug**: Detailed information for debugging (development only)
- **Info**: Important events and milestones
- **Warning**: Potential issues that don't stop execution
- **Error**: Failures and exceptions
---
## Code Structure Patterns
### 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
```
---
## Anti-Patterns to Avoid
**Code Smells**:
- ❌ Mutation and side effects
- ❌ Deep nesting (> 3 levels)
- ❌ God modules (> 200 lines)
- ❌ Global state
- ❌ Large functions (> 50 lines)
- ❌ Hardcoded values
- ❌ Tight coupling
**Security Issues**:
- ❌ Hardcoded credentials
- ❌ Exposed sensitive data in logs
- ❌ Unvalidated user input
- ❌ SQL injection vulnerabilities
- ❌ XSS vulnerabilities
---
## Testing Patterns
**ALWAYS** write tests:
- Unit tests for pure functions
- Integration tests for components
- Test edge cases and error conditions
- Aim for > 80% coverage
- Use descriptive test names
**Test Structure**:
```
describe('Component', () => {
it('should handle valid input', () => {
// Arrange
const input = validData;
// Act
const result = component(input);
// Assert
expect(result).toBe(expected);
});
it('should handle invalid input', () => {
// Test error cases
});
});
```
---
## Documentation Patterns
**ALWAYS** document:
- Public APIs and interfaces
- Complex logic and algorithms
- Non-obvious decisions
- Usage examples
**Use clear, concise language**:
- Explain WHY, not just WHAT
- Include examples
- Keep it up to date
- Use consistent formatting
---
## Language-Specific Implementations
These patterns are language-agnostic. For language-specific implementations:
**TypeScript/JavaScript**: See project context for Next.js, React, Node.js patterns
**Python**: See project context for FastAPI, Django patterns
**Go**: See project context for Go-specific patterns
**Rust**: See project context for Rust-specific patterns
---
## Quick Checklist
Before committing code, verify:
- ✅ Pure functions (no side effects)
- ✅ Input validation
- ✅ Error handling
- ✅ No hardcoded secrets
- ✅ Tests written and passing
- ✅ Documentation updated
- ✅ No security vulnerabilities
- ✅ Code is modular and maintainable
---
## Additional Resources
For more detailed guidelines, see:
- `standards/code-quality.md` - Comprehensive code standards
- `standards/security-patterns.md` - Detailed pattern catalog
- `standards/test-coverage.md` - Testing best practices
- `standards/documentation.md` - Documentation guidelines
- `standards/code-analysis.md` - Code analysis framework
- `workflows/code-review.md` - Code review process

93
.opencode/context/core/navigation.md Normal file
View File

@@ -0,0 +1,93 @@
<!-- Context: core/navigation | Priority: critical | Version: 1.0 | Updated: 2026-02-15 -->
# Core Context Navigation
**Purpose**: Universal standards and workflows for all development
---
## Structure
```
core/
├── navigation.md
├── context-system.md
├── essential-patterns.md
│
├── standards/
│ ├── navigation.md
│ ├── code-quality.md
│ ├── test-coverage.md
│ ├── documentation.md
│ ├── security-patterns.md
│ └── code-analysis.md
│
├── workflows/
│ ├── navigation.md
│ ├── code-review.md
│ ├── task-delegation-basics.md
│ ├── feature-breakdown.md
│ ├── session-management.md
│ └── design-iteration-overview.md
│
├── guides/
│ ├── navigation.md
│ └── resuming-sessions.md
│
├── task-management/
│ ├── navigation.md
│ ├── standards/
│ │ └── navigation.md
│ ├── guides/
│ │ └── navigation.md
│ └── lookup/
│ └── navigation.md
│
├── system/
│ └── context-guide.md
│
└── context-system/
├── navigation.md
├── examples/
│ └── navigation.md
├── guides/
│ └── navigation.md
├── operations/
│ └── navigation.md
└── standards/
└── navigation.md
```
---
## Quick Routes
| Task | Path |
|------|------|
| **Write code** | `standards/code-quality.md` |
| **Write tests** | `standards/test-coverage.md` |
| **Write docs** | `standards/documentation.md` |
| **Security patterns** | `standards/security-patterns.md` |
| **Review code** | `workflows/code-review.md` |
| **Delegate task** | `workflows/task-delegation-basics.md` |
| **Break down feature** | `workflows/feature-breakdown.md` |
| **Resume session** | `guides/resuming-sessions.md` |
| **Manage tasks** | `task-management/navigation.md` |
| **Task CLI commands** | `task-management/lookup/task-commands.md` |
| **Context system** | `context-system.md` |
---
## By Type
**Standards** → Code quality, testing, docs, security (critical priority)
**Workflows** → Review, delegation, task breakdown (high priority)
**Task Management** → JSON-driven task tracking with CLI (high priority)
**System** → Context management and guides (medium priority)
---
## Related Context
- **Development** → `../development/navigation.md`
- **OpenAgents Control Repo** → `../openagents-repo/navigation.md`

152
.opencode/context/core/standards/code-analysis.md Normal file
View File

@@ -0,0 +1,152 @@
<!-- Context: standards/analysis | Priority: high | Version: 2.0 | Updated: 2025-01-21 -->
# 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

164
.opencode/context/core/standards/code-quality.md Normal file
View File

@@ -0,0 +1,164 @@
<!-- Context: standards/code | Priority: critical | Version: 2.0 | Updated: 2025-01-21 -->
# 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.

150
.opencode/context/core/standards/documentation.md Normal file
View File

@@ -0,0 +1,150 @@
<!-- Context: standards/docs | Priority: critical | Version: 2.0 | Updated: 2025-01-21 -->
# 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
bun --bun 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.

66
.opencode/context/core/standards/navigation.md Normal file
View File

@@ -0,0 +1,66 @@
<!-- Context: core/navigation | Priority: critical | Version: 1.0 | Updated: 2026-02-15 -->
# Core Standards Navigation
**Purpose**: Universal standards for all development work
---
## Files
| File | Topic | Priority | Load When |
|------|-------|----------|-----------|
| `code-quality.md` | Code quality rules | ⭐⭐⭐⭐⭐ | Writing/reviewing code |
| `test-coverage.md` | Testing standards | ⭐⭐⭐⭐⭐ | Writing tests |
| `documentation.md` | Documentation rules | ⭐⭐⭐⭐ | Writing docs |
| `security-patterns.md` | Security best practices | ⭐⭐⭐⭐ | Security review, patterns |
| `project-intelligence.md` | What and why | ⭐⭐⭐⭐ | Onboarding, understanding projects |
| `project-intelligence-management.md` | How to manage | ⭐⭐⭐ | Managing intelligence files |
| `code-analysis.md` | Analysis approaches | ⭐⭐⭐ | Analyzing code, debugging |
| `typescript.md` | Universal TypeScript patterns | ⭐⭐⭐⭐ | Writing/reviewing TypeScript code |
| `csharp.md` | Universal C# / .NET patterns | ⭐⭐⭐⭐ | Writing/reviewing C# code |
| `csharp-project-structure.md` | ASP.NET Core project structure (Minimal APIs, CQRS, EF Core + PostgreSQL) | ⭐⭐⭐⭐ | Starting or structuring a C# API project |
---
## Loading Strategy
**For code implementation**:
1. Load `code-quality.md` (critical)
2. Load `security-patterns.md` (high)
**For TypeScript code**:
1. Load `typescript.md` (critical)
2. Load `code-quality.md` (high)
**For C# / .NET code**:
1. Load `csharp.md` (critical)
2. Load `code-quality.md` (high)
**For C# API project structure**:
1. Load `csharp-project-structure.md` (critical)
2. Load `csharp.md` (high)
**For testing**:
1. Load `test-coverage.md` (critical)
2. Depends on: `code-quality.md`
**For documentation**:
1. Load `documentation.md` (critical)
**For code review**:
1. Load `code-quality.md` (critical)
2. Load `security-patterns.md` (high)
3. Load `test-coverage.md` (high)
**For project onboarding/understanding**:
1. Load `project-intelligence.md` (high)
2. Then load: `../../project-intelligence/` folder for full project context
---
## Related
- **Workflows** → `../workflows/navigation.md`
- **Development Principles** → `../../development/principles/`
- **Project Intelligence** → `../../project-intelligence/navigation.md` (full project context)

249
.opencode/context/core/standards/project-intelligence-management.md Normal file
View File

@@ -0,0 +1,249 @@
<!-- Context: standards/intelligence-mgmt | Priority: high | Version: 1.0 | Updated: 2025-01-12 -->
# Project Intelligence Management
> **What**: How to manage project intelligence files and folders.
> **When**: Use this guide when adding, updating, or removing intelligence files.
> **Related**: See `project-intelligence.md` for what and why.
## Quick Reference
| Action | Do This |
|--------|---------|
| Update existing file | Edit + bump frontmatter version |
| Add new file | Create `.md` + add to navigation.md |
| Add subfolder | Create folder + `navigation.md` + update parent nav |
| Remove file | Rename `.deprecated.md` + archive, don't delete |
---
## Update Existing Files
**When**:
- Business changes → Update `business-domain.md`
- New decision → Add to `decisions-log.md`
- New issues → Update `living-notes.md`
- Feature launch → Update `business-tech-bridge.md`
- Stack changes → Update `technical-domain.md`
**Process**:
1. Edit the file
2. Update frontmatter:
```html
<!-- Context: {category} | Priority: {level} | Version: {X.Y} | Updated: {YYYY-MM-DD} -->
```
3. Keep under 200 lines
4. Commit with message like: `docs: Update business-domain.md with new market focus`
---
## Add New Files
**When**:
- New domain area needs dedicated docs
- Existing file exceeds 200 lines
- Specialized context requires separation
**Naming**:
- Kebab-case: `user-research.md`, `api-docs.md`
- Descriptive: filename tells you what's inside
**Template**:
```html
<!-- Context: project-intelligence/{filename} | Priority: {high|medium} | Version: 1.0 | Updated: {YYYY-MM-DD} -->
# File Title
> One-line purpose statement
## Quick Reference
- **Purpose**: [What this covers]
- **Update When**: [Triggers]
- **Related Files**: [Links]
## Content
[Follow patterns from existing files]
## Related Files
- [File 1] - [Description]
```
**Process**:
1. Create file in `project-intelligence/`
2. Add frontmatter with `project-intelligence/{filename}`
3. Follow existing file patterns
4. Keep under 200 lines
5. Add to `navigation.md`
---
## Create Subfolders
**When**:
- 5+ related files need grouping
- Subdomain warrants separation (e.g., `api/`, `mobile/`, `integrations/`)
- Improves navigation clarity
**Structure**:
```
project-intelligence/
├── navigation.md # Root nav
├── [new-subfolder]/ # Create this
│ ├── navigation.md # Subfolder nav required
│ ├── file-1.md
│ └── file-2.md
```
**Process**:
1. Create folder: `mkdir project-intelligence/{name}/`
2. Create `navigation.md` inside:
```html
<!-- Context: project-intelligence/{name}/nav | Priority: medium | Version: 1.0 | Updated: {YYYY-MM-DD} -->
# {Name} Navigation
> Quick overview
## Files
| File | Purpose |
|------|---------|
| `file-1.md` | [Desc] |
```
3. Add content files
4. Update root `navigation.md` with subfolder entry
**Rule**: Every subfolder MUST have `navigation.md`. Avoid nesting deeper than 2 levels (e.g., `project-intelligence/domain/subdomain/`) to prevent context fragmentation.
---
## Remove/Deprecate Files
**When**:
- Content moved elsewhere
- File no longer relevant
- Merged with another file
**Process**:
1. Rename: `filename.md` → `filename.deprecated.md`
2. Add frontmatter:
```html
<!-- DEPRECATED: {YYYY-MM-DD} - {Reason} -->
<!-- REPLACED BY: {new-file.md} -->
```
3. Add banner at top:
> ⚠️ **DEPRECATED**: See `new-file.md` for current info
4. Mark as deprecated in `navigation.md`
**Never Delete**:
- Decision history (archive instead)
- Lessons learned (move to `living-notes.md`)
- Context that might be needed later
---
## Version Tracking
**Frontmatter**:
```html
<!-- Context: {category} | Priority: {level} | Version: {MAJOR.MINOR} | Updated: {YYYY-MM-DD} -->
```
**Version Rules**:
| Change | Version |
|--------|---------|
| New file | 1.0 |
| Content addition/update | MINOR |
| Structure change | MAJOR |
| Typo fix | PATCH |
**Date**: Always `YYYY-MM-DD`
---
## Quality Standards
**Line Limits**:
- Files: <200 lines
- Sections: 3-7 per file
**Required Elements**:
- Frontmatter with all fields
- Quick Reference section
- Related files section
**Anti-Patterns**:
❌ Mix concerns in one file
❌ Exceed 200 lines
❌ Delete files (archive instead)
❌ Skip frontmatter
❌ Duplicate information
✅ Keep focused and scannable
✅ Archive deprecated content
✅ Use frontmatter consistently
✅ Link to related files
---
## Governance
**Ownership**:
| Area | Owner | Responsibility |
|------|-------|----------------|
| Business domain | Product Owner | Keep current, accurate |
| Technical domain | Tech Lead | Keep current, accurate |
| Decisions log | Tech Lead | Document decisions |
| Living notes | Team | Keep active items current |
**Review Cadence**:
| Activity | Frequency |
|----------|-----------|
| Quick review | Per PR |
| Full review | Quarterly |
| Archive review | Semi-annually |
---
## Checklist
### Add New Intelligence File
- [ ] Follow naming convention
- [ ] Add complete frontmatter
- [ ] Include Quick Reference
- [ ] Keep under 200 lines
- [ ] Add to navigation.md
- [ ] Link from related files
- [ ] Version: 1.0
### Update Existing File
- [ ] Make targeted changes
- [ ] Update version/date in frontmatter
- [ ] Verify <200 lines
- [ ] Update navigation if needed
- [ ] Update related files
### Create Subfolder
- [ ] Verify warranted (5+ files)
- [ ] Create folder with kebab-case name
- [ ] Create `navigation.md` inside
- [ ] Add subfolder to parent navigation
- [ ] Create content files
### Deprecate File
- [ ] Rename with `.deprecated.md`
- [ ] Add deprecation frontmatter
- [ ] Add deprecation banner
- [ ] Mark deprecated in navigation
- [ ] Document replacement
---
## Related Files
- **Standard**: `project-intelligence.md`
- **Project Intelligence**: `../../project-intelligence/navigation.md`
- **Context System**: `../context-system.md`

77
.opencode/context/core/standards/project-intelligence.md Normal file
View File

@@ -0,0 +1,77 @@
<!-- Context: standards/intelligence | Priority: high | Version: 1.0 | Updated: 2025-01-12 -->
# Project Intelligence
> **What**: Living documentation that bridges business domain and technical implementation.
> **Why**: Quick project understanding and onboarding for developers, agents, and stakeholders.
> **Where**: `.opencode/context/project-intelligence/` (dedicated folder)
## Quick Reference
| What You Need | File | Description |
|---------------|------|-------------|
| Understand the "why" | `business-domain.md` | Problem, users, value |
| Understand the "how" | `technical-domain.md` | Stack, architecture |
| See the connection | `business-tech-bridge.md` | Business → technical mapping |
| Know the context | `decisions-log.md` | Why decisions were made |
| Current state | `living-notes.md` | Active issues, debt, questions |
## Why This Exists
Projects fail when:
- Business intent is lost in code
- Technical decisions aren't documented with context
- New members spend weeks instead of hours understanding the project
- Context lives only in people's heads (who leave)
This ensures **business and technical domains speak the same language**.
## Structure
```
.opencode/context/
├── project-intelligence/ # Project-specific context
│ ├── navigation.md # Quick overview & routes
│ ├── business-domain.md # Business context, problems solved
│ ├── technical-domain.md # Stack, architecture, decisions
│ ├── business-tech-bridge.md # How business needs → solutions
│ ├── decisions-log.md # Decisions with rationale
│ └── living-notes.md # Active issues, technical debt
└── core/ # Universal standards
```
## Onboarding Checklist
For new team members or agents:
- [ ] Read `navigation.md` (this file)
- [ ] Read `business-domain.md` to understand the "why"
- [ ] Read `technical-domain.md` to understand the "how"
- [ ] Review `business-tech-bridge.md` to see the connection
- [ ] Check `decisions-log.md` for context on key choices
- [ ] Review `living-notes.md` for current state
- [ ] Explore codebase with this context loaded
## How to Keep This Alive
| Trigger | Action |
|---------|--------|
| Business direction shifts | Update `business-domain.md` |
| New technical decision | Add to `decisions-log.md` |
| New issues or debt | Update `living-notes.md` |
| Feature launch | Update `business-tech-bridge.md` |
| Stack changes | Update `technical-domain.md` |
**Full Management Guide**: See `.opencode/context/core/standards/project-intelligence-management.md`
## Integration with Context System
- **Lazy Loading**: Load project intelligence first when joining a project
- **Layering**: Then load standards and specific context as needed
- **Reference**: See `.opencode/context/core/context-system.md` for system overview
## Related Files
- **Management Guide**: `.opencode/context/core/standards/project-intelligence-management.md`
- **Context System**: `.opencode/context/core/context-system.md`
- **Standards Index**: `.opencode/context/core/standards/navigation.md`

149
.opencode/context/core/standards/security-patterns.md Normal file
View File

@@ -0,0 +1,149 @@
<!-- Context: standards/patterns | Priority: high | Version: 2.0 | Updated: 2025-01-21 -->
# 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
**ALWAYS** handle errors gracefully:
- Catch specific errors, not generic ones
- Log errors with context
- Return meaningful error messages
- Don't expose internal implementation details
- Use language-specific error handling mechanisms (try/catch, Result, error returns)
## Validation Pattern
**ALWAYS** validate input data:
- Check for null/nil/None values
- Validate data types
- Validate data ranges and constraints
- Sanitize user input
- Return clear validation error messages
## Logging Pattern
**USE** consistent logging levels:
- **Debug**: Detailed information for debugging (development only)
- **Info**: Important events and milestones
- **Warning**: Potential issues that don't stop execution
- **Error**: Failures and exceptions
## Security Pattern
**NEVER** expose sensitive information:
- Don't log passwords, tokens, or API keys
- Don't expose internal error details to users
- Validate and sanitize all user input
- Use environment variables for secrets
- Follow principle of least privilege
## File System Safety Pattern
**ALWAYS** validate file paths:
- Prevent path traversal attacks
- Check file permissions before operations
- Use absolute paths when possible
- Handle file not found errors gracefully
- Close file handles properly
## Configuration Pattern
**ALWAYS** use environment variables for configuration:
- Never hardcode secrets or credentials
- Provide sensible defaults
- Validate required configuration on startup
- Document all configuration options
- Use different configs for dev/staging/production
## Testing Pattern
**ALWAYS** write testable code:
- Use dependency injection
- Keep functions pure when possible
- Write unit tests for business logic
- Write integration tests for external dependencies
- Use test fixtures and mocks appropriately
## Documentation Pattern
**DOCUMENT** complex logic and public APIs:
- Explain the "why", not just the "what"
- Document function parameters and return values
- Include usage examples
- Keep documentation up to date with code
- Use language-specific documentation tools
## Performance Pattern
**AVOID** unnecessary operations:
- Don't repeat expensive calculations
- Cache results when appropriate
- Use efficient data structures
- Profile before optimizing
- Consider time and space complexity
## Code Organization Pattern
**KEEP** code modular and focused:
- Single Responsibility Principle - one function, one purpose
- Don't Repeat Yourself (DRY)
- Separate concerns (business logic, data access, presentation)
- Use meaningful names for functions and variables
- Keep functions small and focused (< 50 lines ideally)
## Dependency Management
**MANAGE** dependencies carefully:
- Pin dependency versions for reproducibility
- Regularly update dependencies for security
- Minimize number of dependencies
- Audit dependencies for security vulnerabilities
- Document why each dependency is needed
## Version Control
**FOLLOW** git best practices:
- Write clear, descriptive commit messages
- Make atomic commits (one logical change per commit)
- Use feature branches for development
- Review code before merging
- Keep main/master branch stable
## Code Review Checklist
**REVIEW** for these common issues:
- Error handling is comprehensive
- Input validation is present
- No hardcoded secrets or credentials
- Tests cover new functionality
- Documentation is updated
- Code follows project conventions
- No obvious security vulnerabilities
- Performance considerations addressed

127
.opencode/context/core/standards/test-coverage.md Normal file
View File

@@ -0,0 +1,127 @@
<!-- Context: standards/tests | Priority: critical | Version: 2.0 | Updated: 2025-01-21 -->
# 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.

192
.opencode/context/core/system/context-guide.md Normal file
View File

@@ -0,0 +1,192 @@
<!-- Context: core/context-guide | Priority: low | Version: 1.0 | Updated: 2026-02-15 -->
# Context System Guide
## Quick Reference
**Golden Rule**: Fetch context when needed, not before (lazy loading)
**Key Principle**: Use context index for discovery, load specific files as needed
**Index Location**: `.opencode/context/navigation.md` - Quick map of all contexts
**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 the index system for efficient discovery and lazy loading to keep prompts lean.
## Context Index System
**Central Index**: `.opencode/context/navigation.md` - Ultra-compact map of all contexts
The index provides:
- Quick map for common tasks (code, docs, tests, review, delegation)
- Triggers/keywords for each context
- Dependencies between contexts
- Priority levels (critical, high, medium)
### Available Context Files
All files are in `.opencode/context/core/` with organized subfolders:
### Standards (Quality Guidelines + Analysis)
- `standards/code-quality.md` - Modular, functional code principles [critical]
- `standards/documentation.md` - Documentation standards [critical]
- `standards/test-coverage.md` - Testing standards [critical]
- `standards/security-patterns.md` - Core patterns (error handling, security) [high]
- `standards/code-analysis.md` - Analysis framework [high]
### Workflows (Process Templates + Review)
- `workflows/task-delegation-basics.md` - Delegation template [high]
- `workflows/feature-breakdown.md` - Complex task breakdown [high]
- `workflows/session-management.md` - Session lifecycle [medium]
- `workflows/code-review.md` - Code review guidelines [high]
## How to Use the Index
**Step 1: Check Quick Map** (for common tasks)
- Code task? → Load `standards/code-quality.md`
- Docs task? → Load `standards/documentation.md`
- Review task? → Load `workflows/code-review.md`
**Step 2: Load Index** (for keyword matching)
- Load `.opencode/context/navigation.md`
- Scan triggers to find relevant contexts
- Load specific context files as needed
**Step 3: Load Dependencies**
- Check `deps:` in index
- Load dependent contexts for complete guidelines
**Benefits:**
- No prompt bloat (index is only ~120 tokens)
- Fetch only what's relevant
- Faster for simple tasks
- Clear dependency tracking
## When to Use Each File
### .opencode/context/core/standards/code-quality.md
- Writing new code
- Modifying existing code
- Following modular/functional patterns
- Making architectural decisions
### .opencode/context/core/standards/documentation.md
- Writing README files
- Creating API documentation
- Adding code comments
### .opencode/context/core/standards/test-coverage.md
- Writing new tests
- Running test suites
- Debugging test failures
### .opencode/context/core/standards/security-patterns.md
- Error handling
- Security patterns
- Common code patterns
### .opencode/context/core/standards/code-analysis.md
- Analyzing codebase patterns
- Investigating bugs
- Evaluating architecture
### .opencode/context/core/workflows/task-delegation-basics.md
- Delegating to general agent
- Creating task context
- Multi-file coordination
### .opencode/context/core/workflows/feature-breakdown.md
- Tasks with 4+ files
- Estimated effort >60 minutes
- Complex dependencies
### .opencode/context/core/workflows/session-management.md
- Session lifecycle
- Cleanup procedures
- Session isolation
### .opencode/context/core/workflows/code-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-quality.md
- .opencode/context/core/standards/test-coverage.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 index for context discovery
✅ Load only relevant context files
✅ Check dependencies in index
✅ 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.

85
.opencode/context/core/system/context-paths.md Normal file
View File

@@ -0,0 +1,85 @@
<!-- Context: core/context-paths | Priority: low | Version: 1.0 | Updated: 2026-02-15 -->
---
id: context-paths
name: Context File Path Resolution
---
# Context File Path Resolution
## Resolution Order
Context files are resolved in this order (later sources override earlier ones for conflicting keys):
1. **Global context** (`~/.config/opencode/context/`) — user-wide defaults
2. **Local context** (`.opencode/context/` in project root) — project-specific, highest priority
This mirrors OpenCode's own config merging behavior (see [OpenCode Config Docs](https://opencode.ai/docs/config/)).
## What Goes Where
| Content Type | Recommended Location | Why |
|---|---|---|
| **Project Intelligence** (tech stack, patterns, naming) | Local `.opencode/context/project-intelligence/` | Project-specific, committed to git, shared with team |
| **Core Standards** (code-quality, docs, tests) | Wherever OAC was installed | Universal standards, same across projects |
| **Personal Defaults** (your preferred patterns) | Global `~/.config/opencode/context/project-intelligence/` | Personal coding style across all projects |
## How Merging Works
- If a file exists in **both** local and global, the **local version wins**
- If a file exists **only** in global, it's still loaded (acts as a fallback)
- If a file exists **only** in local, it's loaded normally
**Example**: User installs OAC globally (core standards at `~/.config/opencode/context/core/`), then runs `/add-context` in a project (creates `.opencode/context/project-intelligence/` locally). The agent loads both: core standards from global, project intelligence from local.
## Path Configuration
```json
{
"paths": {
"local": ".opencode/context",
"global": "~/.config/opencode/context"
}
}
```
Set `"global": false` to disable global context loading.
## Environment Variable Override
The installer supports `OPENCODE_INSTALL_DIR` to override the install location:
```bash
export OPENCODE_INSTALL_DIR=~/custom/path
bash install.sh developer
```
OpenCode itself supports `OPENCODE_CONFIG_DIR` for a custom config directory (see [OpenCode docs](https://opencode.ai/docs/config/)). If set, context files in that directory are loaded alongside global and local configs.
## Migrating Global to Local
If you installed globally but want project-specific context:
```bash
/context migrate
```
This copies `project-intelligence/` from global (`~/.config/opencode/context/`) to local (`.opencode/context/`), so your project patterns are committed to git and shared with your team. See `/context migrate` for details.
## Common Scenarios
### Scenario 1: Everything Local (Development / Repo Maintainer)
- OAC installed locally via `bash install.sh developer`
- All context in `.opencode/context/`
- Committed to git, team shares everything
### Scenario 2: Global Install + Local Project Intelligence
- OAC installed globally via `bash install.sh developer --install-dir ~/.config/opencode`
- Core standards at `~/.config/opencode/context/core/`
- Run `/add-context` in project → creates `.opencode/context/project-intelligence/` locally
- Project intelligence committed to git, core standards come from global
### Scenario 3: Global Personal Defaults
- Run `/add-context --global` to save personal coding patterns
- These apply to ALL projects as fallback
- Any project can override with local `/add-context`

40
.opencode/context/core/system/navigation.md Normal file
View File

@@ -0,0 +1,40 @@
<!-- Context: core/navigation | Priority: critical | Version: 1.0 | Updated: 2026-02-15 -->
# Core System
**Purpose**: System guides and paths for core operations
---
## Structure
```
core/system/
├── navigation.md (this file)
└── [system guides and paths]
```
---
## Quick Routes
| Task | Path |
|------|------|
| **System guides** | `./` |
| **Core standards** | `../standards/navigation.md` |
| **Context system** | `../context-system/navigation.md` |
---
## By Type
**System Guides** → Operational guides for core systems
**Paths** → System paths and directory structures
---
## Related Context
- **Core Navigation** → `../navigation.md`
- **Context System** → `../context-system/navigation.md`
- **Core Standards** → `../standards/navigation.md`

129
.opencode/context/core/task-management/guides/managing-tasks.md Normal file
View File

@@ -0,0 +1,129 @@
<!-- Context: core/managing-tasks | Priority: high | Version: 1.0 | Updated: 2026-02-15 -->
# Guide: Managing Task Lifecycle
**Purpose**: Step-by-step workflow for JSON-driven task management
**Last Updated**: 2026-01-11
---
## Prerequisites
- TaskManager agent available
- Feature folder created in `.tmp/tasks/` (at project root)
---
## Workflow Overview
```
1. Initiation → TaskManager creates task.json + subtasks
2. Selection → Find eligible tasks (deps satisfied)
3. Execution → Working agent implements task
4. Verification → TaskManager validates completion
5. Archiving → Move to completed/ when done
```
---
## 1. Initiation (TaskManager)
Create feature folder and files:
```
.tmp/tasks/{feature-slug}/
├── task.json
├── subtask_01.json
├── subtask_02.json
└── subtask_03.json
```
Validate with: `task-cli.ts validate {feature}`
---
## 2. Task Selection
Find eligible tasks using CLI:
```bash
task-cli.ts next {feature} # All ready tasks
task-cli.ts parallel {feature} # Parallelizable only
```
Selection criteria:
- `status == "pending"`
- All `depends_on` tasks have `status == "completed"`
---
## 3. Execution (Working Agent)
When picking up task:
1. Read subtask JSON
2. Update status:
```json
{
"status": "in_progress",
"agent_id": "coder-agent",
"started_at": "2026-01-11T14:30:00Z"
}
```
3. Load `context_files` (lazy)
4. Implement `deliverables`
5. Add `completion_summary` (max 200 chars)
---
## 4. Verification (TaskManager)
After agent signals completion:
1. Check each `acceptance_criteria`
2. If all pass → Mark completed:
```bash
task-cli.ts complete {feature} {seq} "summary"
```
3. If fail → Keep in_progress, report failures
---
## 5. Archiving
When `completed_count == subtask_count`:
1. Update task.json: `status: "completed"`
2. Move folder: `.tmp/tasks/{slug}/` → `.tmp/tasks/completed/{slug}/`
---
## Status Ownership
| Status | Who Sets | When |
|--------|----------|------|
| pending | TaskManager | Initial creation |
| in_progress | Working agent | Picks up task |
| completed | TaskManager | After verification |
| blocked | Either | Dependency/issue found |
---
## CLI Commands Summary
| Command | Use Case |
|---------|----------|
| `status` | Quick overview |
| `next` | What to work on |
| `parallel` | Batch parallel work |
| `deps` | Understand blockers |
| `blocked` | Identify issues |
| `complete` | Mark task done |
| `validate` | Health check |
---
## Related
- `../standards/task-schema.md` - JSON field reference
- `splitting-tasks.md` - How to create subtasks
- `../lookup/task-commands.md` - Full CLI reference

115
.opencode/context/core/task-management/guides/splitting-tasks.md Normal file
View File

@@ -0,0 +1,115 @@
<!-- Context: core/splitting-tasks | Priority: high | Version: 1.0 | Updated: 2026-02-15 -->
# Guide: Splitting Features into Tasks
**Purpose**: How to decompose features into atomic subtasks
**Last Updated**: 2026-01-11
---
## Prerequisites
- Feature request understood
- Context bundle loaded (project standards, patterns)
---
## Steps
### 1. Identify Atomic Boundaries
Break feature into tasks that are:
- Completable in 1-2 hours
- Have single, clear outcome
- Testable independently
- Don't overlap with other tasks
**Bad**: "Implement authentication" (too big)
**Good**: "Create password hashing utility" (atomic)
---
### 2. Map Dependencies
For each task, ask:
- What must exist before this can start?
- What files/APIs does this need?
```
01 → no deps (can start immediately)
02 → depends_on: ["01"]
03 → depends_on: ["01", "02"]
```
---
### 3. Identify Parallel Tasks
Mark `parallel: true` when:
- Task doesn't modify shared files
- Task doesn't depend on runtime state from other tasks
- Multiple agents could work simultaneously
Example parallel tasks:
- Writing independent unit tests
- Creating isolated utility functions
- Documentation for separate features
---
### 4. Define Acceptance Criteria
Binary pass/fail conditions only:
- "JWT tokens signed with RS256" ✓
- "Tests pass" ✓
- "Code is clean" ✗ (subjective)
---
### 5. Specify Deliverables
Concrete files/endpoints:
- `src/auth/hash.ts`
- `POST /api/login`
- `tests/auth.test.ts`
---
### 6. Reference Context Files
Don't embed descriptions. Reference paths:
```json
"context_files": [
"(example: .opencode/context/development/backend/auth/jwt-patterns.md)"
]
```
---
## Verification Checklist
- [ ] Each task completable in 1-2 hours?
- [ ] Dependencies create valid execution order?
- [ ] Parallel tasks correctly identified?
- [ ] Acceptance criteria are binary?
- [ ] Deliverables are concrete files/endpoints?
---
## Common Mistakes
| Mistake | Fix |
|---------|-----|
| Task too big | Split into 2-3 smaller tasks |
| Circular deps | Re-order or merge tasks |
| Missing deps | Run `task-cli.ts validate` |
| Vague criteria | Make binary pass/fail |
---
## Related
- `../standards/task-schema.md` - JSON field reference
- `managing-tasks.md` - Lifecycle workflow
- `../lookup/task-commands.md` - CLI reference

204
.opencode/context/core/task-management/lookup/task-commands.md Normal file
View File

@@ -0,0 +1,204 @@
<!-- Context: core/task-commands | Priority: high | Version: 1.0 | Updated: 2026-02-15 -->
# Lookup: Task CLI Commands
**Purpose**: Quick reference for task-cli.ts commands
**Last Updated**: 2026-02-14
---
## Usage
```bash
bunx --bun ts-node .opencode/context/tasks/scripts/task-cli.ts <command> [args]
```
Task files are stored in `.tmp/tasks/` at the project root.
---
## Commands
### status [feature]
Show task status summary for all features or specific feature.
```bash
task-cli.ts status
task-cli.ts status my-feature
```
**Output**:
```
[my-feature] My Feature Name
Status: active | Progress: 40% (2/5)
Pending: 2 | In Progress: 1 | Completed: 2 | Blocked: 0
```
---
### next [feature]
Show tasks ready to work on (deps satisfied).
```bash
task-cli.ts next
task-cli.ts next my-feature
```
**Output**:
```
=== Ready Tasks (deps satisfied) ===
[my-feature]
02 - Create JWT service [sequential]
03 - Write unit tests [parallel]
```
---
### parallel [feature]
Show only parallelizable tasks ready now.
```bash
task-cli.ts parallel
task-cli.ts parallel my-feature
```
**Use**: Batch multiple isolated tasks for parallel execution.
---
### deps \<feature\> \<seq\>
Show dependency tree for a specific task.
```bash
task-cli.ts deps my-feature 04
```
**Output**:
```
=== Dependency Tree: my-feature/04 ===
04 - Integration tests [pending]
├── ✓ 01 - Setup database [completed]
└── ○ 02 - Create API [pending]
└── ✓ 01 - Setup database [completed]
```
---
### blocked [feature]
Show blocked tasks and reasons.
```bash
task-cli.ts blocked
task-cli.ts blocked my-feature
```
**Output**:
```
=== Blocked Tasks ===
[my-feature]
04 - Integration tests (waiting: 02, 03)
05 - Deploy (explicitly blocked)
```
---
### complete \<feature\> \<seq\> "summary"
Mark task as completed with summary (max 200 chars).
```bash
task-cli.ts complete my-feature 02 "Created JWT service with RS256 signing"
```
**Effect**:
- Sets `status: "completed"`
- Sets `completed_at` timestamp
- Sets `completion_summary`
- Updates `task.json` counts
---
### validate [feature]
Check JSON validity, dependencies, circular refs.
```bash
task-cli.ts validate
task-cli.ts validate my-feature
```
**Checks**:
- task.json exists
- ID format correct
- Dependencies exist
- No circular dependencies
- Counts match
**Output**:
```
[my-feature]
✓ All checks passed
[broken-feature]
✗ ERROR: 03: depends on non-existent task 99
⚠ WARNING: 02: No acceptance criteria defined
```
---
## Exit Codes
| Code | Meaning |
|------|---------|
| 0 | Success |
| 1 | Error (validate found issues, missing args) |
---
## Enhanced Schema Support
The CLI fully supports the enhanced task schema (v2.0) with:
- **Line-number precision** - Context files with specific line ranges
- **Domain modeling** - bounded_context, module, vertical_slice fields
- **Contract tracking** - API/interface dependencies
- **Design artifacts** - Figma, wireframes, mockups
- **ADR references** - Architecture decision records
- **Prioritization** - RICE/WSJF scores
All enhanced fields are optional and backward compatible. See `../standards/enhanced-task-schema.md` for details.
---
## Planning Workflow Integration
For multi-stage orchestration workflows, use these planning agents before task creation:
| Agent | Purpose | Output |
|-------|---------|--------|
| **ArchitectureAnalyzer** | DDD bounded context identification | `.tmp/architecture/contexts.json` |
| **StoryMapper** | User journey and story mapping | `.tmp/story-maps/map.json` |
| **PrioritizationEngine** | RICE/WSJF scoring | `.tmp/backlog/prioritized.json` |
| **ContractManager** | API contract definition | `.tmp/contracts/{service}.json` |
| **ADRManager** | Architecture decision records | `docs/adr/` |
These agents populate enhanced schema fields (bounded_context, contracts, related_adrs, rice_score, etc.) automatically.
See `.opencode/context/core/workflows/multi-stage-orchestration.md` for the complete workflow.
---
## Related
- `../standards/task-schema.md` - Base JSON schema reference
- `../standards/enhanced-task-schema.md` - Extended schema with advanced features
- `../guides/managing-tasks.md` - Workflow guide
- `../workflows/multi-stage-orchestration.md` - Planning workflow

66
.opencode/context/core/task-management/navigation.md Normal file
View File

@@ -0,0 +1,66 @@
<!-- Context: core/navigation | Priority: critical | Version: 1.0 | Updated: 2026-02-15 -->
# Task Management Navigation
**Purpose**: JSON-driven task breakdown and tracking system
**Last Updated**: 2026-02-14
---
## Structure
```
core/task-management/
├── navigation.md
├── standards/
│ ├── task-schema.md # Base JSON schema (v1.0)
│ └── enhanced-task-schema.md # Extended schema (v2.0) - line precision, domain modeling, contracts
├── guides/
│ ├── splitting-tasks.md # Task decomposition
│ └── managing-tasks.md # Workflow guide
└── lookup/
└── task-commands.md # CLI script reference
```
---
## Quick Routes
| Task | Path | Priority |
|------|------|----------|
| **Understand base schema** | `standards/task-schema.md` | ⭐⭐⭐⭐⭐ |
| **Use enhanced features** | `standards/enhanced-task-schema.md` | ⭐⭐⭐⭐ |
| **Split a feature** | `guides/splitting-tasks.md` | ⭐⭐⭐⭐⭐ |
| **Manage task lifecycle** | `guides/managing-tasks.md` | ⭐⭐⭐⭐ |
| **Use CLI commands** | `lookup/task-commands.md` | ⭐⭐⭐⭐ |
---
## Loading Strategy
### For Creating Basic Tasks:
1. Load `standards/task-schema.md` (understand base structure)
2. Load `guides/splitting-tasks.md` (decomposition approach)
3. Reference `lookup/task-commands.md` (validate after creation)
### For Multi-Stage Orchestration:
1. Load `standards/enhanced-task-schema.md` (advanced features)
2. Load `standards/task-schema.md` (base structure reference)
3. Load `guides/splitting-tasks.md` (decomposition approach)
4. Reference planning agents: ArchitectureAnalyzer, StoryMapper, PrioritizationEngine, ContractManager, ADRManager
### For Managing Tasks:
1. Load `guides/managing-tasks.md` (workflow)
2. Reference `lookup/task-commands.md` (CLI usage)
---
## Related
- **Active tasks** → `.tmp/tasks/{feature}/` (at project root)
- **Completed tasks** → `.tmp/tasks/completed/{feature}/`
- **TaskManager agent** → `.opencode/agent/subagents/core/task-manager.md`
- **Planning agents** → `.opencode/agent/subagents/planning/` (ArchitectureAnalyzer, StoryMapper, PrioritizationEngine, ContractManager, ADRManager)
- **Multi-stage workflow** → `../workflows/multi-stage-orchestration.md`
- **Core navigation** → `../navigation.md`

201
.opencode/context/core/task-management/standards/task-schema.md Normal file
View File

@@ -0,0 +1,201 @@
<!-- Context: core/task-schema | Priority: critical | Version: 1.0 | Updated: 2026-02-15 -->
# Standard: Task JSON Schema
**Purpose**: JSON schema reference for task management files
**Last Updated**: 2026-02-14
---
## Core Concepts
Task management uses two JSON file types:
- `task.json` - Feature-level metadata and tracking
- `subtask_NN.json` - Individual atomic tasks with dependencies
Location: `.tmp/tasks/{feature-slug}/` (at project root)
---
## Schema Versions
This document describes the **base schema** (v1.0) that all task files must follow.
For **enhanced features** (line-number precision, domain modeling, contracts, ADRs, prioritization):
- See `enhanced-task-schema.md` for extended fields and capabilities
- All enhanced fields are **optional** and backward compatible
- Use enhanced schema for multi-stage orchestration workflows
---
## task.json Schema
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | string | Yes | kebab-case identifier |
| `name` | string | Yes | Human-readable name (max 100) |
| `status` | enum | Yes | active / completed / blocked / archived |
| `objective` | string | Yes | One-line objective (max 200) |
| `context_files` | array | No | **Standards paths only** — coding conventions, patterns, security rules to follow |
| `reference_files` | array | No | **Source material only** — project files to look at (existing code, config, schemas) |
| `exit_criteria` | array | No | Completion conditions |
| `subtask_count` | int | No | Total subtasks |
| `completed_count` | int | No | Done subtasks |
| `created_at` | datetime | Yes | ISO 8601 |
| `completed_at` | datetime | No | ISO 8601 |
---
## subtask_NN.json Schema
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | string | Yes | {feature}-{seq} |
| `seq` | string | Yes | 2-digit (01, 02) |
| `title` | string | Yes | Task title (max 100) |
| `status` | enum | Yes | pending / in_progress / completed / blocked |
| `depends_on` | array | No | Sequence numbers of dependencies |
| `parallel` | bool | No | True if can run alongside others |
| `context_files` | array | No | **Standards paths only** — conventions and patterns to follow |
| `reference_files` | array | No | **Source material only** — existing files to reference |
| `suggested_agent` | string | No | Recommended agent for this task (e.g., OpenFrontendSpecialist) |
| `acceptance_criteria` | array | No | Binary pass/fail conditions |
| `deliverables` | array | No | Files to create/modify |
| `agent_id` | string | No | Set when in_progress |
| `started_at` | datetime | No | ISO 8601 |
| `completed_at` | datetime | No | ISO 8601 |
| `completion_summary` | string | No | What was done (max 200) |
---
## Status Transitions
```
pending → in_progress (by working agent, when deps satisfied)
in_progress → completed (by TaskManager, after verification)
* → blocked (by either, when issue found)
blocked → pending (when unblocked)
```
---
## Parallel Flag
- `parallel: true` = Isolated task, can run alongside others
- `parallel: false` = May affect shared state, run sequentially
Use `task-cli.ts parallel` to find all parallelizable tasks ready to run.
---
## context_files vs reference_files — The Rule
These two fields serve fundamentally different purposes. **Never mix them.**
| Field | Answers | Contains | Agent behavior |
|-------|---------|----------|----------------|
| `context_files` | "What rules do I follow?" | Standards, conventions, patterns from `.opencode/context/` | Load and apply as coding guidelines |
| `reference_files` | "What existing code do I look at?" | Project source files, configs, schemas | Read to understand existing patterns |
**Wrong** ❌ — mixing standards and source files:
```json
"context_files": [
".opencode/context/core/standards/code-quality.md",
"package.json",
"src/existing-auth.ts"
]
```
**Right** ✅ — clean separation:
```json
"context_files": [
".opencode/context/core/standards/code-quality.md",
".opencode/context/core/standards/security-patterns.md"
],
"reference_files": [
"package.json",
"src/existing-auth.ts"
]
```
---
## Example
```json
{
"id": "auth-system-02",
"seq": "02",
"title": "Create JWT service",
"status": "pending",
"depends_on": ["01"],
"parallel": false,
"context_files": [
".opencode/context/core/standards/code-quality.md",
".opencode/context/core/standards/security-patterns.md"
],
"reference_files": [
"src/auth/token-utils.ts"
],
"acceptance_criteria": ["JWT tokens signed with RS256", "Tests pass"],
"deliverables": ["src/auth/jwt.service.ts"]
}
```
---
## Migration to Enhanced Schema
The enhanced schema adds powerful features while maintaining full backward compatibility:
### When to Use Enhanced Schema
Use `enhanced-task-schema.md` when you need:
- **Line-number precision** - Point to specific sections of large files (reduces cognitive load)
- **Domain modeling** - Track bounded contexts, modules, vertical slices
- **Contract tracking** - Manage API/interface dependencies
- **Design artifacts** - Link Figma, wireframes, mockups
- **ADR references** - Connect architectural decisions to tasks
- **Prioritization** - RICE/WSJF scoring for release planning
### Migration Path
1. **No changes required** - Existing task files work as-is
2. **Gradual adoption** - Add enhanced fields incrementally:
- Start with line-number precision for large context files
- Add domain fields (bounded_context, module) when modeling architecture
- Add contracts when defining APIs
- Add prioritization scores when planning releases
3. **Mixed formats** - You can mix old and new formats in the same file
### Example: Adding Line-Number Precision
**Old format** (still valid):
```json
"context_files": [
".opencode/context/core/standards/code-quality.md"
]
```
**New format** (enhanced):
```json
"context_files": [
{
"path": ".opencode/context/core/standards/code-quality.md",
"lines": "53-95",
"reason": "Pure function patterns for service layer"
}
]
```
Both formats work. Agents handle both automatically.
---
## Related
- `enhanced-task-schema.md` - Extended schema with advanced features
- `../guides/splitting-tasks.md` - How to decompose features
- `../guides/managing-tasks.md` - Lifecycle workflow
- `../lookup/task-commands.md` - CLI reference

478
.opencode/context/core/visual-development.md Normal file
View File

@@ -0,0 +1,478 @@
<!-- Context: visual-development | Priority: high | Version: 1.0 | Updated: 2025-01-27 -->
# Visual Development Context
**Purpose**: Visual content creation, UI design, image generation, and diagram creation
---
## Quick Routes
| Task Type | Context File | Subagent | Tools |
|-----------|-------------|----------|-------|
| **Generate image/diagram** | This file | Image Specialist | tool:gemini |
| **Edit existing image** | This file | Image Specialist | tool:gemini |
| **UI mockup (static)** | This file | Image Specialist | tool:gemini |
| **Interactive UI design** | `workflows/design-iteration-overview.md` | - | - |
| **Design system** | `ui/web/design-systems.md` | - | - |
| **UI standards** | `ui/web/ui-styling-standards.md` | - | - |
| **Animation patterns** | `ui/web/animation-patterns.md` | - | - |
---
## Image Specialist Capabilities
### What It Does
The **Image Specialist** subagent uses Gemini Nano Banana AI to:
- ✅ **Generate images from text descriptions** - Create original images, illustrations, graphics
- ✅ **Edit existing images** - Modify, enhance, or transform images
- ✅ **Analyze images** - Describe image content, extract information
- ✅ **Create diagrams** - Architecture diagrams, flowcharts, system visualizations
- ✅ **Design mockups** - UI mockups, wireframes, design concepts
- ✅ **Generate graphics** - Social media graphics, promotional images, icons
### When to Delegate
Delegate to Image Specialist when users request:
**Keywords to Watch For**:
- "create image", "generate image", "make image"
- "diagram", "flowchart", "visualization"
- "mockup", "wireframe", "design concept"
- "graphic", "illustration", "icon"
- "edit image", "modify image", "enhance image"
- "screenshot", "visual", "picture"
**Common Use Cases**:
1. **Architecture Diagrams** - Microservices, system design, infrastructure
2. **UI Mockups** - Dashboard designs, app interfaces, web layouts
3. **Social Media Graphics** - Announcements, promotions, branded content
4. **Documentation Images** - Tutorial screenshots, feature highlights, guides
5. **Presentations** - Slide graphics, charts, visual aids
6. **Marketing Assets** - Product images, hero graphics, banners
### How to Invoke
```javascript
task(
subagent_type="Image Specialist",
description="[Brief 3-5 word description]",
prompt="Context to load:
- .opencode/context/core/visual-development.md
Task: [Detailed visual requirement]
Requirements:
- Style: [Visual aesthetic - modern, minimalist, professional, etc.]
- Dimensions: [Width x Height or aspect ratio]
- Key Elements: [What must be included]
- Colors: [Color scheme, brand colors, palette]
- Format: [PNG, JPG, SVG preference]
Output: [Expected deliverable and location]"
)
```
---
## Use Case Examples
### 1. Architecture Diagram
**User Request**: "Create a diagram showing our microservices architecture"
**Invocation**:
```javascript
task(
subagent_type="Image Specialist",
description="Generate microservices architecture diagram",
prompt="Create a technical architecture diagram showing:
**Services**:
- API Gateway (entry point)
- Auth Service (authentication)
- User Service (user management)
- Order Service (order processing)
- Payment Service (payment processing)
- Notification Service (emails/SMS)
**Infrastructure**:
- PostgreSQL databases (one per service)
- Redis cache (shared)
- RabbitMQ message queue
- AWS S3 (file storage)
**External Services**:
- Stripe (payments)
- SendGrid (emails)
- Twilio (SMS)
**Style**: Clean, professional, modern tech diagram
**Colors**: Blue for services, green for databases, orange for external
**Format**: PNG, 1920x1080
**Layout**: Left-to-right flow, clear connections
Output: Save to docs/architecture-diagram.png"
)
```
---
### 2. UI Mockup
**User Request**: "Show me what the dashboard could look like"
**Invocation**:
```javascript
task(
subagent_type="Image Specialist",
description="Generate analytics dashboard mockup",
prompt="Create a UI mockup for an analytics dashboard:
**Layout**:
- Top: Header with logo, navigation, user menu
- Below header: 4 metric cards in a row
* Total Users (with trend arrow)
* Revenue (with percentage change)
* Conversion Rate (with sparkline)
* Active Sessions (with live indicator)
- Middle: Large line chart showing 30-day trends
- Bottom: Data table with recent transactions
**Style**: Modern, professional SaaS aesthetic
**Theme**: Dark mode with subtle gradients
**Colors**:
- Background: Dark gray (#1e293b)
- Cards: Slightly lighter (#334155)
- Accent: Blue (#3b82f6)
- Text: White/gray
**Typography**: Clean sans-serif (Inter-style)
**Format**: PNG, 1440x900
Output: Save to design_iterations/dashboard_mockup.png"
)
```
---
### 3. Social Media Graphic
**User Request**: "Create a graphic announcing our new feature"
**Invocation**:
```javascript
task(
subagent_type="Image Specialist",
description="Generate feature announcement graphic",
prompt="Create a social media graphic for feature launch:
**Content**:
- Main headline: 'Introducing Real-Time Collaboration'
- Subheadline: 'Work together, ship faster'
- Small text: 'Available now for all teams'
**Visual Elements**:
- Abstract illustration of people collaborating
- Subtle geometric shapes in background
- Modern, energetic feel
**Brand Colors**:
- Primary: #6366f1 (indigo)
- Secondary: #8b5cf6 (purple)
- Background: White with gradient
- Text: Dark gray (#1e293b)
**Format**: PNG, 1200x630 (optimized for Twitter/LinkedIn)
**Style**: Modern, professional, eye-catching
Output: Save to marketing/feature-launch-social.png"
)
```
---
### 4. Flowchart/Process Diagram
**User Request**: "Diagram the user onboarding flow"
**Invocation**:
```javascript
task(
subagent_type="Image Specialist",
description="Generate user onboarding flowchart",
prompt="Create a flowchart showing user onboarding process:
**Steps**:
1. User signs up (email/password)
2. Email verification sent
3. User clicks verification link
4. Profile setup (name, company, role)
5. Choose plan (Free/Pro/Enterprise)
6. Payment (if Pro/Enterprise)
7. Onboarding tutorial (5 steps)
8. Dashboard access
**Decision Points**:
- Email verified? (Yes → Continue, No → Resend)
- Plan selected? (Free → Skip payment, Paid → Payment)
- Payment successful? (Yes → Continue, No → Retry)
**Style**: Clean flowchart with standard symbols
**Colors**:
- Start/End: Green
- Process: Blue
- Decision: Yellow
- Error: Red
**Format**: PNG, 1600x1200
**Layout**: Top-to-bottom flow
Output: Save to docs/onboarding-flow.png"
)
```
---
### 5. Icon/Illustration
**User Request**: "Create an icon for our file upload feature"
**Invocation**:
```javascript
task(
subagent_type="Image Specialist",
description="Generate file upload icon",
prompt="Create a modern icon for file upload feature:
**Concept**: Cloud with upward arrow
**Style**:
- Minimalist, clean lines
- Rounded corners
- Flat design (no gradients)
**Colors**:
- Primary: #3b82f6 (blue)
- Accent: #60a5fa (lighter blue)
**Size**: 512x512px (will be scaled down)
**Format**: PNG with transparent background
**Usage**: App UI, documentation, marketing
Output: Save to assets/icons/upload-icon.png"
)
```
---
### 6. Image Editing
**User Request**: "Make this screenshot look more professional"
**Invocation**:
```javascript
task(
subagent_type="Image Specialist",
description="Enhance screenshot for documentation",
prompt="Edit the existing screenshot at docs/raw-screenshot.png:
**Enhancements Needed**:
- Add subtle drop shadow for depth
- Round the corners (8px radius)
- Add a thin border (#e5e7eb)
- Increase contrast slightly
- Ensure text is crisp and readable
**Optional**:
- Add subtle gradient background
- Highlight key UI elements with arrows/boxes
**Output Format**: PNG, maintain original dimensions
**Quality**: High (for documentation)
Output: Save to docs/enhanced-screenshot.png"
)
```
---
## Decision Tree: Image Specialist vs Design Iteration
Use this decision tree to choose the right approach:
```
User needs visual content
↓
Is it interactive/responsive HTML/CSS?
↓
YES → Use design-iteration-overview.md workflow
| - Create HTML files
| - Iterate on designs
| - Production-ready code
↓
NO → Is it a static visual asset?
↓
YES → Use Image Specialist
| - Diagrams
| - Mockups (non-interactive)
| - Graphics
| - Illustrations
↓
NO → Clarify requirements with user
```
### Quick Reference
| Need | Use |
|------|-----|
| **Interactive dashboard** | design-iteration-overview.md |
| **Dashboard mockup (static image)** | Image Specialist |
| **Responsive landing page** | design-iteration-overview.md |
| **Landing page hero graphic** | Image Specialist |
| **Working HTML prototype** | design-iteration-overview.md |
| **Architecture diagram** | Image Specialist |
| **UI component library** | design-iteration-overview.md |
| **Social media graphic** | Image Specialist |
---
## Tools & Dependencies
### Required Tool
**tool:gemini** - Gemini Nano Banana AI
- Automatically included in Developer profile
- Requires GEMINI_API_KEY environment variable
- Get API key: https://makersuite.google.com/app/apikey
### Configuration
Add to `.env` file:
```bash
GEMINI_API_KEY=your_api_key_here
```
### Capabilities
- **Text-to-Image**: Generate images from descriptions
- **Image-to-Image**: Edit and transform existing images
- **Image Analysis**: Describe and analyze image content
- **Multiple Formats**: PNG, JPG, WebP support
- **High Resolution**: Up to 2048x2048 pixels
---
## Best Practices
### Writing Effective Prompts
✅ **Do**:
- Be specific about dimensions and format
- Describe visual style clearly (modern, minimalist, professional)
- Specify colors using hex codes or names
- Include key elements that must appear
- Mention the intended use case
- Provide context about brand/aesthetic
❌ **Don't**:
- Use vague descriptions ("make it nice")
- Forget to specify dimensions
- Assume default style preferences
- Skip color specifications
- Omit output location
### Example: Good vs Bad Prompts
**❌ Bad Prompt**:
```
"Create a diagram of our system"
```
**✅ Good Prompt**:
```
"Create a technical architecture diagram showing:
- 3 microservices (API, Auth, Database)
- AWS infrastructure (EC2, RDS, S3)
- External APIs (Stripe, SendGrid)
Style: Clean, professional, modern
Colors: Blue for services, green for databases
Format: PNG, 1920x1080
Layout: Left-to-right flow with clear connections
Output: docs/system-architecture.png"
```
---
## Quality Checklist
Before delegating to Image Specialist:
- [ ] User request clearly indicates need for visual content
- [ ] Determined static image is appropriate (not interactive HTML)
- [ ] Gathered requirements: style, dimensions, colors, elements
- [ ] Specified output format and location
- [ ] Confirmed tool:gemini is available in profile
- [ ] Prepared detailed prompt with all specifications
After receiving output:
- [ ] Image meets specified requirements
- [ ] Dimensions and format are correct
- [ ] Visual style matches request
- [ ] All key elements are included
- [ ] Image is saved to specified location
- [ ] User is satisfied with result
---
## Troubleshooting
### Common Issues
**Issue**: Generated image doesn't match expectations
**Solution**: Refine prompt with more specific details, provide reference examples
**Issue**: Image quality is low
**Solution**: Request higher resolution, specify quality requirements in prompt
**Issue**: Colors don't match brand
**Solution**: Provide exact hex codes, reference brand guidelines
**Issue**: Layout is cluttered
**Solution**: Simplify requirements, specify clear hierarchy and spacing
**Issue**: Text in image is unreadable
**Solution**: Request larger text, higher contrast, clearer typography
---
## Related Context
- **UI Design Workflow**: `.opencode/context/core/workflows/design-iteration-overview.md`
- **Design Systems**: `.opencode/context/ui/web/design-systems.md`
- **UI Styling Standards**: `.opencode/context/ui/web/ui-styling-standards.md`
- **Animation Patterns**: `.opencode/context/ui/web/animation-basics.md`, `.opencode/context/ui/web/animation-advanced.md`
- **Subagent Invocation Guide**: `.opencode/context/openagents-repo/guides/subagent-invocation.md`
- **Agent Capabilities**: `.opencode/context/openagents-repo/core-concepts/agents.md`
---
## Keywords for Discovery
**ContextScout should find this file when users mention**:
- image, images, picture, photo, graphic
- diagram, flowchart, visualization, chart
- mockup, wireframe, design, concept
- illustration, icon, asset, visual
- generate, create, make, design
- screenshot, capture, render
- architecture, system, flow, process
- social media, marketing, promotional
- edit, modify, enhance, transform
- UI, interface, dashboard, layout
---
## Version History
- **v1.0** (2025-01-27): Initial creation with comprehensive use cases and examples

136
.opencode/context/core/workflows/code-review.md Normal file
View File

@@ -0,0 +1,136 @@
<!-- Context: workflows/review | Priority: high | Version: 2.0 | Updated: 2025-01-21 -->
# 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.

96
.opencode/context/core/workflows/component-planning.md Normal file
View File

@@ -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
```

20
.opencode/context/core/workflows/delegation.md Normal file
View File

@@ -0,0 +1,20 @@
<!-- Context: workflows/delegation | Priority: high | Version: 2.0 | Updated: 2025-01-21 -->
# Delegation Context Template
> **Note**: This is a reference file. Start with [`task-delegation-basics.md`](./task-delegation-basics.md).
## 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
---
For the full delegation workflow, use:
- [task-delegation-basics.md](./task-delegation-basics.md)
- [task-delegation-specialists.md](./task-delegation-specialists.md)
- [task-delegation-caching.md](./task-delegation-caching.md)

179
.opencode/context/core/workflows/design-iteration-best-practices.md Normal file
View File

@@ -0,0 +1,179 @@
<!-- Context: workflows/design-iteration-best-practices | Priority: high | Version: 1.0 | Updated: 2025-12-09 -->
# Design Iteration Best Practices
## Iteration Process
### When to Create Iterations
**Create new iteration** (`{name}_1_1.html`) when:
- User requests changes to existing design
- Refining based on feedback
- A/B testing variations
- Progressive enhancement
**Create new design** (`{name}_2.html`) when:
- Complete redesign requested
- Different approach/style
- Alternative layout structure
### Iteration Workflow
```
User: "Can you make the buttons larger and change the color?"
1. Read current file: dashboard_1.html
2. Make requested changes
3. Save as: dashboard_1_1.html
4. Present changes to user
User: "Perfect! Now can we add a sidebar?"
1. Read current file: dashboard_1_1.html
2. Add sidebar component
3. Save as: dashboard_1_2.html
4. Present changes to user
```
---
## File Management
### Folder Structure
```
design_iterations/
├── theme_1.css
├── theme_2.css
├── landing_1.html
├── landing_1_1.html
├── landing_1_2.html
├── dashboard_1.html
├── dashboard_1_1.html
└── README.md (optional: design notes)
```
### Version Control
**Track iterations**:
- Initial: `design_1.html`
- Iteration 1: `design_1_1.html`
- Iteration 2: `design_1_2.html`
- Iteration 3: `design_1_3.html`
**New major version**:
- Complete redesign: `design_2.html`
- Then iterate: `design_2_1.html`, `design_2_2.html`
---
## Communication Patterns
### Stage Transitions
**After Layout**:
```
"Here's the proposed layout structure. The design uses a [description].
Would you like to proceed with this layout, or should we make adjustments?"
```
**After Theme**:
```
"I've created a [style] theme with [key features]. The theme file is saved as theme_N.css.
Does this match your vision, or would you like to adjust colors/typography?"
```
**After Animation**:
```
"Here's the animation plan using [timing/style]. All animations are optimized for performance.
Are these animations appropriate, or should we adjust the timing/effects?"
```
**After Implementation**:
```
"I've created the complete design as {filename}.html. The design includes [key features].
Please review and let me know if you'd like any changes or iterations."
```
### Iteration Requests
**User requests change**:
```
"I'll update the design with [changes] and save it as {filename}_N.html.
This preserves the previous version for reference."
```
---
## Quality Checklist
Before presenting each stage:
**Layout Stage**:
- [ ] ASCII wireframe is clear and detailed
- [ ] Components are well-organized
- [ ] Responsive behavior is planned
- [ ] User approval requested
**Theme Stage**:
- [ ] Theme file created and saved
- [ ] Colors use OKLCH format
- [ ] Fonts loaded from Google Fonts
- [ ] Contrast ratios meet WCAG AA
- [ ] User approval requested
**Animation Stage**:
- [ ] Animations documented in micro-syntax
- [ ] Timing is appropriate (< 400ms)
- [ ] Performance optimized (transform/opacity)
- [ ] Accessibility considered
- [ ] User approval requested
**Implementation Stage**:
- [ ] Single HTML file created
- [ ] Theme CSS referenced
- [ ] Tailwind loaded via script tag
- [ ] Icons initialized
- [ ] Responsive design tested
- [ ] Accessibility attributes added
- [ ] Images use valid placeholder URLs
- [ ] Semantic HTML used
- [ ] User review requested
---
## Troubleshooting
### Common Issues
**Issue**: User wants to skip stages
**Solution**: Explain benefits of structured approach, but accommodate if insisted
**Issue**: Theme doesn't match user vision
**Solution**: Iterate on theme file, create theme_2.css with adjustments
**Issue**: Animations feel too slow/fast
**Solution**: Adjust timing in micro-syntax, regenerate with new values
**Issue**: Design doesn't work on mobile
**Solution**: Review responsive breakpoints, add mobile-specific styles
**Issue**: Colors have poor contrast
**Solution**: Use WCAG contrast checker, adjust OKLCH lightness values
---
## References
- [Design Systems Context](../../ui/web/design-systems.md)
- [UI Styling Standards](../../ui/web/ui-styling-standards.md)
- [Animation Basics](../../ui/web/animation-basics.md)
- [ASCII Art Generator](https://www.asciiart.eu/)
- [WCAG Contrast Checker](https://webaim.org/resources/contrastchecker/)
---
## Related Files
- [Overview](./design-iteration-overview.md)
- [Stage 4: Implementation](./design-iteration-stage-implementation.md)
- [Plan Iterations](./design-iteration-plan-iterations.md)

91
.opencode/context/core/workflows/design-iteration-overview.md Normal file
View File

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

182
.opencode/context/core/workflows/design-iteration-plan-file.md Normal file
View File

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

153
.opencode/context/core/workflows/design-iteration-plan-iterations.md Normal file
View File

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

80
.opencode/context/core/workflows/design-iteration-stage-animation.md Normal file
View File

@@ -0,0 +1,80 @@
<!-- Context: workflows/design-iteration-stage-animation | Priority: high | Version: 1.0 | Updated: 2025-12-09 -->
# Stage 3: Animation Design
**Purpose**: Define micro-interactions and transitions
## Process
1. Read design plan file from `.tmp/design-plans/{name}.md`
2. Review approved theme from Stage 2
3. Identify key interactions (hover, click, scroll)
4. Define animation timing and easing
5. Plan loading states and transitions
6. Document animations using micro-syntax
7. **Update plan file** with animation specifications
8. Present animation plan to user for approval
9. **Update plan file** with user feedback and approval status
## Deliverable
- Animation specification in micro-syntax format
- Updated plan file with Stage 3 complete
## Example Output
```
## Animation Design: Smooth & Professional
### Button Interactions
hover: 200ms ease-out [Y0→-2, shadow↗]
press: 100ms ease-in [S1→0.95]
ripple: 400ms ease-out [S0→2, α1→0]
### Card Interactions
cardHover: 300ms ease-out [Y0→-4, shadow↗]
cardClick: 200ms ease-out [S1→1.02]
### Page Transitions
pageEnter: 300ms ease-out [α0→1, Y+20→0]
pageExit: 200ms ease-in [α1→0]
### Loading States
spinner: 1000ms ∞ linear [R360°]
skeleton: 2000ms ∞ [bg: muted↔accent]
### Micro-Interactions
inputFocus: 200ms ease-out [S1→1.01, ring]
linkHover: 250ms ease-out [underline 0→100%]
**Philosophy**: Subtle, purposeful animations that enhance UX without distraction
**Performance**: All animations use transform/opacity for 60fps
**Accessibility**: Respects prefers-reduced-motion
```
## Best Practices
✅ **Do**:
- Use micro-syntax for documentation
- Keep animations under 400ms
- Use transform/opacity for performance
- Respect prefers-reduced-motion
- Make animations purposeful
❌ **Don't**:
- Animate width/height (use scale)
- Create distracting animations
- Ignore performance implications
- Skip accessibility considerations
## Approval Gate
"Are these animations appropriate for your design, or should we adjust?"
---
## Related Files
- [Overview](./design-iteration-overview.md)
- [Stage 2: Theme](./design-iteration-stage-theme.md)
- [Stage 4: Implementation](./design-iteration-stage-implementation.md)
- [Animation Basics](../../ui/web/animation-basics.md)

157
.opencode/context/core/workflows/design-iteration-stage-implementation.md Normal file
View File

@@ -0,0 +1,157 @@
<!-- Context: workflows/design-iteration-stage-implementation | Priority: high | Version: 1.0 | Updated: 2025-12-09 -->
# Stage 4: Implementation
**Purpose**: Generate complete HTML file with all components
## Process
1. Read design plan file from `.tmp/design-plans/{name}.md`
2. Review all approved decisions from Stages 1-3
3. Build individual UI components
4. Integrate theme CSS
5. Add animations and interactions
6. Combine into single HTML file
7. Test responsive behavior
8. Save to design_iterations folder
9. **Update plan file** with output file paths
10. Present to user for review
11. **Update plan file** with user feedback and final approval status
## Deliverable
- Complete HTML file with embedded or linked CSS
- Updated plan file with Stage 4 complete and all output files documented
## File Organization
```
design_iterations/
├── theme_1.css # Theme file from Stage 2
├── dashboard_1.html # Initial design
├── dashboard_1_1.html # First iteration
├── dashboard_1_2.html # Second iteration
├── chat_ui_1.html # Different design
└── chat_ui_1_1.html # Iteration of chat UI
```
## Naming Conventions
| Type | Format | Example |
|------|--------|---------|
| Initial design | `{name}_1.html` | `table_1.html` |
| First iteration | `{name}_1_1.html` | `table_1_1.html` |
| Second iteration | `{name}_1_2.html` | `table_1_2.html` |
| New design | `{name}_2.html` | `table_2.html` |
## Implementation Checklist
```html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Design Name</title>
<!-- ✅ Preconnect to external resources -->
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<!-- ✅ Load fonts -->
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet">
<!-- ✅ Load Tailwind (script tag, not stylesheet) -->
<script src="https://cdn.tailwindcss.com"></script>
<!-- ✅ Load Flowbite if needed -->
<link href="https://cdn.jsdelivr.net/npm/flowbite@2.0.0/dist/flowbite.min.css" rel="stylesheet">
<!-- ✅ Load icons -->
<script src="https://unpkg.com/lucide@latest/dist/umd/lucide.min.js"></script>
<!-- ✅ Link theme CSS -->
<link rel="stylesheet" href="theme_1.css">
<!-- ✅ Custom styles with !important for overrides -->
<style>
body {
font-family: 'Inter', sans-serif !important;
color: var(--foreground) !important;
}
h1, h2, h3, h4, h5, h6 {
font-weight: 600 !important;
}
/* Custom animations */
@keyframes fadeIn {
from { opacity: 0; transform: translateY(20px); }
to { opacity: 1; transform: translateY(0); }
}
.animate-fade-in {
animation: fadeIn 300ms ease-out;
}
</style>
</head>
<body>
<!-- ✅ Semantic HTML structure -->
<header>
<!-- Header content -->
</header>
<main>
<!-- Main content -->
</main>
<footer>
<!-- Footer content -->
</footer>
<!-- ✅ Load Flowbite JS if needed -->
<script src="https://cdn.jsdelivr.net/npm/flowbite@2.0.0/dist/flowbite.min.js"></script>
<!-- ✅ Initialize icons -->
<script>
lucide.createIcons();
</script>
<!-- ✅ Custom JavaScript -->
<script>
// Interactive functionality
</script>
</body>
</html>
```
## Best Practices
✅ **Do**:
- Use single HTML file per design
- Load Tailwind via script tag
- Reference theme CSS file
- Use !important for framework overrides
- Test responsive behavior
- Provide alt text for images
- Use semantic HTML
❌ **Don't**:
- Split into multiple files
- Load Tailwind as stylesheet
- Inline all styles
- Skip accessibility attributes
- Use made-up image URLs
- Use div soup (non-semantic HTML)
## Approval Gate
"Please review the design. Would you like any changes or iterations?"
---
## Related Files
- [Overview](./design-iteration-overview.md)
- [Stage 3: Animation](./design-iteration-stage-animation.md)
- [Best Practices](./design-iteration-best-practices.md)
- [Iteration Process](./design-iteration-plan-iterations.md)

115
.opencode/context/core/workflows/design-iteration-stage-layout.md Normal file
View File

@@ -0,0 +1,115 @@
<!-- Context: workflows/design-iteration-stage-layout | Priority: high | Version: 1.0 | Updated: 2025-12-09 -->
# Stage 1: Layout Design
**Purpose**: Define the structure and component hierarchy before visual design
## Process
1. Read design plan file from `.tmp/design-plans/{name}.md`
2. Analyze user requirements from plan
3. Identify core UI components
4. Plan layout structure and responsive behavior
5. Create ASCII wireframe
6. **Update plan file** with layout structure and component breakdown
7. Present to user for approval
8. **Update plan file** with user feedback and approval status
## Deliverable
- ASCII wireframe with component breakdown
- Updated plan file with Stage 1 complete
## Example Output
```
## Core UI Components
**Header Area**
- Logo/brand (Top left)
- Navigation menu (Top center)
- User actions (Top right)
**Main Content Area**
- Hero section (Full width)
- Feature cards (3-column grid on desktop, stack on mobile)
- Call-to-action (Centered)
**Footer**
- Links (4-column grid)
- Social icons (Centered)
- Copyright (Bottom)
## Layout Structure
Desktop (1024px+):
┌─────────────────────────────────────────────────┐
│ [Logo] Navigation [User Menu] │
├─────────────────────────────────────────────────┤
│ │
│ HERO SECTION │
│ (Full width, centered text) │
│ │
├─────────────────────────────────────────────────┤
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ Card 1 │ │ Card 2 │ │ Card 3 │ │
│ │ │ │ │ │ │ │
│ └─────────┘ └─────────┘ └─────────┘ │
├─────────────────────────────────────────────────┤
│ [Call to Action] │
├─────────────────────────────────────────────────┤
│ Links Links Links Social │
│ Copyright │
└─────────────────────────────────────────────────┘
Mobile (< 768px):
┌─────────────────┐
│ ☰ Logo [👤] │
├─────────────────┤
│ │
│ HERO SECTION │
│ │
├─────────────────┤
│ ┌───────────┐ │
│ │ Card 1 │ │
│ └───────────┘ │
│ ┌───────────┐ │
│ │ Card 2 │ │
│ └───────────┘ │
│ ┌───────────┐ │
│ │ Card 3 │ │
│ └───────────┘ │
├─────────────────┤
│ [CTA] │
├─────────────────┤
│ Links │
│ Social │
│ Copyright │
└─────────────────┘
```
## Best Practices
✅ **Do**:
- Use ASCII wireframes for clarity
- Break down into component hierarchy
- Plan responsive behavior upfront
- Consider mobile-first approach
- Get approval before proceeding
❌ **Don't**:
- Skip wireframing and jump to code
- Ignore responsive considerations
- Proceed without user approval
- Over-complicate initial layout
## Approval Gate
"Would you like to proceed with this layout or need modifications?"
---
## Related Files
- [Overview](./design-iteration-overview.md)
- [Design Plan File](./design-iteration-plan-file.md)
- [Stage 2: Theme](./design-iteration-stage-theme.md)

84
.opencode/context/core/workflows/design-iteration-stage-theme.md Normal file
View File

@@ -0,0 +1,84 @@
<!-- Context: workflows/design-iteration-stage-theme | Priority: high | Version: 1.0 | Updated: 2025-12-09 -->
# Stage 2: Theme Design
**Purpose**: Define colors, typography, spacing, and visual style
## Process
1. Read design plan file from `.tmp/design-plans/{name}.md`
2. Review approved layout from Stage 1
3. Choose design system (neo-brutalism, modern dark, custom)
4. Select color palette (avoid Bootstrap blue unless requested)
5. Choose typography (Google Fonts)
6. Define spacing and shadows
7. Generate theme CSS file
8. **Update plan file** with theme specifications
9. Present theme to user for approval
10. **Update plan file** with user feedback and approval status
## Deliverable
- CSS theme file saved to `design_iterations/theme_N.css`
- Updated plan file with Stage 2 complete
## Theme Selection Criteria
| Style | Use When | Avoid When |
|-------|----------|------------|
| Neo-Brutalism | Creative/artistic projects, retro aesthetic | Enterprise apps, accessibility-critical |
| Modern Dark | SaaS, developer tools, professional dashboards | Playful consumer apps |
| Custom | Specific brand requirements | Time-constrained projects |
## Example Output
```
## Theme Design: Modern Professional
**Style Reference**: Vercel/Linear aesthetic
**Color Palette**: Monochromatic with accent
**Typography**: Inter (UI) + JetBrains Mono (code)
**Spacing**: 4px base unit
**Shadows**: Subtle, soft elevation
**Theme File**: design_iterations/theme_1.css
Key Design Decisions:
- Primary: Neutral gray for professional feel
- Accent: Subtle blue for interactive elements
- Radius: 0.625rem for modern, friendly feel
- Shadows: Soft, minimal elevation
- Fonts: System-like for familiarity
```
## File Naming
`theme_1.css`, `theme_2.css`, etc.
## Best Practices
✅ **Do**:
- Reference design system context files
- Use CSS custom properties
- Save theme to separate file
- Consider accessibility (contrast ratios)
- Avoid Bootstrap blue unless requested
❌ **Don't**:
- Hardcode colors in HTML
- Use generic/overused color schemes
- Skip contrast testing
- Mix color formats (stick to OKLCH)
## Approval Gate
"Does this theme match your vision, or would you like adjustments?"
---
## Related Files
- [Overview](./design-iteration-overview.md)
- [Stage 1: Layout](./design-iteration-stage-layout.md)
- [Stage 3: Animation](./design-iteration-stage-animation.md)
- [Design Systems Context](../../ui/web/design-systems.md)
- [UI Styling Standards](../../ui/web/ui-styling-standards.md)

110
.opencode/context/core/workflows/design-iteration-visual-content.md Normal file
View File

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

461
.opencode/context/core/workflows/external-context-integration.md Normal file
View File

@@ -0,0 +1,461 @@
<!-- Context: workflows/external-context-integration | Priority: high | Version: 1.0 | Updated: 2026-01-28 -->
# External Context Integration Guide
## Overview
This guide explains how to integrate external context (fetched via ExternalScout) into the main agent workflow so that subagents can access it without re-fetching.
**Key Principle**: Main agents fetch external docs once → persist to disk → reference in session → subagents read (no re-fetching)
---
## When to Use External Context
Use ExternalScout to fetch external context when:
1. **User asks about external libraries** (Drizzle, Better Auth, Next.js, etc.)
2. **Task involves integration** between multiple external libraries
3. **Setup or configuration** of external tools is needed
4. **API patterns or best practices** from external libraries are relevant
**Don't use** when:
- Question is about internal project code
- Answer is in `.opencode/context/` (use ContextScout instead)
- User is asking for general programming concepts
---
## Integration Workflow
### Stage 1: Analyze & Discover (Before Approval)
```
Main Agent (OpenAgent, etc.)
↓
1. Analyze user request
↓
2. Identify external libraries mentioned
↓
3. Call ContextScout for internal context
↓
4. Call ExternalScout for external docs
- ExternalScout fetches from Context7 API
- ExternalScout persists to .tmp/external-context/
- ExternalScout returns file paths
↓
5. Capture returned file paths
↓
6. Do NOT write anything to disk yet
```
### Stage 2: Propose Plan (Before Approval)
```
Main Agent
↓
1. Show user lightweight summary:
- What will be done
- Which external libraries involved
- Which context files will be used
↓
2. Include discovered external context files in proposal
↓
3. Wait for user approval
```
### Stage 3: Approve (User Gate)
```
User
↓
Approves plan (or redirects)
```
### Stage 4: Init Session (After Approval)
```
Main Agent
↓
1. Create .tmp/sessions/{session-id}/context.md
↓
2. Populate sections:
- ## Context Files (from ContextScout)
- ## Reference Files (project files)
- ## External Context Fetched (from ExternalScout)
- ## Components
- ## Constraints
- ## Exit Criteria
↓
3. CRITICAL: Add "## External Context Fetched" section with:
- File paths returned by ExternalScout
- Brief description of each file
- Note that files are read-only
```
### Stage 5: Delegate with Context Path
```
Main Agent
↓
1. Call TaskManager (or other subagent)
↓
2. Pass session path in prompt:
"Load context from .tmp/sessions/{session-id}/context.md"
↓
3. TaskManager reads session context
↓
4. TaskManager extracts external context files
↓
5. TaskManager includes in subtask JSONs
```
### Stage 6: Subagents Read External Context
```
TaskManager / CoderAgent / TestEngineer
↓
1. Read session context file
↓
2. Extract "## External Context Fetched" section
↓
3. Read referenced files from .tmp/external-context/
↓
4. Use external docs to inform implementation
↓
5. NO RE-FETCHING ✅
```
---
## Implementation Details
### Step 1: Call ExternalScout
In your main agent (before approval):
```javascript
// Detect external libraries from user request
const externalLibraries = ["drizzle-orm", "better-auth", "next.js"];
// Call ExternalScout
task(
subagent_type="ExternalScout",
description="Fetch external documentation",
prompt="Fetch documentation for these libraries:
- Drizzle ORM: modular schema organization
- Better Auth: Next.js integration
- Next.js: App Router setup
Persist fetched docs to .tmp/external-context/
Return file paths for each fetched document"
)
// Capture returned file paths
// Example return:
// - .tmp/external-context/drizzle-orm/modular-schemas.md
// - .tmp/external-context/better-auth/nextjs-integration.md
// - .tmp/external-context/next.js/app-router-setup.md
```
### Step 2: Propose Plan with External Context
```markdown
## Implementation Plan
**Task**: Set up Drizzle + Better Auth in Next.js
**External Libraries Involved**:
- Drizzle ORM (database)
- Better Auth (authentication)
- Next.js (framework)
**External Context Discovered**:
- `.tmp/external-context/drizzle-orm/modular-schemas.md`
- `.tmp/external-context/better-auth/nextjs-integration.md`
- `.tmp/external-context/next.js/app-router-setup.md`
**Approach**:
1. Set up Drizzle schema with modular organization
2. Configure Better Auth with Drizzle adapter
3. Integrate with Next.js App Router
**Approval needed before proceeding.**
```
### Step 3: Create Session with External Context
After approval, create `.tmp/sessions/{session-id}/context.md`:
```markdown
# Task Context: Drizzle + Better Auth Integration
Session ID: 2026-01-28-drizzle-auth
Created: 2026-01-28T14:30:22Z
Status: in_progress
## Current Request
Set up Drizzle ORM with Better Auth in a Next.js application
## Context Files (Standards to Follow)
- .opencode/context/core/standards/code-quality.md
- .opencode/context/core/standards/test-coverage.md
## Reference Files (Source Material)
- package.json
- src/db/schema.ts (existing)
- src/auth/config.ts (existing)
## External Context Fetched
These are live documentation files fetched from external libraries. Subagents should reference these instead of re-fetching.
### Drizzle ORM
- `.tmp/external-context/drizzle-orm/modular-schemas.md` — Schema organization patterns for modular architecture
- `.tmp/external-context/drizzle-orm/postgresql-setup.md` — PostgreSQL configuration and setup
### Better Auth
- `.tmp/external-context/better-auth/nextjs-integration.md` — Integration guide for Next.js App Router
- `.tmp/external-context/better-auth/drizzle-adapter.md` — Drizzle adapter setup and configuration
### Next.js
- `.tmp/external-context/next.js/app-router-setup.md` — App Router basics and configuration
- `.tmp/external-context/next.js/server-actions.md` — Server Actions patterns for mutations
**Important**: These files are read-only and cached for reference. Do not modify them.
## Components
- Drizzle schema setup with modular organization
- Better Auth configuration with Drizzle adapter
- Next.js App Router integration
## Constraints
- TypeScript strict mode
- Must support PostgreSQL
- Backward compatible with existing auth system
## Exit Criteria
- [ ] Drizzle schema set up with modular organization
- [ ] Better Auth configured with Drizzle adapter
- [ ] Next.js App Router integration complete
- [ ] All tests passing
- [ ] Documentation updated
## Progress
- [ ] Session initialized
- [ ] Tasks created
- [ ] Implementation complete
- [ ] Tests passing
- [ ] Handoff complete
```
### Step 4: Delegate to TaskManager
```javascript
task(
subagent_type="TaskManager",
description="Break down Drizzle + Better Auth integration",
prompt="Load context from .tmp/sessions/2026-01-28-drizzle-auth/context.md
Read the context file for full requirements, standards, and external documentation.
Break down this feature into atomic subtasks:
1. Drizzle schema setup with modular organization
2. Better Auth configuration with Drizzle adapter
3. Next.js App Router integration
4. Test suite
For each subtask, include:
- context_files: Standards from context.md
- reference_files: Project files to understand
- external_context: External docs to reference
Create subtask files in tasks/subtasks/drizzle-auth-integration/"
)
```
### Step 5: TaskManager Creates Subtasks with External Context
TaskManager creates subtask JSONs like:
```json
{
"id": "01-drizzle-schema-setup",
"title": "Set up Drizzle schema with modular organization",
"description": "Create modular Drizzle schema following best practices",
"context_files": [
".opencode/context/core/standards/code-quality.md",
".opencode/context/core/standards/test-coverage.md"
],
"reference_files": [
"package.json",
"src/db/schema.ts"
],
"external_context": [
".tmp/external-context/drizzle-orm/modular-schemas.md",
".tmp/external-context/drizzle-orm/postgresql-setup.md"
],
"instructions": "Set up Drizzle schema following modular patterns from external context. Reference .tmp/external-context/drizzle-orm/modular-schemas.md for best practices.",
"acceptance_criteria": [
"Schema organized into separate files by domain",
"PostgreSQL configuration matches external docs",
"TypeScript types properly exported",
"Tests cover schema setup"
]
}
```
### Step 6: CoderAgent Implements Using External Context
CoderAgent reads subtask JSON and:
1. Loads context_files (standards)
2. Reads reference_files (existing code)
3. **Reads external_context files** (external docs)
4. Implements following all standards and external docs
5. Returns completed subtask
---
## Best Practices
### For Main Agents
✅ **DO**:
- Call ExternalScout early in planning phase
- Capture returned file paths
- Add to session context under "## External Context Fetched"
- Pass session path to subagents
- Include external context in proposal to user
❌ **DON'T**:
- Forget to call ExternalScout when external libraries involved
- Skip adding external context to session
- Re-fetch external docs (trust ExternalScout persistence)
- Modify external context files
### For ExternalScout
✅ **DO**:
- Always persist fetched docs to `.tmp/external-context/`
- Update `.manifest.json` after each fetch
- Include metadata header in every file
- Filter aggressively to relevant sections
- Cite sources and include official docs links
❌ **DON'T**:
- Forget to persist files
- Skip manifest updates
- Return entire documentation
- Fabricate documentation content
- Write outside `.tmp/external-context/`
### For TaskManager
✅ **DO**:
- Extract external_context from session context
- Include in subtask JSONs
- Pass to downstream agents
- Document which external docs informed decisions
❌ **DON'T**:
- Forget to include external_context in subtasks
- Mix external_context with context_files
- Assume subagents will re-fetch
### For Subagents (CoderAgent, TestEngineer, etc.)
✅ **DO**:
- Read external_context files from subtask JSON
- Use external docs to inform implementation
- Reference external docs in comments
- Follow patterns from external docs
❌ **DON'T**:
- Re-fetch external documentation
- Ignore external context files
- Modify external context files
- Assume external docs are optional
---
## Example: Complete Flow
### User Request
```
"Set up Drizzle ORM with Better Auth in Next.js, using modular schema organization"
```
### Main Agent Flow
1. **Analyze**: Detect Drizzle, Better Auth, Next.js
2. **Discover**: Call ContextScout + ExternalScout
3. **Propose**: Show plan with external context files
4. **Approve**: User approves
5. **Init Session**: Create context.md with external context section
6. **Delegate**: Call TaskManager with session path
7. **Validate**: Check tests pass
8. **Complete**: Update docs, cleanup
### ExternalScout Flow
1. **Detect**: Drizzle, Better Auth, Next.js
2. **Fetch**: Get docs from Context7 API
3. **Filter**: Extract relevant sections
4. **Persist**: Write to `.tmp/external-context/{package}/{topic}.md`
5. **Update**: Add to `.manifest.json`
6. **Return**: File paths to main agent
### TaskManager Flow
1. **Read**: Session context.md
2. **Extract**: External context files
3. **Create**: Subtasks with external_context field
4. **Delegate**: Pass to CoderAgent
### CoderAgent Flow
1. **Read**: Subtask JSON
2. **Load**: context_files (standards)
3. **Reference**: reference_files (existing code)
4. **Read**: external_context files (external docs)
5. **Implement**: Following all standards and external docs
6. **Complete**: Return implemented subtask
---
## Troubleshooting
### External Context Files Not Found
**Problem**: Subagent can't find `.tmp/external-context/{package}/{topic}.md`
**Solution**:
1. Check ExternalScout ran successfully
2. Verify file path in session context matches actual location
3. Check `.manifest.json` to see what's cached
4. If missing, re-run ExternalScout
### Stale External Context
**Problem**: External docs are outdated
**Solution**:
1. Delete stale files: `scripts/external-context/manage-external-context.sh delete-package {package}`
2. Re-run ExternalScout to fetch fresh docs
3. Update session context with new file paths
### Manifest Out of Sync
**Problem**: `.manifest.json` doesn't match actual files
**Solution**:
1. Regenerate manifest: `scripts/external-context/manage-external-context.sh regenerate-manifest`
2. Verify all files have metadata headers
---
## References
- **ExternalScout**: `.opencode/agent/subagents/core/externalscout.md`
- **External Context Management**: `.opencode/context/core/workflows/external-context-management.md`
- **Task Delegation**: `.opencode/context/core/workflows/task-delegation-basics.md`
- **Management Script**: `scripts/external-context/manage-external-context.sh`

406
.opencode/context/core/workflows/external-context-management.md Normal file
View File

@@ -0,0 +1,406 @@
<!-- Context: workflows/external-context | Priority: high | Version: 1.0 | Updated: 2026-01-28 -->
# External Context Management
## Overview
External context is live documentation fetched from external libraries and frameworks (via Context7 API or official docs). Instead of re-fetching on every task, we **persist external context** to `.tmp/external-context/` so main agents can pass it to subagents.
**Key Principle**: ExternalScout fetches once → persists to disk → main agents reference → subagents read (no re-fetching)
---
## Directory Structure
```
.tmp/external-context/
├── .manifest.json # Metadata about all cached external docs
├── drizzle-orm/
│ ├── modular-schemas.md # Fetched: "How to organize schemas modularly"
│ ├── postgresql-setup.md # Fetched: "PostgreSQL setup with Drizzle"
│ └── typescript-config.md # Fetched: "TypeScript configuration"
├── better-auth/
│ ├── nextjs-integration.md # Fetched: "Better Auth + Next.js setup"
│ ├── drizzle-adapter.md # Fetched: "Drizzle adapter for Better Auth"
│ └── session-management.md # Fetched: "Session handling"
├── next.js/
│ ├── app-router-setup.md # Fetched: "App Router basics"
│ ├── server-actions.md # Fetched: "Server Actions patterns"
│ └── middleware.md # Fetched: "Middleware configuration"
└── tanstack-query/
├── server-components.md # Fetched: "TanStack Query + Server Components"
└── prefetching.md # Fetched: "Prefetching strategies"
```
### Naming Conventions
- **Package name** (directory): Exact bun --bun package name (kebab-case)
- ✅ `drizzle-orm`, `better-auth`, `next.js`, `@tanstack/react-query`
- ❌ `drizzle`, `nextjs`, `tanstack-query`
- **File name** (topic): Kebab-case description of the topic
- ✅ `modular-schemas.md`, `nextjs-integration.md`, `server-components.md`
- ❌ `modular schemas.md`, `NextJS Integration.md`, `ServerComponents.md`
---
## Manifest File
**Location**: `.tmp/external-context/.manifest.json`
**Purpose**: Track what's cached, when it was fetched, and from which source
**Structure**:
```json
{
"last_updated": "2026-01-28T14:30:22Z",
"packages": {
"drizzle-orm": {
"files": [
"modular-schemas.md",
"postgresql-setup.md",
"typescript-config.md"
],
"last_updated": "2026-01-28T14:30:22Z",
"source": "Context7 API",
"official_docs": "https://orm.drizzle.team"
},
"better-auth": {
"files": [
"nextjs-integration.md",
"drizzle-adapter.md",
"session-management.md"
],
"last_updated": "2026-01-28T14:25:10Z",
"source": "Context7 API",
"official_docs": "https://better-auth.com"
},
"next.js": {
"files": [
"app-router-setup.md",
"server-actions.md",
"middleware.md"
],
"last_updated": "2026-01-28T14:20:05Z",
"source": "Context7 API",
"official_docs": "https://nextjs.org"
}
}
}
```
---
## File Format
Each external context file has a metadata header followed by the documentation content.
**Template**:
```markdown
---
source: Context7 API
library: Drizzle ORM
package: drizzle-orm
topic: modular-schemas
fetched: 2026-01-28T14:30:22Z
official_docs: https://orm.drizzle.team/docs/goodies#multi-file-schemas
---
# Modular Schemas in Drizzle ORM
[Filtered documentation content from Context7 API]
## Key Concepts
[Relevant sections only]
## Code Examples
[Practical examples from official docs]
---
**Source**: Context7 API (live, version-specific)
**Official Docs**: https://orm.drizzle.team/docs/goodies#multi-file-schemas
**Fetched**: 2026-01-28T14:30:22Z
```
---
## Workflow: How External Context Flows
### Stage 1: Main Agent Needs External Context
```
Main Agent (e.g., OpenAgent)
↓
Detects: "User is asking about Drizzle + Better Auth + Next.js"
↓
Calls: ExternalScout to fetch live docs
```
### Stage 2: ExternalScout Fetches & Persists
```
ExternalScout
↓
1. Detects libraries: Drizzle, Better Auth, Next.js
↓
2. Fetches from Context7 API (primary) or official docs (fallback)
↓
3. Filters to relevant sections
↓
4. Persists to .tmp/external-context/{package-name}/{topic}.md
↓
5. Updates .manifest.json
↓
Returns: File paths + formatted documentation
```
### Stage 3: Main Agent References in Session Context
```
Main Agent
↓
Creates session: .tmp/sessions/{session-id}/context.md
↓
Adds section: "## External Context Fetched"
↓
Lists files:
- .tmp/external-context/drizzle-orm/modular-schemas.md
- .tmp/external-context/better-auth/nextjs-integration.md
- .tmp/external-context/next.js/app-router-setup.md
↓
Delegates to TaskManager with session path
```
### Stage 4: Subagents Read External Context
```
TaskManager (or CoderAgent, TestEngineer, etc.)
↓
Reads: .tmp/sessions/{session-id}/context.md
↓
Extracts: "## External Context Fetched" section
↓
Reads: .tmp/external-context/{package-name}/{topic}.md files
↓
Uses: External docs to inform implementation
↓
NO RE-FETCHING needed ✅
```
---
## Integration with Task Delegation
### In Session Context File
Add this section to `.tmp/sessions/{session-id}/context.md`:
```markdown
## External Context Fetched
These are live documentation files fetched from external libraries. Subagents should reference these instead of re-fetching.
### Drizzle ORM
- `.tmp/external-context/drizzle-orm/modular-schemas.md` — Schema organization patterns
- `.tmp/external-context/drizzle-orm/postgresql-setup.md` — PostgreSQL configuration
### Better Auth
- `.tmp/external-context/better-auth/nextjs-integration.md` — Next.js integration guide
- `.tmp/external-context/better-auth/drizzle-adapter.md` — Drizzle adapter setup
### Next.js
- `.tmp/external-context/next.js/app-router-setup.md` — App Router basics
- `.tmp/external-context/next.js/server-actions.md` — Server Actions patterns
**Important**: These files are read-only and should not be modified. They're cached for reference only.
```
### In Subtask JSONs (Created by TaskManager)
When TaskManager creates subtask JSONs, it should include external context files:
```json
{
"id": "01-drizzle-schema-setup",
"title": "Set up Drizzle schema with modular organization",
"context_files": [
".opencode/context/core/standards/code-quality.md",
".opencode/context/core/standards/test-coverage.md"
],
"reference_files": [
"package.json",
"src/db/schema.ts"
],
"external_context": [
".tmp/external-context/drizzle-orm/modular-schemas.md",
".tmp/external-context/drizzle-orm/postgresql-setup.md"
],
"instructions": "Set up Drizzle schema following modular patterns from external context..."
}
```
---
## Cleanup & Maintenance
### When to Clean Up
External context files should be cleaned up when:
1. Task is complete and session is deleted
2. External docs become stale (>7 days old)
3. User explicitly requests cleanup
4. Disk space is needed
### How to Clean Up
**Manual cleanup** (ask user first):
```bash
rm -rf .tmp/external-context/{package-name}/
# Update .manifest.json to remove package entry
```
**Automatic cleanup** (future enhancement):
- Add cleanup script that removes files older than 7 days
- Run as part of session cleanup process
- Update manifest after cleanup
### Manifest Cleanup
After deleting external context files, update `.manifest.json`:
```json
{
"last_updated": "2026-01-28T15:00:00Z",
"packages": {
// Remove entries for deleted packages
}
}
```
---
## Best Practices
### For Main Agents (OpenAgent, etc.)
1. **Call ExternalScout early** in the planning phase
2. **Capture returned file paths** from ExternalScout
3. **Add to session context** in "## External Context Fetched" section
4. **Pass session path to subagents** so they know where to find external docs
5. **Don't re-fetch** — trust that ExternalScout persisted correctly
### For ExternalScout
1. **Always persist** fetched documentation to `.tmp/external-context/`
2. **Update manifest** after each fetch
3. **Include metadata header** in every file (source, library, package, topic, fetched timestamp)
4. **Filter aggressively** — only include relevant sections
5. **Cite sources** — include official docs links
### For Subagents (TaskManager, CoderAgent, etc.)
1. **Read external context files** from session context
2. **Don't re-fetch** — use persisted files
3. **Reference in implementation** — cite which external docs informed decisions
4. **Don't modify** external context files — they're read-only
5. **Include in subtask JSONs** — pass external_context to downstream agents
---
## Examples
### Example 1: Drizzle + Better Auth Integration
**Main Agent Flow**:
```
1. User asks: "Set up Drizzle + Better Auth in Next.js"
2. Main agent calls ExternalScout
3. ExternalScout fetches:
- drizzle-orm/modular-schemas.md
- drizzle-orm/postgresql-setup.md
- better-auth/nextjs-integration.md
- better-auth/drizzle-adapter.md
- next.js/app-router-setup.md
4. ExternalScout persists all files to .tmp/external-context/
5. Main agent creates session with "## External Context Fetched" section
6. Main agent delegates to TaskManager with session path
7. TaskManager reads external context, creates subtasks
8. CoderAgent implements using external docs (no re-fetching)
```
**Session Context File**:
```markdown
## External Context Fetched
### Drizzle ORM
- `.tmp/external-context/drizzle-orm/modular-schemas.md`
- `.tmp/external-context/drizzle-orm/postgresql-setup.md`
### Better Auth
- `.tmp/external-context/better-auth/nextjs-integration.md`
- `.tmp/external-context/better-auth/drizzle-adapter.md`
### Next.js
- `.tmp/external-context/next.js/app-router-setup.md`
```
### Example 2: TanStack Query + Server Components
**Main Agent Flow**:
```
1. User asks: "How do I use TanStack Query with Next.js Server Components?"
2. Main agent calls ExternalScout
3. ExternalScout fetches:
- tanstack-query/server-components.md
- tanstack-query/prefetching.md
- next.js/server-components.md
4. ExternalScout persists to .tmp/external-context/
5. Main agent creates session with external context references
6. Subagents read and implement using external docs
```
---
## Troubleshooting
### External Context Files Not Found
**Problem**: Subagent can't find `.tmp/external-context/{package-name}/{topic}.md`
**Solution**:
1. Check that ExternalScout ran successfully
2. Verify file path in session context matches actual file location
3. Check `.manifest.json` to see what's cached
4. If missing, re-run ExternalScout to fetch and persist
### Stale External Context
**Problem**: External docs are outdated (>7 days old)
**Solution**:
1. Delete stale files: `rm -rf .tmp/external-context/{package-name}/`
2. Update `.manifest.json`
3. Re-run ExternalScout to fetch fresh docs
4. Update session context with new file paths
### Manifest Out of Sync
**Problem**: `.manifest.json` doesn't match actual files
**Solution**:
1. Regenerate manifest by listing actual files:
```bash
find .tmp/external-context -name "*.md" | sort
```
2. Update `.manifest.json` to match
3. Verify all files have metadata headers
---
## References
- **ExternalScout**: `.opencode/agent/subagents/core/externalscout.md` — Fetches and persists external docs
- **Task Delegation**: `.opencode/context/core/workflows/task-delegation-basics.md` — How to reference external context in sessions
- **Session Management**: `.opencode/context/core/workflows/session-management.md` — Session lifecycle
- **Library Registry**: `.opencode/skills/context7/library-registry.md` — Supported libraries and query patterns

165
.opencode/context/core/workflows/external-libraries-faq.md Normal file
View File

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

130
.opencode/context/core/workflows/external-libraries-scenarios.md Normal file
View File

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

270
.opencode/context/core/workflows/feature-breakdown.md Normal file
View File

@@ -0,0 +1,270 @@
<!-- Context: workflows/task-breakdown | Priority: high | Version: 2.0 | Updated: 2025-01-21 -->
# 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

60
.opencode/context/core/workflows/navigation.md Normal file
View File

@@ -0,0 +1,60 @@
<!-- Context: core/navigation | Priority: critical | Version: 1.0 | Updated: 2026-02-15 -->
# Core Workflows Navigation
**Purpose**: Process workflows for common development tasks
---
## Files
| File | Topic | Priority | Load When |
|------|-------|----------|-----------|
| `code-review.md` | Code review process | ⭐⭐⭐⭐ | Reviewing code |
| `task-delegation-basics.md` | Core delegation workflow | ⭐⭐⭐⭐ | Using task tool |
| `task-delegation-specialists.md` | When to delegate to whom | ⭐⭐⭐⭐ | Choosing specialist |
| `task-delegation-caching.md` | Context caching | ⭐⭐⭐ | Repeated tasks |
| `external-libraries-workflow.md` | External library process | ⭐⭐⭐⭐ | External packages |
| `external-libraries-scenarios.md` | Common scenarios | ⭐⭐⭐ | Examples needed |
| `external-libraries-faq.md` | Troubleshooting | ⭐⭐⭐ | Errors/questions |
| `feature-breakdown.md` | Breaking down features | ⭐⭐⭐⭐ | 4+ files, complex tasks |
| `session-management.md` | Managing sessions | ⭐⭐⭐ | Session cleanup |
| `design-iteration-overview.md` | Design workflow overview | ⭐⭐⭐⭐ | Starting design work |
| `design-iteration-plan-file.md` | Design plan template | ⭐⭐⭐⭐ | Creating design plan |
| `design-iteration-stage-layout.md` | Stage 1: Layout | ⭐⭐⭐ | Layout design |
| `design-iteration-stage-theme.md` | Stage 2: Theme | ⭐⭐⭐ | Theme design |
| `design-iteration-stage-animation.md` | Stage 3: Animation | ⭐⭐⭐ | Animation design |
| `design-iteration-stage-implementation.md` | Stage 4: Implementation | ⭐⭐⭐ | Implementation |
| `design-iteration-visual-content.md` | Visual content generation | ⭐⭐ | Image generation |
| `design-iteration-best-practices.md` | Best practices & troubleshooting | ⭐⭐⭐ | Quality check |
| `design-iteration-plan-iterations.md` | Plan file iterations | ⭐⭐⭐ | Managing iterations |
---
## Loading Strategy
**For code review**:
1. Load `code-review.md` (high)
2. Depends on: `../standards/code-quality.md`, `../standards/security-patterns.md`
**For task delegation**:
1. Load `task-delegation-basics.md` (high)
2. Load `task-delegation-specialists.md` (when choosing agent)
**For external libraries**:
1. Load `external-libraries-workflow.md` (high)
2. Reference `external-libraries-scenarios.md` for examples
**For complex features**:
1. Load `feature-breakdown.md` (high)
2. Depends on: `task-delegation-basics.md`
**For session management**:
1. Load `session-management.md` (medium)
---
## Related
- **Standards** → `../standards/navigation.md`
- **OpenAgents Control Delegation** → `../../openagents-repo/guides/subagent-invocation.md`

19
.opencode/context/core/workflows/review.md Normal file
View File

@@ -0,0 +1,19 @@
<!-- Context: workflows/review | Priority: high | Version: 2.0 | Updated: 2025-01-21 -->
# Code Review Guidelines
> **Note**: This is a reference file. The full content is in [`code-review.md`](./code-review.md).
## 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
---
For the complete code review guidelines, see [code-review.md](./code-review.md).

157
.opencode/context/core/workflows/session-management.md Normal file
View File

@@ -0,0 +1,157 @@
<!-- Context: workflows/sessions | Priority: medium | Version: 2.0 | Updated: 2025-01-21 -->
# 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**
- Don't create sessions for simple questions or direct execution
- Initialize on first delegation that requires context file
- Session ID format: `{timestamp}-{random-4-chars}`
- Example: `20250118-143022-a4f2`
## Session Structure
```
.tmp/sessions/{session-id}/
├── .manifest.json
├── features/
│ └── {task-name}-context.md
├── documentation/
│ └── {task-name}-context.md
├── code/
│ └── {task-name}-context.md
├── tasks/
│ └── {task-name}-tasks.md
└── general/
└── {task-name}-context.md
```
## Session Isolation
**Each session has unique ID - prevents concurrent agent conflicts**
✅ Multiple agent instances can run simultaneously
✅ No file conflicts between sessions
✅ Each session tracks only its own files
✅ Safe cleanup - only deletes own session folder
## Manifest Structure
**Location**: `.tmp/sessions/{session-id}/.manifest.json`
```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": "@TaskManager",
"keywords": ["user-auth", "authentication", "features"]
},
"tasks/user-auth-tasks.md": {
"created": "2025-01-18T14:32:15Z",
"for": "@TaskManager",
"keywords": ["user-auth", "tasks", "breakdown"]
}
},
"context_index": {
"user-auth": [
"features/user-auth-context.md",
"tasks/user-auth-tasks.md"
]
}
}
```
## Activity Tracking
**Update timestamp after each context file creation or delegation**
- Update `last_activity` field in manifest
- Used for stale session detection
- Helps identify active vs abandoned sessions
## Cleanup Policy
### Manual Cleanup (Preferred)
**Ask user confirmation before cleanup**
After task completion:
1. Ask: "Should I clean up temporary session files at `.tmp/sessions/{session-id}/`?"
2. Wait for user confirmation
3. Only delete files tracked in current session's manifest
4. Remove entire session folder: `.tmp/sessions/{session-id}/`
### Safety Rules
- **NEVER** delete files outside current session
- **ONLY** delete files tracked in manifest
- **ALWAYS** confirm with user before cleanup
### Stale Session Cleanup
**Auto-remove sessions >24 hours old**
- Check `last_activity` timestamp in manifest
- Safe to run periodically (see `scripts/cleanup-stale-sessions.sh`)
- Won't affect active sessions
## Error Handling
### Subagent Failure
- Report error to user
- Ask if should retry or abort
- Don't auto-retry without approval
### Context File Error
- Fall back to inline context in delegation prompt
- Warn user that context file creation failed
- Continue with task if possible
### Session Creation Error
- Continue without session
- Warn user
- Use inline context for delegation
- Don't block task execution
## Best Practices
1. **Lazy Init**: Only create session when actually needed
2. **Track Everything**: Add all context files to manifest
3. **Update Activity**: Touch `last_activity` on each operation
4. **Clean Promptly**: Remove files after task completion
5. **Isolate Sessions**: Never access files from other sessions
6. **Confirm Cleanup**: Always ask user before deleting
## Example Workflow
```bash
# User: "Build user authentication system"
# → Complex task, needs context file
# → Create session: 20250118-143022-a4f2
# → Create: .tmp/sessions/20250118-143022-a4f2/features/user-auth-context.md
# → Delegate to @task-manager
# User: "Implement login component"
# → Same session, add context
# → Create: .tmp/sessions/20250118-143022-a4f2/code/login-context.md
# → Delegate to @coder-agent
# Task complete
# → Ask: "Clean up session files?"
# → User confirms
# → Delete: .tmp/sessions/20250118-143022-a4f2/
```

138
.opencode/context/core/workflows/task-delegation-basics.md Normal file
View File

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

143
.opencode/context/core/workflows/task-delegation-caching.md Normal file
View File

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

130
.opencode/context/core/workflows/task-delegation-specialists.md Normal file
View File

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

41
.opencode/context/development/ai/mastra-ai/concepts/agents-tools.md Normal file
View File

@@ -0,0 +1,41 @@
<!-- Context: development/agents-tools | Priority: critical | Version: 1.0 | Updated: 2026-02-15 -->
# Concept: Mastra Agents & Tools
**Purpose**: Reusable units of logic and LLM-powered entities.
**Last Updated**: 2026-01-09
---
## Core Idea
Agents are specialized LLM configurations that use Tools to interact with external systems or perform specific logic. Tools are the building blocks that provide functionality to both agents and workflows.
## Key Points
- **Agents**: Defined with a `name`, `instructions`, and `model`. They can be assigned a set of `tools`.
- **Tools**: Defined with `id`, `inputSchema`, `outputSchema`, and an `execute` function.
- **Type Safety**: Both agents and tools use Zod for schema validation.
- **Standalone Use**: Tools can be executed independently of agents, making them highly reusable.
## Quick Example
```typescript
// Tool
const myTool = createTool({
id: 'my-tool',
inputSchema: z.object({ query: z.string() }),
execute: async ({ inputData }) => ({ result: `Processed ${inputData.query}` }),
});
// Agent
const myAgent = new Agent({
name: 'My Agent',
instructions: 'Use my-tool to process queries.',
model: { provider: 'OPEN_AI', name: 'gpt-4o' },
tools: { myTool },
});
```
**Reference**: `src/mastra/agents/`, `src/mastra/tools/`
**Related**:
- concepts/core.md
- concepts/workflows.md

37
.opencode/context/development/ai/mastra-ai/concepts/core.md Normal file
View File

@@ -0,0 +1,37 @@
<!-- Context: development/core | Priority: critical | Version: 1.0 | Updated: 2026-02-15 -->
# Concept: Mastra Core
**Purpose**: Central orchestration layer for AI agents, workflows, and tools in this project.
**Last Updated**: 2026-01-09
---
## Core Idea
Mastra is the central hub that wires together agents, tools, workflows, and observability. It provides a unified interface for executing complex AI tasks with built-in persistence and logging.
## Key Points
- **Centralized Config**: All components are registered in `src/mastra/index.ts`.
- **Persistence**: Uses `LibSQLStore` (SQLite) for storing traces, spans, and workflow states.
- **Observability**: Built-in tracing and logging (Pino) for every execution.
- **Modular Design**: Agents, tools, and workflows are defined separately and composed in the main instance.
## Quick Example
```typescript
import { Mastra } from '@mastra/core/mastra';
import { agents, tools, workflows } from './components';
export const mastra = new Mastra({
agents,
tools,
workflows,
storage: new LibSQLStore({ url: 'file:./mastra.db' }),
});
```
**Reference**: `src/mastra/index.ts`
**Related**:
- concepts/workflows.md
- concepts/agents-tools.md
- lookup/mastra-config.md

41
.opencode/context/development/ai/mastra-ai/concepts/evaluations.md Normal file
View File

@@ -0,0 +1,41 @@
<!-- Context: development/evaluations | Priority: critical | Version: 1.0 | Updated: 2026-02-15 -->
# Concept: Mastra Evaluations
**Purpose**: Quality assurance and scoring for LLM outputs.
**Last Updated**: 2026-01-09
---
## Core Idea
Evaluations in Mastra use Scorers to assess the quality, accuracy, and safety of LLM-generated content. They provide a quantitative way to measure performance and detect issues like hallucinations or factual errors.
## Key Points
- **Scorers**: Specialized functions that take LLM output (and optionally ground truth) and return a score (0-1).
- **Integration**: Registered in the Mastra instance and can be triggered automatically during workflow execution.
- **Metrics**: Common metrics include hallucination detection, fact validation, and relevance scoring.
- **Audit Trail**: Scorer results are stored in the `mastra_scorers` table for long-term analysis and reporting.
## Quick Example
```typescript
// Scorer definition
export const hallucinationDetector = new Scorer({
id: 'hallucination-detector',
description: 'Detects hallucinations in LLM output',
execute: async ({ output, context }) => {
// Logic to detect hallucinations
return { score: 0.95, rationale: 'No hallucinations found' };
},
});
// Registration
export const mastra = new Mastra({
scorers: { hallucinationDetector },
});
```
**Reference**: `src/mastra/scorers/`, `src/mastra/evaluation/`
**Related**:
- concepts/core.md
- concepts/workflows.md

38
.opencode/context/development/ai/mastra-ai/concepts/storage.md Normal file
View File

@@ -0,0 +1,38 @@
<!-- Context: development/storage | Priority: critical | Version: 1.0 | Updated: 2026-02-15 -->
# Concept: Mastra Data Storage
**Purpose**: Persistence layer for cases, documents, assessments, and observability.
**Last Updated**: 2026-01-09
---
## Core Idea
Mastra uses a dual-storage approach: a local SQLite database (via Drizzle ORM) for business entities and a built-in `LibSQLStore` for Mastra-specific execution data (traces, spans).
## Key Points
- **Business Entities**: Managed in `src/db/schema.ts`. Includes `cases`, `documents`, `assessments`, and `outputs`.
- **Mastra Store**: `LibSQLStore` handles `mastra_traces`, `mastra_ai_spans`, and `mastra_scorers`.
- **V3 Extensions**: Specific tables for `timeline_events`, `evidence_gaps`, `sub_claims`, and `vulnerability_flags`.
- **Observability**: `prompt_execution_traces` provides detailed cost and token tracking per AI call.
- **File Storage**: Large blobs (PDFs, JSON outputs) are stored in `./tmp/` with paths referenced in the DB.
## Quick Example
```typescript
// Business Schema (Drizzle)
export const cases = sqliteTable('cases', {
id: text('id').primaryKey(),
status: text('status').default('new'),
});
// Mastra Store Config
storage: new LibSQLStore({
url: process.env.MASTRA_DB_PATH || 'file:./mastra.db',
}),
```
**Reference**: `src/db/schema.ts`, `src/mastra/index.ts`
**Related**:
- concepts/core.md
- lookup/mastra-config.md

35
.opencode/context/development/ai/mastra-ai/concepts/workflows.md Normal file
View File

@@ -0,0 +1,35 @@
<!-- Context: development/workflows | Priority: critical | Version: 1.0 | Updated: 2026-02-15 -->
# Concept: Mastra Workflows
**Purpose**: Linear and parallel execution chains for complex AI tasks.
**Last Updated**: 2026-01-09
---
## Core Idea
Workflows in Mastra are directed graphs of steps that process data sequentially or in parallel. They provide a structured way to handle multi-stage LLM operations with built-in state management and human-in-the-loop (HITL) support.
## Key Points
- **Step Definition**: Created with `createStep`, requiring `inputSchema`, `outputSchema`, and an `execute` function.
- **Chaining**: Steps are linked using `.then()` for sequential and `.parallel()` for concurrent execution.
- **HITL Support**: Steps can `suspend` execution to wait for human input and `resume` when data is provided.
- **State Access**: Each step has access to the global workflow `state` and the `inputData` from the previous step.
## Quick Example
```typescript
const workflow = createWorkflow({ id: 'my-workflow', inputSchema, outputSchema })
.then(step1)
.parallel([step2a, step2b])
.then(mergeStep)
.commit();
const { runId, start } = workflow.createRun();
const result = await start({ inputData: { ... } });
```
**Reference**: `src/mastra/workflows/`
**Related**:
- concepts/core.md
- examples/workflow-example.md

33
.opencode/context/development/ai/mastra-ai/errors/mastra-errors.md Normal file
View File

@@ -0,0 +1,33 @@
<!-- Context: development/mastra-errors | Priority: medium | Version: 1.0 | Updated: 2026-02-15 -->
# Errors: Mastra Implementation
**Purpose**: Common errors, their causes, and recovery strategies.
**Last Updated**: 2026-01-09
---
## Core Idea
Errors in Mastra typically fall into three categories: AI generation failures, structured output validation errors, and context/resource missing errors.
## Key Points
- **AIGenerationError**: Occurs when the LLM fails to generate a response (e.g., safety filters, model downtime).
- **StructuredOutputError**: Triggered when the LLM response doesn't match the Zod schema defined in the tool or step.
- **RateLimitError**: Hit when exceeding provider limits. Includes a `retryAfter` value.
- **MastraContextError**: Raised when a required resource (like `services` or `mastra` instance) is missing from the execution context.
- **Retry Strategy**: Use `isRetryableError(error)` to determine if a transient failure can be recovered with exponential backoff.
## Common Errors Table
| Error | Cause | Fix |
|-------|-------|-----|
| `StructuredOutputError` | LLM hallucinated wrong JSON | Refine prompt or use simpler schema |
| `RateLimitError` | Too many concurrent requests | Implement rate limiting or increase quota |
| `NotFoundError` | Case or Document ID missing in DB | Check DB state before workflow start |
| `MastraContextError` | `services` not passed to tool | Ensure `services` is in `ToolExecutionContext` |
**Reference**: `src/lib/errors.ts`
**Related**:
- concepts/core.md
- guides/testing.md

42
.opencode/context/development/ai/mastra-ai/examples/workflow-example.md Normal file
View File

@@ -0,0 +1,42 @@
<!-- Context: development/workflow-example | Priority: high | Version: 1.0 | Updated: 2026-02-15 -->
# Example: Document Ingestion Workflow
**Purpose**: Demonstrates a multi-step workflow with parallel processing.
**Last Updated**: 2026-01-09
---
## Workflow Definition
```typescript
export const documentIngestionWorkflow = createWorkflow({
id: 'document-ingestion',
inputSchema: z.object({ filename: z.string(), fileBuffer: z.any() }),
outputSchema: z.object({ documentId: z.string(), success: z.boolean() }),
})
.then(uploadStep) // Step 1: Upload
.then(extractionStep) // Step 2: Extract Text
.parallel([ // Step 3: Process in parallel
classificationStep,
summarizationStep
])
.then(mergeResultsStep) // Step 4: Merge
.commit();
```
## Step Execution
```typescript
const uploadStep = createStep({
id: 'upload-document',
execute: async ({ inputData, mastra }) => {
const result = await documentUploadTool.execute(inputData, { mastra });
return result;
},
});
```
**Reference**: `src/mastra/workflows/document-ingestion-with-classification-workflow.ts`
**Related**:
- concepts/workflows.md
- concepts/agents-tools.md

37
.opencode/context/development/ai/mastra-ai/guides/modular-building.md Normal file
View File

@@ -0,0 +1,37 @@
<!-- Context: development/modular-building | Priority: high | Version: 1.0 | Updated: 2026-02-15 -->
# Guide: Modular Mastra Building
**Purpose**: Best practices for structuring a large-scale Mastra implementation.
**Last Updated**: 2026-01-09
---
## Core Idea
Modular building ensures that as the project grows, components remain testable, reusable, and easy to navigate. This is achieved by separating logic into specialized directories and using a central registry.
## Key Points
- **Component Separation**: Keep `agents`, `tools`, `workflows`, and `scorers` in their own top-level directories within `src/mastra/`.
- **Shared Services**: Use a `shared.ts` file to instantiate services (DB, repositories) to prevent circular dependencies between workflows and the main Mastra instance.
- **Central Registry**: Register all components in `src/mastra/index.ts`. This is the single source of truth for the Mastra instance.
- **Feature-Based Steps**: Group related workflow steps into sub-directories (e.g., `src/mastra/workflows/v3/steps/`) to keep workflow files clean.
## Quick Example
```typescript
// src/mastra/shared.ts
export const services = createServices();
// src/mastra/index.ts
import { services } from './shared';
export const mastra = new Mastra({
workflows: { myWorkflow },
agents: { myAgent },
// ...
});
```
**Reference**: `src/mastra/index.ts`, `src/mastra/shared.ts`
**Related**:
- concepts/core.md
- guides/workflow-step-structure.md

35
.opencode/context/development/ai/mastra-ai/guides/testing.md Normal file
View File

@@ -0,0 +1,35 @@
<!-- Context: development/testing | Priority: high | Version: 1.0 | Updated: 2026-02-15 -->
# Guide: Testing Mastra
**Purpose**: How to run and validate Mastra components in this project.
**Last Updated**: 2026-01-09
---
## Core Idea
Testing in this project is divided into tool-level tests and full workflow integration tests. Use the provided bun --bun scripts for rapid validation.
## Key Points
- **Tool Tests**: Validate individual tools in isolation (e.g., `bun --bun run test:playbook`).
- **Workflow Tests**: Run full end-to-end scenarios (e.g., `bun --bun run test:workflow`).
- **Baseline Tests**: Compare current performance against a known baseline (`bun --bun run test:baseline`).
- **Observability**: Use `bun --bun run traces` after tests to inspect the execution details in the database.
## Quick Example
```bash
# Test a specific tool
bun --bun run test:calculator
# Run full validity workflow
bun --bun run validity:workflow
# View results of the last run
bun --bun run traces
```
**Reference**: `package.json` scripts, `scripts/` directory
**Related**:
- concepts/core.md
- lookup/mastra-config.md

40
.opencode/context/development/ai/mastra-ai/guides/workflow-step-structure.md Normal file
View File

@@ -0,0 +1,40 @@
<!-- Context: development/workflow-step-structure | Priority: high | Version: 1.0 | Updated: 2026-02-15 -->
# Guide: Workflow Step Structure
**Purpose**: Standardized pattern for defining maintainable and testable workflow steps.
**Last Updated**: 2026-01-09
---
## Core Idea
Workflow steps should be self-contained units that encapsulate their input/output schemas and execution logic. For complex workflows, steps should be moved to a dedicated `steps/` directory and grouped by phase.
## Key Points
- **Directory Structure**: Group steps by phase (e.g., `steps/phase1-load.ts`, `steps/phase2-process.ts`).
- **Schema Centralization**: Define shared schemas (like `workflowStateSchema`) in a `schemas.ts` file within the steps directory.
- **Explicit State**: Use `stateSchema` in `createStep` to ensure type safety when accessing the global workflow state.
- **Tool Delegation**: Steps should primarily act as orchestrators, delegating heavy lifting to Tools.
- **Logging**: Include clear console logs at the start and end of each step for easier debugging.
## Quick Example
```typescript
// src/mastra/workflows/v3/steps/phase1.ts
export const myStep = createStep({
id: 'my-step-id',
inputSchema: z.object({ ... }),
outputSchema: z.object({ ... }),
stateSchema: workflowStateSchema,
execute: async ({ inputData, state, mastra }) => {
console.log('🚀 Starting myStep...');
const result = await myTool.execute(inputData, { mastra });
return result;
},
});
```
**Reference**: `src/mastra/workflows/v3/steps/`
**Related**:
- concepts/workflows.md
- guides/modular-building.md

41
.opencode/context/development/ai/mastra-ai/lookup/mastra-config.md Normal file
View File

@@ -0,0 +1,41 @@
<!-- Context: development/mastra-config | Priority: high | Version: 1.0 | Updated: 2026-02-15 -->
# Lookup: Mastra Configuration
**Purpose**: Quick reference for Mastra file locations and registration.
**Last Updated**: 2026-01-09
---
## File Locations
| Component | Directory | Registration File |
|-----------|-----------|-------------------|
| **Mastra Instance** | `src/mastra/` | `src/mastra/index.ts` |
| **Agents** | `src/mastra/agents/` | `src/mastra/index.ts` |
| **Tools** | `src/mastra/tools/` | `src/mastra/index.ts` |
| **Workflows** | `src/mastra/workflows/` | `src/mastra/index.ts` |
| **Scorers** | `src/mastra/scorers/` | `src/mastra/index.ts` |
| **Services** | `src/services/` | `src/mastra/shared.ts` |
## Database Tables
| Table Name | Description |
|------------|-------------|
| `mastra_traces` | Workflow execution traces |
| `mastra_ai_spans` | LLM call spans and token usage |
| `mastra_scorers` | Evaluation results and scores |
| `mastra_workflow_state` | Current state of running workflows |
## Common Commands
| Command | Description |
|---------|-------------|
| `bun --bun run dev` | Start Mastra in development mode |
| `bun --bun run traces` | View recent execution traces |
| `bun --bun run test:workflow` | Run the test workflow script |
**Related**:
- concepts/core.md
- concepts/workflows.md

31
.opencode/context/development/ai/navigation.md Normal file
View File

@@ -0,0 +1,31 @@
<!-- Context: development/navigation | Priority: critical | Version: 1.0 | Updated: 2026-02-15 -->
# AI Navigation
**Purpose**: AI frameworks, agent runtimes, and LLM integration patterns.
---
## Structure
```
ai/
├── navigation.md
└── mastra-ai/
├── navigation.md
└── [patterns].md
```
---
## Quick Routes
| Task | Path |
|------|------|
| **MAStra AI** | `mastra-ai/navigation.md` |
---
## By Technology
**MAStra AI** → AI framework for building agents and workflows.

79
.opencode/context/development/backend-navigation.md Normal file
View File

@@ -0,0 +1,79 @@
<!-- Context: development/navigation | Priority: low | Version: 1.0 | Updated: 2026-02-15 -->
# Backend Development Navigation
**Scope**: Server-side, APIs, databases, auth
---
## Structure
```
development/backend/ # [future]
├── navigation.md
│
├── api-patterns/ # Approach-based
│ ├── rest-design.md
│ ├── graphql-design.md
│ ├── grpc-patterns.md
│ └── websocket-patterns.md
│
├── nodejs/ # Tech-specific
│ ├── express-patterns.md
│ ├── fastify-patterns.md
│ └── error-handling.md
│
├── python/
│ ├── fastapi-patterns.md
│ └── django-patterns.md
│
├── authentication/ # Functional concern
│ ├── jwt-patterns.md
│ ├── oauth-patterns.md
│ └── session-management.md
│
└── middleware/
├── logging.md
├── rate-limiting.md
└── cors.md
```
---
## Quick Routes
| Task | Path |
|------|------|
| **REST API** | `backend/api-patterns/rest-design.md` [future] |
| **GraphQL** | `backend/api-patterns/graphql-design.md` [future] |
| **API design principles** | `principles/api-design.md` |
| **Node.js** | `backend/nodejs/express-patterns.md` [future] |
| **Python** | `backend/python/fastapi-patterns.md` [future] |
| **Auth (JWT)** | `backend/authentication/jwt-patterns.md` [future] |
---
## By Approach
**REST** → `backend/api-patterns/rest-design.md` [future]
**GraphQL** → `backend/api-patterns/graphql-design.md` [future]
**gRPC** → `backend/api-patterns/grpc-patterns.md` [future]
## By Language
**Node.js** → `backend/nodejs/` [future]
**Python** → `backend/python/` [future]
## By Concern
**Authentication** → `backend/authentication/` [future]
**Middleware** → `backend/middleware/` [future]
**Data layer** → `data/` [future]
---
## Related Context
- **API Design Principles** → `principles/api-design.md`
- **Core Standards** → `../core/standards/code-quality.md`
- **Data Patterns** → `data/navigation.md` [future]

57
.opencode/context/development/backend/navigation.md Normal file
View File

@@ -0,0 +1,57 @@
<!-- Context: development/navigation | Priority: critical | Version: 1.0 | Updated: 2026-02-15 -->
# Backend Development Navigation
**Purpose**: Server-side development patterns
**Status**: 🚧 Placeholder - Content coming soon
---
## Planned Structure
```
backend/
├── navigation.md
│
├── api-patterns/ # Approach-based
│ ├── rest-design.md
│ ├── graphql-design.md
│ ├── grpc-patterns.md
│ └── trpc-patterns.md
│
├── nodejs/ # Tech-specific
│ ├── express-patterns.md
│ ├── fastify-patterns.md
│ └── nextjs-api-routes.md
│
├── python/
│ ├── fastapi-patterns.md
│ └── django-patterns.md
│
├── authentication/ # Functional concern
│ ├── jwt-patterns.md
│ ├── oauth-patterns.md
│ └── session-management.md
│
└── middleware/
├── logging.md
├── rate-limiting.md
└── cors.md
```
---
## For Now
Use specialized navigation: `../backend-navigation.md`
Also see: `../principles/api-design.md`
---
## Related Context
- **Backend Navigation** → `../backend-navigation.md`
- **API Design Principles** → `../principles/api-design.md`
- **Core Standards** → `../../core/standards/code-quality.md`

38
.opencode/context/development/data/navigation.md Normal file
View File

@@ -0,0 +1,38 @@
<!-- Context: development/navigation | Priority: critical | Version: 1.0 | Updated: 2026-02-15 -->
# Data Layer Navigation
**Purpose**: Database and data access patterns
**Status**: 🚧 Placeholder - Content coming soon
---
## Planned Structure
```
data/
├── navigation.md
│
├── sql-patterns/
│ ├── postgres-patterns.md
│ ├── mysql-patterns.md
│ └── query-optimization.md
│
├── nosql-patterns/
│ ├── mongodb-patterns.md
│ ├── redis-patterns.md
│ └── dynamodb-patterns.md
│
└── orm-patterns/
├── prisma-patterns.md
├── typeorm-patterns.md
└── sequelize-patterns.md
```
---
## Related Context
- **Backend Navigation** → `../backend-navigation.md`
- **Core Standards** → `../../core/standards/code-quality.md`

31
.opencode/context/development/frameworks/navigation.md Normal file
View File

@@ -0,0 +1,31 @@
<!-- Context: development/navigation | Priority: critical | Version: 1.0 | Updated: 2026-02-15 -->
# Frameworks Navigation
**Purpose**: Full-stack and meta-frameworks that span multiple architectural layers.
---
## Structure
```
frameworks/
├── navigation.md
└── tanstack-start/
├── navigation.md
└── [patterns].md
```
---
## Quick Routes
| Task | Path |
|------|------|
| **Tanstack Start** | `tanstack-start/navigation.md` |
---
## By Framework
**Tanstack Start** → Full-stack React framework with SSR and server functions.

42
.opencode/context/development/frontend/navigation.md Normal file
View File

@@ -0,0 +1,42 @@
<!-- Context: development/navigation | Priority: critical | Version: 1.0 | Updated: 2026-02-15 -->
# Frontend Development Navigation
**Purpose**: Client-side development patterns
---
## Structure
```
frontend/
├── navigation.md
├── when-to-delegate.md
└── react/
├── navigation.md
└── react-patterns.md
```
---
## Quick Routes
| Task | Path |
|------|------|
| **When to delegate** | `when-to-delegate.md` |
| **React patterns** | `react/react-patterns.md` |
| **React navigation** | `react/navigation.md` |
---
## By Framework
**React** → `react/` - Modern React patterns, hooks, component design
---
## Related Context
- **UI Navigation** → `../ui-navigation.md`
- **Visual Design** → `../../ui/web/navigation.md`
- **Core Standards** → `../../core/standards/code-quality.md`

468
.opencode/context/development/frontend/when-to-delegate.md Normal file
View File

@@ -0,0 +1,468 @@
<!-- Context: development/frontend/when-to-delegate | Priority: high | Version: 1.0 | Updated: 2026-01-30 -->
# When to Delegate to Frontend Specialist
## Overview
Clear decision criteria for when to delegate frontend/UI work to the **frontend-specialist** subagent vs. handling it directly.
## Quick Reference
**Delegate to frontend-specialist when**:
- UI/UX design work (wireframes, themes, animations)
- Design system implementation
- Complex responsive layouts
- Animation and micro-interactions
- Visual design iterations
**Handle directly when**:
- Simple HTML/CSS edits
- Single component updates
- Bug fixes in existing UI
- Minor styling tweaks
---
## Decision Matrix
### ✅ DELEGATE to Frontend-Specialist
| Scenario | Why Delegate | Example |
|----------|--------------|---------|
| **New UI design from scratch** | Needs staged workflow (layout → theme → animation → implement) | "Create a landing page for our product" |
| **Design system work** | Requires ContextScout for standards, ExternalScout for UI libs | "Implement our design system with Tailwind + Shadcn" |
| **Complex responsive layouts** | Needs mobile-first approach across breakpoints | "Build a dashboard with sidebar, cards, and responsive grid" |
| **Animation implementation** | Requires animation patterns, performance optimization | "Add smooth transitions and micro-interactions to the UI" |
| **Multi-stage design iterations** | Needs versioning (design_iterations/ folder) | "Design a checkout flow with 3 steps" |
| **Theme creation** | Requires OKLCH colors, CSS custom properties | "Create a dark mode theme for the app" |
| **Component library integration** | Needs ExternalScout for current docs (Flowbite, Radix, etc.) | "Integrate Flowbite components into our app" |
| **Accessibility-focused UI** | Requires WCAG compliance, ARIA attributes | "Build an accessible form with proper labels and validation" |
### ⚠️ HANDLE DIRECTLY (Don't Delegate)
| Scenario | Why Direct | Example |
|----------|------------|---------|
| **Simple HTML edits** | Single file, straightforward change | "Change the button text from 'Submit' to 'Send'" |
| **Minor CSS tweaks** | Small styling adjustment | "Make the header padding 20px instead of 16px" |
| **Bug fixes** | Fixing existing code, not creating new design | "Fix the broken link in the footer" |
| **Content updates** | Changing text, images, or data | "Update the hero section copy" |
| **Single component updates** | Modifying one existing component | "Add a new prop to the Button component" |
| **Quick prototypes** | Throwaway code for testing | "Create a quick HTML mockup to test an idea" |
---
## Delegation Checklist
Before delegating to frontend-specialist, ensure:
- [ ] **Task is UI/design focused** (not backend, logic, or data)
- [ ] **Task requires design expertise** (layout, theme, animations)
- [ ] **Task benefits from staged workflow** (layout → theme → animation → implement)
- [ ] **Task needs context discovery** (design systems, UI libraries, standards)
- [ ] **User has approved the approach** (never delegate before approval)
---
## How to Delegate
### Step 1: Discover Context (Optional but Recommended)
If you're unsure what context the frontend-specialist will need:
```javascript
task(
subagent_type="ContextScout",
description="Find frontend design context",
prompt="Find design system standards, UI component patterns, animation guidelines, and responsive breakpoint conventions for frontend work."
)
```
### Step 2: Propose Approach
Present a plan to the user:
```markdown
## Implementation Plan
**Task**: Create landing page with hero section, features grid, and CTA
**Approach**: Delegate to frontend-specialist subagent
**Why**:
- Requires design system implementation
- Needs responsive layout across breakpoints
- Includes animations and micro-interactions
- Benefits from staged workflow (layout → theme → animation → implement)
**Context Needed**:
- Design system standards (ui/web/design-systems.md)
- UI styling standards (ui/web/ui-styling-standards.md)
- Animation patterns (ui/web/animation-patterns.md)
**Approval needed before proceeding.**
```
### Step 3: Get Approval
Wait for explicit user approval before delegating.
### Step 4: Delegate with Context
**For simple delegation** (no session needed):
```javascript
task(
subagent_type="frontend-specialist",
description="Create landing page design",
prompt="Context to load:
- .opencode/context/ui/web/design-systems.md
- .opencode/context/ui/web/ui-styling-standards.md
- .opencode/context/ui/web/animation-basics.md
Task: Create a landing page with:
- Hero section with headline, subheadline, CTA button
- Features grid (3 columns on desktop, 1 on mobile)
- Smooth scroll animations
Requirements:
- Use Tailwind CSS + Flowbite
- Mobile-first responsive design
- Animations <400ms
- Save to design_iterations/landing_1.html
Follow your staged workflow:
1. Layout (ASCII wireframe)
2. Theme (CSS theme file)
3. Animation (micro-interactions)
4. Implement (HTML file)
Request approval between each stage."
)
```
**For complex delegation** (with session):
Create session context file first, then delegate with session path.
---
## Common Patterns
### Pattern 1: New Landing Page
**Trigger**: User asks for a new landing page, marketing page, or product page
**Decision**: ✅ Delegate to frontend-specialist
**Why**: Requires full design workflow (layout, theme, animations, implementation)
**Example**:
```
User: "Create a landing page for our SaaS product"
You: [Propose approach] → [Get approval] → [Delegate to frontend-specialist]
```
### Pattern 2: Design System Implementation
**Trigger**: User wants to implement or update a design system
**Decision**: ✅ Delegate to frontend-specialist
**Why**: Needs ContextScout for standards, ExternalScout for UI library docs
**Example**:
```
User: "Implement our design system using Tailwind and Shadcn"
You: [Propose approach] → [Get approval] → [Delegate to frontend-specialist]
```
### Pattern 3: Component Library Integration
**Trigger**: User wants to integrate a UI component library (Flowbite, Radix, etc.)
**Decision**: ✅ Delegate to frontend-specialist
**Why**: Requires ExternalScout for current docs, proper integration patterns
**Example**:
```
User: "Add Flowbite components to our app"
You: [Propose approach] → [Get approval] → [Delegate to frontend-specialist]
```
### Pattern 4: Animation Work
**Trigger**: User wants animations, transitions, or micro-interactions
**Decision**: ✅ Delegate to frontend-specialist
**Why**: Requires animation patterns, performance optimization (<400ms)
**Example**:
```
User: "Add smooth animations to the dashboard"
You: [Propose approach] → [Get approval] → [Delegate to frontend-specialist]
```
### Pattern 5: Simple HTML Edit
**Trigger**: User wants to change text, fix a link, or update content
**Decision**: ⚠️ Handle directly (don't delegate)
**Why**: Simple edit, no design work needed
**Example**:
```
User: "Change the button text to 'Get Started'"
You: [Edit the HTML file directly]
```
### Pattern 6: CSS Bug Fix
**Trigger**: User reports a styling bug or broken layout
**Decision**: ⚠️ Handle directly (don't delegate)
**Why**: Bug fix, not new design work
**Example**:
```
User: "The header is overlapping the content on mobile"
You: [Read the CSS, fix the issue directly]
```
---
## Red Flags (Don't Delegate)
❌ **User just wants a quick fix** → Handle directly
❌ **Task is backend/logic focused** → Wrong subagent (use coder-agent or handle directly)
❌ **Task is a single line change** → Handle directly
❌ **Task is content update** → Handle directly
❌ **Task is testing/validation** → Wrong subagent (use tester)
❌ **Task is code review** → Wrong subagent (use reviewer)
---
## Green Flags (Delegate)
✅ **User wants a new UI design** → Delegate
✅ **Task involves design systems** → Delegate
✅ **Task requires responsive layouts** → Delegate
✅ **Task includes animations** → Delegate
✅ **Task needs UI library integration** → Delegate
✅ **Task benefits from staged workflow** → Delegate
✅ **Task requires design expertise** → Delegate
---
## Frontend-Specialist Capabilities
**What it does well**:
- Create complete UI designs from scratch
- Implement design systems (Tailwind, Shadcn, Flowbite)
- Build responsive layouts (mobile-first)
- Add animations and micro-interactions
- Integrate UI component libraries
- Create themes with OKLCH colors
- Follow staged workflow (layout → theme → animation → implement)
- Version designs (design_iterations/ folder)
**What it doesn't do**:
- Backend logic or API integration
- Database queries or data processing
- Testing or validation
- Code review or refactoring
- Simple HTML/CSS edits (overkill)
- Content updates (just text changes)
---
## Context Files Frontend-Specialist Uses
The frontend-specialist will automatically load these via ContextScout:
**Design System**:
- `ui/web/design-systems.md` - Theme templates, color systems
- `ui/web/ui-styling-standards.md` - Tailwind, Flowbite, responsive design
- `ui/web/design-assets.md` - Images, icons, fonts
**Patterns**:
- `ui/web/animation-patterns.md` - Animation syntax, micro-interactions
- `development/frontend/react/react-patterns.md` - React patterns (if React project)
**Workflows**:
- `core/workflows/design-iteration-overview.md` - Design iteration workflow
---
## Best Practices
### Do's ✅
- ✅ **Propose before delegating** - Show user the plan first
- ✅ **Get approval** - Never delegate without user approval
- ✅ **Provide context** - List context files the subagent should load
- ✅ **Set clear requirements** - Specify design system, breakpoints, animations
- ✅ **Use staged workflow** - Let frontend-specialist follow its process
- ✅ **Trust the specialist** - It knows design patterns and best practices
### Don'ts ❌
- ❌ **Don't delegate simple edits** - Handle directly for efficiency
- ❌ **Don't skip approval** - Always get user sign-off first
- ❌ **Don't delegate backend work** - Wrong subagent
- ❌ **Don't micromanage** - Let the specialist follow its workflow
- ❌ **Don't delegate without context** - Provide context files to load
- ❌ **Don't delegate bug fixes** - Handle directly unless it's a design issue
---
## Examples
### Example 1: Landing Page (Delegate)
**User Request**: "Create a landing page for our SaaS product with a hero section, features, and pricing"
**Your Response**:
```markdown
## Implementation Plan
**Task**: Create SaaS landing page
**Approach**: Delegate to frontend-specialist subagent
**Why**:
- Requires full design workflow (layout, theme, animations)
- Needs responsive design across breakpoints
- Benefits from design system standards
**Context Needed**:
- Design system standards
- UI styling standards
- Animation patterns
**Approval needed before proceeding.**
```
**After Approval**:
```javascript
task(
subagent_type="frontend-specialist",
description="Create SaaS landing page",
prompt="Context to load:
- .opencode/context/ui/web/design-systems.md
- .opencode/context/ui/web/ui-styling-standards.md
- .opencode/context/ui/web/animation-basics.md
Task: Create a SaaS landing page with:
- Hero section (headline, subheadline, CTA)
- Features section (3-column grid)
- Pricing section (3 tiers)
- Footer
Requirements:
- Tailwind CSS + Flowbite
- Mobile-first responsive
- Smooth scroll animations
- Modern design system
Follow staged workflow and request approval between stages."
)
```
### Example 2: Button Text Change (Direct)
**User Request**: "Change the 'Submit' button to say 'Send Message'"
**Your Response**:
```markdown
I'll update the button text directly.
```
**Action**: Read the HTML file, edit the button text, done. No delegation needed.
---
### Example 3: Design System Implementation (Delegate)
**User Request**: "Implement our design system using Tailwind and Shadcn components"
**Your Response**:
```markdown
## Implementation Plan
**Task**: Implement design system with Tailwind + Shadcn
**Approach**: Delegate to frontend-specialist subagent
**Why**:
- Requires UI library integration (Shadcn)
- Needs ExternalScout for current Shadcn docs
- Benefits from design system standards
**Context Needed**:
- Design system standards
- UI styling standards
- External docs (Shadcn)
**Approval needed before proceeding.**
```
**After Approval**:
```javascript
task(
subagent_type="frontend-specialist",
description="Implement Tailwind + Shadcn design system",
prompt="Context to load:
- .opencode/context/ui/web/design-systems.md
- .opencode/context/ui/web/ui-styling-standards.md
Task: Implement design system using Tailwind CSS and Shadcn/ui
Requirements:
- Call ExternalScout for current Shadcn docs
- Set up Tailwind config
- Integrate Shadcn components
- Create theme file with OKLCH colors
- Document component usage
Follow staged workflow and request approval between stages."
)
```
---
## Summary
**Delegate to frontend-specialist when**:
- New UI designs from scratch
- Design system implementation
- Complex responsive layouts
- Animation work
- UI library integration
- Multi-stage design iterations
**Handle directly when**:
- Simple HTML/CSS edits
- Bug fixes
- Content updates
- Single component updates
- Quick prototypes
**Always**:
- Propose approach first
- Get user approval
- Provide context files
- Trust the specialist's workflow
---
## Related Context
- **Frontend Specialist Agent** → `../../../agent/subagents/development/frontend-specialist.md`
- **Design Systems** → `../../ui/web/design-systems.md`
- **UI Styling Standards** → `../../ui/web/ui-styling-standards.md`
- **Animation Patterns** → `../../ui/web/animation-patterns.md`
- **Delegation Workflow** → `../../core/workflows/task-delegation-basics.md`
- **React Patterns** → `react/react-patterns.md`

75
.opencode/context/development/fullstack-navigation.md Normal file
View File

@@ -0,0 +1,75 @@
<!-- Context: development/navigation | Priority: low | Version: 1.0 | Updated: 2026-02-15 -->
# Full-Stack Development Navigation
**Scope**: End-to-end application development
---
## Common Stacks
### MERN (MongoDB, Express, React, Node)
```
Frontend: development/frontend/react/ [future]
Backend: development/backend/nodejs/express-patterns.md [future]
Data: development/data/nosql-patterns/mongodb.md [future]
API: development/backend/api-patterns/rest-design.md [future]
```
### T3 Stack (Next.js, tRPC, Prisma, Tailwind)
```
Frontend: development/frontend/react/ + ui/web/ui-styling-standards.md [future]
Backend: development/backend/nodejs/ + api-patterns/trpc-patterns.md [future]
Data: development/data/orm-patterns/prisma.md [future]
```
### Python Full-Stack (FastAPI + React)
```
Frontend: development/frontend/react/ [future]
Backend: development/backend/python/fastapi-patterns.md [future]
Data: development/data/sql-patterns/ or nosql-patterns/ [future]
API: development/backend/api-patterns/rest-design.md [future]
```
---
## Quick Routes
| Layer | Navigate To |
|-------|-------------|
| **Frontend** | `ui-navigation.md` |
| **Backend** | `backend-navigation.md` |
| **Data** | `data/navigation.md` [future] |
| **Integration** | `integration/navigation.md` [future] |
| **Infrastructure** | `infrastructure/navigation.md` [future] |
---
## Common Workflows
**New API endpoint**:
1. `principles/api-design.md` (principles)
2. `backend/api-patterns/rest-design.md` (approach) [future]
3. `backend/nodejs/express-patterns.md` (implementation) [future]
**New React feature**:
1. `frontend/react/component-architecture.md` (structure) [future]
2. `frontend/react/hooks-patterns.md` (logic) [future]
3. `ui/web/ui-styling-standards.md` (styling)
**Database integration**:
1. `data/sql-patterns/` or `data/nosql-patterns/` (approach) [future]
2. `data/orm-patterns/` (if using ORM) [future]
3. `backend/nodejs/` or `backend/python/` (implementation) [future]
**Third-party service**:
1. `integration/third-party-services/` (patterns) [future]
2. `integration/api-integration/` (consuming APIs) [future]
---
## Related Context
- **Clean Code** → `principles/clean-code.md`
- **API Design** → `principles/api-design.md`
- **Core Standards** → `../core/standards/navigation.md`

33
.opencode/context/development/infrastructure/navigation.md Normal file
View File

@@ -0,0 +1,33 @@
<!-- Context: development/navigation | Priority: critical | Version: 1.0 | Updated: 2026-02-15 -->
# Infrastructure Navigation
**Purpose**: DevOps and deployment patterns
**Status**: 🚧 Placeholder - Content coming soon
---
## Planned Structure
```
infrastructure/
├── navigation.md
│
├── docker/
│ ├── dockerfile-patterns.md
│ ├── compose-patterns.md
│ └── optimization.md
│
└── ci-cd/
├── github-actions.md
├── deployment-patterns.md
└── testing-pipelines.md
```
---
## Related Context
- **Core Standards** → `../../core/standards/code-quality.md`
- **Testing** → `../../core/standards/test-coverage.md`

38
.opencode/context/development/integration/navigation.md Normal file
View File

@@ -0,0 +1,38 @@
<!-- Context: development/navigation | Priority: critical | Version: 1.0 | Updated: 2026-02-15 -->
# Integration Navigation
**Purpose**: Connecting systems and services
**Status**: 🚧 Placeholder - Content coming soon
---
## Planned Structure
```
integration/
├── navigation.md
│
├── package-management/
│ ├── npm-patterns.md
│ ├── pnpm-patterns.md
│ └── monorepo-patterns.md
│
├── api-integration/
│ ├── rest-client-patterns.md
│ ├── error-handling.md
│ └── retry-strategies.md
│
└── third-party-services/
├── stripe-integration.md
├── sendgrid-integration.md
└── cloudinary-integration.md
```
---
## Related Context
- **Backend Navigation** → `../backend-navigation.md`
- **API Design** → `../principles/api-design.md`

94
.opencode/context/development/navigation.md Normal file
View File

@@ -0,0 +1,94 @@
<!-- Context: development/navigation | Priority: critical | Version: 1.0 | Updated: 2026-02-15 -->
# Development Navigation
**Purpose**: Software development across all stacks
---
## Structure
```
development/
├── navigation.md
├── ui-navigation.md # Specialized
├── backend-navigation.md # Specialized
├── fullstack-navigation.md # Specialized
│
├── principles/ # Universal (language-agnostic)
│ ├── navigation.md
│ ├── clean-code.md
│ └── api-design.md
│
├── frameworks/ # Full-stack frameworks
│ ├── navigation.md
│ └── tanstack-start/
│
├── ai/ # AI & Agents
│ ├── navigation.md
│ └── mastra-ai/
│
├── frontend/ # Client-side
│ ├── navigation.md
│ ├── when-to-delegate.md # When to use frontend-specialist
│ └── react/
│ ├── navigation.md
│ └── react-patterns.md
│
├── backend/ # Server-side (future)
│ ├── navigation.md
│ ├── api-patterns/
│ ├── nodejs/
│ ├── python/
│ └── authentication/
│
├── data/ # Data layer (future)
│ ├── navigation.md
│ ├── sql-patterns/
│ ├── nosql-patterns/
│ └── orm-patterns/
│
├── integration/ # Connecting systems (future)
│ ├── navigation.md
│ ├── package-management/
│ ├── api-integration/
│ └── third-party-services/
│
└── infrastructure/ # DevOps (future)
├── navigation.md
├── docker/
└── ci-cd/
```
---
## Quick Routes
| Task | Path |
|------|------|
| **UI/Frontend** | `ui-navigation.md` |
| **When to delegate frontend** | `frontend/when-to-delegate.md` |
| **Backend/API** | `backend-navigation.md` |
| **Full-stack** | `fullstack-navigation.md` |
| **Clean code** | `principles/clean-code.md` |
| **API design** | `principles/api-design.md` |
---
## By Concern
**Principles** → Universal development practices
**Frameworks** → Full-stack frameworks (Tanstack Start, Next.js)
**AI** → AI frameworks and agent runtimes (MAStra AI)
**Frontend** → React patterns and component design
**Backend** → APIs, Node.js, Python, auth (future)
**Data** → SQL, NoSQL, ORMs (future)
**Integration** → Packages, APIs, services (future)
**Infrastructure** → Docker, CI/CD (future)
---
## Related Context
- **Core Standards** → `../core/standards/navigation.md`
- **UI Patterns** → `../ui/navigation.md`

417
.opencode/context/development/principles/api-design.md Normal file
View File

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

178
.opencode/context/development/principles/clean-code.md Normal file
View File

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

46
.opencode/context/development/principles/navigation.md Normal file
View File

@@ -0,0 +1,46 @@
<!-- Context: development/navigation | Priority: critical | Version: 1.0 | Updated: 2026-02-15 -->
# Development Principles Navigation
**Purpose**: Universal development principles (language-agnostic)
---
## Files
| File | Topic | Priority | Load When |
|------|-------|----------|-----------|
| `clean-code.md` | Clean code practices | ⭐⭐⭐⭐ | Writing any code |
| `api-design.md` | API design principles | ⭐⭐⭐⭐ | Designing APIs |
---
## Loading Strategy
**For general development**:
1. Load `clean-code.md` (high)
2. Also load: `../../core/standards/code-quality.md` (critical)
**For API development**:
1. Load `api-design.md` (high)
2. Also load: `../../core/standards/code-quality.md` (critical)
---
## Scope
**This directory**: Development-specific principles
**Core standards**: Universal standards (all projects, all languages)
| Location | Scope | Examples |
|----------|-------|----------|
| `core/standards/` | **Universal** (all projects) | Code quality, testing, docs, security |
| `development/principles/` | **Development-specific** | Clean code, API design, error handling |
---
## Related
- **Core Standards** → `../../core/standards/navigation.md`
- **Backend Patterns** → `../backend-navigation.md`
- **Frontend Patterns** → `../ui-navigation.md`

53
.opencode/context/development/ui-navigation.md Normal file
View File

@@ -0,0 +1,53 @@
<!-- Context: development/navigation | Priority: low | Version: 1.0 | Updated: 2026-02-15 -->
# UI Development Navigation
**Scope**: Frontend code + visual design
---
## Structure
```
Frontend Code (development/frontend/):
└── react/
├── navigation.md
└── react-patterns.md
Visual Design (ui/web/):
├── animation-patterns.md
├── ui-styling-standards.md
├── design-systems.md
└── design/
├── concepts/
└── examples/
```
---
## Quick Routes
| Task | Path |
|------|------|
| **React patterns** | `frontend/react/react-patterns.md` |
| **Animations** | `../../ui/web/animation-patterns.md` |
| **Styling** | `../../ui/web/ui-styling-standards.md` |
| **Design systems** | `../../ui/web/design-systems.md` |
---
## By Framework
**React** → `frontend/react/`
## By Concern
**Code patterns** → `development/frontend/`
**Visual design** → `ui/web/`
---
## Related Context
- **Core Standards** → `../core/standards/code-quality.md`
- **UI Category** → `../ui/navigation.md`

49
.opencode/context/navigation.md Normal file
View File

@@ -0,0 +1,49 @@
<!-- Context: core/navigation | Priority: critical | Version: 1.0 | Updated: 2026-02-15 -->
# Context Navigation
**New here?** → `openagents-repo/quick-start.md`
---
## Structure
```
.opencode/context/
├── core/ # Universal standards & workflows
├── openagents-repo/ # OpenAgents Control repository work
├── development/ # Software development (all stacks)
├── ui/ # Visual design & UX
├── content-creation/ # Content creation (all formats)
├── data/ # Data engineering & analytics
├── product/ # Product management
└── learning/ # Educational content
```
---
## Quick Routes
| Task | Path |
|------|------|
| **Write code** | `core/standards/code-quality.md` |
| **Write tests** | `core/standards/test-coverage.md` |
| **Write docs** | `core/standards/documentation.md` |
| **Review code** | `core/workflows/code-review.md` |
| **Delegate task** | `core/workflows/task-delegation-basics.md` |
| **Add agent** | `openagents-repo/guides/adding-agent.md` |
| **UI development** | `development/ui-navigation.md` |
| **API development** | `development/backend-navigation.md` |
---
## By Category
**core/** - Standards, workflows, patterns → `core/navigation.md`
**openagents-repo/** - Repository-specific → `openagents-repo/navigation.md`
**development/** - All development → `development/navigation.md`
**ui/** - Design & UX → `ui/navigation.md`
**content-creation/** - Content creation (all formats) → `content-creation/navigation.md`
**data/** - Data engineering → `data/navigation.md`
**product/** - Product management → `product/navigation.md`
**learning/** - Educational → `learning/navigation.md`

257
.opencode/context/openagents-repo/blueprints/context-bundle-template.md Normal file
View File

@@ -0,0 +1,257 @@
<!-- Context: openagents-repo/context-bundle-template | Priority: low | Version: 1.0 | Updated: 2026-02-15 -->
---
description: "Template for creating context bundles when delegating tasks to subagents"
type: "context"
category: "openagents-repo"
tags: [template, delegation, context]
---
# Context Bundle Template
**Purpose**: Template for creating context bundles when delegating tasks to subagents
**Location**: `.tmp/context/{session-id}/bundle.md`
**Used by**: repo-manager agent when delegating to subagents
---
## Template
```markdown
# Context Bundle: {Task Name}
Session: {session-id}
Created: {ISO timestamp}
For: {subagent-name}
Status: in_progress
## Task Overview
{Brief description of what we're building/doing}
## User Request
{Original user request - what they asked for}
## Relevant Standards (Load These Before Starting)
**Core Standards**:
- `.opencode/context/core/standards/code-quality.md` → Modular, functional code patterns
- `.opencode/context/core/standards/test-coverage.md` → Testing requirements and TDD
- `.opencode/context/core/standards/documentation.md` → Documentation standards
- `.opencode/context/core/standards/security-patterns.md` → Error handling, security patterns
**Core Workflows**:
- `.opencode/context/core/workflows/task-delegation-basics.md` → Delegation process
- `.opencode/context/core/workflows/feature-breakdown.md` → Task breakdown methodology
- `.opencode/context/core/workflows/code-review.md` → Code review guidelines
## Repository-Specific Context (Load These Before Starting)
**Quick Start** (ALWAYS load first):
- `.opencode/context/openagents-repo/quick-start.md` → Repo orientation and common commands
**Core Concepts** (Load based on task type):
- `.opencode/context/openagents-repo/core-concepts/agents.md` → How agents work
- `.opencode/context/openagents-repo/core-concepts/evals.md` → How testing works
- `.opencode/context/openagents-repo/core-concepts/registry.md` → How registry works
- `.opencode/context/openagents-repo/core-concepts/categories.md` → How organization works
**Guides** (Load for specific workflows):
- `.opencode/context/openagents-repo/guides/adding-agent-basics.md` → Step-by-step agent creation
- `.opencode/context/openagents-repo/guides/testing-agent.md` → Testing workflow
- `.opencode/context/openagents-repo/guides/updating-registry.md` → Registry workflow
- `.opencode/context/openagents-repo/guides/debugging.md` → Troubleshooting
**Lookup** (Quick reference):
- `.opencode/context/openagents-repo/lookup/file-locations.md` → Where everything is
- `.opencode/context/openagents-repo/lookup/commands.md` → Command reference
## Key Requirements
{Extract key requirements from loaded context}
**From Standards**:
- {requirement 1 from standards/code-quality.md}
- {requirement 2 from standards/test-coverage.md}
- {requirement 3 from standards/documentation.md}
**From Repository Context**:
- {requirement 1 from repo context}
- {requirement 2 from repo context}
- {requirement 3 from repo context}
**Naming Conventions**:
- {convention 1}
- {convention 2}
**File Structure**:
- {structure requirement 1}
- {structure requirement 2}
## Technical Constraints
{List technical constraints and limitations}
- {constraint 1 - e.g., "Must use TypeScript"}
- {constraint 2 - e.g., "Must follow category-based organization"}
- {constraint 3 - e.g., "Must include proper frontmatter metadata"}
## Files to Create/Modify
{List all files that need to be created or modified}
**Create**:
- `{file-path-1}` - {purpose and what it should contain}
- `{file-path-2}` - {purpose and what it should contain}
**Modify**:
- `{file-path-3}` - {what needs to be changed}
- `{file-path-4}` - {what needs to be changed}
## Success Criteria
{Define what "done" looks like - binary pass/fail conditions}
- [ ] {criteria 1 - e.g., "Agent file created with proper frontmatter"}
- [ ] {criteria 2 - e.g., "Eval tests pass"}
- [ ] {criteria 3 - e.g., "Registry validation passes"}
- [ ] {criteria 4 - e.g., "Documentation updated"}
## Validation Requirements
{How to validate the work}
**Scripts to Run**:
- `{validation-script-1}` - {what it validates}
- `{validation-script-2}` - {what it validates}
**Tests to Run**:
- `{test-command-1}` - {what it tests}
- `{test-command-2}` - {what it tests}
**Manual Checks**:
- {check 1}
- {check 2}
## Expected Output
{What the subagent should produce}
**Deliverables**:
- {deliverable 1}
- {deliverable 2}
**Format**:
- {format requirement 1}
- {format requirement 2}
## Progress Tracking
{Track progress through the task}
- [ ] Context loaded and understood
- [ ] {step 1}
- [ ] {step 2}
- [ ] {step 3}
- [ ] Validation passed
- [ ] Documentation updated
---
## Instructions for Subagent
{Specific, detailed instructions for the subagent}
**IMPORTANT**:
1. Load ALL context files listed in "Relevant Standards" and "Repository-Specific Context" sections BEFORE starting work
2. Follow ALL requirements from the loaded context
3. Apply naming conventions and file structure requirements
4. Validate your work using the validation requirements
5. Update progress tracking as you complete steps
**Your Task**:
{Detailed description of what the subagent needs to do}
**Approach**:
{Suggested approach or methodology}
**Constraints**:
{Any additional constraints or notes}
**Questions/Clarifications**:
{Any questions the subagent should consider or clarifications needed}
```
---
## Usage Instructions
### When to Create a Context Bundle
Create a context bundle when:
- Delegating to any subagent
- Task requires coordination across multiple components
- Subagent needs project-specific context
- Task has complex requirements or constraints
### How to Create a Context Bundle
1. **Create session directory**:
```bash
mkdir -p .tmp/context/{session-id}
```
2. **Copy template**:
```bash
cp .opencode/context/openagents-repo/templates/context-bundle-template.md \
.tmp/context/{session-id}/bundle.md
```
3. **Fill in all sections**:
- Replace all `{placeholders}` with actual values
- List specific context files to load (with full paths)
- Extract key requirements from loaded context
- Define clear success criteria
- Provide specific instructions
4. **Pass to subagent**:
```javascript
task(
subagent_type="{SubagentName}",
description="Brief description",
prompt="Load context from .tmp/context/{session-id}/bundle.md before starting.
{Specific task instructions}
Follow all standards and requirements in the context bundle."
)
```
### Best Practices
**DO**:
- ✅ List context files with full paths (don't duplicate content)
- ✅ Extract key requirements from loaded context
- ✅ Define binary success criteria (pass/fail)
- ✅ Provide specific validation requirements
- ✅ Include clear instructions for subagent
- ✅ Track progress through the task
**DON'T**:
- ❌ Duplicate full context file content (just reference paths)
- ❌ Use vague success criteria ("make it good")
- ❌ Skip validation requirements
- ❌ Forget to list technical constraints
- ❌ Omit file paths for files to create/modify
### Example Context Bundle
See `.opencode/context/openagents-repo/examples/context-bundle-example.md` for a complete example.
---
**Last Updated**: 2025-01-21
**Version**: 1.0.0

39
.opencode/context/openagents-repo/blueprints/navigation.md Normal file
View File

@@ -0,0 +1,39 @@
<!-- Context: openagents-repo/navigation | Priority: critical | Version: 1.0 | Updated: 2026-02-15 -->
# OpenAgents Blueprints
**Purpose**: Blueprint templates and patterns for OpenAgents Control
---
## Structure
```
openagents-repo/blueprints/
├── navigation.md (this file)
└── [blueprint files]
```
---
## Quick Routes
| Task | Path |
|------|------|
| **View blueprints** | `./` |
| **Core concepts** | `../core-concepts/navigation.md` |
| **Examples** | `../examples/navigation.md` |
---
## By Type
**Blueprints** → Template patterns for OpenAgents implementations
---
## Related Context
- **OpenAgents Navigation** → `../navigation.md`
- **Core Concepts** → `../core-concepts/navigation.md`
- **Examples** → `../examples/navigation.md`

40
.opencode/context/openagents-repo/concepts/navigation.md Normal file
View File

@@ -0,0 +1,40 @@
<!-- Context: openagents-repo/navigation | Priority: critical | Version: 1.0 | Updated: 2026-02-15 -->
# OpenAgents Concepts
**Purpose**: Core concepts and ideas for OpenAgents Control
---
## Structure
```
openagents-repo/concepts/
├── navigation.md (this file)
└── [concept files]
```
---
## Quick Routes
| Task | Path |
|------|------|
| **View concepts** | `./` |
| **Core concepts** | `../core-concepts/navigation.md` |
| **Guides** | `../guides/navigation.md` |
---
## By Type
**Concepts** → Foundational concepts for OpenAgents
**Core Concepts** → Deep dives into core ideas
---
## Related Context
- **OpenAgents Navigation** → `../navigation.md`
- **Core Concepts** → `../core-concepts/navigation.md`
- **Guides** → `../guides/navigation.md`

133
.opencode/context/openagents-repo/concepts/subagent-testing-modes.md Normal file
View File

@@ -0,0 +1,133 @@
<!-- Context: openagents-repo/concepts | Priority: critical | Version: 1.0 | Updated: 2026-02-15 -->
# Subagent Testing Modes
**Purpose**: Understand the two ways to test subagents (standalone vs delegation)
**Last Updated**: 2026-01-07
---
## Core Concept
Subagents have **two distinct testing modes** depending on what you're validating:
1. **Standalone Mode** - Test subagent logic directly (unit testing)
2. **Delegation Mode** - Test parent → subagent workflow (integration testing)
The mode determines which agent runs and how tools are used.
---
## Standalone Mode (Unit Testing)
**Purpose**: Test subagent's logic in isolation
**Command**:
```bash
bun --bun run eval:sdk -- --subagent=ContextScout
```
**What Happens**:
- Eval framework forces `mode: primary` (overrides `mode: subagent`)
- ContextScout runs as the primary agent
- ContextScout uses tools directly (glob, read, grep, list)
- No parent agent involved
**Use For**:
- Unit testing subagent logic
- Debugging tool usage
- Feature development
- Verifying prompt changes
**Test Location**: `evals/agents/subagents/core/{subagent}/tests/standalone/`
---
## Delegation Mode (Integration Testing)
**Purpose**: Test real production workflow (parent delegates to subagent)
**Command**:
```bash
bun --bun run eval:sdk -- --agent=core/openagent --pattern="delegation/*.yaml"
```
**What Happens**:
- OpenAgent runs as primary agent
- OpenAgent uses `task` tool to delegate to ContextScout
- ContextScout runs with `mode: subagent` (natural mode)
- Tests full delegation workflow
**Use For**:
- Integration testing
- Validating production behavior
- Testing delegation logic
- End-to-end workflows
**Test Location**: `evals/agents/subagents/core/{subagent}/tests/delegation/`
---
## Critical Distinction
| Aspect | Standalone Mode | Delegation Mode |
|--------|----------------|-----------------|
| **Flag** | `--subagent=NAME` | `--agent=PARENT` |
| **Agent Mode** | Forced to `primary` | Natural `subagent` |
| **Who Runs** | Subagent directly | Parent → Subagent |
| **Tool Usage** | Subagent uses tools | Parent uses `task` tool |
| **Tests** | `standalone/*.yaml` | `delegation/*.yaml` |
**Common Mistake**:
```bash
# ❌ WRONG - This runs OpenAgent, not ContextScout
bun --bun run eval:sdk -- --agent=ContextScout
# ✅ CORRECT - This runs ContextScout directly
bun --bun run eval:sdk -- --subagent=ContextScout
```
---
## How to Verify Correct Mode
### Standalone Mode Indicators:
```
⚡ Standalone Test Mode
Subagent: contextscout
Mode: Forced to 'primary' for direct testing
```
### Delegation Mode Indicators:
```
Testing agent: core/openagent
🎯 PARENT: OpenAgent
Delegating to: contextscout
```
---
## When to Use Each Mode
**Use Standalone When**:
- Testing subagent's core logic
- Debugging why subagent isn't using tools
- Validating prompt changes
- Quick iteration during development
**Use Delegation When**:
- Testing production workflow
- Validating parent → subagent communication
- Testing context passing
- Integration testing
---
## Related
- `guides/testing-subagents.md` - Step-by-step testing guide
- `lookup/subagent-test-commands.md` - Quick command reference
- `errors/tool-permission-errors.md` - Common testing issues
**Reference**: `evals/framework/src/sdk/run-sdk-tests.ts` (mode forcing logic)

559
.opencode/context/openagents-repo/core-concepts/agent-metadata.md Normal file
View File

@@ -0,0 +1,559 @@
<!-- Context: openagents-repo/core-concepts/agent-metadata | Priority: critical | Version: 1.0 | Updated: 2026-01-31 -->
# Core Concept: Agent Metadata System
**Purpose**: Understanding the centralized metadata system for OpenAgents Control
**Priority**: CRITICAL - Load this before working with agent metadata
---
## What Is the Agent Metadata System?
The agent metadata system separates **OpenCode-compliant agent configuration** from **OpenAgents Control registry metadata**. This solves the problem of OpenCode validation errors when agents contain fields that aren't part of the OpenCode agent schema.
**Key Principle**: Agent frontmatter contains ONLY valid OpenCode fields. All other metadata lives in a centralized file.
---
## The Problem We Solved
### Before (Validation Errors)
Agent frontmatter contained fields that OpenCode doesn't recognize:
```yaml
---
id: opencoder # ❌ Not valid OpenCode field
name: OpenCoder # ❌ Not valid OpenCode field
category: core # ❌ Not valid OpenCode field
type: core # ❌ Not valid OpenCode field
version: 1.0.0 # ❌ Not valid OpenCode field
author: opencode # ❌ Not valid OpenCode field
tags: [development, coding] # ❌ Not valid OpenCode field
dependencies: [] # ❌ Not valid OpenCode field
description: "..." # ✅ Valid OpenCode field
mode: primary # ✅ Valid OpenCode field
temperature: 0.1 # ✅ Valid OpenCode field
tools: {...} # ✅ Valid OpenCode field
permission: {...} # ✅ Valid OpenCode field
---
```
**Result**: OpenCode validation errors:
```
Extra inputs are not permitted, field: 'id', value: 'opencoder'
Extra inputs are not permitted, field: 'category', value: 'core'
Extra inputs are not permitted, field: 'type', value: 'core'
... (9 validation errors)
```
### After (Clean Separation)
**Agent frontmatter** (`.opencode/agent/core/opencoder.md`):
```yaml
---
# Metadata stored in: .opencode/config/agent-metadata.json
description: "Orchestration agent for complex coding, architecture, and multi-file refactoring"
mode: primary
temperature: 0.1
tools: {...}
permission: {...}
---
```
**Centralized metadata** (`.opencode/config/agent-metadata.json`):
```json
{
"agents": {
"opencoder": {
"id": "opencoder",
"name": "OpenCoder",
"category": "core",
"type": "agent",
"version": "1.0.0",
"author": "opencode",
"tags": ["development", "coding", "implementation"],
"dependencies": [
"subagent:documentation",
"subagent:coder-agent",
"context:core/standards/code"
]
}
}
}
```
**Result**: ✅ No validation errors, clean separation of concerns
---
## Valid OpenCode Agent Fields
Based on [OpenCode documentation](https://opencode.ai/docs/agents/), these are the ONLY valid frontmatter fields:
### Required Fields
- `description` - When to use this agent (required)
- `mode` - Agent type: `primary`, `subagent`, or `all` (defaults to `all`)
### Optional Fields
- `model` - Model override (e.g., `anthropic/claude-sonnet-4-20250514`)
- `temperature` - Response randomness (0.0-1.0)
- `maxSteps` - Max agentic iterations
- `disable` - Set to `true` to disable agent
- `prompt` - Custom prompt file path (e.g., `{file:./prompts/build.txt}`)
- `hidden` - Hide from @ autocomplete (subagents only)
- `tools` - Tool access configuration
- `permission` - Permission rules for tools (v1.1.1+, replaces deprecated `permissions`)
### Example Valid Frontmatter
```yaml
---
description: "Code review agent with security focus"
mode: subagent
model: anthropic/claude-sonnet-4-20250514
temperature: 0.1
tools:
read: true
grep: true
glob: true
write: false
edit: false
permission: # v1.1.1+ (singular, not plural)
bash:
"*": ask
"git *": allow
edit: deny
---
```
---
## Centralized Metadata File
**Location**: `.opencode/config/agent-metadata.json`
### Schema
```json
{
"$schema": "https://opencode.ai/schemas/agent-metadata.json",
"schema_version": "1.0.0",
"description": "Centralized metadata for OpenAgents Control agents",
"agents": {
"agent-id": {
"id": "agent-id",
"name": "Agent Name",
"category": "core|development|content|data|product|learning|meta",
"type": "agent|subagent",
"version": "1.0.0",
"author": "opencode",
"tags": ["tag1", "tag2"],
"dependencies": [
"subagent:subagent-id",
"context:path/to/context"
]
}
},
"defaults": {
"agent": {
"version": "1.0.0",
"author": "opencode",
"type": "agent",
"tags": []
},
"subagent": {
"version": "1.0.0",
"author": "opencode",
"type": "subagent",
"tags": []
}
}
}
```
### Metadata Fields
| Field | Required | Description | Example |
|-------|----------|-------------|---------|
| `id` | Yes | Unique identifier (kebab-case) | `"opencoder"` |
| `name` | Yes | Display name | `"OpenCoder"` |
| `category` | Yes | Agent category | `"core"` |
| `type` | Yes | Component type | `"agent"` or `"subagent"` |
| `version` | Yes | Version number | `"1.0.0"` |
| `author` | Yes | Author identifier | `"opencode"` |
| `tags` | No | Discovery tags | `["development", "coding"]` |
| `dependencies` | No | Component dependencies | `["subagent:tester"]` |
---
## How It Works
### 1. Agent Creation
When creating a new agent:
**Step 1**: Create agent file with ONLY valid OpenCode fields
```bash
# Create agent file
touch .opencode/agent/category/my-agent.md
```
```yaml
---
description: "My agent description"
mode: subagent
temperature: 0.2
tools:
read: true
write: true
---
# Agent prompt content here
```
**Step 2**: Add metadata to `.opencode/config/agent-metadata.json`
```json
{
"agents": {
"my-agent": {
"id": "my-agent",
"name": "My Agent",
"category": "development",
"type": "subagent",
"version": "1.0.0",
"author": "opencode",
"tags": ["custom", "helper"],
"dependencies": ["context:core/standards/code"]
}
}
}
```
**Step 3**: Run auto-detect to update registry
```bash
./scripts/registry/auto-detect-components.sh --auto-add
```
The auto-detect script:
1. Reads frontmatter from agent file (description, mode, etc.)
2. Reads metadata from `agent-metadata.json` (id, name, tags, dependencies)
3. Merges both into registry.json entry
### 2. Auto-Detect Integration
The auto-detect script (`scripts/registry/auto-detect-components.sh`) has been enhanced to:
1. **Extract frontmatter** - Read description from agent file
2. **Lookup metadata** - Check `agent-metadata.json` for agent ID
3. **Merge data** - Combine frontmatter + metadata
4. **Update registry** - Write complete entry to registry.json
**Code snippet** (from auto-detect script):
```bash
# Check if agent-metadata.json exists and merge metadata from it
local metadata_file="$REPO_ROOT/.opencode/config/agent-metadata.json"
if [ -f "$metadata_file" ] && command -v jq &> /dev/null; then
# Try to find metadata for this agent ID
local metadata_entry
metadata_entry=$(jq -r ".agents[\"$id\"] // empty" "$metadata_file" 2>/dev/null)
if [ -n "$metadata_entry" ] && [ "$metadata_entry" != "null" ]; then
# Merge name, tags, dependencies from metadata
# ...
fi
fi
```
### 3. Registry Output
The registry.json entry contains merged data:
```json
{
"id": "opencoder",
"name": "OpenCoder",
"type": "agent",
"path": ".opencode/agent/core/opencoder.md",
"description": "Orchestration agent for complex coding...",
"category": "core",
"tags": ["development", "coding", "implementation"],
"dependencies": [
"subagent:documentation",
"subagent:coder-agent",
"context:core/standards/code"
]
}
```
---
## Workflow
### Adding a New Agent
```bash
# 1. Create agent file (OpenCode-compliant frontmatter only)
vim .opencode/agent/category/my-agent.md
# 2. Add metadata entry
vim .opencode/config/agent-metadata.json
# 3. Update registry
./scripts/registry/auto-detect-components.sh --auto-add
# 4. Validate
./scripts/registry/validate-registry.sh
```
### Updating Agent Metadata
**To update OpenCode configuration** (tools, permissions, temperature):
```bash
# Edit agent file frontmatter
vim .opencode/agent/category/my-agent.md
```
**To update registry metadata** (tags, dependencies, version):
```bash
# Edit metadata file
vim .opencode/config/agent-metadata.json
# Re-run auto-detect
./scripts/registry/auto-detect-components.sh --auto-add
```
### Updating Dependencies
**Add a dependency**:
```json
{
"agents": {
"my-agent": {
"dependencies": [
"subagent:tester",
"context:core/standards/code",
"subagent:new-dependency" // ← Add here
]
}
}
}
```
Then run:
```bash
./scripts/registry/auto-detect-components.sh --auto-add
./scripts/registry/validate-registry.sh
```
---
## Benefits
### ✅ OpenCode Compliance
- Agent frontmatter contains ONLY valid OpenCode fields
- No validation errors from OpenCode
- Agents work correctly with OpenCode CLI
### ✅ Registry Compatibility
- Registry still has all metadata (id, name, category, tags, dependencies)
- Auto-detect script merges frontmatter + metadata
- Backward compatible with existing tools
### ✅ Single Source of Truth
- Metadata centralized in one file
- Easy to update dependencies across multiple agents
- Clear separation: OpenCode config vs. registry metadata
### ✅ Maintainability
- Update dependencies in one place
- Consistent metadata across all agents
- Easy to add new metadata fields
### ✅ Validation
- OpenCode validates frontmatter (no extra fields)
- Registry validator checks dependencies exist
- Clear error messages when metadata is missing
---
## Migration Guide
### Migrating from permissions (plural) to permission (singular)
**OpenCode v1.1.1+ Change**: The field name changed from `permissions:` (plural) to `permission:` (singular).
**Before** (deprecated):
```yaml
permissions:
bash:
"*": "deny"
```
**After** (v1.1.1+):
```yaml
permission:
bash:
"*": "deny"
```
**Migration Steps**:
1. Find all agents using `permissions:` (plural)
```bash
grep -r "^permissions:" .opencode/agent/
```
2. Replace with `permission:` (singular) in each file
3. Verify no validation errors:
```bash
opencode agent validate
```
### Migrating Existing Agents
**Step 1**: Identify agents with extra fields
```bash
# Find agents with invalid OpenCode fields
grep -r "^id:\|^name:\|^category:\|^type:\|^version:\|^author:\|^tags:\|^dependencies:" .opencode/agent/
```
**Step 2**: Extract metadata to `agent-metadata.json`
For each agent:
1. Copy `id`, `name`, `category`, `type`, `version`, `author`, `tags`, `dependencies` to metadata file
2. Remove these fields from agent frontmatter
3. Keep ONLY valid OpenCode fields in frontmatter
**Step 3**: Update registry
```bash
# Remove old entries
jq 'del(.components.agents[] | select(.id == "agent-id"))' registry.json > tmp.json && mv tmp.json registry.json
# Re-add with new metadata
./scripts/registry/auto-detect-components.sh --auto-add
```
**Step 4**: Validate
```bash
./scripts/registry/validate-registry.sh
```
---
## Best Practices
### Agent Frontmatter
✅ **DO**:
- Keep frontmatter minimal (only OpenCode fields)
- Add comment pointing to metadata file
- Use consistent formatting
❌ **DON'T**:
- Add custom fields to frontmatter
- Duplicate metadata in both places
- Skip the metadata file
### Metadata File
✅ **DO**:
- Keep metadata file in version control
- Update metadata when adding/removing dependencies
- Use consistent naming (kebab-case for IDs)
- Document why dependencies exist
❌ **DON'T**:
- Forget to update metadata when creating agents
- Leave orphaned entries (agents that don't exist)
- Skip validation after updates
### Dependencies
✅ **DO**:
- Declare ALL dependencies (subagents, contexts)
- Use correct format: `type:id`
- Validate dependencies exist in registry
❌ **DON'T**:
- Reference components without declaring dependency
- Use invalid dependency formats
- Forget to update when dependencies change
---
## Troubleshooting
### OpenCode Validation Errors
**Problem**: `Extra inputs are not permitted, field: 'id'`
**Solution**: Remove invalid fields from agent frontmatter, add to metadata file
```bash
# 1. Edit agent file - remove id, name, category, type, version, author, tags, dependencies
vim .opencode/agent/category/agent.md
# 2. Add to metadata file
vim .opencode/config/agent-metadata.json
# 3. Update registry
./scripts/registry/auto-detect-components.sh --auto-add
```
### Missing Metadata
**Problem**: Auto-detect can't find metadata for agent
**Solution**: Add entry to `agent-metadata.json`
```json
{
"agents": {
"agent-id": {
"id": "agent-id",
"name": "Agent Name",
"category": "core",
"type": "agent",
"version": "1.0.0",
"author": "opencode",
"tags": [],
"dependencies": []
}
}
}
```
### Registry Out of Sync
**Problem**: Registry has old metadata
**Solution**: Remove entry and re-run auto-detect
```bash
# Remove old entry
jq 'del(.components.agents[] | select(.id == "agent-id"))' registry.json > tmp.json && mv tmp.json registry.json
# Re-add with current metadata
./scripts/registry/auto-detect-components.sh --auto-add
```
---
## Related Files
- **OpenCode Agent Docs**: https://opencode.ai/docs/agents/
- **Registry System**: `.opencode/context/openagents-repo/core-concepts/registry.md`
- **Adding Agents**: `.opencode/context/openagents-repo/guides/adding-agent-basics.md`
- **Dependencies**: `.opencode/context/openagents-repo/quality/registry-dependencies.md`
---
**Last Updated**: 2026-01-31
**Version**: 1.0.0

364
.opencode/context/openagents-repo/core-concepts/agents.md Normal file
View File

@@ -0,0 +1,364 @@
# Core Concept: Agents
**Purpose**: Understanding how agents work in OpenAgents Control
**Priority**: CRITICAL - Load this before working with agents
---
## What Are Agents?
Agents are AI prompt files that define specialized behaviors for different tasks. They are:
- **Markdown files** with frontmatter metadata
- **Category-organized** by domain (core, development, content, etc.)
- **Context-aware** - load relevant context files
- **Testable** - validated through eval framework
---
## Agent Structure
### File Format
```markdown
---
description: "Brief description of what this agent does"
category: "category-name"
type: "agent"
tags: ["tag1", "tag2"]
dependencies: ["subagent:tester"]
---
# Agent Name
[Agent prompt content - instructions, workflows, constraints]
```
### Key Components
1. **Frontmatter** (YAML metadata)
- `description`: Brief description
- `category`: Category name (core, development, content, etc.)
- `type`: Always "agent"
- `tags`: Optional tags for discovery
- `dependencies`: Optional dependencies (e.g., subagents)
2. **Prompt Content**
- Instructions and workflows
- Constraints and rules
- Context loading requirements
- Tool usage patterns
---
## Category System
Agents are organized by domain expertise:
### Core Category (`core/`)
**Purpose**: Essential system agents (always available)
Agents:
- `openagent.md` - General-purpose orchestrator
- `opencoder.md` - Development specialist
- `system-builder.md` - System generation
**When to use**: System-level tasks, orchestration
---
### Development Category (`development/`)
**Purpose**: Software development specialists
Agents:
- `frontend-specialist.md` - React, Vue, modern CSS
- `devops-specialist.md` - CI/CD, deployment, infrastructure
**When to use**: Building applications, dev tasks
---
### Content Category (`content/`)
**Purpose**: Content creation specialists
Agents:
- `copywriter.md` - Marketing copy, persuasive writing
- `technical-writer.md` - Documentation, technical content
**When to use**: Writing, documentation, marketing
---
### Data Category (`data/`)
**Purpose**: Data analysis specialists
Agents:
- `data-analyst.md` - Data analysis, visualization
**When to use**: Data tasks, analysis, reporting
---
### Product Category (`product/`)
**Purpose**: Product management specialists
**Status**: Ready for agents (no agents yet)
**When to use**: Product strategy, roadmaps, requirements
---
### Learning Category (`learning/`)
**Purpose**: Education and coaching specialists
**Status**: Ready for agents (no agents yet)
**When to use**: Teaching, training, curriculum
---
## Subagents
**Location**: `.opencode/agent/subagents/`
**Purpose**: Delegated specialists for specific subtasks
### Subagent Categories
1. **code/** - Code-related specialists
- `tester.md` - Test authoring and TDD
- `reviewer.md` - Code review and security
- `coder-agent.md` - Focused implementations
- `build-agent.md` - Type checking and builds
2. **core/** - Core workflow specialists
- `task-manager.md` - Task breakdown and management
- `documentation.md` - Documentation generation
3. **system-builder/** - System generation specialists
- `agent-generator.md` - Generate agent files
- `command-creator.md` - Create slash commands
- `domain-analyzer.md` - Analyze domains
- `context-organizer.md` - Organize context
- `workflow-designer.md` - Design workflows
4. **utils/** - Utility specialists
- `image-specialist.md` - Image editing and analysis
### Subagents vs Category Agents
| Aspect | Category Agents | Subagents |
|--------|----------------|-----------|
| **Purpose** | User-facing specialists | Delegated subtasks |
| **Invocation** | Direct by user | Via task tool |
| **Scope** | Broad domain | Narrow focus |
| **Example** | `frontend-specialist` | `tester` |
---
## Claude Code Interop (Optional)
OpenAgents Control 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 Control standards or to ship reusable helpers.
---
## Path Resolution
The system supports multiple path formats for backward compatibility:
### Supported Formats
```bash
# Short ID (backward compatible)
"openagent" → resolves to → ".opencode/agent/core/openagent.md"
# Category path
"core/openagent" → resolves to → ".opencode/agent/core/openagent.md"
# Full category path
"development/frontend-specialist" → resolves to → ".opencode/agent/subagents/development/frontend-specialist.md"
# Subagent path
"TestEngineer" → resolves to → ".opencode/agent/subagents/code/test-engineer.md"
```
### Resolution Rules
1. Check if path includes `/` → use as category path
2. If no `/` → check core/ first (backward compat)
3. If not in core/ → search all categories
4. If not found → error
---
## Prompt Variants
**Location**: `.opencode/prompts/{category}/{agent}/`
**Purpose**: Model-specific prompt optimizations
### Supported Models
- `gemini.md` - Google Gemini optimizations
- `grok.md` - xAI Grok optimizations
- `llama.md` - Meta Llama optimizations
- `openrouter.md` - OpenRouter optimizations
### When to Create Variants
- Model has specific formatting requirements
- Model performs better with different structure
- Model has unique capabilities to leverage
### Fallback Behavior
If no variant exists for a model, the base agent file is used.
---
## Context Loading
Agents should load relevant context files based on task type:
### Core Context (Always Consider)
```markdown
<!-- Context: standards/code | Priority: critical -->
```
Loads: `.opencode/context/core/standards/code-quality.md`
### Category Context
```markdown
<!-- Context: development/react-patterns | Priority: high -->
```
Loads: `.opencode/context/ui/web/react-patterns.md`
### Multiple Contexts
```markdown
<!-- Context: standards/code, standards/tests | Priority: critical -->
```
---
## Agent Lifecycle
### 1. Creation
```bash
# Create agent file
touch .opencode/agent/{category}/{agent-name}.md
# Add frontmatter and content
# (See guides/adding-agent.md for details)
```
### 2. Testing
```bash
# Create test structure
mkdir -p evals/agents/{category}/{agent-name}/{config,tests}
# Run tests
cd evals/framework && bun --bun run eval:sdk -- --agent={category}/{agent-name}
```
### 3. Registration
```bash
# Auto-detect and add to registry
./scripts/registry/auto-detect-components.sh --auto-add
# Validate
./scripts/registry/validate-registry.sh
```
### 4. Distribution
```bash
# Users install via install.sh
./install.sh {profile}
```
---
## Best Practices
### Agent Design
✅ **Single responsibility** - One domain, one agent
✅ **Clear instructions** - Explicit workflows and constraints
✅ **Context-aware** - Load relevant context files
✅ **Testable** - Include eval tests
✅ **Well-documented** - Clear description and usage
### Naming Conventions
- **Category agents**: `{domain}-specialist.md` (e.g., `frontend-specialist.md`)
- **Core agents**: `{name}.md` (e.g., `openagent.md`)
- **Subagents**: `{purpose}.md` (e.g., `tester.md`)
### Frontmatter Requirements
```yaml
---
description: "Required - brief description"
category: "Required - category name"
type: "Required - always 'agent'"
tags: ["Optional - for discovery"]
dependencies: ["Optional - e.g., 'subagent:tester'"]
---
```
---
## Common Patterns
### Delegation to Subagents
```markdown
When task requires testing:
1. Implement feature
2. Delegate to TestEngineer for test creation
```
### Context Loading
```markdown
Before implementing:
1. Load core/standards/code-quality.md
2. Load category-specific context if available
3. Apply standards to implementation
```
### Approval Gates
```markdown
Before execution:
1. Present plan to user
2. Request approval
3. Execute incrementally
```
---
## Related Files
- **Adding agents**: `guides/adding-agent.md`
- **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**: 2026-01-13
**Version**: 0.5.1

428
.opencode/context/openagents-repo/core-concepts/categories.md Normal file
View File

@@ -0,0 +1,428 @@
# Core Concept: Category System
**Purpose**: Understanding how components are organized
**Priority**: HIGH - Load this before adding categories or organizing components
---
## What Are Categories?
Categories are domain-based groupings that organize agents, context files, and tests by expertise area.
**Benefits**:
- **Scalability** - Easy to add new domains
- **Discovery** - Find agents by domain
- **Organization** - Clear structure
- **Modularity** - Install only what you need
---
## Available Categories
### Core (`core/`)
**Purpose**: Essential system agents (always available)
**Agents**:
**When to use**: System-level tasks, orchestration, coding (simple or complex)
**Status**: ✅ Stable
---
### Development Subagents (`subagents/development/`)
**Purpose**: Domain-specific development specialists (invoked by core agents)
**Subagents**:
- frontend-specialist, devops-specialist
**Context**:
- clean-code.md, react-patterns.md, api-design.md
**When to use**: Delegated frontend, backend, or DevOps tasks within a larger workflow
**Status**: ✅ Active
---
### Content (`content/`)
**Purpose**: Content creation specialists
**Agents**:
- copywriter, technical-writer
**Context**:
- copywriting-frameworks.md
- tone-voice.md
- audience-targeting.md
- hooks.md
**When to use**: Writing, documentation, marketing
**Status**: ✅ Active
---
### Data (`data/`)
**Purpose**: Data analysis specialists
**Agents**:
- data-analyst
**Context**:
- (Ready for data-specific context)
**When to use**: Data tasks, analysis, reporting
**Status**: ✅ Active
---
---
## Category Structure
### Directory Layout
```
.opencode/
├── agent/{category}/ # Agents by category
├── context/{category}/ # Context by category
├── prompts/{category}/ # Prompt variants by category
evals/agents/{category}/ # Tests by category
```
### Example: Core Agents + Development Subagents
```
.opencode/agent/core/
├── 0-category.json # Category metadata
├── openagent.md
├── opencoder.md
.opencode/agent/subagents/development/
├── 0-category.json # Subagent category metadata
├── frontend-specialist.md
└── devops-specialist.md
.opencode/context/development/
├── navigation.md
├── clean-code.md
├── react-patterns.md
└── api-design.md
```
---
## Category Metadata
### 0-category.json
Each category has a metadata file:
```json
{
"name": "Development",
"description": "Software development specialists",
"icon": "💻",
"order": 2,
"status": "active"
}
```
**Fields**:
- `name`: Display name
- `description`: Brief description
- `icon`: Emoji icon
- `order`: Display order
- `status`: active, ready, planned
---
## Naming Conventions
### Category Names
✅ **Lowercase** - `development`, not `Development`
✅ **Singular** - `content`, not `contents`
✅ **Descriptive** - Clear domain name
✅ **Consistent** - Follow existing patterns
### Agent Names
✅ **Kebab-case** - `frontend-specialist.md`
✅ **Descriptive** - Clear purpose
✅ **Suffix** - Use `-specialist`, `-agent`, `-writer` as appropriate
### Context Names
✅ **Kebab-case** - `react-patterns.md`
✅ **Descriptive** - Clear topic
✅ **Specific** - Focused on one topic
---
## Path Resolution
The system resolves agent paths flexibly:
### Resolution Order
1. **Check for `/`** - If present, treat as category path
2. **Check core/** - For backward compatibility
3. **Search categories** - Look in all categories
4. **Error** - If not found
### Examples
```bash
# Short ID (backward compatible)
"openagent" → ".opencode/agent/core/openagent.md"
# Subagent path
"subagents/development/frontend-specialist" → ".opencode/agent/subagents/development/frontend-specialist.md"
# Subagent path
"TestEngineer" → ".opencode/agent/subagents/code/test-engineer.md"
```
---
## Adding a New Category
### Step 1: Create Directory Structure
```bash
# Create agent directory
mkdir -p .opencode/agent/{category}
# Create context directory
mkdir -p .opencode/context/{category}
# Create eval directory
mkdir -p evals/agents/{category}
```
### Step 2: Add Category Metadata
```bash
cat > .opencode/agent/{category}/0-category.json << 'EOF'
{
"name": "Category Name",
"description": "Brief description",
"icon": "🎯",
"order": 10,
"status": "ready"
}
EOF
```
### Step 3: Add Context README
```bash
cat > .opencode/context/{category}/navigation.md << 'EOF'
# Category Name Context
Context files for {category} specialists.
## Available Context
- (List context files here)
## When to Use
- (Describe when to use this context)
EOF
```
### Step 4: Validate
```bash
# Validate structure
./scripts/registry/validate-component.sh
# Update registry
./scripts/registry/auto-detect-components.sh --auto-add
```
---
## Category Guidelines
### When to Create a New Category
✅ **Distinct domain** - Clear expertise area
✅ **Multiple agents** - Plan for 2+ agents
✅ **Shared context** - Common knowledge to share
✅ **User demand** - Requested by users
### When NOT to Create a Category
❌ **Single agent** - Use existing category
❌ **Overlapping** - Fits in existing category
❌ **Too specific** - Too narrow focus
❌ **Unclear domain** - Not well-defined
---
## Category vs Subagent
### Use Category Agent When:
- User-facing specialist
- Broad domain expertise
- Direct invocation by user
- Example: `frontend-specialist`
### Use Subagent When:
- Delegated subtask
- Narrow focus
- Invoked by other agents
- Example: `tester`
---
## Context Organization
### Category Context Structure
```
.opencode/context/{category}/
├── navigation.md # Overview
├── {topic-1}.md # Specific topic
├── {topic-2}.md # Specific topic
└── {topic-3}.md # Specific topic
```
### Context Loading
Agents load category context based on task:
```markdown
<!-- Context: development/react-patterns | Priority: high -->
```
Loads: `.opencode/context/ui/web/react-patterns.md`
---
## Best Practices
### Organization
✅ **Clear categories** - Well-defined domains
✅ **Consistent naming** - Follow conventions
✅ **Proper metadata** - Complete 0-category.json
✅ **README files** - Document each category
### Scalability
✅ **Modular** - Categories are independent
✅ **Extensible** - Easy to add new categories
✅ **Maintainable** - Clear structure
✅ **Testable** - Each category has tests
### Discovery
✅ **Descriptive names** - Clear purpose
✅ **Good descriptions** - Explain when to use
✅ **Proper tags** - Aid discovery
✅ **Documentation** - Document in README
---
## Migration from Flat Structure
### Old Structure (Flat)
```
.opencode/agent/
├── openagent.md
├── opencoder.md
├── frontend-specialist.md
└── copywriter.md
```
### New Structure (Category-Based)
```
.opencode/agent/
├── core/
│ ├── openagent.md
│ ├── opencoder.md
├── subagents/
│ ├── development/
│ │ ├── frontend-specialist.md
│ │ └── devops-specialist.md
│ └── code/
│ ├── coder-agent.md
│ └── tester.md
└── content/
└── copywriter.md
```
### Backward Compatibility
Old paths still work:
- `openagent` → resolves to `core/openagent`
- `opencoder` → resolves to `core/opencoder`
New agents use category paths:
- `subagents/development/frontend-specialist`
- `content/copywriter`
---
## Common Patterns
### Core Category with Multiple Agents
```
core/
├── 0-category.json
├── openagent.md
├── opencoder.md
```
### Development Subagents
```
subagents/development/
├── 0-category.json
├── frontend-specialist.md
└── devops-specialist.md
```
### Category with Shared Context
```
context/development/
├── navigation.md
├── clean-code.md
├── react-patterns.md
└── api-design.md
```
### Category with Tests
```
evals/agents/core/
├── openagent/
│ ├── config/config.yaml
│ └── tests/smoke-test.yaml
├── opencoder/
```
---
## Related Files
- **Adding agents**: `guides/adding-agent.md`
- **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**: 2026-01-13
**Version**: 0.5.1

496
.opencode/context/openagents-repo/core-concepts/evals.md Normal file
View File

@@ -0,0 +1,496 @@
<!-- Context: openagents-repo/evals | Priority: high | Version: 1.0 | Updated: 2026-02-15 -->
# Core Concept: Eval Framework
**Purpose**: Understanding how agent testing works
**Priority**: CRITICAL - Load this before testing agents
---
## What Is the Eval Framework?
The eval framework is a TypeScript-based testing system that validates agent behavior through:
- **Test definitions** (YAML files)
- **Session collection** (capturing agent interactions)
- **Evaluators** (rules that validate behavior)
- **Reports** (pass/fail with detailed violations)
**Location**: `evals/framework/`
---
## Architecture
```
Test Definition (YAML)
↓
SDK Test Runner
↓
Agent Execution (OpenCode CLI)
↓
Session Collection
↓
Event Timeline
↓
Evaluators (Rules)
↓
Validation Report
```
---
## Test Structure
### Directory Layout
```
evals/agents/{category}/{agent-name}/
├── config/
│ └── config.yaml # Agent test configuration
└── tests/
├── smoke-test.yaml # Basic functionality test
├── approval-gate.yaml # Approval gate test
├── context-loading.yaml # Context loading test
└── ... # Additional tests
```
### Config File (`config.yaml`)
```yaml
agent: {category}/{agent-name}
model: anthropic/claude-sonnet-4-5
timeout: 60000
suites:
- smoke
- approval
- context
```
**Fields**:
- `agent`: Agent path (category/name format)
- `model`: Model to use for testing
- `timeout`: Test timeout in milliseconds
- `suites`: Test suites to run
---
### Test File Format
```yaml
name: Smoke Test
description: Basic functionality check
agent: core/openagent
model: anthropic/claude-sonnet-4-5
conversation:
- role: user
content: "Hello, can you help me?"
- role: assistant
content: "Yes, I can help you!"
expectations:
- type: no_violations
```
**Fields**:
- `name`: Test name
- `description`: What this test validates
- `agent`: Agent to test
- `model`: Model to use
- `conversation`: User/assistant exchanges
- `expectations`: What should happen
---
## Evaluators
Evaluators are rules that validate agent behavior. Each evaluator checks for specific patterns.
### Available Evaluators
#### 1. Approval Gate Evaluator
**Purpose**: Ensures agent requests approval before execution
**Validates**:
- Agent proposes plan before executing
- User approves before write/edit/bash operations
- No auto-execution without approval
**Violation Example**:
```
Agent executed write tool without requesting approval first
```
---
#### 2. Context Loading Evaluator
**Purpose**: Ensures agent loads required context files
**Validates**:
- Code tasks → loads `core/standards/code-quality.md`
- Doc tasks → loads `core/standards/documentation.md`
- Test tasks → loads `core/standards/test-coverage.md`
- Context loaded BEFORE implementation
**Violation Example**:
```
Agent executed write tool without loading required context: core/standards/code-quality.md
```
---
#### 3. Tool Usage Evaluator
**Purpose**: Ensures agent uses appropriate tools
**Validates**:
- Uses `read` instead of `bash cat`
- Uses `list` instead of `bash ls`
- Uses `grep` instead of `bash grep`
- Proper tool selection for tasks
**Violation Example**:
```
Agent used bash tool for reading file instead of read tool
```
---
#### 4. Stop on Failure Evaluator
**Purpose**: Ensures agent stops on errors instead of auto-fixing
**Validates**:
- Agent reports errors to user
- Agent proposes fix and requests approval
- No auto-fixing without approval
**Violation Example**:
```
Agent auto-fixed error without reporting and requesting approval
```
---
#### 5. Execution Balance Evaluator
**Purpose**: Ensures agent doesn't over-execute
**Validates**:
- Reasonable ratio of read vs execute operations
- Not executing excessively
- Balanced tool usage
**Violation Example**:
```
Agent execution ratio too high: 80% execute vs 20% read
```
---
## Running Tests
### Basic Test Run
```bash
cd evals/framework
bun --bun run eval:sdk -- --agent={category}/{agent}
```
### Run Specific Test
```bash
cd evals/framework
bun --bun run eval:sdk -- --agent={category}/{agent} --pattern="smoke-test.yaml"
```
### Run with Debug
```bash
cd evals/framework
bun --bun run eval:sdk -- --agent={category}/{agent} --debug
```
### Run All Tests
```bash
cd evals/framework
bun --bun run eval:sdk
```
---
## Session Collection
### What Are Sessions?
Sessions are recordings of agent interactions stored in `.tmp/sessions/`.
### Session Structure
```
.tmp/sessions/{session-id}/
├── session.json # Complete session data
├── events.json # Event timeline
└── context.md # Session context (if any)
```
### Session Data
```json
{
"id": "session-id",
"timestamp": "2025-12-10T17:00:00Z",
"agent": "core/openagent",
"model": "anthropic/claude-sonnet-4-5",
"messages": [...],
"toolCalls": [...],
"events": [...]
}
```
### Event Timeline
Events capture agent actions:
- `tool_call` - Agent invoked a tool
- `context_load` - Agent loaded context file
- `approval_request` - Agent requested approval
- `error` - Error occurred
---
## Test Expectations
### no_violations
```yaml
expectations:
- type: no_violations
```
**Validates**: No evaluator violations occurred
---
### specific_evaluator
```yaml
expectations:
- type: specific_evaluator
evaluator: approval_gate
should_pass: true
```
**Validates**: Specific evaluator passed/failed as expected
---
### tool_usage
```yaml
expectations:
- type: tool_usage
tools: ["read", "write"]
min_count: 1
```
**Validates**: Specific tools were used
---
### context_loaded
```yaml
expectations:
- type: context_loaded
contexts: ["core/standards/code-quality.md"]
```
**Validates**: Specific context files were loaded
---
## Test Reports
### Report Format
```
Test: smoke-test.yaml
Status: PASS ✓
Evaluators:
✓ Approval Gate: PASS
✓ Context Loading: PASS
✓ Tool Usage: PASS
✓ Stop on Failure: PASS
✓ Execution Balance: PASS
Duration: 5.2s
```
### Failure Report
```
Test: approval-gate.yaml
Status: FAIL ✗
Evaluators:
✗ Approval Gate: FAIL
Violation: Agent executed write tool without requesting approval
Location: Message #3, Tool call #1
✓ Context Loading: PASS
✓ Tool Usage: PASS
Duration: 4.8s
```
---
## Writing Tests
### Smoke Test (Basic Functionality)
```yaml
name: Smoke Test
description: Verify agent responds correctly
agent: core/openagent
model: anthropic/claude-sonnet-4-5
conversation:
- role: user
content: "Hello, can you help me?"
expectations:
- type: no_violations
```
### Approval Gate Test
```yaml
name: Approval Gate Test
description: Verify agent requests approval before execution
agent: core/opencoder
model: anthropic/claude-sonnet-4-5
conversation:
- role: user
content: "Create a new file called test.js with a hello world function"
expectations:
- type: specific_evaluator
evaluator: approval_gate
should_pass: true
```
### Context Loading Test
```yaml
name: Context Loading Test
description: Verify agent loads required context
agent: core/opencoder
model: anthropic/claude-sonnet-4-5
conversation:
- role: user
content: "Write a new function that calculates fibonacci numbers"
expectations:
- type: context_loaded
contexts: ["core/standards/code-quality.md"]
```
---
## Debugging Test Failures
### Step 1: Run with Debug
```bash
cd evals/framework
bun --bun run eval:sdk -- --agent={agent} --pattern="{test}" --debug
```
### Step 2: Check Session
```bash
# Find session
ls -lt .tmp/sessions/ | head -5
# View session
cat .tmp/sessions/{session-id}/session.json | jq
```
### Step 3: Analyze Events
```bash
# View events
cat .tmp/sessions/{session-id}/events.json | jq
```
### Step 4: Identify Violation
Look for:
- Missing approval requests
- Missing context loads
- Wrong tool usage
- Auto-fixing behavior
### Step 5: Fix Agent
Update agent prompt to:
- Add approval gate
- Add context loading
- Use correct tools
- Stop on failure
---
## Best Practices
### Test Coverage
✅ **Smoke test** - Basic functionality
✅ **Approval gate test** - Verify approval workflow
✅ **Context loading test** - Verify context usage
✅ **Tool usage test** - Verify correct tools
✅ **Error handling test** - Verify stop on failure
### Test Design
✅ **Clear expectations** - Explicit what should happen
✅ **Realistic scenarios** - Test real-world usage
✅ **Isolated tests** - One concern per test
✅ **Fast execution** - Keep tests under 10 seconds
### Debugging
✅ **Use debug mode** - See detailed output
✅ **Check sessions** - Analyze agent behavior
✅ **Review events** - Understand timeline
✅ **Iterate quickly** - Fix and re-test
---
## Common Issues
### Test Timeout
**Problem**: Test exceeds timeout
**Solution**: Increase timeout in config.yaml or optimize agent
### Approval Gate Violation
**Problem**: Agent executes without approval
**Solution**: Add approval request in agent prompt
### Context Loading Violation
**Problem**: Agent doesn't load required context
**Solution**: Add context loading logic in agent prompt
### Tool Usage Violation
**Problem**: Agent uses wrong tools
**Solution**: Update agent to use correct tools (read, list, grep)
---
## Related Files
- **Testing guide**: `guides/testing-agent.md`
- **Debugging guide**: `guides/debugging.md`
- **Agent concepts**: `core-concepts/agents.md`
---
**Last Updated**: 2025-12-10
**Version**: 0.5.0

Some files were not shown because too many files have changed in this diff Show More