plcode-darwin-arm64 2.1.0

package/.plcode/context/system-builder-templates/SYSTEM-BUILDER-GUIDE.md

@@ -0,0 +1,495 @@
+# 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 `.plcode` 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 .plcode Structure
+
+```
+.plcode/
+├── 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**: `.plcode/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`

package/.plcode/context/system-builder-templates/navigation.md

@@ -0,0 +1,72 @@
+# System Builder Templates
+
+This directory contains reusable templates for generating context-aware AI systems.
+
+## Template Categories
+
+### Agent Templates
+
+- `orchestrator-template.md` - Main coordinator agent pattern
+- `subagent-template.md` - Specialized subagent pattern
+- `research-agent-template.md` - Research/information gathering pattern
+- `validation-agent-template.md` - Quality assurance pattern
+- `processing-agent-template.md` - Data transformation pattern
+
+### Context Templates
+
+- `domain-knowledge-template.md` - Domain concept documentation
+- `process-workflow-template.md` - Process/workflow documentation
+- `standards-template.md` - Quality and validation standards
+- `template-pattern-template.md` - Reusable output templates
+
+### Workflow Templates
+
+- `simple-workflow-template.md` - Linear 3-5 stage workflow
+- `moderate-workflow-template.md` - Multi-step with decisions
+- `complex-workflow-template.md` - Multi-agent coordination
+
+### Command Templates
+
+- `simple-command-template.md` - Single parameter command
+- `parameterized-command-template.md` - Multi-parameter with flags
+
+### Documentation Templates
+
+- `readme-template.md` - System overview README
+- `architecture-template.md` - Architecture documentation
+- `testing-template.md` - Testing checklist
+- `quickstart-template.md` - Quick start guide
+
+## Usage
+
+These templates are used by the system-builder subagents to generate consistent,
+high-quality files following research-backed patterns.
+
+Each template includes:
+
+- XML structure with optimal component ordering
+- Placeholder markers for customization
+- Example content
+- Validation criteria
+- Best practices
+
+## Template Variables
+
+Templates use these variable patterns:
+
+- `{domain}` - Domain name
+- `{agent_name}` - Agent name
+- `{purpose}` - Purpose description
+- `{workflow_name}` - Workflow name
+- `{context_file}` - Context file reference
+
+## Quality Standards
+
+All templates follow:
+
+- Stanford/Anthropic XML research patterns
+- Optimal component ordering (context→role→task→instructions)
+- Hierarchical context structure
+- @ symbol routing for subagents
+- 3-level context allocation
+- Validation gates and checkpoints