# Project Orchestration > Orchestrate multi-agent workflows for feature development using planning agents, context handoff, and stage management Use when this capability is needed. - Skill: `tomevault-io/project-orchestration-2` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/project-orchestration-2` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/project-orchestration-2/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/project-orchestration-2 --- # 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 ```bash # 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 ```bash # 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 ` | Create context index for feature | | `get-context ` | Get minimal context for specific agent | | `add-output ` | Track agent output | | `show ` | Show full context index | ### Session Management | Command | Description | |---------|-------------| | `session-create ` | Create session context | | `session-load ` | Load session context | | `session-summary ` | Get session summary | ### Stage Management | Command | Description | |---------|-------------| | `stage-init ` | Initialize 8-stage workflow | | `stage-status ` | Show stage progress | | `stage-complete ` | Mark stage complete | | `stage-rollback ` | Rollback stage | | `stage-validate ` | Validate stage | | `stage-abort ` | 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**: ```typescript 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**: ```typescript 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 1. **Architecture Decomposition** - Define system boundaries and components 2. **Story Mapping** - Map user journeys and create stories 3. **Prioritization** - Sequence work by value and dependencies 4. **Enhanced Task Breakdown** - Create atomic, executable tasks 5. **Contract Definition** - Define interfaces before implementation 6. **Parallel Execution** - Execute independent work simultaneously 7. **Integration & Validation** - Integrate and validate components 8. **Release & Learning** - Deploy and capture insights ### Stage Management ```bash # 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 ## See Also - Task Management: `.opencode/skill/task-management/SKILL.md` - Planning Agents Guide: `.opencode/docs/agents/planning-agents-guide.md` - Multi-Stage Orchestration: `.opencode/context/core/workflows/multi-stage-orchestration.md` --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/darrenhinde) — claim your Tome and manage your conversions.