luochen211/dag-delivery

Codex DAG Delivery

Turn GitHub Issues into a live scheduling system. Treat the live work queues—not the diagram or one session's context—as the primary output, and keep recomputing them from current repository and GitHub state.

Enforce the mandatory entry gate

Do this before choosing an operating mode, inspecting an Issue queue, drawing a DAG, creating Issues, or editing code.

1. Inspect before asking

Use the conversation, supplied links, current workspace, and repository files to determine whether both prerequisites already exist:

1. a sufficiently detailed requirements document for the delivery target;
2. the corresponding GitHub repository, available locally or through an accessible GitHub URL.

Search likely requirement sources such as product requirement documents, specifications, design documents, acceptance plans, and repository planning docs. Check whether the current directory is a Git repository, whether it has a GitHub remote, and whether that repository actually corresponds to the requirement.

Do not ask the user for facts that can be established from current context. If either prerequisite cannot be confirmed, ask only for the missing document/link or repository path/URL.

2. Judge requirement sufficiency

Do not count a title, idea, chat fragment, generic README, slide deck, or short feature description as a detailed requirements document. The source must be specific enough to derive atomic Issues without inventing product decisions. Look for:

• delivery goal and intended users;
• in-scope behavior and explicit boundaries or non-goals;
• important flows, business rules, data, roles, and integrations;
• technical or operational constraints already decided;
• acceptance criteria or observable completion conditions;
• named unknowns that still require a user decision.

Mark the requirement gate Pass only when the target, scope, boundaries, and acceptance are sufficiently concrete for decomposition. Mark it Fail when core product decisions are missing. Mark it Unknown when the source cannot be accessed or has not been fully read.

3. Judge repository readiness

Mark the repository gate Pass only when:

• the exact target repository is identified;
• it is hosted on GitHub or has a confirmed GitHub remote;
• its current code, instructions, and GitHub state can be read;
• it corresponds to the requirement rather than merely having a similar name.

An empty or new repository can pass only if it is intentionally the target for a greenfield project and the detailed requirement gate already passes. Mark inaccessible repositories, ambiguous matches, missing remotes, and unspecified future repositories Fail or Unknown.

4. 🔴 CHECKPOINT · 🛑 STOP — Return the gate verdict

Always make the initial verdict explicit:

Requirements: Pass | Fail | Unknown — evidence
GitHub repository: Pass | Fail | Unknown — evidence
Decision: Proceed | Blocked

Do not cross this checkpoint until both gates explicitly read Pass from fresh evidence.

Proceed only when both gates Pass. Otherwise:

• do not create the DAG;
• do not split or create GitHub Issues;
• do not calculate a Ready Queue;
• do not implement code under this workflow;
• identify the smallest missing prerequisite and ask the user to provide it or authorize a separate requirements/repository setup task.

Helping the user write a proper requirement or establish a repository is a valid precursor task, but it is not DAG execution. After that precursor is completed, rerun both gates from fresh evidence.

Choose the operating mode

• Use plan to turn clarified requirements into Epics, atomic Issues, acceptance criteria, and dependency edges. Draft only unless the user authorized creating or editing GitHub objects.
• Use queue for a read-only inventory, DAG validation, visualization, and current Ready Queue.
• Use execute when the user asked to implement or finish work. Select one Ready Issue per executor and close its delivery loop.
• Use audit to determine whether an Epic or release is actually complete across Issues, PRs, checks, deployment, and the live surface.

Do not infer permission to implement from a request that only asks for analysis, planning, visualization, or status.

Apply the source-of-truth order

Use current state in this order:

1. GitHub Issue state and native Parent / dependency metadata when available
2. Open and merged PRs, review state, and required checks
3. The current default branch and repository instructions
4. Deployment state and live verification
5. Repository DAG documents or Mermaid diagrams as human-readable snapshots

Never let a stale local diagram override live GitHub metadata. If the repository encodes dependencies in Issue bodies or labels, identify and follow that convention consistently. Read references/github-operations.md when collecting or mutating GitHub state.

Run the workflow

Run this section only after both entry gates Pass.

1. Establish boundaries

• Read repository AGENTS.md files and relevant planning or operations documents.
• Inspect git status --short, branch, remotes, and current default branch.
• Preserve unrelated dirty work. Use an isolated worktree for parallel or risky implementation when appropriate.
• Clarify the delivery target from available context: requirement, Epic, release, or a named Issue.
• Require every executable Issue to have a bounded outcome, scope, acceptance criteria, and observable dependencies.

If requirements are materially ambiguous, resolve the ambiguity before creating a detailed DAG. Decomposing unclear requirements only multiplies the ambiguity.

2. Inventory live work

Collect the target Epic, child Issues, explicit dependency edges, linked PRs, check status, and any deployment evidence. Detect:

• duplicated or superseded Issues;
• work already present on branches or PRs;
• missing dependency targets;
• self-dependencies and cycles;
• closed Issues whose required upstream work remains open;
• Issue, PR, checklist, default-branch, or deployment state that disagree.

Represent unobservable or conflicting state as invalid or unknown; never silently turn it into ready.

3. Normalize and compute

Create a temporary JSON snapshot using references/snapshot-schema.md, then run:

python3 "<skill-dir>/scripts/dag_queue.py" snapshot.json --format markdown --strict

Use --format json for machine-readable orchestration and --format mermaid for a diagram. The calculator validates references and cycles before classifying work.

Interpret queue states conservatively:

• Ready: open, valid, unclaimed, no active PR or active conflict, and every dependency is Done.
• Claimed: a live executor lease exists for dependency-complete work.
• Stale Claim: the recorded lease expired or was released incompletely; inspect and recover it before reassignment.
• Conflict: dependency-complete work is temporarily unsafe because a declared conflicting Issue is Claimed or in Review.
• Blocked: open and waiting on at least one non-Done dependency.
• Review: implementation exists in a draft/open/merged PR and needs review, checks, merge, or state synchronization.
• Done: the Issue is closed for scheduling purposes.
• Invalid: the graph or recorded state is inconsistent and must be repaired before safe scheduling.

Report Unknown separately when live state could not be observed. Prioritize finishing Review work before starting more Ready work when that reduces work in progress.

4. Plan concurrency

• Treat an independent Codex session as the first-class executor. A Codex subagent is normally a session-local implementation aid, not the cross-session coordination mechanism.
• Assign at most one Ready Issue to each Codex session at a time. A session may use Codex subagents only for bounded work inside its claimed Issue.
• Before work starts, create a visible claim using the repository's established GitHub convention. If none exists, use the lightweight protocol in references/session-operations.md; never rely on chat context alone.
• Give every Codex session its own branch and isolated worktree or clone. Do not run independent sessions in the same mutable checkout.
• Parallelize only Issues whose file, schema, migration, API-contract, and deployment boundaries do not conflict.
• Prefer stable contracts as upstream dependencies; do not force frontend and backend implementations to wait for each other when a reviewed API contract or mock can safely unlock both.
• Keep one Codex session's context centered on one Epic and one atomic Issue.
• Explain why each selected Issue is safe to start and what completing it will unlock.

Do not equate “many sessions or agents running” with DAG scheduling. Parallel work must come from validated dependency, claim, and conflict boundaries.

5. Execute one Ready Issue

Before editing:

1. Restate the Issue goal, allowed scope, dependencies, and acceptance criteria.
2. Confirm that it is still Ready from fresh state.
3. Publish and freshly verify the session's visible claim; stop if another live claim won the race.
4. Identify the isolated worktree, relevant files, conflict boundaries, and checks.

During implementation:

• modify only in-scope files;
• preserve user changes and unrelated assets;
• add or update tests proportional to risk;
• keep migrations, contracts, and shared schemas explicitly coordinated;
• use concise commits and PRs linked to the Issue.

After implementation:

1. Run relevant local checks.
2. Review the diff for scope drift.
3. Push and follow required CI/CD to a terminal state when authorized by the task and repository rules.
4. Verify deployment or the live surface when available.
5. Update or close GitHub objects only when their acceptance criteria are satisfied.
6. Release or replace the claim with the linked PR/delivery state. Do not leave a completed session appearing actively claimed.

Use specialized CI, review-comment, or deployment skills when available; this skill remains responsible for the graph and delivery state.

6. Recalculate after every graph-changing event

Treat claims, claim expiry or takeover, merges, Issue closures or reopenings, dependency edits, failed checks, and deployment failures as scheduling-changing events. Freshly reread live state and recompute the queue after each event.

Do not continue from a cached Ready Queue after any scheduling-changing event.

7. Audit completion

An Epic is not complete merely because its code appears implemented. Verify:

• every required child Issue is closed or explicitly removed from scope;
• dependency metadata and the parent checklist agree;
• linked PRs are merged or intentionally closed;
• required checks are successful;
• changes exist on the intended default branch;
• configured deployment reached a successful terminal state;
• the live URL or delivered surface passes a relevant smoke test when available;
• the readable DAG snapshot is synchronized if the repository maintains one.

Return a compact final report containing the target, queue counts, invalid or unknown state, work completed, newly unlocked work, CI/deployment result, and the next safe action.

Guardrails

• Do not create false dependencies merely to impose a preferred sequence.
• Do not mark blocked work Ready because an upstream implementation “looks nearly done.”
• Do not close an Issue from a PR being open or code existing on a branch.
• Do not treat null, missing fields, API failures, or inaccessible deployments as success.
• Do not modify GitHub metadata or implementation files during queue-only analysis.
• Do not overwrite a live claim. A stale claim permits recovery only after the takeover protocol is recorded and the old branch/PR is inspected.
• Do not infer that a session is inactive merely because it has not replied in the current chat.
• Stop scheduling affected nodes when the graph is invalid; continue read-only diagnosis and identify the exact bad edge or contradictory state.

Bundled resources

• scripts/dag_queue.py: validate a normalized snapshot and emit queue JSON, Markdown, or Mermaid.
• references/snapshot-schema.md: canonical input contract and example.
• references/github-operations.md: live-state collection, mutation, and closeout rules.
• references/session-operations.md: Codex cross-session claim, lease, worktree, recovery, and handoff protocol. Read it whenever two or more independent Codex sessions may work concurrently.