<?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-1-global-kittify-machine-level-runtime/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-04-08-1-global-kittify-machine-level-runtime/</id>
  <title>ADR 1 (2026-04-08): Global `~/.kittify/` as Machine-Level Runtime</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-1-global-kittify-machine-level-runtime/"/>
  <summary>Makes ~/.kittify the machine-level runtime that init bootstraps, leaving per-project .kittify directories holding nothing but project-specific state.</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; was originally designed as a per-project installer: it copied mission templates, scripts, and agent command files into the current project directory. Each project therefore contained a full, independent copy of the spec-kitty runtime. This design made sense when spec-kitty was a lightweight scaffolding tool, but it created several structural problems as the tool matured into a multi-agent orchestration platform:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Data duplication.&lt;/strong&gt; Missions, skills, and agent templates are identical across projects. Every &lt;code dir=&quot;auto&quot;&gt;spec-kitty init&lt;/code&gt; on a developer’s machine produces another full copy.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Inconsistent upgrades.&lt;/strong&gt; Running &lt;code dir=&quot;auto&quot;&gt;spec-kitty upgrade&lt;/code&gt; in one project updated its local copies; other projects remained on older templates. A developer working across three projects could have three different versions of the same slash commands.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Blurred machine/project boundary.&lt;/strong&gt; Agent configuration (which AI tools are installed and trusted on a given machine) is a machine-level concern. Project metadata (charter, feature specifications, work package state) is a project-level concern. init was conflating the two in a single directory.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;No canonical runtime location.&lt;/strong&gt; Code that needed to resolve mission paths, skill locations, or agent configs had to guess: search upward from cwd, look in the package, or use a configurable path. There was no agreed-upon answer for “where does the runtime live?”&lt;/p&gt;
&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;Feature 076 redesigns &lt;code dir=&quot;auto&quot;&gt;spec-kitty init&lt;/code&gt; to address these problems by establishing a global machine-level runtime at &lt;code dir=&quot;auto&quot;&gt;~/.kittify/&lt;/code&gt;.&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;Upgrade consistency:&lt;/strong&gt; One update to the global runtime propagates to all projects without per-project re-runs.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Clear separation of concerns:&lt;/strong&gt; Machine state and project state must not share the same directory.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Explicit error surfaces:&lt;/strong&gt; Runtime bootstrap failures must be visible to the developer, not silently swallowed.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Simplicity:&lt;/strong&gt; init should do one thing — prepare the machine — and do it completely.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Disk efficiency:&lt;/strong&gt; A single global copy of mission templates replaces N per-project copies.&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: Global &lt;code dir=&quot;auto&quot;&gt;~/.kittify/&lt;/code&gt; as machine-level runtime (chosen)&lt;/strong&gt;&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option B: Per-project full copy (status quo pre-076)&lt;/strong&gt;&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option C: Read-only global + writable per-project overlay&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 — Global &lt;code dir=&quot;auto&quot;&gt;~/.kittify/&lt;/code&gt; as machine-level runtime.&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty init&lt;/code&gt; bootstraps a single global runtime at &lt;code dir=&quot;auto&quot;&gt;~/.kittify/&lt;/code&gt;. Re-running init updates the global runtime without touching any project directory. Per-project &lt;code dir=&quot;auto&quot;&gt;.kittify/&lt;/code&gt; directories contain only project-specific state.&lt;/p&gt;
&lt;h3 id=&quot;what-belongs-where&quot;&gt;What Belongs Where&lt;/h3&gt;













































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Artifact&lt;/th&gt;&lt;th&gt;Location&lt;/th&gt;&lt;th&gt;Rationale&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;Mission templates&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;~/.kittify/missions/&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Machine-level; identical across projects&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Agent skills (global install)&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;~/.kittify/agent-skills/{agent}/&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Machine-level; see ADR-C&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Global agent config (which agents enabled)&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;~/.kittify/config.yaml&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Machine-level; one setting per machine&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Per-project agent config (overrides)&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;.kittify/config.yaml&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Project-level; thin overlay&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Charter and governance&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;.kittify/charter.md&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Project-level; authored via &lt;code dir=&quot;auto&quot;&gt;/spec-kitty.charter&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Feature specifications&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;kitty-specs/{feature}/&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Project-level; created by &lt;code dir=&quot;auto&quot;&gt;/spec-kitty.specify&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Local overrides / custom prompts&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;.kittify/overrides/&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Project-level; never touched by init&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;h3 id=&quot;ensure_runtime-behavior&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;ensure_runtime()&lt;/code&gt; Behavior&lt;/h3&gt;
&lt;p&gt;The &lt;code dir=&quot;auto&quot;&gt;ensure_runtime()&lt;/code&gt; function is the sole entry point for verifying that &lt;code dir=&quot;auto&quot;&gt;~/.kittify/&lt;/code&gt; is present and current. Failures must surface as explicit errors with actionable messages (e.g. “Global runtime not found. Run &lt;code dir=&quot;auto&quot;&gt;spec-kitty init&lt;/code&gt; to bootstrap.”). Silent swallowing of &lt;code dir=&quot;auto&quot;&gt;ensure_runtime()&lt;/code&gt; failures — which occurred in several pre-076 code paths — is explicitly prohibited.&lt;/p&gt;
&lt;h3 id=&quot;idempotency&quot;&gt;Idempotency&lt;/h3&gt;
&lt;p&gt;Re-running init on an already-initialized machine is safe. The command detects the existing global runtime, presents current agent configuration, and exits without overwriting data.&lt;/p&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;A single runtime upgrade propagates to all projects on the machine.&lt;/li&gt;
&lt;li&gt;Machine-level and project-level concerns are separated by directory boundary.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;ensure_runtime()&lt;/code&gt; has a canonical target; runtime resolution is unambiguous.&lt;/li&gt;
&lt;li&gt;Disk usage is reduced: one copy of mission templates instead of N copies.&lt;/li&gt;
&lt;li&gt;init is faster: no per-project file-copying for templates already in &lt;code dir=&quot;auto&quot;&gt;~/.kittify/&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;Developers who work on multiple machines must run &lt;code dir=&quot;auto&quot;&gt;spec-kitty init&lt;/code&gt; on each machine separately.&lt;/li&gt;
&lt;li&gt;CI environments (which may not have a persistent home directory) require explicit bootstrapping or &lt;code dir=&quot;auto&quot;&gt;--non-interactive&lt;/code&gt; mode.&lt;/li&gt;
&lt;li&gt;Legacy projects that relied on &lt;code dir=&quot;auto&quot;&gt;.kittify/missions/&lt;/code&gt; existing locally may need migration guidance.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;neutral&quot;&gt;Neutral&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;The &lt;code dir=&quot;auto&quot;&gt;.kittify/&lt;/code&gt; directory in project roots continues to exist but is now a thin overlay rather than a full runtime copy.&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 without creating or modifying any file outside &lt;code dir=&quot;auto&quot;&gt;~/.kittify/&lt;/code&gt; and the project scaffold files (&lt;code dir=&quot;auto&quot;&gt;.gitignore&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;.kittify/metadata.yaml&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;.kittify/config.yaml&lt;/code&gt;); and when running init twice produces identical filesystem state (idempotency). The acceptance test suite covers both conditions.&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-global-kittify-as-machine-level-runtime-chosen&quot;&gt;Option A: Global &lt;code dir=&quot;auto&quot;&gt;~/.kittify/&lt;/code&gt; as machine-level runtime (chosen)&lt;/h3&gt;
&lt;p&gt;A single canonical location for all machine-level runtime artifacts. &lt;code dir=&quot;auto&quot;&gt;spec-kitty init&lt;/code&gt; creates or updates this directory. Per-project &lt;code dir=&quot;auto&quot;&gt;.kittify/&lt;/code&gt; is a thin overlay.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;One upgrade touches all projects.&lt;/li&gt;
&lt;li&gt;Unambiguous runtime location for code resolution.&lt;/li&gt;
&lt;li&gt;Clean machine/project boundary.&lt;/li&gt;
&lt;li&gt;Disk-efficient.&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;Per-machine setup required (cannot bundle runtime into project repo).&lt;/li&gt;
&lt;li&gt;CI environments need explicit handling.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-b-per-project-full-copy-status-quo-pre-076&quot;&gt;Option B: Per-project full copy (status quo pre-076)&lt;/h3&gt;
&lt;p&gt;Each &lt;code dir=&quot;auto&quot;&gt;spec-kitty init&lt;/code&gt; copies the full mission templates, skills, and agent configs into the project’s &lt;code dir=&quot;auto&quot;&gt;.kittify/&lt;/code&gt; directory.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Self-contained: project carries everything it needs.&lt;/li&gt;
&lt;li&gt;Works in environments without a persistent home directory.&lt;/li&gt;
&lt;li&gt;Easy to version-control the runtime alongside the project.&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;Data duplication: N copies of identical templates across N projects.&lt;/li&gt;
&lt;li&gt;Upgrades require running &lt;code dir=&quot;auto&quot;&gt;spec-kitty upgrade&lt;/code&gt; in every project separately.&lt;/li&gt;
&lt;li&gt;Blurs machine-level and project-level state.&lt;/li&gt;
&lt;li&gt;Cannot distinguish “machine is configured” from “this project was initialized”.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Why Rejected:&lt;/strong&gt; The upgrade consistency problem alone makes this model unworkable at scale. Users with 5 or more projects experience diverging runtime versions as a regular frustration.&lt;/p&gt;
&lt;h3 id=&quot;option-c-read-only-global--writable-per-project-overlay&quot;&gt;Option C: Read-only global + writable per-project overlay&lt;/h3&gt;
&lt;p&gt;Global &lt;code dir=&quot;auto&quot;&gt;~/.kittify/&lt;/code&gt; provides read-only base templates; each project has a writable overlay that can override individual files.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Per-project customization supported at the filesystem level.&lt;/li&gt;
&lt;li&gt;Global upgrades still propagate to projects that don’t override.&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;Adds a two-layer resolution system that must be implemented and documented.&lt;/li&gt;
&lt;li&gt;Most projects will never need per-project template overrides; the complexity has no current justification.&lt;/li&gt;
&lt;li&gt;Ambiguous: when a project overlay diverges from the global runtime, which one is authoritative?&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Why Rejected:&lt;/strong&gt; Premature generalization. The overlay mechanism solves a problem that does not yet exist in the user base. The simpler global-only model can be extended to an overlay model in a future feature if demand arises.&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; — FR-003 (bootstrap must surface failures explicitly), FR-016 (idempotent re-runs)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Related ADR:&lt;/strong&gt; ADR-C (2026-04-08-3) — Global skill installation with per-project symlinks&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Related ADR:&lt;/strong&gt; ADR-D (2026-04-08-4) — Charter and doctrine are not init-time concerns&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Related ADR:&lt;/strong&gt; ADR-6 (2026-01-23-6) — Config-driven agent management&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&lt;/code&gt; — init command entry point&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/core/runtime.py&lt;/code&gt; — &lt;code dir=&quot;auto&quot;&gt;ensure_runtime()&lt;/code&gt; implementation&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
