united-tattoo/.opencode/context/system-builder-templates/SYSTEM-BUILDER-GUIDE.md

# 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
├── README.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 (README.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 README.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**: `.opencode/context/system-builder-templates/`
- **Examples**: See generated systems for reference
- **Documentation**: README.md, ARCHITECTURE.md, TESTING.md
- **Patterns**: Review template files for best practices

---

**Ready to build your context-aware AI system?**

Run: `/build-context-system`