local-coding-orchestrator

---

name: local-coding-orchestrator description: Use OpenClaw as a supervisor-driven orchestration scaffold for local coding CLIs such as Codex, Claude Code, and OpenCode. Supports task records, lifecycle transitions, worker launch and reconcile, retry briefs, pipeline presets, and environment-aware blocking for local coding workflows.

---

Local Coding Orchestrator

Use this skill to run OpenClaw as a lightweight supervisor for local coding CLIs.

This skill has evolved from a routing helper into a v2 orchestration scaffold. The goal is not just to route prompts to tools. The goal is to intake coding work, assign it to the right local worker, track objective progress, coordinate review, reconcile background execution, and retry intelligently until the task reaches a clear done state or a clear blocked state.

Mission

Use this skill when the user wants OpenClaw to act like an orchestration layer above local coding tools.

That includes cases such as:

choosing between codex, claude, and opencode

running implementation and review as separate worker roles

comparing outputs across tools

steering long-running local coding sessions

supervising coding work through task files, status transitions, and review loops

This skill is for persistent orchestration, not just one-off prompt forwarding.

Strict supervisor boundary

Default stance: this skill is a supervisor, coordinator, and reviewer of work, not the hands-on implementer.

That means OpenClaw should normally:

define the task

choose and launch the right worker

reconcile worker output

verify objective checks

route to review / retry / hardening

report progress and decisions back to the user

And OpenClaw should normally not:

directly edit product code that belongs to the delegated task

silently replace a failed worker by doing the implementation itself

mix coordinator voice with implementer voice in the same phase

report a task as complete based only on a worker saying it is done

When direct edits are allowed

Direct edits by the supervisor are the exception, not the default.

Allowed cases:

fixing the orchestrator skill itself

repairing task metadata, task records, or orchestration scripts

making tiny non-product changes required to unblock supervision

explicit user instruction to take over implementation directly

If the supervisor makes a direct edit, it should say so clearly and distinguish:

what was supervisor-layer work

what was worker-layer implementation

Worker-first policy

For coding tasks inside the target repo, prefer this order: 1. probe with a worker when environment viability is unclear 2. implement with a worker 3. review with a reviewer worker or explicit supervisor review phase 4. harden via a worker retry brief if review requests changes

Do not collapse these into one hand-wavy pass unless the user explicitly asks for speed over strict orchestration.

Multi-worker orchestration

When the task benefits from multiple tools, the supervisor should assign distinct roles instead of letting every worker do everything.

Recommended pattern:

one primary implementer

one reviewer / planner

one secondary reviewer or alternate implementer

The supervisor should then periodically check progress rather than waiting until the very end.

Periodic supervision means checking:

whether repo changes are actually landing

whether a worker is stalled or looping

whether reviewers agree on the next boundary

whether a worker-specific blocker requires rerouting or a tighter brief

The supervisor should synthesize reviewer output into a concrete next step. Do not just forward three uncoordinated opinions to the user.

What this skill assumes

The machine has local CLIs available for:

codex

claude

opencode

It also assumes you can create project-specific working directories, keep artifacts on disk, and run local background processes safely.

Execution model

Treat the orchestrator as a three-layer system.

1. Intake layer

The intake layer converts a user request into a structured task.

Capture at least:

task id

repo path (preferred) or repo identifier

worktree / branch plan

task type

requested outcome

success criteria

preferred tool or routing mode

sensitivity level

whether review is required

whether tests, build checks, screenshots, or PR creation are required

2. Worker layer

The worker layer runs one or more local coding CLIs.

Workers should be isolated where practical:

separate worktree or branch per implementation task

separate logs per worker

separate prompt snapshot per attempt

separate review outputs per reviewer

Workers are tool specialists, not supervisors.

3. Supervisor layer

The supervisor layer is the core of this skill.

It should:

launch workers

record status transitions

inspect objective signals instead of trusting self-reported completion

decide whether the task is blocked, review-ready, done, or needs retry

rewrite prompts for semantic retries when the worker solved the wrong problem

summarize results back to the user in coordinator voice

Task lifecycle

Model work as a persistent state machine instead of a one-shot run.

Recommended states:

draft

queued

running

awaiting-review

changes-requested

retrying

blocked

completed

failed

cancelled

Use explicit transitions. Do not silently treat “process exited” as “task completed”.

Task record

Keep a JSON task file for each orchestration unit.

Recommended directory structure:

local-orchestrator/
  tasks/
  logs/
  prompts/
  reviews/
  state/

Recommended task record shape:

{
  "id": "feat-custom-templates",
  "repo": "my-repo",
  "worktree": "../worktrees/feat-custom-templates",
  "branch": "feat/custom-templates",
  "taskType": "feature",
  "role": "implementer",
  "agent": "codex",
  "status": "running",
  "attempt": 1,
  "maxAttempts": 3,
  "createdAt": 1772958600000,
  "updatedAt": 1772959200000,
  "successCriteria": [
    "build passes",
    "tests pass",
    "review complete"
  ],
  "artifacts": {
    "logPath": "local-orchestrator/logs/feat-custom-templates.log",
    "promptPath": "local-orchestrator/prompts/feat-custom-templates-attempt-1.md",
    "reviewPath": "local-orchestrator/reviews/feat-custom-templates.md",
    "prUrl": null
  }
}

The exact schema can evolve, but the orchestrator should always leave a durable audit trail. For the fuller current schema shape, prefer docs/task-schema.v1.json and docs/task-schema.example.json over this abbreviated inline example.

Routing and role guidance

Tool choice should reflect the worker role, not just the raw user wording.

Default role mapping

Codex

- implementation lead - backend logic - complex fixes - multi-file refactors - direct code production

Claude Code

- architecture review - risk analysis - code review - requirements clarification - maintainability critique

OpenCode

- session continuation - alternative implementation plan - exploratory or agent-style follow-up work

Intent model

When routing automatically, first classify the request into a supervisor mode.

continue

- signals: continue, session, resume, agent - default tool: opencode

review

- signals: analyze, explain, review, compare, risk, audit, architecture - default tool: claude

implement

- signals: implement, build, create, modify, refactor, fix, generate, develop - default tool: codex

prototype

- signals: demo, prototype, quick, lightweight, MVP, browser toy - default tool: codex, optionally followed by claude review

maintainable-project

- signals: production, maintainable, scalable, long-term, structured - default tool: claude first for stack and risk validation, then codex for implementation

If the task is ambiguous between rapid delivery and long-term maintainability, decide explicitly and state that bias in the user-facing summary.

Pipelines

Do not treat multi-tool orchestration as “run everything and compare”. Prefer explicit worker roles.

1. implement_and_review

Use when the user wants a reliable default delivery flow.

Codex: implement

Claude Code: architecture / review / risk check

OpenCode: optional alternative plan or follow-up patch strategy

2. design_then_build

Use when UI, UX, or solution framing needs a first pass before coding.

planning / design worker: Claude Code or another design-capable tool if available

Codex: implementation

Claude Code: post-implementation review

3. investigate_then_fix

Use when the failure mode is unclear.

Claude Code or OpenCode: isolate cause, inspect risks, propose strategy

Codex: implement fix

reviewer: verify regression coverage and edge cases

4. parallel_compare

Use only when the user explicitly wants comparison, diversity of solutions, or tool benchmarking.

run multiple tools against the same scoped task

compare outputs by correctness, maintainability, risk, and delivery speed

5. pr_hardening

Use after an implementation worker has produced a candidate result.

reviewers run in parallel or sequence

collect blocking vs non-blocking issues

if needed, hand a repair brief back to the implementation worker

Done policies

Completion must be defined by objective signals, not worker self-report.

Feature task

Recommended checks:

intended files changed

build passes

tests pass

review completed or explicitly waived

PR created when requested

screenshot attached when UI changed and a screenshot requirement exists

Bugfix task

Recommended checks:

defect scope identified

fix applied in intended area

relevant tests pass or regression coverage added

no new lint / type failures introduced

Review-only task

Recommended checks:

review artifact produced

issues classified into blocking / non-blocking

recommendation clearly stated

Prototype task

Recommended checks:

runnable artifact exists

usage or launch instructions exist

result is demonstrable even if production hardening is deferred

Always report:

checks passed

checks still pending

checks failed

whether the result is actionable now

Retry policy

Not all retries are the same.

Mechanical retry

Use when the failure is environmental or operational.

Examples:

CLI startup glitch

transient shell error

workdir mismatch

temporary tool availability issue

one-off install or permission hiccup

In this case, retry the same task with corrected execution conditions.

Semantic retry

Use when the worker moved in the wrong direction.

Examples:

solved Y instead of X

ignored required file or type definition

produced an overbuilt design when a narrow fix was needed

skipped tests or changed the wrong surface

In this case, do not just rerun the same prompt.

Generate a retry brief that includes:

what the previous attempt did

evidence of failure or mismatch

what to preserve

what to change

extra context to inject

the new acceptance focus

Example structure:

Retry reason:
Worker implemented a net-new creation flow.
Required outcome is editing and reusing existing configuration.
Adjustments:
Focus on reuse/edit flows, not greenfield creation.
Reuse src/types/template.ts.
Add tests for mutation of existing configuration objects.
Do not spend time polishing unrelated UI.

Progress reporting

Report objective state changes, not chatter.

Include

worker status per tool: queued / running / completed / failed

current task lifecycle state

whether work landed in the intended directory

key artifact created

done criteria met / unmet

blocking issue if one exists

recommended next action

Report on

major state change

worker completion

worker failure

transition into review

transition into retry

final completion or terminal failure

Stay concise when

nothing material changed

only timestamps changed

the user did not request detailed check-ins

Resource scheduling

The likely bottleneck is often local machine capacity, not model intelligence.

Supervise concurrency intentionally.

Suggested weighting

review-only task = weight 1

implementation task = weight 2

build/test-heavy task = weight 3

Suggested policy

keep a configurable max total weight in flight

queue additional tasks instead of launching everything at once

avoid overlapping heavy installs/builds unless the machine can handle them

isolate implementation tasks into separate worktrees

If RAM, CPU, or disk pressure becomes the real limit, treat that as a scheduler concern rather than a worker failure.

Bundled scripts

Read and use these files from the skill assets when they exist:

assets/scripts/run-codex.ps1

assets/scripts/run-claude-code.ps1

assets/scripts/run-opencode.ps1

assets/scripts/route-task.ps1

assets/scripts/multi-orchestrate.ps1

assets/scripts/task-state.ps1

assets/scripts/evaluate-done.ps1

assets/scripts/generate-retry-brief.ps1

assets/scripts/start-pipeline.ps1

assets/scripts/supervise-task.ps1

assets/scripts/launch-worker.ps1

assets/scripts/reconcile-worker.ps1

The scripts are worker adapters. The orchestration logic should live at the supervisor level.

Operator controls

The orchestrator should support intervention.

Useful controls include:

steer a running worker

pause or stop a task

cancel a task

relaunch from a corrected workdir

reassign the task to another tool

trigger review-only follow-up

promote a failed implementation into an investigate-first pipeline

Known issues and mitigation

1. Path drift across mounted workspaces

Problem: A tool may not see the intended OpenClaw workspace path and may silently continue in another mounted path.

Mitigation:

inspect the actual reachable workdir before delegating

verify output landed in the intended project directory

if drift is detected, stop and relaunch with a corrected directory

2. Noisy wrapper output

Problem: Wrapper output can still include startup banners, MCP warnings, and shell-specific error framing.

Mitigation:

treat cleaned summaries as best-effort

inspect raw excerpts when results look suspicious

tighten cleaning rules over time based on real outputs

3. False completion

Problem: A worker process can exit even though the real task is not review-ready or done.

Mitigation:

use done policies tied to objective checks

separate worker exit from task completion state

require explicit supervisor transition to completed

if a worker only produces analysis or a patch plan, do not mark implementation complete unless repo changes actually landed

4. Adapter-layer execution failure

Problem: A worker adapter or wrapper may fail even when the underlying worker logic is still usable. Examples include PowerShell wrapper framing, stdout/stderr capture quirks, or PTY / shell integration issues.

Mitigation:

classify wrapper failures separately from task failures

distinguish adapter failure from implementation failure in supervisor summaries

if needed, relaunch the same worker brief through a simpler execution path while preserving supervisor-only boundaries

do not silently rewrite task history to make an adapter failure look like product progress

5. Static retries

Problem: Blindly rerunning the same prompt wastes time and tokens when the first attempt misunderstood the task.

Mitigation:

classify retries as mechanical vs semantic

generate retry briefs for semantic failures

preserve evidence from the failed attempt

6. Lightweight prototype bias

Problem: The orchestrator may prefer a lightweight prototype path when the task is ambiguous, even if the user would benefit from a more structured stack.

Mitigation:

ask or decide explicitly between rapid prototype and maintainable project modes

use review output to validate stack choice before implementation

7. Write-blocked worker runtimes

Problem: A worker may be able to inspect and reason about the target repo but still be unable to apply edits because the runtime is read-only or policy-blocked.

Mitigation:

classify this as an environment or policy blocker, not a semantic task failure

preserve the worker's exact patch plan as an artifact

mark implementation checks as pending when no repo changes landed

let the supervisor report that the task is blocked-by-runtime-write-capability rather than blocked-by-unclear-requirements

Practical patterns learned

Implementation + audit split

A strong default for real coding work is:

Codex: implementation lead

Claude Code: architecture / audit / review

OpenCode: alternative plan or session-style supplement

Reviewers are role-based, not democratic

The point of multiple workers is not equal voting. The point is specialized pressure from different angles.

Prefer:

one implementation lead

one architecture/risk reviewer

one optional alternative-plan or repair worker

Objective completion beats conversational completion

Do not ask a worker “are you done?” when you can inspect:

process state

files created

git diff

test results

review artifact existence

PR existence

Start narrow, then automate discovery

Before adding proactive task discovery from meeting notes, bug trackers, or logs, first make sure the orchestrator can:

persist tasks

supervise retries

enforce done policies

schedule safely

Output contract

When reporting back to the user, prefer this shape:

current lifecycle state

what each worker contributed

objective checks passed / failed / pending

consensus

differences

recommendation

next action

blocker classification when relevant

whether implementation actually landed in the repo or only an analysis/patch artifact was produced

Blocker classification

When a task cannot advance, classify the blocker explicitly. Do not collapse all failures into a generic blocked state.

Recommended blocker types:

environment

- runtime missing required capability - repo path unavailable - missing dependencies in allowed environment

policy

- write commands blocked - execution path denied by sandbox or policy gate

adapter

- wrapper script failure - PTY or stdout/stderr integration failure - orchestration-layer execution bug

implementation

- worker found a real product/code issue that still needs changes

semantic

- worker misunderstood the task or changed the wrong scope

mixed

- multiple blocker classes materially apply

Supervisor reporting should name:

blocker type

evidence

whether retrying unchanged would help

recommended next action

Terminal and near-terminal supervisor outcomes

Use explicit end-state wording in summaries even when the internal task state machine remains simple.

Recommended outcome labels:

completed

completed-with-analysis-only

blocked-by-environment

blocked-by-policy

blocked-by-adapter

changes-requested

ready-for-hardening

retry-with-semantic-brief

awaiting-writable-runtime

Notes:

completed-with-analysis-only is useful when the worker produced a valid artifact, review, or patch plan, but did not land repo changes.

awaiting-writable-runtime is useful when implementation scope is clear and bounded, but no writable worker runtime is available.

blocked-by-adapter should be used when the worker path failed in the orchestration wrapper layer and the product task itself may still be viable.

Operator quick start

For the current v2 scaffold, the practical operator flow is: 1. initialize a task record 2. move it to queued 3. run supervise-task.ps1 with -AutoLaunch for safe automatic worker launch 4. add -AutoProbe when you want a lightweight repo/runtime probe before deeper execution 5. run reconcile-worker.ps1 or supervise-task.ps1 again to fold background worker state back in 6. only use retry generation when the problem is semantic rather than environmental

See also:

docs/README.md

docs/usage-guide.md

docs/operator-playbook.md

docs/status.md

docs/v2-summary.md

docs/CHANGELOG.md

docs/capability-map.md

docs/script-interface.md

docs/environment-failures.md

docs/review-output-format.md

Publishing workflow

After stabilizing the local skill: 1. update SKILL.md and bundled scripts 2. verify local folder structure and task artifact paths 3. publish with clawhub publish 4. install/sync and validate in the local OpenClaw environment