<?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-08-5-shim-generation-supersedes-script-dispatch/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-04-08-5-shim-generation-supersedes-script-dispatch/</id>
  <title>ADR 5 (2026-04-08): Shim Generation Supersedes Script-Type Dispatch</title>
  <updated>2026-04-08T00: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-08-5-shim-generation-supersedes-script-dispatch/"/>
  <summary>Generated shims supersede shell-script dispatch: the bash and powershell script trees and the script-type flag are removed and must not be reintroduced.</summary>
  <content type="html">&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;Early versions of spec-kitty dispatched agent commands via shell scripts. The model worked as follows:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;During &lt;code dir=&quot;auto&quot;&gt;spec-kitty init&lt;/code&gt;, the user was asked which script type to use: &lt;code dir=&quot;auto&quot;&gt;bash&lt;/code&gt; (for Unix/macOS) or &lt;code dir=&quot;auto&quot;&gt;powershell&lt;/code&gt; (for Windows).&lt;/li&gt;
&lt;li&gt;init copied the appropriate script variant from the package into &lt;code dir=&quot;auto&quot;&gt;.kittify/scripts/bash/&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;.kittify/scripts/powershell/&lt;/code&gt; within the project directory.&lt;/li&gt;
&lt;li&gt;Agent command files in directories like &lt;code dir=&quot;auto&quot;&gt;.claude/commands/&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;.codex/prompts/&lt;/code&gt; were configured to invoke these scripts.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;The &lt;code dir=&quot;auto&quot;&gt;--script&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;--script-type&lt;/code&gt; CLI flag controlled this selection.&lt;/p&gt;
&lt;h3 id=&quot;what-replaced-the-script-model&quot;&gt;What Replaced the Script Model&lt;/h3&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;shims/generator.py&lt;/code&gt; was introduced as the active dispatch mechanism. Instead of shell scripts, it writes thin markdown files directly into each agent’s native command directory. These files are self-contained: they describe the command’s behavior inline, using the agent’s native format. No shell process is invoked; the agent handles execution natively.&lt;/p&gt;
&lt;p&gt;For Claude Code: &lt;code dir=&quot;auto&quot;&gt;.claude/commands/spec-kitty.implement.md&lt;/code&gt;
For GitHub Codex: &lt;code dir=&quot;auto&quot;&gt;.codex/prompts/spec-kitty.implement.md&lt;/code&gt;
For OpenCode: &lt;code dir=&quot;auto&quot;&gt;.opencode/command/spec-kitty.implement.md&lt;/code&gt;&lt;/p&gt;
&lt;p&gt;All 13 supported agents use markdown or text-based command files. None invoke shell scripts.&lt;/p&gt;
&lt;h3 id=&quot;current-state-at-removal&quot;&gt;Current State at Removal&lt;/h3&gt;
&lt;p&gt;The &lt;code dir=&quot;auto&quot;&gt;.kittify/scripts/bash/&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;.kittify/scripts/powershell/&lt;/code&gt; directories are still referenced in &lt;code dir=&quot;auto&quot;&gt;template/manager.py&lt;/code&gt;. init copies them during initialization. However:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;No &lt;code dir=&quot;auto&quot;&gt;.sh&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;.ps1&lt;/code&gt; files exist in the package at the time of feature 076.&lt;/li&gt;
&lt;li&gt;The &lt;code dir=&quot;auto&quot;&gt;copy_specify_base_from_local&lt;/code&gt; function in &lt;code dir=&quot;auto&quot;&gt;template/manager.py&lt;/code&gt; (lines 131–150) copies the &lt;code dir=&quot;auto&quot;&gt;scripts/&lt;/code&gt; directory tree, but the source tree is empty.&lt;/li&gt;
&lt;li&gt;No code path in the spec-kitty runtime calls any script from &lt;code dir=&quot;auto&quot;&gt;.kittify/scripts/&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;init’s cleanup logic removes these directories after the installation completes.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;The result is: init creates &lt;code dir=&quot;auto&quot;&gt;scripts/bash/&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;scripts/powershell/&lt;/code&gt; directories, puts nothing in them (because the package has no scripts), then deletes them during cleanup. The &lt;code dir=&quot;auto&quot;&gt;--script&lt;/code&gt; flag influences which empty directory is created before it is deleted.&lt;/p&gt;
&lt;p&gt;This is pure dead code: the flag exists, the directories are created and deleted, and nothing is affected by any of it.&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;Remove dead code:&lt;/strong&gt; Code that has no runtime effect should not exist. It misleads developers reading the codebase and inflates the maintenance surface.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Clean CLI surface:&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;--script&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;--script-type&lt;/code&gt; is a visible CLI flag that implies a meaningful choice. Exposing it when the choice has no effect is confusing.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Alignment with the shim model:&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;shims/generator.py&lt;/code&gt; is the active, supported, tested dispatch mechanism. The script model is historical.&lt;/li&gt;
&lt;/ul&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: Remove script directories, &lt;code dir=&quot;auto&quot;&gt;--script&lt;/code&gt; flag, and script-type selection logic (chosen)&lt;/strong&gt;&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option B: Keep scripts as a fallback for agents that don’t support markdown commands&lt;/strong&gt;&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option C: Deprecate with a warning, remove in a future release&lt;/strong&gt;&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;Chosen option: Option A — The &lt;code dir=&quot;auto&quot;&gt;scripts/bash/&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;scripts/powershell/&lt;/code&gt; directories, the &lt;code dir=&quot;auto&quot;&gt;--script&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;--script-type&lt;/code&gt; flag, and all script-type selection logic are removed.&lt;/strong&gt;&lt;/p&gt;
&lt;h3 id=&quot;what-is-removed&quot;&gt;What Is Removed&lt;/h3&gt;



































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Removed artifact&lt;/th&gt;&lt;th&gt;Location&lt;/th&gt;&lt;th&gt;Notes&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;--script&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;--script-type&lt;/code&gt; flag&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;init.py:734&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;init.py:982–992&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Entire flag and selection block&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Script-type selection logic&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;init.py:982–992&lt;/code&gt;&lt;/td&gt;&lt;td&gt;10 lines of dead branching&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;copy_specify_base_from_local&lt;/code&gt; script section&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;template/manager.py:131–150&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Empty directories were being copied&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;.kittify/scripts/bash/&lt;/code&gt; directory&lt;/td&gt;&lt;td&gt;Package templates&lt;/td&gt;&lt;td&gt;No files exist; directory removed&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;.kittify/scripts/powershell/&lt;/code&gt; directory&lt;/td&gt;&lt;td&gt;Package templates&lt;/td&gt;&lt;td&gt;No files exist; directory removed&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;h3 id=&quot;what-replaces-it&quot;&gt;What Replaces It&lt;/h3&gt;
&lt;p&gt;Nothing needs to replace it — &lt;code dir=&quot;auto&quot;&gt;shims/generator.py&lt;/code&gt; is already the active mechanism and has been since before feature 076. This removal acknowledges that the replacement already happened and cleans up the vestigial script infrastructure.&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;python&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# Active dispatch (shims/generator.py) — already in place:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;def&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;write_agent_command&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;(&lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;agent_root&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: Path, &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;command_name&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;str&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;, &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;template&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;str&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;)&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; -&gt; &lt;/span&gt;&lt;span style=&quot;--0:#FF6A83;--1:#A24848&quot;&gt;None&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;    &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&quot;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;Write a markdown command file into the agent&apos;s native command directory.&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&quot;&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;    &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;...&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&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;&lt;code dir=&quot;auto&quot;&gt;--script&lt;/code&gt; disappears from the init help output. New users no longer see a flag that has no effect.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;init.py&lt;/code&gt; is shorter and clearer. The script-type selection block is removed without replacement.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;template/manager.py&lt;/code&gt; no longer copies an empty directory tree.&lt;/li&gt;
&lt;li&gt;The codebase more accurately describes the active dispatch model.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;negative&quot;&gt;Negative&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;None. The code being removed has no runtime effect. No user observes a behavior change.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;neutral&quot;&gt;Neutral&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;Developers familiar with the historical script model will notice the flag is gone. The change is described in migration notes.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;confirmation&quot;&gt;Confirmation&lt;/h3&gt;
&lt;p&gt;Correct behavior is confirmed when: &lt;code dir=&quot;auto&quot;&gt;spec-kitty init --help&lt;/code&gt; does not list &lt;code dir=&quot;auto&quot;&gt;--script&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;--script-type&lt;/code&gt;; and &lt;code dir=&quot;auto&quot;&gt;spec-kitty init&lt;/code&gt; completes without creating &lt;code dir=&quot;auto&quot;&gt;.kittify/scripts/&lt;/code&gt; in the project directory. Both conditions are covered by the init integration test suite.&lt;/p&gt;
&lt;h2 id=&quot;pros-and-cons-of-the-options&quot;&gt;Pros and Cons of the Options&lt;/h2&gt;
&lt;h3 id=&quot;option-a-remove-script-directories-flag-and-selection-logic-chosen&quot;&gt;Option A: Remove script directories, flag, and selection logic (chosen)&lt;/h3&gt;
&lt;p&gt;Delete all script-related code. &lt;code dir=&quot;auto&quot;&gt;shims/generator.py&lt;/code&gt; is the only dispatch model.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Dead code is removed, not hidden.&lt;/li&gt;
&lt;li&gt;The codebase accurately describes the active architecture.&lt;/li&gt;
&lt;li&gt;One dispatch model to understand, test, and document.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;None identified.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-b-keep-scripts-as-fallback-for-agents-that-dont-support-markdown-commands&quot;&gt;Option B: Keep scripts as fallback for agents that don’t support markdown commands&lt;/h3&gt;
&lt;p&gt;Retain the script infrastructure in case a future agent requires shell dispatch.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Preserves optionality for hypothetical future agents.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;All 13 currently supported agents use native markdown/text command files. No known agent requires shell dispatch.&lt;/li&gt;
&lt;li&gt;The infrastructure has no scripts in it — the fallback cannot function even if a hypothetical agent needed it.&lt;/li&gt;
&lt;li&gt;Speculative preservation of dead infrastructure blocks clarity.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Why Rejected:&lt;/strong&gt; All 13 supported agents use markdown-based commands. If a future agent requires a different dispatch model, the appropriate approach is to implement that model at the time it is needed — not to maintain empty scaffolding for a requirement that does not exist.&lt;/p&gt;
&lt;h3 id=&quot;option-c-deprecate-with-a-warning-remove-in-a-future-release&quot;&gt;Option C: Deprecate with a warning, remove in a future release&lt;/h3&gt;
&lt;p&gt;Print a deprecation notice when &lt;code dir=&quot;auto&quot;&gt;--script&lt;/code&gt; is passed, then remove the flag in the next minor version.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Gives users advance notice.&lt;/li&gt;
&lt;li&gt;Follows standard deprecation practices.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;The &lt;code dir=&quot;auto&quot;&gt;--script&lt;/code&gt; flag already has zero effect. There are no users depending on its behavior. Deprecation warnings are appropriate for flags that do something; they are noise for flags that do nothing.&lt;/li&gt;
&lt;li&gt;Deprecation extends the maintenance window by at least one release cycle for code that should be removed immediately.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Why Rejected:&lt;/strong&gt; The standard deprecation argument assumes users depend on the flag’s behavior. A flag that has been dead code since the shim model was introduced has no users to warn. Deprecating dead code is itself a code smell.&lt;/p&gt;
&lt;h2 id=&quot;more-information&quot;&gt;More Information&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Spec:&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;kitty-specs/076-init-command-overhaul/spec.md&lt;/code&gt; — “Flags to Remove” table (&lt;code dir=&quot;auto&quot;&gt;--script&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;--script-type&lt;/code&gt;), “Code Paths to Remove” table (&lt;code dir=&quot;auto&quot;&gt;.kittify/scripts/bash/&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;powershell/&lt;/code&gt; copying, script type selection)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Active replacement:&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/shims/generator.py&lt;/code&gt; — the active dispatch mechanism that made scripts obsolete&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Related ADR:&lt;/strong&gt; ADR-F (2026-04-08-6) — Global agent commands supersede per-project copies (describes the shim-generated command files that replaced scripts)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Code locations:&lt;/strong&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/init.py:734, 982–992&lt;/code&gt; — flag definition and selection block&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/template/manager.py:131–150&lt;/code&gt; — script directory copying to be removed&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
