Wakeflow: Instructions file for Claude Code

Wakeflow Source Repository Instructions For Claude Code

This checkout is the development repository for the Wakeflow Codex and Claude Code plugin artifacts. Work here maintains Wakeflow itself; it is not an installed controller workspace and it does not own the product repositories used to test Wakeflow.

The generated plugin artifacts under plugins/ carry the skills, commands and READMEs shipped to installed controller workspaces. They describe an installed workspace's rules, not this repository's. Do not mistake their controller-role restrictions for a prohibition on authorized Wakeflow source maintenance here.

Scope And Safety

• Follow the user's requested scope. Do not expand a Wakeflow change into an Alembic product change or another external repository.
• Preserve pre-existing and unrelated working-tree changes. Inspect git status --short --branch and the relevant diff before editing.
• Do not use destructive Git operations such as git reset --hard, discard another contributor's changes, or rewrite history unless the user explicitly authorizes that exact operation.
• Do not commit, push, tag, publish, or refresh an installed plugin cache unless the user explicitly requests that action. Authorization for one of these actions does not imply authorization for the others.
• Use only explicitly designated disposable workspaces for destructive runtime tests. Never treat a real product repository as a Wakeflow fixture.
• Keep secrets, tokens, private session or thread identifiers, local absolute paths, and machine-specific cache paths out of committed source, fixtures, and docs.

Source Ownership

• src/, tooling/ and tests/ are the only hand-written code. src/ is the runtime in six layers — foundation → contracts → kernel → capabilities / governance / configuration / workspace → hosts → entrypoints — and npm run check:architecture enforces the direction.
• plugins/codex-wakeflow/ and plugins/claude-code-wakeflow/ are generated by tooling/artifacts/build-plugin-artifacts.ts. Never edit them by hand: change the source, run npm run build:artifacts:committed, and let npm run build:check prove the committed bytes match a fresh build.
• assets/agent-text/ is the single source of the skills, commands and READMEs in both artifacts. Host differences are the twelve placeholders filled by src/hosts/<host>/<host>-agent-text-profile.ts; the build fails on an unregistered placeholder or an unused value.
• Host-specific behavior lives only in src/hosts/<host>/: profiles, the hook fragment, the agent-text value table, maintenance execution, Claude's settings and status-line assets. Shared code consumes values a host profile supplies; it must not infer Codex-versus-Claude behavior through ad hoc host checks.
• The Claude Code host has two window transports, tmux and desktop sessions, and both are first-class and maintained together; neither replaces the other. A change to the window transport layer (launch instructions, the helper asset, binding observations, liveness observations, the maintenance asset set, handover text) lands on both transports in the same batch, or registers the gap in docs/references/open-items.md (section Y for tmux, section X for desktop) with the batch that restores parity. Shared code consumes transport values from the host profile and never checks the transport name ad hoc. The plan is docs/reviews/2026-10-30-claude-host-dual-transport-plan.md.
• src/contracts/schemas/ holds the portable JSON Schemas; src/contracts/generated/ is derived by npm run schema:build and checked for drift by npm run schema:check. Do not hand-edit generated files.
• assets/release/version.json is the only version input. The two plugin package.json files, the two plugin manifests and the Claude marketplace entry must agree with it.
• Treat plugin cache directories as installed outputs, never as source. Modify this checkout first and refresh a cache only from a validated plugin artifact when the user asks for it.
• tooling/cli.ts is the maintainer CLI (npm run wf -- verify|doctor|lab| fault|live|capture|ci|timings), documented in docs/references/maintainer-tools.md. It is development support only: it never enters the artifacts, owns no Demand state, and its lab, live and capture receipts under .build/ carry local paths and stay uncommitted.
• .github/workflows/verify.yml runs the same wf verify gate|artifact profiles on Ubuntu and macOS and uploads only the bounded ci export report. A green local gate is not a remote run; say which one ran.
• wakeflow-architecture-atlas/ is a separate read-only map subproject with its own npm run check in that directory; maps/ is its canon. It is not part of the root gate and must not be cited as runtime authority.