OpenWriterControle/docs/features/system-builder/README.md

# Context-Aware System Builder

**Build complete, production-ready AI systems tailored to your domain in minutes.**

## Installation

### Install with Advanced Profile

The system builder is included in the **Advanced** profile:

```bash
curl -fsSL https://raw.githubusercontent.com/darrenhinde/opencode-agents/main/install.sh | bash -s advanced
```

**What you get:**
- ✅ All development tools (22 components)
- ✅ System builder (7 components)
- ✅ **Total: 29 components**

### Add to Existing Installation

Already have `core`, `developer`, or `full` profile? Add system builder:

```bash
# Run advanced profile
curl -fsSL https://raw.githubusercontent.com/darrenhinde/opencode-agents/main/install.sh | bash -s advanced

# When prompted about collisions:
# Choose: 1) Skip existing

# Result: Only system-builder components added
```

---

## Quick Start

```bash
/build-context-system
```

This launches an interactive interview that generates a complete `.opencode` system customized to your needs.

---

## What It Does

Transforms your requirements into a complete AI system with:

✅ **Main Orchestrator Agent** - Intelligent coordinator  
✅ **Specialized Subagents** - Domain-specific experts (3-7 agents)  
✅ **Organized Context Files** - Modular knowledge base  
✅ **Workflow Definitions** - Reusable process patterns  
✅ **Custom Slash Commands** - User-friendly interfaces  
✅ **Complete Documentation** - README, architecture, testing guides  

---

## Key Features

### 🛡️ Safe & Smart
- **Detects existing projects** - Won't overwrite your work
- **Merge options** - Extend, separate, or replace (with backup)
- **Conflict detection** - Intelligent file merging

### 🎯 Adaptive
- **Works for dev tasks** - Code, testing, builds, deployment
- **Works for business tasks** - Content, reports, processes
- **Works for hybrid tasks** - Data engineering, product management
- **Adapts questions** - Based on your domain type

### 🔗 Integrates
- **Detects existing agents** - Reuses what you have
- **Recommends integration** - Leverages existing capabilities
- **Creates unified system** - Cohesive orchestration

---

## How It Works

### 1. Project Detection
```
Scans for existing .opencode/
↓
If found: Offers merge options
- Extend existing (recommended)
- Create separate system
- Replace (with backup)
- Cancel
↓
If not found: Fresh build
```

### 2. Domain Type Detection
```
Analyzes your domain
↓
Classifies as:
- Development (code, testing, builds)
- Business (content, reports, processes)
- Hybrid (both technical and business)
↓
Adapts questions to your domain type
```

### 3. Intelligent Interview
```
Phase 1: Domain & Purpose
Phase 2: Use Cases & Workflows
Phase 3: Complexity & Scale
Phase 4: Integration & Tools
Phase 5: Review & Confirmation
```

### 4. System Generation
```
Routes to specialized subagents:
- domain-analyzer: Identifies concepts and agents
- agent-generator: Creates XML-optimized agents
- context-organizer: Organizes knowledge files
- workflow-designer: Designs process workflows
- command-creator: Creates slash commands
↓
Generates complete system
↓
Integrates with existing agents
```

---

## Examples

### Example 1: Code Review System (Dev)

**Command**: `/build-context-system "Code review automation"`

**Domain Type**: Development

**Questions Adapted**:
- "What programming languages?" → Python, JavaScript
- "What development tools?" → Git, GitHub Actions
- "What code quality standards?" → ESLint, tests

**Generated**:
- code-review-orchestrator
- static-analyzer (subagent)
- security-scanner (subagent)
- test-validator (subagent)
- Commands: /review-code, /scan-security

**Integration**: Leverages existing codebase-agent, reviewer, tester

---

### Example 2: E-commerce System (Business)

**Command**: `/build-context-system "E-commerce order processing"`

**Domain Type**: Business

**Questions Adapted**:
- "What business processes?" → Order fulfillment, refunds
- "What reports needed?" → Sales, inventory
- "What customer touchpoints?" → Email, notifications

**Generated**:
- ecommerce-orchestrator
- order-processor (subagent)
- inventory-checker (subagent)
- refund-manager (subagent)
- Commands: /process-order, /check-inventory

**Integration**: Leverages existing task-manager, workflow-orchestrator

---

### Example 3: Extend Existing Project

**Existing**: Dev tools (codebase-agent, build-agent, tester)

**Command**: `/build-context-system "Add documentation generation"`

**Flow**:
1. Detects existing project
2. User chooses: "Extend existing"
3. Domain type: Hybrid (dev + content)
4. Reuses: codebase-agent, documentation
5. Adds: doc-orchestrator, api-doc-generator
6. Result: Unified system with dev + docs

---

## Generated 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 systems implement 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)

---

## Existing Agent Integration

The system detects and integrates with existing agents:

**Development Agents**:
- `codebase-agent` - Code analysis, file operations
- `build-agent` - Build validation, type checking
- `tester` - Test authoring, TDD
- `reviewer` - Code review, quality assurance
- `coder-agent` - Code generation
- `documentation` - Documentation authoring

**Business Agents**:
- `task-manager` - Task tracking, project management
- `workflow-orchestrator` - Workflow coordination
- `image-specialist` - Image generation/editing

**Integration Strategy**:
- Reuses existing agents where applicable
- Creates new agents only for gaps
- Builds unified orchestrator routing to both
- Merges context files intelligently

---

## Merge Strategies

### Extend Existing (Recommended)
- ✅ Keeps all existing files
- ✅ Adds new capabilities
- ✅ Creates unified orchestrator
- ✅ Integrates new with existing agents
- Best for: Adding features to active projects

### Create Separate
- ✅ Keeps existing system intact
- ✅ Creates new system in separate namespace
- ✅ Both systems coexist
- Best for: Multi-domain projects

### Replace Existing
- ⚠️ Backs up to `.opencode.backup.{timestamp}/`
- ⚠️ Creates fresh system
- ⚠️ Use with caution
- Best for: Complete redesign

---

## Quality Standards

Generated systems score 8+/10 on:

**Agent Quality**:
- ✅ Optimal component ordering (context→role→task→instructions)
- ✅ Hierarchical context structure
- ✅ @ symbol routing with context levels
- ✅ Clear workflow stages with checkpoints
- ✅ Validation gates (pre_flight and post_flight)

**Context Organization**:
- ✅ Files are 50-200 lines (modular)
- ✅ Clear separation of concerns
- ✅ No duplication across files
- ✅ Dependencies documented
- ✅ Concrete examples included

**Workflow Completeness**:
- ✅ Clear stages with prerequisites
- ✅ Context dependencies mapped
- ✅ Success criteria defined
- ✅ Decision points documented
- ✅ Error handling specified

**Documentation Clarity**:
- ✅ Comprehensive README
- ✅ Clear architecture guide
- ✅ Actionable testing checklist
- ✅ Relevant usage examples
- ✅ Next steps provided

---

## System Components

### Command
- `.opencode/command/build-context-system.md` - Entry point

### Main Orchestrator
- `.opencode/agent/system-builder.md` - Coordinates generation

### Specialized Subagents
- `.opencode/agent/subagents/domain-analyzer.md` - Domain analysis
- `.opencode/agent/subagents/agent-generator.md` - Agent generation
- `.opencode/agent/subagents/context-organizer.md` - Context organization
- `.opencode/agent/subagents/workflow-designer.md` - Workflow design
- `.opencode/agent/subagents/command-creator.md` - Command creation

### Templates
- `.opencode/context/system-builder-templates/` - Reusable patterns

### Documentation
- `.opencode/CONTEXT-SYSTEM-BUILDER.md` - Detailed documentation
- `.opencode/SYSTEM-BUILDER-README.md` - This file

---

## Usage Tips

### For Best Results

1. **Be specific** about use cases
   - Good: "Process customer orders from multiple channels"
   - Bad: "Do stuff with orders"

2. **Identify dependencies**
   - "Inventory check must happen before order processing"

3. **Choose appropriate merge strategy**
   - Extending? Choose "Extend existing"
   - New domain? Choose "Create separate"

4. **Customize after generation**
   - Add domain-specific knowledge to context files
   - Refine workflows based on real usage
   - Add examples to improve agent performance

### Common Workflows

**Fresh Build**:
```bash
/build-context-system "Your domain name"
```

**Extend Existing**:
```bash
/build-context-system "Add new capability"
# → Detects existing
# → Choose "Extend existing"
# → Integrates with current system
```

**Multi-Domain**:
```bash
/build-context-system "Client B project"
# → Detects existing Client A
# → Choose "Create separate"
# → Both systems coexist
```

---

## Testing Your Generated System

### Component Testing
- [ ] Test orchestrator with simple request
- [ ] Test each subagent independently
- [ ] Verify context files load correctly
- [ ] Run workflows end-to-end
- [ ] Test custom commands
- [ ] Validate error handling
- [ ] Test edge cases

### Integration Testing
- [ ] Multi-agent coordination
- [ ] Context loading verification
- [ ] Routing logic validation
- [ ] Validation gates functionality
- [ ] Performance measurement

---

## Troubleshooting

**Issue**: System overwrites existing files  
**Solution**: Stage 0 should detect existing project and offer merge options. If not working, check project detection logic.

**Issue**: Questions don't match my domain  
**Solution**: Stage 2.5 should detect domain type. Verify domain classification logic.

**Issue**: Doesn't integrate with existing agents  
**Solution**: Check that existing agents are in `.opencode/agent/` or `.opencode/agent/subagents/`

**Issue**: Generated agents don't route correctly  
**Solution**: Verify @ symbol usage and context level specifications in agent files

---

## Advanced Usage

### Incremental Enhancement

After initial generation, you can:
- Add new agents manually
- Extend existing workflows
- Create additional commands
- Add more context files

### Custom Templates

Modify templates in `.opencode/context/system-builder-templates/` to customize generation patterns.

### Integration Patterns

Study generated orchestrators to understand integration patterns for your own agents.

---

## Performance Expectations

**Time**: 10-15 minutes from start to production-ready system

**Quality**: All components score 8+/10

**Safety**: No data loss, backup before replace

**Integration**: Leverages existing agents, no duplication

**Adaptability**: Works for any domain (dev or non-dev)

---

## Next Steps

1. **Run the command**: `/build-context-system`
2. **Answer interview questions** (5 phases, ~10 minutes)
3. **Review generated system** (README.md, ARCHITECTURE.md)
4. **Test functionality** (TESTING.md checklist)
5. **Customize** (Add domain-specific knowledge)
6. **Deploy** (Use in production)

---

## Resources

- **Detailed Documentation**: `.opencode/CONTEXT-SYSTEM-BUILDER.md`
- **Templates**: `.opencode/context/system-builder-templates/`
- **System Builder Guide**: `.opencode/context/system-builder-templates/SYSTEM-BUILDER-GUIDE.md`

---

## Support

For questions or issues:
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

---

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

```bash
/build-context-system
```