<?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-2-package-bundled-templates-sole-source/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-04-08-2-package-bundled-templates-sole-source/</id>
  <title>ADR 2 (2026-04-08): Package-Bundled Templates as Sole Source</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-2-package-bundled-templates-sole-source/"/>
  <summary>Templates resolve only from the installed package: the GitHub tarball download path and the template-root flag are deleted, leaving one env override for maintainers.</summary>
  <content type="html">&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty init&lt;/code&gt; historically supported three distinct template sources:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Package-bundled (default):&lt;/strong&gt; Templates embedded in the installed &lt;code dir=&quot;auto&quot;&gt;spec-kitty-cli&lt;/code&gt; package, resolved via &lt;code dir=&quot;auto&quot;&gt;importlib.resources&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Remote GitHub download:&lt;/strong&gt; init would download a tarball from the spec-kitty GitHub repository when &lt;code dir=&quot;auto&quot;&gt;--github-token&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;--debug&lt;/code&gt; was passed. This was originally designed to support a “bootstrap without a full install” scenario.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Local repo override:&lt;/strong&gt; When the &lt;code dir=&quot;auto&quot;&gt;--template-root&lt;/code&gt; CLI flag or the &lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_TEMPLATE_ROOT&lt;/code&gt; environment variable was set, init would load templates from the specified local path. This was intended for maintainers testing in-development template changes.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;The multi-source model created several problems:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Network dependency during init.&lt;/strong&gt; The remote download path required network access, TLS validation (&lt;code dir=&quot;auto&quot;&gt;--skip-tls&lt;/code&gt; existed to bypass it), and a GitHub token for private repositories. A simple machine-setup command should not require network calls when the package is already installed.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Dead code paths.&lt;/strong&gt; The remote download scenario — bootstrapping without an installed package — is no longer valid. spec-kitty is distributed exclusively via pipx, and the installed package always contains the templates. The remote path is never used in practice.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Surface area bloat.&lt;/strong&gt; Flags &lt;code dir=&quot;auto&quot;&gt;--debug&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;--skip-tls&lt;/code&gt;, and &lt;code dir=&quot;auto&quot;&gt;--github-token&lt;/code&gt; existed solely to configure the remote download path. They contributed to a confusing CLI surface with no valid end-user use case.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;github_client.py&lt;/code&gt; maintenance cost.&lt;/strong&gt; The module implementing remote download adds code that must be maintained, tested, and kept current with GitHub’s API — for a scenario that no longer occurs.&lt;/p&gt;
&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Eliminate network dependency:&lt;/strong&gt; init should work reliably in air-gapped environments and CI.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Reduce surface area:&lt;/strong&gt; Every flag or code path that has no valid end-user use case is a maintenance liability.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Clarity:&lt;/strong&gt; “Where do templates come from?” should have exactly one answer.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Maintainer workflow:&lt;/strong&gt; Developers testing template changes should still have a mechanism — but it should not require a CLI flag.&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: Package-bundled templates as sole source, env var for maintainers (chosen)&lt;/strong&gt;&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option B: Keep remote mode behind a hidden flag&lt;/strong&gt;&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option C: Keep &lt;code dir=&quot;auto&quot;&gt;--template-root&lt;/code&gt; as a hidden CLI flag&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 — Package-bundled templates are the unconditional source.&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;The template source is always the installed &lt;code dir=&quot;auto&quot;&gt;spec-kitty-cli&lt;/code&gt; package. The &lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_TEMPLATE_ROOT&lt;/code&gt; environment variable remains available for maintainers who need to test template changes from a local checkout without installing. Everything else is removed.&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;github_client.py&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/template/github_client.py&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Entire module deleted&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Remote tarball download&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;init.py:1149–1163&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Dead code path removed&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;--template-root&lt;/code&gt; CLI flag&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;init.py:750&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Env var remains for maintainers&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;--debug&lt;/code&gt; CLI flag&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;init.py:744&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Only wired to remote download path&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;--skip-tls&lt;/code&gt; CLI flag&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;init.py:743&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Only wired to remote download path&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;--github-token&lt;/code&gt; CLI flag&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;init.py:745–748&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Only wired to remote download path&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Local-repo root detection&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;template/manager.py:get_local_repo_root&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Not needed when env var is sufficient&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;h3 id=&quot;what-remains&quot;&gt;What Remains&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_TEMPLATE_ROOT&lt;/code&gt; environment variable: when set, resolves templates from the given path. This is the supported mechanism for maintainer local testing. It is not documented in end-user help text.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;importlib.resources&lt;/code&gt;-based resolution: the default and sole end-user path.&lt;/li&gt;
&lt;/ul&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 network access during init. Works fully offline and in CI.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;github_client.py&lt;/code&gt; and its tests are deleted, reducing the maintenance surface.&lt;/li&gt;
&lt;li&gt;Three flags (&lt;code dir=&quot;auto&quot;&gt;--debug&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;--skip-tls&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;--github-token&lt;/code&gt;) disappear from the CLI help output, simplifying the user-facing surface.&lt;/li&gt;
&lt;li&gt;Template resolution is a single code path, easier to test and reason about.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;negative&quot;&gt;Negative&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;Developers who previously used &lt;code dir=&quot;auto&quot;&gt;--template-root&lt;/code&gt; to test local changes must switch to &lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_TEMPLATE_ROOT&lt;/code&gt;. This is a maintainer-only workflow change with no end-user impact.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;neutral&quot;&gt;Neutral&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;The package-bundled path was already the default; the vast majority of users experience no change.&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&lt;/code&gt; completes successfully without any network calls; and &lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_TEMPLATE_ROOT=/path/to/local spec-kitty init&lt;/code&gt; correctly uses templates from the local path. Both conditions are covered in the 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-package-bundled-templates-as-sole-source-chosen&quot;&gt;Option A: Package-bundled templates as sole source (chosen)&lt;/h3&gt;
&lt;p&gt;Remove all non-package template sources and their associated CLI flags. Retain &lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_TEMPLATE_ROOT&lt;/code&gt; as an undocumented maintainer escape hatch.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Offline-capable.&lt;/li&gt;
&lt;li&gt;No flags to maintain for the remote path.&lt;/li&gt;
&lt;li&gt;One code path to test.&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;Maintainers lose the &lt;code dir=&quot;auto&quot;&gt;--template-root&lt;/code&gt; CLI convenience (minor; env var is equivalent).&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-b-keep-remote-mode-behind-a-hidden-flag&quot;&gt;Option B: Keep remote mode behind a hidden flag&lt;/h3&gt;
&lt;p&gt;Retain &lt;code dir=&quot;auto&quot;&gt;--template-root&lt;/code&gt; and the remote download path but hide them from &lt;code dir=&quot;auto&quot;&gt;--help&lt;/code&gt; output.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Preserves the capability for edge cases not yet anticipated.&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;Hidden flags are still code that must be maintained, tested, and kept secure.&lt;/li&gt;
&lt;li&gt;The remote download path requires network infrastructure (GitHub API tokens, TLS configuration) for a scenario with no known use case.&lt;/li&gt;
&lt;li&gt;“Hidden” is not “removed” — users can still discover and invoke hidden flags; the surface area reduction is cosmetic.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Why Rejected:&lt;/strong&gt; Maintenance burden with no active user. If a legitimate use case emerges in the future, a new flag can be added with a documented scope.&lt;/p&gt;
&lt;h3 id=&quot;option-c-keep---template-root-as-a-hidden-cli-flag&quot;&gt;Option C: Keep &lt;code dir=&quot;auto&quot;&gt;--template-root&lt;/code&gt; as a hidden CLI flag&lt;/h3&gt;
&lt;p&gt;Retain the CLI flag but hide it, removing the remote download path only.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Preserves CLI discoverability if a maintainer forgets about the env var.&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 env var (&lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_TEMPLATE_ROOT&lt;/code&gt;) already exists and covers the identical use case.&lt;/li&gt;
&lt;li&gt;Hidden CLI flags require documentation, parsing code, and test coverage.&lt;/li&gt;
&lt;li&gt;Two mechanisms for the same thing is one too many.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Why Rejected:&lt;/strong&gt; The env var is sufficient. Having both creates ambiguity about which takes precedence and doubles the test surface for an identical capability.&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;--debug&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;--skip-tls&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;--github-token&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;--template-root&lt;/code&gt;), “Code Paths to Remove” table (remote GitHub tarball download, local-repo template override)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Related ADR:&lt;/strong&gt; ADR-A (2026-04-08-1) — Global &lt;code dir=&quot;auto&quot;&gt;~/.kittify/&lt;/code&gt; as machine-level runtime&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/template/github_client.py&lt;/code&gt; — module to be deleted&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/template/manager.py&lt;/code&gt; — &lt;code dir=&quot;auto&quot;&gt;get_local_repo_root&lt;/code&gt; to be removed&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/init.py:743–750&lt;/code&gt; — flags being removed&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
