local-coding-orchestrator

What this skill does

# 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:

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

Recommended task record shape:

```json
{
  "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