From be90bb747f41e6fe5509badfb6a7aede651e50c2 Mon Sep 17 00:00:00 2001 From: SiaoZeng Date: Fri, 12 Sep 2025 21:26:14 +0800 Subject: [PATCH] feat: Add OpenAI Codex CLI support to spec-kit Add comprehensive integration for OpenAI Codex CLI as the fourth supported AI assistant alongside Claude Code, Gemini CLI, and GitHub Copilot. Changes: - Add 'codex' option to AI_CHOICES with proper tool validation - Extend update-agent-context.sh script to support CODEX.md files - Create CODEX-template.md with SDD workflow and configuration guidance - Update plan template to reference Codex CLI integration - Add usage instructions and next steps for Codex CLI workflow - Update .gitignore to exclude user-specific git sync scripts The integration follows the established pattern for AI assistant support: - Tool validation with installation instructions - Context file generation and management - SDD workflow integration (/specify, /plan, /tasks commands) - Template-based project setup --- .gitignore | 3 + scripts/update-agent-context.sh | 25 +++++--- src/specify_cli/__init__.py | 16 ++++- templates/CODEX-template.md | 107 ++++++++++++++++++++++++++++++++ templates/plan-template.md | 2 +- 5 files changed, 143 insertions(+), 10 deletions(-) create mode 100644 templates/CODEX-template.md diff --git a/.gitignore b/.gitignore index 21c7cd0174..a8fdd6b0bc 100644 --- a/.gitignore +++ b/.gitignore @@ -38,3 +38,6 @@ env/ .env .env.local *.lock + +# Git sync script (user-specific) +git_sync_repo.bash diff --git a/scripts/update-agent-context.sh b/scripts/update-agent-context.sh index 21b77aaa07..d11913895f 100755 --- a/scripts/update-agent-context.sh +++ b/scripts/update-agent-context.sh @@ -14,6 +14,7 @@ NEW_PLAN="$FEATURE_DIR/plan.md" CLAUDE_FILE="$REPO_ROOT/CLAUDE.md" GEMINI_FILE="$REPO_ROOT/GEMINI.md" COPILOT_FILE="$REPO_ROOT/.github/copilot-instructions.md" +CODEX_FILE="$REPO_ROOT/CODEX.md" # Allow override via argument AGENT_TYPE="$1" @@ -46,14 +47,19 @@ update_agent_file() { if [ ! -f "$target_file" ]; then echo "Creating new $agent_name context file..." - # Check if this is the SDD repo itself - if [ -f "$REPO_ROOT/templates/agent-file-template.md" ]; then - cp "$REPO_ROOT/templates/agent-file-template.md" "$temp_file" + # Check if this is the SDD repo itself and select appropriate template + local template_file + if [[ "$agent_name" == *"Codex"* ]] && [ -f "$REPO_ROOT/templates/CODEX-template.md" ]; then + template_file="$REPO_ROOT/templates/CODEX-template.md" + elif [ -f "$REPO_ROOT/templates/agent-file-template.md" ]; then + template_file="$REPO_ROOT/templates/agent-file-template.md" else echo "ERROR: Template not found at $REPO_ROOT/templates/agent-file-template.md" return 1 fi + cp "$template_file" "$temp_file" + # Replace placeholders sed -i.bak "s/\[PROJECT NAME\]/$(basename $REPO_ROOT)/" "$temp_file" sed -i.bak "s/\[DATE\]/$(date +%Y-%m-%d)/" "$temp_file" @@ -197,20 +203,24 @@ case "$AGENT_TYPE" in "copilot") update_agent_file "$COPILOT_FILE" "GitHub Copilot" ;; + "codex") + update_agent_file "$CODEX_FILE" "OpenAI Codex CLI" + ;; "") # Update all existing files [ -f "$CLAUDE_FILE" ] && update_agent_file "$CLAUDE_FILE" "Claude Code" [ -f "$GEMINI_FILE" ] && update_agent_file "$GEMINI_FILE" "Gemini CLI" [ -f "$COPILOT_FILE" ] && update_agent_file "$COPILOT_FILE" "GitHub Copilot" + [ -f "$CODEX_FILE" ] && update_agent_file "$CODEX_FILE" "OpenAI Codex CLI" # If no files exist, create based on current directory or ask user - if [ ! -f "$CLAUDE_FILE" ] && [ ! -f "$GEMINI_FILE" ] && [ ! -f "$COPILOT_FILE" ]; then + if [ ! -f "$CLAUDE_FILE" ] && [ ! -f "$GEMINI_FILE" ] && [ ! -f "$COPILOT_FILE" ] && [ ! -f "$CODEX_FILE" ]; then echo "No agent context files found. Creating Claude Code context file by default." update_agent_file "$CLAUDE_FILE" "Claude Code" fi ;; *) - echo "ERROR: Unknown agent type '$AGENT_TYPE'. Use: claude, gemini, copilot, or leave empty for all." + echo "ERROR: Unknown agent type '$AGENT_TYPE'. Use: claude, gemini, copilot, codex, or leave empty for all." exit 1 ;; esac @@ -227,8 +237,9 @@ if [ ! -z "$NEW_DB" ] && [ "$NEW_DB" != "N/A" ]; then fi echo "" -echo "Usage: $0 [claude|gemini|copilot]" +echo "Usage: $0 [claude|gemini|copilot|codex]" echo " - No argument: Update all existing agent context files" echo " - claude: Update only CLAUDE.md" echo " - gemini: Update only GEMINI.md" -echo " - copilot: Update only .github/copilot-instructions.md" \ No newline at end of file +echo " - copilot: Update only .github/copilot-instructions.md" +echo " - codex: Update only CODEX.md" \ No newline at end of file diff --git a/src/specify_cli/__init__.py b/src/specify_cli/__init__.py index 94ac3deabf..90e2c1b83d 100644 --- a/src/specify_cli/__init__.py +++ b/src/specify_cli/__init__.py @@ -51,7 +51,8 @@ AI_CHOICES = { "copilot": "GitHub Copilot", "claude": "Claude Code", - "gemini": "Gemini CLI" + "gemini": "Gemini CLI", + "codex": "OpenAI Codex CLI" } # ASCII Art Banner @@ -737,6 +738,10 @@ def init( if not check_tool("gemini", "Install from: https://github.com/google-gemini/gemini-cli"): console.print("[red]Error:[/red] Gemini CLI is required for Gemini projects") agent_tool_missing = True + elif selected_ai == "codex": + if not check_tool("codex", "Install with: npm install -g @openai/codex"): + console.print("[red]Error:[/red] OpenAI Codex CLI is required for Codex projects") + agent_tool_missing = True # GitHub Copilot check is not needed as it's typically available in supported IDEs if agent_tool_missing: @@ -824,6 +829,12 @@ def init( steps_lines.append(" - See GEMINI.md for all available commands") elif selected_ai == "copilot": steps_lines.append(f"{step_num}. Open in Visual Studio Code and use [bold cyan]/specify[/], [bold cyan]/plan[/], [bold cyan]/tasks[/] commands with GitHub Copilot") + elif selected_ai == "codex": + steps_lines.append(f"{step_num}. Run [bold cyan]codex[/] and use the SDD workflow commands") + steps_lines.append(" - Run codex '/specify [description]' to create specifications") + steps_lines.append(" - Run codex '/plan [tech details]' to create implementation plans") + steps_lines.append(" - Run codex '/tasks' to generate executable tasks") + steps_lines.append(" - See CODEX.md for context and configuration") step_num += 1 steps_lines.append(f"{step_num}. Update [bold magenta]CONSTITUTION.md[/bold magenta] with your project's non-negotiable principles") @@ -856,11 +867,12 @@ def check(): console.print("\n[cyan]Optional AI tools:[/cyan]") claude_ok = check_tool("claude", "Install from: https://docs.anthropic.com/en/docs/claude-code/setup") gemini_ok = check_tool("gemini", "Install from: https://github.com/google-gemini/gemini-cli") + codex_ok = check_tool("codex", "Install with: npm install -g @openai/codex") console.print("\n[green]✓ Specify CLI is ready to use![/green]") if not git_ok: console.print("[yellow]Consider installing git for repository management[/yellow]") - if not (claude_ok or gemini_ok): + if not (claude_ok or gemini_ok or codex_ok): console.print("[yellow]Consider installing an AI assistant for the best experience[/yellow]") diff --git a/templates/CODEX-template.md b/templates/CODEX-template.md new file mode 100644 index 0000000000..1f1b0fbbd1 --- /dev/null +++ b/templates/CODEX-template.md @@ -0,0 +1,107 @@ +# [PROJECT NAME] - OpenAI Codex CLI Integration + +Auto-generated from all feature plans. Last updated: [DATE] + +## Overview + +This project uses **Specification-Driven Development (SDD)** with OpenAI Codex CLI. Codex CLI is a lightweight coding agent that runs locally and can read, modify, and run code on your local machine to help build features faster, squash bugs, and understand unfamiliar code. + +## Active Technologies +[EXTRACTED FROM ALL PLAN.MD FILES] + +## Project Structure +``` +[ACTUAL STRUCTURE FROM PLANS] +``` + +## SDD Workflow with Codex CLI + +### 1. Specification Phase +```bash +codex "/specify [feature description]" +``` +Creates a detailed specification from natural language description. The specification includes user stories, functional requirements, and acceptance criteria. + +### 2. Planning Phase +```bash +codex "/plan [technical details and constraints]" +``` +Generates technical implementation plan based on the specification. Includes architecture decisions, technology choices, and constitutional compliance checks. + +### 3. Task Generation +```bash +codex "/tasks" +``` +Breaks down the plan into executable tasks following Test-Driven Development principles. + +## Commands for Active Technologies +[ONLY COMMANDS FOR ACTIVE TECHNOLOGIES] + +## Code Style Guidelines +[LANGUAGE-SPECIFIC, ONLY FOR LANGUAGES IN USE] + +## Codex CLI Configuration + +### Basic Usage +- **Interactive TUI**: Run `codex` for interactive mode +- **Direct prompts**: Use `codex "your prompt here"` +- **Non-interactive**: Use `codex exec "your prompt"` + +### Key Flags +- `--model/-m`: Select AI model +- `--ask-for-approval/-a`: Enable approval prompts +- `--full-auto`: Enable full automation mode + +### Authentication +Codex CLI supports: +- **ChatGPT plan** (recommended): Sign in with your ChatGPT Plus/Pro/Team/Enterprise account +- **API key**: Alternative setup for usage-based billing + +### Configuration File +Edit `~/.codex/config.toml` for persistent settings: +```toml +# Model selection +default_model = "gpt-4" + +# Approval settings +ask_for_approval = true + +# MCP server support +[mcp_servers] +# Add your MCP servers here +``` + +## Recent Changes +[LAST 3 FEATURES AND WHAT THEY ADDED] + +## Constitutional Principles + +This project follows strict constitutional principles: +- **Library-First**: Every feature starts as a standalone library +- **Test-First**: TDD is non-negotiable (RED-GREEN-REFACTOR cycle) +- **CLI Interface**: Every library exposes functionality via CLI +- **Integration Testing**: Use real dependencies, not mocks + +See `memory/constitution.md` for complete details. + +## Tips for Codex CLI + +### Effective Prompts +- Be specific about what you want to build and why +- Include context about your tech stack and constraints +- Reference existing code patterns when applicable + +### SDD Best Practices +- Always start with `/specify` to create clear specifications +- Use `/plan` to make technical decisions explicit +- Break work into small, testable tasks with `/tasks` +- Follow the constitutional principles for code quality + +### Error Handling +- If Codex gets stuck, provide more specific context +- Use `codex --ask-for-approval` for safer execution +- Check `~/.codex/config.toml` for configuration issues + + + + \ No newline at end of file diff --git a/templates/plan-template.md b/templates/plan-template.md index f28a655d47..3d9f8503c9 100644 --- a/templates/plan-template.md +++ b/templates/plan-template.md @@ -16,7 +16,7 @@ → Update Progress Tracking: Initial Constitution Check 4. Execute Phase 0 → research.md → If NEEDS CLARIFICATION remain: ERROR "Resolve unknowns" -5. Execute Phase 1 → contracts, data-model.md, quickstart.md, agent-specific template file (e.g., `CLAUDE.md` for Claude Code, `.github/copilot-instructions.md` for GitHub Copilot, or `GEMINI.md` for Gemini CLI). +5. Execute Phase 1 → contracts, data-model.md, quickstart.md, agent-specific template file (e.g., `CLAUDE.md` for Claude Code, `.github/copilot-instructions.md` for GitHub Copilot, `GEMINI.md` for Gemini CLI, or `CODEX.md` for OpenAI Codex CLI). 6. Re-evaluate Constitution Check section → If new violations: Refactor design, return to Phase 1 → Update Progress Tracking: Post-Design Constitution Check