subagent-execution

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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
4. If inline: execute the step directly in the controller session
5. 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
2. When findings return, invoke `receiving-code-review` in the controller
   - Follow Verify → Evaluate → Respond → Implement
3. 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

From yimwoo/hotl-plugin, MIT.

More from yimwoo/hotl-plugin