codex-spec

Specification-driven development workflows for AI coding. codex-spec turns intent into executable specs and plans, then guides consistent implementation with context-aware commands.

Why

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.

Workflow Diagram

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]

Installation

Prerequisites:

• Node.js >= 16
• OpenAI API key (environment variable OPENAI_API_KEY)

Install globally:

npm install -g codex-spec

Set your API key:

export OPENAI_API_KEY=your_api_key_here

Optional: If you use the Codex CLI locally, ensure it is installed and available on PATH.

Quickstart

Initialize project context (product, tech, structure):

codex-spec context-setup --force

Create a feature specification:

codex-spec create "User onboarding" "Signup, verification, and first-run experience"

Generate detailed requirements and a plan with tasks:

codex-spec requirements
codex-spec plan
codex-spec plan-summary  # also runs automatically after `plan`
codex-spec tasks         # list task IDs, titles, phases, status

Execute a task and track progress:

codex-spec execute task-1
codex-spec status

Maintain up-to-date context:

codex-spec context-update --auto
codex-spec context-refresh

Commands

• context-setup:
  • Initialize .codex-specs/context/product.md, tech.md, structure.md
• context-update [component]:
  • Update product/tech/structure context (use --auto to diff recent changes)
• context-refresh:
  • Regenerate context files from scratch
• create <feature-name> [description]:
  • Create a comprehensive feature specification
• requirements [spec-name]:
  • Generate requirements from the specification
• plan [spec-name]:
  • Create the implementation plan and extract tasks to .codex-specs/<spec>/tasks.json
• execute <task-id>:
  • Execute an implementation task with context and plan guidance
  • Sandbox: writes are enabled by default (workspace-write). Use --read-only to prevent writes.
• tasks:
  • List tasks with IDs, titles, phase, and status
• execute-phase <phase>:
  • Execute all tasks in a specific phase
  • Sandbox: writes enabled by default; pass --read-only to prevent writes
• status / 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\ Features
  • Windows: codex-spec execute-phase "Core Features"
• Spec directory naming: defaults to AI-chosen snake_case slug with date prefix (YYYY-MM-DD_name_of_the_spec). Override with --title "your_slug".

Project Files

Key directories created in your repo:

.codex-specs/
├── context/
│   ├── product.md
│   ├── tech.md
│   └── structure.md
└── <feature-name>/
    ├── specification.md
    ├── requirements.md
    ├── plan.md
    └── tasks.json

Configuration

• Requires OPENAI_API_KEY
• Works in any Git project; --auto context updates use git diff
• Defaults are sensible; commands expose --help for options

Troubleshooting

• 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.
• API errors: verify OPENAI_API_KEY and network connectivity.

Design & Requirements

• Product Requirements: design/codex_spec_product_requirements.md
• Technical Design: design/codex_spec_workflow.md

License

MIT