README.md

CodexSpec

A Spec-Driven Development (SDD) toolkit for Claude Code

CodexSpec helps you build high-quality software through a structured, specification-first approach. Instead of jumping straight to code, you define what to build and why before deciding how to build it.

Why Choose CodexSpec?

Why use CodexSpec on top of Claude Code? Here's the comparison:

Aspect	Claude Code Only	CodexSpec + Claude Code
Multi-language Support	Default English interaction	Configure team language for smoother collaboration and reviews
Traceability	Hard to trace decisions after session ends	All specs, plans, and tasks saved in `.codexspec/specs/`
Session Recovery	Plan mode interruptions are hard to recover from	Multi-command split + persisted docs = easy recovery
Team Governance	No unified principles, inconsistent styles	`constitution.md` enforces team standards and quality

What is Spec-Driven Development?

Spec-Driven Development (SDD) is a "specifications first, code later" methodology:

Traditional:  Idea → Code → Debug → Rewrite
SDD:          Idea → Confirmed Requirements → Spec → Plan → Tasks → Code

Why use SDD?

Problem	SDD Solution
AI misunderstandings	Specs clarify "what to build", AI stops guessing
Missing requirements	Interactive clarification discovers edge cases
Architecture drift	Review checkpoints ensure correct direction
Wasted rework	Problems are found before code is written

✨ Key Features

Core Workflow

Constitution-Based Development - Establish project principles that guide all decisions
Persistent Requirement Capture - /specify records confirmed discussion in requirements.md before document generation
Automatic Reviews - Every generated spec, plan, and task artifact includes built-in quality checks
Traceable Tasks - Task breakdowns preserve requirement and plan coverage, applying test-first only where required

Human-AI Collaboration

Review Commands - Dedicated review commands for spec, plan, and tasks
Interactive Clarification - Q&A-based requirement refinement
Cross-Artifact Analysis - Detect inconsistencies before implementation

Developer Experience

Native Claude Code Integration - Slash commands work seamlessly
Multi-Language Support - 13+ languages via LLM dynamic translation
Cross-Platform - Bash and PowerShell scripts included
Extensible - Plugin architecture for custom commands

Design Philosophy: Human-AI Collaboration

CodexSpec is built on the belief that effective AI-assisted development requires active human participation at every stage.

Why Human Oversight Matters

Without Reviews	With Reviews
AI makes wrong assumptions	Humans catch misunderstandings early
Incomplete requirements propagate	Gaps identified before implementation
Architecture drifts from intent	Alignment verified at each stage
Tasks miss critical features	Systematic coverage validation
Result: Rework, wasted effort	Result: Get it right the first time

The CodexSpec Approach

CodexSpec structures development into reviewable checkpoints:

Idea → /specify → requirements.md → /generate-spec → spec.md → /spec-to-plan → plan.md → /plan-to-tasks → tasks.md → /implement
                                                   │                         │                            │
                                              Review spec               Review plan                  Review tasks

Confirmed requirements are the highest-priority feature authority. Derived artifacts carry explicit source links so conflicts can be traced back instead of silently propagated.

Every generated artifact has a corresponding review command:

spec.md → /codexspec:review-spec
plan.md → /codexspec:review-plan
tasks.md → /codexspec:review-tasks
All artifacts → /codexspec:analyze

This systematic review process ensures:

Early error detection: Catch misunderstandings before code is written
Alignment verification: Confirm AI's interpretation matches your intent
Quality gates: Validate completeness, clarity, and feasibility at each stage
Reduced rework: Invest minutes in review to save hours of reimplementation

🚀 30-Second Quick Start

# 1. Install
uv tool install codexspec

# 2. Initialize project
#    Option A: Create new project
codexspec init my-project && cd my-project

#    Option B: Initialize in existing project
cd your-existing-project && codexspec init .

# 3. Use in Claude Code
claude
> /codexspec:constitution Create principles focused on code quality and testing
> /codexspec:specify I want to build a todo application
> /codexspec:generate-spec
> /codexspec:spec-to-plan
> /codexspec:plan-to-tasks
> /codexspec:implement-tasks

That's it! Read on for the complete workflow.

Installation

Prerequisites

Python 3.11+
uv (recommended) or pip

Recommended Installation

# Using uv (recommended)
uv tool install codexspec

# Or using pip
pip install codexspec

Verify Installation

codexspec --version

📦 Alternative Installation Methods

One-time Usage (No Installation)

# Create new project
uvx codexspec init my-project

# Initialize in existing project
cd your-existing-project
uvx codexspec init . --ai claude

Install Development Version from GitHub

# Using uv
uv tool install git+https://github.com/Zts0hg/codexspec.git

# Specify branch or tag
uv tool install git+https://github.com/Zts0hg/codexspec.git@main
uv tool install git+https://github.com/Zts0hg/[email protected]

🪟 Notes for Windows Users

Recommended: Use PowerShell

# 1. Install uv (if not already installed)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# 2. Restart PowerShell, then install codexspec
uv tool install codexspec

# 3. Verify installation
codexspec --version

CMD Troubleshooting

If you encounter "Access denied" errors:

Close all CMD windows and reopen
Or manually refresh PATH: set PATH=%PATH%;%USERPROFILE%\.local\bin
Or use full path: %USERPROFILE%\.local\bin\codexspec.exe --version

For detailed troubleshooting, see Windows Troubleshooting Guide.

Upgrade

# Using uv
uv tool install codexspec --upgrade

# Using pip
pip install --upgrade codexspec

Plugin Marketplace Installation (Alternative)

CodexSpec is also available as a Claude Code plugin. This method is ideal if you want to use CodexSpec commands directly in Claude Code without the CLI tool.

Installation Steps

# In Claude Code, add the marketplace
> /plugin marketplace add Zts0hg/codexspec

# Install the plugin
> /plugin install codexspec@codexspec-market

Language Configuration for Plugin Users

After installing via Plugin Marketplace, configure your preferred language using the /codexspec:config command:

# Start interactive configuration
> /codexspec:config

# Or view current configuration
> /codexspec:config --view

The config command will guide you through:

Selecting output language (for generated documents)
Selecting commit message language
Creating the .codexspec/config.yml file

Comparison of Installation Methods

Method	Best For	Features
CLI Installation (`uv tool install`)	Full development workflow	CLI commands (`init`, `check`, `config`) + slash commands
Plugin Marketplace	Quick start, existing projects	Slash commands only (use `/codexspec:config` for language setup)

Note: The plugin uses strict: false mode and reuses the existing multi-language support via LLM dynamic translation.

Core Workflow

CodexSpec breaks development into reviewable checkpoints:

Idea → /specify → requirements.md → /generate-spec → spec.md → /spec-to-plan → plan.md → /plan-to-tasks → tasks.md → /implement
                                                   │                         │                            │
                                              Review spec               Review plan                  Review tasks

Workflow Steps

Step	Command	Output	Human Check
1. Project Principles	`/codexspec:constitution`	`constitution.md`	✅
2. Requirement Clarification	`/codexspec:specify`	`requirements.md`	✅
3. Generate Spec	`/codexspec:generate-spec`	`spec.md` + auto-review	✅
4. Technical Planning	`/codexspec:spec-to-plan`	`plan.md` + auto-review	✅
5. Task Breakdown	`/codexspec:plan-to-tasks`	`tasks.md` + auto-review	✅
6. Cross-Artifact Analysis	`/codexspec:analyze`	Analysis report	✅
7. Implementation	`/codexspec:implement-tasks`	Code	-

specify vs clarify: When to Use Which?

Aspect	`/codexspec:specify`	`/codexspec:clarify`
Purpose	Initial requirement exploration and confirmation	Refine confirmed requirements or derived spec
When to Use	Starting a feature	Requirements or spec need clarification
Output	Creates/updates `requirements.md`	Updates `requirements.md` first, then synchronizes `spec.md`
Method	Open-ended Q&A	Structured scan (4 categories)
Questions	Unlimited	Max 5 per run

Key Concept: Iterative Quality Loop

Every generation command includes automatic review. Verified defects may be fixed and re-reviewed for at most two rounds; advisory suggestions remain separate and never trigger automatic changes.

Review the report
Describe issues to fix in natural language
System automatically updates specs and review reports

%%{init: {
  'theme': 'base',
  'themeVariables': {
    'lineColor': '#888888',
    'primaryColor': '#2d2d2d',
    'primaryTextColor': '#ffffff',
    'primaryBorderColor': '#666666'
  },
  'flowchart': {
    'curve': 'stepBefore',
    'nodeSpacing': 50,
    'rankSpacing': 40
  }
}}%%
flowchart TB
    classDef rectStyle fill:#2d2d2d,stroke:#666,stroke-width:1px,color:#fff,width:220px;
    classDef diamondStyle fill:#3d3d3d,stroke:#888,stroke-width:2px,color:#fff;

    A["Generate Spec/Plan/Tasks"]:::rectStyle --> B["Auto Review"]:::rectStyle
    B --> C{"Issues Found?"}:::diamondStyle

    C -->|Verified defect| D["Fix with evidence"]:::rectStyle
    D --> E["Update artifact + review report"]:::rectStyle

    E --> B

    C -->|No| F["Continue to Next Step"]:::rectStyle

    linkStyle 2,4 stroke:#aaa,stroke-width:1px;

📖 Detailed Workflow Description

1. Initialize Project

codexspec init my-awesome-project
cd my-awesome-project
claude

2. Establish Project Principles

/codexspec:constitution Create principles focused on code quality, testing standards, and clean architecture

3. Clarify Requirements

/codexspec:specify I want to build a task management application

This command will:

Ask clarifying questions to understand your idea
Explore edge cases you might not have considered
Ask you to confirm the final requirement summary
Persist confirmed needs, constraints, decisions, exclusions, and open questions in requirements.md

4. Generate Specification Document

Once requirements are clarified:

/codexspec:generate-spec

This command:

Compiles confirmed entries from requirements.md into a structured specification
Adds source references for requirement traceability
Automatically runs review and generates review-spec.md

5. Create Technical Plan

/codexspec:spec-to-plan Use Python FastAPI for backend, PostgreSQL for database, React for frontend

Uses only relevant planning sections, records Covers links to specification requirements, and verifies applicable project principles.

6. Generate Tasks

/codexspec:plan-to-tasks

Tasks are organized around verifiable outcomes:

Conditional testing: Test-first ordering is used when required by the plan, constitution, or task risk
Parallel Markers [P]: Used only for genuinely independent tasks
File Path Specifications: Clear deliverables per task
Traceability: Each task links to the plan and requirements it covers

7. Cross-Artifact Analysis (Optional but Recommended)

/codexspec:analyze

Detects issues across requirements, spec, plan, and tasks:

Coverage gaps (requirements without tasks)
Duplication and inconsistencies
Constitution violations
Underspecified items

8. Implementation

/codexspec:implement-tasks

Implementation follows conditional TDD workflow:

Code tasks: Test-first (Red → Green → Verify → Refactor)
Non-testable tasks (docs, config): Direct implementation

Available Commands

CLI Commands

Command	Description
`codexspec init`	Initialize a new project
`codexspec check`	Check for installed tools
`codexspec version`	Display version information
`codexspec config`	View or modify configuration

📋 init Options

Option	Description
`PROJECT_NAME`	Project directory name
`--here`, `-h`	Initialize in current directory
`--ai`, `-a`	AI assistant to use (default: claude)
`--lang`, `-l`	Output language (e.g., en, zh-CN, ja)
`--force`, `-f`	Force overwrite existing files
`--no-git`	Skip git initialization
`--debug`, `-d`	Enable debug output

📋 config Options

Option	Description
`--set-lang`, `-l`	Set output language
`--set-commit-lang`, `-c`	Set commit message language
`--list-langs`	List all supported languages

Slash Commands

Core Workflow Commands

Command	Description
`/codexspec:constitution`	Create/update project constitution with cross-artifact validation
`/codexspec:specify`	Clarify, confirm, and persist requirements in `requirements.md`
`/codexspec:generate-spec`	Generate `spec.md` document ★ Auto-review
`/codexspec:spec-to-plan`	Convert spec to technical plan ★ Auto-review
`/codexspec:plan-to-tasks`	Break down plan into traceable, verifiable tasks ★ Auto-review
`/codexspec:implement-tasks`	Execute tasks (conditional TDD)

Review Commands (Quality Gates)

Command	Description
`/codexspec:review-spec`	Review specification (auto or manual)
`/codexspec:review-plan`	Review technical plan (auto or manual)
`/codexspec:review-tasks`	Review task breakdown (auto or manual)

Enhancement Commands

Command	Description
`/codexspec:config`	Manage project configuration (create/view/modify/reset)
`/codexspec:clarify`	Scan spec for ambiguities (4 categories, max 5 questions)
`/codexspec:analyze`	Cross-artifact consistency analysis (read-only, severity-based)
`/codexspec:checklist`	Generate requirements quality checklist
`/codexspec:tasks-to-issues`	Convert tasks to GitHub Issues

Git Workflow Commands

Command	Description
`/codexspec:commit-staged`	Generate commit message from staged changes
`/codexspec:pr`	Generate PR/MR description (auto-detect platform)

Code Review Commands

Command	Description
`/codexspec:review-code`	Review code in any language (idiomatic clarity, correctness, robustness, architecture)

Comparison with spec-kit

CodexSpec is inspired by GitHub spec-kit with key differences:

Feature	spec-kit	CodexSpec
Core Philosophy	Spec-driven development	Spec-driven + Human-AI collaboration
CLI Name	`specify`	`codexspec`
Primary AI	Multi-agent support	Focused on Claude Code
Constitution System	Basic	Full constitution + cross-artifact validation
Two-Phase Spec	No	Yes (clarify + generate)
Review Commands	Optional	3 dedicated review commands + scoring
Clarify Command	Yes	4 focus categories, review integration
Analyze Command	Yes	Read-only, severity-based, constitution-aware
TDD in Tasks	Optional	Conditional on requirements, risk, and policy
Implementation	Standard	Conditional TDD (code vs docs/config)
Extension System	Yes	Yes
PowerShell Scripts	Yes	Yes
i18n Support	No	Yes (13+ languages via LLM translation)

Key Differentiators

Review-First Culture: Every major artifact has a dedicated review command
Constitution Governance: Principles are validated, not just documented
Evidence-Based Review: Defects require concrete evidence; advisory design ideas do not affect acceptance
Human Checkpoints: Workflow designed around validation gates

Internationalization (i18n)

CodexSpec supports multiple languages through LLM dynamic translation. No translation templates to maintain - Claude translates content at runtime based on your language configuration.

Setting Language

During initialization:

# Create Chinese output project
codexspec init my-project --lang zh-CN

# Create Japanese output project
codexspec init my-project --lang ja

After initialization:

# View current configuration
codexspec config

# Change output language
codexspec config --set-lang zh-CN

# Set commit message language
codexspec config --set-commit-lang en

Supported Languages

Code	Language
`en`	English (default)
`zh-CN`	简体中文
`zh-TW`	繁體中文
`ja`	日本語
`ko`	한국어
`es`	Español
`fr`	Français
`de`	Deutsch
`pt-BR`	Português
`ru`	Русский
`it`	Italiano
`ar`	العربية
`hi`	हिन्दी

⚙️ Configuration File Example

.codexspec/config.yml:

version: "1.0"

language:
  output: "zh-CN"        # Output language
  commit: "zh-CN"        # Commit message language (defaults to output)
  templates: "en"        # Keep as "en"

project:
  ai: "claude"
  created: "2025-02-15"

Project Structure

Project structure after initialization:

my-project/
├── .codexspec/
│   ├── memory/
│   │   └── constitution.md    # Project constitution
│   ├── specs/
│   │   └── {feature-id}/
│   │       ├── spec.md        # Feature specification
│   │       ├── plan.md        # Technical plan
│   │       ├── tasks.md       # Task breakdown
│   │       └── checklists/    # Quality checklists
│   ├── templates/             # Custom templates
│   ├── scripts/               # Helper scripts
│   └── extensions/            # Custom extensions
├── .claude/
│   └── commands/              # Claude Code slash commands
└── CLAUDE.md                  # Claude Code context

Extension System

CodexSpec supports a plugin architecture for custom commands:

my-extension/
├── extension.yml          # Extension manifest
├── commands/              # Custom slash commands
│   └── command.md
└── README.md

See extensions/EXTENSION-DEVELOPMENT-GUIDE.md for details.

Development

Prerequisites

Python 3.11+
uv package manager
Git

Local Development

# Clone repository
git clone https://github.com/Zts0hg/codexspec.git
cd codexspec

# Install dev dependencies
uv sync --dev

# Run locally
uv run codexspec --help

# Run tests
uv run pytest

# Lint code
uv run ruff check src/

# Build package
uv build

Contributing

Contributions are welcome! Please read the contributing guidelines before submitting a pull request.

License

MIT License - see LICENSE for details.

Acknowledgements

Inspired by GitHub spec-kit
Built for Claude Code

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

CodexSpec

Table of Contents

Why Choose CodexSpec?

What is Spec-Driven Development?

Core Workflow

Human-AI Collaboration

Developer Experience

Design Philosophy: Human-AI Collaboration

Why Human Oversight Matters

The CodexSpec Approach

🚀 30-Second Quick Start

Installation

Prerequisites

Recommended Installation

Verify Installation

One-time Usage (No Installation)

Install Development Version from GitHub

Upgrade

Plugin Marketplace Installation (Alternative)

Installation Steps

Language Configuration for Plugin Users

Core Workflow

Workflow Steps

specify vs clarify: When to Use Which?

Key Concept: Iterative Quality Loop

1. Initialize Project

2. Establish Project Principles

3. Clarify Requirements

4. Generate Specification Document

5. Create Technical Plan

6. Generate Tasks

7. Cross-Artifact Analysis (Optional but Recommended)

8. Implementation

Available Commands

CLI Commands

Slash Commands

Core Workflow Commands

Review Commands (Quality Gates)

Enhancement Commands

Git Workflow Commands

Code Review Commands

Comparison with spec-kit

Key Differentiators

Internationalization (i18n)

Setting Language

Supported Languages

Project Structure

Extension System

Development

Prerequisites

Local Development

Contributing

License

Acknowledgements