/wakeflow-governance

name: wakeflow-governance
description: Use when working inside Wakeflow on workspace initialization / setup, CLAUDE.md / skill layering, TODO / Backlog intake, Design handoff intake, idle-window scheduling, window coverage, task-package dispatch, producer/consumer sequencing, unified dispatch prompts, test handoffs, validation boundaries, or workspace script pipelines. This skill supplements CLAUDE.md and must not override its hard boundaries.

Wakeflow Governance

This skill holds detailed Wakeflow procedures that are too bulky to keep fully resident in `CLAUDE.md`.

Scope

For workspace initialization or setup requests, use the Wakeflow MCP capability tool first:

• Call `wakeflow_maintain_workspace` with `action: "fresh-initialize"`,

`mode: "preview"`, and one closed `request.selection` for a fresh workspace. The selection explicitly partitions `program`, `topology`, `storage`, `governance`, and `hosts`; repository, support-surface, and window entries use request-local `selectionKey` links. Wakeflow allocates the durable typed IDs.

• Preview is read-only. Review its blockers, exact `confirmedActionPlan`,

returned `confirmedActionPlanDigest`, and `launchIntents`. Apply only after the user confirms the write boundary, by sending the same root and action with `mode: "apply"`, the exact confirmed plan, and that returned digest.

• Use `action: "reconfigure"` only for an intentional desired-model change and

`action: "reconcile"` only to restore managed bytes/projections from current v3 authority. Both follow the same preview-before-apply rule. `recover` requires the exact plan, digest, and incomplete mutation `operationId`.

• Do not infer Design/Test from similar existing directory names such as

`<WorkspaceName>Design`, `<ProductName>Design`, `<WorkspaceName>Test`, or `<ProductName>Test`. Unless the user explicitly names those as Design/Test, Wakeflow should create/use fresh `Design` and `Test` support surfaces.

• If a workspace contains legacy config/runtime/ledger/tool surfaces or unclear

ownership, do not force fresh initialization or pass discovery/reset aliases. Report the stable blocker and use the explicit unregistered migration path only when the user has requested migration.

• During apply, Wakeflow synchronizes the workspace `.gitignore` so

only `.wakeflow-active/` and `.wakeflow-local/` are ignored runtime directories. Do not add product repositories, Design/Test, ledgers, `.DS_Store`, or other user workspace noise as Wakeflow-generated gitignore entries.

• Window removal is a reconfigure decision expressed in the complete desired v3

topology; there is no `excludeWindows` or semantic window-name mutation alias.

• Pass `language: "zh"` when the user is working in Chinese, `language: "en"`

when the user asks for English, and leave `language: "auto"` only when there is no clear preference. The returned `displayTitle` is the canonical window title: the tmux window NAME is the displayTitle (for example "AppRepo Work"), and it may appear in the tmux status bar and terminal tabs. Only the v3 activation owner may apply or restore that display metadata; title text is never identity authority.

• After the confirmed apply succeeds, retain the matching preview's

`launchIntents`. They are host-neutral authorizations. Route each exact launch through the packaged v3 Claude host facade's `launch-window` owner, then call `wakeflow_register_window operation=register` with the final real session handle. Registration writes one typed host-local binding and refreshes the redacted window-runtime projection; it never classifies a startup reply as ready/pending/failed. Retired public-v2 registry/window-host commands are not aliases. If the exact host effect or receipt is unavailable, report the launch intents and stop instead of writing substitute runtime files.

• To rebuild selected windows, call `wakeflow_replace_windows` with

`operation: "replace"` and its exact typed request. Execute only the returned host-neutral replacement intent through the v3 host owner, then register the final session handle. Do not rewrite unrelated bindings or store role, cwd, or title as identity authority.

• Do not use `wakeflow_maintain_workspace` fresh initialization as a refresh path for window

context bloat. Replacement returns only the authorized host-neutral intent; launch only that window and register its final session handle.

• Pod creation and recovery are separate. Use

`wakeflow_pod_open operation=launch-preview/launch-apply` only for first materialization and `operation=inspect-materialization` for an existing binding. Missing or ambiguous identity stops; never fall back to mainline or a discovered same-named worktree. Claude Code desktop windows are not an automation transport.

• tmux windows cannot answer permission prompts while the user is away.

Per-repository `.claude/settings.json` allowlists, or an explicit `--claude-arg --permission-mode=acceptEdits` at launch, are the user's decision; Wakeflow never chooses silently.

• Do not replace that tool with a hand-written inspection checklist when the MCP

server is available.

• If Wakeflow MCP tools are unavailable, say that the MCP server is unavailable

and stop for plugin reload/reinstall instead of pretending initialization can proceed through docs alone.

• Wakeflow MCP initialization does not place real session handles in tracked

docs or prompts. The typed binding is the host-local identity authority; `window-runtime` is a redacted projection, not a second authority.

Use this skill after reading:

1. `CLAUDE.md` 2. `.wakeflow-active/index.md` 3. `.wakeflow-active/current/workspace-current-status.md` 4. the current controller state root and its developer progress document when the active demand has an execution surface

This skill may guide workspace documentation, TODO intake, dispatch planning, and validation. It must not authorize pr