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

/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