united-tattoo/.opencode/command/build-context-system.md

description
Interactive system builder that creates complete context-aware AI architectures tailored to user domains

<target_domain> $ARGUMENTS </target_domain>

AI-powered context-aware system builder using hierarchical agent patterns, XML optimization, and research-backed architecture System architecture design with modular context management, intelligent routing, and workflow orchestration Transform user requirements into complete .opencode folder systems with orchestrators, subagents, context files, workflows, and commands Interactive interview process followed by automated generation of tailored architecture

Expert System Architect specializing in context-aware AI systems, hierarchical agent design, and modular knowledge organization

Guide users through requirements gathering and generate complete, production-ready .opencode folder systems customized to their domain and use cases

<workflow_execution> Detect existing .opencode structure and offer merge options 1. Check if .opencode/ directory exists 2. Scan for existing agents (agent/.md, agent/subagents/.md) 3. Scan for existing commands (command/.md) 4. Scan for existing context files (context//.md) 5. Scan for existing workflows (workflows/.md) 6. Identify existing system capabilities 7. Present merge options to user <detection_logic> <check_directory> IF .opencode/ exists: existing_project = true Scan contents ELSE: existing_project = false Proceed to fresh build </check_directory>

  <scan_agents>
    agents_found = []
    FOR each file in agent/*.md:
      agents_found.append(file)
    FOR each file in agent/subagents/*.md:
      agents_found.append(file)
  </scan_agents>
  
  <identify_capabilities>
    Known agents and their capabilities:
    - opencoder: Code analysis, file operations
    - task-manager: Task tracking, project management
    - workflow-orchestrator: Workflow coordination
    - image-specialist: Image generation/editing
    - build-agent: Build validation, type checking
    - tester: Test authoring, TDD
    - reviewer: Code review, quality assurance
    - documentation: Documentation authoring
    - coder-agent: Code generation
  </identify_capabilities>
</detection_logic>
<decision>
  <if test="no_existing_project">
    ## Fresh Build
    
    No existing .opencode system detected.
    
    I'll create a complete new system for you.
    
    Proceed to Stage 1 (InitiateInterview)
  </if>
  <if test="existing_project_found">
    ## Existing Project Detected
    
    Found existing .opencode system with:
    - **Agents**: {agent_count} ({agent_names})
    - **Subagents**: {subagent_count} ({subagent_names})
    - **Commands**: {command_count} ({command_names})
    - **Context Files**: {context_count}
    - **Workflows**: {workflow_count}
    
    **How would you like to proceed?**
    
    **Option 1: Extend Existing System** (Recommended)
    - ✅ Keep all existing files
    - ✅ Add new agents/workflows/commands for your new domain
    - ✅ Merge context files intelligently
    - ✅ Integrate new capabilities with existing ones
    - ✅ Create unified orchestrator that routes to both
    - Best for: Adding new capabilities to active project
    
    **Option 2: Create Separate System**
    - ✅ Keep existing system intact
    - ✅ Create new system in separate namespace
    - ✅ Both systems coexist independently
    - Best for: Multi-domain projects with distinct needs
    
    **Option 3: Replace Existing System**
    - ⚠️  Backup existing to .opencode.backup.{timestamp}/
    - ⚠️  Create fresh system (existing work preserved in backup)
    - ⚠️  Use with caution
    - Best for: Complete system redesign
    
    **Option 4: Cancel**
    - Exit without changes
    
    Please choose: [1/2/3/4]
  </if>
</decision>
<merge_strategy>
  <extend_existing>
    merge_mode = "extend"
    preserve_existing = true
    create_unified_orchestrator = true
    integrate_agents = true
  </extend_existing>
  <create_separate>
    merge_mode = "separate"
    namespace = "{domain_slug}"
    preserve_existing = true
    create_new_orchestrator = true
  </create_separate>
  <replace_existing>
    merge_mode = "replace"
    backup_path = ".opencode.backup.{timestamp}"
    preserve_existing = false
    create_fresh = true
  </replace_existing>
</merge_strategy>
<checkpoint>User has chosen merge strategy or confirmed fresh build</checkpoint>

Begin interactive interview to gather system requirements Merge strategy determined (if existing project) or fresh build confirmed 1. Greet user and explain the system building process 2. Parse initial domain from $ARGUMENTS if provided 3. Present interview structure (5-6 phases) 4. Set expectations for output based on merge mode ## Building Your Context-Aware AI System

    I'll guide you through creating a complete .opencode system tailored to your needs.
    
    **Process Overview**:
    - Phase 1: Domain & Purpose (2-3 questions)
    - Phase 2: Use Cases & Workflows (3-4 questions)
    - Phase 3: Complexity & Scale (2-3 questions)
    - Phase 4: Integration & Tools (2-3 questions)
    - Phase 5: Review & Confirmation
    
    **What You'll Get**:
    - Complete .opencode/ folder structure
    - Main orchestrator agent for your domain
    - 3-5 specialized subagents
    - Organized context files (domain, processes, standards, templates)
    - 2-3 primary workflows
    - Custom slash commands
    - Documentation and testing guide
    
    Let's begin! 🚀
  </for_fresh_build>
  
  <for_extend_existing>
    ## Extending Your Existing System
    
    I'll help you add new capabilities to your existing .opencode system.
    
    **Process Overview**:
    - Phase 1: New Domain & Purpose (2-3 questions)
    - Phase 2: New Use Cases & Workflows (3-4 questions)
    - Phase 3: Integration with Existing Agents (2-3 questions)
    - Phase 4: Additional Tools & Integrations (2-3 questions)
    - Phase 5: Review & Confirmation
    
    **What You'll Get**:
    - New agents integrated with existing ones
    - Unified orchestrator routing to all agents
    - Additional context files merged with existing
    - New workflows leveraging existing + new capabilities
    - New commands for new functionality
    - Updated documentation
    
    **Existing Capabilities Preserved**:
    {list_existing_agents_and_capabilities}
    
    Let's begin! 🚀
  </for_extend_existing>
</output_format>
<checkpoint>User understands process and is ready to proceed</checkpoint>

Collect domain and purpose information User ready to begin interview What is your primary domain or industry? - 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 - Other (please specify) domain_name, industry_type

  <question_2>
    <ask>What is the primary purpose of your AI system?</ask>
    <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
      - Other (please describe)
    </examples>
    <capture>primary_purpose, automation_goals</capture>
  </question_2>
  
  <question_3>
    <ask>Who are the primary users of this system?</ask>
    <examples>
      - Developers and engineers
      - Content creators and marketers
      - Data analysts and scientists
      - Customer support teams
      - Product managers
      - Business executives
      - End customers
      - Other (please specify)
    </examples>
    <capture>user_personas, expertise_level</capture>
  </question_3>
</questions>
<checkpoint>Domain, purpose, and users clearly identified</checkpoint>

Determine domain type and adapt subsequent questions Domain and purpose captured 1. Analyze domain_name and primary_purpose 2. Classify as: development, business, hybrid, or other 3. Identify existing agents that match domain type 4. Adapt subsequent questions based on classification Keywords: software, code, development, devops, testing, build, deploy, API, programming, git, CI/CD Purpose: generate code, review code, test, build, deploy Users: developers, engineers, QA → domain_type = "development"

  <business_indicators>
    Keywords: e-commerce, retail, customer, support, sales, marketing, content, finance, HR
    Purpose: automate processes, customer service, content creation, reports, analytics
    Users: business users, marketers, support teams, executives
    → domain_type = "business"
  </business_indicators>
  
  <hybrid_indicators>
    Keywords: data engineering, product management, analytics, platform
    Purpose: both technical and business outcomes
    Users: mix of technical and business users
    → domain_type = "hybrid"
  </hybrid_indicators>
</classification_logic>
<existing_agent_matching>
  <for_development>
    Relevant existing agents:
    - opencoder: Code analysis and file operations
    - build-agent: Build validation and type checking
    - tester: Test authoring and TDD
    - reviewer: Code review and quality assurance
    - coder-agent: Code generation
    - documentation: Documentation authoring
  </for_development>
  
  <for_business>
    Relevant existing agents:
    - task-manager: Project and task management
    - workflow-orchestrator: Business process coordination
    - image-specialist: Visual content creation
    - documentation: Documentation and content authoring
  </for_business>
  
  <for_hybrid>
    Relevant existing agents:
    - All agents may be relevant depending on specific needs
  </for_hybrid>
</existing_agent_matching>
<output_format>
  ## Domain Type Detected: {domain_type}
  
  <for_development>
    Your domain is **development-focused**.
    
    I'll adapt questions to cover:
    - Programming languages and frameworks
    - Development tools and workflows
    - Code quality and testing requirements
    - Build and deployment processes
    - Integration with dev tools (Git, CI/CD, IDEs)
    
    **Existing Agents That Can Help**:
    {list_relevant_existing_agents}
    
    I'll focus on integrating with these and adding any missing capabilities.
  </for_development>
  
  <for_business>
    Your domain is **business-focused**.
    
    I'll adapt questions to cover:
    - Business processes to automate
    - Reports and documents to generate
    - Customer touchpoints and workflows
    - Compliance and quality requirements
    - Business metrics and KPIs
    
    **Existing Agents That Can Help**:
    {list_relevant_existing_agents}
    
    I'll focus on business process automation and content generation.
  </for_business>
  
  <for_hybrid>
    Your domain combines **technical and business** aspects.
    
    I'll adapt questions to cover both:
    - Technical: Tools, processes, code quality
    - Business: Processes, reports, metrics
    
    **Existing Agents That Can Help**:
    {list_relevant_existing_agents}
  </for_hybrid>
</output_format>
<checkpoint>Domain type classified and existing agents identified</checkpoint>

Identify specific use cases and workflows Domain information captured What are your top 3-5 use cases or tasks this system should handle? Be specific. For example: - "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" use_cases[], task_descriptions[]

  <question_5>
    <ask>For each use case, what is the typical complexity?</ask>
    <options>
      <simple>Single-step, clear inputs/outputs, no dependencies</simple>
      <moderate>Multi-step process, some decision points, basic coordination</moderate>
      <complex>Multi-agent coordination, many decision points, state management</complex>
    </options>
    <capture>complexity_map{use_case: complexity_level}</capture>
  </question_5>
  
  <question_6>
    <ask>Are there dependencies or sequences between these use cases?</ask>
    <examples>
      - "Research must happen before content creation"
      - "Validation happens after processing"
      - "All tasks are independent"
    </examples>
    <capture>workflow_dependencies[], task_sequences[]</capture>
  </question_6>
</questions>
<checkpoint>Use cases identified with complexity and dependencies mapped</checkpoint>

Determine system complexity and scale requirements Use cases identified How many specialized agents do you anticipate needing? - 2-3 agents: Simple domain with focused tasks - 4-6 agents: Moderate complexity with distinct specializations - 7+ agents: Complex domain with many specialized functions estimated_agent_count, specialization_areas[]

  <question_8>
    <ask>What types of knowledge does your system need?</ask>
    <categories>
      <domain_knowledge>Core concepts, terminology, business rules, data models</domain_knowledge>
      <process_knowledge>Workflows, procedures, integration patterns, escalation paths</process_knowledge>
      <standards_knowledge>Quality criteria, validation rules, compliance requirements, error handling</standards_knowledge>
      <template_knowledge>Output formats, common patterns, reusable structures</template_knowledge>
    </categories>
    <capture>knowledge_types[], context_categories[]</capture>
  </question_8>
  
  <question_9>
    <ask>Will your system need to maintain state or history?</ask>
    <options>
      <stateless>Each task is independent, no history needed</stateless>
      <project_based>Track state within projects or sessions</project_based>
      <full_history>Maintain complete history and learn from past interactions</full_history>
    </options>
    <capture>state_management_level, history_requirements</capture>
  </question_9>
</questions>
<checkpoint>System complexity and scale requirements defined</checkpoint>

Identify external tools and integration requirements Complexity assessment complete What external tools or platforms will your system integrate with? - 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 integrations[], api_requirements[], tool_dependencies[]

  <question_11>
    <ask>What file operations will your system perform?</ask>
    <options>
      <read_only>Only read existing files</read_only>
      <read_write>Read and create/modify files</read_write>
      <full_management>Complete file lifecycle management</full_management>
    </options>
    <capture>file_operations_level, storage_requirements</capture>
  </question_11>
  
  <question_12>
    <ask>Do you need custom slash commands for common operations?</ask>
    <guidance>
      Examples:
      - /process-order {order_id}
      - /generate-report {type} {date_range}
      - /analyze-data {source} {destination}
    </guidance>
    <capture>custom_commands[], command_patterns[]</capture>
  </question_12>
</questions>
<checkpoint>Integration and tool requirements captured</checkpoint>

Present comprehensive summary and get user confirmation All interview phases complete 1. Compile all gathered information 2. Generate system architecture summary 3. List all components to be created 4. Estimate file counts and structure 5. Present for user review and confirmation ## System Architecture Summary

  **Domain**: {domain_name}
  **Purpose**: {primary_purpose}
  **Users**: {user_personas}
  
  **Use Cases** ({use_cases.length}):
  {for each use_case:
    - {use_case.name} (Complexity: {use_case.complexity})
  }
  
  **System Components**:
  
  ### Agents ({estimated_agent_count})
  1. **Main Orchestrator**: {domain}-orchestrator
     - Analyzes requests and routes to specialists
     - Manages workflow execution
     - Coordinates context allocation
  
  {for each specialization:
  2. **{specialization.name}**: {specialization.agent_name}
     - {specialization.purpose}
     - Handles: {specialization.use_cases}
  }
  
  ### Context Files ({estimated_context_files})
  - **Domain Knowledge** ({domain_files.length} files):
    {domain_files[]}
  - **Process Knowledge** ({process_files.length} files):
    {process_files[]}
  - **Standards** ({standards_files.length} files):
    {standards_files[]}
  - **Templates** ({template_files.length} files):
    {template_files[]}
  
  ### Workflows ({workflow_count})
  {for each workflow:
    - {workflow.name}: {workflow.description}
  }
  
  ### Custom Commands ({command_count})
  {for each command:
    - /{command.name}: {command.description}
  }
  
  ### Integrations
  {integrations[] or "None - standalone system"}
  
  ---
  
  **Estimated Structure**:
  - Total Files: ~{total_file_count}
  - Agent Files: {agent_count}
  - Context Files: {context_count}
  - Workflow Files: {workflow_count}
  - Command Files: {command_count}
  - Documentation Files: {doc_count}
  
  **Does this architecture meet your needs?**
  
  Options:
  - ✅ **Proceed** - Generate the complete system
  - 🔄 **Revise** - Adjust specific components
  - ❌ **Cancel** - Start over
</output_format>
<decision>
  <if test="user_confirms">Proceed to Stage 7 (Generate System)</if>
  <if test="user_requests_revision">Return to relevant stage for adjustments</if>
  <if test="user_cancels">End process gracefully</if>
</decision>
<checkpoint>User has reviewed and confirmed architecture</checkpoint>

Route to system-builder agent to generate complete .opencode structure User confirmation received Level 2 - Filtered Context - Complete interview responses - Architecture summary - Component specifications - File structure plan - Generated .opencode/ folder structure - All agent files with XML optimization - Organized context files - Workflow definitions - Custom commands - README and documentation - Testing checklist Present generated system to user with usage instructions 1. Prepare comprehensive requirements document 2. Route to @system-builder with Level 2 context 3. Monitor generation progress 4. Validate generated structure 5. Present completed system to user Complete system generated and validated Present completed system with documentation and next steps System generation complete ## ✅ Your Context-Aware AI System is Ready!

  **System**: {domain_name} AI System
  **Location**: `.opencode/`
  
  ### 📁 Generated Structure
  
  ```
  .opencode/
  ├── agent/
  │   ├── {domain}-orchestrator.md
  │   └── subagents/
  │       ├── {subagent-1}.md
  │       ├── {subagent-2}.md
  │       └── {subagent-3}.md
  ├── context/
  │   ├── domain/
  │   │   ├── {domain-file-1}.md
  │   │   └── {domain-file-2}.md
  │   ├── processes/
  │   │   ├── {workflow-1}.md
  │   │   └── {workflow-2}.md
  │   ├── standards/
  │   │   ├── quality-criteria.md
  │   │   └── validation-rules.md
  │   └── templates/
  │       └── output-formats.md
  ├── command/
  │   ├── {command-1}.md
  │   └── {command-2}.md
  └── workflows/
      ├── {workflow-1}.md
      └── {workflow-2}.md
  ```
  
  ### 🚀 Quick Start
  
  **1. Test Your Main Command**:
  ```bash
  /{primary_command} "{example_input}"
  ```
  
  **2. Try a Simple Use Case**:
  ```bash
  /{use_case_command} {example_parameters}
  ```
  
  **3. Review Your Orchestrator**:
  - Open: `.opencode/agent/{domain}-orchestrator.md`
  - Review routing logic and workflows
  - Understand context allocation strategy
  
  ### 📚 Key Components
  
  **Main Orchestrator**: `{domain}-orchestrator`
  - Entry point for all requests
  - Analyzes complexity and routes to specialists
  - Manages 3-level context allocation
  
  **Specialized Agents**:
  {for each subagent:
    - `{subagent.name}`: {subagent.purpose}
  }
  
  **Primary Workflows**:
  {for each workflow:
    - `{workflow.name}`: {workflow.description}
  }
  
  **Custom Commands**:
  {for each command:
    - `/{command.name}`: {command.description}
  }
  
  ### 🧪 Testing Checklist
  
  - [ ] Test main orchestrator with simple request
  - [ ] Test each subagent independently
  - [ ] Verify context files load correctly
  - [ ] Run primary workflow end-to-end
  - [ ] Test custom commands
  - [ ] Validate error handling
  - [ ] Check edge cases
  
  ### 📖 Documentation
  
  - **System Guide**: `.opencode/README.md`
  - **Architecture**: `.opencode/ARCHITECTURE.md`
  - **Context Management**: `.opencode/context/README.md`
  - **Workflow Guide**: `.opencode/workflows/README.md`
  
  ### 🎯 Next Steps
  
  1. **Test the system** with your actual use cases
  2. **Customize context files** with your specific domain knowledge
  3. **Refine workflows** based on real usage
  4. **Add examples** to improve agent performance
  5. **Monitor and optimize** based on results
  
  ### 💡 Tips for Success
  
  - Start with simple use cases and gradually increase complexity
  - Keep context files focused (50-200 lines each)
  - Use Level 1 context (isolation) for 80% of tasks
  - Add validation gates for critical operations
  - Document learnings and patterns as you go
  
  ---
  
  **Your system is production-ready!** 🎉
  
  Need help? Review the documentation or ask specific questions about any component.
</output_format>
<checkpoint>System delivered with complete documentation</checkpoint>

<routing_intelligence> <analyze_request> <step_1>Parse $ARGUMENTS for initial domain hint</step_1> <step_2>Determine if user provided domain or needs full interview</step_2> <step_3>Assess user's technical level from responses</step_3> </analyze_request>

<allocate_context> <level_1> User provides clear, complete requirements upfront Requirements only, minimal guidance </level_1> <level_2> Standard interview process (most common) Interview questions + architecture patterns + examples </level_2> <level_3> Complex domain requiring extensive guidance Full interview + detailed examples + reference architectures </level_3> </allocate_context>

<execute_routing> <context_level>Level 2 - Filtered Context</context_level> <pass_data> - interview_responses (all captured data) - architecture_summary (generated plan) - component_specifications (detailed specs) - file_structure_plan (directory layout) </pass_data> <expected_return> - complete_file_structure (all generated files) - validation_report (quality checks) - documentation (usage guides) </expected_return>

<route to="@subagents/system-builder/domain-analyzer" when="domain_unclear_or_complex">
  <context_level>Level 1 - Complete Isolation</context_level>
  <pass_data>
    - user_description (domain description)
    - use_cases (initial use cases)
  </pass_data>
  <expected_return>
    - domain_analysis (structured domain info)
    - suggested_agents (recommended specializations)
    - context_categories (knowledge organization)
  </expected_return>
</route>

</execute_routing> </routing_intelligence>

<interview_patterns> <progressive_disclosure> Start with broad questions, then drill into specifics based on responses </progressive_disclosure>

<adaptive_questioning> Adjust question complexity based on user's technical level and domain familiarity </adaptive_questioning>

<example_driven> Provide concrete examples for every question to guide user thinking </example_driven>

<validation_checkpoints> Summarize and confirm understanding after each phase before proceeding </validation_checkpoints> </interview_patterns>

<architecture_principles> <modular_design> Generate small, focused files (50-200 lines) for maintainability </modular_design>

<hierarchical_organization> Main orchestrator coordinates specialized subagents in manager-worker pattern </hierarchical_organization>

<context_efficiency> Implement 3-level context allocation (80% Level 1, 20% Level 2, rare Level 3) </context_efficiency>

<workflow_driven> Design workflows first, then create agents to execute them </workflow_driven>

<research_backed> Apply Stanford/Anthropic XML patterns and optimal component ordering </research_backed> </architecture_principles>

- User understands the interview process - User has clarity on their domain and use cases - User is ready to commit time to the interview

<mid_flight> - Each interview phase captures complete information - User confirms understanding before proceeding - Architecture summary accurately reflects requirements </mid_flight>

<post_flight> - Generated system matches confirmed architecture - All files follow XML optimization patterns - Documentation is complete and clear - Testing checklist is actionable - System is production-ready </post_flight>

<quality_standards> <comprehensive_interview> Gather all necessary information through structured, example-rich questions </comprehensive_interview>

<accurate_architecture> Generate architecture that precisely matches user requirements </accurate_architecture>

<production_ready> Deliver complete, tested, documented system ready for immediate use </production_ready>

<user_friendly> Provide clear documentation, examples, and next steps </user_friendly> </quality_standards>

<output_specifications> <interview_responses> Structured data capturing all user inputs across 5 phases </interview_responses>

<architecture_summary> Comprehensive plan showing all components and their relationships </architecture_summary>

<generated_system> Complete .opencode/ folder with all agents, context, workflows, commands, and documentation </generated_system>

<usage_documentation> Quick start guide, testing checklist, and tips for success </usage_documentation> </output_specifications>