codex deck flow
- Repo stars 8
- License MIT
- Author repo codex-deck
- Domain
- Engineering
- Author-declared agents
- No explicit declaration found; this is not inferred or tested compatibility
- Static check
- 94 / 100 · heuristic scan, not runtime safety proof
- Runtime evidence
- Not run; no isolated runtime test evidence is currently recorded
- Author / version / license
- @asfsdsf · MIT
- Token usage
- Lean
- Setup complexity
- Plug-and-play
- External API key
- Not required
- Operating systems
- Unspecified (assume cross-platform)
- Runtime requirements
- No explicit requirements detected
- Detected file/system behavior
-
- Read-only
- Write / modify
- Network behavior
- Local-only
- Install commands
- None (reference only)
Heads up: Tool permissions are not declared; actual access depends on the runtime.
# Orchestrate Persistent Multi-Agent Workflows
Use this skill to create workflows, inspect workflows, and send control messages to the background codex-deck-flow daemon.
This skill is an **operator control client**, not the long-running orchestrator. After the daemon has started successfully and a control message has been sent successfully, the skill should stop.
Detailed operational guidance is routed through `references/*.md`:
- Command sequences and syntax: `references/commands.md`
- Workflow/task authoring rules: `references/authoring.md`
- Failure recovery runbooks: `references/runbooks.md`
- Scheduler vs workflow-task guidance placement: `references/guidance-routing.md`
- Architecture, contracts, and role prompts: `references/agent-flow-design.md`
- Scheduler mutation heuristics (scheduler task only): `references/scheduler.md`
## Mandatory activation contract
- If the user explicitly mentions `$codex-deck-flow` or `codex-deck-flow`, treat that as a strict instruction to use this workflow system.
- Do not switch to direct ad-hoc coding as the primary path while that request is active.
- In the first response after activation, say that codex-deck-flow orchestration is active and state the first command you are running.
- If the user gives `project root` plus `workflow ID` for a workflow that the current session has not created, loaded, or already resolved, first run `resolve-workflow`, then continue with `validate`, `reconcile`, and `status`.
- If the current session already knows the workflow path from `create`, a previous `resolve-workflow`, or earlier inspection in the same chat, reuse that path instead of resolving again.
- If the user already gave a workflow path, start with `validate`, then `reconcile`, then `status`.
- If no workflow exists yet, start with `create`, then immediately `validate`, then `show` or `status`, and present the authored tasks/prompts for user approval before `trigger`.
- If the user explicitly includes `Strict task creating mode`, keep the normal create/validate/show flow, but use the strict authoring protocol described below.
- Keep merge explicit. Never run `merge --apply` unless the user explicitly asked to apply the integration branch into the target branch.
- Once `trigger` or `daemon-send` succeeds, stop. Do not continue the same skill turn as if it were the orchestrator.
## Strict task creating mode
When the user explicitly includes `Strict task creating mode`, treat that as a workflow-authoring protocol layered on top of the normal codex-deck-flow create flow.
Rules:
- Still run `create`, then `validate`, then `show` or `status` as usual.
- The draft workflow JSON already exists after `create`; approval still gates `trigger`, not draft creation.
- If you must ask the user a clarifying question before the workflow is ready, the assistant message must end with exactly:
- `<codex-deck-flow>Question<codex-deck-flow/>`
- When asking the user to approve the authored workflow, the assistant message must end with exactly:
- `<codex-deck-flow>Request approve:workflow-file-name.json<codex-deck-flow/>`
- Replace `workflow-file-name.json` with the JSON file name only, for example `feature-delivery.json`.
- Use only the file name token after `Request approve:`. Do not add brackets or extra wrappers.
- Do not put any additional text after the strict tag suffix.
- Once the user approves, exit strict task creating mode and continue with the normal codex-deck-flow flow.
- If the approval message includes workflow data for an already-created draft, reuse that workflow and do **not** run `create` again.
- The approval workflow data may include fields such as `workflowPath`, `workflowFileName`, `workflowId`, `projectRoot`, and `boundSessionId`; treat that as the canonical handoff for reusing the already-authored draft.
## Core runtime model
- One workflow = one JSON file under `./.codex-deck/`.
- The daemon is the orchestration owner and can serve workflows from multiple project roots.
- The skill starts daemon if needed, sends one control message, then stops.
- Worker tasks run in isolated `git worktree` directories.
- Scheduler continuity should use codex-deck-flow non-interactive app-server-backed resume behavior (`scripts/codex_resume_noninteractive.py` behavior model), not raw `codex resume SESSION_ID` semantics in daemon mode.
Use `references/agent-flow-design.md` for full runtime contracts and role data.
## Route by intent
Use this decision route, then follow details in `references/commands.md`:
1. New workflow request: `create` -> `validate` -> `show/status` -> user approval -> `trigger`
2. Existing workflow by known path: `validate` -> `reconcile` -> `status`
3. Existing workflow by project root + workflow ID when path unknown in current session: `resolve-workflow` -> `validate` -> `reconcile` -> `status`
4. Explicit daemon control message: `daemon-send` or `stop-workflow-processes`
5. Merge request: `merge` preview, and `merge --apply` only if explicitly requested
## Reference loading boundaries
- Scheduler task only: `references/scheduler.md`
- Scheduler/workflow-task guidance file rules and routing: `references/guidance-routing.md`
- Non-scheduler roles should not load scheduler-specific mutation guidance.
## References
Canonical references:
- `references/commands.md`
- `references/authoring.md`
- `references/runbooks.md`
- `references/guidance-routing.md`
- `references/agent-flow-design.md`
- `references/scheduler.md` (scheduler task only)
Implementation scripts:
- `scripts/workflow.py`
- `scripts/task_runner.py`
- `scripts/daemon.py`
- `scripts/daemon_client.py`
- `scripts/codex_resume_noninteractive.py`
- `scripts/session_state.py`
- `scripts/session_summary.py`
Sections and files
Listed in source order.
sections -> Mandatory activation contract → Strict task creating mode → Core runtime model → Route by intent → Reference loading boundaries → References
terms -> operator control client · not · Use this skill to create workflows, inspect workflows, and send control messages to the background codex-deck-flow daemon. · This skill is an operator control client, not the long-running orchestrator. · - If the user explicitly mentions $codex-deck-flow or codex-deck-flow, treat that as a strict instruction to use this workflow system. · - Still run create, then validate, then show or status as usual. · - One workflow = one JSON file under ./.codex-deck/. · Use references/agent-flow-design.md for full runtime contracts and role data.
files/cmd -> references/*.md · references/commands.md · references/authoring.md · references/runbooks.md · references/guidance-routing.md · references/agent-flow-design.md · references/scheduler.md · $codex-deck-flow
body sha256 -> e3a7ce9a0e67
Mandatory activation contract
If the user explicitly mentions
$codex-deck-floworcodex-deck-flow, treat that as a strict instruction to use this workflow system. Do not switch to direct ad-hoc coding as the primary path while that request is active. In the first response after activation, say that codex-deck-flow orchestration is active and state the first command you are running. If the user givesproject rootplusworkflow IDfor a workflow that the current session has not created, loaded, or already resolved, first runresolve-workflow, then continue withvalidate,reconcile, andstatus.Strict task creating mode
When the user explicitly includes
Strict task creating mode, treat that as a workflow-authoring protocol layered on top of the normal codex-deck-flow create flow. Rules: Still runcreate, thenvalidate, thenshoworstatusas usual. The draft workflow JSON already exists aftercreate; approval still gatestrigger, not draft creation. If you must ask the user a clarifying question before the workflow is ready, the assistant message must end with exactly:Core runtime model
One workflow = one JSON file under
./.codex-deck/. The daemon is the orchestration owner and can serve workflows from multiple project roots. The skill starts daemon if needed, sends one control message, then stops. Worker tasks run in isolatedgit worktreedirectories. Scheduler continuity should use codex-deck-flow non-interactive app-server-backed resume behavior (scripts/codex_resume_noninteractive.pybehavior model), not rawcodex resume SESSION_IDsemantics in daemon mode.Route by intent
Use this decision route, then follow details in
references/commands.md: New workflow request:create->validate->show/status-> user approval ->triggerExisting workflow by known path:validate->reconcile->statusExisting workflow by project root + workflow ID when path unknown in current session:resolve-workflow->validate->reconcile->statusExplicit daemon control message:daemon-sendorstop-workflow-processesReference loading boundaries
Scheduler task only:
references/scheduler.mdScheduler/workflow-task guidance file rules and routing:references/guidance-routing.mdNon-scheduler roles should not load scheduler-specific mutation guidance.