<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/adr/3.x/2026-04-14-2-agent-skills-renderer-for-codex-and-vibe/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-04-14-2-agent-skills-renderer-for-codex-and-vibe/</id>
  <title>ADR 2 (2026-04-14): Agent Skills Renderer for Codex and Vibe</title>
  <updated>2026-04-14T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/adr/3.x/2026-04-14-2-agent-skills-renderer-for-codex-and-vibe/"/>
  <summary>Adds a scoped renderer emitting per-command SKILL.md packages for Codex and Vibe only, installed additively and tracked through an ownership manifest.</summary>
  <content type="html">&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;Spec Kitty supports multiple coding-agent integrations (claude, codex,
gemini, cursor, opencode, windsurf, and others). Each agent discovers the
&lt;code dir=&quot;auto&quot;&gt;/spec-kitty.*&lt;/code&gt; slash commands by reading a directory of prompt files at a
vendor-specific path — e.g. &lt;code dir=&quot;auto&quot;&gt;.claude/commands/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;.codex/prompts/&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;.gemini/commands/&lt;/code&gt;. That pipeline has worked for a year, but two new
pressures made it untenable for the next release:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Mistral Vibe&lt;/strong&gt; — announced April 2026 — ships with no prompt-file
surface at all. It is a &lt;em&gt;skills-first&lt;/em&gt; agent: slash commands are
discovered as Agent Skills packages (&lt;code dir=&quot;auto&quot;&gt;SKILL.md&lt;/code&gt; + body) under
&lt;code dir=&quot;auto&quot;&gt;.agents/skills/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;.vibe/skills/&lt;/code&gt;, or &lt;code dir=&quot;auto&quot;&gt;~/.vibe/skills/&lt;/code&gt;. Spec Kitty
cannot support Vibe by adding another &lt;code dir=&quot;auto&quot;&gt;AGENT_COMMAND_CONFIG&lt;/code&gt; row.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;OpenAI Codex&lt;/strong&gt; has &lt;strong&gt;deprecated&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;.codex/prompts/*.md&lt;/code&gt; in favor of
Agent Skills at &lt;code dir=&quot;auto&quot;&gt;.agents/skills/&lt;/code&gt; (documented at
&lt;a href=&quot;https://developers.openai.com/codex/custom-prompts&quot;&gt;https://developers.openai.com/codex/custom-prompts&lt;/a&gt; and
&lt;a href=&quot;https://developers.openai.com/codex/skills&quot;&gt;https://developers.openai.com/codex/skills&lt;/a&gt;). Spec Kitty’s Codex
integration was writing to the deprecated path while &lt;em&gt;also&lt;/em&gt; shipping
skills to &lt;code dir=&quot;auto&quot;&gt;.agents/skills/&lt;/code&gt; for other purposes. The prompt-file side
had become obsolete without our noticing.&lt;/p&gt;
&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;During P0 research for this mission we confirmed a second, subtler
constraint: the &lt;code dir=&quot;auto&quot;&gt;$ARGUMENTS&lt;/code&gt; pre-substitution pattern Spec Kitty uses in
its command templates is a &lt;strong&gt;command-layer&lt;/strong&gt; feature, not a &lt;strong&gt;skills-layer&lt;/strong&gt;
feature. Codex’s documented skill invocation mechanism (&lt;code dir=&quot;auto&quot;&gt;$skill-name &amp;#x3C;free-form text&gt;&lt;/code&gt;) delivers user input as &lt;em&gt;turn content&lt;/em&gt;, not via a
placeholder the runtime substitutes. Vibe’s vendor docs are silent on
substitution semantics. Moving all agents’ Spec Kitty commands into the
skills layer would therefore lose deterministic argument delivery on Codex
and (worst case) on Vibe, and would degrade TUI autocomplete UX on
opencode (whose skills are model-loaded, not user-invoked slash entries).&lt;/p&gt;
&lt;p&gt;Full per-agent research is recorded in
&lt;code dir=&quot;auto&quot;&gt;kitty-specs/083-agent-skills-codex-vibe/research.md&lt;/code&gt;.&lt;/p&gt;
&lt;h2 id=&quot;decision&quot;&gt;Decision&lt;/h2&gt;
&lt;p&gt;Introduce a &lt;strong&gt;scoped&lt;/strong&gt; Agent Skills renderer and installer that serves
&lt;strong&gt;Codex and Vibe only&lt;/strong&gt;. The renderer reads the same
&lt;code dir=&quot;auto&quot;&gt;command-templates/*.md&lt;/code&gt; source files that the legacy command-file
pipeline reads, transforms the &lt;code dir=&quot;auto&quot;&gt;## User Input&lt;/code&gt; block (the one place the
templates rely on &lt;code dir=&quot;auto&quot;&gt;$ARGUMENTS&lt;/code&gt; substitution) into an explicit instruction
telling the model to read turn content as user input, and emits per-command
&lt;code dir=&quot;auto&quot;&gt;SKILL.md&lt;/code&gt; packages under &lt;code dir=&quot;auto&quot;&gt;.agents/skills/spec-kitty.&amp;#x3C;command&gt;/&lt;/code&gt;. The
installer writes those packages &lt;strong&gt;additively&lt;/strong&gt; into the shared
&lt;code dir=&quot;auto&quot;&gt;.agents/skills/&lt;/code&gt; root and tracks ownership via
&lt;code dir=&quot;auto&quot;&gt;.kittify/command-skills-manifest.json&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;The twelve remaining command-layer agents (claude, gemini, copilot,
cursor, qwen, opencode, windsurf, kilocode, auggie, roo, q, antigravity)
continue to use the existing command-file pipeline unchanged. A
post-mission regression snapshot (132 fixture files: 12 agents × 11
commands) locks that parity in place.&lt;/p&gt;
&lt;p&gt;Concretely:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Canonical command key&lt;/strong&gt; for Mistral Vibe: &lt;code dir=&quot;auto&quot;&gt;vibe&lt;/code&gt; (following the
&lt;code dir=&quot;auto&quot;&gt;claude&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;codex&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;gemini&lt;/code&gt; product-name convention, not the vendor
name).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Primary discovery root&lt;/strong&gt; for Codex in this release:
project-local &lt;code dir=&quot;auto&quot;&gt;.agents/skills/&lt;/code&gt;. Vibe is pointed at that shared tree via
project-local &lt;code dir=&quot;auto&quot;&gt;.vibe/config.toml&lt;/code&gt; &lt;code dir=&quot;auto&quot;&gt;skill_paths&lt;/code&gt;, which matches Mistral’s
documented custom-path mechanism. Vendor-specific skill copies remain out of
scope.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Ownership manifest&lt;/strong&gt; at &lt;code dir=&quot;auto&quot;&gt;.kittify/command-skills-manifest.json&lt;/code&gt; records every
Spec-Kitty-owned file with its SHA-256 hash and a reference-counted
list of agents that installed it. Removing an agent drops its entry
from the list; files are physically deleted only when the list
empties. Third-party files sharing the &lt;code dir=&quot;auto&quot;&gt;.agents/skills/&lt;/code&gt; root are
never read, modified, or deleted by the installer.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Zero-touch Codex migration&lt;/strong&gt;: an upgrade migration moves existing
&lt;code dir=&quot;auto&quot;&gt;.codex/prompts/spec-kitty.*.md&lt;/code&gt; files to
&lt;code dir=&quot;auto&quot;&gt;.codex/prompts.superseded/&lt;/code&gt; (preserving them for user review) and
installs the equivalent &lt;code dir=&quot;auto&quot;&gt;.agents/skills/spec-kitty.&amp;#x3C;command&gt;/SKILL.md&lt;/code&gt;
packages. Non-Spec-Kitty files under &lt;code dir=&quot;auto&quot;&gt;.codex/prompts/&lt;/code&gt; are untouched.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Template rendering is a package operation&lt;/strong&gt;, not a project
operation. Command templates ship inside the installed &lt;code dir=&quot;auto&quot;&gt;specify_cli&lt;/code&gt;
Python package. The installer locates them via
&lt;code dir=&quot;auto&quot;&gt;Path(specify_cli.__file__).parent / &quot;missions&quot; / ...&lt;/code&gt;, never via a
path relative to the user’s project root.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;alternatives-considered&quot;&gt;Alternatives Considered&lt;/h2&gt;
&lt;h3 id=&quot;a-unified-skills-only-renderer-covering-all-agents&quot;&gt;A. Unified skills-only renderer covering all agents&lt;/h3&gt;
&lt;p&gt;Rejected. This would have:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Broken deterministic &lt;code dir=&quot;auto&quot;&gt;$ARGUMENTS&lt;/code&gt; substitution on Codex (no documented
substitution mechanism in Agent Skills) and possibly on Vibe (no vendor
commitment either way).&lt;/li&gt;
&lt;li&gt;Regressed TUI autocomplete UX on opencode, whose skills layer is
model-loaded via a &lt;code dir=&quot;auto&quot;&gt;skill&lt;/code&gt; tool rather than surfaced as slash commands.
Users who currently see &lt;code dir=&quot;auto&quot;&gt;/spec-kitty.specify&lt;/code&gt; in opencode’s autocomplete
would lose it.&lt;/li&gt;
&lt;li&gt;Rewritten every canonical command template to stop relying on
&lt;code dir=&quot;auto&quot;&gt;$ARGUMENTS&lt;/code&gt; pre-substitution, with a blast radius spanning every
supported agent.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;b-vendor-specific-roots-vibeskills-codexskills-plus-shared&quot;&gt;B. Vendor-specific roots (.vibe/skills/, .codex/skills/, plus shared)&lt;/h3&gt;
&lt;p&gt;Rejected for this release. Shared &lt;code dir=&quot;auto&quot;&gt;.agents/skills/&lt;/code&gt; is documented as a
first-class discovery root for both vendors. Vendor-specific roots would
add installer complexity and potential coexistence issues without a clear
user-visible benefit. Deferred to a follow-up if demand emerges.&lt;/p&gt;
&lt;h3 id=&quot;c-filename-only-classification-vs-hash-based-edit-detection-for-the-codex-migration&quot;&gt;C. Filename-only classification vs hash-based edit detection for the Codex migration&lt;/h3&gt;
&lt;p&gt;Rejected (hash-based). Reproducing the pre-3.2 renderer’s exact output
bytes requires either pinning an archived copy of the pre-3.2 rendering
pipeline or running a sandboxed subprocess against historic templates.
Both options are fragile, and the payoff (distinguishing unedited from
edited files) is dominated by the simpler guarantee: &lt;strong&gt;preserve every
Spec-Kitty-named file from &lt;code dir=&quot;auto&quot;&gt;.codex/prompts/&lt;/code&gt; on disk&lt;/strong&gt;, in a sibling
&lt;code dir=&quot;auto&quot;&gt;prompts.superseded/&lt;/code&gt; directory, and surface the list to the user. No
content-hashing needed; no user edits lost; users who never edited the
files can delete &lt;code dir=&quot;auto&quot;&gt;prompts.superseded/&lt;/code&gt; in one command.&lt;/p&gt;
&lt;h3 id=&quot;d-render-templates-via-importlibresourcesfiles-traversable&quot;&gt;D. Render templates via &lt;code dir=&quot;auto&quot;&gt;importlib.resources.files()&lt;/code&gt; Traversable&lt;/h3&gt;
&lt;p&gt;Rejected in favor of deriving the path from &lt;code dir=&quot;auto&quot;&gt;specify_cli.__file__&lt;/code&gt;. The
Traversable API returns a &lt;code dir=&quot;auto&quot;&gt;MultiplexedPath&lt;/code&gt; when the package has multiple
sources (e.g., editable install + installed wheel coexisting), which does
not coerce to &lt;code dir=&quot;auto&quot;&gt;pathlib.Path&lt;/code&gt; and requires the renderer to accept a
&lt;code dir=&quot;auto&quot;&gt;Traversable&lt;/code&gt; instead. Since &lt;code dir=&quot;auto&quot;&gt;specify_cli.missions.software-dev.command-templates&lt;/code&gt;
is a regular directory inside a regular package (not a zipapp), a real
&lt;code dir=&quot;auto&quot;&gt;Path&lt;/code&gt; derived from &lt;code dir=&quot;auto&quot;&gt;__file__&lt;/code&gt; is both simpler and equivalent.&lt;/p&gt;
&lt;h2 id=&quot;consequences&quot;&gt;Consequences&lt;/h2&gt;
&lt;h3 id=&quot;positive&quot;&gt;Positive&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Mistral Vibe becomes a first-class supported agent&lt;/strong&gt; in the same
release that retires the deprecated Codex prompt path.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Codex users get a zero-touch upgrade&lt;/strong&gt; — &lt;code dir=&quot;auto&quot;&gt;spec-kitty upgrade&lt;/code&gt; moves
legacy files and installs skill packages with no manual steps.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Shared-root safety&lt;/strong&gt; is formally guaranteed by the ownership manifest
and the installer’s reference-counted removal semantics. Installing or
removing Codex or Vibe cannot affect third-party files in
&lt;code dir=&quot;auto&quot;&gt;.agents/skills/&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The renderer is pure and deterministic&lt;/strong&gt; — same template inputs
produce byte-identical outputs on repeated runs, verified by 22
snapshot fixtures (11 commands × 2 agents).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The 12 non-migrated agents are locked&lt;/strong&gt; against unintended drift via
a 132-fixture regression snapshot.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;negative&quot;&gt;Negative&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Two parallel installers&lt;/strong&gt; now coexist for &lt;code dir=&quot;auto&quot;&gt;.agents/skills/&lt;/code&gt;: the
pre-existing canonical-skill installer (doctrine, tactics) and the new
command-skill installer. They share the ownership manifest’s shape
but run independently. A future unification is desirable but not
required for correctness.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;FR-004 in the mission spec named 16 canonical commands&lt;/strong&gt; but the
codebase has only 11 template files for them. The 5 missing commands
(&lt;code dir=&quot;auto&quot;&gt;tasks-finalize&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;accept&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;merge&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;status&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;dashboard&lt;/code&gt;) are
CLI-only and never had templates in either pipeline. The renderer
correctly installs the 11 that exist. Adding the missing 5 templates
is follow-up work, not a regression introduced by this mission.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Vendor-specific roots remain unsupported.&lt;/strong&gt; Users who prefer
&lt;code dir=&quot;auto&quot;&gt;.vibe/skills/&lt;/code&gt; over &lt;code dir=&quot;auto&quot;&gt;.agents/skills/&lt;/code&gt; cannot opt into that today.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;security&quot;&gt;Security&lt;/h3&gt;
&lt;p&gt;No new security surface. The installer does not invoke subprocesses, make
network calls, or handle credentials. Agent keys are validated against
an allowlist (&lt;code dir=&quot;auto&quot;&gt;SUPPORTED_AGENTS = (&quot;codex&quot;, &quot;vibe&quot;)&lt;/code&gt;) before being used to
construct filesystem paths. Command names come from a hardcoded
&lt;code dir=&quot;auto&quot;&gt;CANONICAL_COMMANDS&lt;/code&gt; tuple — no user input flows into paths.&lt;/p&gt;
&lt;h2 id=&quot;implementation-references&quot;&gt;Implementation references&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Mission spec: kitty-specs/083-agent-skills-codex-vibe/spec.md&lt;/li&gt;
&lt;li&gt;Plan + research: plan.md, research.md&lt;/li&gt;
&lt;li&gt;Contracts: contracts/skill-renderer.contract.md, contracts/skills-manifest.schema.json&lt;/li&gt;
&lt;li&gt;Post-merge review: mission-review.md&lt;/li&gt;
&lt;li&gt;Core modules: &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/skills/command_renderer.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/skills/command_installer.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/skills/manifest_store.py&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Codex migration: &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/upgrade/migrations/m_3_2_0_codex_to_skills.py&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
