nexus-dev-toolkit 3.1.8__tar.gz → 3.1.10__tar.gz

{nexus_dev_toolkit-3.1.8/nexus_dev_toolkit.egg-info → nexus_dev_toolkit-3.1.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nexus-dev-toolkit
-Version: 3.1.8
+Version: 3.1.10
 Summary: Developer workflow toolkit for Claude Code — Day 0 scaffold + Day 1 EPAV
 Author-email: Ronald dela Cruz <rcdelacruz@users.noreply.github.com>
 License-Expression: MIT
@@ -22,7 +22,7 @@ Dynamic: license-file
 # nexus-dev-toolkit
 
 
-Developer workflow toolkit for Claude Code and OpenCode. Gives any team a structured Day 0 scaffold and repeatable Day 1 feature cycle via the EPAV methodology.
+Developer workflow toolkit for Claude Code, OpenCode and Codex. Gives any team a structured Day 0 scaffold and repeatable Day 1 feature cycle via the EPAV methodology.
 
 **[Documentation](https://nexus.coderstudio.co/docs)**
 
@@ -89,6 +89,7 @@ uv tool install nexus-dev-toolkit
 cd my-project
 nexus init .                                        # Claude Code (default), prompts for graphify/codegraph/none
 nexus init . --tool opencode                        # OpenCode
+nexus init . --tool codex                           # Codex
 nexus init . --graph-backend codegraph              # skip the prompt, use codegraph
 ```
 
@@ -174,6 +175,20 @@ knowledge/             ← same structure
 opencode.json          ← MCP server config
 ```
 
+**Codex** (`nexus init . --tool codex`):
+```
+.agents/skills/<name>/
+├── SKILL.md           ← same EPAV + reviewer skills — invoke with $evaluate, $plan, …
+└── agents/openai.yaml ← EPAV steps only: blocks implicit invocation, so Codex never starts $apply on its own
+.codex/
+├── agents/*.toml      ← same reviewer subagents (converted to Codex TOML)
+├── config.toml        ← [mcp_servers.nexus] (appended — your existing config is never rewritten)
+└── hooks.json         ← PostToolUse: graphify auto-update (graphify backend only)
+knowledge/             ← same structure
+```
+
+Codex only loads project `.codex/` config and hooks for **trusted** projects — trust the project when Codex asks.
+
 ---
 
 ## Commands
@@ -181,6 +196,7 @@ opencode.json          ← MCP server config
 ```bash
 nexus init .                      # Claude Code — set up .claude/ + knowledge/ + .mcp.json
 nexus init . --tool opencode      # OpenCode — set up .opencode/ + knowledge/ + opencode.json
+nexus init . --tool codex         # Codex — set up .agents/skills/ + .codex/ + knowledge/
 nexus --version                   # show installed version
 nexus update                      # update the CLI itself; asks whether to also sync in a real terminal
 nexus update --sync               # skip the prompt, always sync the current project's skills/agents too

{nexus_dev_toolkit-3.1.8 → nexus_dev_toolkit-3.1.10}/README.md

@@ -1,7 +1,7 @@
 # nexus-dev-toolkit
 
 
-Developer workflow toolkit for Claude Code and OpenCode. Gives any team a structured Day 0 scaffold and repeatable Day 1 feature cycle via the EPAV methodology.
+Developer workflow toolkit for Claude Code, OpenCode and Codex. Gives any team a structured Day 0 scaffold and repeatable Day 1 feature cycle via the EPAV methodology.
 
 **[Documentation](https://nexus.coderstudio.co/docs)**
 
@@ -68,6 +68,7 @@ uv tool install nexus-dev-toolkit
 cd my-project
 nexus init .                                        # Claude Code (default), prompts for graphify/codegraph/none
 nexus init . --tool opencode                        # OpenCode
+nexus init . --tool codex                           # Codex
 nexus init . --graph-backend codegraph              # skip the prompt, use codegraph
 ```
 
@@ -153,6 +154,20 @@ knowledge/             ← same structure
 opencode.json          ← MCP server config
 ```
 
+**Codex** (`nexus init . --tool codex`):
+```
+.agents/skills/<name>/
+├── SKILL.md           ← same EPAV + reviewer skills — invoke with $evaluate, $plan, …
+└── agents/openai.yaml ← EPAV steps only: blocks implicit invocation, so Codex never starts $apply on its own
+.codex/
+├── agents/*.toml      ← same reviewer subagents (converted to Codex TOML)
+├── config.toml        ← [mcp_servers.nexus] (appended — your existing config is never rewritten)
+└── hooks.json         ← PostToolUse: graphify auto-update (graphify backend only)
+knowledge/             ← same structure
+```
+
+Codex only loads project `.codex/` config and hooks for **trusted** projects — trust the project when Codex asks.
+
 ---
 
 ## Commands
@@ -160,6 +175,7 @@ opencode.json          ← MCP server config
 ```bash
 nexus init .                      # Claude Code — set up .claude/ + knowledge/ + .mcp.json
 nexus init . --tool opencode      # OpenCode — set up .opencode/ + knowledge/ + opencode.json
+nexus init . --tool codex         # Codex — set up .agents/skills/ + .codex/ + knowledge/
 nexus --version                   # show installed version
 nexus update                      # update the CLI itself; asks whether to also sync in a real terminal
 nexus update --sync               # skip the prompt, always sync the current project's skills/agents too

{nexus_dev_toolkit-3.1.8 → nexus_dev_toolkit-3.1.10}/nexus_cli.py

@@ -1,4 +1,5 @@
 import json
+import re
 import shutil
 import subprocess
 import sys
@@ -12,7 +13,7 @@ from rich.table import Table
 
 from tools.epav import graph_backend
 
-app = typer.Typer(name="nexus", no_args_is_help=False, help="nexus-dev-toolkit — Day 0 scaffold + Day 1 EPAV workflow for Claude Code and OpenCode")
+app = typer.Typer(name="nexus", no_args_is_help=False, help="nexus-dev-toolkit — Day 0 scaffold + Day 1 EPAV workflow for Claude Code, OpenCode and Codex")
 skill_app = typer.Typer(name="skill", no_args_is_help=True, help="Manage skills in .claude/commands/")
 rule_app = typer.Typer(name="rule", no_args_is_help=True, help="Manage rules in knowledge/rules/")
 agent_app = typer.Typer(name="agent", no_args_is_help=True, help="Manage subagents in .claude/agents/")
@@ -22,7 +23,7 @@ app.add_typer(agent_app, name="agent")
 
 console = Console()
 
-_VERSION = "3.1.8"
+_VERSION = "3.1.10"
 
 
 def _fetch_latest_pypi_version() -> str | None:
@@ -174,6 +175,37 @@ export const GraphifyPlugin = async ({ directory }) => {
 """
 
 
+# ── Codex ─────────────────────────────────────────────────────────────────────
+
+_CODEX_MCP_TOML = """\
+[mcp_servers.nexus]
+command = "uvx"
+args = ["--refresh", "--from", "nexus-dev-toolkit", "nexus-mcp"]
+"""
+
+_CODEX_HOOKS = {
+    "hooks": {
+        "PostToolUse": [
+            {
+                "matcher": "Edit|Write",
+                "hooks": [
+                    {
+                        "type": "command",
+                        "command": "graphify update . --force 2>/dev/null || true"
+                    }
+                ]
+            }
+        ]
+    }
+}
+
+# EPAV steps are user-driven — Codex must never start /apply or /commit on its own.
+_CODEX_EXPLICIT_ONLY_YAML = """\
+policy:
+  allow_implicit_invocation: false
+"""
+
+
 def _init_project(project_dir: Path, backend: str = "graphify") -> list[str]:
     """
     nexus init — sets up:
@@ -297,6 +329,140 @@ def _init_opencode(project_dir: Path, backend: str = "graphify") -> list[str]:
     return created
 
 
+def _split_frontmatter(content: str) -> tuple[dict[str, str], str]:
+    """Parse a simple `key: value` frontmatter block. ({}, content) if there isn't one."""
+    if not content.startswith("---"):
+        return {}, content
+    parts = content.split("---", 2)
+    if len(parts) < 3:
+        return {}, content
+    fields = {}
+    for line in parts[1].splitlines():
+        key, sep, value = line.partition(":")
+        if sep:
+            fields[key.strip()] = value.strip()
+    return fields, parts[2].lstrip("\n")
+
+
+# "/plan" → "$plan": Codex invokes skills with $, and "/" belongs to its own built-in commands.
+# The lookbehind skips paths like docs/scaffold or ./plan.
+_SKILL_REF_RE = re.compile(r"(?<![\w/.])/(" + "|".join(re.escape(Path(s).stem) for s in _BUILTIN_SKILLS) + r")\b")
+
+
+def _to_codex_skill(skill_name: str, content: str) -> tuple[str, str | None]:
+    """Convert a nexus skill to a Codex SKILL.md. Skills without frontmatter are the user-driven
+    EPAV steps — they get generated frontmatter plus an openai.yaml that blocks implicit invocation."""
+    content = _SKILL_REF_RE.sub(r"$\1", content)
+    fields, body = _split_frontmatter(content)
+    if fields.get("name") and fields.get("description"):
+        return content, None
+    name = Path(skill_name).stem
+    description = next(
+        (line.replace("**", "").strip() for line in body.splitlines() if line.strip() and not line.startswith("#")),
+        f"nexus {name} skill",
+    )
+    frontmatter = f"---\nname: {name}\ndescription: {json.dumps(description, ensure_ascii=False)}\n---\n\n"
+    return frontmatter + body, _CODEX_EXPLICIT_ONLY_YAML
+
+
+def _to_codex_agent(agent_name: str, content: str) -> str:
+    """Convert a nexus subagent (markdown + frontmatter) to a Codex agent TOML. Claude Code-only
+    fields (tools, model) are dropped — the agent inherits the parent session's model."""
+    fields, body = _split_frontmatter(content)
+    name = fields.get("name") or Path(agent_name).stem
+    # Multi-line literal string keeps the prompt readable; fall back to an escaped basic string
+    # in the unlikely case the body itself contains '''.
+    instructions = json.dumps(body, ensure_ascii=False) if "'''" in body else f"'''\n{body}'''"
+    return (
+        f"name = {json.dumps(name, ensure_ascii=False)}\n"
+        f"description = {json.dumps(fields.get('description', ''), ensure_ascii=False)}\n"
+        f"developer_instructions = {instructions}\n"
+    )
+
+
+def _write_codex_mcp_config(project_dir: Path) -> bool:
+    """Append the nexus MCP block to .codex/config.toml. Text-level only — Python 3.10 has no
+    tomllib, and appending never rewrites the user's TOML. True if the block was added."""
+    config = project_dir / ".codex" / "config.toml"
+    config.parent.mkdir(parents=True, exist_ok=True)
+    existing = config.read_text(encoding="utf-8") if config.exists() else ""
+    if "[mcp_servers.nexus]" in existing:
+        return False
+    if existing and not existing.endswith("\n"):
+        existing += "\n"
+    if existing:
+        existing += "\n"
+    config.write_text(existing + _CODEX_MCP_TOML, encoding="utf-8")
+    return True
+
+
+def _write_codex_hooks(project_dir: Path) -> bool:
+    """Merge the graphify PostToolUse hook into .codex/hooks.json. True if it was added."""
+    hooks_path = project_dir / ".codex" / "hooks.json"
+    hooks_path.parent.mkdir(parents=True, exist_ok=True)
+    existing: dict = {}
+    if hooks_path.exists():
+        try:
+            existing = json.loads(hooks_path.read_text())
+        except Exception:
+            return False  # never clobber a hooks file we can't parse
+    if "graphify update" in json.dumps(existing):
+        return False
+    existing.setdefault("hooks", {}).setdefault("PostToolUse", []).extend(_CODEX_HOOKS["hooks"]["PostToolUse"])
+    hooks_path.write_text(json.dumps(existing, indent=2))
+    return True
+
+
+def _init_codex(project_dir: Path, backend: str = "graphify") -> list[str]:
+    """
+    nexus init --tool codex — sets up:
+      .agents/skills/<name>/ ← built-in skills (SKILL.md, plus agents/openai.yaml for EPAV steps)
+      .codex/agents/         ← built-in subagents as TOML
+      .codex/config.toml     ← MCP server config (appended, never rewritten)
+      .codex/hooks.json      ← graphify PostToolUse hook (only when backend == "graphify")
+      knowledge/             ← empty scaffold
+    """
+    created = []
+
+    # .agents/skills/<name>/SKILL.md — Codex's project skill location
+    skills_dir = project_dir / ".agents" / "skills"
+    for skill_name in _BUILTIN_SKILLS:
+        src = _SKILLS_SRC / skill_name
+        dest_dir = skills_dir / Path(skill_name).stem
+        dest = dest_dir / "SKILL.md"
+        if src.exists() and not dest.exists():
+            skill_md, openai_yaml = _to_codex_skill(skill_name, src.read_text(encoding="utf-8"))
+            dest_dir.mkdir(parents=True, exist_ok=True)
+            dest.write_text(skill_md, encoding="utf-8")
+            if openai_yaml:
+                (dest_dir / "agents").mkdir(exist_ok=True)
+                (dest_dir / "agents" / "openai.yaml").write_text(openai_yaml, encoding="utf-8")
+            created.append(f".agents/skills/{dest_dir.name}/SKILL.md")
+
+    # .codex/agents/<name>.toml — built-in subagents converted to Codex's TOML format
+    agents_dir = project_dir / ".codex" / "agents"
+    agents_dir.mkdir(parents=True, exist_ok=True)
+    for agent_name in _BUILTIN_AGENTS:
+        src = _AGENTS_SRC / agent_name
+        dest = agents_dir / f"{Path(agent_name).stem}.toml"
+        if src.exists() and not dest.exists():
+            dest.write_text(_to_codex_agent(agent_name, src.read_text(encoding="utf-8")), encoding="utf-8")
+            created.append(f".codex/agents/{dest.name}")
+
+    if _write_codex_mcp_config(project_dir):
+        created.append(".codex/config.toml")
+
+    # .codex/hooks.json — graphify hook (codegraph syncs itself, no hook needed)
+    if backend == "graphify" and _write_codex_hooks(project_dir):
+        created.append(".codex/hooks.json")
+
+    # knowledge/ scaffold
+    for d in _KNOWLEDGE_DIRS:
+        (project_dir / d).mkdir(parents=True, exist_ok=True)
+
+    return created
+
+
 def _write_mcp_config(project_dir: Path) -> str:
     mcp_path = project_dir / ".mcp.json"
     existing: dict = {}
@@ -312,7 +478,7 @@ def _write_mcp_config(project_dir: Path) -> str:
 
 # ── Commands ──────────────────────────────────────────────────────────────────
 
-_SUPPORTED_TOOLS = ["claude", "opencode"]
+_SUPPORTED_TOOLS = ["claude", "opencode", "codex"]
 
 _TOOL_CHECK = {
     "claude": {
@@ -327,6 +493,12 @@ _TOOL_CHECK = {
         "install": "curl -fsSL https://opencode.ai/install | bash",
         "install_cmd": None,  # pipe install — run via shell
     },
+    "codex": {
+        "bin": "codex",
+        "name": "Codex",
+        "install": "npm install -g @openai/codex",
+        "install_cmd": ["npm", "install", "-g", "@openai/codex"],
+    },
 }
 
 
@@ -409,6 +581,14 @@ def init(
             console.print("  [yellow]·[/yellow]  Already initialized — nothing to do")
             return
         console.print(f"\n  [bold green]Done.[/bold green] Open [bold]{root}[/bold] in OpenCode and type [cyan]/scaffold[/cyan]\n")
+    elif tool == "codex":
+        created = _init_codex(root, backend)
+        for f in created:
+            console.print(f"  [green]✓[/green]  {f}")
+        if not created:
+            console.print("  [yellow]·[/yellow]  Already initialized — nothing to do")
+            return
+        console.print(f"\n  [bold green]Done.[/bold green] Run [bold]codex[/bold] in [bold]{root}[/bold], trust the project when asked (.codex/ config and hooks only load in trusted projects), and type [cyan]$scaffold[/cyan]\n")
     else:
         created = _init_project(root, backend)
         for f in created:
@@ -430,6 +610,7 @@ def update(
 ) -> None:
     """Update nexus-dev-toolkit to the latest version."""
     latest_version = _fetch_latest_pypi_version()
+    upgraded = False
     if latest_version and not _is_outdated(_VERSION, latest_version):
         console.print(f"\n  [green]✓[/green]  Already up to date (v{_VERSION}).\n")
     else:
@@ -439,6 +620,7 @@ def update(
         else:
             subprocess.run([sys.executable, "-m", "pip", "install", "--upgrade", "nexus-dev-toolkit"])
         console.print("\n  [green]✓[/green]  Done.\n")
+        upgraded = True
 
     if not also_sync:
         if sys.stdin.isatty():
@@ -454,6 +636,21 @@ def update(
             return
 
     root = Path(".").resolve()
+
+    if upgraded:
+        # This process's own _BUILTIN_SKILLS/_BUILTIN_AGENTS were imported before the upgrade
+        # subprocess above ran, so syncing in-process here would silently miss anything newly
+        # added in the version just installed. Re-exec `nexus sync` as a fresh process instead.
+        nexus_bin = shutil.which("nexus")
+        if nexus_bin:
+            subprocess.run([nexus_bin, "sync", str(root)])
+            return
+        console.print(
+            "  [yellow]⚠[/yellow]  Couldn't find [bold]nexus[/bold] on PATH to re-run sync in a fresh "
+            "process — syncing in-process instead, which may miss anything added in this exact "
+            "upgrade. Run [cyan]nexus sync[/cyan] again afterward to be sure.\n"
+        )
+
     table = _sync_project(root)
     if table is None:
         console.print("  [yellow]⚠[/yellow]  Current directory isn't a nexus project — skipping sync.\n")
@@ -464,13 +661,24 @@ def update(
     console.print()
 
 
+def _sync_file(table: Table, dst: Path, text: str, label: str) -> None:
+    """Write text to dst unless it's already identical, and record the result in table."""
+    dst.parent.mkdir(parents=True, exist_ok=True)
+    if dst.exists() and dst.read_text(encoding="utf-8") == text:
+        table.add_row(label, "[dim green]ok[/dim green]")
+    else:
+        dst.write_text(text, encoding="utf-8")
+        table.add_row(label, "[cyan]updated[/cyan]")
+
+
 def _sync_project(root: Path) -> Table | None:
-    """Sync built-in skills/agents into root. None if root isn't a nexus project (neither
-    .claude/ nor .opencode/ present) — callers decide how to handle that case."""
+    """Sync built-in skills/agents into root. None if root isn't a nexus project (none of
+    .claude/, .opencode/ or .codex/ present) — callers decide how to handle that case."""
     has_claude = (root / ".claude").is_dir()
     has_opencode = (root / ".opencode").is_dir()
+    has_codex = (root / ".codex").is_dir()
 
-    if not has_claude and not has_opencode:
+    if not has_claude and not has_opencode and not has_codex:
         return None
 
     table = Table(show_header=True, header_style="dim")
@@ -478,68 +686,52 @@ def _sync_project(root: Path) -> Table | None:
     table.add_column("Status")
 
     if has_claude:
-        (root / ".claude" / "commands").mkdir(parents=True, exist_ok=True)
-        (root / ".claude" / "agents").mkdir(parents=True, exist_ok=True)
-
         for fname in _BUILTIN_SKILLS:
             src = _SKILLS_SRC / fname
-            if not src.exists():
-                continue
-            dst = root / ".claude" / "commands" / fname
-            src_text = src.read_text(encoding="utf-8")
-            if dst.exists() and dst.read_text(encoding="utf-8") == src_text:
-                table.add_row(f".claude/commands/{fname}", "[dim green]ok[/dim green]")
-            else:
-                dst.write_text(src_text, encoding="utf-8")
-                table.add_row(f".claude/commands/{fname}", "[cyan]updated[/cyan]")
+            if src.exists():
+                _sync_file(table, root / ".claude" / "commands" / fname, src.read_text(encoding="utf-8"), f".claude/commands/{fname}")
 
         for fname in _BUILTIN_AGENTS:
             src = _AGENTS_SRC / fname
-            if not src.exists():
-                continue
-            dst = root / ".claude" / "agents" / fname
-            src_text = src.read_text(encoding="utf-8")
-            if dst.exists() and dst.read_text(encoding="utf-8") == src_text:
-                table.add_row(f".claude/agents/{fname}", "[dim green]ok[/dim green]")
-            else:
-                dst.write_text(src_text, encoding="utf-8")
-                table.add_row(f".claude/agents/{fname}", "[cyan]updated[/cyan]")
+            if src.exists():
+                _sync_file(table, root / ".claude" / "agents" / fname, src.read_text(encoding="utf-8"), f".claude/agents/{fname}")
 
     if has_opencode:
-        (root / ".opencode" / "commands").mkdir(parents=True, exist_ok=True)
-        (root / ".opencode" / "agents").mkdir(parents=True, exist_ok=True)
-        (root / ".opencode" / "plugins").mkdir(parents=True, exist_ok=True)
+        for fname in _BUILTIN_SKILLS:
+            src = _SKILLS_SRC / fname
+            if src.exists():
+                _sync_file(table, root / ".opencode" / "commands" / fname, src.read_text(encoding="utf-8"), f".opencode/commands/{fname}")
+
+        for fname in _BUILTIN_AGENTS:
+            src = _AGENTS_SRC / fname
+            if src.exists():
+                text = _strip_claude_frontmatter(src.read_text(encoding="utf-8"))
+                _sync_file(table, root / ".opencode" / "agents" / fname, text, f".opencode/agents/{fname}")
+
+        _sync_file(table, root / ".opencode" / "plugins" / "graphify.js", _OPENCODE_GRAPHIFY_PLUGIN, ".opencode/plugins/graphify.js")
 
+    if has_codex:
         for fname in _BUILTIN_SKILLS:
             src = _SKILLS_SRC / fname
             if not src.exists():
                 continue
-            dst = root / ".opencode" / "commands" / fname
-            src_text = src.read_text(encoding="utf-8")
-            if dst.exists() and dst.read_text(encoding="utf-8") == src_text:
-                table.add_row(f".opencode/commands/{fname}", "[dim green]ok[/dim green]")
-            else:
-                dst.write_text(src_text, encoding="utf-8")
-                table.add_row(f".opencode/commands/{fname}", "[cyan]updated[/cyan]")
+            stem = Path(fname).stem
+            skill_md, openai_yaml = _to_codex_skill(fname, src.read_text(encoding="utf-8"))
+            _sync_file(table, root / ".agents" / "skills" / stem / "SKILL.md", skill_md, f".agents/skills/{stem}/SKILL.md")
+            if openai_yaml:
+                _sync_file(table, root / ".agents" / "skills" / stem / "agents" / "openai.yaml", openai_yaml, f".agents/skills/{stem}/agents/openai.yaml")
 
         for fname in _BUILTIN_AGENTS:
             src = _AGENTS_SRC / fname
-            if not src.exists():
-                continue
-            dst = root / ".opencode" / "agents" / fname
-            src_text = _strip_claude_frontmatter(src.read_text(encoding="utf-8"))
-            if dst.exists() and dst.read_text(encoding="utf-8") == src_text:
-                table.add_row(f".opencode/agents/{fname}", "[dim green]ok[/dim green]")
-            else:
-                dst.write_text(src_text, encoding="utf-8")
-                table.add_row(f".opencode/agents/{fname}", "[cyan]updated[/cyan]")
-
-        plugin_dst = root / ".opencode" / "plugins" / "graphify.js"
-        if plugin_dst.exists() and plugin_dst.read_text(encoding="utf-8") == _OPENCODE_GRAPHIFY_PLUGIN:
-            table.add_row(".opencode/plugins/graphify.js", "[dim green]ok[/dim green]")
-        else:
-            plugin_dst.write_text(_OPENCODE_GRAPHIFY_PLUGIN, encoding="utf-8")
-            table.add_row(".opencode/plugins/graphify.js", "[cyan]updated[/cyan]")
+            if src.exists():
+                stem = Path(fname).stem
+                text = _to_codex_agent(fname, src.read_text(encoding="utf-8"))
+                _sync_file(table, root / ".codex" / "agents" / f"{stem}.toml", text, f".codex/agents/{stem}.toml")
+
+        # Only re-add the graphify hook where the project already opted into one.
+        if (root / ".codex" / "hooks.json").exists():
+            added = _write_codex_hooks(root)
+            table.add_row(".codex/hooks.json", "[cyan]updated[/cyan]" if added else "[dim green]ok[/dim green]")
 
     return table
 
@@ -595,16 +787,20 @@ def doctor(
     # ── Tool ─────────────────────────────────────────────────────────────────
     has_claude_bin = bool(shutil.which("claude"))
     has_opencode_bin = bool(shutil.which("opencode"))
+    has_codex_bin = bool(shutil.which("codex"))
     table.add_row("Claude Code", ok("installed") if has_claude_bin else warn("not found — install: npm install -g @anthropic-ai/claude-code"))
     table.add_row("OpenCode", ok("installed") if has_opencode_bin else warn("not found — install: curl -fsSL https://opencode.ai/install | bash"))
+    table.add_row("Codex", ok("installed") if has_codex_bin else warn("not found — install: npm install -g @openai/codex"))
 
     # ── Project ──────────────────────────────────────────────────────────────
     has_claude_dir = (root / ".claude").is_dir()
     has_opencode_dir = (root / ".opencode").is_dir()
-    initialized = has_claude_dir or has_opencode_dir
+    has_codex_dir = (root / ".codex").is_dir()
+    initialized = has_claude_dir or has_opencode_dir or has_codex_dir
+    tools_found = ['claude' if has_claude_dir else '', 'opencode' if has_opencode_dir else '', 'codex' if has_codex_dir else '']
     table.add_row(
         "nexus initialized",
-        ok(f"yes ({', '.join(filter(None, ['claude' if has_claude_dir else '', 'opencode' if has_opencode_dir else '']))})")
+        ok(f"yes ({', '.join(filter(None, tools_found))})")
         if initialized else fail("no — run nexus init")
     )
 
@@ -638,6 +834,16 @@ def doctor(
             except Exception:
                 table.add_row("opencode.json", warn("invalid JSON"))
 
+    # MCP config — Codex (text check: no tomllib on Python 3.10)
+    if has_codex_dir:
+        codex_config = root / ".codex" / "config.toml"
+        if not codex_config.exists():
+            table.add_row(".codex/config.toml", fail("missing"))
+        elif "[mcp_servers.nexus]" in codex_config.read_text(encoding="utf-8"):
+            table.add_row(".codex/config.toml", ok("nexus entry present"))
+        else:
+            table.add_row(".codex/config.toml", warn("exists but no [mcp_servers.nexus] entry"))
+
     # ── Skills & Agents ──────────────────────────────────────────────────────
     if has_claude_dir:
         cmd_dir = root / ".claude" / "commands"
@@ -673,6 +879,23 @@ def doctor(
         else:
             table.add_row("Built-in agents (OpenCode)", warn(f"{missing_oc_ag} missing — run nexus sync"))
 
+    if has_codex_dir:
+        cx_skills_dir = root / ".agents" / "skills"
+        present_cx = [f for f in _BUILTIN_SKILLS if (cx_skills_dir / Path(f).stem / "SKILL.md").exists()]
+        missing_cx = len(_BUILTIN_SKILLS) - len(present_cx)
+        if missing_cx == 0:
+            table.add_row("Built-in skills (Codex)", ok(f"all {len(_BUILTIN_SKILLS)} present"))
+        else:
+            table.add_row("Built-in skills (Codex)", warn(f"{missing_cx} missing — run nexus sync"))
+
+        cx_ag_dir = root / ".codex" / "agents"
+        present_cx_ag = [f for f in _BUILTIN_AGENTS if (cx_ag_dir / f"{Path(f).stem}.toml").exists()]
+        missing_cx_ag = len(_BUILTIN_AGENTS) - len(present_cx_ag)
+        if missing_cx_ag == 0:
+            table.add_row("Built-in agents (Codex)", ok(f"all {len(_BUILTIN_AGENTS)} present"))
+        else:
+            table.add_row("Built-in agents (Codex)", warn(f"{missing_cx_ag} missing — run nexus sync"))
+
     # ── Knowledge ────────────────────────────────────────────────────────────
     missing_dirs = [d for d in _KNOWLEDGE_DIRS if not (root / d).is_dir()]
     if not missing_dirs:

{nexus_dev_toolkit-3.1.8 → nexus_dev_toolkit-3.1.10/nexus_dev_toolkit.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nexus-dev-toolkit
-Version: 3.1.8
+Version: 3.1.10
 Summary: Developer workflow toolkit for Claude Code — Day 0 scaffold + Day 1 EPAV
 Author-email: Ronald dela Cruz <rcdelacruz@users.noreply.github.com>
 License-Expression: MIT
@@ -22,7 +22,7 @@ Dynamic: license-file
 # nexus-dev-toolkit
 
 
-Developer workflow toolkit for Claude Code and OpenCode. Gives any team a structured Day 0 scaffold and repeatable Day 1 feature cycle via the EPAV methodology.
+Developer workflow toolkit for Claude Code, OpenCode and Codex. Gives any team a structured Day 0 scaffold and repeatable Day 1 feature cycle via the EPAV methodology.
 
 **[Documentation](https://nexus.coderstudio.co/docs)**
 
@@ -89,6 +89,7 @@ uv tool install nexus-dev-toolkit
 cd my-project
 nexus init .                                        # Claude Code (default), prompts for graphify/codegraph/none
 nexus init . --tool opencode                        # OpenCode
+nexus init . --tool codex                           # Codex
 nexus init . --graph-backend codegraph              # skip the prompt, use codegraph
 ```
 
@@ -174,6 +175,20 @@ knowledge/             ← same structure
 opencode.json          ← MCP server config
 ```
 
+**Codex** (`nexus init . --tool codex`):
+```
+.agents/skills/<name>/
+├── SKILL.md           ← same EPAV + reviewer skills — invoke with $evaluate, $plan, …
+└── agents/openai.yaml ← EPAV steps only: blocks implicit invocation, so Codex never starts $apply on its own
+.codex/
+├── agents/*.toml      ← same reviewer subagents (converted to Codex TOML)
+├── config.toml        ← [mcp_servers.nexus] (appended — your existing config is never rewritten)
+└── hooks.json         ← PostToolUse: graphify auto-update (graphify backend only)
+knowledge/             ← same structure
+```
+
+Codex only loads project `.codex/` config and hooks for **trusted** projects — trust the project when Codex asks.
+
 ---
 
 ## Commands
@@ -181,6 +196,7 @@ opencode.json          ← MCP server config
 ```bash
 nexus init .                      # Claude Code — set up .claude/ + knowledge/ + .mcp.json
 nexus init . --tool opencode      # OpenCode — set up .opencode/ + knowledge/ + opencode.json
+nexus init . --tool codex         # Codex — set up .agents/skills/ + .codex/ + knowledge/
 nexus --version                   # show installed version
 nexus update                      # update the CLI itself; asks whether to also sync in a real terminal
 nexus update --sync               # skip the prompt, always sync the current project's skills/agents too

{nexus_dev_toolkit-3.1.8 → nexus_dev_toolkit-3.1.10}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "nexus-dev-toolkit"
-version = "3.1.8"
+version = "3.1.10"
 description = "Developer workflow toolkit for Claude Code — Day 0 scaffold + Day 1 EPAV"
 authors = [
     {name = "Ronald dela Cruz", email = "rcdelacruz@users.noreply.github.com"}

{nexus_dev_toolkit-3.1.8 → nexus_dev_toolkit-3.1.10}/tests/test_cli.py

@@ -310,6 +310,31 @@ def test_doctor_skips_version_row_when_pypi_unreachable(tmp_project):
     assert "nexus-dev-toolkit" not in result.output
 
 
+# ── built-in registration ────────────────────────────────────────────────────
+# A skill/agent .md file living under tools/epav/skills/ or tools/agents/ but
+# missing from _BUILTIN_SKILLS/_BUILTIN_AGENTS is exactly the bug that shipped
+# in v3.1.5 (fixed in v3.1.7) and that update --sync's stale-process bug (fixed
+# in v3.1.9) piggybacked on. These tests make "added the file, forgot the list
+# entry" fail CI instead of silently shipping.
+
+def test_all_skill_files_are_registered_as_builtin():
+    on_disk = {p.name for p in Path("tools/epav/skills").glob("*.md")}
+    assert on_disk == set(_BUILTIN_SKILLS), (
+        f"tools/epav/skills/*.md and _BUILTIN_SKILLS disagree — "
+        f"on disk but not registered: {on_disk - set(_BUILTIN_SKILLS)}; "
+        f"registered but missing from disk: {set(_BUILTIN_SKILLS) - on_disk}"
+    )
+
+
+def test_all_agent_files_are_registered_as_builtin():
+    on_disk = {p.name for p in Path("tools/agents").glob("*.md")}
+    assert on_disk == set(_BUILTIN_AGENTS), (
+        f"tools/agents/*.md and _BUILTIN_AGENTS disagree — "
+        f"on disk but not registered: {on_disk - set(_BUILTIN_AGENTS)}; "
+        f"registered but missing from disk: {set(_BUILTIN_AGENTS) - on_disk}"
+    )
+
+
 # ── update ────────────────────────────────────────────────────────────────────
 
 def test_update_already_up_to_date_skips_upgrade(monkeypatch):
@@ -367,6 +392,43 @@ def test_update_with_sync_flag_syncs_current_project(monkeypatch, tmp_project):
     assert "scaffold.md" in output
 
 
+def test_update_with_sync_flag_reexecs_sync_after_real_upgrade(monkeypatch, tmp_project):
+    """After an actual upgrade, sync must run as a fresh `nexus sync` process, not in-process —
+    this process's own _BUILTIN_SKILLS/_BUILTIN_AGENTS were imported before the upgrade ran, so
+    calling _sync_project() directly here would silently miss anything the upgrade just added."""
+    import nexus_cli
+    monkeypatch.setattr("nexus_cli._fetch_latest_pypi_version", lambda: "99.0.0")
+    calls = []
+    monkeypatch.setattr("nexus_cli.subprocess.run", lambda cmd, *a, **k: calls.append(cmd))
+    monkeypatch.setattr("nexus_cli.shutil.which", lambda name: f"/usr/bin/{name}")
+
+    def _boom(root):
+        raise AssertionError("_sync_project must not run in-process after a real upgrade")
+    monkeypatch.setattr("nexus_cli._sync_project", _boom)
+
+    runner.invoke(app, ["init", str(tmp_project)])
+    monkeypatch.chdir(tmp_project)
+    result = runner.invoke(app, ["update", "--sync"])
+
+    assert result.exit_code == 0
+    assert calls[0] == ["uv", "tool", "upgrade", "nexus-dev-toolkit"]
+    assert calls[1] == ["/usr/bin/nexus", "sync", str(tmp_project.resolve())]
+
+
+def test_update_sync_falls_back_in_process_when_nexus_not_on_path(monkeypatch, tmp_project):
+    import nexus_cli
+    monkeypatch.setattr("nexus_cli._fetch_latest_pypi_version", lambda: "99.0.0")
+    monkeypatch.setattr("nexus_cli.subprocess.run", lambda *a, **k: None)
+    monkeypatch.setattr("nexus_cli.shutil.which", lambda name: "/usr/bin/uv" if name == "uv" else None)
+    runner.invoke(app, ["init", str(tmp_project)])
+    monkeypatch.chdir(tmp_project)
+    result = runner.invoke(app, ["update", "--sync"])
+    assert result.exit_code == 0
+    output = _flat(result.output)
+    assert "Syncing built-ins" in output
+    assert "scaffold.md" in output
+
+
 class _FakeTTY:
     def isatty(self):
         return True
@@ -487,3 +549,150 @@ def test_doctor_stale_graphify_hook_warns(tmp_project, monkeypatch):
     assert result.exit_code == 0
     assert "Stale hook" in output
     assert "codegraph is the active backend" in output
+
+
+# ── init --tool codex ────────────────────────────────────────────────────────
+
+import tomllib  # noqa: E402 — test-only; runtime code stays 3.10-compatible
+
+_EPAV_SKILLS_WITHOUT_FRONTMATTER = [
+    s for s in _BUILTIN_SKILLS
+    if not (Path(__file__).parent.parent / "tools" / "epav" / "skills" / s).read_text().startswith("---")
+]
+
+
+def _frontmatter(text: str) -> dict:
+    assert text.startswith("---"), "SKILL.md must start with frontmatter"
+    fields = {}
+    for line in text.split("---", 2)[1].splitlines():
+        key, sep, value = line.partition(":")
+        if sep:
+            fields[key.strip()] = value.strip().strip('"')
+    return fields
+
+
+def test_init_codex_creates_skills(tmp_project):
+    result = runner.invoke(app, ["init", str(tmp_project), "--tool", "codex"])
+    assert result.exit_code == 0
+    for skill in _BUILTIN_SKILLS:
+        stem = Path(skill).stem
+        skill_md = tmp_project / ".agents" / "skills" / stem / "SKILL.md"
+        assert skill_md.exists(), f"Missing skill: {stem}"
+        fields = _frontmatter(skill_md.read_text())
+        assert fields.get("name") == stem
+        assert fields.get("description"), f"{stem} has an empty description"
+
+
+def test_init_codex_epav_skills_are_explicit_only(tmp_project):
+    runner.invoke(app, ["init", str(tmp_project), "--tool", "codex"])
+    assert _EPAV_SKILLS_WITHOUT_FRONTMATTER, "expected some frontmatter-less EPAV skills"
+    for skill in _BUILTIN_SKILLS:
+        yaml_path = tmp_project / ".agents" / "skills" / Path(skill).stem / "agents" / "openai.yaml"
+        if skill in _EPAV_SKILLS_WITHOUT_FRONTMATTER:
+            assert "allow_implicit_invocation: false" in yaml_path.read_text()
+        else:
+            assert not yaml_path.exists(), f"{skill} should stay implicitly invocable"
+
+
+def test_init_codex_creates_agent_tomls(tmp_project):
+    runner.invoke(app, ["init", str(tmp_project), "--tool", "codex"])
+    for agent in _BUILTIN_AGENTS:
+        toml_path = tmp_project / ".codex" / "agents" / f"{Path(agent).stem}.toml"
+        assert toml_path.exists(), f"Missing agent: {agent}"
+        data = tomllib.loads(toml_path.read_text())
+        assert data["name"] and data["description"] and data["developer_instructions"]
+        assert "model" not in data and "tools" not in data
+
+
+def test_init_codex_creates_config_toml(tmp_project):
+    runner.invoke(app, ["init", str(tmp_project), "--tool", "codex"])
+    data = tomllib.loads((tmp_project / ".codex" / "config.toml").read_text())
+    assert data["mcp_servers"]["nexus"]["command"] == "uvx"
+    assert data["mcp_servers"]["nexus"]["args"][-1] == "nexus-mcp"
+
+
+def test_init_codex_preserves_existing_config_toml(tmp_project):
+    existing = 'model = "gpt-5"\n\n[mcp_servers.other]\ncommand = "other"'
+    (tmp_project / ".codex").mkdir()
+    (tmp_project / ".codex" / "config.toml").write_text(existing)
+    runner.invoke(app, ["init", str(tmp_project), "--tool", "codex"])
+    text = (tmp_project / ".codex" / "config.toml").read_text()
+    assert text.startswith(existing)
+    data = tomllib.loads(text)
+    assert set(data["mcp_servers"]) == {"other", "nexus"}
+
+
+def test_init_codex_does_not_duplicate_nexus_mcp_entry(tmp_project):
+    (tmp_project / ".codex").mkdir()
+    (tmp_project / ".codex" / "config.toml").write_text('[mcp_servers.nexus]\ncommand = "custom"\n')
+    runner.invoke(app, ["init", str(tmp_project), "--tool", "codex"])
+    text = (tmp_project / ".codex" / "config.toml").read_text()
+    assert text.count("[mcp_servers.nexus]") == 1
+    assert 'command = "custom"' in text
+
+
+def test_init_codex_creates_graphify_hook(tmp_project):
+    runner.invoke(app, ["init", str(tmp_project), "--tool", "codex"])
+    data = json.loads((tmp_project / ".codex" / "hooks.json").read_text())
+    entry = data["hooks"]["PostToolUse"][0]
+    assert entry["matcher"] == "Edit|Write"
+    assert "graphify update" in entry["hooks"][0]["command"]
+
+
+def test_init_codex_merges_existing_hooks(tmp_project):
+    (tmp_project / ".codex").mkdir()
+    mine = {"hooks": {"Stop": [{"hooks": [{"type": "command", "command": "echo done"}]}]}}
+    (tmp_project / ".codex" / "hooks.json").write_text(json.dumps(mine))
+    runner.invoke(app, ["init", str(tmp_project), "--tool", "codex"])
+    data = json.loads((tmp_project / ".codex" / "hooks.json").read_text())
+    assert data["hooks"]["Stop"] == mine["hooks"]["Stop"]
+    assert "PostToolUse" in data["hooks"]
+
+
+def test_init_codex_codegraph_backend_skips_hook(tmp_project):
+    runner.invoke(app, ["init", str(tmp_project), "--tool", "codex", "--graph-backend", "codegraph"])
+    assert not (tmp_project / ".codex" / "hooks.json").exists()
+    assert (tmp_project / ".codex" / "config.toml").exists()
+
+
+def test_init_codex_idempotent(tmp_project):
+    runner.invoke(app, ["init", str(tmp_project), "--tool", "codex"])
+    result = runner.invoke(app, ["init", str(tmp_project), "--tool", "codex"])
+    assert result.exit_code == 0
+    assert "Already initialized" in result.output
+
+
+def test_sync_codex_updates_modified_skill(tmp_project):
+    runner.invoke(app, ["init", str(tmp_project), "--tool", "codex"])
+    skill_md = tmp_project / ".agents" / "skills" / "evaluate" / "SKILL.md"
+    skill_md.write_text("stale")
+    result = runner.invoke(app, ["sync", str(tmp_project)])
+    assert result.exit_code == 0
+    assert "updated" in result.output
+    assert skill_md.read_text() != "stale"
+    assert _frontmatter(skill_md.read_text())["name"] == "evaluate"
+
+
+def test_doctor_codex_project(tmp_project):
+    runner.invoke(app, ["init", str(tmp_project), "--tool", "codex"])
+    result = runner.invoke(app, ["doctor", str(tmp_project)])
+    out = _flat(result.output)
+    assert "yes (codex)" in out
+    assert "nexus entry present" in out
+    assert f"all {len(_BUILTIN_SKILLS)} present" in out
+    assert f"all {len(_BUILTIN_AGENTS)} present" in out
+
+
+def test_codex_hook_counts_as_graphify_hook(tmp_project):
+    from tools.epav import graph_backend
+    runner.invoke(app, ["init", str(tmp_project), "--tool", "codex"])
+    assert graph_backend.has_graphify_hook(tmp_project)
+
+
+def test_init_codex_rewrites_skill_refs_to_dollar_syntax(tmp_project):
+    runner.invoke(app, ["init", str(tmp_project), "--tool", "codex"])
+    apply_md = (tmp_project / ".agents" / "skills" / "apply" / "SKILL.md").read_text()
+    assert "$validate" in apply_md and "`/validate`" not in apply_md
+    # Claude Code output must keep the slash syntax
+    runner.invoke(app, ["init", str(tmp_project)])
+    assert "`/validate`" in (tmp_project / ".claude" / "commands" / "apply.md").read_text()

{nexus_dev_toolkit-3.1.8 → nexus_dev_toolkit-3.1.10}/tools/agents/code-reviewer.md

@@ -80,7 +80,7 @@ For every candidate finding, before keeping it:
 
 ## Step 5: Report
 
-Print the `## Repo Context` block as your only text output, then call `ReportFindings` with the verified findings (most severe first; empty array if none survived). Do not also print findings as text, and do not add prose after the tool call.
+Print the `## Repo Context` block as your only text output, then call `ReportFindings` with the verified findings (most severe first; empty array if none survived). Do not also print findings as text, and do not add prose after the tool call. If the `ReportFindings` tool isn't available, print the verified findings as a numbered list instead (most severe first, each with file:line, summary and failure scenario).
 
 - `category`: one of `bug`, `error-handling`, `complexity`, `naming`, `duplication`, `type-safety`, `performance`, `maintainability`, `security`
 - `file`/`line`: omit if not applicable

{nexus_dev_toolkit-3.1.8 → nexus_dev_toolkit-3.1.10}/tools/epav/graph_backend.py

@@ -78,11 +78,11 @@ def run_query(text: str, backend: str | None = None, root: Path = Path(".")) ->
 
 def has_graphify_hook(root: Path = Path(".")) -> bool:
     """True if this project has graphify's PostToolUse automation wired in."""
-    settings_path = root / ".claude" / "settings.json"
-    if settings_path.exists():
-        try:
-            if _GRAPHIFY_HOOK_MARKER in settings_path.read_text():
-                return True
-        except Exception:
-            pass
+    for settings_path in (root / ".claude" / "settings.json", root / ".codex" / "hooks.json"):
+        if settings_path.exists():
+            try:
+                if _GRAPHIFY_HOOK_MARKER in settings_path.read_text():
+                    return True
+            except Exception:
+                pass
     return (root / ".opencode" / "plugins" / "graphify.js").exists()

{nexus_dev_toolkit-3.1.8 → nexus_dev_toolkit-3.1.10}/tools/epav/skills/code-review.md

@@ -17,7 +17,7 @@ Default scope is "what changed": uncommitted/staged changes plus any commits ahe
 
 ### 2 — Delegate to the code-reviewer agent
 
-Launch the `code-reviewer` agent (Agent tool, `subagent_type: "code-reviewer"`) with a prompt stating the scope from Step 1 and any focus areas the user mentioned (e.g. "focus on the auth changes"). The agent discovers repo context itself, reviews read-only, and reports findings via `ReportFindings` — do not ask it to edit code.
+Launch the `code-reviewer` agent (Agent tool, `subagent_type: "code-reviewer"`) with a prompt stating the scope from Step 1 and any focus areas the user mentioned (e.g. "focus on the auth changes"). The agent discovers repo context itself, reviews read-only, and reports findings via `ReportFindings` — do not ask it to edit code. If the `ReportFindings` tool isn't available (non-Claude Code tools), the agent prints the findings as a numbered list instead.
 
 ### 3 — Output