codexspec 0.6.4__tar.gz → 0.7.0__tar.gz

{codexspec-0.6.4 → codexspec-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codexspec
-Version: 0.6.4
+Version: 0.7.0
 Summary: CodexSpec - A Requirements-First SDD toolkit for Claude Code
 Project-URL: Homepage, https://github.com/Zts0hg/codexspec
 Project-URL: Repository, https://github.com/Zts0hg/codexspec
@@ -251,6 +251,9 @@ uvx codexspec init my-project
 # Initialize in existing project
 cd your-existing-project
 uvx codexspec init . --ai claude
+
+# Initialize for Codex CLI
+uvx codexspec init . --ai codex
 ```
 
 #### Install Development Version from GitHub
@@ -530,7 +533,7 @@ Implementation follows **conditional TDD workflow**:
 | --------------- | ------------------------------------- |
 | `PROJECT_NAME`  | Project directory name (`.` or `--here` for current dir) |
 | `--here`, `-h`  | Initialize in the current directory   |
-| `--ai`, `-a`    | AI assistant to use (default: claude) |
+| `--ai`, `-a`    | AI assistant to use: `claude`, `codex`, or `both` (default: claude) |
 | `--lang`, `-l`  | Output (base) language; interaction/document/commit fall back to it (e.g., en, zh-CN, ja) |
 | `--interaction-lang` | Interaction language (LLM dialogue + CLI output); overrides `--lang` |
 | `--document-lang` | Document language (generated spec/plan/tasks); overrides `--lang` |
@@ -738,7 +741,10 @@ my-project/
 │   └── extensions/            # Custom extensions
 ├── .claude/
 │   └── commands/              # Claude Code slash commands
-└── CLAUDE.md                  # Claude Code context
+├── .agents/
+│   └── skills/                # Codex skills (when initialized with --ai codex or both)
+├── CLAUDE.md                  # Claude Code context
+└── AGENTS.md                  # Codex context
 ```
 
 ---

{codexspec-0.6.4 → codexspec-0.7.0}/README.md

@@ -206,6 +206,9 @@ uvx codexspec init my-project
 # Initialize in existing project
 cd your-existing-project
 uvx codexspec init . --ai claude
+
+# Initialize for Codex CLI
+uvx codexspec init . --ai codex
 ```
 
 #### Install Development Version from GitHub
@@ -485,7 +488,7 @@ Implementation follows **conditional TDD workflow**:
 | --------------- | ------------------------------------- |
 | `PROJECT_NAME`  | Project directory name (`.` or `--here` for current dir) |
 | `--here`, `-h`  | Initialize in the current directory   |
-| `--ai`, `-a`    | AI assistant to use (default: claude) |
+| `--ai`, `-a`    | AI assistant to use: `claude`, `codex`, or `both` (default: claude) |
 | `--lang`, `-l`  | Output (base) language; interaction/document/commit fall back to it (e.g., en, zh-CN, ja) |
 | `--interaction-lang` | Interaction language (LLM dialogue + CLI output); overrides `--lang` |
 | `--document-lang` | Document language (generated spec/plan/tasks); overrides `--lang` |
@@ -693,7 +696,10 @@ my-project/
 │   └── extensions/            # Custom extensions
 ├── .claude/
 │   └── commands/              # Claude Code slash commands
-└── CLAUDE.md                  # Claude Code context
+├── .agents/
+│   └── skills/                # Codex skills (when initialized with --ai codex or both)
+├── CLAUDE.md                  # Claude Code context
+└── AGENTS.md                  # Codex context
 ```
 
 ---

{codexspec-0.6.4 → codexspec-0.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "codexspec"
-version = "0.6.4"
+version = "0.7.0"
 description = "CodexSpec - A Requirements-First SDD toolkit for Claude Code"
 readme = "README.md"
 requires-python = ">=3.11"

{codexspec-0.6.4 → codexspec-0.7.0}/src/codexspec/__init__.py

@@ -6,6 +6,7 @@ This toolkit provides a structured approach to software development using
 executable specifications that guide AI-assisted implementation.
 """
 
+import re
 import subprocess
 import sys
 from datetime import datetime
@@ -38,10 +39,11 @@ from .i18n import (
     normalize_locale,
     update_language_field,
 )
+from .integrations import get_integrations
 from .translator import SUPPORTED_LANGUAGES, translate
 
 # Version info
-__version__ = "0.6.0"
+__version__ = "0.7.0"
 __author__ = "CodexSpec Team"
 
 # Constitution file path constants
@@ -471,9 +473,11 @@ def init(
         "--force",
         "-f",
         help=(
-            "Overwrite existing files and auto-confirm prompts (skips the language "
-            "prompt and command-update/migration confirms). Language config is updated "
-            "surgically, never fully regenerated."
+            "Overwrite regenerable files (commands/scripts) and auto-confirm prompts "
+            "(skips the language prompt and command-update/migration confirms). "
+            "User-authored content is preserved: language config is updated surgically "
+            "and an existing CLAUDE.md body is never overwritten (only the constitution "
+            "@import is prepended if missing)."
         ),
     ),
     no_git: bool = typer.Option(
@@ -510,6 +514,14 @@ def init(
     interaction_lang = interaction_lang if isinstance(interaction_lang, str) else None
     document_lang = document_lang if isinstance(document_lang, str) else None
     commit_lang = commit_lang if isinstance(commit_lang, str) else None
+    ai = ai if isinstance(ai, str) else "claude"
+    ai = ai.lower().strip()
+    try:
+        integrations = get_integrations(ai)
+    except ValueError as exc:
+        console.print(f"[red]Error:[/red] {exc}")
+        raise typer.Exit(1) from exc
+    integration_keys = {integration.key for integration in integrations}
 
     # Determine target directory first — needed to detect an existing config.yml
     # before resolving the language base (REQ-007).
@@ -659,65 +671,74 @@ def init(
     else:
         console.print("[yellow]Warning: Docs templates directory not found[/yellow]")
 
-    # Create .claude/commands directory for slash commands
-    claude_dir = target_dir / ".claude"
-    claude_commands_dir = claude_dir / "commands"
-    claude_commands_dir.mkdir(parents=True, exist_ok=True)
-
-    # Target subdirectory for CodexSpec commands
-    codexspec_commands_dir = claude_commands_dir / COMMANDS_SUBDIR
-
     # Get templates directory
     templates_dir = get_templates_dir() / "commands"
-
-    # Check for old structure and migrate if needed
-    old_files = detect_old_structure(claude_dir)
-    migration_happened = False
-    if old_files:
-        console.print()
+    if not templates_dir.exists():
+        # Templates directory is part of the wheel; if it's missing the
+        # install is broken and we cannot recover.
         console.print(
-            f"[yellow]{translate('cli.init.migration_found', normalized_lang, count=len(old_files))}[/yellow]"
+            f"[red]{translate('cli.init.error_templates_missing', normalized_lang, path=str(templates_dir))}[/red]"
         )
-        console.print(f"[dim]{translate('cli.init.migration_old_structure', normalized_lang)}[/dim]")
-        console.print(f"[dim]{translate('cli.init.migration_new_structure', normalized_lang)}[/dim]")
+        raise typer.Exit(1)
 
-        if force or Confirm.ask(translate("cli.init.migration_confirm", normalized_lang), default=True):
-            if migrate_old_commands(claude_dir, old_files):
-                console.print(f"[green]{translate('cli.init.migration_complete', normalized_lang)}[/green]")
-                migration_happened = True
-            else:
-                console.print(f"[red]{translate('cli.init.migration_failed', normalized_lang)}[/red]")
-        else:
-            console.print(f"[dim]{translate('cli.init.migration_skipped', normalized_lang)}[/dim]")
-
-    # Install or update commands (translate after migration if user wants)
-    if migration_happened:
-        # Migration moved files, ask if user wants to update/translate them
-        if force or Confirm.ask(translate("cli.init.update_confirm", normalized_lang), default=True):
-            count = install_commands_to_subdir(
-                codexspec_commands_dir, templates_dir, force=True, language=normalized_lang
-            )
-            console.print(f"[green]{translate('cli.init.commands_updated', normalized_lang, count=count)}[/green]")
-    elif should_update_commands(codexspec_dir):
-        console.print()
-        if force or Confirm.ask(translate("cli.init.update_confirm", normalized_lang), default=True):
-            count = install_commands_to_subdir(
-                codexspec_commands_dir, templates_dir, force=True, language=normalized_lang
-            )
-            console.print(f"[green]{translate('cli.init.commands_updated', normalized_lang, count=count)}[/green]")
-    else:
-        if not templates_dir.exists():
-            # Templates directory is part of the wheel; if it's missing the
-            # install is broken and we cannot recover.
+    if "claude" in integration_keys:
+        # Create .claude/commands directory for slash commands
+        claude_dir = target_dir / ".claude"
+        claude_commands_dir = claude_dir / "commands"
+        claude_commands_dir.mkdir(parents=True, exist_ok=True)
+
+        # Target subdirectory for CodexSpec commands
+        codexspec_commands_dir = claude_commands_dir / COMMANDS_SUBDIR
+
+        # Check for old structure and migrate if needed
+        old_files = detect_old_structure(claude_dir)
+        migration_happened = False
+        if old_files:
+            console.print()
             console.print(
-                f"[red]{translate('cli.init.error_templates_missing', normalized_lang, path=str(templates_dir))}[/red]"
+                f"[yellow]{translate('cli.init.migration_found', normalized_lang, count=len(old_files))}[/yellow]"
             )
-            raise typer.Exit(1)
+            console.print(f"[dim]{translate('cli.init.migration_old_structure', normalized_lang)}[/dim]")
+            console.print(f"[dim]{translate('cli.init.migration_new_structure', normalized_lang)}[/dim]")
+
+            if force or Confirm.ask(translate("cli.init.migration_confirm", normalized_lang), default=True):
+                if migrate_old_commands(claude_dir, old_files):
+                    console.print(f"[green]{translate('cli.init.migration_complete', normalized_lang)}[/green]")
+                    migration_happened = True
+                else:
+                    console.print(f"[red]{translate('cli.init.migration_failed', normalized_lang)}[/red]")
+            else:
+                console.print(f"[dim]{translate('cli.init.migration_skipped', normalized_lang)}[/dim]")
+
+        # Install or update commands (translate after migration if user wants)
+        if migration_happened:
+            # Migration moved files, ask if user wants to update/translate them
+            if force or Confirm.ask(translate("cli.init.update_confirm", normalized_lang), default=True):
+                count = install_commands_to_subdir(
+                    codexspec_commands_dir, templates_dir, force=True, language=normalized_lang
+                )
+                console.print(f"[green]{translate('cli.init.commands_updated', normalized_lang, count=count)}[/green]")
+        elif should_update_commands(codexspec_dir):
+            console.print()
+            if force or Confirm.ask(translate("cli.init.update_confirm", normalized_lang), default=True):
+                count = install_commands_to_subdir(
+                    codexspec_commands_dir, templates_dir, force=True, language=normalized_lang
+                )
+                console.print(f"[green]{translate('cli.init.commands_updated', normalized_lang, count=count)}[/green]")
+        else:
+            count = install_commands_to_subdir(codexspec_commands_dir, templates_dir, language=normalized_lang)
+            cmd_path = f".claude/commands/{COMMANDS_SUBDIR}/"
+            msg = translate("cli.init.commands_installed", normalized_lang, count=count, path=cmd_path)
+            console.print(f"[green]{msg}[/green]")
 
-        count = install_commands_to_subdir(codexspec_commands_dir, templates_dir, language=normalized_lang)
-        cmd_path = f".claude/commands/{COMMANDS_SUBDIR}/"
-        msg = translate("cli.init.commands_installed", normalized_lang, count=count, path=cmd_path)
-        console.print(f"[green]{msg}[/green]")
+    for integration in integrations:
+        if integration.key == "claude":
+            continue
+        count = integration.install(target_dir, templates_dir, force=force, language=normalized_lang)
+        console.print(
+            f"[green]{translate('cli.init.commands_installed', normalized_lang, count=count, path='.agents/skills/')}"
+            "[/green]"
+        )
 
     # Create constitution template
     constitution_file = codexspec_dir / "memory" / "constitution.md"
@@ -747,6 +768,7 @@ def init(
                 commit=keys_to_write.get("commit"),
                 created=datetime.now().strftime("%Y-%m-%d"),
             )
+            config_content = _set_config_ai_content(config_content, ai)
             config_file.write_text(config_content, encoding="utf-8")
             wrote_keys = list(keys_to_write.keys())
             lang_name = get_language_name(normalized_lang)
@@ -761,6 +783,8 @@ def init(
             for key, value in keys_to_write.items():
                 if update_language_field(config_file, key, value):
                     wrote_keys.append(key)
+    if config_file.exists():
+        _update_project_ai(config_file, ai)
 
     # Non-blocking notice of which language keys were set (REQ-010).
     if wrote_keys:
@@ -771,18 +795,23 @@ def init(
     if prompted_base:
         console.print(f"[dim]{translate('cli.init.language_dimensions_hint', normalized_lang)}[/dim]")
 
-    # Create CLAUDE.md
-    claude_md = target_dir / "CLAUDE.md"
-    if not claude_md.exists() or force:
-        project_name = target_dir.name
-        claude_md.write_text(_get_claude_md_content(project_name), encoding="utf-8")
-        console.print(f"[green]{translate('cli.init.created_file', normalized_lang, file='CLAUDE.md')}[/green]")
-    else:
-        # Check if existing CLAUDE.md has compliance section
-        if not has_compliance_section(claude_md):
-            if confirm_add_compliance(normalized_lang):
-                prepend_compliance_section(claude_md)
-                console.print(f"[green]{translate('cli.init.compliance_added', normalized_lang)}[/green]")
+    if "claude" in integration_keys:
+        # Create CLAUDE.md
+        # CLAUDE.md is user-authored content (like the constitution), not a
+        # regenerable artifact (like commands/scripts). Never overwrite an existing
+        # body -- even under --force. --force only auto-confirms the one safe,
+        # idempotent change: prepending the constitution @import if it is missing.
+        claude_md = target_dir / "CLAUDE.md"
+        if not claude_md.exists():
+            project_name = target_dir.name
+            claude_md.write_text(_get_claude_md_content(project_name), encoding="utf-8")
+            console.print(f"[green]{translate('cli.init.created_file', normalized_lang, file='CLAUDE.md')}[/green]")
+        else:
+            # Existing CLAUDE.md: ensure the compliance @import, never clobber the body.
+            if not has_compliance_section(claude_md):
+                if force or confirm_add_compliance(normalized_lang):
+                    prepend_compliance_section(claude_md)
+                    console.print(f"[green]{translate('cli.init.compliance_added', normalized_lang)}[/green]")
 
     # Initialize git if requested
     if not no_git and not (target_dir / ".git").exists():
@@ -794,7 +823,7 @@ def init(
 
     # Print success message with command summary
     console.print()
-    _print_command_summary(normalized_lang)
+    _print_command_summary(normalized_lang, ai=ai)
 
     project_nav = project_name if project_name and project_name != "." else "."
     console.print(
@@ -803,9 +832,9 @@ def init(
             f"{translate('cli.init.success_project_dir', normalized_lang, path=str(target_dir))}\n\n"
             f"[bold]{translate('cli.init.next_steps', normalized_lang)}[/bold]\n"
             f"1. {translate('cli.init.next_step_navigate', normalized_lang, path=project_nav)}\n"
-            f"2. {translate('cli.init.next_step_start_claude', normalized_lang)}\n"
-            f"3. {translate('cli.init.next_step_constitution', normalized_lang)}\n"
-            f"4. {translate('cli.init.next_step_specify', normalized_lang)}",
+            f"2. {_next_step_start(integration_keys, normalized_lang)}\n"
+            f"3. {_next_step_invocation(integrations, 'constitution')}\n"
+            f"4. {_next_step_invocation(integrations, 'specify')}",
             title=translate("cli.init.success_title", normalized_lang),
         )
     )
@@ -813,7 +842,7 @@ def init(
     # Git management tip
     console.print()
     console.print(f"[bold]{translate('cli.init.tips_header', normalized_lang)}[/bold]")
-    console.print(f"   - {translate('cli.init.tips_git', normalized_lang)}")
+    console.print(f"   - {_git_tip(integration_keys, normalized_lang)}")
     console.print(f"   - {translate('cli.init.tips_list_commands', normalized_lang)}")
     console.print(f"   - {translate('cli.init.tips_edit', normalized_lang)}")
 
@@ -822,7 +851,7 @@ def init(
     important_header = translate("cli.init.important_header", normalized_lang)
     important_msg = translate("cli.init.important_message", normalized_lang)
     console.print(f"[yellow]{important_header}[/yellow] {important_msg}")
-    console.print(f"[yellow]{translate('cli.init.important_action', normalized_lang)}[/yellow]")
+    console.print(f"[yellow]{_important_action(integrations, normalized_lang)}[/yellow]")
 
 
 def _rerender_command_frontmatter(config_file: Path) -> None:
@@ -848,9 +877,65 @@ def _rerender_command_frontmatter(config_file: Path) -> None:
     console.print(f"[dim]Updated command descriptions to: {get_language_name(language)}[/dim]")
 
 
-def _print_command_summary(language: str = "en") -> None:
+def _set_config_ai_content(content: str, ai: str) -> str:
+    """Set project.ai in freshly generated config content."""
+    return content.replace('  ai: "claude"', f'  ai: "{ai}"')
+
+
+def _update_project_ai(config_file: Path, ai: str) -> None:
+    """Update the project.ai field in config.yml when present."""
+    try:
+        content = config_file.read_text(encoding="utf-8")
+        updated, count = re.subn(
+            r'^(\s*ai:\s*)["\']?[^"\'\n]+["\']?\s*$',
+            rf'\g<1>"{ai}"',
+            content,
+            flags=re.MULTILINE,
+        )
+        if count:
+            config_file.write_text(updated, encoding="utf-8")
+    except OSError:
+        return
+
+
+def _next_step_start(integration_keys: set[str], language: str) -> str:
+    """Return a target-aware start instruction."""
+    if integration_keys == {"codex"}:
+        return "Start Codex in this project directory: codex"
+    if integration_keys == {"claude", "codex"}:
+        return "Start Claude Code or Codex in this project directory"
+    return translate("cli.init.next_step_start_claude", language)
+
+
+def _next_step_invocation(integrations: list, command_name: str) -> str:
+    """Return a target-aware next-step command invocation."""
+    invocation = integrations[0].invocation_for(command_name)
+    if command_name == "constitution":
+        return f"Use {invocation} to establish project principles"
+    return f"Use {invocation} to create your first specification"
+
+
+def _git_tip(integration_keys: set[str], language: str) -> str:
+    """Return a target-aware git management tip."""
+    if integration_keys == {"codex"}:
+        return "Add .agents/ to Git if you want Codex skills versioned: git add .agents/"
+    if integration_keys == {"claude", "codex"}:
+        return "Add .claude/ and .agents/ to Git if you want AI entrypoints versioned"
+    return translate("cli.init.tips_git", language)
+
+
+def _important_action(integrations: list, language: str) -> str:
+    """Return target-aware constitution command reminder."""
+    if integrations and integrations[0].key == "codex":
+        return f"Run {integrations[0].invocation_for('constitution')} to customize it for your project."
+    return translate("cli.init.important_action", language)
+
+
+def _print_command_summary(language: str = "en", ai: str = "claude") -> None:
     """Print a summary of installed commands grouped by category."""
     metadata = get_commands_metadata()
+    integrations = get_integrations(ai)
+    primary = integrations[0]
 
     # Group by category
     categories: dict[str, list] = {
@@ -865,16 +950,20 @@ def _print_command_summary(language: str = "en") -> None:
         if cat in categories:
             categories[cat].append(cmd)
 
-    console.print(
-        f"[bold]{translate('cli.init.commands_summary', language, count=len(metadata), path=COMMANDS_SUBDIR)}[/bold]"
-    )
+    if primary.key == "claude":
+        summary = translate("cli.init.commands_summary", language, count=len(metadata), path=COMMANDS_SUBDIR)
+        console.print(f"[bold]{summary}[/bold]")
+    elif ai == "both":
+        console.print(f"[bold]Installed {len(metadata)} CodexSpec entrypoints for Claude Code and Codex CLI[/bold]")
+    else:
+        console.print(f"[bold]Installed {len(metadata)} CodexSpec skills to .agents/skills/[/bold]")
     console.print()
 
     for cat, commands in categories.items():
         if commands:
             console.print(f"  [bold]{translate(f'cli.init.category_{cat}', language, count=len(commands))}[/bold]")
             for cmd in commands:
-                console.print(f"    [cyan]{cmd['display_name']}[/cyan]")
+                console.print(f"    [cyan]{primary.invocation_for(cmd['name'])}[/cyan]")
             console.print()
 
 

codexspec-0.7.0/src/codexspec/integrations/__init__.py

@@ -0,0 +1,20 @@
+"""AI coding tool integrations for CodexSpec."""
+
+from .base import Integration
+from .claude import ClaudeIntegration
+from .codex import CodexIntegration
+
+
+def get_integrations(ai: str) -> list[Integration]:
+    """Resolve the requested AI target into concrete integrations."""
+    normalized = ai.strip().lower()
+    if normalized == "claude":
+        return [ClaudeIntegration()]
+    if normalized == "codex":
+        return [CodexIntegration()]
+    if normalized == "both":
+        return [ClaudeIntegration(), CodexIntegration()]
+    raise ValueError(f"Unsupported AI assistant: {ai}")
+
+
+__all__ = ["ClaudeIntegration", "CodexIntegration", "Integration", "get_integrations"]

codexspec-0.7.0/src/codexspec/integrations/base.py

@@ -0,0 +1,20 @@
+"""Shared integration protocol."""
+
+from pathlib import Path
+from typing import Protocol
+
+
+class Integration(Protocol):
+    """Protocol implemented by each AI coding tool integration."""
+
+    key: str
+    display_name: str
+    context_file: str
+
+    def invocation_for(self, command_name: str) -> str:
+        """Return the user-facing invocation for a CodexSpec command."""
+        ...
+
+    def install(self, target_dir: Path, templates_dir: Path, *, force: bool = False, language: str = "en") -> int:
+        """Install this integration into target_dir."""
+        ...

codexspec-0.7.0/src/codexspec/integrations/claude.py

@@ -0,0 +1,25 @@
+"""Claude Code integration."""
+
+from pathlib import Path
+
+from codexspec.commands.installer import COMMANDS_SUBDIR, install_commands_to_subdir
+
+
+class ClaudeIntegration:
+    """Installs CodexSpec as Claude Code slash commands."""
+
+    key = "claude"
+    display_name = "Claude Code"
+    context_file = "CLAUDE.md"
+
+    def invocation_for(self, command_name: str) -> str:
+        """Return the Claude slash command invocation."""
+        return f"/codexspec:{command_name}"
+
+    def commands_dir(self, target_dir: Path) -> Path:
+        """Return the Claude command destination."""
+        return target_dir / ".claude" / "commands" / COMMANDS_SUBDIR
+
+    def install(self, target_dir: Path, templates_dir: Path, *, force: bool = False, language: str = "en") -> int:
+        """Install Claude slash command templates."""
+        return install_commands_to_subdir(self.commands_dir(target_dir), templates_dir, force=force, language=language)

codexspec-0.7.0/src/codexspec/integrations/codex.py

@@ -0,0 +1,170 @@
+"""Codex CLI integration."""
+
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from codexspec.commands.installer import get_commands_metadata
+from codexspec.translator import load_translation_cache, translate_template_frontmatter
+
+CODEXSPEC_CONTEXT_START = "<!-- CODEXSPEC START -->"
+CODEXSPEC_CONTEXT_END = "<!-- CODEXSPEC END -->"
+
+
+class CodexIntegration:
+    """Installs CodexSpec as Codex skills."""
+
+    key = "codex"
+    display_name = "Codex CLI"
+    context_file = "AGENTS.md"
+
+    def invocation_for(self, command_name: str) -> str:
+        """Return the Codex skill mention invocation."""
+        return f"$codexspec:{command_name}"
+
+    def skills_dir(self, target_dir: Path) -> Path:
+        """Return the Codex skills destination."""
+        return target_dir / ".agents" / "skills"
+
+    def install(self, target_dir: Path, templates_dir: Path, *, force: bool = False, language: str = "en") -> int:
+        """Install Codex skills and the Codex context file."""
+        count = self.install_skills(target_dir, templates_dir, force=force, language=language)
+        self.ensure_context_file(target_dir)
+        return count
+
+    def install_skills(
+        self,
+        target_dir: Path,
+        templates_dir: Path,
+        *,
+        force: bool = False,
+        language: str = "en",
+    ) -> int:
+        """Render command templates into Codex SKILL.md files."""
+        if not templates_dir.exists():
+            return 0
+
+        descriptions = {cmd["file_name"]: cmd["description"] for cmd in get_commands_metadata()}
+        translation_cache = None
+        if language != "en":
+            translation_cache = load_translation_cache(language)
+
+        installed_count = 0
+        for template_file in sorted(templates_dir.glob("*.md")):
+            command_name = template_file.stem
+            skill_dir = self.skills_dir(target_dir) / f"codexspec-{command_name}"
+            skill_file = skill_dir / "SKILL.md"
+            if skill_file.exists() and not force:
+                continue
+
+            content = template_file.read_text(encoding="utf-8")
+            content = translate_template_frontmatter(content, command_name, language, translation_cache)
+            skill_content = self.render_skill(command_name, content, descriptions.get(template_file.name, ""))
+            skill_dir.mkdir(parents=True, exist_ok=True)
+            skill_file.write_text(skill_content, encoding="utf-8")
+            installed_count += 1
+
+        return installed_count
+
+    def ensure_context_file(self, target_dir: Path) -> None:
+        """Create or update AGENTS.md with a managed CodexSpec section."""
+        context_path = target_dir / self.context_file
+        existing = context_path.read_text(encoding="utf-8") if context_path.exists() else ""
+        section = self._context_section()
+
+        pattern = re.compile(
+            rf"{re.escape(CODEXSPEC_CONTEXT_START)}.*?{re.escape(CODEXSPEC_CONTEXT_END)}",
+            re.DOTALL,
+        )
+        if pattern.search(existing):
+            updated = pattern.sub(section.strip(), existing)
+        elif existing.strip():
+            updated = existing.rstrip() + "\n\n" + section
+        else:
+            updated = "# AGENTS.md\n\n" + section
+
+        context_path.write_text(updated, encoding="utf-8")
+
+    def render_skill(self, command_name: str, content: str, fallback_description: str = "") -> str:
+        """Render one command template into a Codex SKILL.md."""
+        frontmatter, body = _split_frontmatter(content)
+        description = str(frontmatter.get("description") or fallback_description or f"CodexSpec {command_name}")
+        body = _render_script_placeholders(body, frontmatter)
+        body = _render_codex_body(command_name, body)
+
+        return f"---\nname: codexspec:{command_name}\ndescription: {_yaml_scalar(description)}\n---\n\n{body.strip()}\n"
+
+    def _context_section(self) -> str:
+        return f"""{CODEXSPEC_CONTEXT_START}
+## CodexSpec
+
+This project uses CodexSpec for requirements-first spec-driven development.
+
+Use these Codex skills when working on CodexSpec workflows:
+
+- `$codexspec:constitution` to create or update project principles.
+- `$codexspec:specify` to capture confirmed requirements.
+- `$codexspec:generate-spec` to produce `spec.md`.
+- `$codexspec:spec-to-plan` to produce `plan.md`.
+- `$codexspec:plan-to-tasks` to produce `tasks.md`.
+- `$codexspec:implement-tasks` to implement approved tasks.
+
+Before making workflow decisions, read `.codexspec/memory/constitution.md`.
+{CODEXSPEC_CONTEXT_END}
+"""
+
+
+def _split_frontmatter(content: str) -> tuple[dict[str, Any], str]:
+    if not content.startswith("---"):
+        return {}, content
+    parts = content.split("---", 2)
+    if len(parts) < 3:
+        return {}, content
+    try:
+        parsed = yaml.safe_load(parts[1]) or {}
+    except yaml.YAMLError:
+        parsed = {}
+    if not isinstance(parsed, dict):
+        parsed = {}
+    return parsed, parts[2]
+
+
+def _render_script_placeholders(body: str, frontmatter: dict[str, Any]) -> str:
+    scripts = frontmatter.get("scripts")
+    if not isinstance(scripts, dict):
+        return body
+    preferred = "ps" if sys.platform == "win32" else "sh"
+    default_command = str(scripts.get(preferred) or scripts.get("sh") or scripts.get("ps") or "")
+    sh_command = str(scripts.get("sh") or default_command)
+    ps_command = str(scripts.get("ps") or default_command)
+
+    lines: list[str] = []
+    for line in body.splitlines(keepends=True):
+        if "{SCRIPT}" not in line:
+            lines.append(line)
+        elif "PowerShell:" in line:
+            lines.append(line.replace("{SCRIPT}", ps_command))
+        elif "Bash:" in line:
+            lines.append(line.replace("{SCRIPT}", sh_command))
+        else:
+            lines.append(line.replace("{SCRIPT}", default_command))
+    return "".join(lines)
+
+
+def _render_codex_body(command_name: str, body: str) -> str:
+    arg_text = f"the text after the $codexspec:{command_name} skill mention"
+    body = body.replace("$ARGUMENTS", arg_text)
+    body = body.replace("{ARGS}", arg_text)
+    return re.sub(r"/codexspec:([A-Za-z0-9-]+)", r"$codexspec:\1", body)
+
+
+def _yaml_scalar(value: str) -> str:
+    if re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9 _.,:/()'\"-]*", value):
+        return value
+    escaped = value.replace("\\", "\\\\").replace('"', '\\"')
+    return f'"{escaped}"'

{codexspec-0.6.4 → codexspec-0.7.0}/templates/commands/implement-tasks.md

@@ -133,10 +133,103 @@ When encountering problems, create/update `issues.md` in the same directory as `
 - **Status**: Blocked / Workaround Found / Needs Discussion
 ```
 
-### 6. Completion
+### 6. Pre-Review Baseline
 
-After all tasks:
+After all tasks are implemented:
 
-- Run full test suite (if applicable)
-- Final commit if needed
-- Report completion summary with files modified
+- Run the full test suite.
+- Confirm the suite is green. This green state is the baseline for the Final
+  Code Review Loop; no auto-fix may regress it. If the suite is already red at
+  this point, stop and fix the implementation before reviewing.
+
+### 7. Final Code Review Loop
+
+After the baseline is green, review the implemented code and auto-fix verified
+defects. This mirrors the `review-spec` / `review-plan` / `review-tasks` loops
+the sibling generation commands run.
+
+#### 7.1 Determine the Review Target
+
+Review only the analyzable code changed by this implementation, not the whole
+repository and not per task. Compute the candidate file set:
+
+```
+git diff --name-only $(git merge-base HEAD <main>)..HEAD
+git diff --name-only                       # uncommitted tracked changes
+git ls-files --others --exclude-standard   # untracked files
+```
+
+`<main>` is the project's default branch, resolved from `git.main_branches` in
+`.codexspec/config.yml` (default: `main`, `master`, `develop`).
+
+Then filter the candidate set:
+
+- Keep only analyzable source extensions: `.py .ts .tsx .js .jsx .go .rs .java
+  .kt .kts .rb .sh .bash .zsh .c .h .cpp .hpp .cc .cxx .cs .swift .php`.
+- Exclude `.codexspec/specs/` and generated/vendored paths (e.g. `dist/`,
+  lockfiles, `.venv/`).
+
+If the filtered set is empty (e.g. the implementation produced only docs,
+config, or assets), report "no code to review", skip this loop, and proceed to
+step 8.
+
+Fallback: if git is unavailable or the current branch is not a feature branch
+(so the diff base cannot be determined), review the project's primary source
+directory as `/codexspec:review-code` would by default, and explicitly note the
+degraded fidelity (the review may include pre-existing code).
+
+#### 7.2 Invoke the Review
+
+Invoke `/codexspec:review-code <filtered-paths>`.
+
+`/codexspec:review-code` is **review-only**; it produces findings and scores but
+does not edit code. Apply every fix **yourself**, under this command's tool
+scope (which includes `Edit`/`Write` and running the test suite via `Bash`).
+
+#### 7.3 Auto-Fix Scope
+
+- Auto-fix **CRITICAL, HIGH, and MEDIUM** findings only.
+- **LOW** (suggestion) findings are report-only; never auto-fix them.
+- A **MEDIUM** finding is auto-fixed only when it is grounded in
+  `.codexspec/memory/constitution.md` and the confirmed requirements/spec, and
+  it concerns **maintainability, readability, or testability**. Ungrounded or
+  purely stylistic MEDIUM findings are report-only.
+- Do not auto-fix advisories or design opportunities, and do not introduce any
+  new product decision.
+
+#### 7.4 Test-Safe Fixes (never ship red)
+
+Every fix must be test-safe. A fix that breaks tests is, by definition, an
+incorrect change — it is never shipped and never silently skipped.
+
+- **Functional defects** (logic, correctness, security): follow TDD — add a
+  failing test that reproduces the defect (red), apply the fix until that test
+  passes (green), then refactor while tests stay green.
+- **Non-functional fixes** (refactors for maintainability, readability,
+  testability): run the suite before and after the change. If the change turns
+  any test red, revert it, confirm the suite is green again, and re-attempt the
+  refactor.
+- If a fix cannot be made green after retry, treat it as **unresolved** and stop
+  (see 7.5).
+
+#### 7.5 Loop Bounds and Stop Conditions
+
+- Run at most **two** fix-and-review rounds. (The per-fix TDD retry in 7.4
+  happens within a round; the two-round limit bounds overall effort.)
+- Stop when a defect repeats, remains unresolved, or requires a user or
+  architecture decision.
+- After each green round, commit the fixes (see step 8).
+
+#### 7.6 Terminal Status
+
+- If CRITICAL or HIGH defects remain unresolved after the maximum rounds, the
+  status is **"needs work"** — do not claim success.
+- Otherwise report the review outcome: scores, items fixed, items deferred, and
+  the final test status.
+
+### 8. Final Report and Commit
+
+- Commit any review-driven changes from step 7 that are not already committed.
+- Report the completion summary: files modified, review status (scores, items
+  fixed, items deferred, final test status), and the overall status (success or
+  "needs work").