agentleFS
dynos-fitdynos-fit/dynos-work/skills/execute/SKILL.md

execute

Skill2 starsChanged 8 months agoMITView on GitHub

Execute the approved plan. Orchestrates execution graph segments through specialized executor agents, including dependency management and error recovery. Runs only when the user explicitly types /dynos-work:execute; never auto-triggered from conversation.

57 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use context-optimize, ralplan and 9 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • ibahgatSkill

    context-optimize

    Improve context efficiency and cache stability for long or complex sessions.

    Also in 3 projects that use this

  • ibahgatSkill

    ralplan

    Create a strict, quality-first execution plan with explicit gates and rollback-ready sequencing.

    Also in 5 projects that use this

  • Yeachan-HeoSkill

    ultragoal

    Create and execute durable repo-native multi-goal plans over Codex goal mode artifacts.

    Also in 4 projects that use this

  • buddyhSkill

    deep-dive

    Deep dive on any topic. Decomposes into subtopics, researches each in parallel with thorough source gathering, then synthesizes into a comprehensive report (4,000-10,000+ words, 40-100+ sources). Scales depth dynamically based on topic complexity. Use when asked for a deep dive, deep research, comprehensive analysis, or thorough investigation of a topic.

    Also in 4 projects that use this

  • mukcoSkill

    principles

    General software engineering principles — DRY, SOLID, YAGNI, KISS, naming, code smells, and refactoring. Language-agnostic. Use alongside language-specific skills.

    Also in 3 projects that use this

  • team-attentionSkill

    compound

    This skill should be used when the user says "/compound", "compound this", "document learnings", "save what we learned", or after completing a PR. Extracts knowledge from PR context and saves to docs/learnings/.

    Also in 3 projects that use this

  • +1 more from ibahgat

The file

Show its rules and text

We split this skill into the rules it gives an agent

42 rules. 0 are common, 18 are distinctive, and 24 are very specific to this project.

  • 0

    Common

    Most of the 55 edited versions we read keep these.

  • 18

    Distinctive

    This author's own choices. Worth a look.

  • 24

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Every deterministic step below runs through the plugin CLI.

    line 12
  2. Distinctive:

    No executor prompt may omit learned rules or prevention rules when they exist.

    line 35
  3. Distinctive:

    If verification is weak, the segment is weak.

    line 37
  4. Distinctive:

    If a segment can pass with shallow evidence, the prompt is too soft.

    line 38
  5. Distinctive:

    No executor gets to hide behind “close enough.”

    line 39
  6. Distinctive:

    If validation fails with missing required inputs, print the errors and stop.

    line 51
  7. Very specific:

    Read spec.md, plan.md, and execution-graph.json.

    line 55
  8. Distinctive:

    Before any modification starts:

    line 61
  9. Distinctive:

    Create a snapshot branch at the current commit without leaving the working branch:

    line 62
  10. Very specific:

    Read the printed JSON for head_sha and branch.

    line 76
  11. Very specific:

    When a segment in the execution graph is marked with two_phase: true (indicating its weighted budget hit the ceiling per AC 6), the segment …

    line 83
  12. Distinctive:

    Run deterministic execute setup first:

    line 93
  13. Distinctive:

    If any segment has route_mode in {replace, alongside} with non-null agent_path, the inline branch is FORBIDDEN — take the spawn path.

    line 112
  14. Very specific:

    Run the executor plan router: "$DYNOS" hook router executor-plan --root .

    line 116
  15. Distinctive:

    Write the executor-routing receipt (required for stage transitions).

    line 117
  16. Very specific:

    Run inject-prompt with your base prompt to get the complete prompt with prevention rules.

    line 119
  17. Distinctive:

    Do NOT re-derive dependency depth, cache reuse, or runnable batches in prompt logic.

    line 149
  18. Very specific:

    If cached_segments is non-empty, treat those segments as already satisfied and reuse their evidence files.

    line 153
  19. Very specific:

    If next_batch is empty while pending_segments is non-empty, stop and fail the task as blocked.

    line 155
  20. Very specific:

    Deterministic routing (MANDATORY): Use the segments payload returned by run-execute-setup as the authoritative executor plan.

    line 159
  21. Distinctive:

    Do NOT read project_rules.md tables manually.

    line 161
  22. Very specific:

    If route_mode is replace or alongside, reads the learned agent .md file and appends its rules to the prompt

    line 172
  23. Very specific:

    If status is stale, re-run executor-plan before continuing inject-prompt calls — otherwise per-segment routing will silently fall back to …

    line 183
  24. Distinctive:

    If the injected prompt is weak, strengthen the base prompt before spawning.

    line 197
  25. Very specific:

    If inject-prompt fails or is unavailable, stop and fix the deterministic routing path.

    line 199
  26. Very specific:

    TDD-First Awareness: Check if .dynos/task-{id}/evidence/tdd-tests.md exists.

    line 205
  27. Distinctive:

    Before issuing each parallel next_batch executor batch (this includes the first batch AND every subsequent next_batch — the check runs once …

    line 209
  28. Very specific:

    Write escalation.md in the task directory containing the full JSON output and a human-readable explanation that the spawn budget was …

    line 217
  29. Distinctive:

    Do not proceed with spawning executors.

    line 221
  30. Very specific:

    Pre-loaded file contents (MANDATORY): Run the context builder for each file in the segment's files_expected and append its output to the …

    line 233
  31. Very specific:

    Do NOT pass the full spec.md or plan.md to executors.

    line 241
  32. Distinctive:

    Segment finalization (MANDATORY): After each executor completes, finalize the segment through ctl instead of hand-writing receipt / …

    line 243
  33. Very specific:

    Use run-execution-segment-done as the authoritative completion gate.

    line 273
  34. Very specific:

    Only once next-continuation reports complete do you advance the stage.

    line 299
  35. Very specific:

    If any segment in execution-graph.json declares verify_commands, capture their machine evidence now.

    line 301
  36. Very specific:

    Run the prevention-rules check.

    line 311
  37. Very specific:

    Read plan.md Test Strategy.

    line 345
  38. Very specific:

    If an approved TDD suite exists, run those tests first as the blocking contract suite.

    line 347
  39. Very specific:

    Run the final, authoritative test pass through ctl.

    line 349
  40. Very specific:

    Do NOT move a test failure to REPAIR_PLANNING.

    line 360
  41. Distinctive:

    Dependency discipline: Never spawn an executor before its dependency evidence files are available.

    line 375
  42. Very specific:

    Caching Discipline: Never skip a segment if its files_expected have any uncommitted changes not reflected in the existing evidence.

    line 376

“Common” is measured: kept by at least 6 in 10 of the 55 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

dynos-work: Execute Skill

Manages the parallel execution of the implementation plan via the execution graph. Handles dependency ordering, executor spawning, and final integration.

Command Funnel (applies to every command in this skill)

Every deterministic step below runs through the plugin CLI. Resolve it once at the start of the skill and substitute the ABSOLUTE path literally into each command you run (permission prefix-matching operates on literal command text):

PLUGIN_ROOT="${CODEX_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-}}"
if [ -z "$PLUGIN_ROOT" ]; then
  # Some sessions leave both unset. The plugin root is two levels above this
  # skill's base directory (printed when the skill loads); substitute it here.
  PLUGIN_ROOT="$(cd "{skill_base_dir}/../.." && pwd)"
fi
if [ ! -x "$PLUGIN_ROOT/bin/dynos" ]; then
  echo "Cannot locate the dynos-work plugin root; set CODEX_PLUGIN_ROOT or CLAUDE_PLUGIN_ROOT." >&2
  exit 2
fi
DYNOS="${PLUGIN_ROOT}/bin/dynos"   # resolve once; use the absolute path in every command

"$DYNOS" ctl <subcommand> wraps hooks/ctl.py; "$DYNOS" hook <script> ... wraps helper scripts (router, lib_tokens, build_prompt_context, ...) with PYTHONPATH handled internally. A permissions-ON user can allow the single <plugin-root>/bin/dynos prefix once instead of approving every call.

JSON payloads (classification, execution-graph, repair-log) are piped to the ctl wrapper over stdin with --from - and a heredoc — NEVER staged at /tmp or any raw filesystem path (the write policy denies those, by design). Temp files, when genuinely needed, belong in .dynos/task-{id}/_scratch/.

Ruthlessness Standard

  • No silent shortcuts.
  • No executor prompt may omit learned rules or prevention rules when they exist.
  • A segment is not done because code was written; it is done when the required behavior is proven.
  • If verification is weak, the segment is weak.
  • If a segment can pass with shallow evidence, the prompt is too soft.
  • No executor gets to hide behind “close enough.”

What you do

Step 0 — Contract validation

Validate that all required inputs from the start skill are present:

"$DYNOS" ctl validate-contract --skill execute --task-dir .dynos/task-{id}

If validation fails with missing required inputs, print the errors and stop. Do not proceed with execution.

Step 1 — Review the Plan

Read spec.md, plan.md, and execution-graph.json. Ensure you understand the dependency chain.

If plan-audit-gap-warnings.json exists with advisory: true, read its warnings: plan endpoints or models the gap scanner could not find in the code, downgraded to advisory because the approved plan was unchanged since run-planning validated it. Pass each one to the executor of the segment that touches it as a fact to confirm (the route or model exists where the plan says, or the segment creates it); do not edit plan.md over them.

Step 2 — Snapshot the Base

Before any modification starts:

  1. Create a snapshot branch at the current commit without leaving the working branch:
    git branch dynos/task-{id}-snapshot
    (git checkout -b … && git checkout - must not be used: on a repository with no commits it renames the unborn branch and then fails. With no commits there is nothing to snapshot; record-snapshot says so and asks for an initial commit.)
  2. Record the snapshot SHA into manifest.snapshot via the audited ctl wrapper:
    "$DYNOS" ctl record-snapshot .dynos/task-{id}
    The command auto-detects HEAD SHA and branch from git. It accepts optional --head-sha SHA and --branch NAME to override. Stage gate refuses anything at or beyond EXECUTION. Re-run with the same SHA is a no-op (status: already_recorded); a different SHA is refused.

Read the printed JSON for head_sha and branch. Append to log:

{timestamp} [DECISION] snapshot recorded — branch {branch} at {head_sha}

Two-Phase Execution for Oversized Segments

When a segment in the execution graph is marked with two_phase: true (indicating its weighted budget hit the ceiling per AC 6), the segment requires two-phase A/B split execution under write-first discipline:

  1. Spawn A (read-only): Spawn A is a read-only analysis pass that produces a precise change-list artifact at evidence/<seg-id>-change-list.md. This change-list is the authoritative specification for all writes spawn B will perform.
  2. Spawn B (write phase): Spawn B reads the change-list generated by spawn A as its sole work specification. Spawn B applies all changes under write-first discipline: create the evidence file early with the change-list reproduced verbatim, then execute each item in sequence.

The two-phase separation ensures oversized segments remain verifiable and transparent. The literal strings two_phase: true, change-list, and write-first mark this requirement in the execution graph and in spawn instructions.

Step 3 — Execute segments (Optimized Scheduler)

Run deterministic execute setup first:

"$DYNOS" ctl run-execute-setup .dynos/task-{id}

This command runs execution preflight validation, advances PRE_EXECUTION_SNAPSHOT -> EXECUTION, builds the executor plan, and writes the executor-routing receipt. Use its JSON output directly.

Inline vs spawn decision (authoritative):

The inline branch is permitted ONLY when every cell in row 1 of the table below is satisfied. Any deviation forces the spawn path. Read the executor plan router output first, then look up the row that matches manifest.fast_track, the number of segments in execution-graph.json, and the segment's route_mode + agent_path from the router's response.

fast_trackn_segmentsroute_modeagent_pathpath_taken
true1genericnullinline (no subagent spawn)
true1replaceany non-nullspawn (inline FORBIDDEN)
true1alongsideany non-nullspawn (inline FORBIDDEN)
false OR n_segments > 1anyanyanyspawn

If any segment has route_mode in {replace, alongside} with non-null agent_path, the inline branch is FORBIDDEN — take the spawn path.

Inline execution procedure (only when the decision table row says inline): Inline execution skips the executor subagent entirely and runs the segment in this thread. This avoids the ~30K token overhead of agent context setup, but it does NOT relax any other rule. Even in the inline branch, you MUST still run the router, write the executor-routing receipt, and apply the prompt-injection/prevention pipeline to your own work:

  1. Run the executor plan router: "$DYNOS" hook router executor-plan --root . --task-type {task_type} --graph .dynos/task-{id}/execution-graph.json
  2. Write the executor-routing receipt (required for stage transitions).
  3. Re-verify the decision table row. If the router's response contains any segment with route_mode in {"replace", "alongside"} with a non-null agent_path, STOP — the inline branch is FORBIDDEN for this task. Fall through to the spawn path below.
  4. Run inject-prompt with your base prompt to get the complete prompt with prevention rules. Apply those rules to your own work.
  5. Log the routing decision: {timestamp} [ROUTE] {executor} model={model} route={route_mode} source={route_source}
  6. Transition the manifest stage PRE_EXECUTION_SNAPSHOT → EXECUTION (mandatory — without this the Step 4 transition to TEST_EXECUTION is illegal per ALLOWED_STAGE_TRANSITIONS). transition_task auto-appends the [STAGE] → EXECUTION log line; do not write it manually:
"$DYNOS" ctl transition .dynos/task-{id} EXECUTION

Then read the segment, extract the criteria from spec.md, make the code changes yourself and write evidence. Finalize the segment with run-execution-segment-done exactly as in Segment finalization below (its receipt is what marks the segment complete), then run the end of Step 3 (rules check, run-execution-finish, evidence verification) before Step 4: run-tests refuses a task still at EXECUTION. Log it with "$DYNOS" ctl log-append .dynos/task-{id} --tag INLINE --message "seg-1 — fast-track inline execution (no subagent spawn)".

Inline execution does not relax standards. It removes spawn overhead, not rigor.

Skipping the router in inline mode silently ignores learned agents and breaks the self-learning feedback loop.

Normal execution (fast_track is false or >1 segment):

run-execute-setup already performed deterministic preflight validation and stage advancement. If it failed, repair the plan first; do not patch around a broken plan during execution.

Immediately compute the authoritative execution schedule:

"$DYNOS" ctl run-execution-batch-plan .dynos/task-{id}

This command is authoritative for:

  • segment state: completed | cached | pending
  • cache eligibility and cache rejection reasons
  • dependency depth / critical path
  • next runnable batch and remaining batches

Do NOT re-derive dependency depth, cache reuse, or runnable batches in prompt logic. Consume the JSON output and follow it.

If tdd_covered_segments is present, those testing-executor segments were finalized without a spawn: with tdd_required, every one of their files_expected is in the tdd-tests receipt's file list and on disk, so run-execution-batch-plan wrote their executor-{seg-id} receipt (tdd_covered: true, evidence evidence/tdd-tests.md). They appear under completed_segments; do not spawn executors or run run-execution-segment-done for them.

If cached_segments is non-empty, treat those segments as already satisfied and reuse their evidence files. Log each with "$DYNOS" ctl log-append .dynos/task-{id} --tag CACHE --message "{segment-id} — skipping (inputs unchanged)".

If next_batch is empty while pending_segments is non-empty, stop and fail the task as blocked. That means dependency resolution or receipt state is inconsistent; do not guess.

Progressive auditing remains allowed, but only after a segment is deterministically known complete or cached.

Deterministic routing (MANDATORY): Use the segments payload returned by run-execute-setup as the authoritative executor plan. Do not rebuild routing in prompt logic. The executor-routing receipt has already been written.

Do NOT read project_rules.md tables manually. The router handles model policy, agent routing, and security floors deterministically.

Learned Agent Injection (MANDATORY — NOT OPTIONAL): For every segment, you MUST build the executor prompt using the deterministic prompt builder. This is not a suggestion. This is an enforcement gate. For each segment in the executor plan:

echo "{your base prompt for this segment}" | "$DYNOS" hook router inject-prompt --root . --task-type {task_type} --graph .dynos/task-{id}/execution-graph.json --segment-id {seg-id}

This command:

  1. Reads the base prompt from stdin
  2. Looks up the routing decision for this segment (model, route_mode, agent_path)
  3. If route_mode is replace or alongside, reads the learned agent .md file and appends its rules to the prompt
  4. Appends prevention rules from the project's history
  5. Logs a learned_agent_applied event to .dynos/events.jsonl
  6. Prints the complete prompt to stdout

Routing cache (automatic — no extra steps): executor-plan writes its result to .dynos/task-{id}/router-cache/executor-plan.json keyed by a fingerprint over every input that drives the plan (graph, policy, effectiveness scores, retrospectives, learned registry, benchmark history, prevention rules). Each inject-prompt call checks this cache first; on a fingerprint match it reuses the cached entry instead of re-deriving routing. This guarantees the model the executor was spawned under matches the model the prompt was injected for, even with epsilon-greedy exploration enabled. Cache lookups emit a router_cache_lookup event with status: hit | fingerprint_drift | stale_segment. Inspect freshness with:

"$DYNOS" hook router router-cache-status --root . --task-type {task_type} --graph .dynos/task-{id}/execution-graph.json

If status is stale, re-run executor-plan before continuing inject-prompt calls — otherwise per-segment routing will silently fall back to live builds.

Use the OUTPUT of this command as the prompt for the Agent tool spawn. Do NOT construct the executor prompt yourself. Do NOT skip this step. If you spawn an executor without running inject-prompt first, the learned agent is silently ignored and the whole self-learning system is broken.

Per-spawn tool budget (since 2026-05-06): The injected prompt now includes a ## Tool-Use Budget block specifying the per-spawn tool-call budget computed deterministically from the segment's files_expected count and the resolved model (via hooks/lib_tool_budget.py::compute_segment_budget). The block presents that value as an estimate for scoping, not a cutoff — finishing the segment is the priority, and an executor keeps its work resumable through a progress ledger rather than stopping at a checkpoint. The agent frontmatter maxTurns: 60 is the runaway backstop: it sits above the 40-call TOOL_BUDGET_CEILING so an executor that exhausts its estimate still has turns left to write its ledger and exit cleanly instead of being killed mid-edit. Operators should expect scoping to track segment size, not the model tier.

Sidecar capture (MANDATORY). cmd_inject_prompt writes the SHA-256 of the exact bytes it printed to stdout to .dynos/task-{id}/receipts/_injected-prompts/{seg-id}.sha256 (single-line lowercase hex digest, no trailing newline) plus a companion .txt of the same bytes. Both files are written atomically via tempfile + os.replace, so a retry overwrites cleanly. Immediately after inject-prompt returns, read the sidecar:

INJECTED_PROMPT_SHA256=$(cat .dynos/task-{id}/receipts/_injected-prompts/{seg-id}.sha256)

You MUST pass this captured digest to receipt_executor_done(...) below as injected_prompt_sha256. The receipt writer asserts the same sidecar exists and matches; a mismatch raises ValueError with the literal substrings injected_prompt_sha256 sidecar missing or injected_prompt_sha256 mismatch.

If the injected prompt is weak, strengthen the base prompt before spawning. Do not accept vague executor instructions.

If inject-prompt fails or is unavailable, stop and fix the deterministic routing path. Do NOT manually read agent_path or hand-build the learned-agent prompt.

The Agent spawn hook stamps active-segment-role from the agent type.

Model selection: Pass the model field from the executor plan as the model parameter when spawning the agent. If model is null, use default (omit the model parameter).

TDD-First Awareness: Check if .dynos/task-{id}/evidence/tdd-tests.md exists. If it does, include this instruction in the base prompt (before piping through inject-prompt): "A TDD test suite has already been committed. Your implementation must make those tests pass. Do NOT write new tests or modify existing test files."

Spawn budget check (MANDATORY — BEFORE every batch):

Before issuing each parallel next_batch executor batch (this includes the first batch AND every subsequent next_batch — the check runs once per spawn cycle, before EACH batch, not only the first), run:

"$DYNOS" ctl check-spawn-budget .dynos/task-{id}

Parse the JSON output. The command emits a single-line JSON object with keys status, count, threshold, exempt_count, and task_class. If status is 'paused' or 'already_paused':

  1. Write escalation.md in the task directory containing the full JSON output and a human-readable explanation that the spawn budget was exceeded — name the executor count, the threshold, the task_class, and instruct the operator to run "$DYNOS" ctl spawn-resume .dynos/task-{id} --reason "<≥20-char rationale>" after diagnosing why spawns were wasted.
  2. Record the pause: "$DYNOS" ctl log-append .dynos/task-{id} --tag BUDGET-PAUSE --message "count={count} threshold={threshold}" (never append to execution-log.md directly; the stamped segment role is denied that write).
  3. Exit non-zero.

Do not proceed with spawning executors. The pause is intentional — the policy is calibrated from this project's retrospective history, and the wasted-spawn count has crossed the learned threshold.

Spawn the next_batch executor agents in parallel.

Executor agents by type:

  • ui-executor, backend-executor, ml-executor, db-executor, refactor-executor, testing-executor, integration-executor, docs-executor, infra-executor, security-executor, data-executor, observability-executor, release-executor.

The base prompt for each executor (before inject-prompt) must include:

  1. Its specific segment object from execution-graph.json
  2. The full text of each acceptance criterion referenced by the segment's criteria_ids field, extracted from spec.md
  3. Evidence files from dependency segments: for each segment ID in the executor's depends_on list, read .dynos/task-{id}/evidence/{dependency-segment-id}.md and include its contents
  4. Instruction to write evidence to .dynos/task-{id}/evidence/{segment-id}.md
  5. Pre-loaded file contents (MANDATORY): Run the context builder for each file in the segment's files_expected and append its output to the base prompt:
"$DYNOS" hook build_prompt_context --root . {files_expected_1} {files_expected_2} ...

Append the printed output verbatim to the base prompt. This gives the executor the current file contents upfront so it does not need to call Read at the start, keeping the context window small. If a file does not exist yet (new file), the script emits a placeholder — include it anyway so the executor knows the file is new. The output is held to a byte budget (48 KB by default; --max-bytes N or DYNOS_PROMPT_CONTEXT_MAX_BYTES changes it): past the budget, or when one file would take more than half of it, a file is cut to a head excerpt and then listed by path only, and the output's Prompt-context budget: line records what was kept. Do not work around the budget by pasting file contents yourself; the executor reads excerpted and path-only files on demand.

Do NOT pass the full spec.md or plan.md to executors.

Segment finalization (MANDATORY): After each executor completes, finalize the segment through ctl instead of hand-writing receipt / ownership / manifest logic:

"$DYNOS" ctl run-execution-segment-done \
  .dynos/task-{id} \
  "{seg-id}" \
  --injected-prompt-sha256 "{INJECTED_PROMPT_SHA256 captured from sidecar}" \
  --model "{model from plan or null}" \
  --agent-name "{agent_name from plan or None}" \
  --executor-type "{executor from plan}" \
  --evidence-path ".dynos/task-{id}/evidence/{seg-id}.md" \
  --tokens-used {total_tokens from Agent result or None}

This command deterministically:

  • verifies segment ownership against execution-graph.json
  • verifies the evidence file exists
  • writes receipt_executor_done(...)
  • updates manifest.json.execution_progress from deterministic execution state

Role cleanup (MANDATORY — AFTER run-execution-segment-done writes the receipt): Clear unconsumed role grants immediately after the segment receipt is written. This prevents a stale grant from leaking into any subsequent segment's spawn. Do NOT rm the role file by hand — active-segment-role is wrapper-required and the deletion is denied by write_policy; clear-role is the sanctioned (privilege-reducing) path:

"$DYNOS" ctl clear-role .dynos/task-{id}

It is safe to run while other executors of the same batch are still running: it keeps the stamp and grants of every role whose spawn has not returned (roles_kept_in_flight in its output) and drops the rest. Do not pass --all during a parallel batch; that revokes the running executors' roles and their next writes are denied as orchestrator.

Token usage is recorded automatically by the SubagentStop hook; do not record it by hand.

  • Use run-execution-segment-done as the authoritative completion gate.
  • Append to log: {timestamp} [DONE] {segment-id} — complete.
  • Re-run run-execution-batch-plan to get the next authoritative batch.

Test execution (Step 4): Record test runner events with --phase execution --stage TEST_EXECUTION.

Segment continuation loop (finish the work — budget is NOT a stop condition).

An executor can exit before finishing its segment — most often it ran out of turns mid-edit and never wrote evidence/{seg-id}.md, leaving partial edits applied on disk (e.g. app.js now references a module it never imported). Do NOT abandon the segment, and do NOT cold-restart it blind. When run-execution-batch-plan reports no pending segments, run the continuation loop to drive every incomplete segment to completion:

"$DYNOS" ctl next-continuation .dynos/task-{id}

Parse the JSON status:

  • complete — every segment is done. Proceed to run-execution-finish below.
  • continuation_needed — for each entry in incomplete_segments whose stalled is false, spawn ONE continuation executor of the entry's role (pass its model as the model parameter), built exactly like a normal executor spawn (the Step 3 spawn block: the segment object, the criteria text extracted from spec.md by criteria_ids, dependency evidence, and build_prompt_context for files_expected) PLUS this continuation preamble:

    • "This segment was already partially executed; the prior edits are applied on disk. Do NOT redo completed work — finish ONLY what remains."
    • the entry's incomplete_reasons, verbatim, as the remaining checklist.
    • "Write evidence/{seg-id}.md before you run low on turns."

    After each continuation executor returns, run run-execution-segment-done for that segment (the same authoritative completion gate the normal batch loop uses — it writes the receipt and verifies ownership + evidence; a segment is not "complete" until that receipt exists). Then re-run next-continuation and repeat. There is no spawn-count cap in this loop — keep going as long as segments make progress. Do NOT run check-spawn-budget for continuation spawns; the spawn-budget backstop is for audit thrash, not for finishing execution.

  • verification_needed — the only thing missing is verify_commands evidence (verification_segments names the segments; each entry has verification_only: true). No executor can produce that record, so do not spawn one: run run-verification-evidence (below), then re-run next-continuation. Re-reporting a verification-only segment does not raise its stall_count. In a continuation_needed result, skip entries with verification_only: true the same way.
  • stalled (exit code 3) — every remaining incomplete segment moved nothing across two consecutive continuations; stalled_segments names them. This is the ONLY automatic halt. Write escalation.md with stalled_segments and their incomplete_reasons, record it with "$DYNOS" ctl log-append .dynos/task-{id} --tag CONTINUATION-STALLED --message "{stalled_segments}", and stop: the orchestrator cannot make progress and a human must intervene. Do NOT keep re-spawning.

Only once next-continuation reports complete do you advance the stage.

If any segment in execution-graph.json declares verify_commands, capture their machine evidence now. run-execution-finish refuses to advance while a declared command has no passing record, and the spec-completion auditor accepts only these records (or test-results.json) as proof for criteria that require running something:

"$DYNOS" ctl run-verification-evidence .dynos/task-{id}

Each command gets its own timeout from the graph, else --timeout, else the project policy's verification_timeout_s (~/.dynos/projects/{slug}/policy.json), else 3600 s. A run can outlast the Bash tool's foreground limit (about 10 minutes): start it with run_in_background and wait for it to exit instead of letting the tool call time out. run-execution-segment-done also reports verification_pending for a finished segment whose declared commands have no passing record yet; you may run run-verification-evidence --segment {seg-id} then.

A failing command is a defect in the segment that declared it: fix it (re-spawn that segment's executor) and re-run the command above. Do not edit the command; it was locked at plan approval.

Run the prevention-rules check. run-execution-finish refuses to advance without its rules-check-passed receipt:

"$DYNOS" ctl run-rules-check .dynos/task-{id} --mode task
  • status == "rules_check_passed": continue.
  • status == "rules_check_failed" (exit 1; the JSON is on stderr and names the rule and files): fix the violations and re-run. A rule that cannot apply to this task, such as one another task added for a symbol this branch does not have, is waived instead of edited out of the shared rules file: "$DYNOS" ctl waive-rule .dynos/task-{id} <rule_id> --reason "<why it does not apply>", then re-run the check. Removing and later restoring a rule changes the rules hash, and the stage gate refuses that as drift.

Use --mode task. It checks the files this task changed since its record-snapshot commit (plus untracked files) against the rules pinned when the task started, so pre-existing violations in code the task never touched do not block it; repo-wide rules (caller counts, signature locks) fail only when the task's change caused the violation. The receipt records the mode used, and a task with no snapshot is checked in all mode. --mode all scans every tracked file; the staged mode checks only git diff --cached, and execution never stages files, so it would pass without checking anything.

Then advance:

"$DYNOS" ctl run-execution-finish .dynos/task-{id}

This command refuses the transition if any segment is still pending, AND it runs the full evidence verification (non-empty evidence/{seg-id}.md per segment, every files_expected entry on disk) inside the stage gate before advancing to TEST_EXECUTION. It should pass now that the continuation loop reported complete; if it still reports "status": "blocked", re-run next-continuation (state changed under it) and resolve what it surfaces. Do not manually decide that execution is complete.

While the task is at TEST_EXECUTION, confirm the result with the deterministic evidence verifier. It accepts only EXECUTION and TEST_EXECUTION, and Step 4's run-tests advances the task to CHECKPOINT_AUDIT, so run it now, not after the tests:

"$DYNOS" ctl run-execution-verify-evidence .dynos/task-{id}

It checks that every non-cached segment's evidence file exists and is non-empty and that every files_expected entry exists on disk, and exits non-zero with a JSON error payload if any check fails. Do NOT assert completion in prompt logic — consume this command's output as the authoritative pass/fail signal. If it reports "status": "blocked", address each listed failure before proceeding.

Record it:

"$DYNOS" ctl log-append .dynos/task-{id} --tag DONE --message "execute — all segments verified by ctl (segments_verified={N})"

Step 4 — Run tests

Read plan.md Test Strategy. Run the specified tests. Use incremental testing if the framework supports it (e.g. jest --onlyChanged).

If an approved TDD suite exists, run those tests first as the blocking contract suite. If they pass, run any broader regression suite required by plan.md.

Run the final, authoritative test pass through ctl. Pass every suite the Test Strategy requires — including the repo-wide run, not only the per-directory ones — as repeated --command flags:

"$DYNOS" ctl run-tests .dynos/task-{id} --command "{suite 1}" --command "{suite 2}"

ctl runs each command from the repo root, takes the exit codes as the verdict, writes test-results.json, logs the [DONE]/[FAIL] tests line, and advances TEST_EXECUTION → CHECKPOINT_AUDIT whether the tests passed or failed. For a long suite, run it with run_in_background instead of letting the Bash call time out. Use the JSON output:

  • status == "tests_passed": continue to Audit.
  • status == "tests_failed": continue to Audit anyway. The failure is now a known defect: the spec-completion auditor gets the failing output in its prompt and reports it as a blocking finding, which reaches repair through /dynos-work:audit Step 4. The DONE gate refuses while test-results.json is not passed.

Do NOT move a test failure to REPAIR_PLANNING. The repair log can only cite audit-report findings, so before any audit has run nothing can be planned there, and the only way out is FAILED.

Handoff — Write handoff record

After Step 4, run:

"$DYNOS" ctl write-execute-handoff .dynos/task-{id}

This writes .dynos/task-{id}/handoff-execute-audit.json deterministically from the live manifest stage. Do NOT hand-write the handoff JSON in prompt logic.

Hard Rules

  • No speculative implementation: Executors must stay strictly within their segment's files_expected and criteria_ids.
  • Atomic evidence: Evidence files must be written only after the segment's implementation is complete.
  • Dependency discipline: Never spawn an executor before its dependency evidence files are available.
  • Caching Discipline: Never skip a segment if its files_expected have any uncommitted changes not reflected in the existing evidence.
  • Ownership discipline: A segment that edits files outside files_expected is invalid until repaired and re-evidenced.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.