Project Task Dispatch

Project Task Dispatch 2.0

Overview

The current Base Graph task is the Manager Session. It distributes work to independent, user-visible Project Worker Sessions bound to the saved Codex Project for each repository. Optional Reviewer Sessions provide independent read-only review. These are peer Codex tasks connected by a PDC Dispatch; they are not Agent Team Subagents and do not inherit the Manager conversation.

The user normally interacts only with the Manager. The Manager owns routing, dependency unlock, native task monitoring, findings, repository verification, approval, the status view, and lifecycle cleanup.

When to Use

Use this skill when a user asks to send or split work across PDC Projects, repositories, tasks, chats, or Sessions, including:

• a lightweight hello, notification, or connectivity check;
• an awaited cross-project query or research task;
• a confirmed cross-project design or contract;
• managed implementation, tests, review, and local commits across repositories;
• recovery, monitoring, rework, or closure of an existing PDC Dispatch.

Do not use it for work contained in one Project, ordinary PDC development in the current checkout, generic non-project research, or Agent Team delegation.

Mandatory References

For every run, read routing.md. For awaited Dispatch or Managed Development, also read these completely:

• task-control-plane.md
• manager-runtime.md
• manifest-v2.md

For formal packages read task-package-protocol.md. For Managed Development read development-receipt.md, whose retained filename now describes delivery and Review rather than a progress receipt. For the default live status display read dashboard-runtime.md.

1. Select Mode and Complexity

Choose the mode from user intent; do not force an A/B question when intent is clear.

Mode is selected from the work lifecycle, not from words such as "dispatch", "send", or "create", and not from estimated duration. Apply this precedence:

1. If the user makes an explicit delivery-only request such as "create the tasks and stop; do not wait or review", use Dispatch even when a Worker will write code.
2. Otherwise, if any Worker is authorized to modify project files, run tests or builds, create a local commit, or produce a result the Manager must accept, use Managed Development. This does not require the user to say "monitor" or "dashboard" explicitly.
3. Otherwise, if the user needs read-only results returned or aggregated, use Awaited Dispatch.
4. Otherwise use Dispatch.

Short confirmations such as "confirm", "continue", or "execute" inherit the work lifecycle already established by the conversation. If material ambiguity remains, ask only about the missing lifecycle expectation; do not silently interpret missing monitoring words as delivery-only authorization.

Before the first create_thread, complete a mode gate that records the selected mode, the write/read-only boundary, whether results require Manager acceptance, and the user's explicit delivery-only instruction when one exists. For Managed Development, also create and render the Revision 1 control plane and HTML dashboard first, with Project Sessions UNBOUND and work items READY or WAITING_DEPENDENCY. Start the dashboard and verify client acknowledgement; then create Workers, bind their native identities, assign ready work, and publish the next revision. Worker creation before this gate is a routing error.

Common mode rationalizations:

Stop before create_thread if the mode gate is missing, writable work was classified from wording alone, or Managed Development has no acknowledged Revision 1 dashboard. Correct the control plane first; do not retrofit it after Worker creation.

Use a lightweight readable prompt for hello/notification/simple isolated work. Use the three-document formal package only for shared contracts, dependencies, frozen responsibilities, or substantial development. A lightweight Dispatch does not need a management directory. Awaited Dispatch and Managed Development use manifest v2 when coordination state must survive the current turn.

The user command to distribute/create/send is authorization to create the resolved native tasks. Do not add another confirmation gate. In dry-runs, evals, or previews, never create a real Codex task.

2. Resolve Exact Saved Projects

Use Base Graph repository identity/root plus list_projects projectId/path/host. Normalize paths and require exactly one corroborated saved Project. Never route by label alone.

Writable work requires VERIFIED_CODEX_PROJECT. If the repository path exists but no exact saved Project exists, record a PROJECT_ROUTE blocker and do not create a path-fallback Worker in the Base Graph Project. BASE_PATH_FALLBACK is allowed only for an explicitly accepted READ_ONLY task and must carry readOnlyFallback=true; it cannot later become writable.

For every repository record its own expectedBranch, baselineHead, and dirtyBoundary. Never assume all repositories use the same branch name. Do not create/switch branches or worktrees and do not merge, rebase, reset, push, or clean pre-existing changes unless separately authorized.

3. Build the PDC Control Plane

For Managed Development, create:

<PDC_RUNTIME_ROOT>/<realityProjectId>/dispatches/<dispatchId>/
├─ manifest.json
├─ runtime-cache.json
├─ manager.md
├─ notes.md
├─ project-sessions/<projectSessionKey>/session.md
├─ work-items/<taskId>.md
├─ findings/<findingId>.md
└─ views/
   ├─ live/{index.html,snapshot.json,assets/,server-state.json}
   └─ {current-status,status-rNNNN}.{svg,png}

The Manager is the only writer. manifest.json owns PDC business state; Codex owns native task/turn state; Git owns code facts; runtime-cache.json owns only replaceable cursor/snapshot observations. The directory is not a message queue. Human edits are limited to notes.md.

Use one write Project Worker Session per saved Project per Dispatch. Several work items in that Project map to the same projectSessionKey and run as serial batches. Independent Projects may run in parallel. Downstream work unlocks only after required upstream work is APPROVED, not merely after Worker final.

4. Create and Bind Project Sessions

Discover and use the native tools list_projects, create_thread, wait_threads, read_thread, send_message_to_thread, set_thread_title, set_thread_pinned, set_thread_archived, list_threads, and list_archived_threads. Use navigate_to_codex_page only when the user asks to open a task.

Create each Worker with this exact route shape:

target.type = project
target.projectId = <verified projectId>
target.environment.type = local
title = [PDC][<dispatchId>][<repo>][Worker|Reviewer] <short goal>
prompt = readable complete assignment

PDC Managed Development uses the user's established explicit local checkout policy so each repository keeps its own current branch and existing dirty boundary. If this Skill is used where that direct-checkout authorization has not been established, obtain it before overriding Codex's normal Git-project worktree default.

Omit model/thinking unless the user explicitly selected them. Use worker-initial-message.md for Managed Development. Tell the Worker to use its local Project PDC context and not to create a nested Session/Subagent unless authorized.

create_thread is asynchronous:

• ready result: save threadId + hostId, binding=BOUND;
• queued result: save only clientThreadId, binding=CREATE_PENDING;
• never pass clientThreadId to wait/read/send and never repeat create merely because pending has no threadId;
• after every successful native creation, show the native created-task entry in the Manager response.

5. Monitor and Communicate

For bound unapproved Sessions, use wait_threads in groups of 1–8 with each target's hostId and cached afterCursor. Prefer 30–60 second bounded waits in an active Manager turn. Update runtime cache on snapshots. Do not emit another Manager panel for an unchanged timeout.

Normal Worker commentary is human-readable and does not need JSON. Deep-read with read_thread at completion, attention, error, or Review boundaries. Leave native permission/input requests for the user. A Worker final produces a delivery candidate and can move a work item only to SUBMITTED.

Use send_message_to_thread for the next batch or Review findings. Rework goes to the original Worker threadId; do not fork or replace it. Sending a message is not a hard mid-turn interrupt. The current high-level API can stop future scheduling but cannot guarantee immediate interruption of a running turn.

Use a recurring heartbeat only when the user explicitly requests monitoring after the Manager turn ends. Create/update it with native automation_update, targeting the Manager thread, and stop it when the Dispatch becomes terminal.

6. Review, Rework, and Approval

Managed Development follows this non-bypassable sequence:

Worker final → SUBMITTED → REVIEWING → APPROVED
                                  └→ CHANGES_REQUESTED → same Worker → SUBMITTED

The Manager verifies repository root, branch, baseline/final HEAD, dirty-file boundary, changed files, local commit, actual test results, acceptance IDs, contract revision, dependency approval, open findings, and cross-repository side effects. SUBMITTED → APPROVED is forbidden. Native idle/final and the word “completed” are not approval evidence.

Use open_in_codex to show branch/unstaged/staged/last-turn Review in the current Codex window when that makes human verification easier; it is a view, not the evidence authority.

Use a read-only Reviewer Session for inaccessible repositories, higher-risk changes, or user-required independent review. Run it after the write Worker is idle. Findings must include severity, evidence, required change, and a file/line, contractId, or acceptanceId where applicable. Send findings with worker-rework-message.md.

Normal changes require project-local tests and a local commit; never push. NO_CHANGE_REQUIRED may be submitted without an empty commit but still requires evidence and explicit Manager approval. Do not run broad cross-project tests by default; the final cross-repository check validates agreed contracts and declared integration evidence.

7. Status View and Lifecycle

After every meaningful manifest change, increment revision atomically and regenerate manager.md, Session/work-item/finding Markdown, and the static HTML projection in views/live/. Start or recover the PDC-owned loopback runtime with scripts/dashboard_runtime.py start --dispatch-root <path> after Revision 1; it opens the Windows default external browser unless the user selected the Codex in-window mode. Use reopen when the user asks to open the existing board again. Judge visibility from the client acknowledgement, not process launch.

The dashboard is read-only and fixed to Manager 1 → Project Sessions N → Manager final 1. WebSocket revision notifications update it live; JSON polling is the reconnect fallback and the generated HTML remains a readable static snapshot when the server is unavailable. It must show PDC state and native Codex state separately. A display/runtime failure never blocks dispatch or Review.

HTML is the default display. Do not generate SVG/PNG on every revision; render an image only when the user asks for an inline/exported artifact or when HTML cannot be opened and an in-conversation visual is useful. Markdown remains the final universal fallback. Use open_in_codex only for a user-selected in-window dashboard or code Review; treat queued as not yet visibly opened.

Do not pin or archive created Worker/Reviewer tasks by default. Creation, approval, and Dispatch close leave their native pin/archive state untouched and keep real development and read-only Sessions visible. Call set_thread_pinned or set_thread_archived only when the user explicitly asks for that specific lifecycle action. Archive is lifecycle cleanup, not cancellation, and CLOSED never implies pinned, unpinned, or archived.

8. Recovery and Idempotency

On resume, load and validate manifest revision, then reconcile saved Projects, Git baselines, and task bindings. Use list_threads and list_archived_threads, matching only durable threadId; title is display metadata and must not auto-bind a task. Rebuild deleted runtime cache using read_thread plus wait_threads(timeoutMs=0).

Do not recreate CREATE_PENDING Sessions automatically. Mark a missing bound thread as MISSING, surface it, and require an explicit recovery decision. Persist cursors so a repeated final cannot repeat a reducer transition.

9. Formal Package Compatibility

Keep the existing UTF-8/LF/checksum/chunk protocol. The transport manifest is named task-package-manifest.json; the Dispatch control file is manifest.json. The initial prompt must start with a readable parent-child title, never a protocol marker. A formal package carries shared contracts and that Project's responsibility, while local code knowledge comes from the target Project PDC.

New v2 Workers never receive the 1.x receipt-first progress contract. The compatibility parser in scripts/legacy_receipt.py is only for restoring an already-active 1.x run, and legacy COMPLETED maps to a v2 delivery candidate, never directly to APPROVED.

Completion

Dispatch completes after delivery. Awaited Dispatch completes after requested results are returned. Managed Development completes only when every required work item is APPROVED, the final cross-repository check passes, generated views match the manifest revision, and lifecycle actions requested by policy succeed.

Report the outcome, approved/blocked work, Review findings, verification evidence, and current in-window status view. Do not claim hard interruption, approval, or cross-project completion without direct evidence.