wakeflow

---

• Why Wakeflow
• System Model
• Install Wakeflow
• Initialize A Workspace
• What Wakeflow Creates
• How Work Moves
• Automation Semantics
• MCP Capability Surface
• Runtime And Ledger Boundaries
• Marketplace Release
• Working In This Repository
• Design Principles

Why Wakeflow

Large agent-assisted work rarely lives in one repository or one conversation. A single goal may require a controller, product repositories, a design window, and a real-scenario test window. Without a shared operating model, the work degrades into scattered prompts, copied status tables, unclear ownership, and unfinished evidence review.

Wakeflow provides the missing control layer:

• 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.

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.

System Model

flowchart TD
  User["User goal"] --> Controller["Controller Codex window"]
  Controller --> Gates["AGENTS.md gates<br/>goal, boundary, evidence, stop rules"]
  Controller <--> StateRoot["State root<br/>.workspace-active/..."]
  StateRoot --> Tasks["Task packages"]
  Tasks --> Delivery["Delivery envelopes"]
  LocalRuntime[".workspace-local<br/>thread registry + derived window config"] -. "lookup" .-> Delivery
  Delivery --> Host["Codex host thread tools"]
  Host --> Targets["Repository / Design / Test windows"]
  Targets --> Repos["Responsibility roots"]
  Targets --> Results["TargetResultEnvelope<br/>with evidence refs"]
  Results --> Controller
  Controller --> Ledger["wakeflow-ledger<br/>durable project records"]

The controller is the only acceptance authority. Scripts and MCP tools create, validate, summarize, and record machine data, but they do not widen scope, decide product behavior, or declare a task complete.

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:

Host	Artifact	Catalog
Codex	plugins/codex-wakeflow/	.agents/plugins/marketplace.json
Claude Code	plugins/claude-code-wakeflow/	.claude-plugin/marketplace.json

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). 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.1.2/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.

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