orchestra-loop
Multi-agent orchestra — plan → implement → verify → review. Cursor: ambient hooks + Task subagent_type. OpenCode: orchestra conductor + subagent tool. Use for build/fix/refactor, agent loop, or cross-platform orchestra setup.
- License 许可
- MIT
- 最近更新
- 2026-11-13
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- orchestra-loop
- description
- Multi-agent orchestra — plan → implement → verify → review. Cursor: ambient hooks + Task subagent_type. OpenCode: orchestra conductor + subagent tool. Use for build/fix/refactor, agent loop, or cross-platform orchestra setup.
03 SKILL.md 正文
Orchestra Loop (Cursor + OpenCode + Qoder)
- Cursor: runs via
~/.cursor/hooks — ambient auto-start; spawn with Task +subagent_type. - OpenCode: runs via
~/.config/opencode/— user talks to orchestra conductor; spawn with subagent +agentname (V1taskis retired; runtime requires OpenCode V2). - Qoder: runs via
~/.qoder/settings.jsonhooks like Cursor — spawn with Agent +subagent_type.
You do not need /orchestra on Cursor when ambient mode is ON.
Cross-platform (Cursor + OpenCode)
Same four phase agent names; different spawn tool and chaining.
| Cursor IDE | OpenCode CLI / desktop | |
|---|---|---|
| User entry | Main Agent (ambient hooks) or orchestra conductor |
orchestra only (default_agent) |
| Spawn tool | Task (capital T) | subagent (V2; V1 task retired) |
| Spawn param | subagent_type="orchestra-planner" |
agent="orchestra-planner" + description |
| Phase chain | Hooks subagentStop auto-advance |
Conductor calls subagent once per phase |
| Phase visibility | Task picker | hidden: true — not in @ menu |
Full matrix: docs/orchestra-cross-platform.md · agent ref: references/orchestra-spawn-matrix.md
Cursor Task limitation (conductor fallback)
If Cursor Task rejects subagent_type=orchestra-* (enum / unknown agent), the parent MUST keep the loop alive: run phases itself or spawn generalPurpose loaded with instructions from ~/.cursor/agents/orchestra-*.md. Do not stop the loop. Hooks still match those names when custom agents work.
Anti-stop (CRITICAL — Cursor conductor)
When orchestra is active, or the user said continue / until finish / do all / don't stop:
- Do not end turns with “Done / Next (1)(2)(3)” choice menus that wait for the user.
- After
PLAN_READY→ immediately implement → commit → verify → review in the same run (conductor fallback). - After
ORCHESTRA_COMPLETE, if the plan Handoff / user goal still has unfinished work →orchestra-enable.js start "<next goal>"and run the next loop immediately. - Only stop when: user goal is fully done, user says stop, or 5 resumes fail on one phase — then one short summary (no multi-option Next menu).
- Small-tasks “Done + Next” does not apply while orchestra is active or “continue until finish” is in effect.
Conductor-first entry
Do NOT pick
orchestra-planner,orchestra-implementer,orchestra-verifier, ororchestra-revieweras the user entry on OpenCode. On Cursor, ambient hooks may launch the first phase directly; optionalorchestraconductor uses Task +subagent_type. Hook matchers require exactorchestra-*names — do not rename them.
Models & preflight
Model IDs are assigned dynamically — no hardcoded free-model IDs here.
Agents inherit the main/global model (and small_model) from opencode.json.
Per-agent model: frontmatter is stripped by --apply.
| Role | Primary model | Fallback chain |
|---|---|---|
| all agents (inherit) | global model (set by --apply from highest-stability probe-reachable free model) |
global small_model / heavy free pool fallback |
| frontend variants | same global model | frontend pool head only if explicitly set in config |
Before use: run bash scripts/update-free-models.sh --refresh then bash scripts/update-free-models.sh --probe to validate configured models respond (not just listed).
Auto pools: --refresh regenerates ~/.config/opencode/state/model-pools.json ordered by probes.json reachability/stability; --pools prints them; --apply rewrites global model only and strips agent hardcodes; --schedule installs the weekly refresh timer.
On model error: run --refresh --probe --apply to re-fetch, re-probe, and re-assign the global model, then retry.
Ambient mode (default ON)
When the user asks to add, fix, build, refactor, deploy, install, configure, migrate, integrate, debug, continue, improve, or finish something:
beforeSubmitPromptclassifies the prompt and selects a route:- core (default) — plan → implement → verify → review
- enterprise — full SDLC when
/enterpriseor high complexity signals (architecture, migration, multi-service, security audit, etc.) - informal — short/casual goals still start core with
inferFromContext(planner expands from progress-tracker/git)
- Parent launches the first agent (orchestra-planner for core; discovery agent for enterprise idea).
- Hooks chain subsequent phases via
subagentStop.
Skipped for: explain-only questions, "what is/how does", "no orchestra", "just explain", trivial hi/thanks.
Adaptive routing
| Route | Trigger | Start phase | Loop |
|---|---|---|---|
| core | Normal implement/fix/build | plan |
4 core agents |
| enterprise | /enterprise or complexity signals (beats informal shortness) |
idea |
32-phase SDLC specialists |
| informal | Short/casual ("fix it", "pls", "next improve") | plan | Infer from progress-tracker/git; planner expands |
Planner (or discovery planning) always runs before implementation.
Project-type specialist inserts (core loop): for medium/complex PROJECT SCOPE, the conductor inserts the type's missing specialists into the spine — e.g. web/mobile/saas → product-owner + ui-ux-designer + project-manager before implement, frontend/mobile-engineer in implement, qa/accessibility in verify; api → product-manager + architect + project-manager, backend/database-engineer, api-contract-validator. See the conductor routing table. Inserts end with their own tokens (DESIGN_SPEC_COMPLETE, TASK_BREAKDOWN_COMPLETE).
Corporate tier (large org / multi-team / program / portfolio): conductor escalates to agent-selector → project-type-classifier → workflow-orchestrator → per-track Full Delivery loops each with its own scrum-master + project-manager, a governance committee (business-strategist, product-owner, product-manager, stakeholder-advocate at design; compliance-officer, legal-advisor, security-executive-advisor at release), and corporate close (release-manager, ops-manager, documentation-writer, sre/observer, incident-responder).
After updating hooks, always re-run bash install.sh (it replaces hooks/lib). Restart Cursor.
Phases
| # | Subagent | Role | Git workflow |
|---|---|---|---|
| 1 | orchestra-planner |
Plan only (readonly) |
No commit — plan → .cursor/orchestra-plan.md |
| 2 | orchestra-implementer |
Minimal implementation | Must commit before IMPLEMENT_DONE / before verify |
| 3 | orchestra-verifier |
Tests / lint / smoke | No commit — VERIFY_FAIL if dirty tree |
| 4 | orchestra-reviewer |
Final gate (readonly) |
Suggest docs commit; parent commits docs if dirty |
FIX_REQUIRED / VERIFY_FAIL → hooks loop back to orchestra-implementer (which commits fixes before re-verify).
Phase commit gate (hard rule)
Commit each part before the next part starts.
- Parent runs
git status --porcelainbefore launching the next subagent - Dirty tree (except
.cursor/orchestra-plan.md) → commit/discard first — do not advance - Implementer: empty porcelain required before
IMPLEMENT_DONE - Verifier: dirty code →
VERIFY_FAIL - After
ORCHESTRA_COMPLETE: parent commits remaining docs (progress-tracker) if dirty
Git commit convention
All commits follow: <type>(<scope>): <description>
Types: feat, fix, refactor, test, docs, chore
- Planner includes commit strategy in the plan (phase-gated commits)
- Implementer commits after ALL changes (not mid-implementation) — required before next phase
- Verifier checks
git status --porcelainfor clean tree - Reviewer reviews commit messages; parent may make a docs commit after ORCHESTRA_COMPLETE
Self-review & error-free rules
Each subagent has a self-review checklist and error-free rules:
| Subagent | Key self-review | Error-free rule |
|---|---|---|
| Planner | Goal clear, files exist, done-when testable | No assumptions about undocumented behavior |
| Implementer | All plan items done, no scope creep, committed | Zero tolerance: syntax, debug code, secrets |
| Verifier | All checks run, git clean, verdict clear | Never skip, never assume PASS, never fix code |
| Reviewer | Read actual diff, findings are file:line, verdict matches | Never approve if tests fail or secrets in code |
User commands
| Command | Action |
|---|---|
| (normal coding prompt) | Auto-orchestrate if implement/fix/build |
/orchestra <goal> |
Force start (core route) |
/enterprise <goal> |
Force enterprise SDLC route |
/orchestra stop |
Stop active loop |
disable orchestra |
Turn ambient off |
enable orchestra |
Turn ambient on |
no orchestra |
Skip for this prompt |
CLI
node $env:USERPROFILE\.cursor\hooks\orchestra-enable.js status
node $env:USERPROFILE\.cursor\hooks\orchestra-enable.js tokens
node $env:USERPROFILE\.cursor\hooks\orchestra-enable.js ambient-off
node $env:USERPROFILE\.cursor\hooks\orchestra-enable.js ambient-on
node $env:USERPROFILE\.cursor\hooks\orchestra-enable.js stop
Parent agent rules
- Use Task with
orchestra-*names — hooks matchers require exact names. - Do not nest orchestra inside orchestra.
- After
ORCHESTRA_COMPLETE, summarize and runorchestra-enable.js stop. - Do not modify files between phases — let subagents handle their own work.
- Do not commit between phases — implementer commits, others are read-only.
- Works in Cursor IDE Agent (user hooks). Not cloud agents unless project hooks copied.
Hooks
| Event | Role |
|---|---|
sessionStart |
Inject ambient policy every session |
beforeSubmitPrompt |
Auto-start on implement prompts |
subagentStop |
Chain next phase |
stop |
Nudge if parent stalled |
Opt out
Say "no orchestra" or run ambient-off. Pure Q&A never triggers the chain.
Heartbeat & stall detection
Heartbeat timestamps are written on every hook execution. If a phase runs >5min (configurable), stall detection emits recovery nudges. After 2 stalls, orchestration aborts.
Memory
- Short-term: Tracked during each run (phases, files, errors, decisions). Available to subagents.
- Long-term: Persistent
~/.cursor/hooks/state/orchestra-memory.json. Planner reads past goals/errors; reviewer writes lessons.
node ~/.cursor/hooks/orchestra-enable.js memory # View
node ~/.cursor/hooks/orchestra-enable.js memory clear # Clear
Resumable tasks
- Crash recovery:
sessionStartdetects stale state, offers resume via "resume orchestra" - Manual pause/resume:
pause [reason]/resumecommands or chat - Checkpoint:
checkpointsaves state without pausing
Lifecycle events
Every phase transition recorded to state. Last 200 events retained. Phase durations tracked.
Six-File Context
If the workspace has context/project-overview.md (Six-File Context Methodology), hooks inject read order at session start. Subagents read present context/*.md files before acting.
For product UI: use skills ui-ux-pro-max, brand, design-system, ui-styling, web-design-master; persist tokens into context/ui-context.md (see template Skills section).
Bootstrap in any project:
bash /path/to/pcore-orchestra/scripts/init-context.sh /path/to/your-app --bridge
Token efficiency
Orchestra cycles cost 3–10× a single chat turn. Default policy:
| Phase | Web | Tool focus | Budget |
|---|---|---|---|
| Planner | Avoid | grep/glob → targeted read | ~10k |
| Implementer | Plan only | scoped reads, parallel batch | ~30k |
| Verifier | Never | shell checks, one-line failures | ~15k |
| Reviewer | Never | diff only | ~8k |
Parent rules: pass concise goal + plan summary to subagents; no file reads between phases; subagents may use websearch/webfetch freely (targeted queries) and must honor the latest-stable-only version policy.
Full guide: docs/token-optimization.md. OpenCode: copy docs/opencode.json.example or run bash scripts/setup-opencode-optimal.sh --balanced.
Harness / agents / prompts: docs/agent-harness-recommendations.md.
Concurrent Session Guard (session-claims)
Other AI sessions may be editing the same repo at the same time. Before implementing, and again before committing:
bash <orchestra>/scripts/session-claims.sh check "$PWD" <paths-you-will-touch>
- Exit 1 = another LIVE session holds a claim on those paths → coordinate or wait.
- Claim your own work at phase start, renew on long operations, release when done:
bash scripts/session-claims.sh claim "$PWD" --scope "app/,packages/" --task "goal text"
bash scripts/session-claims.sh renew "$PWD"
bash scripts/session-claims.sh release "$PWD"
Claims auto-expire after 30 min without heartbeat (gc purges them). Set
PCORE_SESSION_ID in your session env for stable identity across shells.
04 同仓库更多 Skills
wrangler
Cloudflare Workers CLI for deploying, developing, and managing Workers, KV, R2, D1, Vectorize, Hyperdrive, Workers AI, Containers, Queues, Workflows, Pipelines, and Secrets Store. Load before running wrangler commands to ensure correct syntax and best practices. Biases towards retrieval from Cloudflare docs over pre-trained knowledge.
workers-best-practices
Reviews and authors Cloudflare Workers code against production best practices. Load when writing new Workers, reviewing Worker code, configuring wrangler.jsonc, or checking for common Workers anti-patterns (streaming, floating promises, global state, secrets, bindings, observability). Biases towards retrieval from Cloudflare docs over pre-trained knowledge.
web-perf
Analyzes web performance using Chrome DevTools MCP. Measures Core Web Vitals (LCP, INP, CLS) and supplementary metrics (FCP, TBT, Speed Index), identifies render-blocking resources, network dependency chains, layout shifts, caching issues, and accessibility gaps. Use when asked to audit, profile, debug, or optimize page load performance, Lighthouse scores, or site speed. Biases towards retrieval from current documentation over pre-trained knowledge.
web-design-master
Professional web design standard ("AI Professional Web Design Master Prompt") covering page/section/layout design, visual hierarchy, color systems, typography scales, 8-point grid spacing, responsive breakpoints, accessibility, and design QA review. Use when designing or building any page, section, or layout so it looks deliberately designed by a professional product team rather than a generic AI template.
verification-before-completion
Require command evidence before claiming done. Use proactively before VERIFY_PASS, ORCHESTRA_COMPLETE, or "all fixed" statements. Run tests, lint, health, or git checks — never trust claims without output.
ui-ux-pro-max
UI/UX design intelligence for web and mobile. Searchable local database with 84 styles, 192 color palettes, 74 font pairings, 192 product types, 98 UX guidelines, 104 icon entries, 16 GSAP motion presets, and 25 chart types across 22 stacks (React, Next.js, Vue, Nuxt, Svelte, Astro, SwiftUI, React Native, Flutter, Tailwind, shadcn/ui, Jetpack Compose, Angular, Laravel, JavaFX, WPF, WinUI, Avalonia, Uno Platform, UWP, Three.js, and HTML/CSS). Use when designing, building, or reviewing UI: pages, components, color schemes, typography, layout, accessibility, animation, or data visualization.