execute

name

execute

description

Consumes a plan file produced by the plan skill and ships it to working artifacts. Dispatches independent units in parallel waves per the plan's dependency graph, runs a single consolidated Oracle review at the end, and updates the plan's Completion Status table inline as units finish. Includes a specialized sub-path for generating new skills via skill-creator assets (scripts, templates, reference docs). Use when a plan file already exists and the user wants it carried out; do NOT trigger on bare 'run tests', bare 'build', or bare '实现' without a plan reference. Triggers: execute, execute plan, execute the plan, run plan, run the plan, dispatch plan, ship plan, build from plan. 触发: 执行, 执行计划, 施工, 实施, 动工, 开干, 按计划执行.

Execute - Plan-to-Artifact Parallel Wave Orchestrator

I am the execute skill: a delegator that consumes a plan file produced by the `plan` skill and ships each U-block in parallel waves until every unit reaches a terminal Completion Status.

I never author artifact code myself. I dispatch category-specialist subagents per wave, collect their structured VERIFICATION payloads, retry failures once with captured failure context, propagate failures along the DAG, run a single consolidated Oracle review at the end, and update the plan's Completion Status footer in place via the edit tool.

Architecture Overview

Plan file (explicit {plan_path} argument or scanned from session context)
      |
      v
Phase 0: Ingest Plan              (parse, validate, flip PLANNED to IN_PROGRESS)
      |
      v
Phase 1: DAG Build + Waves        (topological sort; halt on cycle or file collision)
      |
      v
Phase 2: Wave Dispatch            (parallel task() in a single assistant turn)
      |
      v
Phase 3: Collect + Retry (x1)     (parse VERIFICATION; retry failures once)
      |
      v
Phase 4: Failure Propagation      (transitive skip; advance to next live wave)
      |
      v
Phase 5: Skill-Generation (opt)   (loads references/skill-generation.md if triggered)
      |
      v
Phase 6: Oracle + Status Writeback (one foreground oracle; `edit` the footer)
      |
      v
Phase 7: Handoff                  (one-line summary; optional escalation)

Boundary	Rule
Input	A plan file path (explicit or inferred from session) matching the plan skill schema.
Output	The same plan file with its Completion Status: line updated, plus an appended ### Execution Log subsection.
Code editing	Forbidden. Every artifact write goes through a category subagent. The sole carve-out is edit on the plan's Completion Status line and Execution Log section.
Subagent dispatch	Parallel task(run_in_background=true) per wave, dispatched in a single assistant turn.
User interaction	Only on NEEDS_CONTEXT halts or the final handoff summary. No mid-run questions.
Language	Skill prose stays English. The final user-facing summary matches the user's language.

CRITICAL RULES

1. HARD GATE: `execute` is a delegator. It does not edit source files, run tests, or scaffold projects itself. The sole carve-out is writing the Completion Status line in the plan file via the `edit` tool. Rationale: mixing delegation and direct authoring creates non-reproducible side effects that subagents cannot audit.

2. SINGLE-TURN PARALLEL DISPATCH: every unit in a wave must be dispatched in one assistant turn via parallel task(run_in_background=true) calls. Serial dispatch across multiple turns is a protocol violation. Rationale: waves exist so independent work runs concurrently; serial turns erase the wave abstraction and inflate wall time linearly with unit count.

3. PLAN IS IMMUTABLE: never renumber U-IDs, edit U-block Goals or Approaches, or change the Dependencies table. Only the Completion Status: line and a new ### Execution Log (YYYY-MM-DD) subsection may be appended. Rationale: downstream audits trace artifacts back to stable U-IDs; renumbering breaks provenance.

4. NEVER DISPATCH skill-creator AS A SUBAGENT: skill-creator's workflow includes a human approval turn that stalls task() forever. It is read-only reference material. Rationale: references/skill-generation.md contains the full loop-break explanation; invoking skill-creator via task hangs the run.

5. RETRY EXACTLY ONCE: when a subagent fails (non-zero exit_code or missing === VERIFICATION ===), retry exactly one time with the original failure output injected into the follow-up prompt, reusing the task's session_id to preserve context. Do not retry twice. Rationale: two failures with identical context signal a plan-level gap; escalate instead of looping.

6. DEPENDENCY-AWARE FAILURE PROPAGATION: a FAILED unit marks its transitive dependents SKIPPED. Independent branches of the DAG continue executing. Rationale: cutting a whole wave on one failure wastes latent progress; blocking only the dependents prevents corrupting downstream artifacts.

7. ONE ORACLE REVIEW AT THE END, FOREGROUND: dispatch exactly one task(subagent_type="oracle", run_in_background=false) after Phase 4 converges. Rationale: Oracle is consolidation, not per-unit QA; foreground ensures its verdict lands before status writeback.

8. LANGUAGE MATCHING FOR FINAL REPORT ONLY: the one-line handoff summary and any NEEDS_CONTEXT escalation surface in the user's original language. All skill prose, rules, and agent prompts stay in English. Rationale: subagents are language-brittle; user-facing copy is not.

9. LAZY-LOAD REFERENCES: read references/plan-parser.md only in Phase 0.2, references/skill-generation.md only when Phase 5 triggers, and references/oracle-review.md only in Phase 6. Rationale: context budget is finite and not every reference fires on every run.

Phase 0: Ingest Plan

0.1 Resolve the plan path

Check inputs in priority order:

1. Explicit {plan_path} argument passed with the skill invocation.
2. Scan current session context for the plan signature: a markdown file whose frontmatter contains status: active, whose body contains ## Implementation Units, and whose body has at least one heading matching #### U\d+:. If exactly one file matches, use it.
3. Otherwise, ASK via the question tool: "Which plan file should I execute? Paste an absolute path."

0.2 Validate via plan-parser

Load references/plan-parser.md now (lazy-load; this is the first reference read). Walk every halt condition listed there: missing Dependencies table, same-wave Files: collisions, unknown [category] hints, malformed Completion Status line. If any halt trips, emit the 4-line escalation format (STATUS / REASON / ATTEMPTED / RECOMMENDATION) with STATUS: NEEDS_CONTEXT and exit without dispatching any unit.

0.3 Mark start

First, read the authoritative status line per references/plan-parser.md §Completion Status Field. The plan skill emits the footer in one of two canonical formats:

• Backticked form (the format plan skill currently writes): `PLANNED` on its own line under a ## Completion Status H2 header.
• Inline form: Completion Status: PLANNED on its own line.

Use the edit tool with the EXACT literal string found in the plan (preserving backticks or lack thereof). Replace the PLANNED token with IN_PROGRESS, keeping the surrounding characters identical. For example, if the file contains `PLANNED`, replace `PLANNED` with `IN_PROGRESS`; if it contains Completion Status: PLANNED, replace that full line. Do NOT assume one format; read and match.

Handle edge cases:

• Line is already IN_PROGRESS: print a one-line warning ("plan is resuming from IN_PROGRESS") and skip the edit; the user may be rerunning.
• Line is DONE or DONE_WITH_CONCERNS: halt with NEEDS_CONTEXT "plan already shipped; refuse to re-execute without explicit user override".
• Line is BLOCKED or NEEDS_CONTEXT: overwrite to IN_PROGRESS (preserving the same backticked-or-inline form) and proceed; the prior halt is assumed resolved.

Phase 1: DAG Build and Wave Computation

1.1 Topological sort

Read the Dependencies column of every U-block and build an adjacency map {U_id: [depends_on...]}. Kahn's algorithm produces the wave list: W1 contains units with zero dependencies; W2 contains units whose dependencies all live in W1; and so on.

1.2 Cycle detection

If any unit remains unassigned after the topological pass, the graph contains a cycle. Halt with NEEDS_CONTEXT: "plan DAG has a cycle among U{ids}; the plan skill must be rerun to re-derive dependencies".

1.3 Same-wave file-collision detection

For every wave, union the Files: lists of its member units. If two units in the same wave both list the same file path, halt with NEEDS_CONTEXT: "file {path} is claimed by both {U_a} and {U_b} in wave {N}; these units must serialize".

1.4 Emit the wave list

Produce the ordered list [W1=[U_a,U_b], W2=[U_c], W3=[U_d,U_e,U_f], ...]. This list drives Phase 2.

Phase 2: Wave Dispatch Protocol

All units in a wave must be dispatched in a single assistant turn via parallel task() calls. Serial dispatch is a protocol violation. This section is the heart of the skill; violations negate every downstream optimization.

2.1 Correct parallel dispatch

(one assistant turn)
task(subagent_type="{category}", run_in_background=true, description="{U1} {short goal}", prompt={U1_prompt})
task(subagent_type="{category}", run_in_background=true, description="{U2} {short goal}", prompt={U2_prompt})
task(subagent_type="{category}", run_in_background=true, description="{U3} {short goal}", prompt={U3_prompt})
# end response; wait for system-reminder

2.2 Wrong serial dispatch

(turn 1) task({U1}); wait for result
(turn 2) task({U2}); wait for result
(turn 3) task({U3}); wait for result
# This is serial execution; defeats parallelism

2.3 Category mapping

For each U-block, read the [category] hint exactly as defined in references/plan-parser.md.

• If [category] equals oracle, pass subagent_type="oracle".
• Otherwise pass subagent_type={category} (for example quick, unspecified-low, unspecified-high, ultrabrain, visual-engineering, writing, artistry).

2.4 Subagent prompt template

Every dispatched prompt must require the agent to end its response with this structured verification block:

=== VERIFICATION ===
exit_code: {0 or non-zero}
commands:
  - cmd: "{command}"
    exit: {int}
    output: "{truncated}"
    pass: {true or false}
=== END VERIFICATION ===

Units that omit this block fail Phase 3 parsing and are retried once with an explicit reminder.

2.5 Wait for completion

End your response after dispatching. When <system-reminder> arrives announcing completion, collect each agent's payload via background_output(task_id="..."). Never poll. Never re-fire a task that has not yet reported.

Phase 3: Collect and Retry

3.1 Parse each payload

For each completed task, call background_output(task_id="{task_id}") once and search for === VERIFICATION ===. Parse exit_code:

• exit_code == 0 with VERIFICATION block present: mark SUCCESS.
• exit_code != 0, or VERIFICATION block missing: mark CANDIDATE_RETRY.
• Agent returned an explicit escalation (NEEDS_CONTEXT or BLOCKED): mark ESCALATED, skip retry, and surface the escalation to the user.

3.2 Retry once

For each CANDIDATE_RETRY, dispatch one follow-up task(subagent_type={same}, run_in_background=true, session_id={original_task_session_id}, prompt={original_prompt + "\n\n## Previous attempt failed. stderr/output was:\n" + failure_output}). Reusing session_id preserves the agent's prior context window.

3.3 Final grading

If the retry returns exit_code == 0 with a VERIFICATION block, mark SUCCESS. Otherwise mark FAILED. Never retry a second time.

Phase 4: Failure Propagation and Subsequent Waves

4.1 Compute the skip set

For each unit marked FAILED, traverse the reverse dependency graph and mark every transitive dependent SKIPPED. A unit in a later wave whose dependencies include any FAILED unit must not dispatch.

4.2 Advance waves

Proceed to the next wave. If every unit in wave N+1 is SKIPPED, advance to wave N+2; keep advancing until a wave contains at least one live unit or the wave list is exhausted. Re-run Phase 2 for the live units of the surviving wave.

4.3 Terminal convergence

When no further waves remain, aggregate outcomes into a proposed status:

• All units SUCCESS: propose DONE.
• Any FAILED after retry, rest SUCCESS or SKIPPED: propose DONE_WITH_CONCERNS.
• Wave 1 entirely FAILED (no downstream work possible): propose BLOCKED.

Phase 5: Skill-Generation Sub-Path (Conditional)

5.1 Trigger detection

Activate this sub-path ONCE PER RUN (not per-U-block) if ANY U-block in the plan has a Goal: line mentioning "create/generate a new skill" or a Files: path containing .opencode/skills/{name}/. The quick_validate gate (5.3) runs once after all triggering U-blocks have completed, against the final assembled skill directory. Running it per-unit wastes tokens and can flag transient mid-build states as invalid.

5.2 Load the reference

Load references/skill-generation.md now. Follow its instructions verbatim; it specifies how to consume skill-creator's bundled scripts, templates, and reference docs as static assets.

5.3 Validation gate

Use skill-creator's quick_validate script as a hard gate on the produced skill directory. A failing validation marks the unit FAILED in Phase 3 semantics.

5.4 Never dispatch skill-creator

Do NOT issue task(subagent_type="skill-creator", ...). The reference explains the loop-break reason: skill-creator asks human approval questions mid-workflow, which stalls any subagent call indefinitely. Read its assets as reference material; do not invoke it.

Phase 6: Oracle Review and Status Finalization

6.1 Load the reference

Load references/oracle-review.md now. It contains the full Oracle prompt template and the verdict-to-status mapping table.

6.2 Compute proposed status

Using Phase 4's aggregation:

• All units SUCCESS: propose DONE.
• Any FAILED after retry, rest SUCCESS or SKIPPED: propose DONE_WITH_CONCERNS.
• Wave 1 entirely FAILED: propose BLOCKED.
• Halt hit pre-dispatch: NEEDS_CONTEXT (already written in Phase 0).

6.3 Dispatch Oracle (with in-wave deduplication)

Check first: did any U-block in any prior or current wave (including the final wave itself) have [category]: oracle and return SUCCESS? If yes, that unit already played the Oracle role; reuse its verdict and SKIP the Phase 6 Oracle dispatch. This prevents the double-Oracle waste that occurs when a plan author embeds an [oracle] unit at the tail (the plan skill conventionally does so).

Otherwise, build the Oracle prompt per the reference template (plan path, per-unit outcomes, VERIFICATION blocks). Dispatch exactly one task(subagent_type="oracle", run_in_background=false). Wait for its synchronous return.

6.4 Apply final status

Parse Oracle's verdict. Per the reference's mapping rules, derive the final Completion Status value. Use the edit tool with the EXACT literal string currently in the plan (same backticked-or-inline form chosen in Phase 0.3). Replace the IN_PROGRESS token with the final value. For the backticked form, replace `IN_PROGRESS` with `{final}`; for the inline form, replace Completion Status: IN_PROGRESS with Completion Status: {final}.

6.5 Append execution log

Append an ### Execution Log (YYYY-MM-DD) subsection using the edit tool with an anchor-replace pattern. Anchor on the exact final-status line from 6.4. Construct newString = {exact status line} + two newlines + the log body below. This uses edit (never write) and preserves all other plan content.

Log body format:

### Execution Log (YYYY-MM-DD)

**Waves executed:** W1 (N units) · W2 (N units) · ...
**Artifacts:** {file paths pulled from VERIFICATION blocks, deduped}
**Oracle verdict:** {PASS | FAIL} - {one-line summary}
**Concerns:** {bulleted list from Oracle's `<concerns_to_record>`, empty if none}

Phase 7: Handoff

7.1 One-line summary

Print to the user: Plan {plan_path} executed. Waves: {N}. Units: {total} (success={s}, failed={f}, skipped={k}). Final Status: {status}.

7.2 Escalation on concerns

If the final status is DONE_WITH_CONCERNS or BLOCKED, additionally surface the 4-line escalation format (STATUS / REASON / ATTEMPTED / RECOMMENDATION) built from Oracle's concerns plus the failed-unit summary.

7.3 No downstream dispatch

Do not invoke further skills. The user decides whether to rerun plan, start a scoped rerun of execute, or hand off to review tooling.

Completion Status Vocabulary

Canonical 6-value vocabulary. Reference: ~/.opencode/skills/plan/SKILL.md lines 464-482.

Value	Meaning
PLANNED	Plan file just emitted; no units started. Every plan begins at this status.
IN_PROGRESS	One or more U-blocks actively running under execute.
DONE	All U-blocks complete, all test scenarios pass, validator checklist fully [x].
DONE_WITH_CONCERNS	All units functionally complete but Section 5 checklist items failed or deferred Open Questions remain.
BLOCKED	Execution cannot continue. Must state what was attempted and the external unblocker required.
NEEDS_CONTEXT	Information is missing and execute cannot proceed. Must state exactly what is missing.

Escalation format (used for BLOCKED, NEEDS_CONTEXT, and risk-bearing DONE_WITH_CONCERNS):

STATUS: {one of the 6}
REASON: {1-2 sentences, concrete}
ATTEMPTED: {what was tried}
RECOMMENDATION: {the specific next action required}

Anti-Patterns

Violation	Severity
Dispatching a wave's units across multiple assistant turns (serial dispatch)	CRITICAL
Retrying a failed unit more than once	CRITICAL
Renumbering U-IDs or rewriting U-block Goals or Approaches	CRITICAL
Calling task(subagent_type="skill-creator", ...)	CRITICAL
Writing artifact source files directly from the execute skill	CRITICAL
Skipping the final Oracle review	CRITICAL
Fabricating replacement U-blocks when the plan is malformed	CRITICAL
Using write instead of edit to update the Completion Status line	HIGH
Polling background_output before <system-reminder> arrives	HIGH
Running tests or builds directly instead of via category subagents	HIGH
Modifying plan content beyond the Completion Status line and the Execution Log subsection	HIGH
Loading all three reference files upfront instead of lazy-loading per phase	MEDIUM