Resources

scripts/
  validate-orchestration.sh
references/
  agent-assignment-guide.md

Task Orchestration Protocol

The task orchestration protocol defines how the GoodVibes orchestrator decomposes feature requests into agent tasks, assigns agents and skills, manages parallel execution, and interacts with the runtime engine's WRFC chain system. This is the orchestrator's primary workflow for multi-agent feature delivery.

When to Use This Skill

Use this skill when:

• User provides a feature request requiring multiple work streams
• Request involves multiple domains (backend, frontend, database, etc.)
• Request can be parallelized into independent subtasks
• Request requires coordination across multiple agents

Do NOT use this skill for:

• Simple single-file edits (handle directly)
• Pure analysis tasks without code changes
• Tasks already decomposed by the user

Runtime Engine and WRFC Chains

The runtime engine manages Work-Review-Fix-Complete (WRFC) chains automatically. The orchestrator's role is:

1. Decompose the task into work agents
2. Spawn the initial work agents
3. Execute <gv> directives issued by the runtime engine — mechanically, immediately, without judgment

The runtime engine handles all review, fix, and completion decisions. The orchestrator does NOT manually spawn reviewers or fix agents. These come exclusively from runtime directives after each work agent completes.

Directive Types

The runtime engine issues directives to the orchestrator via system messages containing <gv> tags:

{"action":"spawn","wid":"wrfc_xxx","type":"reviewer","task":"Review the code..."}
{"action":"spawn","wid":"wrfc_xxx","type":"engineer","task":"Fix the issues..."}
{"action":"complete","wid":"wrfc_xxx"}
{"action":"escalate","wid":"wrfc_xxx","reason":"Max fix attempts reached"}

Directive Compliance Rules

These 4 rules are absolute and non-negotiable:

1. Immediate: Execute directives the moment they arrive. NEVER defer, queue, or delay.
2. First: Execute directives BEFORE any other action. No intervening tool calls, no additional agent spawns, no user messages first.
3. Autonomy ends: Once the first directive arrives for a WRFC chain, the orchestrator has no further judgment over that chain. Only directives drive it.
4. Runtime supersedes: Runtime workflow logic ALWAYS supersedes orchestrator judgment. If a directive says review, review. If it says complete, complete.

Configurable Thresholds

The runtime reads goodvibes.json for:

• min_review_score (default: 9.5) — score threshold for PASS
• max_fix_attempts (default: 3) — max fix cycles before escalation

The orchestrator never hardcodes these values. The runtime engine enforces them.

Decomposition Process

Step 1: Classify the Request

Before decomposing, classify the request into one of these categories:

Feature Implementation - Add new functionality

• Identify: "Add X feature", "Implement Y", "Create Z capability"
• Decomposition strategy: Split by domain (API, UI, DB, types)
• Parallelism: High (most work streams independent)

Bug Fix - Resolve existing issue

• Identify: "Fix X not working", "Resolve Y error", "Correct Z behavior"
• Decomposition strategy: Root cause first, then fix propagation
• Parallelism: Low (diagnosis must precede fixes)

Refactoring - Improve code structure without changing behavior

• Identify: "Refactor X", "Restructure Y", "Extract Z"
• Decomposition strategy: Analysis first, then file-by-file changes
• Parallelism: Medium (analysis sequential, changes parallel)

Integration - Connect existing systems

• Identify: "Integrate X with Y", "Connect A to B"
• Decomposition strategy: Understand both sides, then adapter layer
• Parallelism: Medium (research parallel, integration sequential)

Enhancement - Improve existing feature

• Identify: "Improve X", "Add Y to existing Z"
• Decomposition strategy: Understand current state, plan incremental additions
• Parallelism: Medium (discovery sequential, additions parallel)

Step 2: Identify Parallel Opportunities

After classifying, identify work that can run in parallel:

Independent domains:

• API route + React component (if contract is defined upfront)
• Type definitions + database schema
• Multiple UI components with shared types
• Multiple API endpoints with shared middleware

Independent files:

• Creating new files in different directories
• Editing files with no import relationships
• Writing tests for different modules

Independent research:

• Checking multiple documentation sources
• Analyzing multiple files for patterns
• Discovering patterns in different directories

When NOT to parallelize:

• Type definitions must exist before implementation uses them
• Database schema must exist before API queries it
• Parent component must exist before child imports it
• Discovery must complete before planning

Step 3: Define Agent Tasks

For each parallelizable work stream, define a task with:

Task structure:

task_id: unique-task-identifier
agent: engineer | reviewer | tester | architect | deployer | integrator-ai | integrator-services | integrator-state | planner
skills: [skill-1, skill-2]
description: Brief description of what this task accomplishes
scope:
  files: [list of files to create/modify]
  directories: [directories to work within]
constraints:
  - Must use TypeScript
  - Follow existing patterns in src/features/
blocking: [list of task_ids this task blocks]
blocked_by: [list of task_ids blocking this task]
expected_outcome: What success looks like

Example:

task_id: create-user-types
agent: engineer
skills: [gather-plan-apply, precision-mastery, error-recovery, goodvibes-memory]
description: Create TypeScript type definitions for User domain
scope:
  files: [src/types/user.ts, src/types/auth.ts]
  directories: [src/types]
constraints:
  - Use Zod for runtime validation
  - Export all types from src/types/index.ts
blocking: [create-user-api, create-user-components]
blocked_by: []
expected_outcome: Type files exist, export User, AuthContext, and validation schemas

Step 4: Assign Agent and Skills

For each task, assign the appropriate agent type and skills using this decision table:

Agent Type Selection:

Work Type	Agent Type	Rationale
Implement API, components, features	engineer	Code creation and implementation
Review code quality, standards	reviewer	Code quality and standards enforcement
Write tests, test coverage	tester	Testing and validation
Plan architecture, design decisions	architect	High-level design and planning
Deploy applications, infrastructure	deployer	Deployment and infrastructure
Integrate AI/ML services	integrator-ai	AI/ML integration
Integrate external services	integrator-services	External service integration
Manage state and data flow	integrator-state	State management
Coordinate complex workflows	planner	High-level orchestration

Skills Assignment:

All agents receive protocol skills by default:

• gather-plan-apply (GPA loop)
• precision-mastery (tool usage)
• error-recovery (error handling)
• goodvibes-memory (memory integration)

Additional skills by work type:

Work Type	Additional Skills
API implementation	trpc, prisma, nextauth, rest-api-design
Frontend components	react, nextjs, tailwindcss, shadcn-ui
Database schema	prisma, postgresql, drizzle
Authentication	clerk, nextauth, lucia
Type definitions	(none - protocol skills sufficient)
Code review	review-scoring + domain-specific review skills

See references/agent-assignment-guide.md for complete assignment table.

Agent Prompt Template

When spawning agents, ALWAYS include these elements in the agent prompt:

## Task
[Specific, actionable description of what to accomplish]

## Scope
**Files to create:**
- path/to/file.ts - Brief description

**Files to modify:**
- path/to/existing.ts - What changes to make

**Directories in scope:**
- src/features/auth/ - Work within this directory

## Constraints
- [Technical constraint 1]
- [Pattern to follow]
- [Dependency requirement]

## Skills Available
- skill-name - When to use it
- skill-name - When to use it

## Expected Outcome
[Concrete definition of success]

## Blocking/Blocked By
**This task blocks:** [list of downstream tasks waiting for this]
**This task is blocked by:** [list of upstream tasks this waits for]

Critical elements:

1. Scope is explicit (file paths, not vague descriptions)
2. Skills are listed with usage guidance
3. Expected outcome is concrete and verifiable
4. Output format includes the <gv> tag (emitted automatically by the runtime hook; the orchestrator does not need to instruct agents about this)

Note: Do NOT add WRFC participation instructions to agent prompts. Agents only need to complete their work and emit a <gv> tag. The runtime engine handles the WRFC chain automatically.

Monitoring and Coordination

Track Active Agents

Maintain a task tracking structure:

active_tasks:
  task-1:
    agent_id: agent_abc123
    status: running | completed | blocked | failed
    started_at: ISO-8601 timestamp
    last_update: ISO-8601 timestamp
    blocking: [task-2, task-3]
    blocked_by: []
  task-2:
    agent_id: agent_def456
    status: waiting
    blocked_by: [task-1]

Agent Concurrency Limits

Hard limit: 6 concurrent agent chains (from max_parallel_agent_chains in output style config)

A "chain" includes the work agent plus its entire WRFC chain (review, fix, re-review). Each initial work agent spawn creates one chain. Count chains, not individual agents.

When you have more than 6 tasks:

1. Prioritize by dependency order (unblock downstream tasks first)
2. Queue remaining tasks
3. Spawn new agents as chains complete (when runtime issues complete directive)

Task priority formula:

priority = (number of tasks it blocks) - (number of tasks blocking it)

Higher priority = spawn first

Executing <gv> Directives

When the runtime engine issues a directive:

1. Stop everything — do not complete any in-progress reasoning about other tasks
2. Read the directive — identify the action, wid, type, and task fields
3. Execute immediately:
   • spawn: Spawn the specified agent type with the provided task prompt
   • complete: Mark the WRFC chain as done, unblock any dependent tasks, spawn next queued task if slot available
   • escalate: Report to user with the escalation reason, do not spawn further agents for this chain
4. Then resume other orchestration work

No exceptions. A directive is never skipped, reordered, or conditioned on another event.

WRFC Spawn Rules

1. Initial spawns only: Orchestrator spawns ONLY the initial work agents from task decomposition. All reviewer and fix agent spawns come from runtime directives.
2. Parallel when possible: Spawn all tasks in the same dependency wave together
3. Wait for blockers: Do NOT spawn dependent tasks until blocking tasks have received complete directives
4. Respect the limit: Do NOT exceed 6 concurrent chains
5. Escalation handling: If runtime issues escalate, report to user — do not attempt to fix the chain yourself

Agent Communication

Agents do NOT communicate directly. All coordination flows through the orchestrator:

Inter-agent dependencies:

• Task A produces types.ts
• Task B needs types.ts
• Orchestrator: waits for A to receive complete directive, then spawns B with reference to types.ts location

Shared state:

• All agents read/write .goodvibes/memory/
• Orchestrator checks memory for decisions, patterns, failures before spawning
• Orchestrator logs orchestration decisions to .goodvibes/memory/decisions.json

Mode-Specific Behavior

Vibecoding Mode (Default)

Confirm before initial decomposition:

• Show task breakdown to user before spawning any agents
• Allow user to modify the decomposition
• Only the initial decomposition requires user confirmation; once agents are running, the runtime drives the process

Auto-spawn on ambiguity:

• If task decomposition has multiple valid approaches, pick the most common pattern from memory
• If no pattern exists, make a decision and log it to decisions.json
• Only escalate to user for architectural decisions (auth provider, database choice, etc.)

Error handling:

• Agent retries are managed by the runtime engine (up to max_fix_attempts)
• Runtime will issue escalate directive if max attempts are reached
• On escalate, present to user with context from the directive's reason field

Justvibes Mode (Strict)

Auto-proceed:

• Skip the pre-decomposition confirmation
• Spawn agents immediately after decomposition is complete
• Runtime engine handles all WRFC cycles automatically

Error handling:

• Same as vibecoding — runtime manages fix attempts and issues escalate when exhausted
• Present escalation to user when received

Decomposition Examples

Example 1: Feature Implementation

User request: "Add user profile page with edit capability"

Classification: Feature Implementation

Decomposition:

tasks:
  - task_id: create-profile-types
    agent: engineer
    skills: [gather-plan-apply, precision-mastery, error-recovery, goodvibes-memory]
    description: Create Profile and ProfileUpdate types
    scope:
      files: [src/types/profile.ts]
    blocking: [create-profile-api, create-profile-ui]
    blocked_by: []
    
  - task_id: create-profile-api
    agent: engineer
    skills: [gather-plan-apply, precision-mastery, error-recovery, goodvibes-memory, trpc, prisma]
    description: Implement tRPC routes for profile CRUD
    scope:
      files: [src/server/routers/profile.ts]
    blocking: [create-profile-ui]
    blocked_by: [create-profile-types]
    
  - task_id: create-profile-ui
    agent: engineer
    skills: [gather-plan-apply, precision-mastery, error-recovery, goodvibes-memory, nextjs, react, tailwindcss, shadcn-ui]
    description: Build profile page with edit form
    scope:
      files: [src/app/profile/page.tsx, src/components/ProfileForm.tsx]
    blocking: []
    blocked_by: [create-profile-types]
    
  - task_id: test-profile-feature
    agent: tester
    skills: [gather-plan-apply, precision-mastery, error-recovery, goodvibes-memory]
    description: Create tests for profile feature
    scope:
      files: [src/server/routers/profile.test.ts, src/components/ProfileForm.test.tsx]
    blocking: []
    blocked_by: [create-profile-api, create-profile-ui]

Execution plan:

1. Spawn create-profile-types (no blockers)
2. Wait for complete directive for create-profile-types
3. Spawn create-profile-api and create-profile-ui in parallel (both unblocked)
4. Wait for complete directives for both
5. Spawn test-profile-feature (blocked by API + UI)
6. Wait for complete directive for test-profile-feature
7. Aggregate results and return to user

Note: Review and fix cycles for each agent are handled automatically by the runtime engine via directives. The orchestrator does not schedule them.

Parallelism: 3 waves (types solo -> API + UI parallel -> tests solo)

Example 2: Bug Fix

User request: "Fix login redirect loop on /dashboard"

Classification: Bug Fix

Decomposition:

tasks:
  - task_id: diagnose-redirect-loop
    agent: engineer
    skills: [gather-plan-apply, precision-mastery, error-recovery, goodvibes-memory, nextjs, nextauth]
    description: Identify root cause of redirect loop
    scope:
      files: [src/middleware.ts, src/app/dashboard/page.tsx, src/lib/auth.ts]
    blocking: [fix-redirect-loop]
    blocked_by: []
    
  - task_id: fix-redirect-loop
    agent: engineer
    skills: [gather-plan-apply, precision-mastery, error-recovery, goodvibes-memory, nextjs, nextauth]
    description: Apply fix based on diagnosis
    scope:
      files: [determined by diagnosis]
    blocking: []
    blocked_by: [diagnose-redirect-loop]

Execution plan:

1. Spawn diagnose-redirect-loop
2. Wait for complete directive for diagnosis
3. Spawn fix-redirect-loop with diagnosis context
4. Wait for complete directive for fix
5. Return to user

Parallelism: None (fully sequential: diagnose -> fix)

Example 3: Refactoring

User request: "Extract shared auth logic into reusable hooks"

Classification: Refactoring

Decomposition:

tasks:
  - task_id: plan-refactoring-approach
    agent: architect
    skills: [gather-plan-apply, precision-mastery, error-recovery, goodvibes-memory]
    description: Design the refactoring strategy and hook API
    scope:
      directories: [src/components, src/app]
    blocking: [analyze-auth-patterns]
    blocked_by: []
    
  - task_id: analyze-auth-patterns
    agent: engineer
    skills: [gather-plan-apply, precision-mastery, error-recovery, goodvibes-memory]
    description: Discover all auth usage patterns in components
    scope:
      directories: [src/components, src/app]
    blocking: [create-auth-hooks]
    blocked_by: [plan-refactoring-approach]
    
  - task_id: create-auth-hooks
    agent: engineer
    skills: [gather-plan-apply, precision-mastery, error-recovery, goodvibes-memory, react]
    description: Create hooks based on discovered patterns
    scope:
      files: [src/hooks/useAuth.ts, src/hooks/useRequireAuth.ts]
    blocking: [refactor-components-1, refactor-components-2]
    blocked_by: [analyze-auth-patterns]
    
  - task_id: refactor-components-1
    agent: engineer
    skills: [gather-plan-apply, precision-mastery, error-recovery, goodvibes-memory, react]
    description: Refactor components in src/app to use hooks
    scope:
      directories: [src/app]
    blocking: []
    blocked_by: [create-auth-hooks]
    
  - task_id: refactor-components-2
    agent: engineer
    skills: [gather-plan-apply, precision-mastery, error-recovery, goodvibes-memory, react]
    description: Refactor components in src/components to use hooks
    scope:
      directories: [src/components]
    blocking: []
    blocked_by: [create-auth-hooks]

Execution plan:

1. Spawn plan-refactoring-approach (architect)
2. Wait for complete directive for planning
3. Spawn analyze-auth-patterns
4. Wait for complete directive for analysis
5. Spawn create-auth-hooks
6. Wait for complete directive for hooks
7. Spawn refactor-components-1 and refactor-components-2 in parallel
8. Wait for complete directives for both
9. Return to user

Parallelism: 4 waves (planning -> analysis -> hooks -> 2 refactors parallel)

Escalation Criteria

Escalate to user immediately when:

1. Architectural ambiguity - Multiple valid approaches with significant tradeoffs

   • Example: "Use REST vs GraphQL for new API"
   • Escalation: Present options with pros/cons, request decision

2. Missing information - Task cannot be completed without user input

   • Example: "Which auth provider should we use?"
   • Escalation: List options, explain what's needed

3. Scope expansion - Task is larger than initially described

   • Example: "Adding profile page requires new database schema and migration"
   • Escalation: Show expanded scope, request approval

4. Runtime escalation - Runtime engine issues escalate directive

   • Example: Max fix attempts reached on a work agent
   • Escalation: Present the reason from the directive, request guidance or manual intervention

5. Conflicting requirements - Discovered constraints contradict each other

   • Example: "User wants Prisma but codebase uses Drizzle"
   • Escalation: Explain conflict, request resolution

Summary

Task orchestration workflow:

1. Classify request (feature, bug, refactoring, etc.)
2. Identify parallel opportunities (domains, files, research)
3. Define agent tasks (task structure with blocking/blocked_by)
4. Assign agents and skills (use decision table)
5. Spawn initial work agents with structured prompts
6. Monitor active chains (up to 6 concurrent)
7. Execute <gv> directives from runtime immediately and mechanically
8. Aggregate results when all chains receive complete directives

Key principles:

• Explicit > implicit (file paths, not vague descriptions)
• Parallel when possible, sequential when necessary
• Orchestrator handles initial decomposition; runtime engine handles all WRFC cycles
• Execute directives before any other action — no exceptions
• Escalate on ambiguity in vibecoding, auto-proceed in justvibes
• Use memory to inform decisions and avoid repeating failures