<?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-4-charter-doctrine-not-init-time/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-04-08-4-charter-doctrine-not-init-time/</id>
  <title>ADR 4 (2026-04-08): Charter and Doctrine Are Not Init-Time Concerns</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-4-charter-doctrine-not-init-time/"/>
  <summary>Strips the doctrine interview and default application out of init; a charter is authored afterwards via /spec-kitty.charter against an already-created project.</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; accumulated a large body of charter and doctrine logic over time. As of feature 076, the init command contains three major charter/doctrine functions that run during every initialization:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;_run_doctrine_stack_init()&lt;/code&gt;&lt;/strong&gt; (&lt;code dir=&quot;auto&quot;&gt;init.py:520–572&lt;/code&gt;): Runs a doctrine stack interview, asking the developer a series of questions about project governance: tech stack, development philosophy, team norms, and agent behavior preferences. Writes answers to &lt;code dir=&quot;auto&quot;&gt;kitty-specs/doctrine/&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;_run_inline_interview()&lt;/code&gt;&lt;/strong&gt; (&lt;code dir=&quot;auto&quot;&gt;init.py:433–516&lt;/code&gt;): An interactive prompt sequence that collects charter-level project metadata before the user has made any decisions about what the project actually is.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;_apply_doctrine_defaults()&lt;/code&gt;&lt;/strong&gt; (&lt;code dir=&quot;auto&quot;&gt;init.py:392–429&lt;/code&gt;): Applies a set of inferred default doctrine values based on detected project characteristics.&lt;/p&gt;
&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;These three functions account for hundreds of lines of init and represent a substantial portion of the init runtime when run interactively.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;The fundamental architectural error:&lt;/strong&gt; All three functions run at machine-initialization time, before the user has a project. Charter and doctrine describe a specific project’s governance — its team conventions, its technology choices, its agent escalation policies. None of these decisions can be made meaningfully before a project exists.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;How it accumulated:&lt;/strong&gt; spec-kitty was originally a per-project tool. Running &lt;code dir=&quot;auto&quot;&gt;spec-kitty init&lt;/code&gt; inside a project directory was the correct entry point. Charter questions ran after the project existed. When the global runtime model was introduced (see ADR-A), &lt;code dir=&quot;auto&quot;&gt;spec-kitty init&lt;/code&gt; became a machine-level setup command, but the charter/doctrine code was never removed. The result is a machine setup command that asks project-specific questions before any project exists.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Impact:&lt;/strong&gt; New developers are confronted with project governance questions during what should be a simple machine setup. If they guess at answers (the only option), those answers accumulate as authoritative doctrine in the global runtime — creating misleading governance artifacts that apply to no specific project.&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;Logical ordering:&lt;/strong&gt; A developer cannot answer project-specific questions before the project exists.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Correct command surface:&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;spec-kitty init&lt;/code&gt; configures the machine. Charter is authored via &lt;code dir=&quot;auto&quot;&gt;/spec-kitty.charter&lt;/code&gt; after &lt;code dir=&quot;auto&quot;&gt;/spec-kitty.specify&lt;/code&gt; creates the project.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Reduced init complexity:&lt;/strong&gt; Removing the charter stage cuts hundreds of lines from init.py and eliminates &lt;code dir=&quot;auto&quot;&gt;test_init_doctrine.py&lt;/code&gt; entirely.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;User experience:&lt;/strong&gt; Machine setup should be fast and unambiguous. Charter authoring is a richer, deliberate process that belongs in a project context.&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 charter/doctrine entirely from init (chosen)&lt;/strong&gt;&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option B: Keep charter in init, make it optional via a flag&lt;/strong&gt;&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option C: Move charter to a &lt;code dir=&quot;auto&quot;&gt;spec-kitty setup&lt;/code&gt; per-project command&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 — All charter/doctrine code is removed from &lt;code dir=&quot;auto&quot;&gt;spec-kitty init&lt;/code&gt;. Charter is authored via &lt;code dir=&quot;auto&quot;&gt;/spec-kitty.charter&lt;/code&gt; after the project is created.&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 code&lt;/th&gt;&lt;th&gt;Location&lt;/th&gt;&lt;th&gt;Lines&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;_run_doctrine_stack_init()&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;init.py:520–572&lt;/code&gt;&lt;/td&gt;&lt;td&gt;~50 lines&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;_run_inline_interview()&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;init.py:433–516&lt;/code&gt;&lt;/td&gt;&lt;td&gt;~80 lines&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;_apply_doctrine_defaults()&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;init.py:392–429&lt;/code&gt;&lt;/td&gt;&lt;td&gt;~35 lines&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Call site for doctrine stage&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;init.py:1261&lt;/code&gt;&lt;/td&gt;&lt;td&gt;1 line&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;test_init_doctrine.py&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;tests/&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Entire file deleted&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;h3 id=&quot;the-correct-workflow&quot;&gt;The Correct Workflow&lt;/h3&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;plaintext&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:#d6deeb;--1:#403f53&quot;&gt;Machine setup:&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 style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;spec-kitty init                    # Bootstrap ~/.kittify/, configure agents&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;/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:#d6deeb;--1:#403f53&quot;&gt;Project creation:&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 style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;spec-kitty init my-new-project     # Create project directory + minimal scaffold&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 style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;cd my-new-project&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 style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;/spec-kitty.specify [description]  # Define project goals + mission&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 style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;/spec-kitty.charter                # Author project governance (charter + doctrine)&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 style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;/spec-kitty.plan                   # Plan features&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;Charter belongs at step 4 — after the developer knows what the project is, who is working on it, and what governance norms apply.&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;init is simpler, faster, and logically coherent.&lt;/li&gt;
&lt;li&gt;Developers are not asked project-specific questions during machine setup.&lt;/li&gt;
&lt;li&gt;No doctrine artifacts are created before a project exists; the global runtime contains no project-specific data.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;test_init_doctrine.py&lt;/code&gt; is deleted entirely, reducing the test surface area.&lt;/li&gt;
&lt;li&gt;Three large function definitions removed from &lt;code dir=&quot;auto&quot;&gt;init.py&lt;/code&gt;, reducing maintenance burden.&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 relied on init to bootstrap charter artifacts must use &lt;code dir=&quot;auto&quot;&gt;/spec-kitty.charter&lt;/code&gt; instead. This is a workflow change for existing users, but the new workflow is logically correct.&lt;/li&gt;
&lt;li&gt;Documentation that describes charter-during-init must be updated.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;neutral&quot;&gt;Neutral&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;The charter authoring capability is unchanged; only its entry point moves from &lt;code dir=&quot;auto&quot;&gt;spec-kitty init&lt;/code&gt; to &lt;code dir=&quot;auto&quot;&gt;/spec-kitty.charter&lt;/code&gt;.&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: running &lt;code dir=&quot;auto&quot;&gt;spec-kitty init&lt;/code&gt; on a machine with no existing projects produces no files in &lt;code dir=&quot;auto&quot;&gt;kitty-specs/doctrine/&lt;/code&gt; and issues no charter-related prompts. Confirmed by integration tests and by verifying that &lt;code dir=&quot;auto&quot;&gt;_run_doctrine_stack_init&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;_run_inline_interview&lt;/code&gt;, and &lt;code dir=&quot;auto&quot;&gt;_apply_doctrine_defaults&lt;/code&gt; do not appear in &lt;code dir=&quot;auto&quot;&gt;init.py&lt;/code&gt;.&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-charterdoctrine-from-init-entirely-chosen&quot;&gt;Option A: Remove charter/doctrine from init entirely (chosen)&lt;/h3&gt;
&lt;p&gt;Delete &lt;code dir=&quot;auto&quot;&gt;_run_doctrine_stack_init()&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;_run_inline_interview()&lt;/code&gt;, and &lt;code dir=&quot;auto&quot;&gt;_apply_doctrine_defaults()&lt;/code&gt;. Charter is authored exclusively via &lt;code dir=&quot;auto&quot;&gt;/spec-kitty.charter&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Logically correct: project governance cannot be authored before the project exists.&lt;/li&gt;
&lt;li&gt;Simpler init; faster machine setup.&lt;/li&gt;
&lt;li&gt;One clear answer to “where do I write my charter?”: &lt;code dir=&quot;auto&quot;&gt;/spec-kitty.charter&lt;/code&gt;.&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;Existing users who relied on init for charter must update their workflow (minor; new workflow is better).&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-b-keep-charter-in-init-make-it-optional-via-a-flag&quot;&gt;Option B: Keep charter in init, make it optional via a flag&lt;/h3&gt;
&lt;p&gt;Retain the charter/doctrine functions but gate them behind a &lt;code dir=&quot;auto&quot;&gt;--with-charter&lt;/code&gt; flag. Skip by default.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Preserves backward compatibility for users who liked running charter during init.&lt;/li&gt;
&lt;li&gt;No user workflow change.&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 code remains in &lt;code dir=&quot;auto&quot;&gt;init.py&lt;/code&gt; even though the default path skips it.&lt;/li&gt;
&lt;li&gt;The flag encourages the logically wrong workflow (running charter before a project exists).&lt;/li&gt;
&lt;li&gt;Every init flag is a maintenance commitment. A flag for a wrong workflow is a maintenance commitment to a wrong workflow.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Why Rejected:&lt;/strong&gt; Optional code is still code. The workflow is wrong regardless of whether it is gated. The right answer is to remove it and document the correct workflow.&lt;/p&gt;
&lt;h3 id=&quot;option-c-move-charter-to-a-spec-kitty-setup-per-project-command&quot;&gt;Option C: Move charter to a &lt;code dir=&quot;auto&quot;&gt;spec-kitty setup&lt;/code&gt; per-project command&lt;/h3&gt;
&lt;p&gt;Create a new &lt;code dir=&quot;auto&quot;&gt;spec-kitty setup&lt;/code&gt; command that handles per-project initialization including charter. Remove charter from init.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Distinguishes machine init from project init at the CLI command level.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty setup&lt;/code&gt; would be the natural home for charter, &lt;code dir=&quot;auto&quot;&gt;.gitignore&lt;/code&gt; writing, and other per-project concerns.&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;Creating &lt;code dir=&quot;auto&quot;&gt;spec-kitty setup&lt;/code&gt; is a significant new surface area.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;/spec-kitty.charter&lt;/code&gt; already exists and is the intended charter authoring surface.&lt;/li&gt;
&lt;li&gt;Implementing &lt;code dir=&quot;auto&quot;&gt;spec-kitty setup&lt;/code&gt; in the context of feature 076 would expand scope beyond the init overhaul.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Why Rejected:&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;/spec-kitty.charter&lt;/code&gt; is the correct and already-implemented charter authoring surface. A new &lt;code dir=&quot;auto&quot;&gt;spec-kitty setup&lt;/code&gt; command is the right long-term direction but is out of scope for feature 076. The per-project setup concern is documented as a Non-Goal in the spec.&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-015 (command completes without creating or prompting about charter, doctrine, missions, REPO_MAP/SURFACES, or dashboard), Non-Goals section (“Per-project setup… belongs in a future &lt;code dir=&quot;auto&quot;&gt;spec-kitty setup&lt;/code&gt;”)&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 (establishes the machine/project boundary that makes this separation necessary)&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:392–572&lt;/code&gt; — the three doctrine functions to be removed&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/init.py:1261&lt;/code&gt; — call site for &lt;code dir=&quot;auto&quot;&gt;_run_doctrine_stack_init&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;tests/specify_cli/test_init_doctrine.py&lt;/code&gt; — test file to be deleted&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
