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
|
||||
*.log
|
||||
npm-debug.log*
|
||||
yarn-debug.log*
|
||||
yarn-error.log*
|
||||
lerna-debug.log*
|
||||
.pnpm-debug.log*
|
||||
|
||||
# Diagnostic reports (https://nodejs.org/api/report.html)
|
||||
report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
|
||||
|
||||
# Runtime data
|
||||
pids
|
||||
|
|
@ -44,13 +52,141 @@ pids
|
|||
*.seed
|
||||
*.pid.lock
|
||||
|
||||
# Directory for instrumented libs generated by jscoverage/JSCover
|
||||
lib-cov
|
||||
|
||||
# Coverage directory used by tools like istanbul
|
||||
coverage/
|
||||
coverage
|
||||
*.lcov
|
||||
|
||||
# nyc test coverage
|
||||
.nyc_output
|
||||
|
||||
# Temporary folders
|
||||
# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
|
||||
.grunt
|
||||
|
||||
# Bower dependency directory (https://bower.io/)
|
||||
bower_components
|
||||
|
||||
# node-waf configuration
|
||||
.lock-wscript
|
||||
|
||||
# Compiled binary addons (https://nodejs.org/api/addons.html)
|
||||
build/Release
|
||||
|
||||
# Dependency directories
|
||||
node_modules/
|
||||
jspm_packages/
|
||||
|
||||
# Snowpack dependency directory (https://snowpack.dev/)
|
||||
web_modules/
|
||||
|
||||
# TypeScript cache
|
||||
*.tsbuildinfo
|
||||
|
||||
# Optional npm cache directory
|
||||
.npm
|
||||
|
||||
# Optional eslint cache
|
||||
.eslintcache
|
||||
|
||||
# Optional stylelint cache
|
||||
.stylelintcache
|
||||
|
||||
# Microbundle cache
|
||||
.rpt2_cache/
|
||||
.rts2_cache_cjs/
|
||||
.rts2_cache_es/
|
||||
.rts2_cache_umd/
|
||||
|
||||
# Optional REPL history
|
||||
.node_repl_history
|
||||
|
||||
# Output of 'npm pack'
|
||||
*.tgz
|
||||
|
||||
# Yarn Integrity file
|
||||
.yarn-integrity
|
||||
|
||||
# dotenv environment variable files
|
||||
.env
|
||||
.env.development.local
|
||||
.env.test.local
|
||||
.env.production.local
|
||||
.env.local
|
||||
|
||||
# parcel-bundler cache (https://parceljs.org/)
|
||||
.cache
|
||||
.parcel-cache
|
||||
|
||||
# Next.js build output
|
||||
.next
|
||||
out
|
||||
|
||||
# Nuxt.js build / generate output
|
||||
.nuxt
|
||||
dist
|
||||
|
||||
# Gatsby files
|
||||
.cache/
|
||||
# Comment in the public line in if your project uses Gatsby and not Next.js
|
||||
# https://nextjs.org/blog/next-9-1#public-directory-support
|
||||
# public
|
||||
|
||||
# vuepress build output
|
||||
.vuepress/dist
|
||||
|
||||
# vuepress v2.x temp and cache directory
|
||||
.temp
|
||||
.cache
|
||||
|
||||
# Docusaurus cache and generated files
|
||||
.docusaurus
|
||||
|
||||
# Serverless directories
|
||||
.serverless/
|
||||
|
||||
# FuseBox cache
|
||||
.fusebox/
|
||||
|
||||
# DynamoDB Local files
|
||||
.dynamodb/
|
||||
|
||||
# TernJS port file
|
||||
.tern-port
|
||||
|
||||
# Stores VSCode versions used for testing VSCode extensions
|
||||
.vscode-test
|
||||
|
||||
# yarn v2
|
||||
.yarn/cache
|
||||
.yarn/unplugged
|
||||
.yarn/build-state.yml
|
||||
.yarn/install-state.gz
|
||||
.pnp.*
|
||||
|
||||
# macOS
|
||||
.DS_Store
|
||||
|
||||
# IDE
|
||||
.idea/
|
||||
.vscode/
|
||||
*.swp
|
||||
*.swo
|
||||
*~
|
||||
|
||||
# Temporary files
|
||||
tmp/
|
||||
temp/
|
||||
|
||||
# Installation test artifacts
|
||||
.opencode.backup-*
|
||||
.opencode-test/
|
||||
.opencode-agents-version
|
||||
*.backup-*/
|
||||
|
||||
# Test output
|
||||
/tmp/install-output.log
|
||||
.tmp/
|
||||
|
||||
# Optional npm cache directory
|
||||
|
|
|
|||
|
|
@ -27,7 +27,7 @@ permissions:
|
|||
|
||||
<critical_rules priority="absolute" enforcement="strict">
|
||||
<rule id="approval_gate" scope="all_execution">
|
||||
ALWAYS request approval before ANY execution (bash, write, edit, task delegation)
|
||||
ALWAYS request approval before ANY execution (bash, write, edit, task delegation). Read and list operations do not require approval.
|
||||
</rule>
|
||||
<rule id="stop_on_failure" scope="validation">
|
||||
STOP immediately on test failures or errors - NEVER auto-fix
|
||||
|
|
@ -167,60 +167,58 @@ permissions:
|
|||
</stage>
|
||||
</workflow>
|
||||
|
||||
<execution_philosophy>
|
||||
You are a UNIVERSAL agent - handle most tasks directly.
|
||||
|
||||
**Capabilities**: Write code, docs, tests, reviews, analysis, debugging, research, bash, file operations
|
||||
|
||||
**Delegate only when**: 4+ files, specialized expertise needed, thorough multi-component review, complex dependencies, or user requests breakdown
|
||||
|
||||
**Default**: Execute directly, fetch context files as needed (lazy), keep it simple, don't over-delegate
|
||||
|
||||
**Delegation**: Create .tmp/sessions/{id}/context.md with requirements/decisions/files/instructions, reference static context, cleanup after
|
||||
</execution_philosophy>
|
||||
|
||||
<delegation_rules id="delegation_rules">
|
||||
<context_file_creation when="delegating">
|
||||
Only create context file when BOTH:
|
||||
- Delegating to a subagent AND
|
||||
- Context is verbose (>2 sentences) OR risk of misinterpretation
|
||||
|
||||
See: .opencode/context/core/context-discovery.md for details
|
||||
</context_file_creation>
|
||||
<when_to_delegate>
|
||||
Delegate to general agent when ANY of these conditions:
|
||||
|
||||
<route agent="@subagents/core/task-manager"
|
||||
category="features"
|
||||
when="3+_files OR 60+_min OR complex_dependencies OR explicit_request"
|
||||
output=".tmp/sessions/{id}/tasks/{name}-tasks.md"
|
||||
context_inheritance="true">
|
||||
<example>User: "Build user authentication system"</example>
|
||||
</route>
|
||||
1. **Scale**: 4+ files to modify/create
|
||||
2. **Expertise**: Needs specialized knowledge (security, algorithms, architecture, performance)
|
||||
3. **Review**: Needs thorough review across multiple components
|
||||
4. **Complexity**: Multi-step coordination with dependencies
|
||||
5. **Perspective**: Need fresh eyes, alternative approaches, or different viewpoint
|
||||
6. **Simulation**: Testing scenarios, edge cases, user behavior, what-if analysis
|
||||
7. **User request**: User explicitly asks for breakdown/delegation
|
||||
|
||||
<route agent="@subagents/core/documentation"
|
||||
category="documentation"
|
||||
when="comprehensive_docs OR multi_page OR codebase_analysis OR explicit_request">
|
||||
<example>User: "Create API documentation for all endpoints"</example>
|
||||
</route>
|
||||
Otherwise: Execute directly (you are universal, handle it)
|
||||
</when_to_delegate>
|
||||
|
||||
<route agent="@subagents/utils/image-specialist"
|
||||
category="images"
|
||||
when="image_gen OR image_edit OR image_analysis"
|
||||
availability="check_profile">
|
||||
<example>User: "Generate a logo" or "Edit this image"</example>
|
||||
</route>
|
||||
<how_to_delegate>
|
||||
1. Create temp context: `.tmp/sessions/{timestamp}-{task-slug}/context.md`
|
||||
2. Populate using template from .opencode/context/core/workflows/delegation.md
|
||||
3. Delegate with context path and brief description
|
||||
4. Cleanup after completion (ask user first)
|
||||
|
||||
<route agent="@subagents/code/reviewer"
|
||||
category="review"
|
||||
when="code_review OR security_analysis"
|
||||
availability="check_profile">
|
||||
<example>User: "Review this code for security issues"</example>
|
||||
</route>
|
||||
See .opencode/context/core/workflows/delegation.md for full template structure and process.
|
||||
</how_to_delegate>
|
||||
|
||||
<route agent="@subagents/code/codebase-pattern-analyst"
|
||||
category="patterns"
|
||||
when="pattern_discovery OR how_do_we_questions"
|
||||
availability="check_profile">
|
||||
<example>User: "How do we handle pagination in this codebase?"</example>
|
||||
</route>
|
||||
<examples>
|
||||
**Execute Directly:**
|
||||
✅ "Fix this bug" → Single file, clear fix
|
||||
✅ "Add input validation" → Straightforward enhancement
|
||||
|
||||
<route agent="@subagents/code/*"
|
||||
category="code"
|
||||
when="code_specific_task"
|
||||
availability="check_profile">
|
||||
<example>User: "Write tests for this function"</example>
|
||||
</route>
|
||||
**Delegate for Complexity:**
|
||||
⚠️ "Refactor data layer across 5 files" → Multi-file coordination
|
||||
⚠️ "Implement feature X with Y and Z components" → 4+ files, complex integration
|
||||
|
||||
**Delegate for Perspective/Simulation:**
|
||||
⚠️ "Review this API design - what could go wrong?" → Fresh perspective needed
|
||||
⚠️ "Simulate edge cases for this algorithm" → Testing scenarios
|
||||
⚠️ "What are alternative approaches to solve X?" → Brainstorming alternatives
|
||||
</examples>
|
||||
|
||||
<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>
|
||||
|
||||
<principles>
|
||||
|
|
@ -236,17 +234,36 @@ permissions:
|
|||
<transparent>Explain decisions, show reasoning when helpful</transparent>
|
||||
</principles>
|
||||
|
||||
<references>
|
||||
<session_management ref=".opencode/context/core/session-management.md">
|
||||
Lazy initialization, session isolation, cleanup policy, error handling
|
||||
</session_management>
|
||||
<context_discovery ref=".opencode/context/core/context-discovery.md">
|
||||
Dynamic context loading, manifest indexing, keyword search, delegation patterns
|
||||
</context_discovery>
|
||||
<context_management ref=".opencode/context/core/context-management.md">
|
||||
Full context management strategy including session structure and workflows
|
||||
</context_management>
|
||||
<essential_patterns ref=".opencode/context/core/essential-patterns.md">
|
||||
Core coding patterns, error handling, security, testing best practices
|
||||
</essential_patterns>
|
||||
</references>
|
||||
<static_context>
|
||||
Guidelines in .opencode/context/core/ - fetch when needed (WITHOUT @):
|
||||
|
||||
**Standards** (quality guidelines + analysis):
|
||||
- standards/code.md - Modular, functional code
|
||||
- standards/docs.md - Documentation standards
|
||||
- standards/tests.md - Testing standards
|
||||
- standards/patterns.md - Core patterns
|
||||
- standards/analysis.md - Analysis framework
|
||||
|
||||
**Workflows** (process templates + review):
|
||||
- workflows/delegation.md - Delegation template
|
||||
- workflows/task-breakdown.md - Task breakdown
|
||||
- workflows/sessions.md - Session lifecycle
|
||||
- workflows/review.md - Code review guidelines
|
||||
|
||||
See system/context-guide.md for full guide. Fetch only what's relevant - keeps prompts lean.
|
||||
</static_context>
|
||||
|
||||
<critical_rules priority="absolute" enforcement="strict">
|
||||
<rule id="approval_gate" scope="all_execution">
|
||||
ALWAYS request approval before ANY execution (bash, write, edit, task delegation). Read and list operations do not require approval.
|
||||
</rule>
|
||||
<rule id="stop_on_failure" scope="validation">
|
||||
STOP immediately on test failures or errors - NEVER auto-fix
|
||||
</rule>
|
||||
<rule id="report_first" scope="error_handling">
|
||||
On failure: REPORT → PROPOSE FIX → REQUEST APPROVAL → FIX (never auto-fix)
|
||||
</rule>
|
||||
<rule id="confirm_cleanup" scope="session_management">
|
||||
ALWAYS confirm before deleting session files or cleanup operations
|
||||
</rule>
|
||||
</critical_rules>
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
## Quick Reference
|
||||
|
||||
**Critical Patterns**: Error Handling, Validation, Security, Logging
|
||||
|
||||
**ALWAYS**: Handle errors gracefully, validate input, use env vars for secrets
|
||||
|
||||
**NEVER**: Expose sensitive info, hardcode credentials, skip input validation
|
||||
|
||||
**Language-agnostic**: Apply to all programming languages
|
||||
|
||||
---
|
||||
|
||||
These are language-agnostic patterns that apply to all programming languages. Language-specific implementations are loaded from context files based on project detection.
|
||||
|
||||
## Error Handling Pattern
|
||||
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
|
||||
|
||||
## Quick Reference
|
||||
|
||||
**Key Principle**: Lazy initialization - only create when needed
|
||||
|
||||
**Session ID**: `{timestamp}-{random-4-chars}` (e.g., `20250118-143022-a4f2`)
|
||||
|
||||
**Cleanup**: Always ask user confirmation before deleting
|
||||
|
||||
**Safety**: NEVER delete outside current session, ONLY delete tracked files, ALWAYS confirm
|
||||
|
||||
---
|
||||
|
||||
## Lazy Initialization
|
||||
|
||||
**Only create session when first context file needed**
|
||||
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
|
||||
|
||||
### Immediate vs. Lazy Loading
|
||||
|
||||
**With `@` symbol** - **Immediate Loading**:
|
||||
- File is fetched and loaded right away
|
||||
- Content is immediately available to the agent
|
||||
- Use when context is always needed
|
||||
|
||||
**Without `@` symbol** - **Lazy Loading**:
|
||||
- File is only fetched when the agent determines it's needed
|
||||
- Saves tokens if the agent can complete the task without it
|
||||
- Agent discovers and loads the file on-demand
|
||||
|
||||
### Using the `@` Symbol
|
||||
|
||||
**In commands and templates:**
|
||||
|
||||
```bash
|
||||
|
|
@ -82,6 +96,283 @@ your-repo/
|
|||
3. Otherwise → resolve relative to repo root (`Instance.worktree`)
|
||||
4. If not found → look for agent with that name
|
||||
|
||||
### Best Practices for Lazy Loading (Without `@`)
|
||||
|
||||
When referencing files without the `@` symbol, help the agent discover them by:
|
||||
|
||||
**1. Provide clear file paths**
|
||||
```
|
||||
"Use the context from .opencode/command/commit.md if needed"
|
||||
```
|
||||
|
||||
**2. Describe what's there** (so agent knows when to fetch)
|
||||
```
|
||||
"Check the commit command guidelines in .opencode/command/commit.md
|
||||
when you need to understand our commit message format"
|
||||
```
|
||||
|
||||
**3. Mention directory conventions**
|
||||
```
|
||||
"Command templates are in .opencode/command/ - reference them as needed"
|
||||
```
|
||||
|
||||
**4. Reference by purpose, not just path**
|
||||
```
|
||||
"Follow our commit guidelines (available in the command directory)
|
||||
when making commits"
|
||||
```
|
||||
|
||||
### Example: Lazy Loading in Practice
|
||||
|
||||
**Without `@` symbol (lazy loading):**
|
||||
```
|
||||
"Create a git commit. Our commit guidelines are in .opencode/command/commit.md -
|
||||
check them if you need to understand our prefix conventions and message format."
|
||||
```
|
||||
|
||||
This approach:
|
||||
- ✅ Agent knows the file exists and where it is
|
||||
- ✅ Agent knows WHEN it would be useful (for commit conventions)
|
||||
- ✅ Agent only reads it IF it needs that information
|
||||
- ✅ Saves tokens if the agent can complete the task without it
|
||||
|
||||
**With `@` symbol (immediate loading):**
|
||||
```
|
||||
"Create a git commit following these guidelines: @.opencode/command/commit.md"
|
||||
```
|
||||
|
||||
This approach:
|
||||
- ✅ File content is immediately available
|
||||
- ✅ Guaranteed the agent has the context
|
||||
- ⚠️ Uses tokens even if agent doesn't need it
|
||||
|
||||
### When to Use Each Approach
|
||||
|
||||
| Use `@` (Immediate) | Omit `@` (Lazy) |
|
||||
|---------------------|-----------------|
|
||||
| Context always required | Context might be needed |
|
||||
| Short, critical files | Large reference files |
|
||||
| Agent must follow exact format | Agent can infer or discover |
|
||||
| Templates and schemas | Documentation and guides |
|
||||
|
||||
**Pro tip:** Modern agents are good at discovering needed files through `codebase_search` or exploring directories, but being explicit about important files helps ensure consistency.
|
||||
|
||||
---
|
||||
|
||||
## Research-Backed Context Architecture
|
||||
|
||||
### Three-Layer Progressive Architecture
|
||||
|
||||
Based on validated research from Stanford, Anthropic (2025), and recent AI agent engineering studies, effective context loading follows a three-layer progressive architecture:
|
||||
|
||||
#### Layer 1: Static Base Context (First 15% of Prompt)
|
||||
|
||||
This is your foundational layer, grounded in Stanford's position sensitivity research. **Critical instructions positioned early dramatically improve adherence.**
|
||||
|
||||
**What goes here:**
|
||||
- Role definition (5-10%)
|
||||
- Critical rules (defined once, early positioning)
|
||||
- Task definition (clear objective)
|
||||
- Constraint summary (high-level "must/must-not")
|
||||
|
||||
**Example:**
|
||||
```xml
|
||||
<role>Expert Prompt Architect</role>
|
||||
<critical_rules priority="absolute" enforcement="strict">
|
||||
<rule id="position_sensitivity">Critical rules MUST be in first 15%</rule>
|
||||
<rule id="nesting_limit">Max nesting: 4 levels</rule>
|
||||
</critical_rules>
|
||||
<execution_priority>
|
||||
<tier level="1">Research patterns (non-negotiable)</tier>
|
||||
</execution_priority>
|
||||
```
|
||||
|
||||
**Why this matters:** Research shows position sensitivity improves adherence across model sizes. Critical rules at the start are more reliably followed than rules buried later in the prompt.
|
||||
|
||||
#### Layer 2: Lazy-Loaded Context (Just-in-Time Retrieval)
|
||||
|
||||
This layer uses the "just-in-time" approach validated by Anthropic's 2025 research on effective context engineering for AI agents.
|
||||
|
||||
> Rather than pre-processing all relevant data up front, agents built with the "just-in-time" approach maintain lightweight identifiers (file paths, stored queries, web links, etc.) and use these references to dynamically load data into context at runtime using tools.
|
||||
|
||||
**Implementation:**
|
||||
```xml
|
||||
<context_sources>
|
||||
<!-- Agent fetches these as needed, not embedded upfront -->
|
||||
<standards>.opencode/context/core/standards/code.md</standards>
|
||||
<practices>.opencode/context/core/practices/review.md</practices>
|
||||
<workflows>.opencode/context/core/workflows/delegation.md</workflows>
|
||||
</context_sources>
|
||||
```
|
||||
|
||||
**Key insight:** This enables **progressive disclosure**. Agents incrementally discover context through exploration:
|
||||
- File naming hints at purpose (`.../standards/code.md` vs `.../practices/review.md`)
|
||||
- File size signals complexity
|
||||
- Timestamps indicate recency
|
||||
- Folder structure provides hierarchical context
|
||||
|
||||
**Token efficiency gain:**
|
||||
- Pre-loading all context: **2,000-5,000+ tokens**
|
||||
- Just-in-time loading: **300-1,000 tokens per file** (agents typically need 2-3 files, not 10)
|
||||
- **Net savings: 60-80% reduction in token usage**
|
||||
|
||||
#### Layer 3: Dynamic Runtime Context (Execution-Time Loading)
|
||||
|
||||
This layer handles long-horizon tasks and evolving context through compaction and memory strategies.
|
||||
|
||||
**Implementation:**
|
||||
```xml
|
||||
<session_memory>
|
||||
<!-- Agents write notes persisted outside context window -->
|
||||
<!-- Read back in at later times for coherence -->
|
||||
.opencode/sessions/[task-id].md
|
||||
</session_memory>
|
||||
|
||||
<dynamic_context>
|
||||
<!-- RAG retrieval results filtered for relevance -->
|
||||
<!-- Tool execution outputs -->
|
||||
<!-- Delegation context from prior agents -->
|
||||
</dynamic_context>
|
||||
```
|
||||
|
||||
**Research backing:** For tasks spanning multiple turns:
|
||||
- **Compaction**: Summarize context nearing window limit, reinitiate with summary + critical details
|
||||
- **Structured note-taking**: Agent maintains notes in persistent memory (like session files), pulled back in later
|
||||
- **Progressive context assembly**: Each interaction yields context informing the next decision
|
||||
|
||||
### Progressive Disclosure by Design
|
||||
|
||||
Structure your context hierarchy so agents discover relevance layer-by-layer:
|
||||
|
||||
```
|
||||
.opencode/context/core/
|
||||
├── standards/ ← Broad guidelines (agent starts here)
|
||||
│ ├── code.md ← File naming hints: "code" standards
|
||||
│ ├── tests.md ← "tests" = test-specific rules
|
||||
│ └── patterns.md ← "patterns" = architectural patterns
|
||||
├── practices/ ← Execution-level practices
|
||||
│ ├── analysis.md ← "analysis" = how to analyze
|
||||
│ └── review.md ← "review" = code review criteria
|
||||
├── workflows/ ← Process templates
|
||||
│ ├── delegation.md ← Delegation patterns
|
||||
│ ├── task-breakdown.md ← Task analysis workflows
|
||||
│ └── sessions.md ← Session management
|
||||
└── system/
|
||||
└── context-guide.md ← System internals
|
||||
```
|
||||
|
||||
Each folder name signals purpose. Each file name within folders signals specific application. This is **progressive disclosure by design** - agents can navigate the hierarchy based on their current needs.
|
||||
|
||||
### Long-Horizon Task Strategies
|
||||
|
||||
For multi-hour tasks spanning context resets:
|
||||
|
||||
**Compaction Strategy:**
|
||||
```xml
|
||||
<memory_strategy>
|
||||
<!-- Before context reset: Agent summarizes work -->
|
||||
<compaction>
|
||||
Preserve: Architectural decisions, unresolved bugs, key insights
|
||||
Discard: Redundant tool outputs, repeated attempts
|
||||
</compaction>
|
||||
|
||||
<!-- After reset: Agent reads notes and continues -->
|
||||
<structured_notes path=".opencode/sessions/[id].md">
|
||||
• Decisions made
|
||||
• Current phase
|
||||
• Next steps
|
||||
• Unresolved issues
|
||||
</structured_notes>
|
||||
</memory_strategy>
|
||||
```
|
||||
|
||||
**Example:** Anthropic's Claude Code maintains precise tallies across thousands of steps using persistent notes - the same pattern your session files implement.
|
||||
|
||||
### Anti-Patterns to Avoid
|
||||
|
||||
Research identifies these common mistakes that reduce effectiveness:
|
||||
|
||||
#### ❌ Anti-Pattern 1: Overload Static Context
|
||||
|
||||
```xml
|
||||
<!-- DON'T DO THIS -->
|
||||
<prompt>
|
||||
<all_standards><!-- 5000+ tokens of standards upfront --></all_standards>
|
||||
<task>Fix typo in button</task>
|
||||
</prompt>
|
||||
```
|
||||
|
||||
**Problems:**
|
||||
- Attention budget exhaustion (n² transformer relationships)
|
||||
- Reduced position sensitivity effectiveness (critical rules get buried)
|
||||
- Worse adherence to specific instructions
|
||||
|
||||
**Solution:** Use lazy loading for large reference materials.
|
||||
|
||||
#### ❌ Anti-Pattern 2: Deep Nesting
|
||||
|
||||
```xml
|
||||
<!-- DON'T DO THIS -->
|
||||
<instructions>
|
||||
<workflow>
|
||||
<delegation>
|
||||
<criteria>
|
||||
<when>
|
||||
<condition>
|
||||
<!-- 6+ levels: breaks clarity -->
|
||||
```
|
||||
|
||||
**Problem:** Nesting depth >4 levels reduces clarity significantly.
|
||||
|
||||
**Solution:** Use attributes and flatter structures with max 4 levels.
|
||||
|
||||
#### ❌ Anti-Pattern 3: Repeating Critical Rules
|
||||
|
||||
```xml
|
||||
<!-- DON'T DO THIS -->
|
||||
<rule_1>Always request approval</rule_1>
|
||||
... 2000 tokens later ...
|
||||
<rule_2>Always get approval before execution</rule_2>
|
||||
... 3000 tokens later ...
|
||||
<rule_3>Approval must be obtained</rule_3>
|
||||
```
|
||||
|
||||
**Problem:** Repetition causes ambiguity and wastes tokens.
|
||||
|
||||
**Solution:** Define rules once in the first 15%, reference them with `@rule_id` elsewhere.
|
||||
|
||||
### Token Efficiency Metrics
|
||||
|
||||
Real-world measurements from production agent systems:
|
||||
|
||||
| Approach | Token Cost | Files Loaded | Efficiency |
|
||||
|----------|-----------|--------------|------------|
|
||||
| Pre-load all context | 2,000-5,000+ | 10-15 files | Baseline |
|
||||
| Just-in-time loading | 300-1,000 | 2-3 files | **60-80% savings** |
|
||||
| With compaction | 500-1,500 | 3-5 files | **50-70% savings** |
|
||||
|
||||
**Key insight:** Agents typically need only 2-3 context files per task, not the entire knowledge base.
|
||||
|
||||
### Research Validation Summary
|
||||
|
||||
| Pattern | Research Basis | Effect |
|
||||
|---------|----------------|--------|
|
||||
| **Position Sensitivity** | Stanford multi-instruction study | Improves adherence (varies by task/model) |
|
||||
| **Just-in-Time Loading** | Anthropic context engineering (2025) | 60-80% token reduction |
|
||||
| **Progressive Disclosure** | Anthropic agent research | Agents discover context incrementally |
|
||||
| **Nesting Depth ≤4** | Anthropic XML research | Reduces complexity, improves clarity |
|
||||
| **Compaction + Memory** | Anthropic long-horizon tasks | Maintains coherence across resets |
|
||||
|
||||
### Research Sources
|
||||
|
||||
- **Anthropic (2025)**: "Effective Context Engineering for AI Agents"
|
||||
- **Stanford**: Multi-instruction position sensitivity study
|
||||
- **Anthropic**: "XML Prompting as Grammar-Constrained Interaction" (ArXiv 2509.08182)
|
||||
- **ODSC (2025)**: "Building Dynamic In-Context Learning for Self-Optimizing Agents"
|
||||
- **ArXiv**: "Optimization of Retrieval-Augmented Generation Context with Outlier Detection" (2407.01403)
|
||||
|
||||
---
|
||||
|
||||
## Custom Instruction Files
|
||||
|
||||
**For arbitrary paths, use `instructions` field:**
|
||||
|
|
|
|||
|
|
@ -371,3 +371,168 @@ Task(
|
|||
- ✅ Test with: "Can you [task description]"
|
||||
|
||||
That's it! Main agent reads AGENTS.md, sees the patterns, and knows how to invoke slash commands through subagents.
|
||||
|
||||
---
|
||||
|
||||
## Appendix: Path Resolution Test Findings
|
||||
|
||||
**Date:** November 19, 2025
|
||||
**Test Objective:** Verify path resolution behavior for portable agent installation strategy
|
||||
|
||||
### 🔍 Discovery Phase Results
|
||||
|
||||
#### OpenCode Directory Structure
|
||||
|
||||
**Global Configuration:**
|
||||
- **Location:** `~/.config/opencode/`
|
||||
- **Contents:** `opencode.json`, `config.json`, plugins, providers
|
||||
- **Note:** No `agent/`, `command/`, or `context/` folders found in default installation
|
||||
|
||||
**Authentication & Data:**
|
||||
- **Location:** `~/.local/share/opencode/`
|
||||
- **Contents:** `auth.json`, bin, log, project, snapshot, storage
|
||||
|
||||
**Local Repository:**
|
||||
- **Location:** `.opencode/` (in git repository root)
|
||||
- **Structure:** `agent/`, `command/`, `context/`, `plugin/`, `tool/`
|
||||
|
||||
#### Key Findings
|
||||
|
||||
1. ✅ **Global config path confirmed:** `~/.config/opencode/`
|
||||
2. ✅ **Local structure confirmed:** `.opencode/` in repo root
|
||||
3. ⚠️ **Current agents don't use `@` references** - Context loaded via different mechanism
|
||||
4. ✅ **Context files exist** in `.opencode/context/` with subdirectories
|
||||
|
||||
### 📊 Path Resolution Analysis
|
||||
|
||||
#### From OpenCode Documentation
|
||||
|
||||
**`@` Symbol Resolution Order:**
|
||||
1. Check if starts with `~/` → resolve to home directory
|
||||
2. Check if absolute path → use as-is
|
||||
3. Otherwise → resolve relative to repo root (`Instance.worktree`)
|
||||
4. If not found → look for agent with that name
|
||||
|
||||
#### Implications for Installation
|
||||
|
||||
**Local Installation (in repo):**
|
||||
```
|
||||
Repo structure:
|
||||
.opencode/
|
||||
├── agent/security/scanner.md
|
||||
└── context/security/patterns.md
|
||||
|
||||
Reference: @.opencode/context/security/patterns.md
|
||||
Resolution: {repo-root}/.opencode/context/security/patterns.md ✅
|
||||
```
|
||||
|
||||
**Global Installation:**
|
||||
```
|
||||
Global structure:
|
||||
~/.config/opencode/
|
||||
├── agent/security/scanner.md
|
||||
└── context/security/patterns.md
|
||||
|
||||
Reference: @.opencode/context/security/patterns.md
|
||||
Resolution: Tries to find .opencode/ relative to... what? ❌
|
||||
Problem: No "repo root" for global agents!
|
||||
```
|
||||
|
||||
### 🎯 Path Pattern Testing
|
||||
|
||||
#### Test Setup
|
||||
|
||||
Created global test agent with three path patterns:
|
||||
|
||||
```markdown
|
||||
# Pattern 1: With .opencode prefix
|
||||
@.opencode/context/test/global-test-data.md
|
||||
|
||||
# Pattern 2: Without .opencode prefix
|
||||
@context/test/global-test-data.md
|
||||
|
||||
# Pattern 3: Explicit home path
|
||||
@~/.config/opencode/context/test/global-test-data.md
|
||||
```
|
||||
|
||||
#### Expected Results (Based on Documentation)
|
||||
|
||||
| Pattern | Local Install | Global Install | Notes |
|
||||
|---------|--------------|----------------|-------|
|
||||
| `@.opencode/context/file.md` | ✅ Works | ❌ Fails | No .opencode in global path |
|
||||
| `@context/file.md` | ❌ Fails | ❓ Unknown | Might resolve to ~/.config/opencode/context/ |
|
||||
| `@~/.config/opencode/context/file.md` | ❌ Fails | ✅ Works | Explicit path, but breaks local |
|
||||
|
||||
#### Critical Issue
|
||||
|
||||
**No single path pattern works for both local AND global installations!**
|
||||
|
||||
This confirms our installation script approach is necessary.
|
||||
|
||||
### ✅ Validated Assumptions
|
||||
|
||||
1. ✅ **Global path is `~/.config/opencode/`** - Confirmed
|
||||
2. ✅ **Local path is `.opencode/`** - Confirmed
|
||||
3. ✅ **Path transformation is required** - Confirmed (no universal pattern)
|
||||
4. ✅ **Context folder structure works** - Confirmed (exists in current repo)
|
||||
|
||||
### ❌ Invalidated Assumptions
|
||||
|
||||
1. ❌ **`@context/file.md` might work universally** - Unconfirmed, likely fails locally
|
||||
2. ❌ **Current agents use `@` references** - They don't (different loading mechanism)
|
||||
|
||||
### 🔧 Installation Strategy Confirmation
|
||||
|
||||
#### Source Code Convention
|
||||
|
||||
**All context references MUST use:**
|
||||
```markdown
|
||||
@.opencode/context/{category}/{file}.md
|
||||
```
|
||||
|
||||
#### Installation Script Transformation
|
||||
|
||||
**Local Installation:**
|
||||
- Keep references as-is: `@.opencode/context/...`
|
||||
- Copy to: `{repo}/.opencode/`
|
||||
|
||||
**Global Installation:**
|
||||
- Transform: `@.opencode/context/` → `@~/.config/opencode/context/`
|
||||
- Copy to: `~/.config/opencode/`
|
||||
|
||||
#### Transformation Rules
|
||||
|
||||
```bash
|
||||
# For global installation
|
||||
sed 's|@\.opencode/context/|@~/.config/opencode/context/|g'
|
||||
|
||||
# Also transform shell commands
|
||||
sed 's|\.opencode/context/|~/.config/opencode/context/|g'
|
||||
```
|
||||
|
||||
### 🚨 Additional Considerations
|
||||
|
||||
#### Shell Commands in Templates
|
||||
|
||||
**Problem:** Commands like `!`ls .opencode/context/`` also need transformation
|
||||
|
||||
**Solution:** Transform both `@` references AND bare paths in shell commands
|
||||
|
||||
#### Context Cross-References
|
||||
|
||||
**Problem:** Context files may reference other context files
|
||||
|
||||
**Solution:** Transform context files too, not just agents/commands
|
||||
|
||||
#### Platform Compatibility
|
||||
|
||||
**macOS/Linux:** `~/.config/opencode/` ✅
|
||||
**Windows:** Need to verify (likely `%APPDATA%\opencode` or similar)
|
||||
|
||||
### 📝 Recommendations
|
||||
|
||||
1. **Proceed with Installation Script Approach** - The two-tier distribution with path transformation is necessary and correct
|
||||
2. **Strict Convention Enforcement** - Create validation script to ensure all references follow `@.opencode/context/` pattern
|
||||
3. **Transform All File Types** - Agent files, command files, AND context files
|
||||
4. **Test on Actual OpenCode Installation** - Runtime testing would confirm edge cases
|
||||
5. **Platform-Specific Paths** - Verify global paths on Windows before production release
|
||||
|
|
|
|||
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