refactor: simplify agent execution philosophy and reorganize context structure
Major Changes: - Simplified OpenAgent execution philosophy (universal agent, delegate sparingly) - Reorganized context into 3-tier structure: standards/, workflows/, system/ - Improved approval gate wording for clarity - Enhanced .gitignore with comprehensive Node.js patterns - Added comprehensive plugin development guide Context Reorganization: - Consolidated scattered files into organized structure with Quick Reference sections - Emphasis on lazy loading for token efficiency (60-80% token savings) - New standards: code.md, docs.md, tests.md, patterns.md, analysis.md - New workflows: delegation.md, sessions.md, task-breakdown.md, review.md - New system: context-guide.md (master reference) Delegation Improvements: - Removed complex XML-style routing rules - Simplified to clear when/how structure with 7 delegation criteria - Added Perspective and Simulation as delegation triggers - Clearer delegation template and process Documentation Enhancements: - Added building-plugins.md (1,274 lines - comprehensive plugin guide) - Updated how-context-works.md with research-backed architecture - Enhanced slash-commands-and-subagents.md with path resolution findings Content Preservation: - context-discovery.md → system/context-guide.md + workflows/sessions.md - context-management.md → workflows/sessions.md - essential-patterns.md → standards/patterns.md - session-management.md → workflows/sessions.md
This commit is contained in:
darrenhinde
parent
bc8a322550
commit
2bc97007c1
18 changed files with 3215 additions and 551 deletions
140
.gitignore
vendored
140
.gitignore
vendored
|
|
@ -37,6 +37,14 @@ Thumbs.db
|
||||||
# Logs
|
# Logs
|
||||||
logs
|
logs
|
||||||
*.log
|
*.log
|
||||||
|
npm-debug.log*
|
||||||
|
yarn-debug.log*
|
||||||
|
yarn-error.log*
|
||||||
|
lerna-debug.log*
|
||||||
|
.pnpm-debug.log*
|
||||||
|
|
||||||
|
# Diagnostic reports (https://nodejs.org/api/report.html)
|
||||||
|
report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
|
||||||
|
|
||||||
# Runtime data
|
# Runtime data
|
||||||
pids
|
pids
|
||||||
|
|
@ -44,13 +52,141 @@ pids
|
||||||
*.seed
|
*.seed
|
||||||
*.pid.lock
|
*.pid.lock
|
||||||
|
|
||||||
|
# Directory for instrumented libs generated by jscoverage/JSCover
|
||||||
|
lib-cov
|
||||||
|
|
||||||
# Coverage directory used by tools like istanbul
|
# Coverage directory used by tools like istanbul
|
||||||
coverage/
|
coverage
|
||||||
|
*.lcov
|
||||||
|
|
||||||
|
# nyc test coverage
|
||||||
.nyc_output
|
.nyc_output
|
||||||
|
|
||||||
# Temporary folders
|
# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
|
||||||
|
.grunt
|
||||||
|
|
||||||
|
# Bower dependency directory (https://bower.io/)
|
||||||
|
bower_components
|
||||||
|
|
||||||
|
# node-waf configuration
|
||||||
|
.lock-wscript
|
||||||
|
|
||||||
|
# Compiled binary addons (https://nodejs.org/api/addons.html)
|
||||||
|
build/Release
|
||||||
|
|
||||||
|
# Dependency directories
|
||||||
|
node_modules/
|
||||||
|
jspm_packages/
|
||||||
|
|
||||||
|
# Snowpack dependency directory (https://snowpack.dev/)
|
||||||
|
web_modules/
|
||||||
|
|
||||||
|
# TypeScript cache
|
||||||
|
*.tsbuildinfo
|
||||||
|
|
||||||
|
# Optional npm cache directory
|
||||||
|
.npm
|
||||||
|
|
||||||
|
# Optional eslint cache
|
||||||
|
.eslintcache
|
||||||
|
|
||||||
|
# Optional stylelint cache
|
||||||
|
.stylelintcache
|
||||||
|
|
||||||
|
# Microbundle cache
|
||||||
|
.rpt2_cache/
|
||||||
|
.rts2_cache_cjs/
|
||||||
|
.rts2_cache_es/
|
||||||
|
.rts2_cache_umd/
|
||||||
|
|
||||||
|
# Optional REPL history
|
||||||
|
.node_repl_history
|
||||||
|
|
||||||
|
# Output of 'npm pack'
|
||||||
|
*.tgz
|
||||||
|
|
||||||
|
# Yarn Integrity file
|
||||||
|
.yarn-integrity
|
||||||
|
|
||||||
|
# dotenv environment variable files
|
||||||
|
.env
|
||||||
|
.env.development.local
|
||||||
|
.env.test.local
|
||||||
|
.env.production.local
|
||||||
|
.env.local
|
||||||
|
|
||||||
|
# parcel-bundler cache (https://parceljs.org/)
|
||||||
|
.cache
|
||||||
|
.parcel-cache
|
||||||
|
|
||||||
|
# Next.js build output
|
||||||
|
.next
|
||||||
|
out
|
||||||
|
|
||||||
|
# Nuxt.js build / generate output
|
||||||
|
.nuxt
|
||||||
|
dist
|
||||||
|
|
||||||
|
# Gatsby files
|
||||||
|
.cache/
|
||||||
|
# Comment in the public line in if your project uses Gatsby and not Next.js
|
||||||
|
# https://nextjs.org/blog/next-9-1#public-directory-support
|
||||||
|
# public
|
||||||
|
|
||||||
|
# vuepress build output
|
||||||
|
.vuepress/dist
|
||||||
|
|
||||||
|
# vuepress v2.x temp and cache directory
|
||||||
|
.temp
|
||||||
|
.cache
|
||||||
|
|
||||||
|
# Docusaurus cache and generated files
|
||||||
|
.docusaurus
|
||||||
|
|
||||||
|
# Serverless directories
|
||||||
|
.serverless/
|
||||||
|
|
||||||
|
# FuseBox cache
|
||||||
|
.fusebox/
|
||||||
|
|
||||||
|
# DynamoDB Local files
|
||||||
|
.dynamodb/
|
||||||
|
|
||||||
|
# TernJS port file
|
||||||
|
.tern-port
|
||||||
|
|
||||||
|
# Stores VSCode versions used for testing VSCode extensions
|
||||||
|
.vscode-test
|
||||||
|
|
||||||
|
# yarn v2
|
||||||
|
.yarn/cache
|
||||||
|
.yarn/unplugged
|
||||||
|
.yarn/build-state.yml
|
||||||
|
.yarn/install-state.gz
|
||||||
|
.pnp.*
|
||||||
|
|
||||||
|
# macOS
|
||||||
|
.DS_Store
|
||||||
|
|
||||||
|
# IDE
|
||||||
|
.idea/
|
||||||
|
.vscode/
|
||||||
|
*.swp
|
||||||
|
*.swo
|
||||||
|
*~
|
||||||
|
|
||||||
|
# Temporary files
|
||||||
tmp/
|
tmp/
|
||||||
temp/
|
temp/
|
||||||
|
|
||||||
|
# Installation test artifacts
|
||||||
|
.opencode.backup-*
|
||||||
|
.opencode-test/
|
||||||
|
.opencode-agents-version
|
||||||
|
*.backup-*/
|
||||||
|
|
||||||
|
# Test output
|
||||||
|
/tmp/install-output.log
|
||||||
.tmp/
|
.tmp/
|
||||||
|
|
||||||
# Optional npm cache directory
|
# Optional npm cache directory
|
||||||
|
|
|
||||||
|
|
@ -27,7 +27,7 @@ permissions:
|
||||||
|
|
||||||
<critical_rules priority="absolute" enforcement="strict">
|
<critical_rules priority="absolute" enforcement="strict">
|
||||||
<rule id="approval_gate" scope="all_execution">
|
<rule id="approval_gate" scope="all_execution">
|
||||||
ALWAYS request approval before ANY execution (bash, write, edit, task delegation)
|
ALWAYS request approval before ANY execution (bash, write, edit, task delegation). Read and list operations do not require approval.
|
||||||
</rule>
|
</rule>
|
||||||
<rule id="stop_on_failure" scope="validation">
|
<rule id="stop_on_failure" scope="validation">
|
||||||
STOP immediately on test failures or errors - NEVER auto-fix
|
STOP immediately on test failures or errors - NEVER auto-fix
|
||||||
|
|
@ -167,60 +167,58 @@ permissions:
|
||||||
</stage>
|
</stage>
|
||||||
</workflow>
|
</workflow>
|
||||||
|
|
||||||
|
<execution_philosophy>
|
||||||
|
You are a UNIVERSAL agent - handle most tasks directly.
|
||||||
|
|
||||||
|
**Capabilities**: Write code, docs, tests, reviews, analysis, debugging, research, bash, file operations
|
||||||
|
|
||||||
|
**Delegate only when**: 4+ files, specialized expertise needed, thorough multi-component review, complex dependencies, or user requests breakdown
|
||||||
|
|
||||||
|
**Default**: Execute directly, fetch context files as needed (lazy), keep it simple, don't over-delegate
|
||||||
|
|
||||||
|
**Delegation**: Create .tmp/sessions/{id}/context.md with requirements/decisions/files/instructions, reference static context, cleanup after
|
||||||
|
</execution_philosophy>
|
||||||
|
|
||||||
<delegation_rules id="delegation_rules">
|
<delegation_rules id="delegation_rules">
|
||||||
<context_file_creation when="delegating">
|
|
||||||
Only create context file when BOTH:
|
<when_to_delegate>
|
||||||
- Delegating to a subagent AND
|
Delegate to general agent when ANY of these conditions:
|
||||||
- Context is verbose (>2 sentences) OR risk of misinterpretation
|
|
||||||
|
|
||||||
See: .opencode/context/core/context-discovery.md for details
|
1. **Scale**: 4+ files to modify/create
|
||||||
</context_file_creation>
|
2. **Expertise**: Needs specialized knowledge (security, algorithms, architecture, performance)
|
||||||
|
3. **Review**: Needs thorough review across multiple components
|
||||||
<route agent="@subagents/core/task-manager"
|
4. **Complexity**: Multi-step coordination with dependencies
|
||||||
category="features"
|
5. **Perspective**: Need fresh eyes, alternative approaches, or different viewpoint
|
||||||
when="3+_files OR 60+_min OR complex_dependencies OR explicit_request"
|
6. **Simulation**: Testing scenarios, edge cases, user behavior, what-if analysis
|
||||||
output=".tmp/sessions/{id}/tasks/{name}-tasks.md"
|
7. **User request**: User explicitly asks for breakdown/delegation
|
||||||
context_inheritance="true">
|
|
||||||
<example>User: "Build user authentication system"</example>
|
Otherwise: Execute directly (you are universal, handle it)
|
||||||
</route>
|
</when_to_delegate>
|
||||||
|
|
||||||
<route agent="@subagents/core/documentation"
|
<how_to_delegate>
|
||||||
category="documentation"
|
1. Create temp context: `.tmp/sessions/{timestamp}-{task-slug}/context.md`
|
||||||
when="comprehensive_docs OR multi_page OR codebase_analysis OR explicit_request">
|
2. Populate using template from .opencode/context/core/workflows/delegation.md
|
||||||
<example>User: "Create API documentation for all endpoints"</example>
|
3. Delegate with context path and brief description
|
||||||
</route>
|
4. Cleanup after completion (ask user first)
|
||||||
|
|
||||||
<route agent="@subagents/utils/image-specialist"
|
See .opencode/context/core/workflows/delegation.md for full template structure and process.
|
||||||
category="images"
|
</how_to_delegate>
|
||||||
when="image_gen OR image_edit OR image_analysis"
|
|
||||||
availability="check_profile">
|
<examples>
|
||||||
<example>User: "Generate a logo" or "Edit this image"</example>
|
**Execute Directly:**
|
||||||
</route>
|
✅ "Fix this bug" → Single file, clear fix
|
||||||
|
✅ "Add input validation" → Straightforward enhancement
|
||||||
<route agent="@subagents/code/reviewer"
|
|
||||||
category="review"
|
**Delegate for Complexity:**
|
||||||
when="code_review OR security_analysis"
|
⚠️ "Refactor data layer across 5 files" → Multi-file coordination
|
||||||
availability="check_profile">
|
⚠️ "Implement feature X with Y and Z components" → 4+ files, complex integration
|
||||||
<example>User: "Review this code for security issues"</example>
|
|
||||||
</route>
|
**Delegate for Perspective/Simulation:**
|
||||||
|
⚠️ "Review this API design - what could go wrong?" → Fresh perspective needed
|
||||||
<route agent="@subagents/code/codebase-pattern-analyst"
|
⚠️ "Simulate edge cases for this algorithm" → Testing scenarios
|
||||||
category="patterns"
|
⚠️ "What are alternative approaches to solve X?" → Brainstorming alternatives
|
||||||
when="pattern_discovery OR how_do_we_questions"
|
</examples>
|
||||||
availability="check_profile">
|
|
||||||
<example>User: "How do we handle pagination in this codebase?"</example>
|
|
||||||
</route>
|
|
||||||
|
|
||||||
<route agent="@subagents/code/*"
|
|
||||||
category="code"
|
|
||||||
when="code_specific_task"
|
|
||||||
availability="check_profile">
|
|
||||||
<example>User: "Write tests for this function"</example>
|
|
||||||
</route>
|
|
||||||
|
|
||||||
<direct_execution when="single_file OR simple_task_under_30min OR quick_edit OR explicit_openagent_request">
|
|
||||||
<example>User: "Create a README" or "Update this function"</example>
|
|
||||||
</direct_execution>
|
|
||||||
</delegation_rules>
|
</delegation_rules>
|
||||||
|
|
||||||
<principles>
|
<principles>
|
||||||
|
|
@ -236,17 +234,36 @@ permissions:
|
||||||
<transparent>Explain decisions, show reasoning when helpful</transparent>
|
<transparent>Explain decisions, show reasoning when helpful</transparent>
|
||||||
</principles>
|
</principles>
|
||||||
|
|
||||||
<references>
|
<static_context>
|
||||||
<session_management ref=".opencode/context/core/session-management.md">
|
Guidelines in .opencode/context/core/ - fetch when needed (WITHOUT @):
|
||||||
Lazy initialization, session isolation, cleanup policy, error handling
|
|
||||||
</session_management>
|
**Standards** (quality guidelines + analysis):
|
||||||
<context_discovery ref=".opencode/context/core/context-discovery.md">
|
- standards/code.md - Modular, functional code
|
||||||
Dynamic context loading, manifest indexing, keyword search, delegation patterns
|
- standards/docs.md - Documentation standards
|
||||||
</context_discovery>
|
- standards/tests.md - Testing standards
|
||||||
<context_management ref=".opencode/context/core/context-management.md">
|
- standards/patterns.md - Core patterns
|
||||||
Full context management strategy including session structure and workflows
|
- standards/analysis.md - Analysis framework
|
||||||
</context_management>
|
|
||||||
<essential_patterns ref=".opencode/context/core/essential-patterns.md">
|
**Workflows** (process templates + review):
|
||||||
Core coding patterns, error handling, security, testing best practices
|
- workflows/delegation.md - Delegation template
|
||||||
</essential_patterns>
|
- workflows/task-breakdown.md - Task breakdown
|
||||||
</references>
|
- workflows/sessions.md - Session lifecycle
|
||||||
|
- workflows/review.md - Code review guidelines
|
||||||
|
|
||||||
|
See system/context-guide.md for full guide. Fetch only what's relevant - keeps prompts lean.
|
||||||
|
</static_context>
|
||||||
|
|
||||||
|
<critical_rules priority="absolute" enforcement="strict">
|
||||||
|
<rule id="approval_gate" scope="all_execution">
|
||||||
|
ALWAYS request approval before ANY execution (bash, write, edit, task delegation). Read and list operations do not require approval.
|
||||||
|
</rule>
|
||||||
|
<rule id="stop_on_failure" scope="validation">
|
||||||
|
STOP immediately on test failures or errors - NEVER auto-fix
|
||||||
|
</rule>
|
||||||
|
<rule id="report_first" scope="error_handling">
|
||||||
|
On failure: REPORT → PROPOSE FIX → REQUEST APPROVAL → FIX (never auto-fix)
|
||||||
|
</rule>
|
||||||
|
<rule id="confirm_cleanup" scope="session_management">
|
||||||
|
ALWAYS confirm before deleting session files or cleanup operations
|
||||||
|
</rule>
|
||||||
|
</critical_rules>
|
||||||
|
|
|
||||||
|
|
@ -1,226 +0,0 @@
|
||||||
# Context Discovery
|
|
||||||
|
|
||||||
## Purpose
|
|
||||||
|
|
||||||
**Dynamically load relevant context files when delegating to subagents**
|
|
||||||
|
|
||||||
Allows subagents to discover and access context created earlier in the session, preventing information loss across delegation boundaries.
|
|
||||||
|
|
||||||
## How It Works
|
|
||||||
|
|
||||||
### 1. Context File Creation
|
|
||||||
|
|
||||||
When creating a context file, add metadata to manifest:
|
|
||||||
|
|
||||||
```json
|
|
||||||
"context_files": {
|
|
||||||
"features/user-auth-context.md": {
|
|
||||||
"created": "2025-01-18T14:30:22Z",
|
|
||||||
"for": "@subagents/core/task-manager",
|
|
||||||
"keywords": ["user-auth", "authentication", "features"]
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
**Metadata Fields**:
|
|
||||||
- `created`: Timestamp of file creation
|
|
||||||
- `for`: Target subagent (which agent will use this)
|
|
||||||
- `keywords`: Array of searchable keywords for discovery
|
|
||||||
|
|
||||||
### 2. Context Indexing
|
|
||||||
|
|
||||||
Manifest maintains keyword index for fast lookup:
|
|
||||||
|
|
||||||
```json
|
|
||||||
"context_index": {
|
|
||||||
"user-auth": [
|
|
||||||
"features/user-auth-context.md",
|
|
||||||
"tasks/user-auth-tasks.md"
|
|
||||||
],
|
|
||||||
"api": [
|
|
||||||
"documentation/api-docs-context.md"
|
|
||||||
]
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
**Index Structure**:
|
|
||||||
- Key: Keyword (from context file metadata)
|
|
||||||
- Value: Array of file paths containing that keyword
|
|
||||||
|
|
||||||
### 3. Context Discovery Process
|
|
||||||
|
|
||||||
When delegating to subagent:
|
|
||||||
|
|
||||||
1. **Extract keywords** from user request or task context
|
|
||||||
2. **Search manifest** `context_index` for matching keywords
|
|
||||||
3. **Find related files** by category or keyword match
|
|
||||||
4. **Pass file paths** to subagent in delegation prompt
|
|
||||||
5. **Subagent reads** context files as needed
|
|
||||||
|
|
||||||
### 4. Delegation Pattern
|
|
||||||
|
|
||||||
**Context Reference Format**:
|
|
||||||
```
|
|
||||||
Related context available at: .tmp/sessions/{session-id}/features/user-auth-context.md
|
|
||||||
```
|
|
||||||
|
|
||||||
**Full Delegation Example**:
|
|
||||||
```
|
|
||||||
Delegating to @subagents/code/coder-agent:
|
|
||||||
|
|
||||||
"Implement user authentication login component.
|
|
||||||
|
|
||||||
Related context available at:
|
|
||||||
- .tmp/sessions/20250118-143022-a4f2/features/user-auth-context.md
|
|
||||||
- .tmp/sessions/20250118-143022-a4f2/tasks/user-auth-tasks.md
|
|
||||||
|
|
||||||
Read these files for full context on requirements and task breakdown."
|
|
||||||
```
|
|
||||||
|
|
||||||
## When to Create Context Files
|
|
||||||
|
|
||||||
**Only create when ALL of these apply**:
|
|
||||||
- Delegating to a subagent
|
|
||||||
- Context description is verbose (>2 sentences) OR
|
|
||||||
- Risk of misinterpretation without detailed context
|
|
||||||
|
|
||||||
**Don't create for**:
|
|
||||||
- Simple, one-line instructions
|
|
||||||
- Direct execution (no delegation)
|
|
||||||
- Conversational questions
|
|
||||||
|
|
||||||
## Context File Categories
|
|
||||||
|
|
||||||
```
|
|
||||||
features/ - Feature development context
|
|
||||||
documentation/ - Documentation tasks
|
|
||||||
code/ - Code-related tasks
|
|
||||||
refactoring/ - Refactoring tasks
|
|
||||||
testing/ - Testing tasks
|
|
||||||
tasks/ - Task breakdowns created by task-manager
|
|
||||||
general/ - General tasks that don't fit other categories
|
|
||||||
```
|
|
||||||
|
|
||||||
## Context File Template
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
# Context: {Task Name}
|
|
||||||
Session: {session-id}
|
|
||||||
|
|
||||||
## Request Summary
|
|
||||||
[Brief description of what needs to be done]
|
|
||||||
|
|
||||||
## Background
|
|
||||||
[Relevant context and information]
|
|
||||||
|
|
||||||
## Expected Output
|
|
||||||
[What the subagent should produce]
|
|
||||||
|
|
||||||
## Constraints
|
|
||||||
[Any limitations or requirements]
|
|
||||||
|
|
||||||
## Related Context
|
|
||||||
[Links to other context files if applicable]
|
|
||||||
```
|
|
||||||
|
|
||||||
## Discovery Strategies
|
|
||||||
|
|
||||||
### By Keyword
|
|
||||||
Search `context_index` for exact keyword matches:
|
|
||||||
```
|
|
||||||
User: "Add login validation"
|
|
||||||
Keywords: ["login", "validation", "user-auth"]
|
|
||||||
→ Finds: features/user-auth-context.md, tasks/user-auth-tasks.md
|
|
||||||
```
|
|
||||||
|
|
||||||
### By Category
|
|
||||||
Search `context_files` for matching category:
|
|
||||||
```
|
|
||||||
Delegating to @documentation agent
|
|
||||||
Category: "documentation"
|
|
||||||
→ Finds all files in documentation/ folder
|
|
||||||
```
|
|
||||||
|
|
||||||
### By Target Agent
|
|
||||||
Search `context_files` for files created for specific agent:
|
|
||||||
```
|
|
||||||
Delegating to @task-manager
|
|
||||||
Filter: "for": "@subagents/core/task-manager"
|
|
||||||
→ Finds all context files created for task-manager
|
|
||||||
```
|
|
||||||
|
|
||||||
## Example Workflow
|
|
||||||
|
|
||||||
```
|
|
||||||
1. User: "Build user authentication system"
|
|
||||||
→ OpenAgent creates: features/user-auth-context.md
|
|
||||||
→ Manifest updated with keywords: ["user-auth", "authentication", "features"]
|
|
||||||
→ Delegates to @task-manager with context file path
|
|
||||||
|
|
||||||
2. Task-manager creates: tasks/user-auth-tasks.md
|
|
||||||
→ Manifest updated with keywords: ["user-auth", "tasks", "breakdown"]
|
|
||||||
→ Both files now indexed under "user-auth"
|
|
||||||
|
|
||||||
3. User: "Implement the login component"
|
|
||||||
→ OpenAgent searches manifest for "user-auth" OR "login"
|
|
||||||
→ Finds: features/user-auth-context.md, tasks/user-auth-tasks.md
|
|
||||||
→ Delegates to @coder-agent with references to BOTH files
|
|
||||||
→ Coder-agent reads both files to understand full context
|
|
||||||
|
|
||||||
4. User: "Add password reset feature"
|
|
||||||
→ OpenAgent searches manifest for "user-auth" OR "password"
|
|
||||||
→ Finds existing user-auth context
|
|
||||||
→ Creates new: features/password-reset-context.md
|
|
||||||
→ Links to existing user-auth context
|
|
||||||
→ Delegates with all related context files
|
|
||||||
```
|
|
||||||
|
|
||||||
## Benefits
|
|
||||||
|
|
||||||
✅ **No context loss**: Information persists across subagent calls
|
|
||||||
✅ **Automatic discovery**: Related context found by keywords
|
|
||||||
✅ **Flexible**: Subagents read only what they need
|
|
||||||
✅ **Traceable**: Manifest shows all context relationships
|
|
||||||
✅ **Scalable**: Works with multiple context files per session
|
|
||||||
✅ **Reusable**: Later tasks can reference earlier context
|
|
||||||
|
|
||||||
## Context Inheritance
|
|
||||||
|
|
||||||
**Load related context files from manifest before delegating**
|
|
||||||
|
|
||||||
When delegating to a subagent:
|
|
||||||
1. Check if session exists
|
|
||||||
2. Read manifest if available
|
|
||||||
3. Search for related context by keyword/category
|
|
||||||
4. Include relevant context file paths in delegation
|
|
||||||
5. Subagent reads context files as first step
|
|
||||||
|
|
||||||
This ensures subagents have full context from earlier in the session.
|
|
||||||
|
|
||||||
## Error Handling
|
|
||||||
|
|
||||||
### Manifest Not Found
|
|
||||||
- Session not initialized yet
|
|
||||||
- Continue without context discovery
|
|
||||||
- Create new session if context file needed
|
|
||||||
|
|
||||||
### Context File Missing
|
|
||||||
- File was deleted or moved
|
|
||||||
- Warn user about missing context
|
|
||||||
- Continue with available context
|
|
||||||
- Update manifest to remove missing file
|
|
||||||
|
|
||||||
### Keyword Collision
|
|
||||||
- Multiple files match same keyword
|
|
||||||
- Include all matching files in delegation
|
|
||||||
- Let subagent determine relevance
|
|
||||||
- Consider more specific keywords in future
|
|
||||||
|
|
||||||
## Best Practices
|
|
||||||
|
|
||||||
1. **Use specific keywords**: "user-auth" better than "auth"
|
|
||||||
2. **Include category in keywords**: ["features", "user-auth"]
|
|
||||||
3. **Link related context**: Reference other context files
|
|
||||||
4. **Update manifest immediately**: Don't delay indexing
|
|
||||||
5. **Clean up stale context**: Remove when task complete
|
|
||||||
6. **Validate file exists**: Before passing to subagent
|
|
||||||
|
|
@ -1,256 +0,0 @@
|
||||||
# Context Management Strategy
|
|
||||||
|
|
||||||
## Session-Based Isolation
|
|
||||||
|
|
||||||
### Purpose
|
|
||||||
Prevent concurrent agent instances from interfering with each other by using isolated session folders.
|
|
||||||
|
|
||||||
### Session Structure
|
|
||||||
```
|
|
||||||
.tmp/sessions/{session-id}/{task-category}/{task-name}-context.md
|
|
||||||
```
|
|
||||||
|
|
||||||
### Session ID Format
|
|
||||||
`{timestamp}-{random-4-chars}`
|
|
||||||
|
|
||||||
Example: `20250118-143022-a4f2`
|
|
||||||
|
|
||||||
### Session Manifest
|
|
||||||
Each session has a manifest file tracking all context files:
|
|
||||||
|
|
||||||
**Location**: `.tmp/sessions/{session-id}/.manifest.json`
|
|
||||||
|
|
||||||
**Structure**:
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"session_id": "20250118-143022-a4f2",
|
|
||||||
"created_at": "2025-01-18T14:30:22Z",
|
|
||||||
"last_activity": "2025-01-18T14:35:10Z",
|
|
||||||
"context_files": {
|
|
||||||
"features/user-auth-context.md": {
|
|
||||||
"created": "2025-01-18T14:30:22Z",
|
|
||||||
"for": "@subagents/core/task-manager",
|
|
||||||
"keywords": ["user-auth", "authentication", "features"]
|
|
||||||
},
|
|
||||||
"tasks/user-auth-tasks.md": {
|
|
||||||
"created": "2025-01-18T14:32:15Z",
|
|
||||||
"for": "@subagents/core/task-manager",
|
|
||||||
"keywords": ["user-auth", "tasks", "breakdown"]
|
|
||||||
},
|
|
||||||
"documentation/api-docs-context.md": {
|
|
||||||
"created": "2025-01-18T14:35:10Z",
|
|
||||||
"for": "@subagents/core/documentation",
|
|
||||||
"keywords": ["api", "documentation"]
|
|
||||||
}
|
|
||||||
},
|
|
||||||
"context_index": {
|
|
||||||
"user-auth": [
|
|
||||||
"features/user-auth-context.md",
|
|
||||||
"tasks/user-auth-tasks.md"
|
|
||||||
],
|
|
||||||
"api": [
|
|
||||||
"documentation/api-docs-context.md"
|
|
||||||
]
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## Temporary Context Files
|
|
||||||
|
|
||||||
### When to Create
|
|
||||||
Only create context files when **ALL** of these apply:
|
|
||||||
- Delegating to a subagent
|
|
||||||
- Context description is verbose (>2 sentences) OR
|
|
||||||
- Risk of misinterpretation without detailed context
|
|
||||||
|
|
||||||
### File Structure
|
|
||||||
```
|
|
||||||
.tmp/sessions/{session-id}/{task-category}/{task-name}-context.md
|
|
||||||
```
|
|
||||||
|
|
||||||
### Categories
|
|
||||||
- `features/` - Feature development context
|
|
||||||
- `documentation/` - Documentation tasks
|
|
||||||
- `code/` - Code-related tasks
|
|
||||||
- `refactoring/` - Refactoring tasks
|
|
||||||
- `testing/` - Testing tasks
|
|
||||||
- `tasks/` - Task breakdowns created by task-manager
|
|
||||||
- `general/` - General tasks that don't fit other categories
|
|
||||||
|
|
||||||
### Examples
|
|
||||||
```
|
|
||||||
.tmp/sessions/20250118-143022-a4f2/features/user-auth-context.md
|
|
||||||
.tmp/sessions/20250118-143022-a4f2/documentation/api-docs-context.md
|
|
||||||
.tmp/sessions/20250118-150000-b7k9/code/database-refactor-context.md
|
|
||||||
.tmp/sessions/20250118-151500-c3x8/testing/integration-tests-context.md
|
|
||||||
```
|
|
||||||
|
|
||||||
### File Contents
|
|
||||||
```markdown
|
|
||||||
# Context: {Task Name}
|
|
||||||
Session: {session-id}
|
|
||||||
|
|
||||||
## Request Summary
|
|
||||||
[Brief description of what needs to be done]
|
|
||||||
|
|
||||||
## Background
|
|
||||||
[Relevant context and information]
|
|
||||||
|
|
||||||
## Expected Output
|
|
||||||
[What the subagent should produce]
|
|
||||||
|
|
||||||
## Constraints
|
|
||||||
[Any limitations or requirements]
|
|
||||||
```
|
|
||||||
|
|
||||||
## Cleanup Strategy
|
|
||||||
|
|
||||||
### During Session
|
|
||||||
1. Remove individual context files after task completion
|
|
||||||
2. Update manifest to remove file entry
|
|
||||||
3. Update `last_activity` timestamp
|
|
||||||
|
|
||||||
### End of Session
|
|
||||||
1. Remove entire session folder: `.tmp/sessions/{session-id}/`
|
|
||||||
2. Only delete files tracked in current session's manifest
|
|
||||||
|
|
||||||
### Stale Session Cleanup
|
|
||||||
- Automatically clean sessions older than 24 hours with no activity
|
|
||||||
- Check `last_activity` timestamp in manifest
|
|
||||||
- Safe to run periodically without affecting active sessions
|
|
||||||
|
|
||||||
### Manual Cleanup
|
|
||||||
Users can safely delete:
|
|
||||||
- Entire `.tmp/` folder anytime
|
|
||||||
- Individual session folders
|
|
||||||
- Stale sessions (check `last_activity` timestamp)
|
|
||||||
|
|
||||||
## Concurrent Safety
|
|
||||||
|
|
||||||
### Isolation Guarantees
|
|
||||||
✅ Each agent instance has unique session ID
|
|
||||||
✅ Context files are isolated per session
|
|
||||||
✅ Manifest tracks only files created by this session
|
|
||||||
✅ Cleanup only affects current session's files
|
|
||||||
✅ No risk of deleting another instance's context
|
|
||||||
|
|
||||||
### Best Practices
|
|
||||||
1. **Generate session ID early** - At first context file creation
|
|
||||||
2. **Track all files** - Add every context file to manifest
|
|
||||||
3. **Update activity** - Touch `last_activity` on each operation
|
|
||||||
4. **Clean up promptly** - Remove files after task completion
|
|
||||||
5. **Only clean own files** - Never delete files outside current session
|
|
||||||
|
|
||||||
## Dynamic Context Loading
|
|
||||||
|
|
||||||
### Purpose
|
|
||||||
Allow subagents to discover and load relevant context files created earlier in the session.
|
|
||||||
|
|
||||||
### How It Works
|
|
||||||
|
|
||||||
**1. Context File Creation**
|
|
||||||
When creating a context file, add metadata to manifest:
|
|
||||||
```json
|
|
||||||
"context_files": {
|
|
||||||
"features/user-auth-context.md": {
|
|
||||||
"created": "2025-01-18T14:30:22Z",
|
|
||||||
"for": "@subagents/core/task-manager",
|
|
||||||
"keywords": ["user-auth", "authentication", "features"]
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
**2. Context Indexing**
|
|
||||||
Manifest maintains keyword index for fast lookup:
|
|
||||||
```json
|
|
||||||
"context_index": {
|
|
||||||
"user-auth": [
|
|
||||||
"features/user-auth-context.md",
|
|
||||||
"tasks/user-auth-tasks.md"
|
|
||||||
]
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
**3. Context Discovery**
|
|
||||||
When delegating to subagent:
|
|
||||||
1. Search manifest for related context files (by keyword/category)
|
|
||||||
2. Pass relevant context file paths to subagent
|
|
||||||
3. Subagent reads context files as needed
|
|
||||||
|
|
||||||
**4. Delegation Pattern**
|
|
||||||
```
|
|
||||||
Delegating to @subagents/code/coder-agent:
|
|
||||||
"Implement user authentication login component.
|
|
||||||
|
|
||||||
Related context available at:
|
|
||||||
- .tmp/sessions/20250118-143022-a4f2/features/user-auth-context.md
|
|
||||||
- .tmp/sessions/20250118-143022-a4f2/tasks/user-auth-tasks.md
|
|
||||||
|
|
||||||
Read these files for full context on requirements and task breakdown."
|
|
||||||
```
|
|
||||||
|
|
||||||
### Example Workflow
|
|
||||||
|
|
||||||
```
|
|
||||||
1. User: "Build user authentication system"
|
|
||||||
→ OpenAgent creates: features/user-auth-context.md
|
|
||||||
→ Delegates to @task-manager
|
|
||||||
|
|
||||||
2. Task-manager creates: tasks/user-auth-tasks.md
|
|
||||||
→ Both files tracked in manifest with keyword "user-auth"
|
|
||||||
|
|
||||||
3. User: "Implement the login component"
|
|
||||||
→ OpenAgent searches manifest for "user-auth" context
|
|
||||||
→ Finds both context files
|
|
||||||
→ Delegates to @coder-agent with references to both files
|
|
||||||
→ Coder-agent reads files to understand full context
|
|
||||||
```
|
|
||||||
|
|
||||||
### Benefits
|
|
||||||
- **No context loss**: Information persists across subagent calls
|
|
||||||
- **Automatic discovery**: Related context found by keywords
|
|
||||||
- **Flexible**: Subagents read only what they need
|
|
||||||
- **Traceable**: Manifest shows all context relationships
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Why This Approach?
|
|
||||||
|
|
||||||
### Session Isolation
|
|
||||||
- **Concurrent safety**: Multiple agents can run simultaneously
|
|
||||||
- **No conflicts**: Each session has its own namespace
|
|
||||||
- **Easy cleanup**: Delete entire session folder when done
|
|
||||||
- **Traceable**: Manifest shows what belongs to each session
|
|
||||||
|
|
||||||
### Dynamic Context
|
|
||||||
- **Discoverable**: Context files indexed by keywords
|
|
||||||
- **Reusable**: Later subagents can access earlier context
|
|
||||||
- **Flexible**: Load only relevant context
|
|
||||||
- **Persistent**: Context survives across subagent calls
|
|
||||||
|
|
||||||
### Why `.tmp/sessions/`?
|
|
||||||
- Standard `.tmp/` convention (commonly ignored)
|
|
||||||
- `sessions/` subfolder makes purpose clear
|
|
||||||
- Session ID provides unique namespace
|
|
||||||
- Easy to identify and clean up stale sessions
|
|
||||||
- Hidden folder (starts with `.`)
|
|
||||||
|
|
||||||
## Example Workflow
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Agent Instance 1 starts
|
|
||||||
Session ID: 20250118-143022-a4f2
|
|
||||||
Creates: .tmp/sessions/20250118-143022-a4f2/features/user-auth-context.md
|
|
||||||
|
|
||||||
# Agent Instance 2 starts (concurrent)
|
|
||||||
Session ID: 20250118-143030-b7k9
|
|
||||||
Creates: .tmp/sessions/20250118-143030-b7k9/features/payment-context.md
|
|
||||||
|
|
||||||
# Both agents work independently without conflicts
|
|
||||||
|
|
||||||
# Agent Instance 1 completes
|
|
||||||
Deletes: .tmp/sessions/20250118-143022-a4f2/ (entire folder)
|
|
||||||
|
|
||||||
# Agent Instance 2 continues unaffected
|
|
||||||
Still has: .tmp/sessions/20250118-143030-b7k9/
|
|
||||||
```
|
|
||||||
150
.opencode/context/core/standards/analysis.md
Normal file
150
.opencode/context/core/standards/analysis.md
Normal file
|
|
@ -0,0 +1,150 @@
|
||||||
|
# Analysis Guidelines
|
||||||
|
|
||||||
|
## Quick Reference
|
||||||
|
|
||||||
|
**Process**: Context → Gather → Patterns → Impact → Recommendations
|
||||||
|
|
||||||
|
**Report Format**: Context, Findings, Patterns, Issues (🔴🟡🔵), Recommendations, Trade-offs, Next Steps
|
||||||
|
|
||||||
|
**Be**: Thorough, Objective, Specific, Actionable
|
||||||
|
|
||||||
|
**Checklist**: Context stated, Evidence gathered, Patterns identified, Issues prioritized, Recommendations specific, Trade-offs considered
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Purpose
|
||||||
|
Framework for analyzing code, patterns, and technical issues systematically.
|
||||||
|
|
||||||
|
## When to Use
|
||||||
|
Reference this when:
|
||||||
|
- Analyzing codebase patterns
|
||||||
|
- Investigating bugs or issues
|
||||||
|
- Evaluating architectural decisions
|
||||||
|
- Assessing code quality
|
||||||
|
- Researching solutions
|
||||||
|
|
||||||
|
## Analysis Process
|
||||||
|
|
||||||
|
### 1. Understand Context
|
||||||
|
- What are we analyzing and why?
|
||||||
|
- What's the goal or question?
|
||||||
|
- What's the scope?
|
||||||
|
- What constraints exist?
|
||||||
|
|
||||||
|
### 2. Gather Information
|
||||||
|
- Read relevant code / data points
|
||||||
|
- Check documentation
|
||||||
|
- Search for patterns
|
||||||
|
- Review related issues
|
||||||
|
- Examine dependencies
|
||||||
|
|
||||||
|
### 3. Identify Patterns
|
||||||
|
- What's consistent across the codebase?
|
||||||
|
- What conventions are followed?
|
||||||
|
- What patterns are repeated?
|
||||||
|
- What's inconsistent or unusual?
|
||||||
|
|
||||||
|
### 4. Assess Impact
|
||||||
|
- What are the implications?
|
||||||
|
- What are the trade-offs?
|
||||||
|
- What could break?
|
||||||
|
- What are the risks?
|
||||||
|
|
||||||
|
### 5. Provide Recommendations
|
||||||
|
- What should be done?
|
||||||
|
- Why this approach?
|
||||||
|
- What are alternatives?
|
||||||
|
- What's the priority?
|
||||||
|
|
||||||
|
## Analysis Report Format
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
## Analysis: {Topic}
|
||||||
|
|
||||||
|
**Context:** {What we're analyzing and why}
|
||||||
|
|
||||||
|
**Findings:**
|
||||||
|
- {Key finding 1}
|
||||||
|
- {Key finding 2}
|
||||||
|
- {Key finding 3}
|
||||||
|
|
||||||
|
**Patterns Observed:**
|
||||||
|
- {Pattern 1}: {Description}
|
||||||
|
- {Pattern 2}: {Description}
|
||||||
|
|
||||||
|
**Issues Identified:**
|
||||||
|
- 🔴 Critical: {Issue requiring immediate attention}
|
||||||
|
- 🟡 Warning: {Issue to address soon}
|
||||||
|
- 🔵 Suggestion: {Nice-to-have improvement}
|
||||||
|
|
||||||
|
**Recommendations:**
|
||||||
|
1. {Recommendation 1} - {Why}
|
||||||
|
2. {Recommendation 2} - {Why}
|
||||||
|
|
||||||
|
**Trade-offs:**
|
||||||
|
- {Approach A}: {Pros/Cons}
|
||||||
|
- {Approach B}: {Pros/Cons}
|
||||||
|
|
||||||
|
**Next Steps:**
|
||||||
|
- {Action 1}
|
||||||
|
- {Action 2}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Common Analysis Types
|
||||||
|
|
||||||
|
### Code Quality Analysis
|
||||||
|
- Complexity (cyclomatic, cognitive)
|
||||||
|
- Duplication
|
||||||
|
- Test coverage
|
||||||
|
- Documentation completeness
|
||||||
|
- Naming consistency
|
||||||
|
- Error handling patterns
|
||||||
|
|
||||||
|
### Architecture Analysis
|
||||||
|
- Module dependencies
|
||||||
|
- Coupling and cohesion
|
||||||
|
- Separation of concerns
|
||||||
|
- Scalability considerations
|
||||||
|
- Performance bottlenecks
|
||||||
|
|
||||||
|
### Bug Investigation
|
||||||
|
- Reproduce the issue
|
||||||
|
- Identify root cause
|
||||||
|
- Assess impact and severity
|
||||||
|
- Propose fix with rationale
|
||||||
|
- Consider edge cases
|
||||||
|
|
||||||
|
### Pattern Discovery
|
||||||
|
- Search for similar implementations
|
||||||
|
- Identify common approaches
|
||||||
|
- Document conventions
|
||||||
|
- Note inconsistencies
|
||||||
|
- Recommend standardization
|
||||||
|
|
||||||
|
## Best Practices
|
||||||
|
|
||||||
|
### Be Thorough
|
||||||
|
- Check multiple examples
|
||||||
|
- Consider edge cases
|
||||||
|
- Look for exceptions
|
||||||
|
- Verify assumptions
|
||||||
|
|
||||||
|
### Be Objective
|
||||||
|
- Base conclusions on evidence
|
||||||
|
- Avoid assumptions
|
||||||
|
- Consider multiple perspectives
|
||||||
|
- Acknowledge limitations
|
||||||
|
|
||||||
|
### Be Specific
|
||||||
|
- Provide concrete examples
|
||||||
|
- Include file names and line numbers
|
||||||
|
- Show code snippets
|
||||||
|
- Quantify when possible
|
||||||
|
|
||||||
|
### Be Actionable
|
||||||
|
- Clear recommendations
|
||||||
|
- Prioritize findings
|
||||||
|
- Explain rationale
|
||||||
|
- Suggest next steps
|
||||||
|
|
||||||
|
|
||||||
163
.opencode/context/core/standards/code.md
Normal file
163
.opencode/context/core/standards/code.md
Normal file
|
|
@ -0,0 +1,163 @@
|
||||||
|
# Code Standards
|
||||||
|
|
||||||
|
## Quick Reference
|
||||||
|
|
||||||
|
**Core Philosophy**: Modular, Functional, Maintainable
|
||||||
|
**Golden Rule**: If you can't easily test it, refactor it
|
||||||
|
|
||||||
|
**Critical Patterns** (use these):
|
||||||
|
- ✅ Pure functions (same input = same output, no side effects)
|
||||||
|
- ✅ Immutability (create new data, don't modify)
|
||||||
|
- ✅ Composition (build complex from simple)
|
||||||
|
- ✅ Small functions (< 50 lines)
|
||||||
|
- ✅ Explicit dependencies (dependency injection)
|
||||||
|
|
||||||
|
**Anti-Patterns** (avoid these):
|
||||||
|
- ❌ Mutation, side effects, deep nesting
|
||||||
|
- ❌ God modules, global state, large functions
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Core Philosophy
|
||||||
|
|
||||||
|
**Modular**: Everything is a component - small, focused, reusable
|
||||||
|
**Functional**: Pure functions, immutability, composition over inheritance
|
||||||
|
**Maintainable**: Self-documenting, testable, predictable
|
||||||
|
|
||||||
|
## Principles
|
||||||
|
|
||||||
|
### Modular Design
|
||||||
|
- Single responsibility per module
|
||||||
|
- Clear interfaces (explicit inputs/outputs)
|
||||||
|
- Independent and composable
|
||||||
|
- < 100 lines per component (ideally < 50)
|
||||||
|
|
||||||
|
### Functional Approach
|
||||||
|
- **Pure functions**: Same input = same output, no side effects
|
||||||
|
- **Immutability**: Create new data, don't modify existing
|
||||||
|
- **Composition**: Build complex from simple functions
|
||||||
|
- **Declarative**: Describe what, not how
|
||||||
|
|
||||||
|
### Component Structure
|
||||||
|
```
|
||||||
|
component/
|
||||||
|
├── index.js # Public interface
|
||||||
|
├── core.js # Core logic (pure functions)
|
||||||
|
├── utils.js # Helpers
|
||||||
|
└── tests/ # Tests
|
||||||
|
```
|
||||||
|
|
||||||
|
## Patterns
|
||||||
|
|
||||||
|
### Pure Functions
|
||||||
|
```javascript
|
||||||
|
// ✅ Pure
|
||||||
|
const add = (a, b) => a + b;
|
||||||
|
const formatUser = (user) => ({ ...user, fullName: `${user.firstName} ${user.lastName}` });
|
||||||
|
|
||||||
|
// ❌ Impure (side effects)
|
||||||
|
let total = 0;
|
||||||
|
const addToTotal = (value) => { total += value; return total; };
|
||||||
|
```
|
||||||
|
|
||||||
|
### Immutability
|
||||||
|
```javascript
|
||||||
|
// ✅ Immutable
|
||||||
|
const addItem = (items, item) => [...items, item];
|
||||||
|
const updateUser = (user, changes) => ({ ...user, ...changes });
|
||||||
|
|
||||||
|
// ❌ Mutable
|
||||||
|
const addItem = (items, item) => { items.push(item); return items; };
|
||||||
|
```
|
||||||
|
|
||||||
|
### Composition
|
||||||
|
```javascript
|
||||||
|
// ✅ Compose small functions
|
||||||
|
const processUser = pipe(validateUser, enrichUserData, saveUser);
|
||||||
|
const isValidEmail = (email) => validateEmail(normalizeEmail(email));
|
||||||
|
|
||||||
|
// ❌ Deep inheritance
|
||||||
|
class ExtendedUserManagerWithValidation extends UserManager { }
|
||||||
|
```
|
||||||
|
|
||||||
|
### Declarative
|
||||||
|
```javascript
|
||||||
|
// ✅ Declarative
|
||||||
|
const activeUsers = users.filter(u => u.isActive).map(u => u.name);
|
||||||
|
|
||||||
|
// ❌ Imperative
|
||||||
|
const names = [];
|
||||||
|
for (let i = 0; i < users.length; i++) {
|
||||||
|
if (users[i].isActive) names.push(users[i].name);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Naming
|
||||||
|
|
||||||
|
- **Files**: lowercase-with-dashes.js
|
||||||
|
- **Functions**: verbPhrases (getUser, validateEmail)
|
||||||
|
- **Predicates**: isValid, hasPermission, canAccess
|
||||||
|
- **Variables**: descriptive (userCount not uc), const by default
|
||||||
|
- **Constants**: UPPER_SNAKE_CASE
|
||||||
|
|
||||||
|
## Error Handling
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
// ✅ Explicit error handling
|
||||||
|
function parseJSON(text) {
|
||||||
|
try {
|
||||||
|
return { success: true, data: JSON.parse(text) };
|
||||||
|
} catch (error) {
|
||||||
|
return { success: false, error: error.message };
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// ✅ Validate at boundaries
|
||||||
|
function createUser(userData) {
|
||||||
|
const validation = validateUserData(userData);
|
||||||
|
if (!validation.isValid) {
|
||||||
|
return { success: false, errors: validation.errors };
|
||||||
|
}
|
||||||
|
return { success: true, user: saveUser(userData) };
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Dependency Injection
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
// ✅ Dependencies explicit
|
||||||
|
function createUserService(database, logger) {
|
||||||
|
return {
|
||||||
|
createUser: (userData) => {
|
||||||
|
logger.info('Creating user');
|
||||||
|
return database.insert('users', userData);
|
||||||
|
}
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
|
// ❌ Hidden dependencies
|
||||||
|
import db from './database.js';
|
||||||
|
function createUser(userData) { return db.insert('users', userData); }
|
||||||
|
```
|
||||||
|
|
||||||
|
## Anti-Patterns
|
||||||
|
|
||||||
|
❌ **Mutation**: Modifying data in place
|
||||||
|
❌ **Side effects**: console.log, API calls in pure functions
|
||||||
|
❌ **Deep nesting**: Use early returns instead
|
||||||
|
❌ **God modules**: Split into focused modules
|
||||||
|
❌ **Global state**: Pass dependencies explicitly
|
||||||
|
❌ **Large functions**: Keep < 50 lines
|
||||||
|
|
||||||
|
## Best Practices
|
||||||
|
|
||||||
|
✅ Pure functions whenever possible
|
||||||
|
✅ Immutable data structures
|
||||||
|
✅ Small, focused functions (< 50 lines)
|
||||||
|
✅ Compose small functions into larger ones
|
||||||
|
✅ Explicit dependencies (dependency injection)
|
||||||
|
✅ Validate at boundaries
|
||||||
|
✅ Self-documenting code
|
||||||
|
✅ Test in isolation
|
||||||
|
|
||||||
|
**Golden Rule**: If you can't easily test it, refactor it.
|
||||||
148
.opencode/context/core/standards/docs.md
Normal file
148
.opencode/context/core/standards/docs.md
Normal file
|
|
@ -0,0 +1,148 @@
|
||||||
|
# Documentation Standards
|
||||||
|
|
||||||
|
## Quick Reference
|
||||||
|
|
||||||
|
**Golden Rule**: If users ask the same question twice, document it
|
||||||
|
|
||||||
|
**Document** (✅ DO):
|
||||||
|
- WHY decisions were made
|
||||||
|
- Complex algorithms/logic
|
||||||
|
- Public APIs, setup, common use cases
|
||||||
|
|
||||||
|
**Don't Document** (❌ DON'T):
|
||||||
|
- Obvious code (i++ doesn't need comment)
|
||||||
|
- What code does (should be self-explanatory)
|
||||||
|
|
||||||
|
**Principles**: Audience-focused, Show don't tell, Keep current
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Principles
|
||||||
|
|
||||||
|
**Audience-focused**: Write for users (what/how), developers (why/when), contributors (setup/conventions)
|
||||||
|
**Show, don't tell**: Code examples, real use cases, expected output
|
||||||
|
**Keep current**: Update with code changes, remove outdated info, mark deprecations
|
||||||
|
|
||||||
|
## README Structure
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# Project Name
|
||||||
|
Brief description (1-2 sentences)
|
||||||
|
|
||||||
|
## Features
|
||||||
|
- Key feature 1
|
||||||
|
- Key feature 2
|
||||||
|
|
||||||
|
## Installation
|
||||||
|
```bash
|
||||||
|
npm install package-name
|
||||||
|
```
|
||||||
|
|
||||||
|
## Quick Start
|
||||||
|
```javascript
|
||||||
|
const result = doSomething();
|
||||||
|
```
|
||||||
|
|
||||||
|
## Usage
|
||||||
|
[Detailed examples]
|
||||||
|
|
||||||
|
## API Reference
|
||||||
|
[If applicable]
|
||||||
|
|
||||||
|
## Contributing
|
||||||
|
[Link to CONTRIBUTING.md]
|
||||||
|
|
||||||
|
## License
|
||||||
|
[License type]
|
||||||
|
```
|
||||||
|
|
||||||
|
## Function Documentation
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
/**
|
||||||
|
* Calculate total price including tax
|
||||||
|
*
|
||||||
|
* @param {number} price - Base price
|
||||||
|
* @param {number} taxRate - Tax rate (0-1)
|
||||||
|
* @returns {number} Total with tax
|
||||||
|
*
|
||||||
|
* @example
|
||||||
|
* calculateTotal(100, 0.1) // 110
|
||||||
|
*/
|
||||||
|
function calculateTotal(price, taxRate) {
|
||||||
|
return price * (1 + taxRate);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## What to Document
|
||||||
|
|
||||||
|
### ✅ DO
|
||||||
|
- **WHY** decisions were made
|
||||||
|
- Complex algorithms/logic
|
||||||
|
- Non-obvious behavior
|
||||||
|
- Public APIs
|
||||||
|
- Setup/installation
|
||||||
|
- Common use cases
|
||||||
|
- Known limitations
|
||||||
|
- Workarounds (with explanation)
|
||||||
|
|
||||||
|
### ❌ DON'T
|
||||||
|
- Obvious code (i++ doesn't need comment)
|
||||||
|
- What code does (should be self-explanatory)
|
||||||
|
- Redundant information
|
||||||
|
- Outdated/incorrect info
|
||||||
|
|
||||||
|
## Comments
|
||||||
|
|
||||||
|
### Good
|
||||||
|
```javascript
|
||||||
|
// Calculate discount by tier (Bronze: 5%, Silver: 10%, Gold: 15%)
|
||||||
|
const discount = getDiscountByTier(customer.tier);
|
||||||
|
|
||||||
|
// HACK: API returns null instead of [], normalize it
|
||||||
|
const items = response.items || [];
|
||||||
|
|
||||||
|
// TODO: Use async/await when Node 18+ is minimum
|
||||||
|
```
|
||||||
|
|
||||||
|
### Bad
|
||||||
|
```javascript
|
||||||
|
// Increment i
|
||||||
|
i++;
|
||||||
|
|
||||||
|
// Get user
|
||||||
|
const user = getUser();
|
||||||
|
```
|
||||||
|
|
||||||
|
## API Documentation
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
### POST /api/users
|
||||||
|
Create a new user
|
||||||
|
|
||||||
|
**Request:**
|
||||||
|
```json
|
||||||
|
{ "name": "John", "email": "john@example.com" }
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response:**
|
||||||
|
```json
|
||||||
|
{ "id": "123", "name": "John", "email": "john@example.com" }
|
||||||
|
```
|
||||||
|
|
||||||
|
**Errors:**
|
||||||
|
- 400 - Invalid input
|
||||||
|
- 409 - Email exists
|
||||||
|
```
|
||||||
|
|
||||||
|
## Best Practices
|
||||||
|
|
||||||
|
✅ Explain WHY, not just WHAT
|
||||||
|
✅ Include working examples
|
||||||
|
✅ Show expected output
|
||||||
|
✅ Cover error handling
|
||||||
|
✅ Use consistent terminology
|
||||||
|
✅ Keep structure predictable
|
||||||
|
✅ Update when code changes
|
||||||
|
|
||||||
|
**Golden Rule**: If users ask the same question twice, document it.
|
||||||
|
|
@ -1,5 +1,17 @@
|
||||||
# Essential Patterns - Core Knowledge Base
|
# 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.
|
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
|
## Error Handling Pattern
|
||||||
125
.opencode/context/core/standards/tests.md
Normal file
125
.opencode/context/core/standards/tests.md
Normal file
|
|
@ -0,0 +1,125 @@
|
||||||
|
# Testing Standards
|
||||||
|
|
||||||
|
## Quick Reference
|
||||||
|
|
||||||
|
**Golden Rule**: If you can't test it easily, refactor it
|
||||||
|
|
||||||
|
**AAA Pattern**: Arrange → Act → Assert
|
||||||
|
|
||||||
|
**Test** (✅ DO):
|
||||||
|
- Happy path, edge cases, error cases
|
||||||
|
- Business logic, public APIs
|
||||||
|
|
||||||
|
**Don't Test** (❌ DON'T):
|
||||||
|
- Third-party libraries, framework internals
|
||||||
|
- Simple getters/setters, private details
|
||||||
|
|
||||||
|
**Coverage**: Critical (100%), High (90%+), Medium (80%+)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Principles
|
||||||
|
|
||||||
|
**Test behavior, not implementation**: Focus on what code does, not how
|
||||||
|
**Keep tests simple**: One assertion per test, clear names, minimal setup
|
||||||
|
**Independent tests**: No shared state, run in any order
|
||||||
|
**Fast and reliable**: Quick execution, no flaky tests, deterministic
|
||||||
|
|
||||||
|
## Test Structure (AAA Pattern)
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
test('calculateTotal returns sum of item prices', () => {
|
||||||
|
// Arrange - Set up test data
|
||||||
|
const items = [{ price: 10 }, { price: 20 }, { price: 30 }];
|
||||||
|
|
||||||
|
// Act - Execute code
|
||||||
|
const result = calculateTotal(items);
|
||||||
|
|
||||||
|
// Assert - Verify result
|
||||||
|
expect(result).toBe(60);
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
## What to Test
|
||||||
|
|
||||||
|
### ✅ DO Test
|
||||||
|
- Happy path (normal usage)
|
||||||
|
- Edge cases (boundaries, empty, null, undefined)
|
||||||
|
- Error cases (invalid input, failures)
|
||||||
|
- Business logic (core functionality)
|
||||||
|
- Public APIs (exported functions)
|
||||||
|
|
||||||
|
### ❌ DON'T Test
|
||||||
|
- Third-party libraries
|
||||||
|
- Framework internals
|
||||||
|
- Simple getters/setters
|
||||||
|
- Private implementation details
|
||||||
|
|
||||||
|
## Coverage Goals
|
||||||
|
|
||||||
|
1. **Critical**: Business logic, data transformations (100%)
|
||||||
|
2. **High**: Public APIs, user-facing features (90%+)
|
||||||
|
3. **Medium**: Utilities, helpers (80%+)
|
||||||
|
4. **Low**: Simple wrappers, configs (optional)
|
||||||
|
|
||||||
|
## Testing Pure Functions
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
function add(a, b) { return a + b; }
|
||||||
|
|
||||||
|
test('add returns sum', () => {
|
||||||
|
expect(add(2, 3)).toBe(5);
|
||||||
|
expect(add(-1, 1)).toBe(0);
|
||||||
|
expect(add(0, 0)).toBe(0);
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
## Testing with Dependencies
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
// Testable with dependency injection
|
||||||
|
function createUserService(database) {
|
||||||
|
return {
|
||||||
|
getUser: (id) => database.findById('users', id)
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
|
// Test with mock
|
||||||
|
test('getUser retrieves from database', () => {
|
||||||
|
const mockDb = {
|
||||||
|
findById: jest.fn().mockReturnValue({ id: 1, name: 'John' })
|
||||||
|
};
|
||||||
|
|
||||||
|
const service = createUserService(mockDb);
|
||||||
|
const user = service.getUser(1);
|
||||||
|
|
||||||
|
expect(mockDb.findById).toHaveBeenCalledWith('users', 1);
|
||||||
|
expect(user).toEqual({ id: 1, name: 'John' });
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
## Test Naming
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
// ✅ Good: Descriptive, clear expectation
|
||||||
|
test('calculateDiscount returns 10% off for premium users', () => {});
|
||||||
|
test('validateEmail returns false for invalid format', () => {});
|
||||||
|
test('createUser throws error when email exists', () => {});
|
||||||
|
|
||||||
|
// ❌ Bad: Vague, unclear
|
||||||
|
test('it works', () => {});
|
||||||
|
test('test user', () => {});
|
||||||
|
```
|
||||||
|
|
||||||
|
## Best Practices
|
||||||
|
|
||||||
|
✅ Test one thing per test
|
||||||
|
✅ Use descriptive test names
|
||||||
|
✅ Keep tests independent
|
||||||
|
✅ Mock external dependencies
|
||||||
|
✅ Test edge cases and errors
|
||||||
|
✅ Make tests readable
|
||||||
|
✅ Run tests frequently
|
||||||
|
✅ Fix failing tests immediately
|
||||||
|
|
||||||
|
**Golden Rule**: If you can't test it easily, refactor it.
|
||||||
171
.opencode/context/core/system/context-guide.md
Normal file
171
.opencode/context/core/system/context-guide.md
Normal file
|
|
@ -0,0 +1,171 @@
|
||||||
|
# Context System Guide
|
||||||
|
|
||||||
|
## Quick Reference
|
||||||
|
|
||||||
|
**Golden Rule**: Fetch context when needed, not before (lazy loading)
|
||||||
|
|
||||||
|
**Key Principle**: Reference files WITHOUT @ symbol - agent fetches only when needed
|
||||||
|
|
||||||
|
**Structure**: standards/ (quality + analysis), workflows/ (process + review), system/ (internals)
|
||||||
|
|
||||||
|
**Session Location**: `.tmp/sessions/{timestamp}-{task-slug}/context.md`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
Context files provide guidelines and templates for specific tasks. Use lazy loading (fetch when needed) to keep prompts lean.
|
||||||
|
|
||||||
|
## Available Context Files
|
||||||
|
|
||||||
|
All files are in `.opencode/context/core/` with organized subfolders:
|
||||||
|
|
||||||
|
### Standards (Quality Guidelines + Analysis)
|
||||||
|
- `.opencode/context/core/standards/code.md` - Modular, functional code principles
|
||||||
|
- `.opencode/context/core/standards/docs.md` - Documentation standards
|
||||||
|
- `.opencode/context/core/standards/tests.md` - Testing standards
|
||||||
|
- `.opencode/context/core/standards/patterns.md` - Core patterns (error handling, security)
|
||||||
|
- `.opencode/context/core/standards/analysis.md` - Analysis framework
|
||||||
|
|
||||||
|
### Workflows (Process Templates + Review)
|
||||||
|
- `.opencode/context/core/workflows/delegation.md` - Delegation template
|
||||||
|
- `.opencode/context/core/workflows/task-breakdown.md` - Complex task breakdown
|
||||||
|
- `.opencode/context/core/workflows/sessions.md` - Session lifecycle
|
||||||
|
- `.opencode/context/core/workflows/review.md` - Code review guidelines
|
||||||
|
|
||||||
|
## Lazy Loading (Recommended)
|
||||||
|
|
||||||
|
Reference files **WITHOUT** `@` symbol - agent fetches only when needed:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
"Write code following .opencode/context/core/standards/code.md"
|
||||||
|
"Review using .opencode/context/core/workflows/review.md"
|
||||||
|
"Break down task using .opencode/context/core/workflows/task-breakdown.md"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Benefits:**
|
||||||
|
- No prompt bloat
|
||||||
|
- Fetch only what's relevant
|
||||||
|
- Faster for simple tasks
|
||||||
|
- Agent decides when to load
|
||||||
|
|
||||||
|
## When to Use Each File
|
||||||
|
|
||||||
|
### .opencode/context/core/standards/code.md
|
||||||
|
- Writing new code
|
||||||
|
- Modifying existing code
|
||||||
|
- Following modular/functional patterns
|
||||||
|
- Making architectural decisions
|
||||||
|
|
||||||
|
### .opencode/context/core/standards/docs.md
|
||||||
|
- Writing README files
|
||||||
|
- Creating API documentation
|
||||||
|
- Adding code comments
|
||||||
|
|
||||||
|
### .opencode/context/core/standards/tests.md
|
||||||
|
- Writing new tests
|
||||||
|
- Running test suites
|
||||||
|
- Debugging test failures
|
||||||
|
|
||||||
|
### .opencode/context/core/standards/patterns.md
|
||||||
|
- Error handling
|
||||||
|
- Security patterns
|
||||||
|
- Common code patterns
|
||||||
|
|
||||||
|
### .opencode/context/core/standards/analysis.md
|
||||||
|
- Analyzing codebase patterns
|
||||||
|
- Investigating bugs
|
||||||
|
- Evaluating architecture
|
||||||
|
|
||||||
|
### .opencode/context/core/workflows/delegation.md
|
||||||
|
- Delegating to general agent
|
||||||
|
- Creating task context
|
||||||
|
- Multi-file coordination
|
||||||
|
|
||||||
|
### .opencode/context/core/workflows/task-breakdown.md
|
||||||
|
- Tasks with 4+ files
|
||||||
|
- Estimated effort >60 minutes
|
||||||
|
- Complex dependencies
|
||||||
|
|
||||||
|
### .opencode/context/core/workflows/sessions.md
|
||||||
|
- Session lifecycle
|
||||||
|
- Cleanup procedures
|
||||||
|
- Session isolation
|
||||||
|
|
||||||
|
### .opencode/context/core/workflows/review.md
|
||||||
|
- Reviewing code
|
||||||
|
- Conducting code audits
|
||||||
|
- Providing PR feedback
|
||||||
|
|
||||||
|
## Temporary Context (Session-Specific)
|
||||||
|
|
||||||
|
When delegating, create focused task context:
|
||||||
|
|
||||||
|
**Location**: `.tmp/sessions/{timestamp}-{task-slug}/context.md`
|
||||||
|
|
||||||
|
**Structure**:
|
||||||
|
```markdown
|
||||||
|
# Task Context: {Task Name}
|
||||||
|
|
||||||
|
Session ID: {id}
|
||||||
|
Created: {timestamp}
|
||||||
|
Status: in_progress
|
||||||
|
|
||||||
|
## Current Request
|
||||||
|
{What user asked for}
|
||||||
|
|
||||||
|
## Requirements
|
||||||
|
- {requirement 1}
|
||||||
|
- {requirement 2}
|
||||||
|
|
||||||
|
## Decisions Made
|
||||||
|
- {decision 1}
|
||||||
|
|
||||||
|
## Files to Modify/Create
|
||||||
|
- {file 1} - {purpose}
|
||||||
|
|
||||||
|
## Static Context Available
|
||||||
|
- .opencode/context/core/standards/code.md
|
||||||
|
- .opencode/context/core/standards/tests.md
|
||||||
|
|
||||||
|
## Constraints/Notes
|
||||||
|
{Important context}
|
||||||
|
|
||||||
|
## Progress
|
||||||
|
- [ ] {task 1}
|
||||||
|
- [ ] {task 2}
|
||||||
|
|
||||||
|
---
|
||||||
|
**Instructions for Subagent:**
|
||||||
|
{Specific instructions}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Session Management
|
||||||
|
|
||||||
|
### Session Structure
|
||||||
|
```
|
||||||
|
.tmp/sessions/{session-id}/
|
||||||
|
├── context.md # Task context
|
||||||
|
├── notes.md # Working notes
|
||||||
|
└── artifacts/ # Generated files
|
||||||
|
```
|
||||||
|
|
||||||
|
### Session ID Format
|
||||||
|
`{timestamp}-{random-4-chars}`
|
||||||
|
Example: `20250119-143022-a4f2`
|
||||||
|
|
||||||
|
### Cleanup
|
||||||
|
- Ask user before deleting session files
|
||||||
|
- Remove after task completion
|
||||||
|
- Keep if user wants to review
|
||||||
|
|
||||||
|
## Best Practices
|
||||||
|
|
||||||
|
✅ Use lazy loading (no @ symbol)
|
||||||
|
✅ Fetch only relevant context
|
||||||
|
✅ Create temp context when delegating
|
||||||
|
✅ Clean up sessions after completion
|
||||||
|
✅ Reference specific sections when possible
|
||||||
|
✅ Keep temp context focused and concise
|
||||||
|
|
||||||
|
**Golden Rule**: Fetch context when needed, not before.
|
||||||
81
.opencode/context/core/workflows/delegation.md
Normal file
81
.opencode/context/core/workflows/delegation.md
Normal file
|
|
@ -0,0 +1,81 @@
|
||||||
|
# Delegation Context Template
|
||||||
|
|
||||||
|
## Quick Reference
|
||||||
|
|
||||||
|
**Process**: Create context → Populate → Delegate → Cleanup
|
||||||
|
|
||||||
|
**Location**: `.tmp/sessions/{timestamp}-{task-slug}/context.md`
|
||||||
|
|
||||||
|
**Template Sections**: Request, Requirements, Decisions, Files, Static Context, Constraints, Progress, Instructions
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
Use this template when creating temporary context files for task delegation.
|
||||||
|
|
||||||
|
## Template Structure
|
||||||
|
|
||||||
|
**Location**: `.tmp/sessions/{timestamp}-{task-slug}/context.md`
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# Task Context: {Task Name}
|
||||||
|
|
||||||
|
Session ID: {id}
|
||||||
|
Created: {timestamp}
|
||||||
|
Status: in_progress
|
||||||
|
|
||||||
|
## Current Request
|
||||||
|
{What user asked for}
|
||||||
|
|
||||||
|
## Requirements
|
||||||
|
- {requirement 1}
|
||||||
|
- {requirement 2}
|
||||||
|
|
||||||
|
## Decisions Made
|
||||||
|
- {decision 1 - approach/constraints}
|
||||||
|
- {decision 2}
|
||||||
|
|
||||||
|
## Files to Modify/Create
|
||||||
|
- {file 1} - {purpose}
|
||||||
|
- {file 2} - {purpose}
|
||||||
|
- {file 3} - {purpose}
|
||||||
|
- {file 4} - {purpose}
|
||||||
|
|
||||||
|
## Static Context Available
|
||||||
|
- .opencode/context/core/standards/code.md (for code quality)
|
||||||
|
- .opencode/context/core/standards/tests.md (for test requirements)
|
||||||
|
- .opencode/context/core/{standards|workflows}/{other-relevant}.md
|
||||||
|
|
||||||
|
## Constraints/Notes
|
||||||
|
{Important context, preferences, compatibility}
|
||||||
|
|
||||||
|
## Progress
|
||||||
|
- [ ] {task 1}
|
||||||
|
- [ ] {task 2}
|
||||||
|
|
||||||
|
---
|
||||||
|
**Instructions for Subagent:**
|
||||||
|
{Specific instructions on what to do}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Delegation Process
|
||||||
|
|
||||||
|
**Step 1: Create temporary context**
|
||||||
|
- Location: `.tmp/sessions/{timestamp}-{task-slug}/context.md`
|
||||||
|
- Use template above
|
||||||
|
|
||||||
|
**Step 2: Populate context file**
|
||||||
|
- Fill in all sections with relevant details
|
||||||
|
- Reference static context files (don't duplicate content)
|
||||||
|
|
||||||
|
**Step 3: Delegate with context path**
|
||||||
|
```
|
||||||
|
Task: {brief description}
|
||||||
|
Context: .tmp/sessions/{id}/context.md
|
||||||
|
|
||||||
|
Read the context file for full details on requirements, decisions, and instructions.
|
||||||
|
Reference static context files as needed (lazy load).
|
||||||
|
```
|
||||||
|
|
||||||
|
**Step 4: Cleanup after completion**
|
||||||
|
- Ask user: "Task complete. Clean up session files at .tmp/sessions/{id}/?"
|
||||||
|
- If approved: Delete session directory
|
||||||
134
.opencode/context/core/workflows/review.md
Normal file
134
.opencode/context/core/workflows/review.md
Normal file
|
|
@ -0,0 +1,134 @@
|
||||||
|
# Code Review Guidelines
|
||||||
|
|
||||||
|
## Quick Reference
|
||||||
|
|
||||||
|
**Golden Rule**: Review code as you'd want yours reviewed - thoroughly but kindly
|
||||||
|
|
||||||
|
**Checklist**: Functionality, Code Quality, Security, Testing, Performance, Maintainability
|
||||||
|
|
||||||
|
**Report Format**: Summary, Assessment, Issues (🔴🟡🔵), Positive Observations, Recommendations
|
||||||
|
|
||||||
|
**Principles**: Constructive, Thorough, Timely
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Principles
|
||||||
|
|
||||||
|
**Constructive**: Focus on code not person, explain WHY, suggest improvements, acknowledge good practices
|
||||||
|
**Thorough**: Check functionality not just style, consider edge cases, think maintainability, look for security
|
||||||
|
**Timely**: Review promptly, don't block unnecessarily, prioritize critical issues
|
||||||
|
|
||||||
|
## Review Checklist
|
||||||
|
|
||||||
|
### Functionality
|
||||||
|
- [ ] Does what it's supposed to do
|
||||||
|
- [ ] Edge cases handled
|
||||||
|
- [ ] Error cases handled
|
||||||
|
- [ ] No obvious bugs
|
||||||
|
|
||||||
|
### Code Quality
|
||||||
|
- [ ] Clear, descriptive naming
|
||||||
|
- [ ] Functions small and focused
|
||||||
|
- [ ] No unnecessary complexity
|
||||||
|
- [ ] Follows coding standards
|
||||||
|
- [ ] DRY - no duplication
|
||||||
|
|
||||||
|
### Security
|
||||||
|
- [ ] Input validation present
|
||||||
|
- [ ] No SQL injection vulnerabilities
|
||||||
|
- [ ] No XSS vulnerabilities
|
||||||
|
- [ ] No hardcoded secrets
|
||||||
|
- [ ] Sensitive data handled properly
|
||||||
|
- [ ] Auth/authorization appropriate
|
||||||
|
|
||||||
|
### Testing
|
||||||
|
- [ ] Tests present
|
||||||
|
- [ ] Happy path covered
|
||||||
|
- [ ] Edge cases covered
|
||||||
|
- [ ] Error cases covered
|
||||||
|
- [ ] All tests pass
|
||||||
|
|
||||||
|
### Performance
|
||||||
|
- [ ] No obvious performance issues
|
||||||
|
- [ ] Efficient algorithms
|
||||||
|
- [ ] No unnecessary operations
|
||||||
|
- [ ] Resources properly managed
|
||||||
|
|
||||||
|
### Maintainability
|
||||||
|
- [ ] Easy to understand
|
||||||
|
- [ ] Complex logic documented
|
||||||
|
- [ ] Follows project conventions
|
||||||
|
- [ ] Easy to modify/extend
|
||||||
|
|
||||||
|
## Review Report Format
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
## Code Review: {Feature/PR Name}
|
||||||
|
|
||||||
|
**Summary:** {Brief overview}
|
||||||
|
**Assessment:** Approve / Needs Work / Requires Changes
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Issues Found
|
||||||
|
|
||||||
|
#### 🔴 Critical (Must Fix)
|
||||||
|
- **File:** `src/auth.js:42`
|
||||||
|
**Issue:** Password stored in plain text
|
||||||
|
**Fix:** Hash password before storing
|
||||||
|
|
||||||
|
#### 🟡 Warnings (Should Fix)
|
||||||
|
- **File:** `src/user.js:15`
|
||||||
|
**Issue:** No input validation
|
||||||
|
**Fix:** Validate email format
|
||||||
|
|
||||||
|
#### 🔵 Suggestions (Nice to Have)
|
||||||
|
- **File:** `src/utils.js:28`
|
||||||
|
**Issue:** Could be more concise
|
||||||
|
**Fix:** Use array methods instead of loop
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Positive Observations
|
||||||
|
- ✅ Good test coverage (95%)
|
||||||
|
- ✅ Clear function names
|
||||||
|
- ✅ Proper error handling
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Recommendations
|
||||||
|
{Next steps, improvements, follow-up items}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Common Issues
|
||||||
|
|
||||||
|
### Security
|
||||||
|
🔴 Hardcoded credentials
|
||||||
|
🔴 SQL injection vulnerabilities
|
||||||
|
🔴 Missing input validation
|
||||||
|
🔴 Exposed sensitive data
|
||||||
|
|
||||||
|
### Code Quality
|
||||||
|
🟡 Large functions (>50 lines)
|
||||||
|
🟡 Deep nesting (>3 levels)
|
||||||
|
🟡 Code duplication
|
||||||
|
🟡 Unclear naming
|
||||||
|
|
||||||
|
### Testing
|
||||||
|
🟡 Missing tests
|
||||||
|
🟡 Low coverage (<80%)
|
||||||
|
🟡 Flaky tests
|
||||||
|
🟡 Tests testing implementation
|
||||||
|
|
||||||
|
## Best Practices
|
||||||
|
|
||||||
|
✅ Review within 24 hours
|
||||||
|
✅ Provide specific, actionable feedback
|
||||||
|
✅ Explain WHY, not just WHAT
|
||||||
|
✅ Suggest alternatives
|
||||||
|
✅ Acknowledge good work
|
||||||
|
✅ Use severity levels (Critical/Warning/Suggestion)
|
||||||
|
✅ Test the code if possible
|
||||||
|
✅ Check for security issues first
|
||||||
|
|
||||||
|
**Golden Rule**: Review code as you'd want yours reviewed - thoroughly but kindly.
|
||||||
|
|
@ -1,5 +1,17 @@
|
||||||
# Session Management
|
# 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
|
## Lazy Initialization
|
||||||
|
|
||||||
**Only create session when first context file needed**
|
**Only create session when first context file needed**
|
||||||
268
.opencode/context/core/workflows/task-breakdown.md
Normal file
268
.opencode/context/core/workflows/task-breakdown.md
Normal file
|
|
@ -0,0 +1,268 @@
|
||||||
|
# Task Breakdown Guidelines
|
||||||
|
|
||||||
|
## Quick Reference
|
||||||
|
|
||||||
|
**When to Use**: 4+ files, >60 min effort, complex dependencies, multi-step coordination
|
||||||
|
|
||||||
|
**Process**: Scope → Phases → Small Tasks (1-2h) → Dependencies → Estimates
|
||||||
|
|
||||||
|
**Template Sections**: Overview, Prerequisites, Tasks (by Phase), Testing Strategy, Total Estimate, Notes
|
||||||
|
|
||||||
|
**Best Practices**: Keep tasks small (1-2h), make dependencies clear, include verification, be realistic with estimates
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Purpose
|
||||||
|
Framework for breaking down complex tasks into manageable, sequential subtasks.
|
||||||
|
|
||||||
|
## When to Use
|
||||||
|
Reference this when:
|
||||||
|
- Task involves 4+ files
|
||||||
|
- Estimated effort >60 minutes
|
||||||
|
- Complex dependencies exist
|
||||||
|
- Multi-step coordination needed
|
||||||
|
- User requests task breakdown
|
||||||
|
|
||||||
|
## Breakdown Process
|
||||||
|
|
||||||
|
### 1. Understand the Full Scope
|
||||||
|
- What's the complete requirement?
|
||||||
|
- What are all the components needed?
|
||||||
|
- What's the end goal?
|
||||||
|
- What are the constraints?
|
||||||
|
|
||||||
|
### 2. Identify Major Phases
|
||||||
|
- What are the logical groupings?
|
||||||
|
- What must happen first?
|
||||||
|
- What can happen in parallel?
|
||||||
|
- What depends on what?
|
||||||
|
|
||||||
|
### 3. Break Into Small Tasks
|
||||||
|
- Each task should be 1-2 hours max
|
||||||
|
- Clear, actionable items
|
||||||
|
- Independently completable
|
||||||
|
- Easy to verify completion
|
||||||
|
|
||||||
|
### 4. Define Dependencies
|
||||||
|
- What must be done first?
|
||||||
|
- What can be done in parallel?
|
||||||
|
- What blocks what?
|
||||||
|
- What's the critical path?
|
||||||
|
|
||||||
|
### 5. Estimate Effort
|
||||||
|
- Realistic time estimates
|
||||||
|
- Include testing time
|
||||||
|
- Account for unknowns
|
||||||
|
- Add buffer for complexity
|
||||||
|
|
||||||
|
## Breakdown Template
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# Task Breakdown: {Task Name}
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
{1-2 sentence description of what we're building}
|
||||||
|
|
||||||
|
## Prerequisites
|
||||||
|
- [ ] {Prerequisite 1}
|
||||||
|
- [ ] {Prerequisite 2}
|
||||||
|
|
||||||
|
## Tasks
|
||||||
|
|
||||||
|
### Phase 1: {Phase Name}
|
||||||
|
**Goal:** {What this phase accomplishes}
|
||||||
|
|
||||||
|
- [ ] **Task 1.1:** {Description}
|
||||||
|
- **Files:** {files to create/modify}
|
||||||
|
- **Estimate:** {time estimate}
|
||||||
|
- **Dependencies:** {none / task X}
|
||||||
|
- **Verification:** {how to verify it's done}
|
||||||
|
|
||||||
|
- [ ] **Task 1.2:** {Description}
|
||||||
|
- **Files:** {files to create/modify}
|
||||||
|
- **Estimate:** {time estimate}
|
||||||
|
- **Dependencies:** {task 1.1}
|
||||||
|
- **Verification:** {how to verify it's done}
|
||||||
|
|
||||||
|
### Phase 2: {Phase Name}
|
||||||
|
**Goal:** {What this phase accomplishes}
|
||||||
|
|
||||||
|
- [ ] **Task 2.1:** {Description}
|
||||||
|
- **Files:** {files to create/modify}
|
||||||
|
- **Estimate:** {time estimate}
|
||||||
|
- **Dependencies:** {phase 1 complete}
|
||||||
|
- **Verification:** {how to verify it's done}
|
||||||
|
|
||||||
|
## Testing Strategy
|
||||||
|
- [ ] Unit tests for {component}
|
||||||
|
- [ ] Integration tests for {flow}
|
||||||
|
- [ ] Manual testing: {scenarios}
|
||||||
|
|
||||||
|
## Total Estimate
|
||||||
|
**Time:** {X} hours
|
||||||
|
**Complexity:** {Low / Medium / High}
|
||||||
|
|
||||||
|
## Notes
|
||||||
|
{Any important context, decisions, or considerations}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Example Breakdown
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# Task Breakdown: User Authentication System
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
Build authentication system with login, registration, and password reset.
|
||||||
|
|
||||||
|
## Prerequisites
|
||||||
|
- [ ] Database schema designed
|
||||||
|
- [ ] Email service configured
|
||||||
|
|
||||||
|
## Tasks
|
||||||
|
|
||||||
|
### Phase 1: Core Authentication
|
||||||
|
**Goal:** Basic login/logout functionality
|
||||||
|
|
||||||
|
- [ ] **Task 1.1:** Create user model and database schema
|
||||||
|
- **Files:** `models/user.js`, `migrations/001_users.sql`
|
||||||
|
- **Estimate:** 1 hour
|
||||||
|
- **Dependencies:** none
|
||||||
|
- **Verification:** Can create user in database
|
||||||
|
|
||||||
|
- [ ] **Task 1.2:** Implement password hashing
|
||||||
|
- **Files:** `utils/password.js`
|
||||||
|
- **Estimate:** 30 min
|
||||||
|
- **Dependencies:** Task 1.1
|
||||||
|
- **Verification:** Passwords are hashed, not plain text
|
||||||
|
|
||||||
|
- [ ] **Task 1.3:** Create login endpoint
|
||||||
|
- **Files:** `routes/auth.js`, `controllers/auth.js`
|
||||||
|
- **Estimate:** 1.5 hours
|
||||||
|
- **Dependencies:** Task 1.1, 1.2
|
||||||
|
- **Verification:** Can login with valid credentials
|
||||||
|
|
||||||
|
### Phase 2: Registration
|
||||||
|
**Goal:** New user registration
|
||||||
|
|
||||||
|
- [ ] **Task 2.1:** Create registration endpoint
|
||||||
|
- **Files:** `routes/auth.js`, `controllers/auth.js`
|
||||||
|
- **Estimate:** 1 hour
|
||||||
|
- **Dependencies:** Phase 1 complete
|
||||||
|
- **Verification:** Can create new user account
|
||||||
|
|
||||||
|
- [ ] **Task 2.2:** Add email validation
|
||||||
|
- **Files:** `utils/validation.js`
|
||||||
|
- **Estimate:** 30 min
|
||||||
|
- **Dependencies:** Task 2.1
|
||||||
|
- **Verification:** Invalid emails rejected
|
||||||
|
|
||||||
|
### Phase 3: Password Reset
|
||||||
|
**Goal:** Users can reset forgotten passwords
|
||||||
|
|
||||||
|
- [ ] **Task 3.1:** Generate reset tokens
|
||||||
|
- **Files:** `utils/tokens.js`
|
||||||
|
- **Estimate:** 1 hour
|
||||||
|
- **Dependencies:** Phase 1 complete
|
||||||
|
- **Verification:** Tokens generated and validated
|
||||||
|
|
||||||
|
- [ ] **Task 3.2:** Create reset endpoints
|
||||||
|
- **Files:** `routes/auth.js`, `controllers/auth.js`
|
||||||
|
- **Estimate:** 1.5 hours
|
||||||
|
- **Dependencies:** Task 3.1
|
||||||
|
- **Verification:** Can request and complete password reset
|
||||||
|
|
||||||
|
- [ ] **Task 3.3:** Send reset emails
|
||||||
|
- **Files:** `services/email.js`
|
||||||
|
- **Estimate:** 1 hour
|
||||||
|
- **Dependencies:** Task 3.2
|
||||||
|
- **Verification:** Reset emails sent successfully
|
||||||
|
|
||||||
|
## Testing Strategy
|
||||||
|
- [ ] Unit tests for password hashing
|
||||||
|
- [ ] Unit tests for token generation
|
||||||
|
- [ ] Integration tests for login flow
|
||||||
|
- [ ] Integration tests for registration flow
|
||||||
|
- [ ] Integration tests for password reset flow
|
||||||
|
- [ ] Manual testing: Complete user journey
|
||||||
|
|
||||||
|
## Total Estimate
|
||||||
|
**Time:** 8.5 hours
|
||||||
|
**Complexity:** Medium
|
||||||
|
|
||||||
|
## Notes
|
||||||
|
- Use bcrypt for password hashing (industry standard)
|
||||||
|
- Reset tokens expire after 1 hour
|
||||||
|
- Rate limit password reset requests
|
||||||
|
- Email service must be configured before Phase 3
|
||||||
|
```
|
||||||
|
|
||||||
|
## Best Practices
|
||||||
|
|
||||||
|
### Keep Tasks Small
|
||||||
|
- 1-2 hours maximum per task
|
||||||
|
- If larger, break it down further
|
||||||
|
- Each task should be completable in one sitting
|
||||||
|
|
||||||
|
### Make Dependencies Clear
|
||||||
|
- Explicitly state what must be done first
|
||||||
|
- Identify parallel work opportunities
|
||||||
|
- Note blocking dependencies
|
||||||
|
|
||||||
|
### Include Verification
|
||||||
|
- How do you know the task is done?
|
||||||
|
- What should work when complete?
|
||||||
|
- How can it be tested?
|
||||||
|
|
||||||
|
### Be Realistic with Estimates
|
||||||
|
- Include time for testing
|
||||||
|
- Account for unknowns
|
||||||
|
- Add buffer for complexity
|
||||||
|
- Better to overestimate than underestimate
|
||||||
|
|
||||||
|
### Group Related Work
|
||||||
|
- Organize by feature or component
|
||||||
|
- Keep related tasks together
|
||||||
|
- Make phases logical and cohesive
|
||||||
|
|
||||||
|
## Common Patterns
|
||||||
|
|
||||||
|
### Database-First Pattern
|
||||||
|
1. Design schema
|
||||||
|
2. Create migrations
|
||||||
|
3. Build models
|
||||||
|
4. Implement business logic
|
||||||
|
5. Add API endpoints
|
||||||
|
6. Write tests
|
||||||
|
|
||||||
|
### Feature-First Pattern
|
||||||
|
1. Define requirements
|
||||||
|
2. Design interface
|
||||||
|
3. Implement core logic
|
||||||
|
4. Add error handling
|
||||||
|
5. Write tests
|
||||||
|
6. Document usage
|
||||||
|
|
||||||
|
### Refactoring Pattern
|
||||||
|
1. Add tests for existing behavior
|
||||||
|
2. Refactor small section
|
||||||
|
3. Verify tests still pass
|
||||||
|
4. Repeat for next section
|
||||||
|
5. Clean up and optimize
|
||||||
|
6. Update documentation
|
||||||
|
|
||||||
|
## Quick Reference
|
||||||
|
|
||||||
|
**Good breakdown:**
|
||||||
|
- Small, focused tasks (1-2 hours)
|
||||||
|
- Clear dependencies
|
||||||
|
- Realistic estimates
|
||||||
|
- Verification criteria
|
||||||
|
- Logical phases
|
||||||
|
|
||||||
|
**Breakdown checklist:**
|
||||||
|
- [ ] All requirements captured
|
||||||
|
- [ ] Tasks are small and focused
|
||||||
|
- [ ] Dependencies identified
|
||||||
|
- [ ] Estimates are realistic
|
||||||
|
- [ ] Testing included
|
||||||
|
- [ ] Verification criteria clear
|
||||||
1273
dev/ai-tools/opencode/building-plugins.md
Normal file
1273
dev/ai-tools/opencode/building-plugins.md
Normal file
File diff suppressed because it is too large
Load diff
|
|
@ -59,6 +59,20 @@ your-repo/
|
||||||
|
|
||||||
## File References with `@` Symbol
|
## File References with `@` Symbol
|
||||||
|
|
||||||
|
### Immediate vs. Lazy Loading
|
||||||
|
|
||||||
|
**With `@` symbol** - **Immediate Loading**:
|
||||||
|
- File is fetched and loaded right away
|
||||||
|
- Content is immediately available to the agent
|
||||||
|
- Use when context is always needed
|
||||||
|
|
||||||
|
**Without `@` symbol** - **Lazy Loading**:
|
||||||
|
- File is only fetched when the agent determines it's needed
|
||||||
|
- Saves tokens if the agent can complete the task without it
|
||||||
|
- Agent discovers and loads the file on-demand
|
||||||
|
|
||||||
|
### Using the `@` Symbol
|
||||||
|
|
||||||
**In commands and templates:**
|
**In commands and templates:**
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
|
|
@ -82,6 +96,283 @@ your-repo/
|
||||||
3. Otherwise → resolve relative to repo root (`Instance.worktree`)
|
3. Otherwise → resolve relative to repo root (`Instance.worktree`)
|
||||||
4. If not found → look for agent with that name
|
4. If not found → look for agent with that name
|
||||||
|
|
||||||
|
### Best Practices for Lazy Loading (Without `@`)
|
||||||
|
|
||||||
|
When referencing files without the `@` symbol, help the agent discover them by:
|
||||||
|
|
||||||
|
**1. Provide clear file paths**
|
||||||
|
```
|
||||||
|
"Use the context from .opencode/command/commit.md if needed"
|
||||||
|
```
|
||||||
|
|
||||||
|
**2. Describe what's there** (so agent knows when to fetch)
|
||||||
|
```
|
||||||
|
"Check the commit command guidelines in .opencode/command/commit.md
|
||||||
|
when you need to understand our commit message format"
|
||||||
|
```
|
||||||
|
|
||||||
|
**3. Mention directory conventions**
|
||||||
|
```
|
||||||
|
"Command templates are in .opencode/command/ - reference them as needed"
|
||||||
|
```
|
||||||
|
|
||||||
|
**4. Reference by purpose, not just path**
|
||||||
|
```
|
||||||
|
"Follow our commit guidelines (available in the command directory)
|
||||||
|
when making commits"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Example: Lazy Loading in Practice
|
||||||
|
|
||||||
|
**Without `@` symbol (lazy loading):**
|
||||||
|
```
|
||||||
|
"Create a git commit. Our commit guidelines are in .opencode/command/commit.md -
|
||||||
|
check them if you need to understand our prefix conventions and message format."
|
||||||
|
```
|
||||||
|
|
||||||
|
This approach:
|
||||||
|
- ✅ Agent knows the file exists and where it is
|
||||||
|
- ✅ Agent knows WHEN it would be useful (for commit conventions)
|
||||||
|
- ✅ Agent only reads it IF it needs that information
|
||||||
|
- ✅ Saves tokens if the agent can complete the task without it
|
||||||
|
|
||||||
|
**With `@` symbol (immediate loading):**
|
||||||
|
```
|
||||||
|
"Create a git commit following these guidelines: @.opencode/command/commit.md"
|
||||||
|
```
|
||||||
|
|
||||||
|
This approach:
|
||||||
|
- ✅ File content is immediately available
|
||||||
|
- ✅ Guaranteed the agent has the context
|
||||||
|
- ⚠️ Uses tokens even if agent doesn't need it
|
||||||
|
|
||||||
|
### When to Use Each Approach
|
||||||
|
|
||||||
|
| Use `@` (Immediate) | Omit `@` (Lazy) |
|
||||||
|
|---------------------|-----------------|
|
||||||
|
| Context always required | Context might be needed |
|
||||||
|
| Short, critical files | Large reference files |
|
||||||
|
| Agent must follow exact format | Agent can infer or discover |
|
||||||
|
| Templates and schemas | Documentation and guides |
|
||||||
|
|
||||||
|
**Pro tip:** Modern agents are good at discovering needed files through `codebase_search` or exploring directories, but being explicit about important files helps ensure consistency.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Research-Backed Context Architecture
|
||||||
|
|
||||||
|
### Three-Layer Progressive Architecture
|
||||||
|
|
||||||
|
Based on validated research from Stanford, Anthropic (2025), and recent AI agent engineering studies, effective context loading follows a three-layer progressive architecture:
|
||||||
|
|
||||||
|
#### Layer 1: Static Base Context (First 15% of Prompt)
|
||||||
|
|
||||||
|
This is your foundational layer, grounded in Stanford's position sensitivity research. **Critical instructions positioned early dramatically improve adherence.**
|
||||||
|
|
||||||
|
**What goes here:**
|
||||||
|
- Role definition (5-10%)
|
||||||
|
- Critical rules (defined once, early positioning)
|
||||||
|
- Task definition (clear objective)
|
||||||
|
- Constraint summary (high-level "must/must-not")
|
||||||
|
|
||||||
|
**Example:**
|
||||||
|
```xml
|
||||||
|
<role>Expert Prompt Architect</role>
|
||||||
|
<critical_rules priority="absolute" enforcement="strict">
|
||||||
|
<rule id="position_sensitivity">Critical rules MUST be in first 15%</rule>
|
||||||
|
<rule id="nesting_limit">Max nesting: 4 levels</rule>
|
||||||
|
</critical_rules>
|
||||||
|
<execution_priority>
|
||||||
|
<tier level="1">Research patterns (non-negotiable)</tier>
|
||||||
|
</execution_priority>
|
||||||
|
```
|
||||||
|
|
||||||
|
**Why this matters:** Research shows position sensitivity improves adherence across model sizes. Critical rules at the start are more reliably followed than rules buried later in the prompt.
|
||||||
|
|
||||||
|
#### Layer 2: Lazy-Loaded Context (Just-in-Time Retrieval)
|
||||||
|
|
||||||
|
This layer uses the "just-in-time" approach validated by Anthropic's 2025 research on effective context engineering for AI agents.
|
||||||
|
|
||||||
|
> Rather than pre-processing all relevant data up front, agents built with the "just-in-time" approach maintain lightweight identifiers (file paths, stored queries, web links, etc.) and use these references to dynamically load data into context at runtime using tools.
|
||||||
|
|
||||||
|
**Implementation:**
|
||||||
|
```xml
|
||||||
|
<context_sources>
|
||||||
|
<!-- Agent fetches these as needed, not embedded upfront -->
|
||||||
|
<standards>.opencode/context/core/standards/code.md</standards>
|
||||||
|
<practices>.opencode/context/core/practices/review.md</practices>
|
||||||
|
<workflows>.opencode/context/core/workflows/delegation.md</workflows>
|
||||||
|
</context_sources>
|
||||||
|
```
|
||||||
|
|
||||||
|
**Key insight:** This enables **progressive disclosure**. Agents incrementally discover context through exploration:
|
||||||
|
- File naming hints at purpose (`.../standards/code.md` vs `.../practices/review.md`)
|
||||||
|
- File size signals complexity
|
||||||
|
- Timestamps indicate recency
|
||||||
|
- Folder structure provides hierarchical context
|
||||||
|
|
||||||
|
**Token efficiency gain:**
|
||||||
|
- Pre-loading all context: **2,000-5,000+ tokens**
|
||||||
|
- Just-in-time loading: **300-1,000 tokens per file** (agents typically need 2-3 files, not 10)
|
||||||
|
- **Net savings: 60-80% reduction in token usage**
|
||||||
|
|
||||||
|
#### Layer 3: Dynamic Runtime Context (Execution-Time Loading)
|
||||||
|
|
||||||
|
This layer handles long-horizon tasks and evolving context through compaction and memory strategies.
|
||||||
|
|
||||||
|
**Implementation:**
|
||||||
|
```xml
|
||||||
|
<session_memory>
|
||||||
|
<!-- Agents write notes persisted outside context window -->
|
||||||
|
<!-- Read back in at later times for coherence -->
|
||||||
|
.opencode/sessions/[task-id].md
|
||||||
|
</session_memory>
|
||||||
|
|
||||||
|
<dynamic_context>
|
||||||
|
<!-- RAG retrieval results filtered for relevance -->
|
||||||
|
<!-- Tool execution outputs -->
|
||||||
|
<!-- Delegation context from prior agents -->
|
||||||
|
</dynamic_context>
|
||||||
|
```
|
||||||
|
|
||||||
|
**Research backing:** For tasks spanning multiple turns:
|
||||||
|
- **Compaction**: Summarize context nearing window limit, reinitiate with summary + critical details
|
||||||
|
- **Structured note-taking**: Agent maintains notes in persistent memory (like session files), pulled back in later
|
||||||
|
- **Progressive context assembly**: Each interaction yields context informing the next decision
|
||||||
|
|
||||||
|
### Progressive Disclosure by Design
|
||||||
|
|
||||||
|
Structure your context hierarchy so agents discover relevance layer-by-layer:
|
||||||
|
|
||||||
|
```
|
||||||
|
.opencode/context/core/
|
||||||
|
├── standards/ ← Broad guidelines (agent starts here)
|
||||||
|
│ ├── code.md ← File naming hints: "code" standards
|
||||||
|
│ ├── tests.md ← "tests" = test-specific rules
|
||||||
|
│ └── patterns.md ← "patterns" = architectural patterns
|
||||||
|
├── practices/ ← Execution-level practices
|
||||||
|
│ ├── analysis.md ← "analysis" = how to analyze
|
||||||
|
│ └── review.md ← "review" = code review criteria
|
||||||
|
├── workflows/ ← Process templates
|
||||||
|
│ ├── delegation.md ← Delegation patterns
|
||||||
|
│ ├── task-breakdown.md ← Task analysis workflows
|
||||||
|
│ └── sessions.md ← Session management
|
||||||
|
└── system/
|
||||||
|
└── context-guide.md ← System internals
|
||||||
|
```
|
||||||
|
|
||||||
|
Each folder name signals purpose. Each file name within folders signals specific application. This is **progressive disclosure by design** - agents can navigate the hierarchy based on their current needs.
|
||||||
|
|
||||||
|
### Long-Horizon Task Strategies
|
||||||
|
|
||||||
|
For multi-hour tasks spanning context resets:
|
||||||
|
|
||||||
|
**Compaction Strategy:**
|
||||||
|
```xml
|
||||||
|
<memory_strategy>
|
||||||
|
<!-- Before context reset: Agent summarizes work -->
|
||||||
|
<compaction>
|
||||||
|
Preserve: Architectural decisions, unresolved bugs, key insights
|
||||||
|
Discard: Redundant tool outputs, repeated attempts
|
||||||
|
</compaction>
|
||||||
|
|
||||||
|
<!-- After reset: Agent reads notes and continues -->
|
||||||
|
<structured_notes path=".opencode/sessions/[id].md">
|
||||||
|
• Decisions made
|
||||||
|
• Current phase
|
||||||
|
• Next steps
|
||||||
|
• Unresolved issues
|
||||||
|
</structured_notes>
|
||||||
|
</memory_strategy>
|
||||||
|
```
|
||||||
|
|
||||||
|
**Example:** Anthropic's Claude Code maintains precise tallies across thousands of steps using persistent notes - the same pattern your session files implement.
|
||||||
|
|
||||||
|
### Anti-Patterns to Avoid
|
||||||
|
|
||||||
|
Research identifies these common mistakes that reduce effectiveness:
|
||||||
|
|
||||||
|
#### ❌ Anti-Pattern 1: Overload Static Context
|
||||||
|
|
||||||
|
```xml
|
||||||
|
<!-- DON'T DO THIS -->
|
||||||
|
<prompt>
|
||||||
|
<all_standards><!-- 5000+ tokens of standards upfront --></all_standards>
|
||||||
|
<task>Fix typo in button</task>
|
||||||
|
</prompt>
|
||||||
|
```
|
||||||
|
|
||||||
|
**Problems:**
|
||||||
|
- Attention budget exhaustion (n² transformer relationships)
|
||||||
|
- Reduced position sensitivity effectiveness (critical rules get buried)
|
||||||
|
- Worse adherence to specific instructions
|
||||||
|
|
||||||
|
**Solution:** Use lazy loading for large reference materials.
|
||||||
|
|
||||||
|
#### ❌ Anti-Pattern 2: Deep Nesting
|
||||||
|
|
||||||
|
```xml
|
||||||
|
<!-- DON'T DO THIS -->
|
||||||
|
<instructions>
|
||||||
|
<workflow>
|
||||||
|
<delegation>
|
||||||
|
<criteria>
|
||||||
|
<when>
|
||||||
|
<condition>
|
||||||
|
<!-- 6+ levels: breaks clarity -->
|
||||||
|
```
|
||||||
|
|
||||||
|
**Problem:** Nesting depth >4 levels reduces clarity significantly.
|
||||||
|
|
||||||
|
**Solution:** Use attributes and flatter structures with max 4 levels.
|
||||||
|
|
||||||
|
#### ❌ Anti-Pattern 3: Repeating Critical Rules
|
||||||
|
|
||||||
|
```xml
|
||||||
|
<!-- DON'T DO THIS -->
|
||||||
|
<rule_1>Always request approval</rule_1>
|
||||||
|
... 2000 tokens later ...
|
||||||
|
<rule_2>Always get approval before execution</rule_2>
|
||||||
|
... 3000 tokens later ...
|
||||||
|
<rule_3>Approval must be obtained</rule_3>
|
||||||
|
```
|
||||||
|
|
||||||
|
**Problem:** Repetition causes ambiguity and wastes tokens.
|
||||||
|
|
||||||
|
**Solution:** Define rules once in the first 15%, reference them with `@rule_id` elsewhere.
|
||||||
|
|
||||||
|
### Token Efficiency Metrics
|
||||||
|
|
||||||
|
Real-world measurements from production agent systems:
|
||||||
|
|
||||||
|
| Approach | Token Cost | Files Loaded | Efficiency |
|
||||||
|
|----------|-----------|--------------|------------|
|
||||||
|
| Pre-load all context | 2,000-5,000+ | 10-15 files | Baseline |
|
||||||
|
| Just-in-time loading | 300-1,000 | 2-3 files | **60-80% savings** |
|
||||||
|
| With compaction | 500-1,500 | 3-5 files | **50-70% savings** |
|
||||||
|
|
||||||
|
**Key insight:** Agents typically need only 2-3 context files per task, not the entire knowledge base.
|
||||||
|
|
||||||
|
### Research Validation Summary
|
||||||
|
|
||||||
|
| Pattern | Research Basis | Effect |
|
||||||
|
|---------|----------------|--------|
|
||||||
|
| **Position Sensitivity** | Stanford multi-instruction study | Improves adherence (varies by task/model) |
|
||||||
|
| **Just-in-Time Loading** | Anthropic context engineering (2025) | 60-80% token reduction |
|
||||||
|
| **Progressive Disclosure** | Anthropic agent research | Agents discover context incrementally |
|
||||||
|
| **Nesting Depth ≤4** | Anthropic XML research | Reduces complexity, improves clarity |
|
||||||
|
| **Compaction + Memory** | Anthropic long-horizon tasks | Maintains coherence across resets |
|
||||||
|
|
||||||
|
### Research Sources
|
||||||
|
|
||||||
|
- **Anthropic (2025)**: "Effective Context Engineering for AI Agents"
|
||||||
|
- **Stanford**: Multi-instruction position sensitivity study
|
||||||
|
- **Anthropic**: "XML Prompting as Grammar-Constrained Interaction" (ArXiv 2509.08182)
|
||||||
|
- **ODSC (2025)**: "Building Dynamic In-Context Learning for Self-Optimizing Agents"
|
||||||
|
- **ArXiv**: "Optimization of Retrieval-Augmented Generation Context with Outlier Detection" (2407.01403)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
## Custom Instruction Files
|
## Custom Instruction Files
|
||||||
|
|
||||||
**For arbitrary paths, use `instructions` field:**
|
**For arbitrary paths, use `instructions` field:**
|
||||||
|
|
|
||||||
|
|
@ -371,3 +371,168 @@ Task(
|
||||||
- ✅ Test with: "Can you [task description]"
|
- ✅ Test with: "Can you [task description]"
|
||||||
|
|
||||||
That's it! Main agent reads AGENTS.md, sees the patterns, and knows how to invoke slash commands through subagents.
|
That's it! Main agent reads AGENTS.md, sees the patterns, and knows how to invoke slash commands through subagents.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Appendix: Path Resolution Test Findings
|
||||||
|
|
||||||
|
**Date:** November 19, 2025
|
||||||
|
**Test Objective:** Verify path resolution behavior for portable agent installation strategy
|
||||||
|
|
||||||
|
### 🔍 Discovery Phase Results
|
||||||
|
|
||||||
|
#### OpenCode Directory Structure
|
||||||
|
|
||||||
|
**Global Configuration:**
|
||||||
|
- **Location:** `~/.config/opencode/`
|
||||||
|
- **Contents:** `opencode.json`, `config.json`, plugins, providers
|
||||||
|
- **Note:** No `agent/`, `command/`, or `context/` folders found in default installation
|
||||||
|
|
||||||
|
**Authentication & Data:**
|
||||||
|
- **Location:** `~/.local/share/opencode/`
|
||||||
|
- **Contents:** `auth.json`, bin, log, project, snapshot, storage
|
||||||
|
|
||||||
|
**Local Repository:**
|
||||||
|
- **Location:** `.opencode/` (in git repository root)
|
||||||
|
- **Structure:** `agent/`, `command/`, `context/`, `plugin/`, `tool/`
|
||||||
|
|
||||||
|
#### Key Findings
|
||||||
|
|
||||||
|
1. ✅ **Global config path confirmed:** `~/.config/opencode/`
|
||||||
|
2. ✅ **Local structure confirmed:** `.opencode/` in repo root
|
||||||
|
3. ⚠️ **Current agents don't use `@` references** - Context loaded via different mechanism
|
||||||
|
4. ✅ **Context files exist** in `.opencode/context/` with subdirectories
|
||||||
|
|
||||||
|
### 📊 Path Resolution Analysis
|
||||||
|
|
||||||
|
#### From OpenCode Documentation
|
||||||
|
|
||||||
|
**`@` Symbol Resolution Order:**
|
||||||
|
1. Check if starts with `~/` → resolve to home directory
|
||||||
|
2. Check if absolute path → use as-is
|
||||||
|
3. Otherwise → resolve relative to repo root (`Instance.worktree`)
|
||||||
|
4. If not found → look for agent with that name
|
||||||
|
|
||||||
|
#### Implications for Installation
|
||||||
|
|
||||||
|
**Local Installation (in repo):**
|
||||||
|
```
|
||||||
|
Repo structure:
|
||||||
|
.opencode/
|
||||||
|
├── agent/security/scanner.md
|
||||||
|
└── context/security/patterns.md
|
||||||
|
|
||||||
|
Reference: @.opencode/context/security/patterns.md
|
||||||
|
Resolution: {repo-root}/.opencode/context/security/patterns.md ✅
|
||||||
|
```
|
||||||
|
|
||||||
|
**Global Installation:**
|
||||||
|
```
|
||||||
|
Global structure:
|
||||||
|
~/.config/opencode/
|
||||||
|
├── agent/security/scanner.md
|
||||||
|
└── context/security/patterns.md
|
||||||
|
|
||||||
|
Reference: @.opencode/context/security/patterns.md
|
||||||
|
Resolution: Tries to find .opencode/ relative to... what? ❌
|
||||||
|
Problem: No "repo root" for global agents!
|
||||||
|
```
|
||||||
|
|
||||||
|
### 🎯 Path Pattern Testing
|
||||||
|
|
||||||
|
#### Test Setup
|
||||||
|
|
||||||
|
Created global test agent with three path patterns:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# Pattern 1: With .opencode prefix
|
||||||
|
@.opencode/context/test/global-test-data.md
|
||||||
|
|
||||||
|
# Pattern 2: Without .opencode prefix
|
||||||
|
@context/test/global-test-data.md
|
||||||
|
|
||||||
|
# Pattern 3: Explicit home path
|
||||||
|
@~/.config/opencode/context/test/global-test-data.md
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Expected Results (Based on Documentation)
|
||||||
|
|
||||||
|
| Pattern | Local Install | Global Install | Notes |
|
||||||
|
|---------|--------------|----------------|-------|
|
||||||
|
| `@.opencode/context/file.md` | ✅ Works | ❌ Fails | No .opencode in global path |
|
||||||
|
| `@context/file.md` | ❌ Fails | ❓ Unknown | Might resolve to ~/.config/opencode/context/ |
|
||||||
|
| `@~/.config/opencode/context/file.md` | ❌ Fails | ✅ Works | Explicit path, but breaks local |
|
||||||
|
|
||||||
|
#### Critical Issue
|
||||||
|
|
||||||
|
**No single path pattern works for both local AND global installations!**
|
||||||
|
|
||||||
|
This confirms our installation script approach is necessary.
|
||||||
|
|
||||||
|
### ✅ Validated Assumptions
|
||||||
|
|
||||||
|
1. ✅ **Global path is `~/.config/opencode/`** - Confirmed
|
||||||
|
2. ✅ **Local path is `.opencode/`** - Confirmed
|
||||||
|
3. ✅ **Path transformation is required** - Confirmed (no universal pattern)
|
||||||
|
4. ✅ **Context folder structure works** - Confirmed (exists in current repo)
|
||||||
|
|
||||||
|
### ❌ Invalidated Assumptions
|
||||||
|
|
||||||
|
1. ❌ **`@context/file.md` might work universally** - Unconfirmed, likely fails locally
|
||||||
|
2. ❌ **Current agents use `@` references** - They don't (different loading mechanism)
|
||||||
|
|
||||||
|
### 🔧 Installation Strategy Confirmation
|
||||||
|
|
||||||
|
#### Source Code Convention
|
||||||
|
|
||||||
|
**All context references MUST use:**
|
||||||
|
```markdown
|
||||||
|
@.opencode/context/{category}/{file}.md
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Installation Script Transformation
|
||||||
|
|
||||||
|
**Local Installation:**
|
||||||
|
- Keep references as-is: `@.opencode/context/...`
|
||||||
|
- Copy to: `{repo}/.opencode/`
|
||||||
|
|
||||||
|
**Global Installation:**
|
||||||
|
- Transform: `@.opencode/context/` → `@~/.config/opencode/context/`
|
||||||
|
- Copy to: `~/.config/opencode/`
|
||||||
|
|
||||||
|
#### Transformation Rules
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# For global installation
|
||||||
|
sed 's|@\.opencode/context/|@~/.config/opencode/context/|g'
|
||||||
|
|
||||||
|
# Also transform shell commands
|
||||||
|
sed 's|\.opencode/context/|~/.config/opencode/context/|g'
|
||||||
|
```
|
||||||
|
|
||||||
|
### 🚨 Additional Considerations
|
||||||
|
|
||||||
|
#### Shell Commands in Templates
|
||||||
|
|
||||||
|
**Problem:** Commands like `!`ls .opencode/context/`` also need transformation
|
||||||
|
|
||||||
|
**Solution:** Transform both `@` references AND bare paths in shell commands
|
||||||
|
|
||||||
|
#### Context Cross-References
|
||||||
|
|
||||||
|
**Problem:** Context files may reference other context files
|
||||||
|
|
||||||
|
**Solution:** Transform context files too, not just agents/commands
|
||||||
|
|
||||||
|
#### Platform Compatibility
|
||||||
|
|
||||||
|
**macOS/Linux:** `~/.config/opencode/` ✅
|
||||||
|
**Windows:** Need to verify (likely `%APPDATA%\opencode` or similar)
|
||||||
|
|
||||||
|
### 📝 Recommendations
|
||||||
|
|
||||||
|
1. **Proceed with Installation Script Approach** - The two-tier distribution with path transformation is necessary and correct
|
||||||
|
2. **Strict Convention Enforcement** - Create validation script to ensure all references follow `@.opencode/context/` pattern
|
||||||
|
3. **Transform All File Types** - Agent files, command files, AND context files
|
||||||
|
4. **Test on Actual OpenCode Installation** - Runtime testing would confirm edge cases
|
||||||
|
5. **Platform-Specific Paths** - Verify global paths on Windows before production release
|
||||||
|
|
|
||||||
0
scripts/tests/test-collision-detection.sh
Normal file → Executable file
0
scripts/tests/test-collision-detection.sh
Normal file → Executable file
Loading…
Reference in a new issue