<?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-07-1-global-slash-command-installation/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-04-07-1-global-slash-command-installation/</id>
  <title>Global Slash Command Installation</title>
  <updated>2026-04-07T00: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-07-1-global-slash-command-installation/"/>
  <summary>Slash command files install once into machine-level agent directories at CLI startup; init stops writing them and a migration deletes the per-project copies.</summary>
  <content type="html">&lt;p&gt;&lt;strong&gt;Amended by:&lt;/strong&gt; ADR &lt;a href=&quot;/adr/4.x/2026-10-20-1-command-skills-use-spec-conformant-names/&quot;&gt;2026-10-20-1&lt;/a&gt; (home-folder writer scoped to configured agents; the &lt;code dir=&quot;auto&quot;&gt;antigravity&lt;/code&gt; row below is superseded: Antigravity reads command skills, not &lt;code dir=&quot;auto&quot;&gt;~/.agent/workflows/&lt;/code&gt;).&lt;/p&gt;
&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;Spec-kitty writes slash command files (e.g., &lt;code dir=&quot;auto&quot;&gt;spec-kitty.plan.md&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;spec-kitty.implement.md&lt;/code&gt;) into each project’s agent command directories (&lt;code dir=&quot;auto&quot;&gt;.claude/commands/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;.gemini/commands/&lt;/code&gt;, etc.) during &lt;code dir=&quot;auto&quot;&gt;spec-kitty init&lt;/code&gt;. This has three consequences:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Per-project friction&lt;/strong&gt;: every new repository requires &lt;code dir=&quot;auto&quot;&gt;spec-kitty init&lt;/code&gt; before slash commands are available.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Per-upgrade friction&lt;/strong&gt;: every repository requires &lt;code dir=&quot;auto&quot;&gt;spec-kitty upgrade&lt;/code&gt; after each CLI upgrade to get updated command files.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Repository churn&lt;/strong&gt;: 13 agents × 16 commands = up to 208 generated files that must be gitignored or tracked in every consumer project.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;Skills were already globalized in commit &lt;code dir=&quot;auto&quot;&gt;cea2d8de&lt;/code&gt; using &lt;code dir=&quot;auto&quot;&gt;ensure_global_agent_skills()&lt;/code&gt;, called at every CLI startup — they install to &lt;code dir=&quot;auto&quot;&gt;~/.claude/skills/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;~/.agents/skills/&lt;/code&gt;, etc. without any per-project action required. Commands must follow the same pattern.&lt;/p&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Zero-setup experience&lt;/strong&gt;: a user who installs &lt;code dir=&quot;auto&quot;&gt;spec-kitty-cli&lt;/code&gt; should have all slash commands available in every project immediately, without running &lt;code dir=&quot;auto&quot;&gt;spec-kitty init&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Automatic upgrades&lt;/strong&gt;: upgrading the CLI via &lt;code dir=&quot;auto&quot;&gt;pipx upgrade&lt;/code&gt; must update slash commands everywhere, without per-project &lt;code dir=&quot;auto&quot;&gt;spec-kitty upgrade&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Consistency with skills model&lt;/strong&gt;: skills are already global; diverging the commands model creates unnecessary conceptual overhead.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;No project-level override requirement&lt;/strong&gt;: project-level command customization is not a supported use case and does not justify per-project installation.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;decision&quot;&gt;Decision&lt;/h2&gt;
&lt;p&gt;Install all 16 slash command files globally to &lt;code dir=&quot;auto&quot;&gt;~/.&amp;#x3C;agent-dir&gt;/&lt;/code&gt; at every CLI startup, using the same version-locked bootstrap pattern as skills. Remove command installation from &lt;code dir=&quot;auto&quot;&gt;spec-kitty init&lt;/code&gt; entirely. Provide a migration that removes existing project-level command files from upgraded projects.&lt;/p&gt;
&lt;h2 id=&quot;considered-options&quot;&gt;Considered Options&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Option A: Keep per-project, fix the upgrade friction&lt;/strong&gt; — automatic per-project upgrade on each CLI invocation. Rejected: still pollutes project directories with generated files; complex to implement safely in multi-worktree environments.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option B: Global-only installation&lt;/strong&gt; ← &lt;strong&gt;Chosen&lt;/strong&gt;&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option C: Global install + optional project-level override&lt;/strong&gt; — allow projects to override individual commands in &lt;code dir=&quot;auto&quot;&gt;.claude/commands/&lt;/code&gt;. Deferred: no current demand; can be added later if needed.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;decision-outcome&quot;&gt;Decision Outcome&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Option B: Global-only installation&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;Commands are installed to the global agent command roots on every CLI startup. The startup hook (&lt;code dir=&quot;auto&quot;&gt;ensure_global_agent_commands()&lt;/code&gt;) mirrors &lt;code dir=&quot;auto&quot;&gt;ensure_global_agent_skills()&lt;/code&gt; exactly: fast-path version check, exclusive lock for writes, version file written last. Project directories no longer contain &lt;code dir=&quot;auto&quot;&gt;spec-kitty.*&lt;/code&gt; command files.&lt;/p&gt;
&lt;h3 id=&quot;all-13-agents-and-their-global-command-roots&quot;&gt;All 13 Agents and Their Global Command Roots&lt;/h3&gt;







































































































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Agent key&lt;/th&gt;&lt;th&gt;Tool name&lt;/th&gt;&lt;th&gt;Global command dir&lt;/th&gt;&lt;th&gt;File extension&lt;/th&gt;&lt;th&gt;Arg format&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;claude&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Claude Code&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;~/.claude/commands/&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;.md&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;$ARGUMENTS&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;copilot&lt;/code&gt;&lt;/td&gt;&lt;td&gt;GitHub Copilot&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;~/.github/prompts/&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;.prompt.md&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;$ARGUMENTS&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;gemini&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Gemini CLI&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;~/.gemini/commands/&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;.toml&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;{{args}}&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;cursor&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Cursor&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;~/.cursor/commands/&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;.md&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;$ARGUMENTS&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;qwen&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Qwen Code&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;~/.qwen/commands/&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;.toml&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;{{args}}&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;opencode&lt;/code&gt;&lt;/td&gt;&lt;td&gt;opencode&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;~/.opencode/command/&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;.md&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;$ARGUMENTS&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;windsurf&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Windsurf&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;~/.windsurf/workflows/&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;.md&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;$ARGUMENTS&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;codex&lt;/code&gt;&lt;/td&gt;&lt;td&gt;GitHub Codex&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;~/.codex/prompts/&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;.md&lt;/code&gt; (hyphens→underscores)&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;$ARGUMENTS&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;kilocode&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Kilo Code&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;~/.kilocode/workflows/&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;.md&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;$ARGUMENTS&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;auggie&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Augment Code&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;~/.augment/commands/&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;.md&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;$ARGUMENTS&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;roo&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Roo Code&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;~/.roo/commands/&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;.md&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;$ARGUMENTS&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;q&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Amazon Q&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;~/.amazonq/prompts/&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;.md&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;$ARGUMENTS&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;del&gt;&lt;code dir=&quot;auto&quot;&gt;antigravity&lt;/code&gt;&lt;/del&gt;&lt;/td&gt;&lt;td&gt;&lt;del&gt;Google Antigravity&lt;/del&gt;&lt;/td&gt;&lt;td&gt;&lt;del&gt;&lt;code dir=&quot;auto&quot;&gt;~/.agent/workflows/&lt;/code&gt;&lt;/del&gt;&lt;/td&gt;&lt;td&gt;&lt;del&gt;&lt;code dir=&quot;auto&quot;&gt;.md&lt;/code&gt;&lt;/del&gt;&lt;/td&gt;&lt;td&gt;&lt;del&gt;&lt;code dir=&quot;auto&quot;&gt;$ARGUMENTS&lt;/code&gt;&lt;/del&gt; (superseded, see ADR 2026-10-20-1)&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;Global root = &lt;code dir=&quot;auto&quot;&gt;Path.home() / AGENT_COMMAND_CONFIG[agent_key][&quot;dir&quot;]&lt;/code&gt;&lt;/p&gt;
&lt;h3 id=&quot;implementation&quot;&gt;Implementation&lt;/h3&gt;
&lt;ol&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/runtime/agent_commands.py&lt;/code&gt;&lt;/strong&gt; — new module mirroring &lt;code dir=&quot;auto&quot;&gt;agent_skills.py&lt;/code&gt;. &lt;code dir=&quot;auto&quot;&gt;ensure_global_agent_commands()&lt;/code&gt; installs all 16 commands (9 prompt-driven + 7 CLI shims) for all 13 agents. Version lock: &lt;code dir=&quot;auto&quot;&gt;~/.kittify/cache/agent-commands.lock&lt;/code&gt;. Per-agent failures are caught and logged; one agent’s failure does not block others.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/__init__.py&lt;/code&gt;&lt;/strong&gt; — &lt;code dir=&quot;auto&quot;&gt;ensure_global_agent_commands()&lt;/code&gt; called in &lt;code dir=&quot;auto&quot;&gt;main_callback()&lt;/code&gt; after &lt;code dir=&quot;auto&quot;&gt;ensure_global_agent_skills()&lt;/code&gt;.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/cli/commands/init.py&lt;/code&gt;&lt;/strong&gt; — &lt;code dir=&quot;auto&quot;&gt;generate_agent_assets()&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;generate_all_shims()&lt;/code&gt; calls removed. &lt;code dir=&quot;auto&quot;&gt;init&lt;/code&gt; no longer writes project-level command files.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/upgrade/migrations/m_3_1_2_globalize_commands.py&lt;/code&gt;&lt;/strong&gt; — migration that removes existing &lt;code dir=&quot;auto&quot;&gt;spec-kitty.*&lt;/code&gt; command files from all configured agent directories in consumer projects on &lt;code dir=&quot;auto&quot;&gt;spec-kitty upgrade&lt;/code&gt;.&lt;/p&gt;
&lt;/li&gt;
&lt;/ol&gt;
&lt;h3 id=&quot;consequences&quot;&gt;Consequences&lt;/h3&gt;
&lt;h4 id=&quot;positive&quot;&gt;Positive&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;No &lt;code dir=&quot;auto&quot;&gt;spec-kitty init&lt;/code&gt; required for commands — CLI installation is sufficient.&lt;/li&gt;
&lt;li&gt;No per-project &lt;code dir=&quot;auto&quot;&gt;spec-kitty upgrade&lt;/code&gt; required for command updates.&lt;/li&gt;
&lt;li&gt;Consumer projects are not polluted with up to 208 generated files.&lt;/li&gt;
&lt;li&gt;Consistent with the skills globalization model established in &lt;code dir=&quot;auto&quot;&gt;cea2d8de&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;negative&quot;&gt;Negative&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;Commands are no longer project-scoped — they cannot vary per-project without explicit override infrastructure (not currently supported).&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;~/.github/prompts/&lt;/code&gt; (copilot) is written at user-home scope, outside the typical &lt;code dir=&quot;auto&quot;&gt;.github/&lt;/code&gt; project scope. Users who rely on copilot in multiple GitHub accounts on one machine will share one command set.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;neutral&quot;&gt;Neutral&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;_resolve_mission_command_templates_dir()&lt;/code&gt; remains in &lt;code dir=&quot;auto&quot;&gt;init.py&lt;/code&gt; for potential future per-project override support but is not called by default.&lt;/li&gt;
&lt;li&gt;The migration is idempotent: a project with no &lt;code dir=&quot;auto&quot;&gt;spec-kitty.*&lt;/code&gt; command files triggers &lt;code dir=&quot;auto&quot;&gt;detect() == False&lt;/code&gt; and is skipped.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;more-information&quot;&gt;More Information&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Related ADRs:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;cea2d8de&lt;/code&gt; commit — skills globalization (the model this decision follows)&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;References:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/runtime/agent_commands.py&lt;/code&gt; — implementation&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/upgrade/migrations/m_3_1_2_globalize_commands.py&lt;/code&gt; — cleanup migration&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/core/config.py&lt;/code&gt; — &lt;code dir=&quot;auto&quot;&gt;AGENT_COMMAND_CONFIG&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/doctrine/skills/spec-kitty-setup-doctor/references/agent-path-matrix.md&lt;/code&gt; — full agent path matrix&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
