codexspec: Instructions file for Claude Code

@.codexspec/memory/constitution.md @docs/internal/repository-layout.md

CLAUDE.md - CodexSpec Development Guide

This document provides comprehensive context and guidelines for Claude Code when working on the CodexSpec project itself.

Project Overview

CodexSpec is a Requirements-First SDD toolkit for Claude Code. It is a Python CLI tool that can be installed via uv tool install and provides structured slash commands for AI-assisted software development.

Purpose

CodexSpec helps developers:

• Establish project principles through a constitution
• Create detailed specifications focused on "what" and "why"
• Generate technical implementation plans
• Break down plans into actionable tasks
• Execute implementations systematically
• Validate quality through checklists and analysis

Technology Stack

• Language: Python 3.11+
• CLI Framework: Typer (with Rich for formatting)
• Package Manager: uv
• Build System: Hatchling
• Testing: pytest
• Linting: ruff

Architecture

CLI Architecture

The CLI is built using Typer and follows a modular structure:

# Main entry point
app = typer.Typer(
    name="codexspec",
    help="CodexSpec - A Requirements-First SDD toolkit for Claude Code",
)

# Commands
@app.command()
def init(...): ...

@app.command()
def check(...): ...

@app.command()
def version(...): ...

@app.command()
def config(...): ...  # NEW: Configuration management

Internationalization (i18n) Architecture

CodexSpec uses LLM-based dynamic translation for internationalization instead of maintaining multiple template translations.

Core Concept: Keep templates in English, let Claude translate at runtime based on user's language preference.

Implementation:

1. src/codexspec/i18n.py - Language utilities (normalization, validation)
2. .codexspec/config.yml - Per-project language configuration
3. Template ## Language Preference section - Instructs Claude to check config