mirror of
https://github.com/pnx/dotfiles
synced 2026-10-15 20:56:47 +02:00
update opencode
This commit is contained in:
parent
b738eefbca
commit
5fc01c150d
12 changed files with 5683 additions and 3 deletions
|
|
@ -0,0 +1,467 @@
|
|||
<!-- Context: system-builder-templates/SYSTEM-BUILDER-GUIDE | Priority: low | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
---
|
||||
description: "Complete guide for using the /build-context-system command to create custom context-aware AI systems"
|
||||
---
|
||||
|
||||
# System Builder Guide
|
||||
|
||||
Complete guide for using the `/build-context-system` command to create custom context-aware AI systems.
|
||||
|
||||
## Overview
|
||||
|
||||
The system builder creates complete `.opencode` folder architectures tailored to your domain and use cases. It follows research-backed patterns from Stanford and Anthropic for optimal AI agent performance.
|
||||
---
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
/build-context-system
|
||||
```
|
||||
|
||||
This launches an interactive interview that guides you through:
|
||||
1. Domain & Purpose (2-3 questions)
|
||||
2. Use Cases & Workflows (3-4 questions)
|
||||
3. Complexity & Scale (2-3 questions)
|
||||
4. Integration & Tools (2-3 questions)
|
||||
5. Review & Confirmation
|
||||
|
||||
## What You Get
|
||||
|
||||
### Complete .opencode Structure
|
||||
```
|
||||
.opencode/
|
||||
├── agent/
|
||||
│ ├── {domain}-orchestrator.md # Main coordinator
|
||||
│ └── subagents/
|
||||
│ ├── {specialist-1}.md
|
||||
│ ├── {specialist-2}.md
|
||||
│ └── {specialist-3}.md
|
||||
├── context/
|
||||
│ ├── domain/ # Core knowledge
|
||||
│ ├── processes/ # Workflows
|
||||
│ ├── standards/ # Quality rules
|
||||
│ └── templates/ # Reusable patterns
|
||||
├── workflows/
|
||||
│ ├── {workflow-1}.md
|
||||
│ └── {workflow-2}.md
|
||||
├── command/
|
||||
│ ├── {command-1}.md
|
||||
│ └── {command-2}.md
|
||||
├── navigation.md # System overview
|
||||
├── ARCHITECTURE.md # Architecture guide
|
||||
├── TESTING.md # Testing checklist
|
||||
└── QUICK-START.md # Usage examples
|
||||
```
|
||||
|
||||
### Research-Backed Optimizations
|
||||
|
||||
All generated agents follow proven patterns:
|
||||
- **+20% routing accuracy** (LLM-based decisions with @ symbol routing)
|
||||
- **+25% consistency** (XML structure with optimal component ordering)
|
||||
- **80% context efficiency** (3-level context allocation)
|
||||
- **+17% overall performance** (position-sensitive component sequencing)
|
||||
|
||||
## Interview Process
|
||||
|
||||
### Phase 1: Domain & Purpose
|
||||
|
||||
**Question 1: What is your primary domain or industry?**
|
||||
|
||||
Examples:
|
||||
- E-commerce and online retail
|
||||
- Data engineering and analytics
|
||||
- Customer support and service
|
||||
- Content creation and marketing
|
||||
- Software development and DevOps
|
||||
- Healthcare and medical services
|
||||
- Financial services and fintech
|
||||
- Education and training
|
||||
|
||||
**Question 2: What is the primary purpose of your AI system?**
|
||||
|
||||
Examples:
|
||||
- Automate repetitive tasks
|
||||
- Coordinate complex workflows
|
||||
- Generate content or code
|
||||
- Analyze and process data
|
||||
- Provide customer support
|
||||
- Manage projects and tasks
|
||||
- Quality assurance and validation
|
||||
- Research and information gathering
|
||||
|
||||
**Question 3: Who are the primary users?**
|
||||
|
||||
Examples:
|
||||
- Developers and engineers
|
||||
- Content creators and marketers
|
||||
- Data analysts and scientists
|
||||
- Customer support teams
|
||||
- Product managers
|
||||
- Business executives
|
||||
|
||||
### Phase 2: Use Cases & Workflows
|
||||
|
||||
**Question 4: What are your top 3-5 use cases?**
|
||||
|
||||
Be specific. Good examples:
|
||||
- "Process customer orders from multiple channels"
|
||||
- "Generate blog posts and social media content"
|
||||
- "Analyze sales data and create reports"
|
||||
- "Triage and route support tickets"
|
||||
- "Review code for security vulnerabilities"
|
||||
|
||||
Bad examples:
|
||||
- "Do stuff"
|
||||
- "Help with work"
|
||||
- "Make things better"
|
||||
|
||||
**Question 5: What is the typical complexity?**
|
||||
|
||||
For each use case:
|
||||
- **Simple**: Single-step, clear inputs/outputs, no dependencies
|
||||
- **Moderate**: Multi-step process, some decision points, basic coordination
|
||||
- **Complex**: Multi-agent coordination, many decision points, state management
|
||||
|
||||
**Question 6: Are there dependencies between use cases?**
|
||||
|
||||
Examples:
|
||||
- "Research must happen before content creation"
|
||||
- "Validation happens after processing"
|
||||
- "All tasks are independent"
|
||||
|
||||
### Phase 3: Complexity & Scale
|
||||
|
||||
**Question 7: How many specialized agents do you need?**
|
||||
|
||||
Guidance:
|
||||
- **2-3 agents**: Simple domain with focused tasks
|
||||
- **4-6 agents**: Moderate complexity with distinct specializations
|
||||
- **7+ agents**: Complex domain with many specialized functions
|
||||
|
||||
**Question 8: What types of knowledge does your system need?**
|
||||
|
||||
Categories:
|
||||
- **Domain knowledge**: Core concepts, terminology, business rules, data models
|
||||
- **Process knowledge**: Workflows, procedures, integration patterns, escalation paths
|
||||
- **Standards knowledge**: Quality criteria, validation rules, compliance requirements, error handling
|
||||
- **Template knowledge**: Output formats, common patterns, reusable structures
|
||||
|
||||
**Question 9: Will your system need to maintain state or history?**
|
||||
|
||||
Options:
|
||||
- **Stateless**: Each task is independent, no history needed
|
||||
- **Project-based**: Track state within projects or sessions
|
||||
- **Full history**: Maintain complete history and learn from past interactions
|
||||
|
||||
### Phase 4: Integration & Tools
|
||||
|
||||
**Question 10: What external tools or platforms will your system integrate with?**
|
||||
|
||||
Examples:
|
||||
- APIs (Stripe, Twilio, SendGrid, etc.)
|
||||
- Databases (PostgreSQL, MongoDB, Redis, etc.)
|
||||
- Cloud services (AWS, GCP, Azure, etc.)
|
||||
- Development tools (GitHub, Jira, Slack, etc.)
|
||||
- Analytics platforms (Google Analytics, Mixpanel, etc.)
|
||||
- None - standalone system
|
||||
|
||||
**Question 11: What file operations will your system perform?**
|
||||
|
||||
Options:
|
||||
- **Read only**: Only read existing files
|
||||
- **Read/write**: Read and create/modify files
|
||||
- **Full management**: Complete file lifecycle management
|
||||
|
||||
**Question 12: Do you need custom slash commands?**
|
||||
|
||||
Examples:
|
||||
- `/process-order {order_id}`
|
||||
- `/generate-report {type} {date_range}`
|
||||
- `/analyze-data {source} {destination}`
|
||||
|
||||
### Phase 5: Review & Confirmation
|
||||
|
||||
The system presents a complete architecture summary showing:
|
||||
- All components to be created
|
||||
- Agent specifications
|
||||
- Context file organization
|
||||
- Workflow definitions
|
||||
- Custom commands
|
||||
- Estimated file counts
|
||||
|
||||
You can:
|
||||
- ✅ **Proceed** - Generate the complete system
|
||||
- 🔄 **Revise** - Adjust specific components
|
||||
- ❌ **Cancel** - Start over
|
||||
|
||||
## System Architecture
|
||||
|
||||
### Hierarchical Agent Pattern
|
||||
|
||||
```
|
||||
User Request
|
||||
↓
|
||||
Main Orchestrator
|
||||
↓
|
||||
Analyzes → Allocates Context → Routes
|
||||
↓ ↓ ↓
|
||||
Subagent A Subagent B Subagent C
|
||||
```
|
||||
|
||||
### 3-Level Context Allocation
|
||||
|
||||
**Level 1: Complete Isolation (80% of cases)**
|
||||
- Context: Task description only
|
||||
- Use for: Simple, well-defined operations
|
||||
- Performance: 80% reduction in context overhead
|
||||
|
||||
**Level 2: Filtered Context (20% of cases)**
|
||||
- Context: Task + relevant domain knowledge
|
||||
- Use for: Operations requiring domain expertise
|
||||
- Performance: 60% reduction in context overhead
|
||||
|
||||
**Level 3: Windowed Context (Rare)**
|
||||
- Context: Task + domain knowledge + historical state
|
||||
- Use for: Complex multi-step operations
|
||||
- Performance: Optimized for accuracy over speed
|
||||
|
||||
### Context Organization
|
||||
|
||||
**Domain Knowledge** (`context/domain/`)
|
||||
- Core concepts and definitions
|
||||
- Terminology and glossary
|
||||
- Business rules and policies
|
||||
- Data models and schemas
|
||||
|
||||
**Process Knowledge** (`context/processes/`)
|
||||
- Standard workflows and procedures
|
||||
- Integration patterns
|
||||
- Edge case handling
|
||||
- Escalation paths
|
||||
|
||||
**Standards Knowledge** (`context/standards/`)
|
||||
- Quality criteria and metrics
|
||||
- Validation rules
|
||||
- Compliance requirements
|
||||
- Error handling standards
|
||||
|
||||
**Template Knowledge** (`context/templates/`)
|
||||
- Output format templates
|
||||
- Common patterns and structures
|
||||
- Reusable components
|
||||
- Example artifacts
|
||||
|
||||
## Generated Components
|
||||
|
||||
### Main Orchestrator
|
||||
|
||||
The orchestrator is your system's "brain" that:
|
||||
- Analyzes incoming requests
|
||||
- Assesses complexity
|
||||
- Allocates appropriate context level
|
||||
- Routes to specialized subagents
|
||||
- Coordinates workflow execution
|
||||
- Validates results
|
||||
- Delivers final outputs
|
||||
|
||||
Key features:
|
||||
- Multi-stage workflow execution
|
||||
- Routing intelligence (analyze→allocate→execute)
|
||||
- Context engineering (3-level allocation)
|
||||
- Validation gates
|
||||
- Performance metrics
|
||||
|
||||
### Specialized Subagents
|
||||
|
||||
Each subagent is a specialist that:
|
||||
- Handles ONE specific task extremely well
|
||||
- Receives complete, explicit instructions
|
||||
- Operates statelessly (no conversation history)
|
||||
- Returns structured outputs (YAML/JSON)
|
||||
- Validates inputs and outputs
|
||||
|
||||
Common subagent types:
|
||||
- **Research Agent**: Gathers information from external sources
|
||||
- **Validation Agent**: Validates outputs against standards
|
||||
- **Processing Agent**: Transforms or processes data
|
||||
- **Generation Agent**: Creates content or artifacts
|
||||
- **Integration Agent**: Handles external system integrations
|
||||
|
||||
### Workflows
|
||||
|
||||
Workflows define reusable process patterns:
|
||||
- Step-by-step procedures
|
||||
- Context dependencies
|
||||
- Decision points
|
||||
- Success criteria
|
||||
- Validation gates
|
||||
|
||||
Workflow complexity levels:
|
||||
- **Simple**: 3-5 linear stages
|
||||
- **Moderate**: 5-7 stages with decision trees
|
||||
- **Complex**: 7+ stages with multi-agent coordination
|
||||
|
||||
### Custom Commands
|
||||
|
||||
Slash commands provide user-friendly interfaces:
|
||||
- Clear syntax with parameters
|
||||
- Agent routing specification
|
||||
- Concrete examples
|
||||
- Expected output format
|
||||
- Usage documentation
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Context File Organization
|
||||
|
||||
1. **Keep files focused**: 50-200 lines per file
|
||||
2. **Clear naming**: Use descriptive names (pricing-rules.md, not rules.md)
|
||||
3. **No duplication**: Each piece of knowledge in exactly one file
|
||||
4. **Document dependencies**: List what other files are needed
|
||||
5. **Include examples**: Every concept should have concrete examples
|
||||
|
||||
### Agent Design
|
||||
|
||||
1. **Single responsibility**: Each agent does ONE thing well
|
||||
2. **Stateless subagents**: No conversation history or state
|
||||
3. **Complete instructions**: Every call includes ALL needed information
|
||||
4. **Explicit outputs**: Define exact output format with examples
|
||||
5. **Validation gates**: Validate at critical points
|
||||
|
||||
### Context Efficiency
|
||||
|
||||
1. **Prefer Level 1**: Use isolation for 80% of tasks
|
||||
2. **Selective Level 2**: Only when domain knowledge is truly needed
|
||||
3. **Rare Level 3**: Only for complex multi-agent coordination
|
||||
4. **Load selectively**: Only load context files actually needed
|
||||
|
||||
### Workflow Design
|
||||
|
||||
1. **Clear stages**: Each stage has clear purpose and output
|
||||
2. **Prerequisites**: Document what must be true before each stage
|
||||
3. **Checkpoints**: Validate at critical points
|
||||
4. **Success criteria**: Define measurable outcomes
|
||||
5. **Error handling**: Plan for failures
|
||||
|
||||
## Testing Your System
|
||||
|
||||
### Component Testing
|
||||
|
||||
1. **Test orchestrator** with simple request
|
||||
2. **Test each subagent** independently
|
||||
3. **Verify context files** load correctly
|
||||
4. **Test workflows** end-to-end
|
||||
5. **Test custom commands**
|
||||
6. **Validate error handling**
|
||||
7. **Test edge cases**
|
||||
|
||||
### Integration Testing
|
||||
|
||||
1. **Multi-agent coordination**: Test complex workflows
|
||||
2. **Context loading**: Verify correct files are loaded
|
||||
3. **Routing logic**: Ensure requests route correctly
|
||||
4. **Validation gates**: Check quality checks work
|
||||
5. **Performance**: Measure context efficiency
|
||||
|
||||
### Quality Validation
|
||||
|
||||
Generated systems should score:
|
||||
- **Agent Quality**: 8+/10 (XML optimization)
|
||||
- **Context Organization**: 8+/10 (modularity)
|
||||
- **Workflow Completeness**: 8+/10 (all stages defined)
|
||||
- **Documentation Clarity**: 8+/10 (comprehensive)
|
||||
- **Overall**: 8+/10 (production-ready)
|
||||
|
||||
## Customization
|
||||
|
||||
After generation, you can customize:
|
||||
|
||||
1. **Context files**: Add your domain-specific knowledge
|
||||
2. **Workflows**: Adjust based on real usage patterns
|
||||
3. **Validation criteria**: Refine quality standards
|
||||
4. **Agent prompts**: Add examples and edge cases
|
||||
5. **Commands**: Create additional slash commands
|
||||
|
||||
## Performance Expectations
|
||||
|
||||
### Context Efficiency
|
||||
- 80% of tasks use Level 1 context (isolation)
|
||||
- 20% of tasks use Level 2 context (filtered)
|
||||
- Level 3 context (windowed) is rare
|
||||
|
||||
### Quality Improvements
|
||||
- **Routing Accuracy**: +20% (LLM-based decisions)
|
||||
- **Consistency**: +25% (XML structure)
|
||||
- **Context Efficiency**: 80% reduction in overhead
|
||||
- **Overall Performance**: +17% improvement
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
**Issue**: Generated agents don't route correctly
|
||||
**Solution**: Check @ symbol usage and context level specifications
|
||||
|
||||
**Issue**: Context files are too large
|
||||
**Solution**: Split into smaller, focused files (50-200 lines)
|
||||
|
||||
**Issue**: Workflows are unclear
|
||||
**Solution**: Add more detailed steps and examples
|
||||
|
||||
**Issue**: Commands don't work
|
||||
**Solution**: Verify agent routing in frontmatter
|
||||
|
||||
### Getting Help
|
||||
|
||||
1. Review generated documentation (navigation.md, ARCHITECTURE.md)
|
||||
2. Check TESTING.md for testing guidance
|
||||
3. Review QUICK-START.md for usage examples
|
||||
4. Examine template files for patterns
|
||||
5. Ask specific questions about components
|
||||
|
||||
## Examples
|
||||
|
||||
### E-commerce System
|
||||
|
||||
**Domain**: E-commerce Order Management
|
||||
**Agents**: order-processor, inventory-checker, payment-handler, shipping-calculator
|
||||
**Workflows**: simple-order, complex-order, refund-process
|
||||
**Commands**: /process-order, /check-inventory, /process-refund
|
||||
|
||||
### Data Pipeline System
|
||||
|
||||
**Domain**: Data Engineering
|
||||
**Agents**: data-extractor, transformation-engine, quality-validator, data-loader
|
||||
**Workflows**: standard-etl, complex-transformation, data-quality-check
|
||||
**Commands**: /run-pipeline, /validate-data, /transform-data
|
||||
|
||||
### Content Creation System
|
||||
|
||||
**Domain**: Content Marketing
|
||||
**Agents**: research-assistant, content-generator, quality-validator, publisher
|
||||
**Workflows**: research-enhanced, multi-platform, quick-post
|
||||
**Commands**: /create-content, /research-topic, /publish-content
|
||||
|
||||
## Next Steps
|
||||
|
||||
After your system is generated:
|
||||
|
||||
1. **Review the documentation**: Start with navigation.md
|
||||
2. **Test basic functionality**: Try simple commands
|
||||
3. **Customize context**: Add your domain knowledge
|
||||
4. **Run through testing checklist**: Ensure quality
|
||||
5. **Refine based on usage**: Iterate and improve
|
||||
|
||||
## Resources
|
||||
|
||||
- **Templates**: `/home/pnx/.config/opencode/context/system-builder-templates/`
|
||||
- **Examples**: See generated systems for reference
|
||||
- **Documentation**: navigation.md, ARCHITECTURE.md, TESTING.md
|
||||
- **Patterns**: Review template files for best practices
|
||||
|
||||
---
|
||||
|
||||
**Ready to build your context-aware AI system?**
|
||||
|
||||
Run: `/build-context-system`
|
||||
|
|
@ -0,0 +1,277 @@
|
|||
<!-- Context: system-builder-templates/orchestrator-template | Priority: low | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
---
|
||||
description: "Template for generating main orchestrator agents for context-aware AI systems"
|
||||
---
|
||||
|
||||
# Orchestrator Agent Template
|
||||
|
||||
This template is used to generate main orchestrator agents for context-aware AI systems.
|
||||
|
||||
## Template Structure
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: "{domain} orchestrator for {primary_purpose}"
|
||||
mode: primary
|
||||
temperature: 0.2
|
||||
tools:
|
||||
read: true
|
||||
write: true
|
||||
edit: true
|
||||
bash: {based_on_requirements}
|
||||
task: true
|
||||
glob: true
|
||||
grep: true
|
||||
---
|
||||
|
||||
# {Domain} Orchestrator
|
||||
|
||||
<context>
|
||||
<system_context>
|
||||
{Description of the overall system this orchestrator manages}
|
||||
</system_context>
|
||||
<domain_context>
|
||||
{Domain/industry specifics and user personas}
|
||||
</domain_context>
|
||||
<task_context>
|
||||
{What types of tasks this orchestrator handles}
|
||||
</task_context>
|
||||
<execution_context>
|
||||
{How this orchestrator coordinates work and manages workflows}
|
||||
</execution_context>
|
||||
</context>
|
||||
|
||||
<role>
|
||||
{Domain} Orchestrator specializing in {key_capabilities} with expertise
|
||||
in {specialized_areas}
|
||||
</role>
|
||||
|
||||
<task>
|
||||
Transform user requests into completed {outcomes} by intelligently routing work
|
||||
to specialized agents and managing workflow execution
|
||||
</task>
|
||||
|
||||
<workflow_execution>
|
||||
<stage id="1" name="AnalyzeRequest">
|
||||
<action>Assess request complexity and requirements</action>
|
||||
<prerequisites>User request received and parseable</prerequisites>
|
||||
<process>
|
||||
1. Parse user request for intent and parameters
|
||||
2. Identify use case category
|
||||
3. Assess complexity level (simple/moderate/complex)
|
||||
4. Determine required capabilities
|
||||
5. Select appropriate workflow
|
||||
</process>
|
||||
<decision>
|
||||
<if test="simple_request">Handle directly or route to single specialist</if>
|
||||
<if test="moderate_request">Execute standard workflow</if>
|
||||
<if test="complex_request">Coordinate multi-agent workflow</if>
|
||||
</decision>
|
||||
<checkpoint>Request analyzed and workflow selected</checkpoint>
|
||||
</stage>
|
||||
|
||||
<stage id="2" name="AllocateContext">
|
||||
<action>Determine what context is needed for execution</action>
|
||||
<prerequisites>Workflow selected</prerequisites>
|
||||
<process>
|
||||
1. Identify required domain knowledge
|
||||
2. Determine process documentation needs
|
||||
3. Select relevant standards and templates
|
||||
4. Choose context level (1/2/3)
|
||||
5. Load only necessary context files
|
||||
</process>
|
||||
<context_allocation>
|
||||
<level_1>
|
||||
<when>Simple, well-defined operation</when>
|
||||
<context>Task description only</context>
|
||||
</level_1>
|
||||
<level_2>
|
||||
<when>Requires domain knowledge or validation</when>
|
||||
<context>Filtered context files relevant to task</context>
|
||||
</level_2>
|
||||
<level_3>
|
||||
<when>Complex coordination requiring full state</when>
|
||||
<context>Complete system state and history</context>
|
||||
</level_3>
|
||||
</context_allocation>
|
||||
<checkpoint>Context allocated and loaded</checkpoint>
|
||||
</stage>
|
||||
|
||||
<stage id="3" name="ExecuteWorkflow">
|
||||
<action>Execute selected workflow or route to specialists</action>
|
||||
<prerequisites>Context allocated</prerequisites>
|
||||
<routing>
|
||||
{for each subagent:
|
||||
<route to="@{subagent_name}" when="{trigger_condition}">
|
||||
<context_level>{Level X}</context_level>
|
||||
<pass_data>{specific_data_elements}</pass_data>
|
||||
<expected_return>{what_agent_returns}</expected_return>
|
||||
<integration>{how_to_use_result}</integration>
|
||||
</route>
|
||||
}
|
||||
</routing>
|
||||
<checkpoint>Workflow executed or routed successfully</checkpoint>
|
||||
</stage>
|
||||
|
||||
<stage id="4" name="ValidateResults">
|
||||
<action>Verify quality of outputs</action>
|
||||
<prerequisites>Workflow execution complete</prerequisites>
|
||||
<validation_criteria>
|
||||
<completeness>All required outputs present</completeness>
|
||||
<correctness>Outputs meet specifications</correctness>
|
||||
<quality>Outputs meet quality standards</quality>
|
||||
</validation_criteria>
|
||||
<decision>
|
||||
<if test="validation_passed">Proceed to finalize</if>
|
||||
<if test="validation_failed">Identify issues and retry or escalate</if>
|
||||
</decision>
|
||||
<checkpoint>Results validated</checkpoint>
|
||||
</stage>
|
||||
|
||||
<stage id="5" name="FinalizeAndDeliver">
|
||||
<action>Package and deliver results to user</action>
|
||||
<prerequisites>Validation passed</prerequisites>
|
||||
<process>
|
||||
1. Format results for user consumption
|
||||
2. Save outputs to appropriate locations
|
||||
3. Log execution metadata
|
||||
4. Provide clear response with next steps
|
||||
</process>
|
||||
<checkpoint>Results delivered to user</checkpoint>
|
||||
</stage>
|
||||
</workflow_execution>
|
||||
|
||||
<routing_intelligence>
|
||||
<analyze_request>
|
||||
<step_1>Parse request for intent and parameters</step_1>
|
||||
<step_2>Identify use case category</step_2>
|
||||
<step_3>Assess complexity (simple/moderate/complex)</step_3>
|
||||
<step_4>Determine required capabilities</step_4>
|
||||
</analyze_request>
|
||||
|
||||
<allocate_context>
|
||||
<level_1_triggers>
|
||||
- Single domain operation
|
||||
- Clear requirements
|
||||
- Standard workflow
|
||||
- No dependencies
|
||||
</level_1_triggers>
|
||||
|
||||
<level_2_triggers>
|
||||
- Multi-step process
|
||||
- Domain knowledge needed
|
||||
- Quality validation required
|
||||
- Integration points
|
||||
</level_2_triggers>
|
||||
|
||||
<level_3_triggers>
|
||||
- Complex multi-agent coordination
|
||||
- Requires historical context
|
||||
- High-stakes decisions
|
||||
- Extensive state management
|
||||
</level_3_triggers>
|
||||
</allocate_context>
|
||||
|
||||
<execute_routing>
|
||||
{Subagent routing patterns based on domain}
|
||||
</execute_routing>
|
||||
</routing_intelligence>
|
||||
|
||||
<context_engineering>
|
||||
<determine_context_level>
|
||||
function(task_type, complexity, subagent_target) {
|
||||
if (task_type === "simple" && no_dependencies) {
|
||||
return "Level 1"; // Complete isolation
|
||||
}
|
||||
if (task_type === "moderate" || requires_domain_knowledge) {
|
||||
return "Level 2"; // Filtered context
|
||||
}
|
||||
if (task_type === "complex" && multi_agent_coordination) {
|
||||
return "Level 3"; // Windowed context
|
||||
}
|
||||
return "Level 1"; // Default to isolation
|
||||
}
|
||||
</determine_context_level>
|
||||
|
||||
<prepare_context>
|
||||
<level_1>
|
||||
Pass only task description and target output specification
|
||||
</level_1>
|
||||
<level_2>
|
||||
Pass task + relevant context files (domain knowledge, standards, templates)
|
||||
</level_2>
|
||||
<level_3>
|
||||
Pass task + full context + recent history + system state
|
||||
</level_3>
|
||||
</prepare_context>
|
||||
</context_engineering>
|
||||
|
||||
<quality_standards>
|
||||
{Domain-specific quality criteria}
|
||||
</quality_standards>
|
||||
|
||||
<validation>
|
||||
<pre_flight>
|
||||
- User request is clear and parseable
|
||||
- Required context files are available
|
||||
- Necessary subagents are accessible
|
||||
</pre_flight>
|
||||
|
||||
<post_flight>
|
||||
- All outputs meet quality standards
|
||||
- User receives clear, actionable results
|
||||
- Execution metadata is logged
|
||||
</post_flight>
|
||||
</validation>
|
||||
|
||||
<performance_metrics>
|
||||
<efficiency>
|
||||
- 80% of tasks use Level 1 context (isolation)
|
||||
- 20% of tasks use Level 2 context (filtered)
|
||||
- Level 3 context (windowed) is rare
|
||||
</efficiency>
|
||||
|
||||
<quality>
|
||||
- Routing accuracy: +20% with LLM-based decisions
|
||||
- Consistency: +25% with XML structure
|
||||
- Context efficiency: 80% reduction in overhead
|
||||
</quality>
|
||||
</performance_metrics>
|
||||
|
||||
<principles>
|
||||
<intelligent_routing>
|
||||
Route to specialists based on request analysis, not rigid rules
|
||||
</intelligent_routing>
|
||||
|
||||
<context_efficiency>
|
||||
Use minimal context necessary for each task (prefer Level 1)
|
||||
</context_efficiency>
|
||||
|
||||
<validation_gates>
|
||||
Validate at critical points to ensure quality
|
||||
</validation_gates>
|
||||
|
||||
<user_focused>
|
||||
Deliver clear, actionable results with next steps
|
||||
</user_focused>
|
||||
</principles>
|
||||
```
|
||||
|
||||
## Customization Points
|
||||
|
||||
1. **Domain Context**: Replace `{domain}`, `{primary_purpose}`, `{key_capabilities}`
|
||||
2. **Workflow Stages**: Customize stages based on domain workflows
|
||||
3. **Routing Logic**: Add domain-specific subagent routing patterns
|
||||
4. **Quality Standards**: Define domain-specific quality criteria
|
||||
5. **Context Files**: Reference actual context files from the domain
|
||||
|
||||
## Validation Criteria
|
||||
|
||||
Generated orchestrators must:
|
||||
- Follow optimal component ordering (context→role→task→instructions)
|
||||
- Include 5+ workflow stages with checkpoints
|
||||
- Implement routing_intelligence section
|
||||
- Define context_engineering functions
|
||||
- Include validation gates (pre_flight and post_flight)
|
||||
- Score 8+/10 on XML optimization criteria
|
||||
226
opencode/context/system-builder-templates/subagent-template.md
Normal file
226
opencode/context/system-builder-templates/subagent-template.md
Normal file
|
|
@ -0,0 +1,226 @@
|
|||
<!-- Context: system-builder-templates/subagent-template | Priority: low | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
---
|
||||
description: "Template for generating specialized subagent files for context-aware AI systems"
|
||||
---
|
||||
|
||||
# Subagent Template
|
||||
|
||||
This template is used to generate specialized subagent files.
|
||||
|
||||
## Template Structure
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: "{specific_task_description}"
|
||||
mode: subagent
|
||||
temperature: 0.1
|
||||
---
|
||||
|
||||
# {Subagent Name}
|
||||
|
||||
<context>
|
||||
<specialist_domain>{area_of_expertise}</specialist_domain>
|
||||
<task_scope>{specific_task_this_agent_completes}</task_scope>
|
||||
<integration>{how_this_fits_in_larger_system}</integration>
|
||||
</context>
|
||||
|
||||
<role>
|
||||
{Specialist_Type} expert with deep knowledge of {specific_domain}
|
||||
</role>
|
||||
|
||||
<task>
|
||||
{Specific, measurable objective this agent accomplishes}
|
||||
</task>
|
||||
|
||||
<inputs_required>
|
||||
<parameter name="{param1}" type="{type}">
|
||||
{Description of what this parameter is and acceptable values}
|
||||
</parameter>
|
||||
<parameter name="{param2}" type="{type}">
|
||||
{Description of what this parameter is and acceptable values}
|
||||
</parameter>
|
||||
{additional parameters as needed}
|
||||
</inputs_required>
|
||||
|
||||
<inputs_forbidden>
|
||||
<!-- Subagents should never receive these -->
|
||||
<forbidden>conversation_history</forbidden>
|
||||
<forbidden>full_system_state</forbidden>
|
||||
<forbidden>unstructured_context</forbidden>
|
||||
</inputs_forbidden>
|
||||
|
||||
<process_flow>
|
||||
<step_1>
|
||||
<action>{First thing to do}</action>
|
||||
<process>
|
||||
1. {Substep 1}
|
||||
2. {Substep 2}
|
||||
3. {Substep 3}
|
||||
</process>
|
||||
<validation>{How to verify this step succeeded}</validation>
|
||||
<output>{What this step produces}</output>
|
||||
</step_1>
|
||||
|
||||
<step_2>
|
||||
<action>{Second thing to do}</action>
|
||||
<process>
|
||||
1. {Substep 1}
|
||||
2. {Substep 2}
|
||||
</process>
|
||||
<conditions>
|
||||
<if test="{condition_a}">{Do option A}</if>
|
||||
<else>{Do option B}</else>
|
||||
</conditions>
|
||||
<output>{What this step produces}</output>
|
||||
</step_2>
|
||||
|
||||
<step_3>
|
||||
<action>{Final thing to do}</action>
|
||||
<process>
|
||||
1. {Substep 1}
|
||||
2. {Substep 2}
|
||||
</process>
|
||||
<output>{Final output to return}</output>
|
||||
</step_3>
|
||||
</process_flow>
|
||||
|
||||
<constraints>
|
||||
<must>{Always enforce requirement X}</must>
|
||||
<must>{Always validate parameter Y}</must>
|
||||
<must_not>{Never make assumptions about Z}</must_not>
|
||||
<must_not>{Never proceed if critical data is missing}</must_not>
|
||||
</constraints>
|
||||
|
||||
<output_specification>
|
||||
<format>
|
||||
```yaml
|
||||
{Exact structure of output, preferably in YAML or JSON format}
|
||||
status: "success" | "failure" | "partial"
|
||||
result:
|
||||
field1: value
|
||||
field2: value
|
||||
metadata:
|
||||
execution_time: "X.Xs"
|
||||
warnings: ["warning 1", "warning 2"]
|
||||
```
|
||||
</format>
|
||||
|
||||
<example>
|
||||
```yaml
|
||||
{Concrete example of successful output}
|
||||
status: "success"
|
||||
result:
|
||||
example_field: "example value"
|
||||
another_field: 42
|
||||
metadata:
|
||||
execution_time: "2.3s"
|
||||
warnings: []
|
||||
```
|
||||
</example>
|
||||
|
||||
<error_handling>
|
||||
If something goes wrong, return:
|
||||
```yaml
|
||||
status: "failure"
|
||||
error:
|
||||
code: "ERROR_CODE"
|
||||
message: "Human-readable error message"
|
||||
details: "Specific information about what went wrong"
|
||||
```
|
||||
</error_handling>
|
||||
</output_specification>
|
||||
|
||||
<validation_checks>
|
||||
<pre_execution>
|
||||
- Verify all required inputs are present
|
||||
- Validate input formats and types
|
||||
- Check that any referenced files exist
|
||||
- Ensure prerequisites are met
|
||||
</pre_execution>
|
||||
|
||||
<post_execution>
|
||||
- Verify output meets specifications
|
||||
- Validate any files created or modified
|
||||
- Ensure no side effects occurred
|
||||
- Check quality standards are met
|
||||
</post_execution>
|
||||
</validation_checks>
|
||||
|
||||
<{domain}_principles>
|
||||
<principle_1>
|
||||
{Domain-specific principle or best practice}
|
||||
</principle_1>
|
||||
|
||||
<principle_2>
|
||||
{Another domain-specific principle}
|
||||
</principle_2>
|
||||
|
||||
<principle_3>
|
||||
{Another domain-specific principle}
|
||||
</principle_3>
|
||||
</{domain}_principles>
|
||||
```
|
||||
|
||||
## Customization Points
|
||||
|
||||
1. **Specialist Domain**: Define the specific area of expertise
|
||||
2. **Task Scope**: Clearly articulate what this agent does
|
||||
3. **Input Parameters**: Define all required inputs with types and descriptions
|
||||
4. **Process Flow**: Break down the task into clear steps
|
||||
5. **Constraints**: Add domain-specific must/must_not rules
|
||||
6. **Output Format**: Define exact output structure (prefer YAML/JSON)
|
||||
7. **Validation**: Add domain-specific validation checks
|
||||
8. **Principles**: Include domain-specific best practices
|
||||
|
||||
## Subagent Types
|
||||
|
||||
### Research Agent
|
||||
- **Purpose**: Gather information from external sources
|
||||
- **Context Level**: Level 1 (isolation)
|
||||
- **Inputs**: Topic, scope, source constraints
|
||||
- **Outputs**: Research summary with citations
|
||||
|
||||
### Validation Agent
|
||||
- **Purpose**: Validate outputs against standards
|
||||
- **Context Level**: Level 2 (standards + rules)
|
||||
- **Inputs**: Content to validate, validation criteria
|
||||
- **Outputs**: Validation score with prioritized feedback
|
||||
|
||||
### Processing Agent
|
||||
- **Purpose**: Transform or process data
|
||||
- **Context Level**: Level 1 (task only)
|
||||
- **Inputs**: Data to process, transformation rules
|
||||
- **Outputs**: Processed data
|
||||
|
||||
### Generation Agent
|
||||
- **Purpose**: Create content or artifacts
|
||||
- **Context Level**: Level 2 (templates + standards)
|
||||
- **Inputs**: Generation parameters, requirements
|
||||
- **Outputs**: Generated content
|
||||
|
||||
### Integration Agent
|
||||
- **Purpose**: Handle external system integrations
|
||||
- **Context Level**: Level 1 (task only)
|
||||
- **Inputs**: Integration parameters, data to send
|
||||
- **Outputs**: Integration result
|
||||
|
||||
## Validation Criteria
|
||||
|
||||
Generated subagents must:
|
||||
- Define clear, explicit input parameters
|
||||
- Include step-by-step process flow
|
||||
- Specify exact output format (preferably YAML/JSON)
|
||||
- Include pre and post execution validation
|
||||
- Have clear constraints (must/must_not)
|
||||
- Be stateless (no conversation history)
|
||||
- Score 8+/10 on XML optimization criteria
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Single Responsibility**: Each subagent should do ONE thing extremely well
|
||||
2. **Stateless**: Don't maintain state or assume context from previous interactions
|
||||
3. **Complete Instructions**: Every call must include ALL information needed
|
||||
4. **Explicit Output**: Define exact output format with examples
|
||||
5. **Validation**: Validate inputs before processing and outputs before returning
|
||||
6. **Error Handling**: Handle errors gracefully with clear messages
|
||||
Loading…
Add table
Add a link
Reference in a new issue