SuperAPI AI Directory

orchestrate

General & other

View repository

Updated 10-16 08:43

About this skill

Orchestrate Skill(v1 report-only)

Declarative intent → planner agent derives a workflow plan that changes with repo state → human preview approval → read-only fanout → pre/post no-change verification → report goes through the existing doc review loop. Control plane (.claude_workflows/) is the orchestrator's only state surface; review reminder state has been stored outside the repo since hook-lightweighting § 3.2 (~/.cache/sd0x-dev-flow/), and the orchestrator neither reads nor writes it.

Trigger

  • Keywords: orchestrate, workflow orchestration, orchestration, plan this workflow, audit the repo for, automatic orchestration

When NOT to Use

  • Steps that modify files when executed (v1 always outputs as proposed-manual, handed to a human through the normal process)
  • Tasks that a single skill can complete (call that skill directly)
  • Code review(/codex-review-fast)、doc review(/codex-review-doc)
  • Existing fixed-shape deep exploration (/deep-explore) or research (/deep-research) — orchestrate is a cross-skill orchestration layer and does not replace them

Flags

Flag Behavior
(none) / --dry-run planning + preview only (plan preview = default deliverable)
--execute preview + after AskUserQuestion approvalexecute read-only fanout → verify → report
--budget S|M|L Budget tier (default M); over-budget fails closed, see scripts/plan-context.js
(internal)plan-context.js --out packets are always written to files, returning only a summary (including sha256); the main session must not hold the full packet (~81 KB × 2 → ~0.5 KB), see references/planner-prompt.md
--resume <run-id> withoriginal baseline compare: no drift → continue running pending steps;drift → mark run needs_human and stop(must not re-snapshot the baseline to whitewash it; to continue, you can only start a new run = new baseline + new approval). baseline itselfstays in .claude_workflows/<run-id>/baseline.json, still present across sessions; but baseline_sha256 lives only in the main session's context, and run-state deliberately does not store it (storing it next to the baseline is equivalent to no binding). Therefore the actual limit on resume is the digest, not the file: if context is lost / session changes → cannot resume, start a new run
--backend dw|agent force fanout backend; default auto (Workflow use if the tool is available, otherwise background Agent ≤3 concurrent) — same admission

Workflow

sequenceDiagram
    participant U as User
    participant C as Claude(主 session)
    participant S as scripts
    participant P as Planner(Explore,admission 約束)
    participant W as Fanout workers(read-only)
    U->>C: /orchestrate "意圖" --execute
    C->>S: plan-context.js --out(封包寫檔,主 session 只收摘要)
    C->>S: run-verify.js snapshot > .claude_workflows/<run-id>/baseline.json(digest 由 stderr 收進 session)
    C->>P: 背景派發 planner(傳封包路徑,非內容)
    P->>P: Read 封包
    P-->>C: plan JSON
    C->>S: run-verify.js compare --baseline-sha256(planning 後立即驗)
    C->>S: validate-plan.js --context-sha256 <摘要 sha256>(admission + gate lint + 封包完整性)
    C->>U: Plan preview + AskUserQuestion
    U-->>C: 核可
    C->>C: Write run-state(redact 先行)
    loop 每個 parallel_group(≤ max_waves)
        C->>W: 平行派發(單訊息)
        W-->>C: findings(context packet)
    end
    C->>S: run-verify.js compare --baseline-sha256(同一 baseline,同一 digest)
    alt drift
        C->>U: ⚠️ Need Human(run 標 failed,不寫報告)
    else 無變更
        C->>C: Write 報告 → /codex-review-doc 接手
    end

Baseline timing invariant (hard rule)

run-verify.js snapshot mustprecede any agent dispatch(including planner) — otherwise mutations during planning will be merged into the baseline, and the report-only proof becomes invalid. snapshot's stdout (the baseline itself) is always directed to .claude_workflows/<run-id>/baseline.json, and both compares read from --baseline <該路徑> ; the main session does not retain baseline content (it contains content hashes for the whole tree, and carrying it verbatim in context is both expensive and will be dropped by compaction).digest takes another path: it exists only in the main session's context and is never written into .claude_workflows/. This split of "the body lands on disk, the digest stays in the session" is exactly the binding itself — the baseline file has no value to a worker, because it cannot forge the digest held by the main session; storing the digest next to the baseline is equivalent to no binding. planner and fanout workers are constrained bythe same admission allowlist (planner = Explore, the only one in the list with research capability). After planning ends and before preview, compare once (early interception); after execute ends, useSame baseline compare again (final interception).

Both comparesmustcarry --baseline-sha256, value taken from the snapshot printed to stderr by baseline_sha256=…. Without this binding, compare only proves "the file I received matches the repo"—and the worker, after making changes, can rerun snapshot once to produce such a file, so drift reads as ok: true. The digest is obtained by the main sessionbefore any dispatchand is also returned by the main session; the worker never touches it throughout, so it can block substitution on the worker plane; itcannot blockan already-taken-over main session—no mechanism at that layer can block it, because both parameters are determined by it. Same trust chain as validate-plan.js --context-sha256 .

Admission(deny-by-default)

Fanout candidates are always checked against references/admission-allowlist.json(v1 only Explore + performance-optimizer;coverage-analyst / git-investigator is explicitly excluded, reason in file). Not on the list = rejected, regardless of its allowed-tools declaration—allowed-tools cannot be trusted as a read-only criterion. List changes must go through review + re-review of run-verify.js verification-plane coverage.

Report-only enforcement mechanism (not capability-layer blocking; best-effort fail-closed defense in depth):report-only Does not rely oncapability-layer blocking of the Skill tool—both seemingly viable capability paths do not apply. v1's report-only is a best-effort fail-closed combination of three things: admission allowlist (only curated read-only-oriented workers accepted), verification-layer drift detection, and behavioral-layer contractBest-effort fail-closed combination,notan absolute guarantee against an admitted Bash-capable worker—admitted Explore has Bash and can trigger the residual bypasses listed in the verification-layer row of the table below (e.g. assume-unchanged index hiding), so the strength of v1 report-only actually depends on the curation of the admission list; residual bypasses are explicitly deferred to v2 (see table below and end of paragraph):

Layer Mechanism Guarantee Limitation/Reason
Capability layer Omit allowed-tools in Skill No hard block Per Claude Code,allowed-tools is only apre-approvedlist; tools not listed can still be called under the user's normal permissions
Capability layer disallowed-tools: Skill Hard block, butdeliberately unused Per current Claude Code behavior, it is only lifted on the next user message; it also kills the same round's /codex-review-doc handoff (which also uses the Skill tool), making the run forever unable to reach Mergeable/done
Verification layer run-verify.js snapshot/compare primitives (SC-2) For the git monitoring surface(porcelain + tracked/untracked/ignored content hash + tracked mode + untracked/ignored directory nodes + refs/config/worktree/stash), provides fail-closed drift evidence for repo state changes (drift → exit 1) not a hard sequencing guarantee: call order, run-state transitions, and report suppression are handled by the SKILL.md dispatch flow and the references/execution-policy.md behavioral contract; and there are residual risks (node_modules/、.venv/、build/、dist/, writes outside the repo,assume-unchanged/skip-worktree index hiding, etc., see admission-allowlist.json of residual_risk);.claude_workflows/ control plane is excluded by-design (the orchestrator itself writes run-state, not a monitoring plane)
Behavior layer planner/executor contract v1 does not execute main-skill mutating concepts are all converted to kind: proposed-manual(mutating: true); non-mutating main-skill remains kind: main-skill subject to validate-plan.js A4 target validation, but the v1 executor does not dispatch

In dispatch order,run-verify.js snapshot atbefore any agent dispatchtake a baseline, and after execute use the same baseline compare; any drift falling within the monitored git-scoped plane → run marked failed、no report written(see references/execution-policy.md fail-closed matrix). If v2 wants to open main-skill execution, the precondition is that skill_candidates carries a mutation flag so that mutating targets are rejected first at A4 + a reviewed read-only allowlist (see validate-plan.js A4 comment), rather than lifting any Skill capability block.

Run-state management

Rule Content
Path .claude_workflows/<run-id>.json(gitignored;run-id = <UTC yyyymmdd-HHMMSS>-<intent-slug>)
Write tool Main session Write(gitignored path, does not enter the review plane)
Redaction Before writing to disk, pass the scripts/security-redact.js full contract:scanHighConfidence truthy → abort fail-closed(do not write the file, run marked needs_human, prompt to rewrite the intent); medium → write after masking
FIFO Keep the most recent 10 runs; delete the oldest when exceeded.Count both together, delete both together:<run-id>.json(run-state) and the same-named <run-id>/ directory (packet + plan + baseline). Cleaning only .json will let plan-context.json(~81 KB/run) accumulate indefinitely in the gitignored directory; the packet already contains the full catalog and repo signals, so keeping it after expiry is just garbage and an exposure surface.Execution method(canonical path, not a capability boundary: this skill has not pre-approved Bash(rm:*), but the pre-approved Bash(node:*) likewise covers node -e 'fs.rmSync(…)', and there is no mechanism forcing deletion to go through this script; containment holds only when this path is taken):node "${CLAUDE_PLUGIN_ROOT}/skills/orchestrate/scripts/prune-runs.js"(first run --dry-run to see the list).The path must be an absolute plugin root path, consistent with the form in which this skill calls plan-context.js/validate-plan.js : when the skill executes, the cwd istarget repo, not the plugin directory, so a repo-relative path only happens to work when developing inside this repo; deployed to any other project it is MODULE_NOT_FOUND—retention therefore never runs, and .claude_workflows/ keeps accumulating at ~81 KB per run, exactly the leak this script is meant to prevent. The script reads the run-id from the directory itself, rejects roots that are not .claude_workflows and symlinks, and keeps and reports any unrecognized filenames
Early packet deletion (recommended) validate-plan.js passes and the plan enters execution,<run-id>/plan-context.json has no further use—it can be deleted immediately, keeping only <run-id>/plan.json for post-hoc audit. The digest has already been compared at validation time; keeping the packet afterward adds no guarantee
Final state done ofthe only path = the report's doc review returns Mergeable gate; returns blocked / degraded / cannot determine → needs_human(must not be presented as complete)

output isolation contract

/orchestrate own outputforbiddengate sentinels appear (gate header line, bare Ready / Mergeable / Blocked / All-Pass markers) — these are behavioral-layer signals; when the model and reviewer read the conversation they will treat them as gate verdicts, and orchestrate's summary must not fabricate a verdict that no gate produced. The run summary uses ## Orchestrate Run Summary + [ORCHESTRATE_RUN] run_id=… status=… structural lines. After the report is written, the doc gate sentinel is output by /codex-review-doc itself (legitimate path).

Verification Checklist

  • snapshot precedes any agent dispatch, and stdout is directed to .claude_workflows/<run-id>/baseline.json; compare once after planning + once after execute (same baseline file)
  • baseline_sha256 stays only in the main session context, not written to .claude_workflows/ any file
  • both compares carry --baseline-sha256(value taken from the snapshot stderr's baseline_sha256=); if not carried or mismatched, exit 1
  • the plan passes all rules of validate-plan.js (A1-A4 / G1-G2 / O1 / B1 / S1 / SCHEMA)
  • validate-plan.js carry in --context-sha256(value taken from plan-context.js --out summary's sha256);if no digest is carried, always exit 1,--context -(stdin) is no exception— what is bound is the channel the digest travels through that the worker cannot touch, not which fd the bytes come in from
  • before execution, human approval via AskUserQuestion
  • run final state correct: drift → failed; doc gate not passed → needs_human;Mergeable → done
  • no git state-changing operations whatsoever (add / commit / push / stash / tag / config / checkout / reset etc. —allowed-tools only read-only git commands are allowed, mutations are backstopped by run-verify.js compare)

Bundled References

File Purpose
planner-prompt.md Planner independently derives the contract (does not feed Claude pre-drafted steps)
plan-schema.md Plan JSON schema canon (including lint rule cross-reference)
execution-policy.md Backend selection, waves, fail-closed matrix
admission-allowlist.json Fanout allowlist (curated + exclusion records)

Examples

Input: /orchestrate "audit 全 repo hook 的 fail-open 路徑" --execute
Action: context → snapshot → planner → lint → preview → 核可 → 3× Explore fanout → compare → 報告 → doc review
Input: /orchestrate "完成 feature X 並確保品質"
Action: 規劃 + 預覽即止——mutating 步驟以 proposed-manual 列出(含 code-review + precommit gate),交人走正常流程