/wakeflow-controller

name: wakeflow-controller
description: Use when Wakeflow total control starts or resumes Wakeflow Delivery Loop in Claude Code, reviews strict TargetResult records, prepares typed delivery transport, coordinates the v3 Claude host adapter, decides acceptance / rework / block / next wave, or stops unattended automation.

Wakeflow Controller

Use this skill only from the controller window. `CLAUDE.md` owns hard judgment; this skill owns the mechanical loop steps.

Purpose

Wakeflow Delivery Loop lets the controller fan out work to target window sessions, receive strict TargetResult records, inspect target-authored review inputs, run independent checks, and decide the next package. It does not replace planning, scope control, validation, or acceptance.

Direct-thread dispatch is the normal transport; on Claude Code a Wakeflow thread id is the window's Claude Code session id, generated at launch and stable across resumes. Every Wakeflow window (the controller included) is a tmux-resident interactive `claude` session inside the workspace tmux server session. In explicitly enabled unattended mode, keep reviewing results, inspecting inputs, validating, deciding, planning next eligible packages, and dispatching until final completion, a hard gate, explicit user stop, missing review inputs that need human judgment, or no eligible TODO remains.

After an explicit v3 host-adapter outcome, record the exact transport and readback fact through `wakeflow_record_delivery operation=target-outcome`. Pending/unavailable pane visibility is `sent-unconfirmed`; it never authorizes another pane read, resend, or lease release. The controller dispatch turn then stops without claiming destination reachability. Do not keep the turn open with `sleep`, repeated result review, repeated session reads, or manual polling. The target returns later through one strict `wakeflow-target-result` TargetResult and, if policy allows, a controller-return delivery sent to the controller's own tmux window. Status, review, and trace must derive from strict state, transport, result, binding, and redacted host-projection facts. Silence is never auto-judged: a long quiet spell may be a legitimate long tool call, so whether a window is stalled remains the CONTROLLER'S judgment after an explicit inspection. Do not arm per-dispatch watchers, poll panes, or use a synchronous wait compatibility route.

Source Practices For Acceptance

**Iron Law: NO ACCEPTANCE UNTIL THE CONTROLLER HAS PERSONALLY ESTABLISHED THE INTENDED BEHAVIOR FROM FRESH RAW INPUTS AND INDEPENDENT CHECKS.** A result envelope, a script's `OK`, or a window's success report is only a review input. Violating the letter of this rule is violating its spirit.

Controller acceptance adapts mature review practice — `code-reviewer` (understand intent first, then correctness, safety, maintainability, performance, tests; start large changes at entrypoints and high-risk files), `senior-qa` (confidence per unit effort; flakiness is evidence degradation, not success), and SRE evidence practice (separate symptom, cause, black-box, and white-box evidence; logs, probes, and scripts are inputs, not conclusions) — under Wakeflow's stricter authority boundary: target window sessions, Test, Design, scripts, Claude Code subagents (the Task/Agent tool), and MCP tools provide review inputs only; only the controller accepts, requests rework, blocks, waits, completes a demand, archives, or creates the next package.

| Claim | Requires | Not sufficient | |---|---|---| | Target task done | the VCS diff inspected and relevant behavior independently checked this turn | the envelope says "done" | | Behavior delivered | the controller reproduced or directly inspected the user-visible behavior | a connection / empty API / static mock exists | | Demand complete | line-by-line vs the requirement design + non-goals | all tasks marked done | | Ready for Test | existing non-Test targets accepted + controllerSelfChecks recorded | hoping Test will establish correctness |

Demand Creation Authority

Default substantial new product behavior to the Design window. Total control may still create a bounded bug, supplement, research demand, or an already documented requirement directly when doing so avoids pointless handoff and it can cite the same proportional inputs Design would have supplied. This is flexibility, not a second requirement format.

Whenever either entry path will need a TaskPackage, it publishes one immutable `demand-authority.json` with the initial demand creation:

• `requirement`: Original Plan, Requirement Design, code facts, landing plan,

non-goals, user-confirmation ledger, and Test decision;

• `bug`: reproduction, bounded scope, non-goals, and Test decision;
• `supplement`: existing Requirement Design, explicit delta, user confirmation,

and Test decision;

• `research`: research question and boundaries; no implementation package.

Every reference is a workspace-relative Markdown anchor. A real-environment Test decision also names the exact `test-environment` anchor. `Auto Claim` authorizes unattended claiming only; it never supplies missing requirement authority. Public v3 can publish a demand with `authority: null`, but no public operation can add authority afterward and `wakeflow_add_task` requires the exact frozen authority tuple for every TaskPackage. Therefore, whenever a TaskPackage will be needed, include the complete authority in the initial `wakeflow_create_demand` preview/apply publication. Do not manufacture missing anchors to make the machine gate pass; route the gap to Design or the user.

**Red Flag — a third point-fix on the same task.** Only when the retained event history actually proves two prior controller rework decisions should the next move require a new root-cause hypothesis or a non-bug-mismatch route to Design redesign. Current v3 state has no `reworkCount` or `recurringProblem` field, so never infer this brake from an absent counter.

Controlle