name: project-orchestration description: Orchestrate multi-agent workflows for feature development using planning agents, context handoff, and stage management version: 1.0.0 author: opencode type: skill category: orchestration tags:

orchestration
multi-agent
planning
workflow
stages ---

Project Orchestration Skill

Purpose: Orchestrate multi-agent workflows for feature development

What I Do

Coordinate multi-agent planning and execution workflows:

Pass minimal context between planning agents
Track planning agent outputs
Manage 8-stage feature delivery workflow
Maintain planning session state

Three Workflows

1. Context Handoff (Lightweight)

Pass minimal context between agents (RECOMMENDED for automation)

Commands: create, get-context, add-output, show
Use when: Orchestrating planning agents
See: workflows/context-handoff.md

2. Session Context (Interactive)

Human-readable planning narrative (for debugging/review)

Commands: session-create, session-load, session-summary
Use when: Debugging or reviewing planning sessions
See: workflows/context-handoff.md

3. Multi-Stage Delivery (8 Stages)

Full feature delivery workflow

Commands: stage-init, stage-status, stage-complete, stage-rollback
Use when: Running complete 8-stage feature workflow
See: workflows/8-stage-delivery.md

Quick Start

Context Handoff Workflow

# Create context index
bash .opencode/skill/project-orchestration/router.sh create auth-system

# Get minimal context for specific agent
bash .opencode/skill/project-orchestration/router.sh get-context auth-system StoryMapper

# Track agent output
bash .opencode/skill/project-orchestration/router.sh add-output auth-system ArchitectureAnalyzer .tmp/architecture/auth-system/contexts.json

# Show full index
bash .opencode/skill/project-orchestration/router.sh show auth-system

8-Stage Workflow

# Initialize workflow
bash .opencode/skill/project-orchestration/router.sh stage-init auth-system

# Check status
bash .opencode/skill/project-orchestration/router.sh stage-status auth-system

# Mark stage complete
bash .opencode/skill/project-orchestration/router.sh stage-complete auth-system 1

# Rollback if needed
bash .opencode/skill/project-orchestration/router.sh stage-rollback auth-system 1

Command Reference

Context Management

Command	Description
`create <feature>`	Create context index for feature
`get-context <feature> <agentType>`	Get minimal context for specific agent
`add-output <feature> <agent> <path>`	Track agent output
`show <feature>`	Show full context index

Session Management

Command	Description
`session-create <feature> <request>`	Create session context
`session-load <sessionId>`	Load session context
`session-summary <sessionId>`	Get session summary

Stage Management

Command	Description
`stage-init <feature>`	Initialize 8-stage workflow
`stage-status <feature>`	Show stage progress
`stage-complete <feature> <stage>`	Mark stage complete
`stage-rollback <feature> <stage>`	Rollback stage
`stage-validate <feature> <stage>`	Validate stage
`stage-abort <feature>`	Abort workflow

Architecture

.opencode/skill/project-orchestration/
├── SKILL.md                          # This file
├── router.sh                         # CLI router
├── scripts/
│   ├── context-index.ts              # Lightweight context handoff
│   ├── session-context-manager.ts    # Session context management
│   └── stage-cli.ts                  # 8-stage workflow management
└── workflows/
    ├── context-handoff.md            # Detailed context handoff guide
    ├── 8-stage-delivery.md           # Detailed 8-stage workflow guide
    └── planning-agents.md            # Planning agents integration guide

File Locations

Scripts

Context Index: .opencode/skill/project-orchestration/scripts/context-index.ts
Session Context: .opencode/skill/project-orchestration/scripts/session-context-manager.ts
Stage CLI: .opencode/skill/project-orchestration/scripts/stage-cli.ts

Runtime Files

Context Index: .tmp/context-index/{feature}.json
Sessions: .tmp/sessions/{session-id}/context.md
Stage Tracking: .tmp/sessions/{session-id}/stage-tracking.json

Workflow Guides

Context Handoff: .opencode/skill/project-orchestration/workflows/context-handoff.md
8-Stage Delivery: .opencode/skill/project-orchestration/workflows/8-stage-delivery.md
Planning Agents: .opencode/skill/project-orchestration/workflows/planning-agents.md

Context Handoff Pattern

Lightweight Context Index (RECOMMENDED)

Use when: Multi-agent pipelines, performance-critical workflows, automated orchestration

How it works:

Orchestrator maintains lightweight index (.tmp/context-index/{feature}.json)
Each agent gets ONLY the files they need
83% reduction in context per agent

Example:

import { createContextIndex, getContextForAgent, addAgentOutput } from './scripts/context-index';

// Create index
createContextIndex('auth-system', { request: 'Build JWT auth' });

// Get minimal context for StoryMapper
const context = getContextForAgent('auth-system', 'StoryMapper');
// Returns: { contextFiles: [...], agentOutputs: { ArchitectureAnalyzer: "..." } }

// After agent completes, update index
addAgentOutput('auth-system', 'StoryMapper', '.tmp/story-maps/auth-system/map.json', 
  { verticalSlice: 'user-login' });

Benefits:

✅ Minimal context per agent (only what they need)
✅ Fast (small JSON files)
✅ Scalable (index stays small)
✅ Clear dependencies (explicit file paths)

Session Context (Interactive)

Use when: Interactive sessions, human review, debugging, narrative tracking

How it works:

Creates markdown file (.tmp/sessions/{session-id}/context.md)
Human-readable narrative of entire workflow
All agents read/update same file

Example:

import { createSession, updateSession, markStageComplete } from './scripts/session-context-manager';

// Create session
const sessionId = await createSession('auth-system', {
  request: 'Build JWT authentication',
  contextFiles: ['.opencode/context/core/standards/code-quality.md'],
  exitCriteria: ['All endpoints implemented']
});

// Update after agent completes
await updateSession(sessionId, {
  architectureContext: { boundedContext: 'authentication' }
});

await markStageComplete(sessionId, 'Stage 1: Architecture Decomposition', [
  '.tmp/architecture/auth-system/contexts.json'
]);

Benefits:

✅ Human-readable (markdown format)
✅ Complete narrative (see entire workflow)
✅ Good for debugging (trace decisions)
✅ Audit trail (who did what when)

Comparison

Feature	Context Index	Session Context
Format	JSON	Markdown
Size	Small (~200 lines)	Large (2000+ lines)
Audience	Agents only	Humans + Agents
Context per agent	Minimal (2-5 files)	Everything (all files)
Performance	Fast	Slower
Use case	Automated pipelines	Interactive sessions
Human readable	No	Yes
Debugging	Harder	Easier

Recommendation

For most multi-agent workflows: Use Context Index (lightweight, fast, minimal context per agent)

For interactive development: Use Session Context (human-readable, complete narrative)

You can use both: Context Index for automation, Session Context for human review

8-Stage Delivery Workflow

The Multi-Stage Orchestration Workflow provides a systematic approach to complex feature development:

Stages

Architecture Decomposition - Define system boundaries and components
Story Mapping - Map user journeys and create stories
Prioritization - Sequence work by value and dependencies
Enhanced Task Breakdown - Create atomic, executable tasks
Contract Definition - Define interfaces before implementation
Parallel Execution - Execute independent work simultaneously
Integration & Validation - Integrate and validate components
Release & Learning - Deploy and capture insights

Stage Management

# Initialize workflow
bash .opencode/skill/project-orchestration/router.sh stage-init auth-system

# Check status
bash .opencode/skill/project-orchestration/router.sh stage-status auth-system

# Validate stage readiness
bash .opencode/skill/project-orchestration/router.sh stage-validate auth-system 1

# Mark stage complete
bash .opencode/skill/project-orchestration/router.sh stage-complete auth-system 1

# Rollback if needed
bash .opencode/skill/project-orchestration/router.sh stage-rollback auth-system 1

# Abort workflow
bash .opencode/skill/project-orchestration/router.sh stage-abort auth-system

Stage Tracking

Stage tracking files are stored in .tmp/sessions/{timestamp}-{feature}/stage-tracking.json

Each stage tracks:

Status (pending, in_progress, completed, failed)
Start and completion timestamps
Outputs produced
Validation results
Error messages (if failed)

Planning Agents Integration

The orchestration skill integrates with planning agents to enrich task metadata:

ArchitectureAnalyzer

Provides bounded_context and module fields based on domain analysis.

StoryMapper

Provides vertical_slice field for feature slice architecture.

PrioritizationEngine

Provides rice_score, wsjf_score, and release_slice fields for prioritization.

ContractManager

Provides contracts array for API/interface dependencies.

ADRManager

Provides related_adrs array for architectural decision references.

See workflows/planning-agents.md for detailed integration guide.

Best Practices

Context Handoff

Use Context Index for automated pipelines
Use Session Context for human review
Update index immediately after agent completes
Keep metadata small and useful

Stage Management

Validate stage prerequisites before execution
Mark stages complete only when all criteria met
Document rollback reasons
Track stage outputs for traceability

Planning Integration

Call ArchitectureAnalyzer for complex domain logic
Use StoryMapper for user journey mapping
Apply PrioritizationEngine for MVP identification
Define contracts with ContractManager for parallel dev
Document decisions with ADRManager

SKILL.md 11 KB

Historie Surový

Project Orchestration Skill

What I Do

Three Workflows

1. Context Handoff (Lightweight)

2. Session Context (Interactive)

3. Multi-Stage Delivery (8 Stages)

Quick Start

Context Handoff Workflow

8-Stage Workflow

Command Reference

Context Management

Session Management

Stage Management

Architecture

File Locations

Scripts

Runtime Files

Workflow Guides

Context Handoff Pattern

Lightweight Context Index (RECOMMENDED)

Session Context (Interactive)

Comparison

Recommendation

8-Stage Delivery Workflow

Stages

Stage Management

Stage Tracking

Planning Agents Integration

ArchitectureAnalyzer

StoryMapper

PrioritizationEngine

ContractManager

ADRManager

Best Practices

Context Handoff

Stage Management

Planning Integration

See Also

SKILL.md 11 KB Historie Surový

Project Orchestration Skill

What I Do

Three Workflows

1. Context Handoff (Lightweight)

2. Session Context (Interactive)

3. Multi-Stage Delivery (8 Stages)

Quick Start

Context Handoff Workflow

8-Stage Workflow

Command Reference

Context Management

Session Management

Stage Management

Architecture

File Locations

Scripts

Runtime Files

Workflow Guides

Context Handoff Pattern

Lightweight Context Index (RECOMMENDED)

Session Context (Interactive)

Comparison

Recommendation

8-Stage Delivery Workflow

Stages

Stage Management

Stage Tracking

Planning Agents Integration

ArchitectureAnalyzer

StoryMapper

PrioritizationEngine

ContractManager

ADRManager

Best Practices

Context Handoff

Stage Management

Planning Integration

See Also

SKILL.md 11 KB

Historie Surový