CodexSpec

English | 中文 | 日本語 | Español | Português | 한국어 | Deutsch | Français

📖 Documentation | 中文文档 | 日本語ドキュメント | 한국어 문서 | Documentación | Documentation | Dokumentation | Documentação

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

CodexSpec is a toolkit that helps you build high-quality software using a structured, specification-driven approach. It flips the script on traditional development by making specifications executable artifacts that directly guide implementation.

Design Philosophy: Human-AI Collaboration

CodexSpec is built on the belief that effective AI-assisted development requires active human participation at every stage. The toolkit is designed around a core principle:

Review and validate each artifact before moving forward.

Why Human Oversight Matters

In AI-assisted development, skipping review stages leads to:

Problem	Consequence
Unclear requirements	AI makes assumptions that diverge from your intent
Incomplete specifications	Features get built without critical edge cases
Misaligned technical plans	Architecture doesn't match business needs
Vague task breakdowns	Implementation goes off-track, requiring expensive rework

The CodexSpec Approach

CodexSpec structures development into reviewable checkpoints:

Idea → Clarify → Review → Plan → Review → Tasks → Review → Analyze → Implement
              ↑              ↑              ↑
           Human checks    Human checks    Human checks

Every 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

Features

Core SDD Workflow

• Constitution-Based: Establish project principles that guide all subsequent decisions
• Two-Phase Specification: Interactive clarification (/specify) followed by document generation (/generate-spec)
• Plan-Driven Development: Technical choices come after requirements are validated
• TDD-Ready Tasks: Task breakdowns enforce test-first methodology

Human-AI Collaboration

• Review Commands: Dedicated review commands for spec, plan, and tasks to validate AI output
• Interactive Clarification: Q&A-based requirement refinement with immediate feedback
• Cross-Artifact Analysis: Detect inconsistencies between spec, plan, and tasks before implementation
• Quality Checklists: Automated quality assessment for requirements

Developer Experience

• Claude Code Integration: Native slash commands for Claude Code
• Internationalization (i18n): Multi-language support via LLM dynamic translation
• Cross-Platform: Support for both Bash and PowerShell scripts
• Extensible: Plugin architecture for custom commands

Installation

Prerequisites

• Python 3.11+
• uv (recommended) or pip

Option 1: Install with uv (Recommended)

The easiest way to install CodexSpec is using uv:

uv tool install codexspec

Option 2: Install with pip

Alternatively, you can use pip:

pip install codexspec

Option 3: One-time Usage

Run directly without installing:

# Create a new project
uvx codexspec init my-project

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

Option 4: Install from GitHub (Development Version)

For the latest development version or a specific branch:

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

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

# Specific branch or tag
uv tool install git+https://github.com/Zts0hg/codexspec.git@main
uv tool install git+https://github.com/Zts0hg/codexspec.git@v0.2.0

Windows Users

Recommended: Use PowerShell

Windows users should use PowerShell for installation and running CodexSpec:

# 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

Troubleshooting for CMD Users

If you encounter "Access denied" or "spawn codexspec access denied (OSError 5)" errors in CMD:

Solution 1: Refresh environment variables

# Close all CMD windows and open a new one
# Or manually refresh PATH
set PATH=%PATH%;%USERPROFILE%\.local\bin
codexspec --version

Solution 2: Use full path

%USERPROFILE%\.local\bin\codexspec.exe --version

Solution 3: Use pipx instead of uv tool

pip install pipx
pipx ensurepath
# Restart CMD
pipx install codexspec

FAQ

Q: Why does PowerShell work but CMD doesn't? A: PowerShell and CMD handle user environment variables differently. When uv adds paths to user PATH, PowerShell typically recognizes them immediately, while CMD may require a restart or manual refresh.

For more details, see Windows Troubleshooting Guide.

Quick Start

After installation, you can use the CLI:

# Create new project
codexspec init my-project

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

# Initialize in existing project
codexspec init . --ai claude
# or
codexspec init --here --ai claude

# Check installed tools
codexspec check

# View version
codexspec version

To upgrade to the latest version:

# Using uv
uv tool install codexspec --upgrade

# Using pip
pip install --upgrade codexspec

Usage

1. Initialize a Project

After installation, create or initialize your project:

codexspec init my-awesome-project
# or in current directory
codexspec init . --ai claude

2. Establish Project Principles

Launch Claude Code in the project directory:

cd my-awesome-project
claude

Use the /codexspec.constitution command to create your project's governing principles:

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

3. Clarify Requirements

Use /codexspec.specify to explore and clarify your requirements through interactive Q&A:

/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
• Co-create high-quality requirements through dialogue
• NOT generate files automatically - you stay in control

4. Generate Specification Document

Once requirements are clarified, use /codexspec.generate-spec to create the spec.md document:

/codexspec.generate-spec

This command acts as a "requirement compiler" that transforms your clarified requirements into a structured specification document.

5. Review Specification (Recommended)

Before proceeding to planning, validate your specification:

/codexspec.review-spec

This command generates a detailed review report with:

• Section completeness analysis
• Clarity and testability assessment
• Constitution alignment check
• Prioritized recommendations

6. Create a Technical Plan

Use /codexspec.spec-to-plan to define how to implement it:

/codexspec.spec-to-plan Use Python with FastAPI for the backend, PostgreSQL for the database, and React for the frontend

The command includes constitutionality review - verifying your plan aligns with project principles.

7. Review Plan (Recommended)

Before breaking down into tasks, validate your technical plan:

/codexspec.review-plan

This verifies:

• Specification alignment
• Architecture soundness
• Tech stack appropriateness
• Constitution compliance

8. Generate Tasks

Use /codexspec.plan-to-tasks to break down the plan:

/codexspec.plan-to-tasks

Tasks are organized into standard phases with:

• TDD enforcement: Test tasks precede implementation tasks
• Parallel markers [P]: Identify independent tasks
• File path specifications: Clear deliverables per task

9. Review Tasks (Recommended)

Before implementation, validate task breakdown:

/codexspec.review-tasks

This checks:

• Plan coverage
• TDD compliance
• Dependency correctness
• Task granularity

10. Analyze (Optional but Recommended)

Use /codexspec.analyze for cross-artifact consistency check:

/codexspec.analyze

This detects issues across spec, plan, and tasks:

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

11. Implement

Use /codexspec.implement-tasks to execute the implementation:

/codexspec.implement-tasks

The 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 CodexSpec project
codexspec check	Check for installed tools
codexspec version	Display version information
codexspec config	View or modify project configuration

codexspec init Options

Option	Description
PROJECT_NAME	Name for your new project directory
--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

codexspec config Options

Option	Description
--set-lang, -l	Set the output language
--set-commit-lang, -c	Set the commit message language (defaults to output language)
--list-langs	List all supported languages

Slash Commands

After initialization, these slash commands are available in Claude Code:

Core Workflow Commands

Command	Description
/codexspec.constitution	Create or update project constitution with cross-artifact validation and sync impact reporting
/codexspec.specify	Clarify requirements through interactive Q&A (no file generation)
/codexspec.generate-spec	Generate spec.md document after requirements are clarified
/codexspec.spec-to-plan	Convert specification to technical plan with constitutionality review and module dependency graph
/codexspec.plan-to-tasks	Break down plan into atomic, TDD-enforced tasks with parallel markers [P]
/codexspec.implement-tasks	Execute tasks with conditional TDD workflow (TDD for code, direct for docs/config)

Review Commands (Quality Gates)

Command	Description
/codexspec.review-spec	Validate specification for completeness, clarity, consistency, and testability with scoring
/codexspec.review-plan	Review technical plan for feasibility, architecture quality, and constitution alignment
/codexspec.review-tasks	Validate task breakdown for plan coverage, TDD compliance, dependencies, and granularity

Enhancement Commands

Command	Description
/codexspec.clarify	Scan existing spec.md for ambiguities using 4 focused categories, integrate with review findings
/codexspec.analyze	Non-destructive cross-artifact analysis (spec, plan, tasks) with severity-based issue detection
/codexspec.checklist	Generate quality checklists for requirements validation
/codexspec.tasks-to-issues	Convert tasks to GitHub issues for project management integration

Git Workflow Commands

Command	Description
/codexspec.commit	Generate Conventional Commits messages based on git status and session context
/codexspec.commit-staged	Generate commit message from staged changes only
/codexspec.pr	Generate structured PR (GitHub) or MR (GitLab) descriptions with platform auto-detection

Workflow Overview

┌──────────────────────────────────────────────────────────────────────────┐
│                    CodexSpec Human-AI Collaboration Workflow             │
├──────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  1. Constitution  ──►  Define project principles                         │
│         │                         with cross-artifact validation         │
│         ▼                                                                │
│  2. Specify  ───────►  Interactive Q&A to clarify requirements           │
│         │               (no file created - human control)                │
│         ▼                                                                │
│  3. Generate Spec  ─►  Create spec.md document                           │
│         │                                                                │
│         ▼                                                                │
│  ╔═══════════════════════════════════════════════════════════════════╗   │
│  ║  ★ REVIEW GATE 1: /codexspec.review-spec ★                        ║   │
│  ║  Validate: Completeness, Clarity, Testability, Constitution       ║   │
│  ╚═══════════════════════════════════════════════════════════════════╝   │
│         │                                                                │
│         ▼                                                                │
│  4. Clarify  ───────►  Resolve ambiguities (iterative)                   │
│         │               4 focused categories, max 5 questions            │
│         ▼                                                                │
│  5. Spec to Plan  ──►  Create technical plan with:                       │
│         │               • Constitutionality review (MANDATORY)           │
│         │               • Module dependency graph                        │
│         ▼                                                                │
│  ╔═══════════════════════════════════════════════════════════════════╗   │
│  ║  ★ REVIEW GATE 2: /codexspec.review-plan ★                        ║   │
│  ║  Validate: Spec Alignment, Architecture, Tech Stack, Phases       ║   │
│  ╚═══════════════════════════════════════════════════════════════════╝   │
│         │                                                                │
│         ▼                                                                │
│  6. Plan to Tasks  ─►  Generate atomic tasks with:                       │
│         │               • TDD enforcement (tests before impl)            │
│         │               • Parallel markers [P]                           │
│         │               • File path specifications                       │
│         ▼                                                                │
│  ╔═══════════════════════════════════════════════════════════════════╗   │
│  ║  ★ REVIEW GATE 3: /codexspec.review-tasks ★                       ║   │
│  ║  Validate: Coverage, TDD Compliance, Dependencies, Granularity    ║   │
│  ╚═══════════════════════════════════════════════════════════════════╝   │
│         │                                                                │
│         ▼                                                                │
│  7. Analyze  ───────►  Cross-artifact consistency check                  │
│         │               Detect gaps, duplications, constitution issues   │
│         ▼                                                                │
│  8. Implement  ─────►  Execute with conditional TDD workflow             │
│                          Code: Test-first | Docs/Config: Direct          │
│                                                                          │
└──────────────────────────────────────────────────────────────────────────┘

Key Insight: Each review gate (★) is a human checkpoint where you validate AI output before investing more time. Skipping these gates often leads to costly rework.

Key Concept: Requirement Clarification Workflow

CodexSpec provides two distinct clarification commands for different stages of the workflow:

specify vs clarify: When to Use Which?

Aspect	/codexspec.specify	/codexspec.clarify
Purpose	Initial requirement exploration	Iterative refinement of existing spec
When to Use	Starting with a new idea, no spec.md exists	spec.md exists, need to fill gaps
Input	Your initial idea or requirement	Existing spec.md file
Output	None (dialogue only)	Updates spec.md with clarifications
Method	Open-ended Q&A	Structured ambiguity scan (4 categories)
Question Limit	Unlimited	Maximum 5 questions
Typical Use	"I want to build a todo app"	"The spec is missing error handling details"

Two-Phase Specification

Before generating any documentation:

Phase	Command	Purpose	Output
Explore	/codexspec.specify	Interactive Q&A to explore and refine requirements	None (dialogue only)
Generate	/codexspec.generate-spec	Compile clarified requirements into structured document	spec.md

Iterative Clarification

After spec.md is created:

spec.md ──► /codexspec.clarify ──► Updated spec.md (with Clarifications section)
                │
                └── Scans for ambiguities in 4 focused categories:
                    • Completeness Gaps - Missing sections, empty content
                    • Specificity Issues - Vague terms, undefined constraints
                    • Behavioral Clarity - Error handling, state transitions
                    • Measurability Problems - Non-functional requirements without metrics

Benefits of This Design

• Human-AI collaboration: You actively participate in requirement discovery
• Explicit control: Files are only created when you decide
• Quality focus: Requirements are thoroughly explored before documentation
• Iterative refinement: Specs can be improved incrementally as understanding deepens

Project Structure

After initialization, your project will have this structure:

my-project/
├── .codexspec/
│   ├── memory/
│   │   └── constitution.md    # Project governing principles
│   ├── specs/
│   │   └── {feature-id}/
│   │       ├── spec.md        # Feature specification
│   │       ├── plan.md        # Technical plan
│   │       ├── tasks.md       # Task breakdown
│   │       └── checklists/    # Quality checklists
│   ├── templates/             # Custom templates
│   ├── scripts/               # Helper scripts
│   │   ├── bash/              # Bash scripts
│   │   └── powershell/        # PowerShell scripts
│   └── extensions/            # Custom extensions
├── .claude/
│   └── commands/              # Slash commands for Claude Code
└── CLAUDE.md                  # Context for Claude Code

Internationalization (i18n)

CodexSpec supports multiple languages through LLM dynamic translation. Instead of maintaining translated templates, we let Claude translate content at runtime based on your language configuration.

Setting Language

During initialization:

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

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

After initialization:

# View current configuration
codexspec config

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

# Set commit messages to English (while keeping output in Chinese)
codexspec config --set-commit-lang en

# List supported languages
codexspec config --list-langs

Commit Message Language

You can configure a different language for commit messages than the output language:

# Use Chinese for interactions but English for commit messages
codexspec config --set-lang zh-CN
codexspec config --set-commit-lang en

Language priority for commit messages:

1. language.commit setting (if specified)
2. language.output (fallback)
3. "en" (default)

Note: The commit type (feat, fix, docs, etc.) and scope always remain in English. Only the description part uses the configured language.

Configuration File

The .codexspec/config.yml file stores language settings:

version: "1.0"

language:
  # Output language for Claude interactions and generated documents
  output: "zh-CN"

  # Commit message language (defaults to output language)
  # Set to "en" for English commit messages regardless of output language
  commit: "zh-CN"

  # Template language - keep as "en" for compatibility
  templates: "en"

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

Supported Languages

Code	Language
en	English (default)
zh-CN	Chinese (Simplified)
zh-TW	Chinese (Traditional)
ja	Japanese
ko	Korean
es	Spanish
fr	French
de	German
pt	Portuguese
ru	Russian
it	Italian
ar	Arabic
hi	Hindi

How It Works

1. Single English Templates: All command templates remain in English
2. Language Configuration: Project specifies preferred output language
3. Dynamic Translation: Claude reads English instructions, outputs in target language
4. Context-Aware: Technical terms (JWT, OAuth, etc.) remain in English when appropriate

Benefits

• Zero Translation Maintenance: No need to maintain multiple template versions
• Always Up-to-Date: Template updates automatically benefit all languages
• Context-Aware Translation: Claude provides natural, context-appropriate translations
• Unlimited Languages: Any language supported by Claude works immediately

Constitution and Generated Documents

When you use /codexspec.constitution to create your project constitution, it will be generated in the language specified in your configuration:

• Single File Approach: Constitution is generated in one language only
• Claude Understands All Languages: Claude can work with constitution files in any supported language
• Team Collaboration: Teams should use a consistent working language

This design avoids synchronization issues between multiple language versions and reduces maintenance overhead.

Extension System

CodexSpec supports a plugin architecture for adding custom commands:

Extension Structure

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

Creating Extensions

1. Copy the template from extensions/template/
2. Modify extension.yml with your extension details
3. Add your custom commands in commands/
4. Test locally and publish

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

Development

Prerequisites

• Python 3.11+
• uv package manager
• Git

Local Development

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

# Install development dependencies
uv sync --dev

# Run locally
uv run codexspec --help

# Run tests
uv run pytest

# Lint code
uv run ruff check src/

Building

# Build the package
uv build

Comparison with spec-kit

CodexSpec is inspired by GitHub's spec-kit but with some key differences:

Feature	spec-kit	CodexSpec
Core Philosophy	Spec-driven development	Spec-driven development + human-AI collaboration
CLI Name	specify	codexspec
Primary AI	Multi-agent support	Claude Code focused
Command Prefix	/speckit.*	/codexspec.*
Constitution System	Basic	Full constitution with cross-artifact validation
Two-Phase Spec	No	Yes (clarify + generate)
Review Commands	Optional	3 dedicated review commands with scoring
Clarify Command	Yes	4 focused categories, review integration
Analyze Command	Yes	Read-only, severity-based, constitution-aware
TDD in Tasks	Optional	Enforced (tests precede implementation)
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

1. Review-First Culture: Every major artifact has a dedicated review command
2. Constitution Governance: Principles are validated, not just documented
3. TDD by Default: Test-first methodology enforced in task generation
4. Human Checkpoints: Workflow designed around validation gates

Philosophy

CodexSpec follows these core principles:

SDD Fundamentals

1. Intent-driven development: Specifications define the "what" before the "how"
2. Rich specification creation: Use guardrails and organizational principles
3. Multi-step refinement: Rather than one-shot code generation
4. Constitution governance: Project principles guide all decisions

Human-AI Collaboration

5. Human-in-the-loop: AI generates artifacts, humans validate them
6. Review-oriented: Validate each artifact before moving forward
7. Progressive disclosure: Complex information revealed incrementally
8. Explicit over implicit: Requirements should be clear, not assumed

Quality Assurance

9. Test-driven by default: TDD workflow built into task generation
10. Cross-artifact consistency: Analyze spec, plan, and tasks together
11. Constitution alignment: All artifacts respect project principles

Why Review Matters

Without Review	With Review
AI makes incorrect assumptions	Human catches misinterpretations early
Incomplete requirements propagate	Gaps identified before implementation
Architecture drifts from intent	Alignment verified at each stage
Tasks miss critical functionality	Coverage validated systematically
Result: Rework, wasted effort	Result: Right first time

Contributing

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

License

MIT License - see LICENSE for details.

Acknowledgements

• Inspired by GitHub spec-kit
• Built for Claude Code