graphflow

name	graphflow
description	Create, edit, and run persistent Codex workflow graphs with optional GitHub delivery.
disable-model-invocation	true

Run a persistent Codex workflow graph

Its bundled runtime stores state under .codex/ and dispatches agent nodes through Codex. The runner owns scheduling, recovery, node execution, and durable state; the coordinator owns graph design, authority, integration, acceptance, and delivery.

1. Resolve identity and authority

Read automation-lifecycle.md. Create an unused stable workflow_id, or require the exact ID to activate or resume an existing workflow:

python3 <skill-dir>/scripts/workflow_state.py resolve .codex/workflows --workflow-id <id>

Effective authority is the intersection of the user request, executor policy, and repository policy. Record commit, push, pull request, merge, deploy, destructive, network, and credential capabilities separately. Complete this phase when identity, objective, authority, and lifecycle state are unambiguous.

If delivery is required, read delivery-contract.md now. Prove the configured adapter, hosting repository, remote, hostname, and available authentication route before any executor dispatch; an unsupported provider or unavailable authorized preflight is a waiting_external terminal, not a late Publish discovery.

For an existing noncanonical flow, read flow-editing.md. Produce a digest-bound reframe proposal and wait for approval before conversion. A canonical flow proceeds through the remaining gates.

2. Close pivotal uncertainty

Record observable objective, atomic requirements and acceptance, constraints, non-goals, authority, and pivotal unknowns. Route a genuinely fuzzy root through the installed brainstorming skill; route a concrete feature brief through grill-me. Missing required skills are design blockers under skill-routing.md.

Read question-triage.md. Resolve pivotal contract unknowns before ready, use evidence-backed reversible defaults for local uncertainty, and isolate branch-scoped questions. Read preflight-costing.md only for a hard budget, requested options, or material execution risk.

Complete this phase when question_gate is locked, clear, and has no unresolved pivotal question.

3. Freeze the intent baseline

Read prototype-gate.md. Use the cheapest credible artifact: wireframe for subjective intent, isolated prototype for integration, characterization test for behavior, or dry-run for deterministic automation. Bind approval to the artifact digest; treat static or mocked evidence as intent proof only.

Complete this phase when the approved digest and limitations are recorded, or a deterministic exemption has a concrete machine-checkable reason.

4. Compile an executable graph

Read graph-contract.md, executor-runtime.md, workspace-trust.md, checkout-guard.md, and method-routing.md. Copy workflow-template to .codex/workflows/<id>/, then adapt every normative artifact.

• Cover every atomic requirement exactly once.
• Give writes, artifacts, and decisions one disjoint owner.
• Pass named outputs only through dependency ancestry.
• Expand by bounded outcome; parallelize only disjoint ownership.
• Compile each leaf to one digest-locked command or agent executor with a local oracle.
• Register modifying, integration, and verifier workspaces separately.

python3 <skill-dir>/scripts/validate_graph.py <graph.json> --phase draft
python3 <skill-dir>/scripts/question_gate.py lock <workflow-dir>
python3 <skill-dir>/scripts/workspace_manager.py init <workflow-dir>
python3 <skill-dir>/scripts/checkout_guard.py --repo-root <repo> init <workflow-dir>

Read integrity-contract.md, adapt requirement checks and independent verifier roles, then lock the oracle:

python3 <skill-dir>/scripts/evidence_runner.py lock <workflow-dir> --repo-root <repo>
python3 <skill-dir>/scripts/validate_graph.py <graph.json> --phase executable --ready
python3 <skill-dir>/scripts/evidence_runner.py validate <workflow-dir> --phase active --repo-root <repo>

Read shared-memory.md and initialize bounded coordinator-owned memory. Complete compilation only when executable validation passes and all executor, question, intent, workspace, memory, and oracle locks match the same semantic graph.

5. Route and run

Read skill-routing.md and subagent-routing.md. Derive node skills from operations, pass only the node contract and named artifacts, and use the cheapest sufficient executor. Read dashboard.md only when a local read-only projection is useful.

python3 <skill-dir>/scripts/run_workflow.py <workflow-dir> --repo-root <repo>

Let the runner acquire the lease, reconcile durable state, check the primary checkout, execute the ready frontier, validate result envelopes, run acceptance checks, and continue to a terminal or waiting state. Read runtime-decomposition.md when an agent returns a structural decomposition proposal. Preserve failed coverage and retry once only after a classified contract repair.

Execution is complete when the runner reaches an honest terminal or digest-bound waiting state with no unaccounted live executor.

6. Verify and deliver

Give a fresh verifier the requirements, approved baseline, locked checks, integrated artifacts, and known limits. Read evidence-calibration.md and record each claim as verified, observed, inferred, or unverified.

python3 <skill-dir>/scripts/evidence_runner.py validate <workflow-dir> --phase complete --repo-root <repo>
python3 <skill-dir>/scripts/memory_state.py validate <workflow-dir> --phase complete --check-artifacts

Every required claim needs a current critical attestation; aggregate score cannot compensate for a failed requirement.

When delivery is authorized, read delivery-contract.md and the installed ship skill. Preserve Gate → Record → Commit → Publish, discover the remote and base branch from repository evidence, and bind one approval to the exact verified tree. Merge and deploy remain separate authority.

Finish with outcome or PR, requirement-level evidence, changed scope, calibrated limitations, cost variance, and deferred optional work. Clear owned leases and processes while retaining evidence needed for recovery or review.