Research Plan Executor

Invocation: star-plan-executor PLAN_NAME [DESCRIPTION]. Resolve the leaf by slug, numeric prefix, or filename. Remaining natural language may constrain scope or explicitly authorize execution choices; ask only when the target, research scope, acceptance criteria, cost, key inputs, destructive action, or overwrite remains unresolved.

Shared conventions. Resolve the invocation target and mode first. Then read only the sections of docs/mds/star-workflow/research-workflow-conventions.md that the selected goal uses; load cited references/ and assets/ only when entering their branch or mode. Read .env once for the needed STAR_LANG, INVOLVE, STAR_*_MODEL, and runtime values; reuse values and convention text still visible verbatim. Resolve language under conventions §7.6: explicit user request first, then valid STAR_LANG, then dialogue or invocation language; use the corresponding localized resources. SKILL_zh.md is for human readers and is never loaded at runtime. Preserve an existing document's frontmatter language. Clear natural-language instructions may select the target and scope and authorize the corresponding action; do not ask again for work already authorized.

After resolving the target, run scripts/scan.sh --slim and treat its plan-frontmatter and run-log-frontmatter digest as raw input to Steps 0–1; still read the target leaf in full. If the script fails, read the plan files directly and report the fallback.

Passing a tier model. Resolve the selected mode's PLAN, EXEC, or READ model for the current harness under conventions §10.8. Pass the resolved value when delegation accepts a per-dispatch model; use a fresh, self-contained context if model selection conflicts with full context inheritance. READ-tier collection and blind review do not inherit the producer's conversation. With an empty value, omit the model override and preserve the host/session default; if a configured value cannot be selected, keep the work here and state why. Never translate provider model names, invent parameters, or launch another CLI. A delegate carrying tier= does not relocate the whole run again and records its actual model from its own session provenance.

Role

Drive one leaf execution sub-plan to its done-criterion by changing code and running light validation. Upstream, star-plan-decomposer owns the sub-plan's strategy and task breakdown; this skill owns implementation results: code under ${CODE_NAME}/, intermediate working files under tasks/<plan-name>/, and generated artifacts plus verification evidence under wkdrs/<run>/. Derive <plan-name> from the selected plan filename by removing _plan.md (for example, 00_demo_plan.md → tasks/00_demo/).

Execute; do not re-strategize or silently re-decompose. If §3 or §5 is too vague to execute, report the concrete gaps and route back to star-plan-decomposer.

Core Principles

1. Read before writing. Inspect .env, the named inputs, the relevant code, and the actual launch entry point before planning a change. Produce a current-state-versus-required gap list. Follow references/orient_checklist.md.
2. Make the plan visible, then proceed within scope. Convert the sub-plan into an EXEC_PLAN whose actions each name files, commands, artifacts, and the action's own check. Track it with your plan tool — one step per action, each marked in_progress while it is in flight — and summarize the plan in commentary. Invoking this executor authorizes ordinary in-scope implementation and light validation; request new direction only when a decision would materially change scope or require new authority.
3. Delegate what benefits from it. How the work is split is the main agent's call. Delegate bounded, independent work whenever collaboration tools are available and delegation materially helps — that is the ordinary case, not the exception. When that condition is met, dispatch a writing sub-agent for implementation or a read-only sub-agent for read-only orientation. Never create one subagent per trivial sequential step. Give each delegate the narrow brief in references/agent_dispatch_spec.md; the main agent remains responsible for integration and verified checks. It may accept inspectable original command/result evidence tied to the corresponding code version; it re-runs a narrow check when provenance is missing or stale and after integration changes relevant behavior. That file's tree discipline — an action-start snapshot, restore before retry, and an explicit or already-recorded decision about edits of an action that ended blocked — binds local execution too and never erases pre-existing/user work or raw evidence.
4. Stop before unapproved heavy or irreversible work. Long or multi-GPU training, full-dataset evaluation, costly API calls, unbounded jobs, and overwrites of valuable artifacts cross the STOP line. Prepare the reproducible command, cost, and outputs. Launch only under a specific applicable user authorization or the bounded star-auto exception; otherwise hand it to the user. Follow references/stop_line_rules.md.
5. Record verified state — and keep the sub-plan true. Store EXEC_PLAN.md and EXEC_LOG.md under wkdrs/<run>/. Update the log after each action's check. Keep only exec_status, exec_runs, and updated in the sub-plan frontmatter — plus, where execution provably diverges from the sub-plan, or settles a value it left open that a method document will cite, an authorized write-back of the affected §2–§5 content with a ## Revision History entry (references/plan_sync_rules.md), so the plan a user rereads later matches what was executed. Reuse an existing specific authorization; a generic implementation request and auto=unattended do not authorize changing research scope or §5 acceptance.
6. Use the project runtime and layout. Read CONDA_HOME, PYTHON_HOME, and CODE_NAME from .env; never guess local paths or use system Python. Use execs/run.sh when it is the project entrypoint. Create tasks/<plan-name>/ for intermediate files needed while executing that plan; put reusable run scripts in execs/scpts/, generated output and durable execution records in wkdrs/<run>/, data in datas/, weights in inits/, and code in ${CODE_NAME}/. Follow AGENTS.md.

Workflow

Where this run executes. The overall run uses PLAN and stays with the user-facing session whenever a required decision remains. Step 4 (execute and verify) uses EXEC through the handoff below. Existing execution authorization counts; a tier= delegate never re-hands the same phase.

Step 0: Resolve the target

1. Match PLAN_NAME against the plans the opening load's digest lists, by slug, numeric prefix, or full filename; it is the listing, so do not list the directory again.
2. Only leaves are executable. If the target has non-empty children:, list its leaves and ask which to execute (recommend the first ready one), or offer to process them one at a time in dependency order.
3. If the target is absent or ambiguous, list concise candidates and ask one direct question.
4. Read the selected sub-plan in full.

Step 1: Check readiness

1. Require concrete §3 Task Breakdown and §5 Done-Criteria. If they are mostly [TBD] / 【待定】, report the missing decisions and ask whether to return to star-plan-decomposer (recommended) or continue with the remaining uncertainty explicitly recorded.
2. Verify named datasets, weights, code modules, and every depends_on sibling — read their state from the digest, which already carries every sibling's frontmatter, rather than opening each one. If a hard dependency is missing or an upstream sibling is not exec_status: done, stop and report the exact blocker. A missing dataset or weight is a decomposition gap, not a blocker to work around: name the data-readiness leaf that should own it, or route to star-plan-decomposer <parent> to add one.
3. Refuse a leaf carrying dropped:, or with a dropped ancestor: name the node the drop was written on and stop. Reviving it starts with clearing that field through star-plan-reviser — running a direction the user already decided against spends compute on work nothing will count.
4. Check the leaf is right-sized. An executable leaf can still be the wrong unit of work, and nothing re-checks that after the split. Apply the sizing judgement the decomposer applies to its own drafts — one independently checkable chunk (its references/subplan_rubric.md, item 8) — to the plan as it stands; every signal is in the text Step 0 already read, so the check costs no call of its own. Strong, any one is enough: §5 states more than one independent check; §3 crosses the STOP line more than once, each hand-back a natural leaf boundary; §3 mixes acquiring data, building code, and running experiments in one unit, where a dataset is owed a leaf of its own. Weak, two together count as one strong: §3 runs past 12 steps; §4 spreads over unrelated artifact families or more than one run directory. A lone weak signal is one sentence in the report, never a question — interrupting a right-sized leaf costs more than missing an oversized one. Where the check fires, follow references/sizing_check.md: the preview shown before the question, the question itself and what each answer costs, and where the verdict is recorded. A leaf whose exec_runs is non-empty, or with a run in flight on a branch or worktree, skips this check outright: splitting mid-run leaves that run's wkdrs/<run>/ hanging off a node no executor revisits — what star-plan-decomposer stops to warn about.

Step 2: Orient

Follow references/orient_checklist.md:

1. Read .env and resolve CODE_NAME, CONDA_HOME, PYTHON_HOME (conventions §3). If the environment those paths name is missing or cannot run python, recommend building it with star-env-builder before executing.
2. Map ${CODE_NAME}/ and declare empty codebase when it contains no implementation — or start from a reference codebase first with star-code-architect.
3. Trace each §3 step to real files and classify it as exists / modify / create.
4. Identify the actual run and test entrypoints.

Step 3: Build and write out EXEC_PLAN

1. Refine §3 plus the gap list into ordered actions. Each action must bind {files / command through project env / artifact / check}; the final action binds the §5 done-criterion. Shape the list toward the step-groups Step 4 dispatches when it delegates (references/agent_dispatch_spec.md): adjacent actions that touch the same files and end in one shared check are written as one group of at most 3, not left as separate dispatches — every dispatch a group saves is a fresh sub-agent context that never has to be opened, and the check granularity survives, since a group still ends in its one check and splits at any STOP-line boundary.
2. Mark the STOP line explicitly and estimate runtime/cost when known. The finished plan is the second reading of the leaf's size: if it runs past 12 actions or crosses the STOP line more than once and Step 1's sizing check did not fire, carry that to item 5 as one material choice — go back and split it before implementation begins, or execute the leaf as written — rather than as a question of its own.
3. Collect material divergences from the sub-plan's §2–§5 into EXEC_PLAN's "Divergences from sub-plan" table, in delta form (ADDED / MODIFIED / REMOVED / ENRICHED — references/plan_sync_rules.md). A contradiction at the sub-plan's own granularity is a divergence; extra concreteness is not — except a value the plan left unstated that a method document will cite, an ENRICHED row naming that section. Read references/plan_sync_rules.md where the table comes out non-empty: it is the write-back procedure item 6 and Step 5 run, and an empty table runs neither.
4. Settle the branch and worktree lines (conventions §11): if any EXEC_PLAN action modifies a pre-existing tracked file under ${CODE_NAME}/, the plan carries branch: <run> and recommends executing on it; a plan that only adds new files, or writes only tasks/<plan-name>/ and wkdrs/<run>/, carries branch: none. Record the branch the checkout is on as base:, whatever its name. The worktree line answers whether this checkout is free right now (§11.7): any busy signal (HEAD on another run's execution branch; uncommitted changes on paths another run's records claim; handed-back commands whose results are not collected — a possible live job; or the user naming parallel work) → worktree: ../<root-dirname>--wt/<run>, which forces branch: <run> even where the gap list said none (§11.8); no signal → worktree: none. Follow an applicable user choice already given. If neither is settled, low takes and logs the recommendations; medium asks them together with the plan, and high asks each unresolved judgment separately. Read references/branch_rules.md when either line is not none; it defines creation, commits, resume, merge authority, conflict handling, and artifact-preserving cleanup.
5. Show a concise plan and the changes it will make in commentary. There is no general approval gate before ordinary in-scope implementation or light validation. Per-action commits are recommended: reuse an existing choice; otherwise low takes and logs it, while medium/high ask according to conventions §7.7. Never stage pre-existing changes. Resolve divergence rows through references/plan_sync_rules.md: reuse specific applicable authorization; let auto=unattended cover only rows whose substance leaves research scope, key inputs, §5 acceptance, and approved cost unchanged; ask once for still-undecided material rows. An already-authorized STOP-line launch is not asked again, but it still waits for the command, cost, and current review required by references/stop_line_rules.md.
6. Create the recorded branch or tree first, by references/branch_rules.md's "Creation", and everything below is born on it. Then create tasks/<plan-name>/ for this plan's intermediate working files. Run name = <prefix>_<slug>; append a user-supplied suffix (_v2, a date) to distinguish re-runs, and where that directory already exists but is not a resumable run for this leaf, ask for the suffix — never invent one. Create wkdrs/<run>/EXEC_PLAN.md from the matching language template and initialize EXEC_LOG.md there. Update the sub-plan frontmatter to exec_status: in_progress and append this run to exec_runs rather than replacing the last entry — that history lets star-expt-analyst aggregate see every run of this leaf. A plan still carrying a single exec_run: is migrated to exec_runs: [<that run>] first. Sync authorized divergence rows into the sub-plan now: update the affected §2–§5 passages in place, append a ## Revision History entry, bump updated from the system clock, and mark each row synced.

Before implementation, run the design check. Send references/design_check.md out for a blind read: a read-only sub-agent on the PLAN tier's model (conventions §10.8, where the harness can name one: a second reading of finished work is research judgment), briefed with exactly three files — the EXEC_PLAN just written, the leaf sub-plan, and the root plan read at its §4 alone, the only root section the checklist admits as evidence (name the checklist's _zh twin when the plan's frontmatter says language: zh; the delegate never picks) — and the scope "ONLY these three files, and of the root plan only its §4. Do not rank, do not decide, do not run anything." It returns, per item: item, verdict: pass | fail | unclear, evidence, fix. Re-open the cited evidence for every fail. Correct execution-plan defects within the authorized plan; ask only when a confirmed finding leaves research scope, acceptance, key input, or cost unresolved. Where no delegate is available, run the checklist locally once and record that no independent reader was available; do not repeatedly ask for a tool the host lacks.

Hand Step 4 to the EXEC tier. With EXEC_PLAN, EXEC_LOG, and all currently required decisions recorded, dispatch one writing sub-agent when the configured EXEC override is usable — either its model differs from this run's, or the harness can apply its depth per dispatch — and this run is not already a tier=exec delegate. Pass the EXEC model and supported depth under conventions §10.8, brief it to read this manifest and resume from Step 4 with involve=<level> tier=exec and any valid auto=unattended grant. It may not edit EXEC_PLAN or improvise around a plan-level gap. A STOP-line command or an unresolved decision about blocked edits is recorded and returned to the user-facing run; an existing applicable decision is reused. Re-read EXEC_LOG when it returns and continue at Step 5. With no usable override or delegation route, run Step 4 here without asking repeatedly for unavailable machinery.

Step 4: Execute and verify

The main agent schedules the unfinished actions freely by their dependencies — delegating independent actions concurrently or one by one as it judges best (references/agent_dispatch_spec.md). A tier=exec delegate runs this step and no other: it picks up at the first unfinished action and returns when the step ends, leaving Step 5 to the run that dispatched it. For each action:

1. Choose local execution or selective delegation. When delegating, dispatch a writing sub-agent on the EXEC tier's model (read-only ones only for orientation, on the READ tier's), use references/agent_dispatch_spec.md, and keep file ownership non-overlapping.
2. Make only the action's necessary changes and run its own narrow check through the project environment.
3. Review the diff and verify the action's check as references/agent_dispatch_spec.md defines. Accept inspectable original evidence when it includes the exact command, exit/result, raw log or artifact, and corresponding code version. Re-run the narrow check when that provenance is missing or stale and whenever integration changes relevant behavior, dependencies, or checked code. On pass, record the evidence and artifact path, then make the per-action commit when the recorded choice enables it; on an execution branch it also stages only the run-record updates this action caused (conventions §11.2). On fail, preserve the raw evidence and restore only the action-owned delta from its action-start snapshot before retrying; never erase pre-existing/user work. Retry at most twice when a concrete correction exists, otherwise mark blocked, reuse an applicable decision about its edits or ask for the still-missing destructive authority, and stop.
4. If the action crosses the STOP line, prepare the exact command (and optionally execs/scpts/<run>.sh), record it under Awaiting user with expected cost (GPUs × hours, or call count and spend), outputs, and code version. Follow references/stop_line_rules.md: a specifically authorized ordinary launch or valid star-auto launch proceeds only after its review and cost guards; otherwise hand it to the user. A tier=exec delegate returns at this boundary and never launches it itself.
5. If a retry or blocker changes the approach at the sub-plan's granularity (a step added/dropped/replaced, a deliverable path or done-criterion shifted), record a delta row under EXEC_LOG's Pending amendments. Continue independent authorized work, but do not rely on a changed research scope, key input, or done-criterion until its specific authorization is settled at Step 5.

Step 5: Finalize

1. For non-empty Pending amendments, apply references/plan_sync_rules.md: reuse recorded specific decisions, present only still-undecided rows once, and write back authorized rows with their Revision History provenance and system-clock updated date. auto=unattended covers only recommended tactical rows whose substance leaves research scope, key inputs, §5 acceptance, and approved cost unchanged; a section number or ENRICHED label does not broaden that grant. Parent-plan or kill-criterion changes route through the plan-level finding in point 5.
2. Check references/exec_rubric.md and fix in-scope failures before reporting; list at most five remaining failures with concrete remedies.
3. Verify the sub-plan's §5 done-criterion and record its exact command, raw result/artifact, and corresponding code version in EXEC_LOG.md. Use valid existing evidence when those are inspectable; do not repeat every test or costly command merely for main-agent ownership. Re-run only when provenance is missing/stale or relevant integration changed. Any later change to code, key inputs or acceptance invalidates affected evidence: reopen the affected status, run the required narrow checks, and establish the current criterion before setting done again.
4. If met, set the run and sub-plan exec_status: done. Retain tasks/<plan-name>/ scratch and the plan's own tool scripts by default, with their locations in the report. Delete only files the user specifically requests after promoting durable artifacts and evidence to wkdrs/<run>/; auto=unattended supplies no scratch-deletion grant. If unmet, follow the local fallback in §6 or report the verified gap.
5. If a result hits a root kill-criterion or invalidates the cheap MVP assumption, record a Plan-level finding in the log and recommend star-plan-reviser <slug> (audit the evidence and revise the plan), star-plan-coach <slug>, or star-plan-decomposer <slug>. Do not edit the parent's strategy sections.

Step 6: Report

Lead with the outcome. State what was verified and its evidence, where the retained tasks/<plan-name>/ workspace and wkdrs/<run>/ records/artifacts live, which commands await launch authority or results, which amendments were synced, and any remaining risk. Name the independent review Step 7 starts before any awaiting heavy command. Confirmed blocker/major findings, and any fixes the review was authorized to apply, return through star-plan-executor <leaf>; it reopens or verifies affected actions using fresh checks or attributable original evidence before a launch is retried. On an execution branch, the clean review leads to the merge authorization point in references/branch_rules.md; reuse a specific merge authorization, otherwise ask. Name the branch's unmerged state and any worktree path. Once heavy outputs exist, star-expt-analyst <leaf> scores them against §5 and explains them. Keep the report under about 500 words.

Step 7: Review and return to the execution goal

The active executor retains responsibility for the user's execution goal. Before a heavy launch or merge, run star-code-reviewer for this leaf unless a recorded review already covers the current code version and scope and satisfies the existing launch guard when a launch is pending. Pass the existing execution goal and its authority, and ask the reviewer to return its evidence and control to this executor. A standalone review-only request has no such continuation.