subagent-execution

HOTL Subagent Execution

Overview

This is a delegation profile over the HOTL execution state machine defined in skills/loop-execution/SKILL.md. It follows the same resolve → preflight → lint → execute → verify → loop → gate → summarize flow, but eligible steps are delegated to fresh subagents instead of running inline.

When selected by governed-execution, the controller uses the chosen driver for all durable transitions and remains responsible for ownership, action gates and effect outcomes, budgets, verification, receipts, and recovery. Native or background-agent success is never sufficient by itself.

Core principle: delegation is allowed; governance is not delegated.

When to Use

• The workflow file already exists (canonical docs/plans/YYYY-MM-DD-<slug>-workflow.md preferred; legacy root hotl-workflow-<slug>.md still accepted during migration)
• Steps are independent enough to hand to one worker at a time
• You want the controller to stay in this session and keep ownership of gates and verification

Execution

Follow the HOTL Execution State Machine in skills/loop-execution/SKILL.md for the full execution flow (workflow resolution, interrupted run detection, branch/worktree preflight, structural lint, execution state persistence, typed verification, loop rules, gate rules, completion).

The controller owns all hotl-rt runtime calls. It initializes with --require-owner, runs owner claim, retains the one-time token only in HOTL_OWNER_TOKEN, and runs owner heartbeat before dispatch, after a worker returns, and at safe transition boundaries. It calls hotl-rt step N start/verify/retry/block, hotl-rt gate N, sensitive-action lifecycle commands, budget checks, hotl-rt finalize, and hotl-rt finish from the resolved execution_root, pinning every call to the captured run_id (--run-id <run-id> or HOTL_RUN_ID=<run-id>). Subagents never receive the owner token and never call the runtime directly. The runtime-managed .hotl/state/<run-id>.json and .hotl/reports/<run-id>.md are the source of truth; delegated workers do implementation only.

Host background subagents, goals, handoffs, hooks, and agent dashboards provide scheduling and liveness only. The controller must persist every transition. Stable host features may be used when available; preview or experimental agent views/teams remain opt-in.

Sensitive effects stay controller-owned: run action request with a stable idempotency key and human action decide; persist action begin before the external operation and action complete with evidence afterward. If a worker or controller is interrupted around the effect, inspect the target and run action reconcile; never ask another worker to replay an in_progress or uncertain effect.

The only difference is how each step body runs:

1. Announce the step
2. Decide whether to delegate or run inline (see Delegation Rules below)
3. If delegated:

• Run owner heartbeat immediately before dispatch and after the worker returns; if the lease cannot remain renewable, stop at a durable boundary instead of leaving an unowned mutation path
• Dispatch a fresh subagent with the full step text, the relevant files, and the success condition
• Do not make the subagent infer the plan from scratch — provide the step directly
• Require the delegated worker to return one of the statuses defined below
• Answer clarifying questions before letting the subagent continue

1. If inline: execute the step directly in the controller session
2. Run verification, loop rules, and gate rules as defined in the state machine

Delegated Worker Prompt Requirements

Every delegated implementation prompt must include:

• Full workflow step text, including action, loop, verify, gate, and any relevant frontmatter context
• Exact files or directories the worker may inspect or edit
• The success condition in plain language
• A reminder that the worker is not alone in the codebase and must not revert unrelated changes
• A reminder that the worker must not call hotl-rt, mark workflow checkboxes, run gates, or finalize the run
• A reminder that the worker must never receive, request, log, or infer HOTL_OWNER_TOKEN
• The required report format:

Status: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED
Summary:
Files changed:
Tests or checks run:
Concerns or blockers:

Handling Worker Status

Treat the worker's status as an input to controller judgment, not as proof of completion.

DONE: Continue with controller-owned verification for the step.

DONE_WITH_CONCERNS: Read the concerns before verification. If they raise correctness, scope, safety, or architecture risk, address them before marking the step verified. If they are non-blocking observations, record them in the runtime report and continue to verification.

NEEDS_CONTEXT: Provide the missing context and re-dispatch the same step. Do not count this as a failed loop iteration unless the worker had enough context and still could not proceed.

BLOCKED: Stop the step and assess the blocker. Options are: provide more context, split the step, run the step inline in the controller, or mark the step blocked through hotl-rt step ... block. Do not retry the same prompt unchanged.

Never mark a delegated step complete from the worker report alone. The controller must inspect the changed files as needed, run the configured verification, apply loop rules, and record the result with the pinned run_id.

Critical Invariants

These rules apply regardless of delegation decisions:

1. Verification always runs in the controller session — never in the subagent
2. Gates always stay in the controller session — gate: human pauses the controller, not the subagent
3. No nested delegation — subagents cannot spawn other subagents
4. No parallel write-heavy steps — do not run multiple implementation subagents in parallel against the same workflow
5. Controller owns stop conditions — on repeated verify failure, the controller stops and reports; it does not let the subagent retry silently
6. Controller owns sensitive effects — workers may prepare local inputs, but the controller performs the action begin / effect / action complete sequence and uses action reconcile after uncertainty
7. Completion requires disposition — successful hotl-rt finalize produces ready_to_finish; only explicit finish produces completed and a sufficient receipt

Delegation Rules

Delegate by default:

• Test-writing steps
• Implementation steps
• Localized documentation changes
• Contained refactors

Keep controller-owned by default:

• Human-gated steps
• Security-sensitive decisions
• Final verification and summaries
• Any step whose failure would require architectural judgment

Review Checkpoints

Record git rev-parse HEAD as the review base before delegating each reviewable batch.

After Meaningful Delegated Batches

After a meaningful batch of delegated implementation completes and verification passes:

1. Invoke requesting-code-review from the controller (not from a subagent)

• Review type: checkpoint
• Review base: the recorded pre-batch HEAD
• Steps reviewed: all steps completed in this batch

1. When findings return, invoke receiving-code-review in the controller

• Follow Verify → Evaluate → Respond → Implement

1. Resolve all BLOCK findings before delegating the next batch

Review is not required after every single delegated step. The controller decides when a batch is "meaningful" based on:

• 3+ completed implementation steps
• Cross-module changes
• High-risk, user-facing, or shared-infra changes

Before Final Completion

A final review is required unless the most recent review already covers all current changes and no code changed afterward.

1. Invoke requesting-code-review with review type: final

• Review base: branch point or last review base, whichever is more recent

1. When findings return, invoke receiving-code-review
2. Resolve all BLOCK findings before finalizing
3. If fixes after the last review changed scope, constraints, or risk_level, request a scoped follow-up review before completing

Review happens after step verification, before verification-before-completion, before hotl-rt finalize.

After finalize returns ready_to_finish, use hotl:finishing-a-development-branch with the same run id and owner token. After explicit finish, release ownership and require a sufficient receipt before claiming completion.

Reporting

Execution report output must conform to docs/contracts/execution-report-output.md. This is the canonical reporting contract from skills/loop-execution/SKILL.md. Live step visibility follows the same rules as skills/loop-execution/SKILL.md — per-step chat logs on all platforms, deterministic renderer for final summary.

Related Skills

• hotl:loop-execution — the canonical execution state machine (this skill builds on it)
• hotl:verification-before-completion — required before claiming done
• hotl:dispatch-agents — use for generic parallel independent tasks, not governed workflow execution