Specification-driven development workflow for AI coding (OpenAI Codex)
npm install codex-specSpecification-driven development workflows for AI coding. codex-spec turns intent into executable specs and plans, then guides consistent implementation with context-aware commands.
AI is great at generating code, but results can be inconsistent without clear intent and shared context. codex-spec makes specifications the source of truth so you can:
- Align teams on intent before coding
- Preserve evolving project context (product, tech, structure)
- Generate detailed requirements and plans automatically
- Execute tasks with dependency awareness and progress tracking
This reduces rework, accelerates delivery, and keeps documentation in lockstep with the codebase.
``mermaid`
flowchart TD
A[Setup] --> B[Context Creation]
B --> C[Feature Specification]
C --> D[Requirements]
D --> E[Implementation Plan]
E --> F[Execute Tasks]
F --> G[Progress & Status]
G --> H[Maintenance: Context Update/Refresh]
Prerequisites:
- Node.js >= 16
- OpenAI API key (environment variable OPENAI_API_KEY)
Install globally:
`bash`
npm install -g codex-spec
Set your API key:
`bash`
export OPENAI_API_KEY=your_api_key_here
Optional: If you use the Codex CLI locally, ensure it is installed and available on PATH.
Initialize project context (product, tech, structure):
`bash`
codex-spec context-setup --force
Create a feature specification:
`bash`
codex-spec create "User onboarding" "Signup, verification, and first-run experience"
Generate detailed requirements and a plan with tasks:
`bashplan
codex-spec requirements
codex-spec plan
codex-spec plan-summary # also runs automatically after `
codex-spec tasks # list task IDs, titles, phases, status
Execute a task and track progress:
`bash`
codex-spec execute task-1
codex-spec status
Maintain up-to-date context:
`bash`
codex-spec context-update --auto
codex-spec context-refresh
- context-setup:.codex-specs/context/product.md
- Initialize , tech.md, structure.mdcontext-update [component]
- :--auto
- Update product/tech/structure context (use to diff recent changes)context-refresh
- :create
- Regenerate context files from scratch
- :requirements [spec-name]
- Create a comprehensive feature specification
- :plan [spec-name]
- Generate requirements from the specification
- :.codex-specs/
- Create the implementation plan and extract tasks to execute
- :--read-only
- Execute an implementation task with context and plan guidance
- Sandbox: writes are enabled by default (workspace-write). Use to prevent writes.tasks
- :execute-phase
- List tasks with IDs, titles, phase, and status
- :--read-only
- Execute all tasks in a specific phase
- Sandbox: writes enabled by default; pass to prevent writesstatus
- / plan-summary:
- View progress and plan overview
Notes:
- Phase names with spaces must be quoted or escaped when running by phase:
- macOS/Linux: codex-spec execute-phase "Core Features" or codex-spec execute-phase Core\ Featurescodex-spec execute-phase "Core Features"
- Windows: YYYY-MM-DD_name_of_the_spec
- Spec directory naming: defaults to AI-chosen snake_case slug with date prefix (). Override with --title "your_slug".
Key directories created in your repo:
``
.codex-specs/
├── context/
│ ├── product.md
│ ├── tech.md
│ └── structure.md
└──
├── specification.md
├── requirements.md
├── plan.md
└── tasks.json
- Requires OPENAI_API_KEY--auto
- Works in any Git project; context updates use git diff--help
- Defaults are sensible; commands expose for options
- Command hangs or errors when running tasks: ensure the codex CLI (if you use it) is installed and available on PATH; otherwise the tool will use the OpenAI API for generation and planning.OPENAI_API_KEY
- API errors: verify and network connectivity.
- Product Requirements: design/codex_spec_product_requirements.md
- Technical Design: design/codex_spec_workflow.md`
MIT