Delegation Harness

Delegation Harness

Use Freeflow delegation to preserve context locality, not to create agent spectacle.

Core rule:

Store broadly. Return compactly. Promote selectively. Load narrowly.

Parent and child name context topology and coordination ownership, not competence or seniority. Workers remain responsible engineers: they implement, self-verify, self-review, correct local mistakes, and learn without continuous supervision. Reading review/verify skills may enhance those inline methods without creating independence. The user is the accountable owner and collaborator, not factual authority.

Subagent Routing Contract

Treat “subagent” as any separate agent context: Freeflow pane, host-native child, reviewer, researcher, worker, verifier, integrator, planning-parent, execution-parent, or future role-specific agent.

When a task warrants separate context, route in this order:

1. Use the Freeflow delegation harness when delegate_* tools are available, healthy, and appropriate for the task.
2. Otherwise use the host's native subagent mechanism when available.
3. Otherwise work inline and report that delegation was unavailable or not worth the overhead.

This applies when other skills ask for a fresh reviewer, researcher, verifier, worker, subagent, or independent context. Standing artifact review, approved plan-selected phase-exit reviews, final work review, and one distinct final verifier need no dispatch reconfirmation. Any other reviewer or independent verifier requires Workflow's scoped user authorization. Do not choose a host-native subagent before checking the harness route.

If the harness route is unavailable or inappropriate, name that and the fallback before presenting the work as independently reviewed or delegated.

Do not manually run cmux for normal child management. Manual cmux is only for bootstrapping a parent pane, recovering/debugging the harness itself, or notification/cleanup when the delegation tool surface is unavailable.

Tiny clear work stays inline during implementation. Do not create delegation state, specs, plans, or panes unnecessarily; when Workflow requires final independent assurance, still use distinct reviewer and verifier contexts or report that independence is unavailable.

Decide execution delegation from the whole work package, not the next slice. For broad or multi-slice implementation, the execution-parent coordinates and assigns a worker stream; it does not become the main implementer just because the current slice is small. Reuse a worker across sequential slices when context remains useful. Spawn a new worker only for a real context boundary, parallelism, write-scope/capability change, stale context, or isolation need.

Execution-parent inline edits are limited to coordination, reporting, or mechanical integration. If an execution-parent edits product/runtime files, it must state why that edit is not worker-owned.

Model

• Orchestrator: root continuity, user-facing routing, final closeout, final commit/push decision.
• Planning-parent: user-guided planning, research synthesis, spec/plan writing, and the standing artifact review.
• Execution-parent: plan-guided execution coordination, worker assignment, integration, formal-finding adjudication, and final reviewer/verifier sequencing.
• Children: bounded researcher, worker, reviewer, verifier, or integrator panes.

The user normally talks to the orchestrator or active parent. The user owns intent and consequential decisions; agents may correct factual or technical claims with evidence. Leaf children communicate through structured results, blockers, status, and evidence pointers.

Harness state and alerts need a failure contract before happy-path implementation: who may set each state, whether it is terminal, what evidence is required, whether it wakes the parent, what must not happen, and the recovery path.

Hard Stops

Do not spawn before delegation preflight passes. If cmux is missing, unusable, or not the active visible workspace, fail closed and route to inline work, install/start cmux, or disable delegation. Do not fall back to hidden/headless child execution.

Do not dynamically grant tools to a running child pane. If a child lacks capability, route to the parent: handle it there, spawn a different pane, ask the user, or deny/defer.

Do not treat raw child transcripts as handoffs, completion signals, or normal TUI output. Child results, role-native reports, stored status, parent alerts, and parent reports are the handoffs; transcripts and screen captures are recoverable evidence.

Do not use parent polling loops as the normal completion/attention path. Children should emit sparse terminal or attention alerts backed by stored state. delegate_wait is explicit watch mode only; use a timeout and retry cap.

Do not send long multiline task packets into an active Pi TUI. Use delegate_spawn launch-time packets or delegate_send file-backed follow-ups/fixes. Short TUI prompts are only for simple follow-ups.

Do not close completed --no-session child panes until the parent or user agrees the context is no longer needed.

Do not let delegation bypass workflow gates. Source-truth conflicts and user-owned decisions route to Decision Gate; unsettled options, public contracts, sensitive behavior, and irreversible architecture route to Discover, design, spec, or plan as appropriate.

Do not parallelize implementation unless independence is explicit and writers are isolated. One writer per checkout.

Tool Map

• delegate_status: inspect preflight, task/agent state, unread parent alerts, and compact execution-map metadata.
• delegate_task_init: create repo-local task state under gitignored .freeflow/delegation/.
• delegate_spawn: preflight, write the task packet, open a visible cmux pane, and start a delegated Pi child.
• delegate_send: send a bounded note or file-backed follow-up/fix packet to an existing child.
• delegate_wait: bounded watch for terminal/attention state; not a polling loop.
• delegate_result: read compact parsed results/reports and evidence pointers; no raw transcript injection.
• delegate_capture: save a bounded screen snapshot as evidence without dumping raw screen text.
• delegate_cancel: interrupt a valid child while preserving evidence.
• delegate_close: close a valid child surface after result/capture is consumed.
• delegate_record_report: store planning/execution reports and malformed-report evidence.
• delegate_finish: store a terminal child result or parent report and alert the direct parent when the tool is active.
• delegate_attention: store blocker/attention state and alert the direct parent.
• delegate_progress: store progress without waking the parent by default.
• delegate_inbox: read current-task/direct-parent alert state.
• delegate_ack_alert / delegate_ack_all: mark alert(s) read within scoped inbox rules.
• delegate_user_attention: request harness-owned user attention through configured channels.
• delegate_update_execution_map: update canonical execution-map package state through validation.

Normal Tool Flow

1. Decide delegation is warranted; otherwise stay inline.
2. delegate_status with preflight when availability matters.
3. delegate_task_init for the task.
4. delegate_spawn with role/profile, cwd, objective, source pointers, in/out-of-scope, allowed commands, write scope, evidence pointers, and stop conditions.
5. Let child terminal or attention alerts wake the parent. Use delegate_wait only for explicit bounded watch.
6. Use delegate_result, role-native report tools, or delegate_status to consume compact state from the tool output first; read canonical JSON only when the compact envelope is malformed, ambiguous, or insufficient for exact evidence recovery.
7. Use delegate_send for bounded fixes/follow-ups when needed.
8. Use delegate_capture only for bounded evidence snapshots.
9. Use delegate_close only after the parent/user has consumed needed evidence.
10. Promote durable decisions to tracked docs only when workflow requires it; do not commit .freeflow/delegation/ runtime state.

Result Protocol

Use the right representation for the interface.

• Child task prompts are readable Markdown by default.
• Tool outputs, alerts, and compact parent-facing envelopes use pipe-style rows that are sufficient for normal parent decisions without reading JSON.
• delegate_finish, delegate_attention, and role-native result tools are preferred when active.
• Legacy FFRESULT, PLANNING_REPORT, and EXECUTION_REPORT rows are fallback chat protocol; they must use normal ASCII | separators and include their closing marker, such as END_FFRESULT.
• Do not tell a child to use delegate_finish unless that tool is actually active for the child.
• Include output-router evidence pointers (outputId, path, or lines) instead of raw command output.

When To Delegate

Delegate when work has real context boundaries:

• planning research can run independently;
• Workflow requires the standing final verifier or a scoped user authorization selects another independent verifier/reviewer;
• execution packages can be isolated by dependencies/write sets;
• context-window pressure would force noisy compaction;
• a phase parent can synthesize child outputs into a compact report.

Keep small, reversible, single-file work inline. Do not use slice-local smallness to inline a broad execution plan.

Phase Flow

1. Orchestrator and user settle the goal and rough scope.
2. Planning-parent owns deep planning, writes the consequential spec/plan package, and runs its standing independent artifact review before implementation.
3. Planning-parent reports settled decisions, artifacts, open questions, risks, and execution guidance to orchestrator.
4. Orchestrator starts execution after required user approval.
5. Execution-parent builds a live execution map, assigns worker streams, preserves workers' implementation feedback loops, directly verifies and integrates results, and runs additional review only at authorized boundaries.
6. After the sequential final self-check, freeze the implementation and dispatch a fresh verifier plus a different fresh reviewer in parallel.
7. Each works independently against the same state; collect both results before parent adjudication.
8. Orchestrator closes only with verifier Pass and resolved review without code changes, then owns the assurance summary, commit/push decision, handoff, and completion claim.

Execution autonomy is desired, not guaranteed. If execution reveals new path-changing evidence, route backward.

Read When Needed

Read context locality when explaining why delegation exists, deciding whether to delegate, or handling context-window/compaction pressure.

Read roles and contracts when deciding which pane owns a phase, who talks to the user, or what a parent/child report should contain.

Read task packets and results when spawning a child, shaping a task packet, handling blockers/capability gaps, or consuming child results.

Read execution and integration when using workers, reviewers, verifiers, integrators, worktrees, execution maps, review loops, or commit checkpoints.

Read reviewer profiles when selecting requirements, code-quality, verification, security, performance, accessibility, or release/operations perspectives. Profiles define focus, not agent/model choice or authority.

Before spawning the standing final verifier or another authorized verifier, load ../verify-work/SKILL.md and follow its independent-verifier contract.

Read tool policy when a child asks for tools, commands, writes, or capability escalation.