mcp-orchestrator

mcp-orchestrator

This skill is designed for an Orchestrating AI (e.g. Claude, Kilo, Roo Code) to coordinate Kilo (the Executor) using RAG, Worktrees, non-blocking Parallel Execution, Monitoring/Intervention, and Issues Tracking.

Role discipline: delegate, don't implement

You are the architect/orchestrator, not the implementer. When a task is scoped for delegation (a plan/macroplan task, or any request to "implement X" that this skill's description matches), implementation work goes through kilo_implement - not your own Edit/Write tools. This holds even when a task looks small or fast to do yourself; "it's simple, I'll just do it" is exactly how delegation gets silently skipped. If kilo_implement is unavailable or fails, stop and say so instead of implementing in its place - don't silently fall back to doing the work yourself.

The one exception is verification-phase minor fixes: while reviewing a Final Report (Phase 5 below), you may correct a small, obvious issue yourself directly in Kilo's worktree - a typo, a wrong import, a misnamed variable - without a full round-trip. Anything bigger than a handful of lines, or that touches actual logic, goes back to Kilo via kilo_implement(continue_session_id=..., task_instructions="<corrective instructions>"), not a direct edit. When in doubt, delegate rather than fix it yourself.

Logic and Behavior

• Phase 1 - Discovery & RAG: Explore the repository using kilo_rag_search before designing solutions. Do not guess filenames. Use kilo_list_models and kilo_auth_status to ensure Kilo's engine and models are ready.
• Phase 2 - Isolation: kilo_implement has no isolation and no locking by default — it runs directly in working_directory (defaulting to the server's own cwd), and nothing stops a second concurrent writer — another kilo_implement call, or your own git commands — from racing it in the exact same tree. This is not hypothetical: it has caused a real incident (a live git race that reset a branch and nearly dropped in-progress work while the orchestrator was doing its own git surgery in the same checkout Kilo was still committing to). Default to isolating:
  • Pass isolation='worktree' directly on the kilo_implement call (auto-creates .kilo-worktrees/<branch> and runs there) — prefer this over the two-step kilo_create_worktree + working_directory combo, it's one step and harder to forget.
  • Use kilo_create_worktree standalone only when you need the worktree to exist before deciding what to delegate into it.
  • Skip isolation only for a single trivial, quick edit — and even then, if kilo_implement's response is prefixed with a ⚠️ COLLISION WARNING (another task already running against that exact directory), treat it as a stop sign: wait for the other task (kilo_task_status/kilo_task_result), isolate, or pick a different directory. Never proceed past it on the assumption it's a false alarm.
  • The same risk runs in the other direction too: before running your own git commands (rebase, reset, checkout, history rewrites) against a directory, check kilo_task_status for that working_directory first — a still-running kilo_implement task there is exactly the same hazard.
  • Git worktree isolation does NOT isolate shared host resources. Two parallel isolation='worktree' tasks (e.g. comparing two models on the same feature) still run on the same machine, sharing ports, Docker container names, and any file each task's own tooling might write outside its worktree. Observed live: two parallel tasks both starting a dev server on the default port collided, discovered only after both were already running, forcing a cancel-and-relaunch. Before launching tasks in parallel that will each run a server/container/process, explicitly assign each one a distinct port/container name/resource in the task instructions — decide this by design before dispatching, don't wait to discover the collision mid-run.
  • Worktree isolation does NOT isolate the repository's own configuration. .git/config is shared by every worktree of a repo, so a delegated task that runs git config - or any tool that runs it on your behalf, e.g. husky init setting core.hooksPath - writes into the configuration the user's own checkout reads. Observed live: a lint-and-hooks task, correctly isolated in its own worktree, was one command away from installing a pre-commit hook on the user's working checkout of applications in daily production use, where a broken hook would have blocked their real commits. Any task that would touch repo-level configuration must be instructed to create the files and document the activation command instead of running it, and to prove it didn't by showing git config --get <key> returning empty. Activation is the user's call, not the task's.
• Phase 3 - Delegation: Use kilo_implement to delegate implementation work. It runs in the background by default and returns a task_id immediately — never block the conversation waiting on it. Pass focus_files found during search, configure any skills_to_load, and dispatch tasks in parallel across worktrees. For work that spans multiple dependent steps or sessions, write it up first as a plans/ macroplan (see the macroplan-authoring skill) and delegate one task file at a time — each task file is already scoped, self-contained, and has its own verification section, which maps directly onto one well-formed kilo_implement call.
• Phase 4 - Monitoring & Intervention: Scale how closely you watch a task to its complexity/risk:
  • Small, well-scoped tasks: a single kilo_task_result check at the end is enough.
  • Large, multi-file, or high-risk tasks: poll kilo_task_progress periodically or inspect Kilo's live checklist with kilo_get_session_todo. You can also directly inject or update the plan using kilo_update_session_todo to guide execution.
  • A "WORKING" verdict from kilo_task_status is not enough on its own — always cross-check it against kilo_task_progress's cost/tokens/plan before trusting it. That heuristic proves a socket is open to the model, not that the call is converging: a task can sit "connected, long call in progress" for many minutes while burning real cost on every turn. The tell is a low CPU-time/elapsed-time ratio (seconds of CPU across many minutes of wall clock — waiting on the network, not computing) combined with a ballooning cost/token count and no recorded plan, especially after a continue_session_id call resuming a prior session: it usually means the task is re-reading its own accumulated context every turn instead of acting on it. Observed live: a corrective kilo_implement resuming a failed session ran 50+ minutes and $7+ in cost with under two minutes of CPU time and no plan ever recorded — cancelled via kilo_task_cancel and redone directly rather than left to keep burning. Make this cross-check routine, not something reached for only once a task already looks slow.
  • If a task drifts off-spec or looks stuck: kilo_task_cancel stops it (attempts a graceful REST abort, then hard kill by tracked PID). Alternatively, use kilo_session_revert to rewind to a previous checkpoint, or kilo_session_fork to test an alternative path in parallel. If Kilo pauses asking a question, answer with kilo_respond_question. Review kilo_workspace_status for partial changes, then either revert or continue with a corrective kilo_implement call using continue_session_id — Kilo resumes the SAME session with full memory of what it already built, instead of starting blind.
  • Don't go idle after dispatching — check back proactively, don't wait to be asked. kilo_implement returning a task_id immediately means control comes back to you well before the work is done; if you just end your turn there, nothing polls the task until the user happens to ask "how's it going?". If your host exposes a self-scheduled wakeup (e.g. Claude Code's ScheduleWakeup), use it to check progress/result again after a delay. Otherwise, state explicitly in your response how the user can check progress.
  • Ready-to-invoke scripts for the manual/no-task-id case live in scripts/ (see below) — use them instead of re-deriving the pgrep/ps/lsof/sqlite3 diagnostic pipeline from scratch each session.
• Phase 5 - Verification & Review: NEVER trust the Final Report alone. Inspect results with kilo_workspace_status, then actually execute what was built — reading the report or the diff is not verification, it's a summary. Across real delegation rounds, deviations that never surfaced from the report alone only showed up by running the code: a file committed that should have been gitignored, a cited source path that didn't exist anywhere in the codebase (invented for plausibility), a citation pointing at the right method but the wrong line, DB column types guessed from convention instead of read from the real DDL already available. Calibrate to what was built:
  • Backend: actually start the app against a real seeded database, don't just read the JPA annotations — a schema validation mode that passes silently is much stronger evidence than a visual read. Hit the endpoints with real curl calls (200/401/etc.), don't assume them from the controller code.
  • Frontend: actually run the build and test suite (headless browser if needed), don't stop at reading the .ts files.
  • Schema/data: if a file is claimed "copied verbatim" from a source, diff it for real against that source — don't trust the claim.
  • Infra: if there's a docker-compose.yml, actually bring it up, wait for the healthcheck, and query the resulting service/DB for real.
  • See the task-spec-authoring skill for calibrating verification depth to task risk in more detail.
• Phase 5b - Verify the integration, not only the tasks. Every task in a batch can be green in its own worktree and the merged result still be broken: tasks branched from the same commit cannot see each other. Observed live: two tasks in one batch each declared their own BBox type in the same library; lint and unit tests stayed green in both worktrees and after the merge, and only the application build caught it (a duplicate-export error on the library's barrel file). The integration gate is therefore not the union of the tasks' own criteria: after every merge run lint, tests, and a full build of a consuming application, and treat that as the batch's real acceptance.
• Phase 6 - Closure & Telemetry: If defects are found, log them with kilo_log_issue (vital for continuous prompt/specification tuning — see mcp-metrics-analyst) and request Kilo to fix them.
  • Merging: always checkout the target branch explicitly first. Running git merge --no-ff <feature-branch> -m "..." <target> without checking out <target> first is a real, observed mistake - the trailing <target> argument gets interpreted as another branch to merge IN, not as the destination, so the merge silently lands on whatever branch you happened to be on. Correct sequence, every time: git status --short (clean) → git checkout <target> (explicit, never implicit) → git merge --no-ff <feature-branch> -m "..." → git log --oneline --graph -6 (confirm the merge landed where intended). Remove the worktree once merged and no longer needed (git worktree remove <path>).