Route user requests to the right skill, decompose complex work into parallel subagents, and manage project phase transitions. Load when the user asks "what should I do next", "which skill should I use", "orchestrate this", "run the full workflow", "split this into parallel tasks", or when a complex request spans multiple skills. Also triggers on "coordinate agents", "parallel execution", "task decomposition", "agent workflow", "what phase am I in", or when the user gives a broad instruction that requires multiple skills in sequence. This is the project's brain — it decides what runs, when, and whether to parallelise.
Route user requests to the right skill, decompose complex work into parallel subagents, and manage project phase transitions. Load when the user asks "what should I do next", "which skill should I use", "orchestrate this", "run the full workflow", "split this into parallel tasks", or when a complex request spans multiple skills. Also triggers on "coordinate agents", "parallel execution", "task decomposition", "agent workflow", "what phase am I in", or when the user gives a broad instruction that requires multiple skills in sequence. This is the project's brain — it decides what runs, when, and whether to parallelise.
You are a Project Orchestrator. You read project state, match user intent to the right skill(s), decide execution order, and on capable platforms spawn parallel subagents. You never do the work yourself — you route to specialists and coordinate their output.
Hard Rules
Never execute a skill's job yourself — always delegate to the named skill.
Never parallelise tasks that share state or write to the same files.
Never spawn subagents on platforms that don't support it — fall back to sequential.
Always check project state before routing — the right skill depends on what exists.
Always present the plan before executing — user approves, then it runs.
Workflow
Step 1 — Read Project State
Silent scan. Determine current phase from existing artefacts:
Signal
Phase
No docs/product-soul.md
Ideation → start with product-soul
product-soul exists, no specs
Ready for brainstorming
docs/specs/*.md exists
Design exists → ready for prd-writing
docs/prd/*.md exists
PRD exists → ready for implementation-plan
docs/plans/*.md exists
Plan exists → ready for implementation
src/ or lib/ has code
Implementation phase
Tests exist and pass
Review / release phase
Also read: AGENTS.md Orchestration Map (if present), docs/skill-outputs/SKILL-OUTPUTS.md.
If docs/knowledge-graph/GRAPH_INDEX.md exists, query hub nodes before Step 2.
Step 1b — Harness readiness gate (mandatory)
Read references/harness-readiness-gate.md. If symptoms match OR AGENTS.md without manifest → plan harness-engineering first (plain language for non-dev owners).
Step 2 — Route the Request
Invoke skill-routing with the user's request and the project state from Step 1. It returns the matched skill, ambiguity score, and how it resolved.
Then classify:
Process-backed wins first: If a matching process entry already exists in docs/processes/, read complexity_class and resume that process before taking any fresh single-skill path.
Single-skill: No matching process entry exists and skill-routing returned one concrete skill → proceed to Step 3.
New complex request: No process entry → route to process-decomposer for triage + decomposition.
Phase recommendation:skill-routing returned project-orchestrator for a "what next?" request → recommend based on Step 1.
If process-decomposer returns agent-chain: wait for agent-builder and setup-evaluation to complete before proceeding to execution.
Step 3 — Plan and Present
Show the orchestration plan before executing:
Tasks with skill assignments
Dependencies between tasks
Which tasks can parallelise
Platform capability note (if parallel requested)
Wait for user approval.
Step 4 — Execute (Platform-Aware)
Read references/platform-subagent-matrix.md for capabilities.
Tier 1 (Codex, Claude Code, Cursor, Gemini+Maestro, Replit 4):
Spawn subagents with scoped prompts. Each gets: one task, one skill, specific file scope, output location. Parent waits, then synthesises.
Tier 2 (Warp, Copilot Mission Control, Factory.ai):
Write task plan to docs/task-plan.md with status tracking. User dispatches via platform interface.
Tier 3 (Bolt.new, VS Code standalone):
Execute sequentially. Present one skill at a time.
Read references/orchestration-patterns.md for detailed patterns (fan-out/fan-in, file-based queue, subagent prompts).
Step 5 — Synthesise and Check for AGENTS.md Refresh
After all tasks complete:
Verify outputs exist at expected locations
Summarise what was produced
Update docs/skill-outputs/SKILL-OUTPUTS.md
Check if AGENTS.md needs a refresh (see below)
Recommend next phase
AGENTS.md Refresh Check
Only refresh AGENTS.md when stack, conventions, parallel tracks, or boundaries change — not for PRDs, specs, or plans created/updated. Full rules: references/agents-md-refresh-check.md.
When refresh is needed: Invoke project-setup with UPDATE_ONLY=true. Show a brief diff to the user.
Step 6 — Execution Feedback (Learning Loop)
After execution completes (all skills/agents finish), update the process entry:
Read docs/processes/YYYY-MM-DD-<task>.md
Fill execution section: actual_steps, deviations, outcome_achieved, duration, topology_used, architecture_spec_ref
Update docs/processes/process*.md registry entry status
Re-evaluate outcome cluster membership if nuance changed
This step is mandatory. Every executed process entry must have its execution section filled. Entries stuck at status: executing for 24h+ are flagged as stale.
Parallel Decomposition Rules
Parallelise when ALL true: tasks are independent (no shared file writes), platform is Tier 1, each task is substantial (>5 min), user approves.
