• Why Wakeflow
• Architecture
• Install Wakeflow
• Initialize A Workspace
• Run Your First Demand
• What Wakeflow Creates
• Automation Semantics
• MCP Capability Surface
• Runtime And Ledger Boundaries
• Dual-Host Workspaces
• Marketplace Release
• Working In This Repository
• Design Principles

Why Wakeflow

Hand an agent fleet a real, multi-repository goal and come back later with the
three questions that matter: what was actually done, what evidence proves
it, and what is still open? Without a control layer the honest answer is a
pile of scattered prompts, copied status tables, unclear ownership, and
"looks done" — work that cannot be audited, resumed, or trusted.

Wakeflow is that missing control layer — one controller window drives focused
repository windows through an explicit, machine-checked loop, and every step
leaves a verifiable artifact on disk:

• Controller-first judgment: the parent workspace owns goals, boundaries,
  dispatch decisions, acceptance, TODO routing, and archive decisions.
• One state root per demand: task packages, target results, review
  candidates, decisions, and progress projections stay tied to the same demand.
• Focused child windows: each repository window works only inside its
  configured responsibility boundary.
• Compact delivery: direct-thread prompts wake the right window with a small
  envelope; the state root and skills hold the task details.
• Evidence before acceptance: target backfill is input, not a conclusion.
  The controller still reviews raw evidence before completing work.
• Local-first runtime: real thread ids live only in the local thread
  registry; window config is a derived sendability view, and active state stays
  out of tracked source.

What you get, concretely:

• Auditable — every dispatch, delivery, result, and decision is a JSON
  artifact tied into one trace spine; wakeflow_view (scope trace) replays
  who did what, on which evidence, at which state revision.
• Resumable — demands continue from their on-disk state roots. Codex
  threads and Claude Code conversations are rebound from host-local registered
  ids; after a machine reboot, Claude's tmux windows must be relaunched before
  those conversations resume. No conversation memory is state authority.
• Hard to fake — acceptance requires raw evidence that the reducers verify
  on disk (missing evidence refs fail closed); "the target said done" is never
  enough, and results never accept themselves.
• Parallel without chaos — up to maxActiveDemands demands run side by
  side as isolated pods (own controller, own worktrees, own Test); within one
  demand each repo stays strictly one-window-one-package, and pod branches
  merge back only through a human-reviewed ledger.
• Safe by construction — fail-closed guards on ownership, capacity, locks,
  and archive redaction; real session ids never leave the local registry.

Wakeflow is not a command launcher with nicer names. It is a reusable workflow
capability for keeping multi-window agent work legible, bounded, and resumable.

Architecture

Wakeflow is three layers working together: a window fleet you can see, a
closed loop that moves the work, and a disk layout that survives restarts.
Both editions — Codex and Claude Code — run the same host-neutral state,
delivery, and validation core. Their manifests, memory files, window lifecycle,
and transport remain host-specific (Codex host thread tools vs a tmux helper).

Layer 1 — the fleet (what you see)

Every Wakeflow window is an agent session pinned to one responsibility. On
Claude Code the baseline fleet lives in the configured tmux session and each
demand pod has its own tmux session; on Codex the windows are host threads.

Layer 2 — the loop (how work moves)

Work is organized into demands: one demand = one goal = one state root on
disk. Every demand moves through the same closed loop:

 1 init       raw state init creates the demand root               (unclaimed)
 2 claim      public create, or first raw-state drive, binds host  (codex | claude)
 3 add task   a task package names the target window and scope
 4 dispatch   envelope written -> window LOCKED -> prompt delivered
 5 work       the target window executes inside its repository boundary
 6 result     TargetResultEnvelope lands with evidence refs -> lock released
 7 review     controller reads RAW evidence, then accepts / reworks / blocks
 8 complete   only when every task is accepted and no blockers remain

Two rules keep the loop honest: prompts wake, state instructs (the
delivered prompt only names window, task id, and state root; the task
definition lives in the state root and skills), and backfill is input, not
acceptance (the controller reviews raw evidence before any decision; a
blocked decision is always recoverable once new evidence arrives).

Layer 3 — the ground (what's on disk)

<workspace>/
  wakeflow.config.json          windows, roles, per-host knobs      committed
  AGENTS.md / CLAUDE.md          per-host controller gates           committed
  wakeflow-ledger/               durable designs, records, archives  committed
  .wakeflow-active/             demand state roots (layer 2)        local
  .wakeflow-local/wakeflow-delivery/                                local
    dispatch-packets/  delivery-envelopes/  delivery-runs/    transport records
    target-results/                                           evidence envelopes
    locks/                       one in-flight delivery per window, cross-host
    hosts/codex/                 codex thread registry  (host-scoped)
    hosts/claude-code/           claude session registry + tmux bindings

Rule of thumb: business truth is host-neutral and shared; transport handles
are host-scoped and never leave .wakeflow-local/.

Who decides what (trust model)

Scripts and MCP tools create, validate, and record machine data; they never
choose acceptance, widen scope, or decide product behavior on their own. They
only persist an explicit controller decision. Target windows execute
exactly their dispatched package. The controller is the only acceptance
authority and must establish functional correctness before Test starts. Test
cannot invent goals, methods, or completion criteria; it only investigates the
approved environment boundary. The user owns product decisions.

Dual-host coexistence

One workspace may run both editions side by side: demands bind to one platform
at claim time (machine-enforced on every driving command), the shared
per-window lock serializes deliveries across hosts, and ownership moves only
through the explicit, audited adopt-demand-host transfer.

Install Wakeflow

Wakeflow uses the same two-layer marketplace shape as Lark Remote: the
repository root is the development workspace, and the installable plugin
artifacts live under plugins/. The repository ships two host editions built
from one shared core:

Install the Claude Code edition from inside Claude Code:

/plugin marketplace add GxFn/Wakeflow
/plugin install wakeflow@gxfn

The Claude Code edition is terminal-only: every Wakeflow window (controller
included) is a tmux-resident interactive claude session in the wakeflow
tmux server session, and a Wakeflow thread id is the window's Claude Code
session id (stable across resumes). Up to maxActiveDemands (default 2)
demands may run side by side as demand pods — each pod is its own tmux
session with its own controller, per-repo isolation worktree windows, and its
own Test, the WHOLE pod sharing the demand's one worktree set (Test verifies
there, never on a main checkout); claiming past capacity fails closed, and
pod branches merge back only through the human-reviewed pending-merges.md
ledger. See
plugins/claude-code-wakeflow/README.md
for the full Claude Code guide.

Install the public Codex plugin artifact:

npx codex-marketplace add GxFn/Wakeflow/plugins/codex-wakeflow --plugin

For a pinned release after the matching tag exists:

npx codex-marketplace add https://github.com/GxFn/Wakeflow/tree/v0.8.14/plugins/codex-wakeflow --plugin

If the Codex dialog separates source, ref, and sparse path, use the repository
URL, the desired ref, and plugins/codex-wakeflow as the sparse path.

The Codex edition runs the shared demand-pod model as per-demand thread sets:
wakeflow_pod_open creates the demand's worktree set and returns a windowPlan
the agent realizes with create_thread (each thread's cwd is its worktree),
and wakeflow_pod_close tears it down onto the pending-merges ledger after
completion. The invariant is shared (one controller, one Test, and one
worktree per selected repository for the demand), while each host owns its
window lifecycle and teardown sequence.

For local development, register this checkout as its own local marketplace:

[marketplaces.gxfn]
source_type = "local"
source = "/absolute/path/to/Wakeflow"

[plugins."wakeflow@gxfn"]
enabled = true

[plugins."wakeflow@gxfn".mcp_servers.wakeflow]
default_tools_approval_mode = "approve"

Wakeflow does not require an aggregate marketplace repository. A separate
catalog can still list Wakeflow for brand discovery, but that is not part of
the primary install or release path.

Initialize A Workspace

Wakeflow is installed as a Codex or Claude Code plugin. A target workspace
does not need to contain Wakeflow source code. The expected target shape is:

Naming: wakeflow.config.json is the canonical config name. A pre-rename
workspace's workspace.config.json keeps working (read fallback); rename it
with git mv workspace.config.json wakeflow.config.json when convenient —
check-workspace reminds you.

MyWorkspace/
  AGENTS.md or CLAUDE.md
  wakeflow.config.json
  .wakeflow-active/          # ignored active controller state
  .wakeflow-local/           # ignored thread registry and derived runtime
  wakeflow-ledger/            # durable project coordination records
  ProductRepo/
  CoreRepo/
  Design/                     # default internal requirement-design surface
  Test/                       # default internal test coordination surface

The simplest user prompt is:

Use Wakeflow to initialize the current workspace.
Preview the plan first and wait for my confirmation before writing.

The operating flow is:

1. Codex calls wakeflow_initialize_workspace with apply: false.
2. Wakeflow returns directory facts and an agentSelectionProtocol.
3. Codex judges whether the workspace is clean or messy from those facts and
   user context.
4. For a clean workspace, Codex calls the tool again with explicit
   repositories mappings for the intended work windows.
5. For a messy workspace, Codex asks which directories are managed windows
   before writing. It must not use a broad discovered-directory import.
6. After user confirmation for a fresh workspace, Codex calls
   wakeflow_initialize_workspace with apply: true.
7. Codex creates the returned Codex threads, resets each thread title to the
   returned displayTitle, and passes each real thread id once to Wakeflow's
   local registration command. The thread registry is the only thread-id
   authority; window config is refreshed as a derived view.

For an already initialized workspace, wakeflow_initialize_workspace is not a
general refresh button. It may write only after the user explicitly requests a
reset initialization; the apply call must set resetInitialization: true, pass
explicit repositories, reconfirm Design/Test mode, and must not use
useDiscovered. Heavy or stale windows use the replacement commands instead.

Command responsibilities stay separate:

In the Claude Code edition, the same preview/apply contract is used. The
returned launch plan is materialized by the tmux host helper instead of Codex
create_thread: each window is launched as an interactive claude session,
and the returned Claude Code session id is registered as the Wakeflow thread
id.

Design and Test are fresh support surfaces by default. Existing similarly named
directories such as <Product>Design or <Product>Test are treated as ordinary
directory facts unless the user explicitly maps them as Design/Test.

Wakeflow supports localized initialization. Pass language: "zh" for Chinese
workspaces, language: "en" for English workspaces, or language: "auto" when
there is no clear preference. Generated thread titles keep the window name at
the front so the important repository name remains visible in narrow sidebars.
New state-root progress documents and subsequent Unified Status renders also
use the selected interface language.

Controller and child windows can use Codex or Claude Code subagents to speed
up bounded code search, log triage, test localization, and evidence summaries.
Subagent output is evidence or advice only; controller review, dispatch, state
writes, and repository boundaries remain with the Wakeflow window that owns the
task.

Run Your First Demand

The loop is the same on both hosts; only how you drive it differs.

Claude Code (slash commands):

1. /wakeflow:init — discover the workspace, confirm scope with you, write
   config/docs, and launch the tmux fleet (tmux attach -t wakeflow to watch).
2. Feed the goal to the Design window (or write the requirement yourself).
   Design clarifies it and calls wakeflow_deliver — the demand lands as a
   pending-claim row on the global TODO board with its design docs linked.
3. In the controller: /wakeflow:status to see the board, then claim it —
   wakeflow_claim_next (auto-claimable rows) or wakeflow_create_demand
   (explicit). This inits the state root and consumes the row; the controller
   confirms the plan and task packages with you before any dispatch.
4. /wakeflow:dispatch — prepare one envelope, deliver it in one step, record
   the readback, end the turn. The target window works inside its repository
   and its controller-return wakes the controller with evidence attached.
5. /wakeflow:review — read the raw evidence behind the result, then record
   the decision: accept / rework / blocked / redesign.
6. Repeat dispatch → review until every non-Test task is accepted and the
   controller has completed its own functional validation. Only then may the
   controller add/dispatch a confirmed Test card; Test follows the frozen goal,
   approved Test plan, controllerSelfChecks, allowed skills, setup policy,
   and attempt bound. A Test skill such as progressive-chain-validation is
   usable only when the card names it explicitly.
7. When every required task is accepted, run
   wakeflow_complete_demand and wakeflow_archive close the story into the
   ledger. Demand archive dry-run reports real-id and absolute-path findings;
   use redact: true to commit a re-scanned portable copy while preserving the
   original locally.
   If a verified same-scope gap appears after completion but before archive,
   wakeflow_continue_demand preserves that completion and adds the
   first bug/supplement/authorized-optimization package. Archived history stays
   immutable; independent follow-up work uses a new demand.

Codex (natural prompts): the same loop through the same MCP tools —
"Use Wakeflow to initialize this workspace", "claim the next demand",
"dispatch the next package", "review the returned results", "complete and
archive the demand".

Daily driving (Claude Code):

What Wakeflow Creates

Initialization writes only the surfaces needed for the confirmed workspace
boundary:

Wakeflow also synchronizes .gitignore so only .wakeflow-active/ and
.wakeflow-local/ remain local runtime directories. It does not add product
repositories, Design/Test folders, ledgers, .DS_Store, or other user
workspace noise to .gitignore.

Automation Semantics

Wakeflow automation is direct-thread delivery plus explicit result return.

Core rules:

• Real thread ids live only in the host-scoped local thread registry under
  .wakeflow-local/wakeflow-delivery/hosts/<host>/thread-registry/
  (codex or claude-code).
• Window config is derived from wakeflow.config.json plus thread-registry
  presence; it is not a second thread-id or window-semantics authority.
• Delivery prompts remain compact and human-readable.
• The host sends prompts through its transport boundary: Codex thread tools for
  Codex, and the tmux host helper for Claude Code. Wakeflow records the send
  and readback evidence.
• group-ready waits for the expected target results before a controller
  return.
• per-target can wake the controller once per target while still preserving a
  group snapshot.
• After a real send is recorded as sent with readback evidence, the controller
  turn stops. It does not sleep or poll in the same turn.
• Keep-live support is runtime assistance only. It is not task logic, transport
  authority, or acceptance evidence.
• Raw wakeflow-state init is host-neutral and writes controllerHost: null.
  The public wakeflow_create_demand wrapper immediately adopts the new root
  for the calling host; an independently imported raw root remains unclaimed
  until its first driving command.
• After a demand is owned by one host, the other host fails closed on
  controller mutations and dispatch preparation unless ownership is explicitly
  transferred with --adopt-host.
• Up to maxActiveDemands (default 2, top-level wakeflow.config.json) demands may be active at once; claiming past capacity fails closed until one completes and archives. wakeflow_next_work reports activeDemands + demandCapacity.
• wakeflow_status exposes demand ownership under dualHost.demandOwnership
  so mixed-host controllers can see which platform owns active work before
  acting.

Automation stops on final completion, hard gates, user stop, no eligible work,
missing evidence, blocked state, or any condition that requires controller or
user judgment.

MCP Capability Surface

Wakeflow exposes only stable outer workflow contracts as MCP tools. Runtime
scripts remain the internal implementation and test surface; they are not
public tools just because they exist. A target closeout uses the same
direct-thread delivery model as controller dispatch: prepare an envelope, send
the prompt with the host thread tool, then record the delivery run.

Primary tool groups:

Public MCP tools are for outer agent workflows. Target closeout is deliberately
split: record a target result, review readiness, prepare a controller-return
envelope when policy allows, send through the active host transport, and record
delivery evidence. Controller review stays split as review pack, result
reduction, and explicit decision; result reduction only creates a review
candidate and is not acceptance. Do not collapse those steps into a single
target-window MCP tool. Internal steps such as archive summary refresh internals,
keep-live state, and script backend execution stay inside Wakeflow JS/runtime
scripts and skills. Public archive MCP tools wrap controller-approved demand,
TODO, and workspace-document archive flows. wakeflow_sanitize_archive only
replaces an already archived demand with a privacy-clean copy and preserves the
original locally; neither tool makes acceptance decisions or sends host messages.

Wakeflow declares MCP tool annotations for every public tool: read-only tools
are marked read-only, write tools are local, non-destructive, and closed-world.
Codex approval policy is still controlled by the user's Codex config. For a
trusted local Wakeflow installation, the matching Codex server policy is:

[plugins."wakeflow@gxfn".mcp_servers.wakeflow]
default_tools_approval_mode = "approve"

Runtime And Ledger Boundaries

Wakeflow keeps source, active runtime, and durable records separate:

The source repository tracks reusable Wakeflow capability. Product code,
project-specific active state, real thread ids, and derived local runtime
artifacts do not belong in Wakeflow source.

Dual-Host Workspaces

One workspace may run the Codex and Claude Code Wakeflow editions side by
side. Shared business state stays host-neutral: .wakeflow-active/,
wakeflow-ledger/, and the shared delivery spine under
.wakeflow-local/wakeflow-delivery/ (dispatch-packets/,
dispatch-groups/, delivery-envelopes/, delivery-runs/,
target-results/, and shared locks/).

Host-scoped runtime is separated per host:

• .wakeflow-local/wakeflow-delivery/hosts/codex/{thread-registry,window-config,keep-live}/
• .wakeflow-local/wakeflow-delivery/hosts/claude-code/{thread-registry,window-config,window-host,keep-live}/

AGENTS.md (Codex) and CLAUDE.md (Claude Code) may coexist at the
workspace and child roots. Each demand still has exactly one controller host:
public creation adopts the calling host, raw state init remains neutral until
first drive, non-owning hosts fail closed, and --adopt-host is the explicit
transfer mechanism.

Marketplace Release

Wakeflow is packaged as a dual-host plugin source repository. The public
source of truth is:

https://github.com/GxFn/Wakeflow.git

The repository carries separate host catalogs:

• .agents/plugins/marketplace.json points the Codex plugin entry at
  ./plugins/codex-wakeflow.
• .claude-plugin/marketplace.json points the Claude Code plugin entry at
  ./plugins/claude-code-wakeflow.

Publishing Wakeflow means tagging the repository and submitting the correct
nested artifact for the target host, not the development workspace root.

Before publishing a release tag:

1. Run npm test from this repository.
2. Run the host-specific plugin manifest validators where available.
3. Confirm plugins/codex-wakeflow/.codex-plugin/plugin.json has no more than
   three starter prompts.
4. Confirm both host catalogs point only at their nested plugin artifacts.
5. Confirm runtime scripts and installed skills contain no project-specific
   default controller names, product overlays, local paths, or private thread
   ids.
6. Tag the exact commit that the host marketplace should install.

Working In This Repository

Use this repository to develop the Wakeflow plugin itself.

npm run sync:core    # copy core/ into both plugin artifacts
npm run check:core   # fail when an artifact drifts from core/
npm run validate     # codex artifact validation
npm run validate:claude
npm run smoke        # codex artifact smoke
npm run smoke:claude
npm run test:wakeflow
npm test             # check:core + both validates + both smokes + tests

Shared-core rule: host-neutral runtime files live in core/ and are synced
into both artifacts with tools/sync-core.mjs; edit them in core/, never in
an artifact copy. Host-specific files (host profile, host artifact checks,
host send adapter, manifests, READMEs, memory-file template, skills, template
bundle) live only inside each artifact. npm run check:core keeps the copies
honest.

The full dual-edition architecture, code logic, local file storage (the
shared-business-state vs host-scoped-runtime split), and state flow are
documented in
docs/wakeflow-dual-edition-architecture-and-state-flow.md;
the companion design-pattern read — why the architecture looks like this and
what it costs — is
docs/wakeflow-architecture-deep-dive-2026-07-02.md.

Common source areas:

Backend/source-maintenance command references live in
scripts/README.md. Installed
controllers use the MCP tools and skills rather than treating raw scripts as
their operator interface.

Design Principles

1. Judgment stays visible: script output, status rows, and target backfill
   are evidence, not acceptance.
2. One demand, one state root: JSON state and Markdown progress surfaces
   stay tied to the same demand.
3. Prompts wake, state instructs: prompts should be compact; task detail
   belongs in state roots, task packages, and installed skills.
4. Repository boundaries matter: each window owns its source, tests,
   commits, and evidence.
5. Automation moves work, not authority: direct-thread delivery proves that
   a prompt was sent, not that the result is complete.
6. Local runtime stays local: real thread ids stay only in the local thread
   registry, and active runtime state never enters tracked documentation.
7. Fresh support windows by default: Design and Test are created as clear
   Wakeflow support surfaces unless the user explicitly maps existing ones.

Wakeflow exists to make multi-window agent work safe to resume, easy to
inspect, and hard to fake.