Skill: lijiejoy/local-coding-orchestrator (version 0.2.2)

--- 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: ```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 / 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: ```text 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

path: assets/references/output-cleaning.md
content: # Worker output cleaning patterns

Use these patterns to turn noisy local CLI output into short supervisor-facing summaries.

## Remove or down-weight

- tool banners
- MCP startup lines
- provider/model/session metadata
- repeated shell framing
- empty lines and duplicate lines

## Preserve

- explicit failure reasons
- repository/path problems
- read-only or sandbox constraints
- missing credential/login messages
- build/test/review outcomes
- concise final worker conclusion when present

## Summary target

Aim for a short excerpt that helps the supervisor decide:
- still running
- completed
- failed
- blocked by environment
- needs review


path: assets/references/patterns.md
content: # Local Coding Orchestrator Patterns

## Recommended role split

- Codex -> implementation lead
- Claude Code -> audit / architecture / review
- OpenCode -> alternate approach / session continuation

## Auto-routing modes

### continue
- best default: OpenCode

### review
- best default: Claude Code

### implement
- best default: Codex

### prototype
- best default: Codex first, then optional Claude review

### maintainable-project
- best default: Claude first for stack validation, then Codex for implementation

## Directory discipline

Always prefer a dedicated subdirectory for the task.

Bad:
- dumping generated files into the workspace root
- allowing tools to drift into a different mounted path without noticing

Good:
- create a focused project directory first
- pass that directory explicitly to the wrappers

## Progress reporting

For long-running work:
- run tool workers in background when possible
- use OpenClaw cron or system-event wakeups for periodic checks
- stop progress checks once all workers are done
- treat cron stop-after-completion as coordinator logic, not a native external-worker completion primitive

## Known operational issues

- Some tool workers may not share the same visible filesystem mount set.
- Multi-tool aggregation is currently a structured sequential collector, not a true parallel process supervisor.
- Output cleaning is heuristic and may leave shell-specific noise in summaries.
- Windows PowerShell profiles or constrained language behavior can interfere with some CLI invocations.

## Lightweight prototype path

Use this path when speed matters most:
- HTML
- CSS
- JS
- browser-native runtime
- Three.js CDN for 3D

Use heavier stacks only when they pay for themselves.


path: assets/references/progress-template.md
content: # Intelligent Progress Feedback Template

Use this structure for progress updates:

## Status
- Codex: running/completed/failed
- Claude: running/completed/failed
- OpenCode: running/completed/failed

## Key output
- What changed since last check
- Which files or artifacts were created
- Whether results landed in the intended directory

## Assessment
- Is the task now actionable?
- Are results aligned or conflicting?
- Is there an environmental issue blocking progress?

## Next action
- Continue waiting
- Relaunch failed worker
- Merge results
- Ask user to choose between prototype vs maintainable path


path: assets/references/supervisor-vs-worker.md
content: # Supervisor vs worker responsibilities

This reference clarifies the boundary between orchestration logic and local coding workers.

## Supervisor responsibilities

The supervisor is responsible for:
- accepting or structuring the task
- choosing the pipeline
- choosing worker roles and tools
- creating task records
- managing lifecycle transitions
- evaluating objective completion signals
- deciding whether review is required
- generating retry briefs
- deciding between mechanical retry and semantic retry
- summarizing status to the user
- deciding whether the task is completed, blocked, failed, or needs another pass

## Worker responsibilities

A worker is responsible for:
- reading the current brief
- editing code or producing a review artifact
- running requested local checks when possible
- writing output into the intended directory
- returning raw execution results or files

Workers are not responsible for:
- redefining task scope
- deciding final completion state
- suppressing failed objective checks
- overwriting supervisor decisions

## Boundary rule

Treat workers as specialized executors.
Treat the supervisor as the source of truth for task state.

## Why this matters

Without a clear boundary, orchestration collapses into prompt forwarding.
With a clear boundary, OpenClaw can:
- supervise multiple workers
- retry intelligently
- avoid false completion
- keep a reliable task history


path: docs/artifacts-and-logs.md
content: # Artifacts and log wiring

This document defines how `local-coding-orchestrator` should persist worker execution artifacts.

## Goal

Before attaching real worker execution, make sure every run has a predictable place for:
- prompt / brief
- raw log
- structured result
- short summary
- launch metadata

## Recommended directories

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

## Task record responsibilities

The task record should carry two related but different concepts.

### 1. `artifacts`

Persistent file locations associated with the task:
- `promptPath`
- `logPath`
- `resultPath`
- `summaryPath`
- `reviewPath`
- `prUrl`

### 2. `workerRun`

The latest execution metadata for the currently active or most recent worker run:
- `tool`
- `role`
- `startedAt`
- `finishedAt`
- `exitCode`
- `status`
- `logPath`
- `resultPath`
- `summary`

## Why keep both

`artifacts` answers: where are the files?
`workerRun` answers: what happened during the last execution?

## Minimum statuses for workerRun

Suggested values:
- `planned`
- `running`
- `completed`
- `failed`
- `blocked`

## First safe step

Before running workers directly, the adapter should at least:
- allocate log and result paths
- write prompt path
- write workerRun metadata with `planned`
- update the task record

That makes the next step—real tool execution—much safer to wire up.


path: docs/background-workers.md
content: # Background worker model

This document defines the next-step execution model for `local-coding-orchestrator`.

## Why background mode

Local coding CLIs can take a long time or block interactively.
Because of that, synchronous execution should not be the default orchestration path.

## Goal

Track background worker execution as a supervised handle, not as a blocking call.

## Minimum metadata to persist

Store background execution details in `workerRun`:
- `mode`: `background`
- `sessionId`: OpenClaw process session id
- `pid`: underlying process id when available
- `startedAt`
- `lastPolledAt`
- `finishedAt`
- `status`
- `exitCode`

## Expected flow

1. launch worker in background
2. persist session handle into the task record
3. mark worker run as `running`
4. let supervisor poll objective state later
5. on completion, write result/log metadata and update task record

## Important rule

Do not confuse:
- worker still running
- worker exited cleanly
- task completed

Worker completion is only one signal. The supervisor still owns task completion.


path: docs/capability-map.md
content: # Capability map

This document summarizes what the v2 scaffold can currently do.

## Task control plane

- create task records
- track lifecycle state
- record transition history
- store artifacts and worker metadata

## Decision layer

- evaluate done policies
- generate retry briefs
- resolve role-based pipeline presets
- classify environment failures
- recommend next orchestration action

## Execution layer

- generate worker briefs
- support a dedicated probe-mode brief for repo/runtime feasibility checks
- support a dedicated review-mode brief for next-step classification
- route prompts via `TaskFile`
- launch workers in sync or background mode
- reconcile background worker runs
- backfill some objective checks from worker summaries

## Current boundaries

- no fully reliable background session abstraction yet
- no robust PR/test/build parser yet
- environment capability varies with local CLI setup
- supervisor is semi-automatic rather than fully autonomous

## Practical interpretation

The skill is suitable for:
- local orchestration experiments
- supervisor-driven coding workflows
- structured implementation/review loops
- iterative hardening toward a fuller runtime

The skill is not yet ideal for:
- unattended production deployment
- deterministic CI-grade orchestration
- high-confidence automatic merge pipelines


path: docs/CHANGELOG.md
content: # Changelog

## v0.3.1

### Added
- formal review-phase semantics in the supervisor flow
- dedicated review-mode worker briefing
- phase model documentation (`probe` / `implement` / `review` / `harden`)

### Improved
- supervisor can now recommend `launch-review-worker` after successful probe outcomes
- clearer stage-based orchestration guidance in docs and pipeline descriptions

### Known rough edges
- review phase is now formalized, but harden phase is still mostly conceptual
- background execution still depends on local CLI behavior
- result interpretation is still partly heuristic

## v0.3.0

### Added
- probe-mode worker briefing for lightweight repo/runtime feasibility checks
- supervisor auto-probe support in queued task flow
- probe outcome integration into reconcile and supervisor decisions
- repoPath standardization with backward compatibility for existing repo field usage
- repo preflight script for early repository validation

### Improved
- cleaner constrained-environment testing flow
- better distinction between probe work and full implementation work
- stronger handling of blocked build/test outcomes discovered during probe runs

### Known rough edges
- background execution still depends on local CLI behavior
- result interpretation is still partly heuristic
- objective checks still need deeper artifact-driven automation beyond summary parsing

## v2 scaffold / v0.2.0

### Added
- persistent task schema and lifecycle model
- done policy evaluator
- retry brief generation
- role-based pipeline presets
- worker launch adapter
- synchronous and background execution modes
- TaskFile-based prompt handoff
- worker reconcile step
- environment failure classification
- supervisor auto-advance and auto-launch support
- summary cleaning and objective-check backfill framework
- docs index, capability map, script interface, usage guide, and status overview

### Improved
- clearer separation of supervisor vs worker responsibilities
- better product-style documentation and operator guidance
- stronger handling of environment-blocked runs

### Known rough edges
- background execution still depends on local CLI behavior
- result interpretation is partly heuristic
- objective checks still need deeper artifact-driven automation


path: docs/done-policies.md
content: # Done policies

This document defines the minimum completion policies for `local-coding-orchestrator`.

## Principle

A task is complete when its required objective checks pass.
A worker process exiting or claiming success is not sufficient.

## Check status vocabulary

Use a small fixed vocabulary for objective checks:
- `pending`
- `passed`
- `failed`
- `blocked`
- `not-required`

## Core checks

Common checks used across task types:
- `build`
- `tests`
- `review`
- `pr`
- `screenshot`
- `artifact`
- `repro`
- `docs`

Not every task needs every check.

## Policy by task type

### Feature

Minimum recommended checks:
- `build`
- `tests`
- `review`
- `pr` when requested
- `screenshot` when UI changed and screenshot proof is required

Completion guidance:
- all required checks must be `passed`
- optional checks may stay `not-required`
- any `failed` check blocks completion

### Bugfix

Minimum recommended checks:
- `repro` or equivalent defect evidence
- `tests`
- `review`
- `build` unless the environment is intentionally check-light

Completion guidance:
- defect scope should be evidenced
- fix should not introduce new lint/type/build failures

### Review-only

Minimum recommended checks:
- `artifact`
- `review`

Completion guidance:
- the review artifact exists
- findings are categorized clearly enough to act on

### Prototype

Minimum recommended checks:
- `artifact`
- `docs`
- `review` optional

Completion guidance:
- result is runnable or demonstrable
- operator knows how to launch or inspect it
- production hardening can remain deferred if declared

## Evaluation rule

A task may be marked `completed` only if:
1. every required check is `passed`, and
2. no required check is `pending`, `failed`, or `blocked`

If some required checks are still pending, the task is not complete even if the worker stopped.

## Suggested policy shape

A future evaluator can use a policy structure like:

```json
{
  "feature": {
    "required": ["build", "tests", "review"],
    "conditional": {
      "pr": "whenRequested",
      "screenshot": "whenUiChanged"
    }
  },
  "bugfix": {
    "required": ["tests", "review"],
    "conditional": {
      "build": "whenBuildable",
      "repro": "whenBugNeedsExplicitRepro"
    }
  }
}
```

## Recommended user-facing report shape

When reporting status, include:
- checks passed
- checks pending
- checks failed
- whether the current result is actionable
- what is needed to reach completion


path: docs/environment-failures.md
content: # Environment failure classification

This document defines the first environment-oriented failure classes for `local-coding-orchestrator`.

## Why this exists

A worker can fail even when the task itself was reasonable.
Those cases should not be treated the same as implementation failure.

## Initial classes

- `environment-missing`
  - read-only sandbox
  - non-writable workspace
  - missing local prerequisites

- `repo-unavailable`
  - repository path missing
  - checkout not present
  - expected project directory not found

- `credential-missing`
  - MCP login missing
  - API token missing
  - environment variable for auth missing

- `environment-blocked`
  - the worker explicitly reports blocked prerequisites

## Supervisor behavior

When one of these classes is detected, prefer:
- `nextAction = operator-intervention`
- `recommendedState = blocked`

rather than automatically generating a semantic retry.


path: docs/multi-worker-supervision.md
content: # Multi-worker supervision

This document defines how `local-coding-orchestrator` should supervise multiple local coding tools at the same time.

## Goal

Use different worker tools for distinct roles while keeping the supervisor responsible for:
- coordination
- periodic progress checks
- blocker detection
- reviewer consensus
- next-step routing

The supervisor should not disappear after launch.
Launching workers is only the start of orchestration, not the end.

## Recommended multi-worker role split

Use role separation whenever practical.

### Primary implementer

Default purpose:
- make repo changes
- ship the next usable increment
- keep scope aligned with the active phase

Examples:
- OpenCode as primary implementation worker on hosts where it has confirmed write capability
- Codex when sandboxed write paths are stable

### Reviewer / planner

Default purpose:
- inspect the current codebase
- identify architecture and migration risks
- define the minimum acceptable shape for the next implementation step
- keep implementation from wandering

Examples:
- Claude Code for planning, review, and requirements refinement
- Codex or OpenCode as a second reviewer when comparison is useful

### Secondary reviewer or alternate implementer

Default purpose:
- provide a second opinion
- compare recommended persistence/storage paths
- validate whether the primary worker is over-scoping or under-scoping
- take over a bounded follow-up task if the primary worker is blocked

## Supervisor responsibilities during execution

The supervisor must keep checking on active workers.
Recommended loop:
1. launch workers with explicit role briefs
2. wait a reasonable interval
3. inspect progress logs or process output
4. detect blockers, stalls, or completed outputs
5. coordinate the next step
6. repeat until a stable outcome is reached

The supervisor should look for:
- whether files are actually being created or updated
- whether the worker is only thinking or truly writing
- whether package installation or runtime verification succeeded
- whether the worker has become stuck on a narrow issue
- whether reviewers agree on the next implementation boundary

## Periodic supervision checks

Periodic checks can be manual, heartbeat-driven, or scheduler-driven.

At each check, report at least:
- worker status: running / completed / stalled / blocked
- what each worker has contributed since the last check
- active blocker classification
- whether coordination is needed
- recommended next action

Good examples of supervisor interventions:
- narrowing scope after reviewer feedback
- telling an implementer to land persistence before edit/delete flows
- rerouting to a different worker when the current worker cannot write files
- stopping a worker that is looping without producing repo changes

## Consensus handling

When multiple reviewers are active, do not just quote them.
The supervisor should synthesize.

Recommended synthesis pattern:
- note where reviewers agree
- note where they differ
- choose a working implementation order
- explain why that order is safer or faster

Example:
- Claude recommends persistence first
- Codex recommends a repository boundary first, then persistence
- Supervisor synthesis: create a minimal storage boundary and place persistence behind it before broader CRUD expansion

## Escalation and rerouting

If a worker stalls or hits a narrow blocker, the supervisor should intervene instead of waiting indefinitely.

Typical rerouting patterns:
- adapter failure -> relaunch through a simpler path
- write-blocked runtime -> reroute to a worker with confirmed write capability
- semantic drift -> send a tighter retry brief
- reviewer disagreement -> freeze implementation scope and request a focused comparison

## Completion expectations

A multi-worker run is not complete just because a single worker exits.
The supervisor should confirm:
- repo changes landed
- the app still runs
- review feedback has been incorporated or explicitly deferred
- blockers are classified and documented
- the next action is clear

## Practical pattern validated in local runs

A practical validated pattern is:
- OpenCode implements when real write capability is confirmed
- Claude Code reviews and plans the next increment
- Codex performs a secondary technical assessment
- the supervisor periodically checks all three and coordinates the implementation order

This pattern is especially useful on hosts where tool write capabilities differ in practice.


path: docs/objective-check-backfill.md
content: # Objective check backfill

This document defines the next hardening step for automatic objective check updates.

## Goal

Use worker summaries and result artifacts to backfill some objective checks automatically.

## First useful signals

- if summary mentions read-only sandbox or missing repo, do not mark checks passed; prefer blocked interpretation
- if summary explicitly says build passed, set `build = passed`
- if summary explicitly says tests passed, set `tests = passed`
- if summary explicitly says review completed or review artifact exists, set `review = passed`
- if summary explicitly says a check remains pending, keep it pending

## Caution

Do not infer success from silence.
Only mark checks passed when the worker or artifact provides direct evidence.


path: docs/operator-playbook.md
content: # Operator playbook

This is the practical guide for using `local-coding-orchestrator` as of the current stage-based scaffold.

## Recommended flow

### 1. Start with repo path, not just repo name
Use a concrete repo path whenever possible.

### 2. Run a probe first in constrained environments
Use probe mode when:
- the repo is new to the orchestrator
- the runtime may be read-only or policy-limited
- you are unsure whether build/test can run

Recommended supervisor call:
```powershell
powershell -ExecutionPolicy Bypass -File assets/scripts/supervise-task.ps1 \
  -TaskId feat-demo -AutoLaunch -AutoProbe -ApplyTransition -Json
```

### 3. Reconcile after background execution
After the worker runs, reconcile the result:
```powershell
powershell -ExecutionPolicy Bypass -File assets/scripts/reconcile-worker.ps1 \
  -TaskId feat-demo -Json
```

### 4. Let supervisor decide the next phase
Then ask the supervisor what phase comes next:
```powershell
powershell -ExecutionPolicy Bypass -File assets/scripts/supervise-task.ps1 \
  -TaskId feat-demo -Json
```

## Phase intent

### Probe
Find out whether the repo and runtime are viable.

### Implement
Make changes when the runtime is good enough.

### Review
Classify blockers and decide whether to advance, block, or request changes.

### Harden
Do final cleanup or follow-up fixes before considering the task complete.

## Practical advice

- if probe says the runtime is blocked, trust it and stop forcing implementation
- if review says `blocked-by-environment`, do not generate semantic retry briefs
- if review says `approved-for-next-step`, then move to implementation or hardening
- use retry generation for misunderstanding or wrong-scope work, not for policy or sandbox limits

## What this skill is best at right now

- structuring local coding work
- supervising local agent runs
- distinguishing environment blockers from implementation blockers
- guiding next-step decisions with lightweight orchestration state

## What still needs caution

- background execution still inherits local CLI quirks
- build/test feasibility can be runtime-limited even when repo access works
- some conclusions still depend on summary parsing rather than deterministic artifact analysis


path: docs/phase-model.md
content: # Phase model

This document captures the emerging stage-based execution model of `local-coding-orchestrator`.

## Current phases

### 1. Probe
Purpose:
- validate repo access
- inspect minimal structure
- determine runtime feasibility

### 2. Implement
Purpose:
- make code changes
- run implementation-oriented checks when possible

### 3. Review
Purpose:
- inspect probe or implementation outcomes
- classify blockers and next-step risk
- recommend advance, block, or changes requested

### 4. Harden
Purpose:
- perform follow-up fixes, cleanup, or polish before declaring completion

## Why phases matter

Phase-based orchestration avoids asking a single worker to do everything at once.
It lets the supervisor choose lighter or heavier worker modes based on current evidence.


path: docs/pipeline-presets.md
content: # Pipeline presets

This document defines the initial pipeline presets for `local-coding-orchestrator`.

## Goal

Multi-tool orchestration should use role-based pipelines, not just side-by-side tool fan-out.

## Presets

### `implement_and_review`
- Codex: implementation lead
- Claude: architecture and risk review
- OpenCode: alternative plan or follow-up support

Use when:
- default coding delivery flow
- normal feature work
- refactors that benefit from post-implementation scrutiny

### `design_then_build`
- Claude: design and solution framing
- Codex: implementation
- Claude: post-build review

Use when:
- solution framing matters before code changes
- UI or architecture direction is still soft

### `investigate_then_fix`
- Claude: root-cause analysis
- Codex: fix implementation
- Claude: regression and edge-case review

Use when:
- bug cause is unclear
- user wants diagnosis before code edits

### `parallel_compare`
- Codex: candidate A
- Claude: candidate B
- OpenCode: candidate C

Use when:
- the user explicitly wants comparison
- benchmarking or solution diversity matters more than speed

### `pr_hardening`
- Claude: review for architecture and maintainability
- OpenCode: alternative patch or follow-up strategy
- Codex: repair pass for blocking issues

Use when:
- a candidate implementation already exists
- the goal is to harden before merge or approval

## Guidance

Prefer the narrowest pipeline that fits the task.
Do not default to `parallel_compare` unless the user really wants multiple competing outputs.

## Stage model

The v2 scaffold now benefits from treating work as stage-based rather than as a single launch.

Recommended conceptual stages:
- `probe`
- `implement`
- `review`
- `harden`

Current implementation is strongest in `probe` and `implement`, and is moving toward a more formal `review` stage.


path: docs/probe-mode.md
content: # Probe mode

This document defines the lightweight worker probe mode.

## Goal

Separate repo/runtime feasibility checks from full implementation work.

## Why it exists

In constrained environments, a full worker brief may waste time on:
- loading workspace context the worker cannot access
- complex shell probing
- implementation planning before basic repo access is confirmed

## Probe mode rules

A probe worker should:
- verify repo path access
- inspect top-level structure only
- determine whether build/test can proceed
- report blockers clearly

A probe worker should not:
- load orchestrator workspace context files
- treat missing workspace context as a blocker
- start full implementation planning
- rely on complex multi-line shell constructions

## When to use

Use probe mode when:
- validating a new repo target
- testing a constrained environment
- checking whether the local runtime is viable before handing off a bigger task


path: docs/README.md
content: # local-coding-orchestrator docs

> Experimental v2 scaffold for advanced users. This is not yet a fully autonomous production runtime.

This folder documents the v2 direction of `local-coding-orchestrator`.

## Start here

- `usage-guide.md` — practical operator flow
- `operator-playbook.md` — the most practical stage-based operating guide
- `status.md` — current maturity and limits
- `v2-summary.md` — what changed and what the scaffold now means
- `CHANGELOG.md` — condensed record of the v2 upgrade

## Architecture

- `v2-plan.md`
- `state-machine.md`
- `pipeline-presets.md`
- `phase-model.md`
- `retry-model.md`
- `supervisor-loop.md`

## Execution and artifacts

- `artifacts-and-logs.md`
- `worker-launch.md`
- `worker-reconcile.md`
- `objective-check-backfill.md`
- `multi-worker-supervision.md`

## Policies

- `done-policies.md`
- `environment-failures.md`

## Real-world validation

- `real-world-validation.md`

## Schemas

- `task-schema.example.json`
- `task-schema.v1.json`


path: docs/real-world-validation.md
content: # Real-world validation

This document records practical validation runs for `local-coding-orchestrator`.

## Case 1 — Static marketing site under read-only worker runtime

### Repo
- `D:\data\code\fengyun-marketing-web`

### Goal
Validate strict supervisor-only orchestration on a real static site task using:
- probe
- implement
- review
- harden

### What happened
- The supervisor created and tracked a real task.
- Probe confirmed the repo shape and local reachability.
- Review identified bounded issues: encoding corruption risk, placeholder contact details, incomplete focus styling, missing favicon.
- Harden produced an exact patch plan.
- Worker runtime could inspect and reason, but could not write due to read-only / policy-blocked execution.

### Correct classification
- blocker type: `policy`
- near-terminal outcome: `awaiting-writable-runtime`

### Lesson
A worker that can read and analyze but cannot write should not be treated as a semantic failure. Preserve the patch artifact and classify the task as blocked by runtime write capability.

---

## Case 2 — Forum build validation under real multi-tool worker checks

### Repo
- `D:\data\code\forum-orchestrator-demo`

### Goal
Validate that the orchestrator can support a real delivery workflow for a new forum project in `D:\data\code`.

### Supervisor intent
- create repo on D drive
- initialize task via orchestrator
- probe runtime and repo
- confirm which local coding tools can actually start and write files
- prefer real delivery over abstract rule editing

### Tool availability checks
Observed on host:
- `claude` available
- `codex` available
- `opencode` available

### Minimal write tests
The supervisor ran a write-file test in the forum repo for each tool.

#### OpenCode
- Result: success
- Wrote: `TOOLCHECK_OPENCODE.txt`
- Conclusion: can perform real write operations in repo

#### Claude Code
- Result: partial
- Tool started, but requested permission before writing `TOOLCHECK_CLAUDE.txt`
- Conclusion: runnable, but not yet confirmed for unattended write flow

#### Codex
- Result: partial failure
- Tool started and attempted write operations
- Blocked by Windows sandbox refresh failure during patch or shell write path
- Conclusion: installed and runnable, but write path is not yet stable on this host

### Current capability matrix
- OpenCode: runnable + writable
- Claude Code: runnable + write requires approval path
- Codex: runnable + write path unstable due to sandbox issue

### Lesson
Do not treat “tool installed” as sufficient validation.
The orchestrator should validate at least three layers:
1. tool exists
2. tool launches
3. tool can land repo changes

If only one or two layers pass, report the exact capability level instead of claiming the worker is fully operational.

### Practical supervisor recommendation
For immediate delivery on this host:
- use OpenCode as the primary implementation worker
- use Claude Code as reviewer after write path is clarified
- keep Codex in the pool, but treat it as not yet production-ready on this Windows runtime until sandbox write issues are resolved


path: docs/retry-model.md
content: # Retry model

This document defines the retry strategy for `local-coding-orchestrator`.

## Principle

Retries should preserve learning.
Do not blindly rerun the same prompt unless the failure was purely mechanical.

## Retry classes

### Mechanical retry

Use mechanical retry when the problem was operational rather than conceptual.

Examples:
- shell startup glitch
- transient CLI failure
- workdir mismatch
- temporary permissions issue
- install or process launch hiccup

Behavior:
- keep task intent the same
- fix the execution condition
- preserve accepted scope
- rerun with minimal prompt changes

### Semantic retry

Use semantic retry when the worker misunderstood the task or optimized for the wrong thing.

Examples:
- solved the wrong requirement
- changed the wrong files
- overbuilt instead of making the narrow fix
- ignored required context or definitions
- skipped expected validation or tests

Behavior:
- explain what went wrong
- preserve the valid parts of the prior attempt
- explicitly redirect scope
- restate acceptance focus
- write a new retry brief for the next attempt

## Minimum retry brief fields

A retry brief should include:
- retry reason
- what to preserve
- what to change
- extra context
- acceptance focus

## Task updates

When generating a retry brief for a new attempt, the orchestrator should:
- increment the attempt counter
- update the prompt artifact path
- preserve task history and prior evidence

## Suggested sequence

1. classify failure as mechanical or semantic
2. collect evidence
3. generate retry brief
4. transition task into `retrying`
5. relaunch the worker
6. transition back into `running`


path: docs/review-output-format.md
content: # Review output format

This document defines the lightweight structured output expected from review-mode workers.

## Required headings

- `Review Decision:`
- `Risk Level:`
- `Blocker Type:`
- `Recommended Next Step:`
- `Rationale:`

## Allowed values

### Review Decision
- `approved-for-next-step`
- `blocked-by-environment`
- `changes-requested`
- `ready-for-hardening`

### Risk Level
- `low`
- `medium`
- `high`

### Blocker Type
- `none`
- `environment`
- `implementation`
- `mixed`

### Recommended Next Step
- `probe-again`
- `implement`
- `review`
- `harden`
- `operator-intervention`

## Why this exists

The supervisor should not rely only on free-form text when a lightweight structured decision can be requested.
This format is intentionally simple enough for local coding workers to follow without heavy parsing requirements.


path: docs/review-phase.md
content: # Review phase

This document defines the next-stage formalization of review work in `local-coding-orchestrator`.

## Goal

Treat review as its own orchestration phase rather than as an informal afterthought.

## Review phase responsibilities

A review worker should:
- inspect the candidate outcome or probe result
- classify risks and blockers
- distinguish environment blockers from implementation blockers
- produce a concise review artifact or recommendation

## Review phase outcomes

Typical review outcomes:
- `approved-for-next-step`
- `blocked-by-environment`
- `changes-requested`
- `ready-for-hardening`

## Near-term implementation direction

The scaffold should support a lightweight review worker handoff after:
- probe completion
- implementation completion
- failed or ambiguous execution that needs triage

## Why this matters

Without a formal review phase, the supervisor is forced to infer too much from raw worker summaries.
A dedicated review phase gives the orchestrator a clearer place for judgment, classification, and handoff.


path: docs/script-interface.md
content: # Script interface overview

This file lists the main scripts and their current role in the v2 scaffold.

## Task state

### `task-state.ps1`
Purpose:
- initialize tasks
- fetch task records
- perform validated state transitions

## Evaluation

### `evaluate-done.ps1`
Purpose:
- inspect objective checks
- determine whether task completion is currently allowed

## Retry

### `generate-retry-brief.ps1`
Purpose:
- create mechanical or semantic retry briefs
- optionally write the next prompt artifact

## Pipeline

### `start-pipeline.ps1`
Purpose:
- resolve role-based worker presets for the configured pipeline

## Worker launch

### `launch-worker.ps1`
Purpose:
- select the worker role
- generate either a default brief or a probe-mode brief
- allocate prompt/log/result artifacts
- optionally launch sync or background worker execution

## Worker reconcile

### `reconcile-worker.ps1`
Purpose:
- inspect worker runtime state
- classify worker outcome
- write summary/result artifacts
- backfill some objective checks
- interpret probe-mode results for supervisor follow-up

## Supervisor

### `supervise-task.ps1`
Purpose:
- reconcile running background workers
- evaluate current task status
- recommend or apply next orchestration steps
- optionally auto-launch or auto-block in safe cases

## Tool wrappers

### `run-codex.ps1`
### `run-claude-code.ps1`
### `run-opencode.ps1`
Purpose:
- adapt local coding CLIs to the orchestrator
- accept either `Task` or `TaskFile`


path: docs/state-machine.md
content: # Task lifecycle and state machine

This document defines the minimum lifecycle model for `local-coding-orchestrator` tasks.

## Purpose

A local worker exiting is not enough to call a task done.

The supervisor owns lifecycle transitions. Workers only produce artifacts and execution outcomes.

## Canonical states

- `draft`
- `queued`
- `running`
- `awaiting-review`
- `changes-requested`
- `retrying`
- `blocked`
- `completed`
- `failed`
- `cancelled`

## State meanings

### `draft`
Task exists but has not been accepted for execution.

### `queued`
Task is ready to run but waiting for resources, prerequisites, or scheduling.

### `running`
At least one assigned worker is actively executing the current attempt.

### `awaiting-review`
Implementation attempt produced a candidate result and the supervisor is now waiting for review or objective checks.

### `changes-requested`
Review or checks found issues that need another implementation pass.

### `retrying`
The supervisor has decided to relaunch the task after preparing a revised attempt.

### `blocked`
Task cannot proceed without outside help, missing context, environmental repair, or explicit operator decision.

### `completed`
All required objective checks passed and the supervisor has explicitly marked the task done.

### `failed`
The task reached a terminal unsuccessful state, such as max attempts exhausted or a fatal constraint.

### `cancelled`
The task was intentionally stopped by the operator.

## Allowed transitions

```text
draft -> queued | cancelled
queued -> running | blocked | cancelled
running -> awaiting-review | blocked | failed | cancelled
awaiting-review -> completed | changes-requested | blocked | failed | cancelled
changes-requested -> retrying | blocked | failed | cancelled
retrying -> running | blocked | failed | cancelled
blocked -> queued | cancelled | failed
failed -> queued | cancelled
completed -> (terminal)
cancelled -> (terminal)
```

## Transition rules

### Who may change state

The supervisor is the only authority that should commit lifecycle transitions.

Workers may emit signals such as:
- process exited
- patch written
- tests passed
- review artifact created

But workers should not write `completed` directly into the task state without supervisor confirmation.

### Required metadata on transition

Every lifecycle transition should record:
- previous state
- next state
- timestamp
- reason
- actor (`supervisor`, `worker`, `operator`, `system`)
- attempt number

Recommended event record:

```json
{
  "from": "running",
  "to": "awaiting-review",
  "at": 1772959300000,
  "reason": "worker exited and produced candidate patch",
  "actor": "supervisor",
  "attempt": 1
}
```

### Blocked vs failed

Use `blocked` when progress may resume after intervention.
Use `failed` only for terminal outcomes.

Examples of `blocked`:
- missing repository access
- environment not prepared
- ambiguous requirement
- unavailable dependency

Examples of `failed`:
- max attempts exhausted
- repository intentionally rejected task direction
- required tool unavailable and no substitute allowed

## Minimum state transition checks

Before allowing a transition, validate:
- transition pair is allowed
- task id exists
- attempt number is present
- timestamp is written
- reason is non-empty

## Suggested helper API

A future helper script or module can expose functions like:

- `New-OrchestratorTask`
- `Get-OrchestratorTask`
- `Set-OrchestratorTaskState`
- `Add-OrchestratorTaskEvent`
- `Get-OrchestratorTaskHistory`

The helper should reject illegal state jumps unless an operator explicitly forces them.


path: docs/status.md
content: # local-coding-orchestrator status

> Experimental v2 scaffold. Publishable for advanced users, but not yet a stable autonomous production orchestrator.

## Current maturity

The skill is in an advanced scaffold stage.
It has real orchestration components, but still needs hardening before fully autonomous production use.

## Implemented

- task schema and example
- task lifecycle/state machine
- done policy evaluator
- retry brief generation
- pipeline preset resolver
- worker launch preview
- synchronous worker execution adapter
- background worker launch metadata
- TaskFile-based prompt handoff
- background worker reconcile step
- environment failure classification
- supervisor auto-advance recommendations
- supervisor auto-launch support in safe cases
- supervisor auto-probe support for constrained repo/runtime validation
- early review-phase formalization with dedicated review-mode briefing
- repoPath standardization with backward compatibility for existing repo field usage
- stage-based execution model emerging across probe / implement / review / harden

## Still rough

- process/session tracking is not yet unified on OpenClaw process handles
- background reconcile uses lightweight heuristics
- objective checks now support limited backfill from worker summaries, but still need deeper artifact-driven automation
- some wrappers still inherit local CLI quirks and environment assumptions

## Recommended next hardening items

1. use OpenClaw process/session ids in workerRun where possible
2. enrich objective checks from actual command results
3. normalize result parsing and summaries
4. tighten worker completion classification
5. separate implementation workers from review workers more explicitly


path: docs/supervisor-loop.md
content: # Supervisor loop

This document describes the first supervisor loop for `local-coding-orchestrator`.

## Goal

Connect task records, done evaluation, and pipeline presets into a single supervisory decision point.

## Current loop

The initial supervisor loop should:
1. load the task record
2. inspect current lifecycle state
3. evaluate objective completion checks
4. resolve the configured pipeline preset
5. recommend the next orchestration action
6. recommend the next lifecycle state

## Important constraint

The initial loop is advisory.
It should recommend actions before it starts mutating task state or launching workers automatically.

This keeps the first version inspectable and safer to debug.

## Example actions

- `queue-task`
- `launch-worker`
- `continue-monitoring`
- `review-for-retry-or-block`
- `generate-retry-brief`
- `prepare-retry`
- `relaunch-worker`
- `transition-to-completed`
- `operator-intervention`
- `decide-requeue-or-cancel`

## Why advisory first

A bad supervisor that auto-mutates state can create confusing failures quickly.
An advisory supervisor gives you a tight feedback loop while preserving human control.

## Current upgrade

The supervisor loop now supports optional controlled actions:
- optionally write state transitions
- optionally trigger retry brief generation
- reconcile background worker state before making the next decision
- auto-recommend review or blocked states when worker outcomes already exist
- optionally auto-launch, auto-probe, and auto-block in safe cases

These actions are opt-in so the default mode stays inspectable.

## Expected next step

After this controlled mode is stable, upgrade it to:
- optionally launch the next worker for the chosen pipeline
- optionally attach worker outputs back into the task record
- optionally enforce queue and scheduler decisions


path: docs/task-schema.example.json
content: {
  "id": "feat-example",
  "repo": "my-repo",
  "repoPath": "D:/data/code/my-repo",
  "worktree": "../worktrees/feat-example",
  "branch": "feat/example",
  "taskType": "feature",
  "pipeline": "implement_and_review",
  "role": "implementer",
  "agent": "codex",
  "status": "queued",
  "attempt": 1,
  "maxAttempts": 3,
  "createdAt": 1772958600000,
  "updatedAt": 1772958600000,
  "successCriteria": [
    "build passes",
    "tests pass",
    "review complete"
  ],
  "objectiveChecks": {
    "build": "pending",
    "tests": "pending",
    "review": "pending",
    "pr": "not-required",
    "screenshot": "not-required"
  },
  "artifacts": {
    "logPath": "local-orchestrator/logs/feat-example.log",
    "promptPath": "local-orchestrator/prompts/feat-example-attempt-1.md",
    "reviewPath": "local-orchestrator/reviews/feat-example.md",
    "prUrl": null,
    "resultPath": "local-orchestrator/results/feat-example.json",
    "summaryPath": "local-orchestrator/results/feat-example-summary.md"
  },
  "workerRun": {
    "tool": "codex",
    "role": "implementer",
    "startedAt": 1772958605000,
    "finishedAt": null,
    "lastPolledAt": null,
    "exitCode": null,
    "status": "planned",
    "mode": "background",
    "sessionId": "example-session-id",
    "pid": 12345,
    "logPath": "local-orchestrator/logs/feat-example.log",
    "resultPath": "local-orchestrator/results/feat-example.json",
    "summary": null
  },
  "notes": []
}


path: docs/task-schema.v1.json
content: {
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://openclaw.local/skills/local-coding-orchestrator/task-schema.v1.json",
  "title": "local-coding-orchestrator task record",
  "type": "object",
  "additionalProperties": true,
  "required": [
    "id",
    "repo",
    "taskType",
    "pipeline",
    "role",
    "agent",
    "status",
    "attempt",
    "maxAttempts",
    "createdAt",
    "updatedAt",
    "objectiveChecks",
    "artifacts"
  ],
  "properties": {
    "id": { "type": "string", "minLength": 1 },
    "repo": { "type": "string", "minLength": 1 },
    "repoPath": { "type": ["string", "null"] },
    "worktree": { "type": ["string", "null"] },
    "branch": { "type": ["string", "null"] },
    "taskType": {
      "type": "string",
      "enum": ["feature", "bugfix", "review", "prototype", "investigation", "maintenance"]
    },
    "pipeline": {
      "type": "string",
      "enum": ["implement_and_review", "design_then_build", "investigate_then_fix", "parallel_compare", "pr_hardening"]
    },
    "role": {
      "type": "string",
      "enum": ["implementer", "reviewer", "planner", "investigator", "repairer"]
    },
    "agent": {
      "type": "string",
      "enum": ["codex", "claude", "opencode", "auto"]
    },
    "status": {
      "type": "string",
      "enum": ["draft", "queued", "running", "awaiting-review", "changes-requested", "retrying", "blocked", "completed", "failed", "cancelled"]
    },
    "attempt": { "type": "integer", "minimum": 1 },
    "maxAttempts": { "type": "integer", "minimum": 1 },
    "createdAt": { "type": "integer", "minimum": 0 },
    "updatedAt": { "type": "integer", "minimum": 0 },
    "successCriteria": {
      "type": "array",
      "items": { "type": "string" }
    },
    "objectiveChecks": {
      "type": "object",
      "additionalProperties": {
        "type": "string",
        "enum": ["pending", "passed", "failed", "blocked", "not-required"]
      }
    },
    "artifacts": {
      "type": "object",
      "required": ["logPath", "promptPath", "reviewPath", "prUrl"],
      "properties": {
        "logPath": { "type": ["string", "null"] },
        "promptPath": { "type": ["string", "null"] },
        "reviewPath": { "type": ["string", "null"] },
        "prUrl": { "type": ["string", "null"] },
        "resultPath": { "type": ["string", "null"] },
        "summaryPath": { "type": ["string", "null"] }
      }
    },
    "workerRun": {
      "type": ["object", "null"],
      "properties": {
        "tool": { "type": ["string", "null"] },
        "role": { "type": ["string", "null"] },
        "startedAt": { "type": ["integer", "null"], "minimum": 0 },
        "finishedAt": { "type": ["integer", "null"], "minimum": 0 },
        "lastPolledAt": { "type": ["integer", "null"], "minimum": 0 },
        "exitCode": { "type": ["integer", "null"] },
        "status": { "type": ["string", "null"] },
        "mode": { "type": ["string", "null"] },
        "sessionId": { "type": ["string", "null"] },
        "pid": { "type": ["integer", "null"] },
        "logPath": { "type": ["string", "null"] },
        "resultPath": { "type": ["string", "null"] },
        "summary": { "type": ["string", "null"] }
      }
    },
    "notes": {
      "type": "array",
      "items": { "type": "string" }
    },
    "history": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["from", "to", "at", "reason", "actor", "attempt"],
        "properties": {
          "from": { "type": "string" },
          "to": { "type": "string" },
          "at": { "type": "integer", "minimum": 0 },
          "reason": { "type": "string", "minLength": 1 },
          "actor": { "type": "string", "enum": ["supervisor", "worker", "operator", "system"] },
          "attempt": { "type": "integer", "minimum": 1 }
        }
      }
    }
  }
}


path: docs/usage-guide.md
content: # local-coding-orchestrator usage guide

This guide describes the current v2 shape of `local-coding-orchestrator`.

## What it is now

The skill is no longer just a router for local coding CLIs.
It is now a lightweight supervisor skeleton with:
- persistent task records
- lifecycle transitions
- done policy evaluation
- retry brief generation
- pipeline presets
- worker launch adapters
- background worker reconcile
- environment failure classification

## Core scripts

### Task and lifecycle
- `assets/scripts/task-state.ps1`
- `assets/scripts/evaluate-done.ps1`

### Orchestration
- `assets/scripts/start-pipeline.ps1`
- `assets/scripts/generate-retry-brief.ps1`
- `assets/scripts/supervise-task.ps1`

### Worker execution
- `assets/scripts/launch-worker.ps1`
- `assets/scripts/reconcile-worker.ps1`
- `assets/scripts/run-codex.ps1`
- `assets/scripts/run-claude-code.ps1`
- `assets/scripts/run-opencode.ps1`

## Recommended happy path

1. create/init a task record
2. move it to `queued`
3. let supervisor auto-launch a background worker
4. reconcile worker state periodically
5. let supervisor recommend `awaiting-review`, `blocked`, or `completed`
6. use retry briefs only when the failure is semantic rather than environmental

## Example flow

### 1. initialize a task
```powershell
powershell -ExecutionPolicy Bypass -File assets/scripts/task-state.ps1 \
  -Action init -TaskId feat-demo -Repo D:/data/code/my-repo -TaskType feature \
  -Pipeline implement_and_review -Role implementer -Agent codex
```

Prefer a concrete repo path. Internally the scaffold now standardizes toward `repoPath` while remaining backward-compatible with the `repo` field.

### 2. queue the task
```powershell
powershell -ExecutionPolicy Bypass -File assets/scripts/task-state.ps1 \
  -Action transition -TaskId feat-demo -ToState queued -Reason "ready" -Actor supervisor
```

### 3. let supervisor auto-launch
```powershell
powershell -ExecutionPolicy Bypass -File assets/scripts/supervise-task.ps1 \
  -TaskId feat-demo -AutoLaunch -ApplyTransition -Json
```

### 3b. use auto-probe for constrained environments
```powershell
powershell -ExecutionPolicy Bypass -File assets/scripts/supervise-task.ps1 \
  -TaskId feat-demo -AutoLaunch -AutoProbe -ApplyTransition -Json
```

### 4. reconcile background worker later
```powershell
powershell -ExecutionPolicy Bypass -File assets/scripts/reconcile-worker.ps1 \
  -TaskId feat-demo -Json
```

### 5. ask supervisor what to do next
```powershell
powershell -ExecutionPolicy Bypass -File assets/scripts/supervise-task.ps1 \
  -TaskId feat-demo -Json
```

## Current known limits

- background worker completion is still heuristic
- worker output cleaning is basic
- environment failures are classified, but not all types are normalized yet
- task objective checks still need deeper automatic population from actual builds/tests/reviews

## Best use right now

Use this skill as a local orchestration scaffold and supervisor layer.
Do not treat it as a fully autonomous production runtime yet.


path: docs/v2-plan.md
content: # local-coding-orchestrator v2 plan

## Goal

Upgrade the skill from a prompt router into a lightweight local coding supervisor.

## Priority roadmap

### P1 - foundation
- add persistent task records
- define lifecycle states
- define done policies by task type
- define supervisor vs worker responsibilities

### P2 - orchestration quality
- add mechanical vs semantic retry model ✅
- add role-based pipelines ✅
- add objective progress reporting shape

### P3 - operational safety
- add resource scheduling guidance
- add worktree / artifact isolation rules ✅
- add operator controls for steer / cancel / reassign

### P4 - automation expansion
- add task queue ingestion from files/issues
- add stuck-task detection
- add optional proactive task discovery

## Recommended artifacts

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

## Recommended first implementation targets

1. task JSON schema
2. task state transition helper
3. done policy evaluator
4. retry brief generator
5. pipeline presets

## Notes

Do not add proactive discovery until the system is reliable at:
- persisting tasks
- supervising running workers
- distinguishing worker exit from task completion
- retrying semantically when task interpretation is wrong


path: docs/v2-summary.md
content: # v2 summary

`local-coding-orchestrator` has been upgraded from a local tool router into a v2 orchestration scaffold.

## What changed conceptually

Before:
- route a task to Codex, Claude Code, or OpenCode
- collect or compare outputs

Now:
- persist task records
- supervise lifecycle transitions
- launch workers with structured briefs
- reconcile background runs
- classify environment failures
- generate retry briefs
- evaluate done policies
- recommend or apply next orchestration steps

## What exists now

- task ledger and schema
- lifecycle state machine
- objective check evaluation
- role-based pipelines
- worker launch adapters
- background worker metadata
- worker reconcile loop
- environment-aware blocking
- dedicated probe-mode execution path
- partial objective-check backfill from worker summaries
- docs and interface guide for continued iteration

## What still needs hardening

- stronger session/process integration with OpenClaw-native handles
- richer parsing of build/test/review outcomes
- better background completion signals
- less heuristic result interpretation

## Bottom line

The skill is now best understood as a local orchestration runtime scaffold, not just a routing helper.


path: docs/worker-briefing.md
content: # Worker briefing guidance

This document defines how worker briefs should be shaped in constrained local environments.

## Principle

When shell policy is restrictive, do not start with broad context loading and complex command composition.
Start with the smallest useful repo probe.

## Preferred order

1. verify repo path access
2. inspect minimal directory structure
3. check whether build/test execution is realistically possible
4. only then attempt deeper implementation or review actions

## Avoid

- complex multi-line `powershell -Command` strings
- unnecessary shell batching just to gather context
- profile-dependent shell setup
- expensive probing before basic repo access is confirmed

## Prefer

- TaskFile prompt handoff
- filesystem inspection when available
- concise explanations of policy or sandbox limits
- early environment blocking when execution cannot proceed


path: docs/worker-launch.md
content: # Worker launch adapter

This document defines the first worker launch adapter for `local-coding-orchestrator`.

## Goal

Bridge pipeline presets to a concrete worker selection and a concrete worker brief.

## First-stage behavior

The first-stage adapter should:
1. load the task record
2. resolve the configured pipeline preset
3. choose a worker role
4. write a worker brief into `local-orchestrator/prompts/`
5. record the brief path into the task artifacts
6. return the intended launch command preview

## Why preview first

Directly attaching live worker execution is powerful but riskier.
Preview-first lets you verify:
- worker selection
- prompt structure
- role mapping
- artifact wiring

before you start large background runs.

## Current upgrade

The adapter now supports an initial synchronous execution mode and uses file-based prompt handoff.

In execution mode it can:
- call the actual tool wrapper
- pass prompt content by `TaskFile` instead of inline multi-line command arguments
- capture raw output into logs
- write result JSON and summary files
- update `workerRun` metadata in the task record

## Expected next step

After synchronous execution is stable, the adapter can:
- let the supervisor trigger worker launch automatically
- add background execution for long-running tasks
- attach richer parsing/cleaning of worker output
- feed execution results back into objective checks and review routing


path: docs/worker-reconcile.md
content: # Worker reconcile loop

This document defines the first reconcile step for background worker runs.

## Goal

Take a launched background worker and fold its runtime state back into the task record.

## What reconcile does

- reads the task record
- checks whether the recorded PID is still alive
- updates `lastPolledAt`
- extracts a short log summary
- if the process ended, writes completion metadata
- writes result and summary artifacts when possible

## Important limitation

Reconcile tells you what happened to the worker run and now also writes lightweight classification metadata.
It still does not decide that the task is done.

The supervisor must still decide whether:
- objective checks passed
- review is needed
- retry should be generated
- the task can transition to `completed`

## First heuristic

The initial reconcile step uses a lightweight text heuristic on logs to classify the worker run as `completed` or `failed`.
It also assigns an initial failure kind such as:
- `environment-missing`
- `repo-unavailable`
- `credential-missing`
- `environment-blocked`
- `generic-failure`

That heuristic should be replaced or tightened over time.


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)