Feature Specification: Constitution Interview Compiler and Context Bootstrap
Feature: 054-constitution-interview-compiler-and-bootstrap Created: 2026-03-09 Status: Draft Target Branch: feature/agent-profile-implementation Supersedes: 043-doctrine-lite-constitution-generator, 044-constitution-interview-compiler-context-bootstrap
Goals
- Provide a two-step, interview-driven constitution creation workflow:
interviewcaptures answers,generatecompiles them. - Ensure
generatefails with a clear, actionable error when noanswers.yamlexists (no silent defaults). - Remove the
agents.yamlsurface from constitution sync output entirely. - Validate shipped doctrine selections against the shipped catalog at generate-time; reject unknown shipped references while allowing project-local override/supporting files.
- Inject constitution governance context into
specify,plan,implement, andreviewcommand templates for all 12 supported agents (48 files), tracked per-action in a bootstrap state file. - Keep the system deterministic: the same
answers.yaml+ doctrine catalog always produces identical output.
Clarifications
Session 2026-03-09
- Q: Which JSON shape should be canonical for
spec-kitty constitution context --json? → A: Include bothcontextandtext, plusmodeanddepthfor compatibility. - Q: When
spec-kitty constitution generate --forceis used, which files should it replace? → A: All files generated by the command, including sync outputs. - Q: Where should the governance prose extracted from command templates be returned by
spec-kitty constitution context? → A: Both depth 2 and depth 3. - Q: Should
constitution generate --jsonuselibrary_filesto report local override/supporting doctrine files actually used, leaving it empty for shipped-catalog-only runs? → A: Yes. - Q: Are project-local doctrine override files in scope for validation and generation in feature 054? → A: Yes; shipped catalog references are validated strictly, while project-local overrides may be free-form Markdown and are accepted without catalog-ID validation.
- Directive: The doctrine catalog used for validation MUST scan canonised
shipped/artifacts only by default._proposed/artifacts are excluded unless a caller explicitly opts into them for curation workflows. - Q: What should the
index.yamltop-level structure be for action-scoped doctrine declarations? → A: Flat lists per artifact type —directives: [id1, id2],tactics: [id1],styleguides: [...],toolguides: [...]. - Q: What should the top-level structure of
answers.yamlbe? → A: Flat keys at root —selected_paradigm: "...",selected_directives: [...],template_set: "...",available_tools: [...]. - Q: What should each action's entry in
context-state.jsoncontain? → A: Boolean flag + last depth used —{"specify": {"bootstrapped": true, "last_depth": 1}}. - Q: How should governance prose be moved from existing command templates into
guidelines.mdfiles? → A: Hybrid — a migration script creates stubs from detected prose sections; a contributor then refines the content. - Q: When
generateruns without--forceand some output files already exist, what should happen? → A: Warn and ask the user interactively whether they wish to replace the existing files; proceed only on confirmation.
User Scenarios & Testing
US-01 — Interview Captures Answers (P1)
As a maintainer setting up a new project, I run spec-kitty constitution interview to answer guided questions about governance preferences and persist those answers for later compilation.
Acceptance: 1. spec-kitty constitution interview writes .kittify/constitution/interview/answers.yaml. 2. Re-running prompts to confirm overwrite or extend existing answers. 3. Answers file is human-readable and directly editable without breaking the compiler. 4. --json flag emits structured output with path to written answers.yaml.
US-02 — Generate Requires Prior Interview (P1)
As a maintainer, running generate without a prior interview gives a clear, actionable error rather than silently applying defaults.
Acceptance: 1. spec-kitty constitution generate with no answers.yaml exits non-zero and prints: "No interview answers found. Run 'spec-kitty constitution interview' first." 2. Error message includes the expected path (.kittify/constitution/interview/answers.yaml). 3. With answers.yaml present, generate compiles and exits 0. 4. --force overwrites all files generated by generate, including constitution.md, references.yaml, and constitution sync outputs, without prompting. Without --force, if any generated output already exists, generate warns listing conflicting files and prompts the user interactively to confirm; it proceeds only on confirmation and aborts without writing on rejection.
US-03 — Compiled Constitution Output (P1)
As a maintainer, generate produces a readable constitution that acts as a selection manifest — no content is copied or materialised locally.
Acceptance: 1. Output files created: constitution.md, references.yaml. 2. constitution.md contains governance selections, active doctrine IDs, and concise summaries — no full prose content from the doctrine catalog. 3. references.yaml lists each selected shipped doctrine item with source ID and summary, and may also reference project-local override/supporting files used during generation; it does NOT copy shipped doctrine content locally. 4. No generated library/ directory is created. Shipped doctrine content is retrieved at runtime from src/doctrine/, while any project-local override/supporting files are read from their existing project paths. 5. Constitution sync still emits governance.yaml, directives.yaml, metadata.yaml (unchanged). 6. agents.yaml is not emitted by constitution sync.
US-04 — Catalog Validation at Generate-Time (P1)
As a maintainer, referencing a doctrine artifact that does not exist in the shipped catalog fails fast with a useful error.
Acceptance: 1. Unknown selected_directives value → error naming the unrecognized ID. 2. Unknown selected_paradigms value → error naming the unrecognized ID. 3. Unknown template_set value → error naming the unrecognized value. 4. Unknown available_tools value → error naming the unrecognized tool. 5. Valid shipped-catalog selections pass validation without warnings, and project-local override/supporting Markdown files are accepted without catalog-ID validation. 6. Catalog validation scans only canonised shipped/ doctrine artifacts by default; _proposed/ artifacts participate only when explicitly enabled for curation flows.
US-05 — First-Load Context Bootstrap (P1)
As an agent operator, the first time I run specify, plan, implement, or review in a project, the command template instructs me to call spec-kitty constitution context --action <action> to load enriched governance context.
Acceptance: 1. Each of the four command templates includes a step calling spec-kitty constitution context --action <action>. 2. First call for an action writes the bootstrap state and returns a full governance summary (constitution summary + referenced tactic procedures, retrieved from the src/doctrine/missions package). 3. Subsequent calls for the same action return a compact context (directive names only, no full procedures). 4. Bootstrap state is persisted in .kittify/constitution/context-state.json keyed by action name. 5. Missing constitution files degrade gracefully: warning printed, empty context returned, no crash.
US-08 — Iterative Deepening Context Retrieval (P1)
As an agent operator, I can request progressively richer doctrine content at any point, without the template needing to embed the content inline.
Acceptance: 1. spec-kitty constitution context --action specify (depth 1, compact default after first call): returns only directive names and tactic IDs scoped to the specify action index — not all selected directives project-wide. 2. spec-kitty constitution context --action specify --depth 2: returns full directive intent + procedures + tactic steps for directives/tactics listed in the specify action index and selected in references.yaml, plus the per-action governance prose extracted from the specify command template. Directives relevant to implement only are absent. 3. spec-kitty constitution context --action specify --depth 3: returns all depth-2 content and adds styleguide and toolguide details for tools listed in the specify action index. 4. Explicit --depth always overrides the bootstrap auto-selection. 5. Each artifact type is fetched via its own repository service — no type fetches content from another type's service. 6. The first bootstrap call automatically delivers depth-2 content; subsequent calls default to depth-1 (compact).
US-09 — Inline Prose Extracted from Command Templates (P1)
As a contributor, command templates in src/doctrine/missions/*/command-templates/ contain only workflow steps — no embedded governance prose (guidelines, writing rules, success criteria instructions, etc.).
Acceptance: 1. After this feature, all governance prose (e.g., "Quick Guidelines", "Section Requirements", "For AI Generation", "Success Criteria Guidelines") is removed from command template markdown files. 2. The same content is accessible at runtime via spec-kitty constitution context --action <action> --depth 2 and remains present at depth 3. 3. Command templates reference doctrine content by calling constitution context rather than embedding it. 4. The migration deploys the slimmed templates to all 48 agent copies.
US-06 — All 12 Agent Templates Updated (P2)
As a user of any supported AI agent (Claude, Codex, Gemini, Cursor, etc.), the specify, plan, implement, and review templates for my agent include the constitution context bootstrap step.
Acceptance: 1. A migration updates 48 template files (12 agents × 4 commands). 2. Templates that did not previously call constitution context now include the call. 3. Templates are updated via the existing migration mechanism (not manual edits). 4. Migration is idempotent: running it twice produces no duplicate insertions.
US-07 — JSON Output and Scriptability (P2)
As a CI operator, all constitution commands support --json output for scripting.
Acceptance: 1. constitution interview --json emits {"result": "success", "answers_file": "<path>"}. 2. constitution generate --json emits {"result": "success", "constitution_file": "<path>", "references_file": "<path>", "generated_files": [...], "library_files": [...]} where library_files lists any project-local override/supporting doctrine files actually used and is empty when generation relied only on the shipped catalog. 3. constitution context --json --action <action> emits {"result": "success", "context": "<text>", "text": "<text>", "mode": "full|compact", "depth": 1|2|3}. 4. All commands exit non-zero on failure and emit {"error": "<message>"} in JSON mode.
Requirements
Functional Requirements
| ID | Requirement | Priority |
|---|---|---|
| FR-001 | spec-kitty constitution interview MUST write .kittify/constitution/interview/answers.yaml with user selections for paradigms, directives, template set, and available tools. The file uses flat root-level keys: selected_paradigm (string), selected_directives (list), template_set (string), available_tools (list). | P1 |
| FR-002 | spec-kitty constitution generate MUST exit non-zero with an actionable error message if answers.yaml is absent. | P1 |
| FR-003 | spec-kitty constitution generate MUST validate all shipped-catalog selections from answers.yaml against the shipped doctrine catalog before producing any output. The doctrine catalog MUST scan canonised shipped/ artifacts only by default and MUST exclude _proposed/ artifacts unless a caller explicitly opts into them for curation workflows. Project-local override/supporting Markdown files are also in scope and MAY be referenced during generation, but they are accepted without catalog-ID validation. | P1 |
| FR-004 | spec-kitty constitution generate MUST produce constitution.md and references.yaml recording governance selections. It MUST NOT materialise or copy doctrine content locally; shipped doctrine prose is retrieved at runtime from src/doctrine/, while project-local override/supporting files are read from their existing project paths. | P1 |
| FR-005 | Constitution sync MUST emit governance.yaml, directives.yaml, and metadata.yaml. It MUST NOT emit agents.yaml. | P1 |
| FR-006 | spec-kitty constitution context --action <action> MUST return full governance context on first call and compact context on subsequent calls for that action. Content MUST be retrieved live from src/doctrine/ modules — not from any locally materialised copies. | P1 |
| FR-007 | Bootstrap state MUST be persisted in .kittify/constitution/context-state.json keyed by action name. Each action entry contains bootstrapped (boolean) and last_depth (integer), e.g. {"specify": {"bootstrapped": true, "last_depth": 1}}. The last_depth field records the depth used on the most recent call for that action. | P1 |
| FR-008 | A migration MUST update specify, plan, implement, and review templates for all 12 supported agents to call spec-kitty constitution context --action <action>. | P2 |
| FR-009 | The template migration MUST be idempotent (running twice produces no duplicate insertions). | P2 |
| FR-010 | All constitution commands (interview, generate, context) MUST support --json output. | P2 |
| FR-016 | spec-kitty constitution context --json MUST emit both context and text fields containing the same rendered output, plus mode and depth, to preserve compatibility while standardizing the response contract. | P1 |
| FR-011 | --force flag on generate MUST allow overwriting all files produced by the command, including constitution.md, references.yaml, governance.yaml, directives.yaml, and metadata.yaml, without prompting. Without --force, if any of those output files already exist, generate MUST warn listing the conflicting files and prompt the user interactively to confirm overwrite; it proceeds only on confirmation and aborts without writing on rejection. | P1 |
| FR-017 | spec-kitty constitution generate --json MUST report constitution_file, references_file, and generated_files. It MUST also include library_files, which lists only project-local override/supporting doctrine files actually used during generation and MUST be empty when generation relies solely on the shipped doctrine catalog. | P1 |
| FR-018 | spec-kitty constitution generate and spec-kitty constitution context MUST support project-local override/supporting doctrine files in addition to shipped doctrine artifacts. These local files MAY be free-form Markdown; the system SHOULD use shipped validation rules when applicable but MUST NOT reject local override files solely because they do not map to shipped catalog IDs or schemas. | P1 |
| FR-012 | Command templates in src/doctrine/missions/software-dev/command-templates/ MUST NOT embed inline governance prose (software-dev mission only; other missions are out of scope). All extracted prose MUST be stored as per-action doctrine artifacts (guidelines.md) and served at runtime via constitution context. Extraction uses a hybrid approach: a migration script detects and stubs prose sections into guidelines.md files; a contributor then reviews and refines the content. | P1 |
| FR-013 | spec-kitty constitution context MUST support iterative deepening via `--depth <1\ | 2\ |
| FR-014 | On first bootstrap call for an action, constitution context MUST automatically use depth-2. On subsequent calls, it MUST default to depth-1 (compact). An explicit --depth flag ALWAYS overrides the bootstrap auto-selection; bootstrap state determines the default only when --depth is not passed. | P1 |
| FR-015 | Each action's doctrine scope MUST be declared in src/doctrine/missions/software-dev/actions/<action>/index.yaml listing artifact IDs per type. The file uses flat lists keyed by artifact type: directives: [id1, id2], tactics: [id1], styleguides: [...], toolguides: [...]. The retrieval intersection (action index ∩ project selections) MUST be computed at call time; unselected artifacts silently skipped. | P1 |
Non-Functional Requirements
| ID | Requirement | Priority |
|---|---|---|
| NFR-001 | Generation MUST be deterministic: identical answers.yaml + doctrine catalog always produces identical output (excluding timestamps). | P1 |
| NFR-002 | Missing or corrupted constitution files MUST NOT crash context loading; graceful degradation with a printed warning is required. | P1 |
| NFR-003 | Catalog validation errors MUST name the offending ID or value explicitly in the error message. | P1 |
Constraints
| ID | Constraint |
|---|---|
| C-001 | Python 3.11+ and existing specify_cli codebase patterns. No new external dependencies. |
| C-002 | Template migration MUST use get_agent_dirs_for_project() to respect user agent configuration. |
| C-003 | This feature removes agents.yaml from constitution sync output only. It does not modify the agent identity system introduced in feature 048. |
Success Criteria
| ID | Criterion |
|---|---|
| SC-001 | constitution interview + constitution generate complete end-to-end in a clean project and exit 0. |
| SC-002 | constitution generate without prior interview exits non-zero with a message containing the expected answers.yaml path. |
| SC-003 | All four shipped-catalog validation error cases (directive, paradigm, template_set, tool) are covered by tests and produce named-ID error messages, while project-local override/supporting Markdown files are accepted without those catalog-ID failures. Catalog tests also confirm shipped-only scanning by default and explicit _proposed/ inclusion only when requested. |
| SC-004 | agents.yaml is absent from all constitution sync output; any existing tests asserting its presence are removed or updated. |
| SC-005 | constitution context returns different output on first vs. subsequent calls for the same action. |
| SC-006 | Template migration passes in a parametrized test across all 12 agents. |
| SC-007 | Running the migration twice produces no duplicate context bootstrap insertions. |
| SC-008 | After migration, deployed command templates contain no inline governance prose; the sections "Quick Guidelines", "Section Requirements", "For AI Generation", and "Success Criteria Guidelines" (or equivalent) are absent from all 48 agent copies. |
| SC-009 | constitution context --action specify --depth 2 returns the governance content that was previously embedded inline in specify.md. |
| SC-010 | constitution context --json --action specify --depth 2 emits valid JSON with context, text, mode, and depth fields, where context and text are identical. |
| SC-011 | constitution context --action implement --depth 2 does NOT return directives or tactics scoped exclusively to specify. Each action's content is independent. |
Key Entities
| Entity | Description | Location |
|---|---|---|
answers.yaml | Persisted interview answers; sole input to the compiler. Flat root-level keys: selected_paradigm (string), selected_directives (list), template_set (string), available_tools (list). | .kittify/constitution/interview/answers.yaml |
constitution.md | Governance selection manifest: active doctrine IDs, concise summaries, no full prose | .kittify/constitution/constitution.md |
references.yaml | Manifest of selected doctrine items: source ID, summary (no full content copy) | .kittify/constitution/references.yaml |
governance.yaml | Sync-extracted governance selections | .kittify/constitution/governance.yaml |
directives.yaml | Sync-extracted resolved directive list | .kittify/constitution/directives.yaml |
metadata.yaml | Sync-extracted metadata (feature, version, date) | .kittify/constitution/metadata.yaml |
context-state.json | Bootstrap state keyed by action name. Per-action entry: {bootstrapped: bool, last_depth: int}. | .kittify/constitution/context-state.json |
| Doctrine catalog | Shipped directives, paradigms, toolguides, styleguides | src/doctrine/** |
| Project-local overrides | Optional project-local override/supporting doctrine files, potentially free-form Markdown, used alongside shipped doctrine during generation and context assembly | project-defined paths |
src/doctrine/missions package | Python package exposing mission-level doctrine content for runtime retrieval; action-scoped guidelines, writing rules, and tactic references per mission | src/doctrine/missions/ |
| Action index | Per-action declaration of relevant artifact IDs by type (flat lists: directives, tactics, styleguides, toolguides); drives scoped retrieval in constitution context | src/doctrine/missions/software-dev/actions/<action>/index.yaml |
| Action guidelines | Per-action governance prose extracted from templates; returned at depth 2 and depth 3 | src/doctrine/missions/software-dev/actions/<action>/guidelines.md |
Assumptions
- The shipped doctrine catalog (directives 001–026, paradigms, toolguides) remains the authoritative validation source for shipped IDs and is derived from canonised
shipped/artifacts by default. Project-local override/supporting files are also in scope and may be free-form Markdown without matching shipped catalog IDs. interviewis interactive by default; a--non-interactive/ pre-seeded mode is out of scope.DoctrineService(from feature 046,src/doctrine/service.py) is available and provides repository access for all artifact types. This feature wires it intoconstitution context.- This feature implements Phase 1 of the architecture initiative
architecture/2.x/initiatives/2026-03-doctrine-execution-integration/. Phase 2 (Connector Interface Contract) and Phase 3 (Event Store Abstraction) are out of scope. - Full curation alignment of feature 046 doctrine artifacts is not a hard prerequisite; Phase 1 mechanics proceed against the current catalog.
- Features 043 and 044
kitty-specs/directories are retained as historical reference with their status updated tocancelled.
Out of Scope
- Non-interactive interview mode.
- Remote doctrine catalog fetching.
- Mission state-machine redesign.
- Changes to the agent profile identity system (feature 048).
- Telemetry expansion beyond existing patterns.
- Governance prose for missions other than
software-dev(documentation, research, plan missions are not in scope for extraction).