Skip to content

README.md

Latest commit

 

History

History
296 lines (231 loc) · 10.5 KB

README.md

File metadata and controls

296 lines (231 loc) · 10.5 KB

OpenCode Agent Orchestration Framework

A developer-focused framework for building software features through coordinated AI agent collaboration.

Requires opencode v0.15.29+ because of positional arguments for across agent compatibility.

Quick Start

Prerequisites

  • Git repository initialized
  • OpenCode CLI installed

Basic Usage

# Create a task from your current discussion
/auto_task "Add OAuth2 support to our authentication service"

# Plan the implementation with architectural analysis
/auto_plan ./.task/0030-add-oauth2-support.md @architect @sonnet

# Execute the plan with code generation
/orch ./.task/0030-add-oauth2-support.md ./.plan/0030-add-oauth2-support.md grok sonnet

Core Commands

/auto_task - Task Creation

Transforms conversation into structured development tasks.

Usage:

/auto_task [task description]

What it does:

  • Creates numbered task files in ./.task/ directory
  • Generates kebab-case filenames (max 7 words)
  • Structures requirements and expected outcomes
  • Uses the current conversation context as input when called after discussing requirements

Example:

# After discussing authentication requirements:
/auto_task "Implement JWT token refresh mechanism with Redis caching"
# Creates: ./.task/0040-implement-jwt-token-refresh.md

/auto_feature - Feature Specification

Creates comprehensive feature specifications with architectural planning.

Usage:

/auto_feature [feature description]

What it does:

  • Creates feature files in ./.feature/ directory
  • Generates feature architecture documentation
  • Uses the current conversation context as input when called after architectural discussions
  • Breaks down complex features into manageable components

Example:

# After discussing system architecture:
/auto_feature "Implement user authentication system with JWT and OAuth2"
# Creates: ./.feature/100-user-authentication-system.md

/auto_plan - Planning & Architecture

Generates comprehensive development plans with architectural analysis.

Usage:

/auto_plan ./.task/[filename].md @architect @agent_type

File outputs:

  • ./.plan/arch_[filename].md - Architectural analysis
  • ./.plan/[filename].md - Implementation plan

Example:

/auto_plan ./.task/0040-implement-jwt-token-refresh.md @architect @sonnet

/orch - Code Execution

Executes development plans with quality validation.

Usage:

/orch ./.task/[filename].md ./.plan/[filename].md agent_1 agent_2

Process:

  1. First agent implements the plan
  2. Second agent reviews implementation quality
  3. Iterative improvement until 90%+ compliance
  4. Tracks modified files without automatic commits

Example:

/orch ./.task/0040-implement-jwt-token-refresh.md ./.plan/0040-implement-jwt-token-refresh.md grok sonnet

Advanced Workflows

Feature Workflow (Complex Projects)

For multi-task features requiring architectural coordination.

# 1. Create feature specification
/auto_feature "Implement user authentication system with JWT and OAuth2"

# 2. Decompose into individual tasks
/feature_decompose ./.feature/100-user-authentication-system.md

# 3. Plan each task
/auto_plan ./.task/100_1_10-jwt-service.md @sonnet @glm
/auto_plan ./.task/100_1_20-oauth2-integration.md @sonnet @glm

# 4. Execute each task
/orch ./.task/100_1_10-jwt-service.md ./.plan/100_1_10-jwt-service.md grok sonnet

Simple Task Workflow

For straightforward development tasks.

# 1. Create task
/auto_task "Add input validation to user registration endpoint"

# 2. Generate plan
/auto_plan ./.task/0050-add-input-validation.md @sonnet @glm

# 3. Execute implementation
/orch ./.task/0050-add-input-validation.md ./.plan/0050-add-input-validation.md grok sonnet

Agent Selection Guide

Primary Development Agents

  • grok: General coding and planning
  • sonnet: General coding and planning
  • supernova: General coding and planning
  • qwen3: General coding and planning

Specialized Agents

  • architect: Architectural guidance, design patterns, system integration
  • security-auditor: Security reviews, vulnerability identification
  • review: Code quality, best practices, performance optimization

Recommended Combinations

  • Planning: @glm @sonnet or @sonnet @glm
  • Execution: @glm @sonnet or @sonnet @glm

Quality Assurance

Planning Quality (90%+ threshold)

  • Implementation Feasibility (40%)
  • Architectural Alignment (30%)
  • Completeness (20%)
  • Integration Quality (10%)

Execution Quality (90%+ threshold)

  • Plan compliance - follows specified implementation
  • Approach adherence - uses planned methodology
  • Code quality - follows best practices
  • Security considerations - addresses vulnerabilities
  • Test coverage - includes appropriate tests

File Structure

project/
├── .task/                       # Individual tasks
│   └── {id}-{title}.md         # Task specifications
├── .plan/                       # Development plans
│   ├── arch_{id}.md            # Architecture analysis
│   └── {id}.md                 # Implementation plans
├── .feature/                    # Feature specifications (complex projects)
│   ├── {id}-{title}.md         # Feature requirements
│   ├── arch_{id}.md            # Feature architecture
│   └── {id}-decomposition.md   # Task breakdown
└── .cache/                      # Support files
    └── arch_migration.md       # Migration documentation

Best Practices

Task Creation

  • Be specific about requirements and constraints
  • Include architectural considerations when known
  • Use clear, descriptive task titles
  • Discuss requirements first, then call /auto_task to capture the conversation context

Feature Creation

  • Discuss architecture and scope first, then call /auto_feature to capture the conversation context
  • Include integration points and dependencies
  • Define clear success criteria

Agent Selection

  • Use different agents for planning and review to get diverse perspectives
  • Match agent specialties to task requirements
  • Consider security-auditor for authentication, data handling, or network code

Quality Standards

  • The 90% score threshold ensures high-quality deliverables
  • Review percentage breakdowns to understand specific improvement areas
  • Monitor retry counts for potential issues

Development Workflow

  • No premature commits - review all changes before committing
  • Use feature workflow for complex projects with 3+ related tasks
  • Track modified files for incremental review and testing

Error Handling & Reliability

  • Retry Limits: 3 attempts per phase with clear failure handling
  • Linear Flow: Predictable progression through phases
  • No Infinite Loops: Eliminated problematic "repeat till file exists" patterns
  • Graceful Degradation: Best effort completion when limits reached

Examples in Practice

Adding Database Migration

/auto_task "Create database migration for user profile schema changes"
/auto_plan ./.task/0060-create-user-profile-migration.md @architect @sonnet
/orch ./.task/0060-create-user-profile-migration.md ./.plan/0060-create-user-profile-migration.md grok sonnet

Implementing API Rate Limiting

/auto_task "Add rate limiting to public API endpoints using Redis"
/auto_plan ./.task/0070-add-api-rate-limiting.md @architect @sonnet
/orch ./.task/0070-add-api-rate-limiting.md ./.plan/0070-add-api-rate-limiting.md grok sonnet

Security Audit Integration

/auto_task "Review authentication service for security vulnerabilities"
/auto_plan ./.task/0080-security-audit-auth-service.md @architect @security-auditor
/orch ./.task/0080-security-audit-auth-service.md ./.plan/0080-security-audit-auth-service.md grok sonnet

This framework provides a structured approach to AI-assisted development with clear separation between planning and execution, ensuring high-quality, architecturally sound software implementation.

Key Benefits

  1. Structured Process: Clear separation between planning and execution
  2. Quality Assurance: Percentage-based validation ensures high-quality output
  3. Architectural Integrity: Research-backed architectural decisions
  4. Iterative Improvement: Automatic refinement until 90%+ quality achieved
  5. Traceability: Clear documentation trail from task to implementation
  6. Separation of Concerns: Architecture, planning, and implementation are handled separately
  7. Reliability: Retry limits, error handling, and no infinite loops 🛡️
  8. Flexibility: Dynamic agent selection with customizable combinations

Best Practices

  1. Task Creation: Be specific about requirements and include architectural considerations
  2. Agent Selection: Use different agents for planning (@agent_1) and review (@agent_2) to get diverse perspectives
  3. Quality Standards: The 90% score threshold ensures high-quality deliverables
  4. Documentation: Each stage produces comprehensive documentation for future reference
  5. No Premature Commits: Review all changes before committing to maintain code quality
  6. Feature vs Task: Use feature workflow for complex projects with 3+ related tasks
  7. Error Handling: Monitor retry counts and check for graceful failure handling
  8. Quality Tracking: Review percentage breakdowns to understand specific improvement areas

File Structure

project/
├── .feature/                      # Feature workflow
│   ├── {id}-{title}.md           # Feature specifications
│   ├── arch_{id}.md              # Essential architecture
│   ├── arch_{id}_research.md     # Detailed research (optional)
│   └── {id}-decomposition.md     # Task breakdown
├── .task/
│   └── {id}-{title}.md           # Individual tasks
├── .plan/
│   ├── arch_{id}.md              # Task-specific architecture
│   └── {id}.md                   # Implementation plans
├── .cache/                        # Support files
│   └── arch_migration.md         # Migration guide
├── templates/                     # Architecture templates
│   ├── arch_essential.md         # Essential arch template
│   └── arch_research.md          # Research template
└── [your code files]             # Implementation results

This framework ensures systematic, high-quality feature development through coordinated agent collaboration while maintaining architectural integrity and code quality standards.