@softspark/ai-toolkit 4.14.1 → 4.15.1

package/scripts/generate_agents_md.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
-"""Generate AGENTS.md from app/agents/*.md frontmatter.
+"""Generate the shared AGENTS.md instruction core.
 
-Output is compatible with Codex, OpenCode, and Gemini CLI AGENTS.md format.
+Output is compatible with the Codex and GitHub Copilot AGENTS.md format.
 Usage: ./scripts/generate_agents_md.py > AGENTS.md
 """
 from __future__ import annotations
@@ -10,94 +10,11 @@ import sys
 from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).resolve().parent))
-import subprocess
-
-from _common import agents_dir, frontmatter_field
+from instruction_core import render_instruction_core
 
 
 def main() -> None:
-    print("# AGENTS.md")
-    print()
-    print(
-        "This file describes the specialized AI agents bundled with ai-toolkit."
-    )
-    print(
-        "It is auto-generated from `app/agents/*.md` frontmatter"
-        " — do not edit manually."
-    )
-    print()
-    print("To regenerate: `python3 scripts/generate_agents_md.py > AGENTS.md`")
-    print()
-    print("Compatible with: Claude Code, Codex, OpenCode, Gemini CLI.")
-    print()
-    print("---")
-    print()
-    print("## Usage")
-    print()
-    print("### Claude Code")
-    print(
-        "Agents are loaded automatically from `.claude/agents/`"
-        " after running `install.sh`."
-    )
-    print("Invoke via the Agent tool:")
-    print("```")
-    print(
-        'Use subagent_type: "backend-specialist" to implement the API endpoint.'
-    )
-    print("```")
-    print()
-    print("### Codex / OpenCode")
-    print("Reference agents by name in your prompts:")
-    print("```")
-    print("@backend-specialist implement the payment API")
-    print("```")
-    print()
-    print("### Gemini CLI")
-    print("Use agent descriptions as system context:")
-    print("```")
-    print(
-        'gemini --system "$(cat .claude/agents/backend-specialist.md)"'
-        ' "implement the API"'
-    )
-    print("```")
-    print()
-    print("---")
-    print()
-    print("## Agents")
-    print()
-
-    for agent_file in sorted(agents_dir.glob("*.md")):
-        if not agent_file.is_file():
-            continue
-
-        name = frontmatter_field(agent_file, "name")
-        description = frontmatter_field(agent_file, "description")
-        tools = frontmatter_field(agent_file, "tools")
-
-        if not name:
-            continue
-
-        print(f"### `{name}`")
-        print()
-        if description:
-            print(description)
-            print()
-        if tools:
-            print(f"**Tools:** `{tools}`")
-            print()
-        print("---")
-        print()
-
-    # Codex CLI configuration block (agents, skills, guidelines)
-    codex_script = Path(__file__).resolve().parent / "generate_codex.py"
-    result = subprocess.run(
-        ["python3", str(codex_script)],
-        capture_output=True, text=True,
-    )
-    if result.returncode == 0 and result.stdout.strip():
-        print(result.stdout.rstrip())
-
-    # Note: custom rules are included via generate_codex.py output above
+    print(render_instruction_core(), end="")
 
 
 if __name__ == "__main__":

package/scripts/generate_codex.py

@@ -1,8 +1,8 @@
 #!/usr/bin/env python3
-"""Generate AGENTS.md content for OpenAI Codex CLI.
+"""Generate the compact shared AGENTS.md policy for OpenAI Codex CLI.
 
-Adapts Claude-oriented skills to Codex-native delegation guidance so the full
-skill catalog can be surfaced in Codex installs.
+Agent and skill discovery is installed separately in native directories, so
+the always-on instruction file contains policy rather than duplicated catalogs.
 
 Usage: ./scripts/generate_codex.py > AGENTS.md
 """
@@ -13,108 +13,18 @@ import sys
 from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).resolve().parent))
-from codex_skill_adapter import codex_skill_description
-from dir_rules_shared import (
-    rule_code_style,
-    rule_output_mode,
-    rule_security,
-    rule_testing,
-)
 from emission import (
-    agents_dir,
-    skills_dir,
-    generate_quality_standards,
-    generate_workflow_guidelines,
     print_toolkit_end,
     print_toolkit_start,
 )
-from frontmatter import frontmatter_field
+from instruction_core import render_instruction_core
 from paths import RULES_DIR
 
 
-def _emit_agents() -> str:
-    """Emit agents as bullets."""
-    lines: list[str] = []
-    for agent_file in sorted(agents_dir.glob("*.md")):
-        name = frontmatter_field(agent_file, "name")
-        description = frontmatter_field(agent_file, "description")
-        if not name or not description:
-            continue
-        lines.append(f"- **{name}**: {description}")
-    return "\n".join(lines)
-
-
-def _emit_skills() -> str:
-    """Emit skills as bullets, adapting Claude-native descriptions for Codex."""
-    lines: list[str] = []
-    for skill_dir in sorted(skills_dir.iterdir()):
-        if skill_dir.name.startswith("_"):
-            continue
-        skill_file = skill_dir / "SKILL.md"
-        if not skill_file.is_file():
-            continue
-        name = frontmatter_field(skill_file, "name")
-        description = codex_skill_description(skill_file)
-        if not name or not description:
-            continue
-        lines.append(f"- **{name}**: {description}")
-    return "\n".join(lines)
-
-
-def _emit_coding_rules() -> str:
-    """Inline the universal coding-rule bodies so Codex receives them.
-
-    Codex reads project instructions only from AGENTS.md (and AGENTS.override.md);
-    it does not read a ``.agents/rules/`` directory. Workflow + quality standards
-    are already emitted above, so this adds code-style, testing, security, and
-    output-mode under a single ``## Coding Rules`` section (H1 demoted to H3).
-    """
-    sections: list[str] = []
-    for rule_fn in (rule_code_style, rule_testing, rule_security, rule_output_mode):
-        body = rule_fn().rstrip()
-        if body.startswith("# "):
-            body = "### " + body[2:]
-        sections.append(body)
-    return "## Coding Rules\n\n" + "\n\n".join(sections)
-
-
 def main() -> None:
     print_toolkit_start()
-
-    print("# AI Toolkit — Codex CLI Configuration")
-    print()
-    print(
-        "Shared AI development toolkit with specialized agents,"
-        " Codex-compatible skills, quality hooks, and a safety constitution."
-    )
-
-    # Agents (all agents are informational — safe to list)
-    print()
-    print("## Available Agents")
+    print(render_instruction_core().rstrip())
     print()
-    print("Specialized agent personas — apply their expertise for relevant tasks:")
-    print()
-    print(_emit_agents())
-
-    # Skills
-    print()
-    print("## Available Skills")
-    print()
-    print("Skills are invocable commands or auto-loaded knowledge sources:")
-    print()
-    print(_emit_skills())
-
-    # Guidelines
-    print()
-    print(generate_quality_standards())
-    print()
-    print(generate_workflow_guidelines())
-
-    # Universal coding rules — Codex reads instructions only from AGENTS.md,
-    # so inline them here (previously emitted to the unread .agents/rules/).
-    print()
-    print(_emit_coding_rules())
-
     print_toolkit_end()
 
     # Registered custom rules from ~/.softspark/ai-toolkit/rules/.

package/scripts/generate_codex_agents.py

@@ -0,0 +1,242 @@
+#!/usr/bin/env python3
+"""Generate native Codex custom-agent TOML files."""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import tempfile
+import tomllib
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from emission import agents_dir
+from frontmatter import frontmatter_field
+
+AGENT_PREFIX = "ai-toolkit-"
+MANAGED_MARKER = "# ai-toolkit-managed: codex-agent"
+REQUIRED_FIELDS = {"name", "description", "developer_instructions"}
+
+
+def _agent_body(agent_file: Path) -> str:
+    text = agent_file.read_text(encoding="utf-8")
+    lines = text.splitlines(keepends=True)
+    body = text
+    if lines and lines[0].rstrip("\r\n") == "---":
+        for index, line in enumerate(lines[1:], start=1):
+            if line.rstrip("\r\n") == "---":
+                body = "".join(lines[index + 1:])
+                break
+    return body.lstrip("\r\n").rstrip() + "\n"
+
+
+def _toml_string(value: str) -> str:
+    return json.dumps(value, ensure_ascii=False)
+
+
+def _render_agent(agent_file: Path) -> str:
+    name = frontmatter_field(agent_file, "name")
+    description = frontmatter_field(agent_file, "description")
+    body = _agent_body(agent_file)
+    return "\n".join(
+        [
+            "# Generated by ai-toolkit. Do not edit.",
+            MANAGED_MARKER,
+            f"name = {_toml_string(name)}",
+            f"description = {_toml_string(description)}",
+            f"developer_instructions = {_toml_string(body)}",
+            "",
+        ]
+    )
+
+
+def _is_managed(path: Path) -> bool:
+    if path.is_symlink() or not path.is_file():
+        return False
+    try:
+        lines = path.read_text(encoding="utf-8").splitlines()
+    except (OSError, UnicodeError):
+        return False
+    return MANAGED_MARKER in lines[:3]
+
+
+def _warn_preserved(path: Path, reason: str) -> None:
+    print(
+        f"Warning: preserving user Codex agent '{path}': {reason}",
+        file=sys.stderr,
+    )
+
+
+def _unmanaged_agent_names(output_dir: Path) -> set[str]:
+    names: set[str] = set()
+    for path in sorted(output_dir.glob("*.toml")):
+        if path.is_symlink():
+            _warn_preserved(path, "path is a symlink")
+            continue
+        if _is_managed(path):
+            continue
+        try:
+            data = tomllib.loads(path.read_text(encoding="utf-8"))
+        except (OSError, UnicodeError, tomllib.TOMLDecodeError) as error:
+            _warn_preserved(path, f"cannot parse TOML ({error})")
+            continue
+        name = data.get("name")
+        if isinstance(name, str) and name.strip():
+            names.add(name)
+    return names
+
+
+def _cleanup_stale(output_dir: Path, expected: set[str]) -> int:
+    removed = 0
+    for output in sorted(output_dir.glob(f"{AGENT_PREFIX}*.toml")):
+        if output.is_symlink():
+            continue
+        if output.name in expected or not _is_managed(output):
+            continue
+        output.unlink()
+        removed += 1
+    return removed
+
+
+def _assert_safe_output_paths(base: Path, output_dir: Path) -> None:
+    if base.is_symlink():
+        raise RuntimeError(f"Refusing symlinked Codex config directory: {base}")
+    if output_dir.is_symlink():
+        raise RuntimeError(f"Refusing symlinked Codex agents directory: {output_dir}")
+
+
+def _prepare_output_dir(base: Path) -> Path:
+    output_dir = base / "agents"
+    _assert_safe_output_paths(base, output_dir)
+    output_dir.mkdir(parents=True, exist_ok=True)
+    _assert_safe_output_paths(base, output_dir)
+    return output_dir
+
+
+def _validate_agent_toml(rendered: str, source: Path) -> None:
+    data = tomllib.loads(rendered)
+    if set(data) != REQUIRED_FIELDS:
+        raise ValueError(f"Invalid Codex agent fields rendered from {source}")
+    if any(not isinstance(data[field], str) or not data[field] for field in REQUIRED_FIELDS):
+        raise ValueError(f"Empty Codex agent field rendered from {source}")
+
+
+def _build_write_plan(
+    output_dir: Path,
+    unmanaged_names: set[str],
+) -> tuple[list[tuple[Path, str]], set[str]]:
+    plan: list[tuple[Path, str]] = []
+    expected: set[str] = set()
+
+    for agent_file in sorted(agents_dir.glob("*.md")):
+        name = frontmatter_field(agent_file, "name")
+        description = frontmatter_field(agent_file, "description")
+        if not name or not description:
+            continue
+        if name in unmanaged_names:
+            continue
+        filename = f"{AGENT_PREFIX}{name}.toml"
+        expected.add(filename)
+        output = output_dir / filename
+        if output.is_symlink():
+            _warn_preserved(output, "destination is a symlink")
+            continue
+        if output.exists() and not _is_managed(output):
+            continue
+        rendered = _render_agent(agent_file)
+        _validate_agent_toml(rendered, agent_file)
+        plan.append((output, rendered))
+    return plan, expected
+
+
+def _discard_temp(path: Path, output_dir: Path) -> None:
+    if path.parent != output_dir:
+        return
+    try:
+        path.unlink(missing_ok=True)
+    except OSError:
+        pass
+
+
+def _stage_agent(output_dir: Path, output: Path, rendered: str) -> Path:
+    fd, temp_name = tempfile.mkstemp(
+        dir=output_dir,
+        prefix=f".{output.name}.",
+        suffix=".tmp",
+    )
+    temp_path = Path(temp_name)
+    try:
+        handle = os.fdopen(fd, "w", encoding="utf-8")
+        fd = -1
+        with handle:
+            handle.write(rendered)
+            handle.flush()
+            os.fsync(handle.fileno())
+        _validate_agent_toml(temp_path.read_text(encoding="utf-8"), output)
+        return temp_path
+    except Exception:
+        if fd >= 0:
+            os.close(fd)
+        _discard_temp(temp_path, output_dir)
+        raise
+
+
+def _stage_all(
+    output_dir: Path,
+    plan: list[tuple[Path, str]],
+) -> list[tuple[Path, Path]]:
+    staged: list[tuple[Path, Path]] = []
+    try:
+        for output, rendered in plan:
+            staged.append((_stage_agent(output_dir, output, rendered), output))
+        return staged
+    except Exception:
+        for temp_path, _ in staged:
+            _discard_temp(temp_path, output_dir)
+        raise
+
+
+def _replace_all(
+    base: Path,
+    output_dir: Path,
+    staged: list[tuple[Path, Path]],
+) -> int:
+    written = 0
+    _assert_safe_output_paths(base, output_dir)
+    for temp_path, output in staged:
+        if output.is_symlink():
+            _warn_preserved(output, "destination became a symlink during generation")
+            continue
+        if output.exists() and not _is_managed(output):
+            _warn_preserved(output, "destination became user-owned during generation")
+            continue
+        os.replace(temp_path, output)
+        written += 1
+    return written
+
+
+def generate(target_dir: Path, config_root: Path | None = None) -> tuple[int, int]:
+    base = config_root if config_root is not None else target_dir / ".codex"
+    output_dir = _prepare_output_dir(base)
+    unmanaged_names = _unmanaged_agent_names(output_dir)
+    plan, expected = _build_write_plan(output_dir, unmanaged_names)
+    staged = _stage_all(output_dir, plan)
+    try:
+        written = _replace_all(base, output_dir, staged)
+        _assert_safe_output_paths(base, output_dir)
+    finally:
+        for temp_path, _ in staged:
+            _discard_temp(temp_path, output_dir)
+    removed = _cleanup_stale(output_dir, expected)
+    return written, removed
+
+
+def main() -> None:
+    target = Path(sys.argv[1]) if len(sys.argv) > 1 else Path.cwd()
+    written, removed = generate(target)
+    print(f"Generated: .codex/agents/ ({written} agents, {removed} stale removed)")
+
+
+if __name__ == "__main__":
+    main()