codex-task-dispatch

name	codex-task-dispatch
description	Use when a repository needs ChatGPT web planning converted into reviewable Codex task packets, GitHub task storage, or one-PR-at-a-time local Codex execution.

Codex Task Dispatch

Use this skill to turn a broad product request into a controlled local-execution pipeline:

ChatGPT web planner
-> PRD + technical design + work plan
-> independent Codex task packets
-> GitHub docs or GitHub Issue task store
-> local Codex App / CLI execution
-> one PR per task
-> review + merge
-> next task

Core Rules

1. Put the workflow in the target code repository, not a random queue repo, unless the user explicitly asks for a central orchestration repo.
2. Resolve the target repository from explicit user input or current git evidence before writing plans. Never use a hard-coded personal project default.
3. Make the target repository's agent.md / AGENTS.md the highest execution contract after the current user request.
4. If local path, GitHub remote, base branch, or authority docs conflict, stop and ask for clarification instead of guessing.
5. Do not dispatch implementation before the PRD, technical design, work plan, and task packet are written or attached.
6. Split tasks into PR-sized units that Codex can complete independently.
7. Run one dependent task at a time. Start the next task only after the previous task's PR is reviewed, approved, merged, and the base branch is updated.
8. Include frontend, backend, database, docs, tests, hooks, provider, permission, and deployment boundaries in the plan when they are relevant.
9. Keep secrets out of prompts, issues, logs, and task packets.
10. Real provider smoke must stay separate from default deterministic tests unless the project contract explicitly says otherwise.
11. When the user wants the workflow installed in a repository, use scripts/scaffold_codex_dispatch.py to create the reusable GitHub task-store and local Codex execution files before hand-editing project-specific details.

Public Distribution And Privacy

This skill is intended to be reusable across projects and safe to publish.

• Do not store personal absolute paths, private IP addresses, private repository names, API hosts, usernames, tokens, cookies, browser history, or credentials in the skill or generated templates.
• Use placeholders such as <owner/repo>, <local-repo>, <base-branch>, and <epic-slug> in reusable docs.
• Before publishing or sharing this skill, run a local sensitive-string scan over the skill directory.
• ChatGPT web prompts must contain only the minimum project context needed for planning. Replace secrets and private data with redacted placeholders.
• If the user asks to send repository context to ChatGPT web, send public or low-sensitive planning context by default; ask again before sending credentials, private personal files, private customer data, or raw provider prompts.

Workflow

1. Resolve Target Repository

Resolve in this order:

1. Use explicit user input if provided:
   • GitHub owner/repo
   • local checkout path
   • base branch
   • target branch policy
   • whether tasks should open PRs or push directly
2. Otherwise inspect the current working directory:
   • git rev-parse --show-toplevel
   • git remote get-url origin
   • git symbolic-ref --short refs/remotes/origin/HEAD
   • git branch --show-current
3. Identify repository authority docs, preferring files that actually exist:
   • agent.md
   • AGENTS.md
   • CLAUDE.md
   • README.md
   • project architecture docs referenced by the repo itself
4. Stop and ask if more than one repository is plausible, no git remote exists, the base branch cannot be inferred, or the user-provided target conflicts with git evidence.

Never silently fall back to a named project, personal path, or assumed base branch.

2. Generate Planning Package

Use references/chatgpt-planner-template.md for the ChatGPT web prompt.

The planning package must include:

• PRD
• technical architecture document
• frontend plan
• backend/API plan
• data/storage plan
• testing and verification plan
• hook/boundary plan
• rollout and merge plan
• task breakdown with dependencies
• PR acceptance criteria

3. Convert Plan Into Codex Task Packets

Use references/codex-task-packet-template.md.

Each packet must include:

• task id and PR title
• dependency on previous task, if any
• allowed write set
• forbidden write set
• frontend/backend/docs/test changes
• exact source docs Codex must read first
• TDD or cheapest-verification steps
• review checklist
• merge criteria
• not-verified list

4. Create GitHub Task Store

Use references/github-dispatch-template.md for the GitHub storage and local execution shape.

Prefer:

docs/codex/epics/<epic>/... or GitHub Issue -> local Codex App / CLI -> branch -> PR

Use GitHub Actions only when the user explicitly asks for cloud execution. The default skill path is local execution.

To scaffold the task-store side in any repository:

python <skill>/scripts/scaffold_codex_dispatch.py --repo <local-repo>

The script infers owner/repo and base branch from git when possible. Pass --owner-repo <owner/repo> or --base-branch <branch> only when inference is wrong or unavailable. It writes only docs and prompt templates. It skips existing files by default, does not create GitHub Actions, does not configure secrets, and does not enable auto-merge.

5. Execute One PR At A Time

For each task:

1. Store only the next unblocked task in docs/codex/epics/<epic>/tasks/ or a GitHub Issue.
2. Local Codex reads agent.md, PRD, technical design, work plan, and the task packet.
3. Local Codex creates codex/<task-slug> branch.
4. Codex implements the task within the allowed write set.
5. Codex runs the task's verification ladder.
6. Local Codex opens a PR with source evidence, verification, not-verified items, and risk notes.
7. Codex Cloud, local codex review, or a human reviewer approves or requests changes.
8. Local Codex addresses review feedback.
9. Merge the PR to base.
10. Pull/update base before dispatching the next task.

Do not start downstream PRs from stale base.

6. Finish The Epic

After all task PRs merge:

• verify base branch is up to date
• run the aggregate verification ladder
• update final PRD/architecture/work-plan status
• record remaining manual-required items
• push final docs sync if needed

Output Shape

When asked to design this flow, return:

1. where files should live
2. ChatGPT planner prompt
3. GitHub task-store shape and local execution prompt
4. task packet schema
5. PR sequence
6. security notes
7. first concrete next action

Keep the response grounded in the current repository and never claim ChatGPT has written GitHub files, Codex Cloud has reviewed a PR, or a PR has merged until those actions actually happened.

Publish Checklist

Before pushing this skill to a public GitHub repository:

rg -n "Users\\\\|C:\\\\|D:\\\\|E:\\\\|token|secret|password|api[_-]?key|Authorization|cookie|private|PRIVATE|[0-9]{1,3}(\\.[0-9]{1,3}){3}" <skill-dir>
python <skill-dir>/scripts/scaffold_codex_dispatch.py --repo <target-repo> --dry-run

The first command should show only generic safety warnings or no matches. The dry run must infer or explicitly receive the target repository without writing files.