{"id":47680058,"url":"https://github.com/shinpr/codex-workflows","last_synced_at":"2026-04-15T05:02:49.918Z","repository":{"id":345891880,"uuid":"1184212122","full_name":"shinpr/codex-workflows","owner":"shinpr","description":"Structured agentic coding workflows for OpenAI Codex CLI with specialized AI subagents, planning, and quality gates.","archived":false,"fork":false,"pushed_at":"2026-04-06T11:57:48.000Z","size":334,"stargazers_count":6,"open_issues_count":1,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-06T13:32:55.149Z","etag":null,"topics":["agent-skills","agentic-coding","ai-coding","ai-coding-agent","code-generation","code-quality","codex","codex-cli","context-engineering","development-workflow","multi-agent","openai","subagents","tdd"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/shinpr.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-03-17T11:13:57.000Z","updated_at":"2026-04-06T11:56:14.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/shinpr/codex-workflows","commit_stats":null,"previous_names":["shinpr/codex-workflows"],"tags_count":18,"template":false,"template_full_name":null,"purl":"pkg:github/shinpr/codex-workflows","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shinpr%2Fcodex-workflows","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shinpr%2Fcodex-workflows/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shinpr%2Fcodex-workflows/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shinpr%2Fcodex-workflows/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shinpr","download_url":"https://codeload.github.com/shinpr/codex-workflows/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shinpr%2Fcodex-workflows/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31826907,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-14T18:05:02.291Z","status":"online","status_checked_at":"2026-04-15T02:00:06.175Z","response_time":63,"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","agentic-coding","ai-coding","ai-coding-agent","code-generation","code-quality","codex","codex-cli","context-engineering","development-workflow","multi-agent","openai","subagents","tdd"],"created_at":"2026-04-02T13:56:32.323Z","updated_at":"2026-04-15T05:02:49.897Z","avatar_url":"https://github.com/shinpr.png","language":"JavaScript","readme":"# codex-workflows\n\n[![Codex CLI](https://img.shields.io/badge/Codex%20CLI-Compatible-10a37f)](https://developers.openai.com/codex/cli)\n[![Agent Skills](https://img.shields.io/badge/Agent%20Skills-Spec%20Compliant-blue)](https://developers.openai.com/codex/skills/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n**Structured agentic coding workflows for [OpenAI Codex CLI](https://developers.openai.com/codex/cli)** — specialized AI coding agents plan, implement, test, and review changes with traceable docs, task-level commits, and quality gates.\n\nBuilt on the [Agent Skills specification](https://developers.openai.com/codex/skills/) and [Codex subagents](https://developers.openai.com/codex/subagents). Designed for long-running tasks, large refactors, and reviewable changes.\n\n---\n\n## Quick Start\n\n```bash\ncd your-project\nnpx codex-workflows install\n```\n\nThen in Codex CLI:\n\n```\n$recipe-implement Add user authentication with JWT\n```\n\n`$` is Codex CLI's syntax for invoking a skill explicitly. Type `$recipe-` to see all available recipes via tab completion.\n\nSmall changes stay lightweight. Larger tasks get structure: requirements → design → task decomposition → TDD implementation → quality gates.\n\ncodex-workflows is the Codex-native counterpart of [Claude Code Workflows](https://github.com/shinpr/claude-code-workflows): same document-driven development style, adapted for Codex CLI, subagents, and GPT models.\n\n---\n\n## Why codex-workflows?\n\nCodex is already strong at one-shot implementation. The problem starts when a change spans multiple files, needs design decisions to stay visible, or has to survive review, testing, and follow-up edits.\n\nFor larger tasks, explicit planning changes the job from raw generation into verification against a design, a task breakdown, and acceptance criteria. That matters because review loops are more reliable than first-shot generation once scope and ambiguity grow.\n\ncodex-workflows adds the missing structure around those jobs:\n- Traceable artifacts: PRD → Design Doc → Task → Commit\n- Built-in TDD and quality gates before code is ready to commit\n- Agent context separation for large refactors, migrations, and PR-sized changes\n- Diagnosis and reverse-engineering flows for bugs and legacy code\n\n## Not Designed For\n\n- One-shot toy scripts or vibe-coding sessions where speed matters more than traceability\n- Repositories that do not use tests, lint, builds, or reviewable commits\n- Teams that do not want design docs, task breakdowns, or explicit quality gates\n\n---\n\n## What It Does\n\nA single request becomes a structured development process. The framework chooses the level of ceremony based on scope:\n\n| Scale | File Count | What Happens |\n|-------|------------|-------------|\n| Small | 1-2 | Simplified plan → direct implementation |\n| Medium | 3-5 | Design Doc → work plan → task execution |\n| Large | 6+ | PRD → ADR → Design Doc → test skeletons → work plan → autonomous execution |\n\nFor larger work, the path usually looks like this: understand the problem, analyze the codebase, design the change, break it into atomic tasks, implement with tests, and run quality checks before commit.\n\nEach step is handled by a specialized subagent in its own context, using context engineering to prevent context pollution and reduce error accumulation in long-running tasks:\n\n```\nUser Request\n    ↓\nrequirement-analyzer  →  Scale determination (Small / Medium / Large)\n    ↓\nprd-creator           →  Product requirements (Large scale)\n    ↓\ncodebase-analyzer     →  Existing codebase facts + focus areas\n    ↓\ntechnical-designer    →  ADR + Design Doc with acceptance criteria\n    ↓\ncode-verifier         →  Design Doc vs existing code verification\n    ↓\ndocument-reviewer     →  Quality gate with verification evidence\n    ↓\nacceptance-test-gen   →  Test skeletons from ACs\n    ↓\nwork-planner          →  Phased execution plan\n    ↓\ntask-decomposer       →  Atomic tasks (1 task = 1 commit)\n    ↓\ntask-executor         →  TDD implementation per task\n    ↓\nquality-fixer         →  Lint, test, build — no failing checks\n    ↓\nReady to commit\n```\n\n### The Diagnosis Pipeline\n\n```\nProblem → investigator → verifier (ACH + Devil's Advocate) → solver → Actionable solutions\n```\n\n### Reverse Engineering\n\n```\nExisting code → scope-discoverer (discoveredUnits + prdUnits) → prd-creator → code-verifier → document-reviewer → Design Docs\n```\n\nThis works best when repository knowledge is explicit and local. Short `AGENTS.md` files can act as entry points, while design docs, plans, and task files hold the deeper instructions that agents need to execute reliably.\n\n---\n\n## Installation\n\n### Requirements\n\n- [Codex CLI](https://developers.openai.com/codex/cli) (latest)\n- Node.js \u003e= 22\n\n### Install\n\n```bash\ncd your-project\nnpx codex-workflows install\n```\n\nThis copies into your project:\n- `.agents/skills/` — Codex skills (foundational + recipes)\n- `.codex/agents/` — Subagent TOML definitions\n- Manifest file for tracking managed files\n\n### Update\n\n```bash\n# Preview what will change\nnpx codex-workflows update --dry-run\n\n# Apply updates\nnpx codex-workflows update\n```\n\nFiles you've modified locally are preserved — the updater compares each file against its hash at install time and skips any file you've changed. New files from the update are added automatically.\n\n```bash\n# Check installed version\nnpx codex-workflows status\n```\n\n---\n\n## Recipe Workflows\n\nInvoke recipes with `$recipe-name` in Codex. Type `$recipe-` and use tab completion to see all available recipes.\n\n### Backend \u0026 General\n\n| Recipe | What it does | When to use |\n|--------|-------------|-------------|\n| `$recipe-implement` | Full lifecycle with layer routing (backend/frontend/fullstack) | New features — universal entry point |\n| `$recipe-task` | Single task with rule selection | Bug fixes, small changes |\n| `$recipe-design` | Requirements → ADR/Design Doc | Architecture planning |\n| `$recipe-plan` | Design Doc → test skeletons → work plan | Planning phase |\n| `$recipe-build` | Execute backend tasks autonomously | Resume backend implementation |\n| `$recipe-review` | Design Doc compliance and security validation with auto-fixes | Post-implementation check |\n| `$recipe-diagnose` | Problem investigation → verification → solution | Bug investigation |\n| `$recipe-reverse-engineer` | Generate PRD + Design Docs from existing code | Legacy system documentation |\n| `$recipe-add-integration-tests` | Add integration/E2E tests from Design Doc | Test coverage for existing code |\n| `$recipe-update-doc` | Update existing Design Doc / PRD / ADR with review | Spec changes, document maintenance |\n\n### Frontend (React/TypeScript)\n\n| Recipe | What it does | When to use |\n|--------|-------------|-------------|\n| `$recipe-front-design` | Requirements → UI Spec → frontend Design Doc | Frontend architecture planning |\n| `$recipe-front-plan` | Frontend Design Doc → test skeletons → work plan | Frontend planning phase |\n| `$recipe-front-build` | Execute frontend tasks with RTL + quality checks | Resume frontend implementation |\n| `$recipe-front-review` | Frontend compliance and security validation with React-specific fixes | Frontend post-implementation check |\n\n### Fullstack (Cross-Layer)\n\n| Recipe | What it does | When to use |\n|--------|-------------|-------------|\n| `$recipe-fullstack-implement` | Full lifecycle with separate Design Docs per layer | Cross-layer features |\n| `$recipe-fullstack-build` | Execute tasks with layer-aware agent routing | Resume cross-layer implementation |\n\n### Examples\n\n**Full feature development:**\n```\n$recipe-implement Add user authentication with JWT and role-based access control\n```\n\n**Quick fix with proper rule selection:**\n```\n$recipe-task Fix validation error message in checkout form\n```\n\n**Investigate a bug:**\n```\n$recipe-diagnose API returns 500 error on user login after deployment\n```\n\n**Document undocumented legacy code:**\n```\n$recipe-reverse-engineer src/auth module\n```\n\n---\n\n## Foundational Skills\n\nThese load automatically when the conversation context matches — no explicit invocation needed:\n\n| Skill | What it provides |\n|-------|-----------------|\n| `coding-rules` | Code quality, function design, error handling, refactoring |\n| `testing` | TDD Red-Green-Refactor, test types, AAA pattern, mocking |\n| `ai-development-guide` | Anti-patterns, debugging (5 Whys), quality check workflow |\n| `documentation-criteria` | Document creation rules and templates (PRD, ADR, Design Doc, Work Plan) |\n| `implementation-approach` | Strategy selection: vertical / horizontal / hybrid slicing |\n| `integration-e2e-testing` | Integration/E2E test design, ROI calculation, review criteria |\n| `task-analyzer` | Task analysis, scale estimation, skill selection |\n| `subagents-orchestration-guide` | Multi-agent coordination, workflow flows, autonomous execution |\n\nLanguage-specific references are included for TypeScript/React projects (`coding-rules/references/typescript.md`, `testing/references/typescript.md`).\n\n---\n\n## Subagents\n\nCodex spawns these as needed during recipe execution. Each agent runs in its own context with specialized instructions and skill configurations.\n\n### Document Creation Agents\n\n| Agent | Role |\n|-------|------|\n| `requirement-analyzer` | Requirements analysis and work scale determination |\n| `prd-creator` | PRD creation and structuring |\n| `technical-designer` | ADR and Design Doc creation (backend) |\n| `technical-designer-frontend` | Frontend ADR and Design Doc creation (React) |\n| `ui-spec-designer` | UI Specification from PRD and optional prototype code |\n| `codebase-analyzer` | Existing codebase analysis before Design Doc creation |\n| `work-planner` | Work plan creation from Design Docs |\n| `document-reviewer` | Document consistency and approval |\n| `design-sync` | Cross-document consistency verification |\n\n### Implementation Agents\n\n| Agent | Role |\n|-------|------|\n| `task-decomposer` | Work plan → atomic task files |\n| `task-executor` | TDD implementation following task files (backend) |\n| `task-executor-frontend` | React implementation with Testing Library |\n| `quality-fixer` | Quality checks and fixes until all pass (backend) |\n| `quality-fixer-frontend` | React-specific quality checks (TypeScript, RTL, bundle) |\n| `acceptance-test-generator` | Test skeleton generation from acceptance criteria |\n| `integration-test-reviewer` | Test quality review |\n\n### Analysis Agents\n\n| Agent | Role |\n|-------|------|\n| `code-reviewer` | Design Doc compliance validation |\n| `code-verifier` | Document-code consistency verification |\n| `security-reviewer` | Security compliance review after implementation |\n| `rule-advisor` | Skill selection via metacognitive analysis |\n| `scope-discoverer` | Codebase scope discovery for reverse docs, including PRD unit grouping |\n\n### Diagnosis Agents\n\n| Agent | Role |\n|-------|------|\n| `investigator` | Evidence collection and hypothesis enumeration |\n| `verifier` | Hypothesis validation (ACH + Devil's Advocate) |\n| `solver` | Solution derivation with tradeoff analysis |\n\n---\n\n## How It Works\n\n### Autonomous Execution Mode\n\nAfter work plan approval, the framework enters guided autonomous execution with escalation points:\n\n1. **task-executor** implements each task with TDD\n2. **quality-fixer** runs all checks (lint, tests, build) before every commit\n3. Escalation pauses execution when design deviation or ambiguity is detected\n4. Each task produces one commit — rollback-friendly granularity\n\n### Context Separation\n\nEach subagent runs in a fresh context. This context-engineering pattern keeps long-running agentic coding tasks legible and reviewable:\n- generation and verification happen in separate contexts, reducing author bias and carry-over assumptions\n- **document-reviewer** reviews without the author's bias\n- **investigator** collects evidence without confirmation bias\n- **code-reviewer** validates compliance without implementation context\n\n---\n\n## Project Structure\n\nAfter installation, your project gets:\n\n```\nyour-project/\n├── .agents/skills/           # Codex skills\n│   ├── coding-rules/         # Foundational (auto-loaded)\n│   ├── testing/\n│   ├── ai-development-guide/\n│   ├── documentation-criteria/\n│   ├── implementation-approach/\n│   ├── integration-e2e-testing/\n│   ├── task-analyzer/\n│   ├── subagents-orchestration-guide/\n│   ├── recipe-implement/     # Recipes ($recipe-*)\n│   ├── recipe-design/\n│   ├── recipe-build/\n│   ├── recipe-plan/\n│   ├── recipe-review/\n│   ├── recipe-diagnose/\n│   ├── recipe-task/\n│   ├── recipe-update-doc/\n│   ├── recipe-reverse-engineer/\n│   └── recipe-add-integration-tests/\n├── .codex/agents/            # Subagent TOML definitions\n│   ├── requirement-analyzer.toml\n│   ├── technical-designer.toml\n│   ├── task-executor.toml\n│   └── ... (23 agents total)\n└── docs/                     # Created as you use the recipes\n    ├── prd/\n    ├── design/\n    ├── adr/\n    ├── ui-spec/\n    └── plans/\n        └── tasks/\n```\n\n---\n\n## Works With\n\nIf your requirements already live in Linear or an existing PRD, [linear-prism](https://github.com/shinpr/linear-prism) can decompose them into implementation-ready tasks by reading the codebase, making dependencies explicit, and preserving Design Doc boundaries.\n\nThose tasks can then be passed into `$recipe-design` to enter the design phase with clearer scope and better task visibility.\n\n---\n\n## FAQ\n\n**Q: What models does this work with?**\n\nA: Designed for the latest GPT models. Lightweight subagents (e.g. rule-advisor) can use smaller models for faster analysis. Models are configurable per agent in the TOML files.\n\n**Q: Can I customize the agents?**\n\nA: Yes. Edit the TOML files in `.codex/agents/` — change model, sandbox_mode, developer_instructions, or skills.config. Files you modify locally are preserved during `npx codex-workflows update`.\n\n**Q: What's the difference between `$recipe-implement` and `$recipe-fullstack-implement`?**\n\nA: `$recipe-implement` is the universal entry point. It runs requirement-analyzer first, detects affected layers from the codebase, and automatically routes to backend, frontend, or fullstack flow. `$recipe-fullstack-implement` skips the detection and goes straight into the fullstack flow (separate Design Docs per layer, design-sync, layer-aware task execution). Use `$recipe-implement` when you're not sure; use `$recipe-fullstack-implement` when you know upfront that the feature spans both layers.\n\n**Q: Does this work with MCP servers?**\n\nA: Yes. Codex skills and subagents work alongside [MCP](https://developers.openai.com/codex/mcp) — skills operate at the instruction layer while MCP operates at the tool transport layer. You can add MCP servers to any agent's TOML configuration.\n\n**Q: What if a subagent gets stuck?**\n\nA: Subagents escalate to the user when they encounter design deviations, ambiguous requirements, or specification conflicts. The framework stops autonomous execution and presents the issue with options.\n\n---\n\n## Design Rationale\n\n\u003cdetails\u003e\n\u003csummary\u003eBackground reading behind the workflow design\u003c/summary\u003e\n\n- [Planning Is the Real Superpower of Agentic Coding](https://www.norsica.jp/blog/planning-superpower-agentic-coding) — why explicit planning turns large-task execution from raw generation into verification against a design and task breakdown\n- [Why LLMs Are Bad at 'First Try' and Great at Verification](https://www.norsica.jp/blog/llm-verification-over-generation) — why review loops and session separation are more reliable than first-shot generation on complex work\n- [Stop Putting Everything in AGENTS.md](https://www.norsica.jp/blog/stop-putting-everything-in-agents-md) — why `AGENTS.md` should stay lean while rules, docs, and task instructions live near the point of use\n\n\u003c/details\u003e\n\n---\n\n## License\n\nMIT License — free to use, modify, and distribute.\n\n---\n\nBuilt and maintained by [@shinpr](https://github.com/shinpr)\n","funding_links":[],"categories":["Codex Workflow Frameworks"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshinpr%2Fcodex-workflows","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshinpr%2Fcodex-workflows","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshinpr%2Fcodex-workflows/lists"}