codex-spec (shenli) — Summary

codex-spec is a Node.js CLI tool that automates spec-driven development workflows for OpenAI Codex, wrapping the OpenAI API to turn high-level feature intent into a structured artifact chain: product context → specification → requirements → implementation plan → task list → per-task execution. Unlike methodology documents, it actually invokes the OpenAI API at each stage, persisting artifacts to a .codex-specs/ directory tree. It targets the Codex CLI ecosystem (OpenAI Codex) as its primary runtime, though the CLI itself is a standalone npm package with no hard dependency on the codex binary. The framework is small (1 contributor, 45 stars) and purpose-built as a Codex-era counterpart to Kiro/OpenSpec patterns, shipping 10 CLI subcommands that mirror the spec pipeline stages. Compared to seeds, codex-spec differs from openspec (which is multi-tool and ships slash-commands + skills) in that it is a pure CLI tool that calls the OpenAI API directly, and differs from spec-kit (which ships a Python CLI with hooks and AI-tool integrations) in that it has no hooks, no multi-agent orchestration, and no TDD enforcement — it is the leanest possible CLI wrapper around a sequential spec-to-code pipeline.

codex-spec — Origin & Philosophy

Origin

Created by shenli (single maintainer), last commit September 2025. The repo description is "Automated workflows for OpenAI Codex. Features spec-driven development for new features: Product Requirement → Design → Development Plan → Implementation." It was built when OpenAI's Codex CLI was gaining traction as an autonomous coding agent and the author wanted a specification scaffold to feed it structured context before it executed code.

Core Philosophy

Make specifications the source of truth so AI agents work from shared, documented intent rather than free-form prompts. The README states the goal as: "Align teams on intent before coding · Preserve evolving project context · Generate detailed requirements and plans automatically · Execute tasks with dependency awareness and progress tracking."

Manifesto-style quotes (verbatim from README)

"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."

"This reduces rework, accelerates delivery, and keeps documentation in lockstep with the codebase."

Context

The framework is explicitly framed around the Codex CLI ecosystem (requires OPENAI_API_KEY). It optionally integrates with the codex binary on PATH but falls back to the OpenAI API for generation when codex CLI is unavailable. It is a minimal proof-of-concept level implementation: 1 contributor, 45 stars, 6 forks.

codex-spec — Architecture

Distribution

npm package (codex-spec), installed globally via npm install -g codex-spec.

Install

npm install -g codex-spec
export OPENAI_API_KEY=your_api_key_here
codex-spec context-setup --force

Required Runtime

• Node.js >= 16
• OPENAI_API_KEY environment variable
• Optional: codex CLI binary on PATH (falls back to API)

Directory Structure Created

.codex-specs/
├── context/
│   ├── product.md       # product context (what the project does)
│   ├── tech.md          # technology stack context
│   └── structure.md     # codebase structure context
├── current/             # alias to most recent spec
│   ├── specification.md
│   └── AGENTS.md
└── <YYYY-MM-DD_feature_name>/
    ├── specification.md  # feature spec
    ├── requirements.md   # EARS-style requirements
    ├── plan.md           # implementation plan
    └── tasks.json        # extracted tasks with IDs, phases, status

Source Structure

src/
├── cli.js               # CLI entry point (commander.js)
├── commands/            # 10 command handlers
│   ├── spec-context-setup.js
│   ├── spec-context-update.js
│   ├── spec-context-refresh.js
│   ├── spec-create.js
│   ├── spec-requirements.js
│   ├── spec-plan.js
│   ├── spec-tasks.js
│   ├── spec-execute.js
│   ├── spec-status.js
│   └── index.js
└── utils/
    ├── codex-client.js  # OpenAI API wrapper
    └── prompt-builder.js # prompt templates

Target AI Tools

• Primary: OpenAI Codex CLI / OpenAI API
• The execute command can invoke the local codex binary if available on PATH

codex-spec — Components

CLI Commands (10 total)

All commands are subcommands of the codex-spec binary.

No Skills / Hooks / MCP Servers

codex-spec ships zero Claude Code skills, hooks, or MCP servers. It is a pure standalone CLI.

Utility Modules

• CodexClient — wraps OpenAI API with system prompt injection
• PromptBuilder — builds prompts for each stage (spec creation, requirements, plan, execute)

codex-spec — Uniqueness & Positioning

differs_from_seeds

Closest seed is openspec (both are npm CLIs implementing a spec pipeline), but codex-spec differs fundamentally: it calls the OpenAI API itself at each stage (context setup, spec creation, requirements, plan, execution) rather than generating prompt files for a human-driven AI tool session. Where openspec ships slash-commands and skills that a human pastes into Claude Code, codex-spec is fully autonomous — run a command, get an artifact, no AI tool UI required. It also differs from spec-kit (Python CLI, hooks, multi-AI integrations) by having zero hooks and no TDD enforcement. Against agent-os (bash scaffold that writes CLAUDE.md files), codex-spec is lower-ceremony but narrower: it writes to .codex-specs/ not to Claude-specific config files.

Unique Positioning

codex-spec is the only framework in this batch targeting OpenAI Codex as primary runtime and calling the OpenAI API directly (not Claude Code). This makes it a non-Claude-first spec framework — it was built specifically when OpenAI launched the Codex CLI and authors wanted structured context to feed it.

Observable Failure Modes

1. No human gates: the pipeline runs from context-setup to execute with no review checkpoints — spec quality depends entirely on the initial description.
2. No TDD: the execute command writes code with no failing test first.
3. Context drift: product.md/tech.md/structure.md can go stale; --auto refresh requires git diff and manual invocation.
4. Requires OpenAI: hard dependency on OPENAI_API_KEY; no Claude, no Gemini support.
5. Single maintainer: 1 contributor, last commit Sep 2025, risk of abandonment.

Explicit Antipatterns (inferred from design)

• Writing code without first running context-setup and create
• Skipping requirements before plan