{"id":47680058,"url":"https://github.com/shinpr/codex-workflows","last_synced_at":"2026-06-14T04:02:03.955Z","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-15T03:56:15.000Z","size":338,"stargazers_count":7,"open_issues_count":1,"forks_count":3,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-15T05:25:35.749Z","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-15T03:54:44.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":20,"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":32550973,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-02T21:31:48.061Z","status":"ssl_error","status_checked_at":"2026-05-02T21:31:46.574Z","response_time":132,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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-06-14T04:02:03.947Z","avatar_url":"https://github.com/shinpr.png","language":"JavaScript","funding_links":[],"categories":["Codex Workflow Frameworks"],"sub_categories":[],"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 workflows for [OpenAI Codex CLI](https://developers.openai.com/codex/cli).**\n\nThey help when multi-step changes stop being easy to reason about, test, or review.\n\nBuilt on the [Agent Skills specification](https://developers.openai.com/codex/skills/) and [Codex subagents](https://developers.openai.com/codex/subagents). This starts to matter when tasks get large: refactors, migrations, or anything that spans multiple files and needs to stay reviewable.\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 are broken into requirements, design, task decomposition, TDD implementation, and quality checks.\n\n---\n\n## Why codex-workflows?\n\nCodex works well for short, focused tasks. The problems start when a change spans multiple files, needs design decisions to stay visible, or has to survive review, testing, and follow-up edits.\n\nMany developers have seen the same pattern: things work at first, then drift. Context grows, assumptions accumulate, intermediate decisions disappear, and results become harder to trust.\n\ncodex-workflows is built around those failure modes. Instead of asking Codex to \"just implement it\", it turns a request into a sequence of steps you can inspect and verify:\n- Traceable artifacts: PRD → Design Doc → Task → Commit\n- Built-in TDD and quality checks 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## Background\n\nThe recipes, subagents, and quality checks in this repo were not designed top-down. Each piece was added in response to a concrete failure mode encountered during delivery work.\n\nThat is why the workflow separates requirements, design, verification, implementation, and quality checks instead of treating them as one long session.\n\n## Not Designed For\n\n- One-shot scripts or exploratory sessions where speed matters more than traceability\n- Repositories without tests, lint, builds, or reviewable commits\n- Teams that would rather skip design docs and quality checks entirely\n\n---\n\n## What It Does\n\nInstead of forcing a fixed workflow, the framework adjusts how much structure it adds 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 → guided 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 isolates one concern, so decisions can be checked before they carry into later stages. Specialized subagents run in their own contexts to reduce carry-over assumptions during changes that would otherwise require long sessions:\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 (path map + failure points) → verifier (path coverage + independent failure-point evaluation) → 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, including nullable E2E skeleton handling |\n| `$recipe-prepare-implementation` | Verify work plan readiness and resolve prep gaps | Pre-build check that the plan is implementable |\n| `$recipe-build` | Execute backend tasks with validation between steps | Resume backend implementation |\n| `$recipe-review` | Design Doc compliance and security validation with auto-fixes | Post-implementation check |\n| `$recipe-diagnose` | Problem investigation → failure-point 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-adjust` | Implemented UI adjustment with external context and verification | Focused UI changes after implementation |\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### Working State\n\nRecipes use `docs/plans/` as ephemeral working state for work plans, decomposed task files, prep tasks, review-fix tasks, and intermediate analysis files. Add it to your project's `.gitignore` unless your team intentionally wants to review those transient files:\n\n```gitignore\ndocs/plans/\n```\n\nPRDs, ADRs, UI Specs, and Design Docs are durable project documents and are intended to be committed.\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 are applied automatically based on context. You rarely need to think about them directly.\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, value-based selection, review criteria |\n| `external-resource-context` | Access methods for design sources, design systems, API schemas, and verification environments |\n| `task-analyzer` | Task analysis, scale estimation, skill selection |\n| `subagents-orchestration-guide` | Multi-agent coordination, workflow flows, guided 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. You do not need to learn them first; recipes route work to the right agents automatically. 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| `ui-analyzer` | UI facts from external resources (design tools, design-system docs, deployed UI) and frontend code |\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, path mapping, and failure-point discovery |\n| `verifier` | Path coverage validation and independent failure-point evaluation |\n| `solver` | Solution derivation with tradeoff analysis |\n\n---\n\n## How It Works\n\n### Guided Autonomous Execution Mode\n\nAfter work plan approval, the framework executes task files with explicit validation points:\n\n1. **task-executor** implements each task with TDD\n2. **quality-fixer** first rejects incomplete task-scoped implementations, then runs lint, tests, and build before every commit\n3. Escalation pauses execution when design deviation or ambiguity is detected\n4. Each task produces one commit for rollback-friendly granularity\n\n### Context Separation\n\nEach subagent runs in a fresh context. This pattern keeps multi-step 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│   ├── external-resource-context/\n│   ├── task-analyzer/\n│   ├── subagents-orchestration-guide/\n│   ├── recipe-implement/     # Recipes ($recipe-*)\n│   ├── recipe-design/\n│   ├── recipe-build/\n│   ├── recipe-front-adjust/\n│   ├── recipe-plan/\n│   ├── recipe-prepare-implementation/\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│   ├── ui-analyzer.toml\n│   ├── task-executor.toml\n│   └── ... (25 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. Custom agents inherit parent `mcp_servers` when the agent TOML omits `mcp_servers`; add agent-local MCP config only for agent-specific servers or tool filtering.\n\n**Q: How is this related to claude-code-workflows?**\n\nA: [claude-code-workflows](https://github.com/shinpr/claude-code-workflows) is the Claude Code counterpart. The repositories share the same workflow philosophy, adapted to each tool's native extension points. They can coexist in the same project because Codex uses `.agents/skills/`, `.codex/agents/`, and `AGENTS.md`, while Claude Code uses its own `.claude/` files and `CLAUDE.md`.\n\n**Q: What if a subagent seems stuck?**\n\nA: Long waits can be normal in this workflow because many subagents perform substantial multi-step work. The orchestrator keeps ownership of the pending deliverable, continues waiting for the required output, and uses diagnostics only to confirm missing inputs or restate the pending deliverable. User direction remains the boundary for interrupting that work.\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","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"}