{"id":50412318,"url":"https://github.com/cskwork/codex-goal-handoff","last_synced_at":"2026-05-31T04:04:54.605Z","repository":{"id":356419427,"uuid":"1232430750","full_name":"cskwork/codex-goal-handoff","owner":"cskwork","description":"Turn a ticket into a verified, deployed PR — wraps OpenAI Codex CLI's /goal Ralph loop with a 4-file durable spec, 4 HUMAN GATE approval tokens, and a one-line installer for Claude Code, Codex CLI, and .agents/skills/.","archived":false,"fork":false,"pushed_at":"2026-05-08T00:26:42.000Z","size":33,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-08T02:40:19.945Z","etag":null,"topics":["agent-skills","ai-agents","claude-code","codex-cli","developer-tools","llm-tools","long-horizon-agent","openai-codex","ralph-loop","skill"],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cskwork.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-07T23:35:53.000Z","updated_at":"2026-05-08T00:26:46.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/cskwork/codex-goal-handoff","commit_stats":null,"previous_names":["cskwork/codex-goal-handoff"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/cskwork/codex-goal-handoff","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cskwork%2Fcodex-goal-handoff","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cskwork%2Fcodex-goal-handoff/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cskwork%2Fcodex-goal-handoff/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cskwork%2Fcodex-goal-handoff/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cskwork","download_url":"https://codeload.github.com/cskwork/codex-goal-handoff/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cskwork%2Fcodex-goal-handoff/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33718496,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-31T02:00:06.040Z","response_time":95,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-skills","ai-agents","claude-code","codex-cli","developer-tools","llm-tools","long-horizon-agent","openai-codex","ralph-loop","skill"],"created_at":"2026-05-31T04:04:53.808Z","updated_at":"2026-05-31T04:04:54.600Z","avatar_url":"https://github.com/cskwork.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# codex-goal-handoff\n\n**Turn a ticket into a verified, reviewed, deployed PR — using OpenAI Codex `/goal`.**\n\n- **What you get:** a reproduction script, a scoped fix on a branch, green local + dev verification, an as-is/to-be PDF report, and a posted ticket comment — all from one ticket ID.\n- **What you do:** approve four `APPROVED:Gx` gate tokens (push, merge, deploy, public comment). Everything between gates is autonomous.\n- **What it costs:** one Codex `/goal` token budget (~500k–2M tokens for a typical ticket), and the four gate reviews. No proxy-signal completions: the agent re-runs every Verification command before claiming done.\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](#license)\n[![Codex CLI ≥ 0.128.0](https://img.shields.io/badge/Codex_CLI-%E2%89%A50.128.0-black)](https://developers.openai.com/codex/cli)\n[![Works with Claude Code](https://img.shields.io/badge/Works_with-Claude_Code-D97757)](https://docs.claude.com/en/docs/claude-code)\n[![Works with Codex CLI](https://img.shields.io/badge/Works_with-Codex_CLI-000)](https://developers.openai.com/codex/cli)\n[![Works with .agents/skills](https://img.shields.io/badge/Works_with-.agents%2Fskills-555)](#install)\n\n\u003c/div\u003e\n\n---\n\n## Why this exists\n\nOpenAI's Codex CLI 0.128.0 shipped [`/goal`](https://developers.openai.com/blog/run-long-horizon-tasks-with-codex) — a persistent objective that runs the **Ralph Loop** (Plan → Act → Test → Review → Iterate) until done, paused, or out of budget. It's a real long-horizon agent.\n\nBut raw `/goal` has three problems for production work:\n\n1. **It does not stop on its own** for irreversible actions (push, merge, deploy, externally-visible comments).\n2. **It happily accepts proxy signals** as completion — \"tests should pass,\" \"the fix is in place\" — without running them.\n3. **A short inline goal text gets truncated by mid-turn compaction** ([codex#19910](https://github.com/openai/codex/issues/19910)), so substance has to live in files Codex re-reads every iteration.\n\n`codex-goal-handoff` is a **portable skill** that fixes all three:\n\n- It generates the **four-file durable spec** (`Prompt.md`, `Plan.md`, `Implement.md`, `Documentation.md`) that Codex's docs recommend.\n- It uses the **official Codex objective vocabulary verbatim** — `Scope · Behavior · Non-goals · Verification` at the objective level, `Deliverable · Acceptance · Validation · Stop-and-fix` per milestone.\n- It encodes **HUMAN GATEs** as wait-state milestones whose validation is a literal `grep \"APPROVED:Gx\"` — the loop **cannot** advance without you.\n- It works in **three host environments**: OpenAI Codex CLI standalone, Claude Code, and any agent runtime that reads `~/.agents/skills/`.\n\n## 30-second demo\n\n```text\nYou (in Claude Code):  use codex-goal-handoff to fix PROJ-1234\n\nSkill:  • verifies Codex \u003e= 0.128.0, ChatGPT auth, features.goals=true\n        • fetches the ticket, pastes verbatim text into Prompt.md\n        • renders Plan.md (16 milestones, 4 gates), Implement.md, Documentation.md\n        • hands off:  /codex:rescue Pursue the goal at .codex-goals/PROJ-1234/Prompt.md\n\nCodex:  M1 done · M2 done · M3 reproduces (intentionally fails) · M4 explores ·\n        M5 branch · M6 fix · M7 unit pass · M8 playwright pass · M9 curl pass\n        [paused] G1 — awaiting APPROVED:G1 (push approval)\n\nYou:    [reads diff] APPROVED:G1 — by alice — saw: commit 7f3a1c2\n\nCodex:  M10 push · [paused] G2 ...\n\n[ ... three gates later ... ]\n\nCodex:  Final audit\n        ok V1 git log — 1 commit (PROJ-1234)\n        ok V2 playwright local — exit 0\n        ok V3 playwright dev   — exit 0\n        ok V4 module tests     — exit 0\n        ok V5 screenshots      — both present\n        ok V6 report.pdf       — generated\n        ok V7 four gate tokens — all approved\n        ok V8 ticket comment   — posted (id 8821)\n        Status: complete\n```\n\n## Install\n\n### One-liner (recommended)\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/cskwork/codex-goal-handoff/main/install.sh | bash\n```\n\nThe installer:\n\n- **Detects** which agent-skill parents exist on your machine (`~/.claude/`, `~/.agents/`, `~/.codex/`) and copies the skill into each one's `skills/` subdirectory.\n- **Backs up** any existing copy to `\u003cdir\u003e.bak-\u003ctimestamp\u003e` before overwriting.\n- **Auto-enables** `features.goals = true` in `~/.codex/config.toml` (idempotent; backs up the config first).\n- **Skips** parents that don't exist — no pollution.\n\nPass `--dry-run` to preview, or `--uninstall` to remove all installed copies.\n\n### Paste-into-the-LLM install\n\nDon't want to run a script? Paste this into Claude Code or Codex:\n\n```\nInstall the codex-goal-handoff skill from\nhttps://github.com/cskwork/codex-goal-handoff\n\nSteps:\n  1. git clone https://github.com/cskwork/codex-goal-handoff /tmp/cgh\n  2. bash /tmp/cgh/install.sh\n  3. Confirm `codex login status` shows ChatGPT auth.\n  4. (Claude Code only, optional)\n       /plugin marketplace add openai/codex-plugin-cc\n       /plugin install codex@openai-codex\n  5. Verify with `codex` then `/goal` — should be a known command.\n```\n\n### Manual\n\n```bash\ngit clone https://github.com/cskwork/codex-goal-handoff\ncp -r codex-goal-handoff ~/.claude/skills/      # or ~/.agents/skills/, ~/.codex/skills/\n# enable the feature flag manually:\nprintf '\\n[features]\\ngoals = true\\n' \u003e\u003e ~/.codex/config.toml   # only if [features] section absent\ncodex login   # choose \"Sign in with ChatGPT\"\n```\n\n## How it works\n\n### The four files\n\nEvery long-horizon goal lives in `${WORKDIR}/.codex-goals/\u003cTICKET_ID\u003e/`:\n\n```\n.codex-goals/PROJ-1234/\n├── Prompt.md          frozen objective spec — Scope, Behavior, Non-goals, Verification\n├── Plan.md            milestone table       — Deliverable, Acceptance, Validation, Stop-and-fix, HUMAN_GATE\n├── Implement.md       Ralph-loop runbook    — read-state -\u003e pick-one -\u003e plan -\u003e act -\u003e validate -\u003e decide\n├── Documentation.md   live audit log        — Codex appends; you append APPROVED tokens here\n├── exploration.md     Codex's repo notes (file:line citations)\n├── screenshots/\n│   ├── as-is.png\n│   └── to-be.png\n├── curl/run.sh        API smoke harness\n├── jira-comment.md    draft external comment\n└── report.pdf         final as-is/to-be report\n```\n\n### The vocabulary (official Codex `/goal` terms — used verbatim)\n\n**Objective level** (in `Prompt.md`):\n\n| Term | What it controls |\n|---|---|\n| **Scope** | Exactly which files / modules / surfaces are allowed to change. |\n| **Behavior** | What must be **observably** true after the change (black-box, not implementation). |\n| **Non-goals** | Things the agent must refuse even when convenient. |\n| **Verification** | Concrete shell commands whose green output proves the objective achieved. |\n\n**Milestone level** (every row in `Plan.md`):\n\n| Term | What it controls |\n|---|---|\n| **Deliverable** | The artifact this milestone produces (file, commit, screenshot, build). |\n| **Acceptance criteria** | The observable property the deliverable must have. |\n| **Validation command** | A copy-pasteable `exit-0` shell command proving acceptance. |\n| **Stop-and-fix rule** | What to do on failure: fix root cause; never retry the same milestone more than once. |\n\nThese are **not synonyms we picked.** They are the exact words OpenAI's `/goal` documentation uses, and Codex's internal prompts key off them. Renaming to \"Goals\" or \"Acceptance Tests\" loses alignment with Codex's continuation prompts.\n\n### The Ralph loop, formally\n\n```\n+------------------------------------------------------------------+\n|                                                                  |\n|   1. Read state          (Plan.md -\u003e first non-done row,         |\n|                           Documentation.md -\u003e last 3 entries,    |\n|                           Prompt.md sections 2-5)                |\n|   2. Pick ONE milestone                                          |\n|   3. Plan the action     (write 1-5 bullets to Documentation.md) |\n|   4. Act                 (smallest change producing Deliverable) |\n|   5. Validate            (run Validation command; capture output)|\n|   6. Decide:                                                     |\n|        green -\u003e Status=done -\u003e loop                              |\n|        first  fail -\u003e diagnose, edit once, re-validate           |\n|        second fail -\u003e Status=blocked, /goal pause                |\n|        gate        -\u003e Status=awaiting_approval, /goal pause      |\n|                                                                  |\n+------------------------------------------------------------------+\n```\n\n### The four HUMAN GATEs\n\nThe canonical workflow ships with four wait-states. Each one's Validation is a literal `grep \"APPROVED:Gx\" Documentation.md` — Codex cannot advance until you write the token.\n\n| Gate | Guards | What you review |\n|---|---|---|\n| **G1** | `git push` to remote | `git diff base..HEAD`, commit messages |\n| **G2** | merge feature into integration branch | full PR diff, CI status, teammate comments |\n| **G3** | trigger CI/CD deploy | integration-branch tip SHA — make sure no surprise commit is riding along |\n| **G4** | post the externally-visible ticket comment | the draft comment Codex wrote to `jira-comment.md` |\n\nYou write `APPROVED:G2 — by alice — saw: PR #321 green` to `Documentation.md` and `/goal resume`. Or `REJECTED:G2 — reason: ...` and the milestone goes `blocked`.\n\n## Customizing for your repo\n\nThe shipped workflow (`workflows/jira-bug-fix.md`) targets the most common case: a ticketed bug, Playwright reproduction, branch/fix/merge, CI-system deploy, browser re-verify, PDF, comment.\n\nTo adapt:\n\n1. **Point at your ticket system.** Set `{{TICKET_PROVIDER}}` to `jira` / `linear` / `github` / `asana`. The skill picks the right MCP / CLI for M1 (fetch) and M15 (comment).\n2. **Point at your CI.** Fill `{{CI_DEPLOY_TRIGGER}}` and `{{CI_DEPLOY_POLL}}` with the right Jenkins / GitHub Actions / GitLab / CircleCI commands. `workflows/jira-bug-fix.md` has copy-pasteable snippets for the common four.\n3. **Point at your test runner.** Fill `{{LOCAL_TEST_CMD}}` and `{{LOCAL_START_CMD}}`. Examples for Spring Boot / pnpm / npm / pytest / Go / Cargo are in `workflows/jira-bug-fix.md`.\n4. **Adjust scope.** Edit `Prompt.md §2 Scope -\u003e Allowed module(s)` to point at your service tree.\n\nFor workflows other than bug-fix, see `workflows/README.md` — the rules for authoring your own workflow on top of the same four-file model.\n\n## How this differs from raw `/goal`\n\n| | Raw `/goal` | `codex-goal-handoff` |\n|---|---|---|\n| Objective vocabulary | Free-form prose | **Scope / Behavior / Non-goals / Verification** template |\n| Milestone structure | Implicit | Explicit table with **Deliverable / Acceptance / Validation / Stop-and-fix** columns |\n| Compaction safety | Inline goal can be truncated | Substance lives in files re-read every iteration |\n| Stops on irreversible actions | No | Yes — explicit `APPROVED:Gx`-token gates |\n| Stops on proxy signals | No | Yes — Final audit must re-run every Verification command |\n| Cross-host portability | Codex CLI only | Codex CLI + Claude Code + `.agents/skills/` |\n| Ticket-system handoff | Manual | M1 / M15 / G4 wired |\n| CI/CD deploy gating | Manual | G3 + M12 wired (Jenkins / GH Actions / GitLab examples) |\n\n## FAQ\n\n**Does this require a ChatGPT subscription?**\nYes — `/goal`'s persistence layer is tied to ChatGPT account auth. API-key auth does not enable goals. (`codex login status` should print \"ChatGPT\".)\n\n**Does it work without Claude Code?**\nYes. Run `install.sh` (or the manual steps), then use `codex` directly: `codex` then `/goal pursue the goal at .codex-goals/\u003cid\u003e/Prompt.md`. The skill files are pure markdown — no host-specific runtime.\n\n**Why four files instead of one big prompt?**\nBecause Codex 0.128.0 has a known mid-turn compaction bug ([codex#19910](https://github.com/openai/codex/issues/19910)) where a long inline goal can lose its continuation prompt. Putting substance in files Codex re-reads on each iteration is the documented mitigation.\n\n**What if my repo's branch convention isn't `main`/`develop`?**\nSet `{{BASE_BRANCH}}` and `{{INTEGRATION_BRANCH}}` to whatever your team uses. The skill's templates are 100% placeholders — there are no hard-coded names.\n\n**Can I add a fifth gate?**\nYes. Add a `**Gx**` row to `Plan.md` whose Deliverable is `(gate) ...` and whose Validation is `grep -F \"APPROVED:Gx\" Documentation.md`. Done.\n\n**Does it work for features, not just bugs?**\nYes — set `TICKET_TYPE=feat` and adjust `workflows/jira-bug-fix.md` (or write a new workflow file). The four-file model is workflow-agnostic.\n\n**Why not just use `/work` + `/verify` skills?**\nThose are great for short-horizon work in a single Claude Code session. `/goal` is for tasks that outlive a session and need persistence + budget control + automatic resumption after compaction. Different tool for a different job — they compose well.\n\n## Compatibility\n\n- **Codex CLI:** ≥ 0.128.0 (first `/goal` release)\n- **ChatGPT auth required** (not API-key auth)\n- **Skill hosts:** Claude Code (`~/.claude/skills/`), `.agents/skills/`-compatible runtimes, Codex CLI (`~/.codex/skills/`)\n- **OS:** macOS, Linux, WSL. Windows native: install.sh runs under Git Bash.\n\n## Contributing\n\nPRs welcome. Areas where help is most appreciated:\n\n- More CI-system snippets for `workflows/jira-bug-fix.md` (Buildkite, TeamCity, Bitbucket Pipelines)\n- More `{{LOCAL_TEST_CMD}}` examples for less-common stacks\n- New workflow files (`workflows/feat-implementation.md`, `workflows/dependency-upgrade.md`, `workflows/migration.md`)\n- Translations of `SKILL.md` and `README.md`\n\nWhen proposing a workflow, follow `workflows/README.md` — the rules for keeping the official vocabulary intact.\n\n## License\n\nMIT. See `LICENSE`.\n\n## Acknowledgements\n\n- OpenAI for shipping [`/goal`](https://developers.openai.com/blog/run-long-horizon-tasks-with-codex) and the [codex-plugin-cc bridge](https://github.com/openai/codex-plugin-cc).\n- Anthropic for [Claude Code](https://docs.claude.com/en/docs/claude-code) and its skill system.\n- Everyone who wrote about the Ralph Loop pattern early — particularly [Simon Willison's writeup](https://simonwillison.net/2026/Apr/30/codex-goals/).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcskwork%2Fcodex-goal-handoff","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcskwork%2Fcodex-goal-handoff","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcskwork%2Fcodex-goal-handoff/lists"}