priivacy-ai/spec-kitty-charter-doctrine

spec-kitty-charter-doctrine

Manage the charter lifecycle: interview, generate, context-load, sync, and status. Access doctrine artifacts programmatically via DoctrineService. Resolve agent profiles for role-scoped behavior. Load governance context iteratively at action boundaries rather than dumping everything upfront.

.kittify/charter/charter.md is the Spec Kitty runtime governance source for a project. A repository may also keep public governance docs outside .kittify/; those docs are human-facing authority unless the runtime charter summarizes or references them. All structured config (governance.yaml, directives.yaml, references.yaml) is derived from the runtime charter. The doctrine layer (src/doctrine/) provides the reusable knowledge artifacts (directives, tactics, paradigms, styleguides, toolguides, procedures, agent profiles, step contracts) that the charter references.

---

⛔ ARCHITECTURAL INVARIANT: spec-kitty NEVER calls LLMs

spec-kitty is a CLI tool invoked BY an LLM harness (Claude Code, Codex, Cursor, Gemini, etc.). The LLM harness IS the inference engine. spec-kitty must NEVER call any LLM API itself.

This is not a preference. It is a hard architectural rule with no exceptions.

Why this rule exists

| What you are reading this in | What that means | |------------------------------|-----------------| | Claude Code | Claude IS already running. It should generate doctrine. | | Codex CLI | Codex IS already running. It should generate doctrine. | | Cursor / Gemini / Kiro / ... | Same — the harness IS the inference engine. |

If spec-kitty called the Anthropic SDK internally:

• It would need a separate ANTHROPIC_API_KEY — a second API key alongside the one the harness already uses.
• It would bypass the harness entirely, making the agent's reasoning invisible.
• It would make spec-kitty Anthropic-specific, breaking all other harnesses.
• It would be a hidden inference call the user never authorized or configured.
• It would duplicate what the harness can already do better, with full context.

What this means for charter synthesis

Charter synthesis is an LLM reasoning task. YOU (the agent running this skill) are the LLM that should do it.

The synthesis workflow is:

answers.yaml   (the interview answers — what the user told spec-kitty about the project)
     +
doctrine schemas  (the YAML shapes expected for directives, tactics, styleguides)
     +
THIS SKILL  (the instructions you are reading right now)
     ↓
YOU generate the doctrine YAML files
     ↓
spec-kitty CLI commands  (validate, stage, and promote the files you wrote)

spec-kitty's CLI provides validation, schema-checking, DRG validation, neutrality gating, staging, and atomic promotion. It does NOT provide generation — that is your job as the agent.

If you see code that calls anthropic.Anthropic() or imports the anthropic SDK

inside spec-kitty source files, that is a bug. Remove it immediately.

Canonical locations that must NEVER contain import anthropic or any Anthropic SDK call:

• src/charter/ — any file
• src/specify_cli/ — any file
• pyproject.toml — must not list anthropic as a runtime dependency

---

How to Synthesize Doctrine Artifacts (Agent-Driven)

When a user says "synthesize charter doctrine", "generate project doctrine", or "run charter synthesize", you do the following — you do NOT call any CLI command that triggers an LLM. You ARE the LLM.

Step 1 — Read the interview answers

cat .kittify/charter/interview/answers.yaml

This file contains the user's responses: project intent, languages, testing requirements, quality gates, etc.

Step 2 — Read the doctrine schemas for the target artifact kinds

The current synthesis scope is: directive, tactic, styleguide.

Read shipped examples to understand the expected YAML shape:

spec-kitty doctrine list --kind directive
spec-kitty doctrine show <a-directive-id>

spec-kitty doctrine list --kind tactic
spec-kitty doctrine show <a-tactic-id>

spec-kitty doctrine list --kind styleguide
spec-kitty doctrine show <a-styleguide-id>

Step 3 — Read the interview mapping to know what to generate

The interview fields map to target artifact kinds:

• project_intent, quality_gates, risk_boundaries → directives
• testing_requirements → directives + tactics (TDD flavour)
• languages_frameworks → styleguides (language-specific)
• performance_targets, deployment_constraints → directives

For each synthesis target, derive: kind, slug (kebab-case, project-specific), title, and body (the full artifact content as YAML matching the shipped schema).

Step 4 — Write the doctrine YAML to .kittify/charter/generated/

The harness writes artifact inputs here; spec-kitty charter synthesize validates, stages, and promotes them into the live doctrine tree.

.kittify/charter/generated/
  directives/
    <NNN>-<slug>.directive.yaml
  tactics/
    <slug>.tactic.yaml
  styleguides/
    <slug>.styleguide.yaml

Use the shipped artifact YAML structure as your template. Make the content specific to the project based on the interview answers. Do not write generic filler.

Step 5 — Run the full validation stack without promoting

spec-kitty charter synthesize --dry-run

This is a real stage-and-validate pass. It writes the agent-authored artifacts into the staging tree, runs schema validation, project DRG validation, and the neutrality gate, then wipes the staging directory on success.

Step 6 — Promote the validated artifact set

spec-kitty charter synthesize

By default this reads from .kittify/charter/generated/ via the generated adapter and promotes the validated outputs into:

• .kittify/doctrine/ for artifact content and project graph.yaml
• .kittify/charter/provenance/ plus synthesis-manifest.yaml for bookkeeping

Step 7 — Commit the promoted charter synthesis state

git add .kittify/doctrine/ .kittify/charter/provenance/ .kittify/charter/synthesis-manifest.yaml
git commit -m "feat(charter): promote project-local doctrine from generated inputs"

---

---

How the Charter System Works

The charter is a governance-as-code framework. A human-written markdown document captures project policy, and the runtime extracts structured YAML from it to constrain what agents see and do during workflow actions.

The 3-Layer Model

1. Runtime charter (.kittify/charter/charter.md) — Human-editable markdown consumed by Spec Kitty. Created via interview or written by hand. If the repository also has a public constitution or handbook, keep the runtime charter concise: summarize binding directives and reference the public authority through prose or authority_paths.

2. Extracted config — Machine-readable YAML derived deterministically by sync. Never edit these directly — they are overwritten on every sync.

   • governance.yaml — Testing, quality, performance, branching, doctrine selections
   • directives.yaml — Numbered project rules with severity and scope
   • metadata.yaml — Hash, timestamp, extraction mode

3. Doctrine references (library/*.md) — Detailed guidance documents for selected paradigms, directives, and tools. Copied from src/doctrine/ during generation.

Data Flow

Interview Answers (answers.yaml)
        ↓
  [generate command]  ← doctrine templates, mission config
        ↓
Runtime Charter (charter.md)  ← Spec Kitty runtime source
        ↓
  [auto-sync triggered]
        ↓
    ├→ governance.yaml      ← extracted structured config
    ├→ directives.yaml      ← extracted numbered rules
    ├→ metadata.yaml        ← hash, timestamp, extraction mode
    └→ library/*.md         ← copied doctrine reference docs
        ↓
  [context command]  at each workflow action
        ↓
    Text injected into agent prompt

How Sync Extraction Works

The sync command parses charter.md by classifying section headings against a keyword map:

| Heading keyword | Target schema | |---|---| | testing, test, coverage | governance.testing | | quality, lint | governance.quality | | commit | governance.commits | | performance | governance.performance | | branch | governance.branch_strategy | | paradigm, tool, template | governance.doctrine | | directive, constraint, rule | directives.directives |

For each matched section, the parser extracts structured data from:

1. Markdown tables — rows parsed as key-value dicts
2. YAML code blocks — parsed directly
3. Numbered lists — extracted as directive items
4. Keyword patterns — regex matching for quantitative values:
   • 90%+ coverage → testing.min_coverage: 90
   • TDD required → testing.tdd_required: true
   • < 2 seconds → performance.cli_timeout_seconds: 2.0
   • <project-type-checker> → testing.type_checking: "<project-type-checker>"
   • 1 approval → quality.pr_approvals: 1
   • conventional commits → commits.convention: "conventional"
   • pre-commit hooks → quality.pre_commit_hooks: true

Doctrine selections (paradigms, directives, tools, template_set) are merged from YAML blocks and tables that contain keys like selected_paradigms, available_tools, or template_set.

governance.yaml Schema

testing:
  min_coverage: 90              # Minimum test coverage %
  tdd_required: false           # TDD mandatory
  framework: <project-runner>   # Test framework / runner
  type_checking: "<project-type-checker>" # Type checker
quality:
  linting: "<project-linter>"   # Linter
  pr_approvals: 1               # Required approvals before merge
  pre_commit_hooks: false       # Pre-commit hooks required
commits:
  convention: conventional      # Commit convention (or null)
performance:
  cli_timeout_seconds: 2.0      # Max CLI command duration
  dashboard_max_wps: 100        # Max work packages dashboard displays
branch_strategy:
  main_branch: main             # Primary branch
  dev_branch: null              # Development branch (optional)
  rules: []                     # Branch naming/protection rules
doctrine:
  selected_paradigms: []        # Active paradigm IDs
  selected_directives: []       # Active directive IDs
  available_tools: []           # Active tool IDs
  template_set: null            # Mission template set
enforcement: {}                 # Enforcement policy by domain

directives.yaml Schema

directives:
  - id: DIR-001                 # Auto-generated or custom ID
    title: "Short title"        # First 50 chars
    description: "Full text"    # Full description
    severity: warn              # error (blocks), warn (displayed), info (logged)
    applies_to: [implement, review]  # Actions where directive fires

Hash-Based Staleness Detection

Sync uses SHA-256 to detect changes. The hash of charter.md content (whitespace-normalized) is stored in metadata.yaml. On sync:

• If hashes match and --force not set → skip (idempotent)
• If hashes differ → re-extract
• If no metadata.yaml exists → always stale

How Context Gets Injected Into Workflow Actions

When you run /spec-kitty.specify, /spec-kitty.plan, /spec-kitty.implement, or /spec-kitty.review, the runtime automatically calls spec-kitty charter context --action <action>. The returned text is injected into the agent prompt.

Three context modes:

| Mode | When | Content | |---|---|---| | bootstrap | First load for an action | Full policy summary (up to 8 bullets) + reference doc list (up to 10) | | compact | Subsequent loads | Resolved paradigms, directives, tools, template_set only | | missing | No charter exists | Instructions to create one |

First-load state is tracked in .kittify/charter/context-state.json. Each action (specify, plan, implement, review) has an independent first-load timestamp.

Doctrine Artifact Kinds

Doctrine organizes knowledge into 8 artifact kinds. Each kind has a dedicated repository in DoctrineService, follows two-source loading (shipped defaults + project overrides), and is accessible programmatically or via CLI.

Directives — Numbered project rules that constrain agent behavior. Each directive has a severity (error, warn, info), an applies_to scope listing which actions it fires on, and may reference tactics. Directives are the what you must do layer.

directive = service.directives.get("DIRECTIVE_034")
# directive.title → "Test-First Development"
# directive.severity → "warn"
# directive.applies_to → ["implement", "review"]

spec-kitty doctrine list --kind directive

Tactics — Reusable implementation approaches that describe how to do something. Tactics cover testing (TDD, ZOMBIES, acceptance-test-first), domain modeling (bounded context, aggregate boundaries), refactoring (strangler fig, extract class), review (intent-and-risk-first), and planning (problem decomposition, eisenhower). The shipped set includes a refactoring sub-catalog.

tactic = service.tactics.get("tdd-red-green-refactor")
# tactic.title, tactic.description, tactic.steps

Paradigms — High-level development philosophies that group related tactics and directives. A paradigm (e.g., domain-driven-design) declares which tactics it recommends. Paradigms are selected during the charter interview and scope which tactics appear in governance context.

paradigm = service.paradigms.get("domain-driven-design")
# paradigm.tactics → ["bounded-context-identification", ...]

Styleguides — Language- or domain-specific writing and coding style rules. Applied when the charter's languages_frameworks answer matches the styleguide's target language.

styleguide = service.styleguides.get("python-conventions")

Toolguides — Operational guidance for specific tools. Teaches agents how to use git, the project's test runner, diagramming tools, etc. within the project's governance constraints.

toolguide = service.toolguides.get("efficient-local-tooling")

Procedures — Multi-step workflow primitives with prerequisites and ordered steps. Procedures are the reusable building blocks that step contracts delegate to. They describe a complete mini-workflow (e.g., "refactoring", "test-first-bug-fixing", "situational-assessment").

procedure = service.procedures.get("refactoring")
# procedure.steps → ordered list of actions
# procedure.prerequisites → what must be true before starting

Agent Profiles — Role definitions with 6 sections: context_sources, purpose, specialization, collaboration, mode_defaults, and initialization_declaration. Profiles form a hierarchy (specializes_from) and support weighted matching against task context (DDR-011 algorithm).

profile = service.agent_profiles.get("implementer")
# profile.purpose.mandate → what this agent is responsible for
# profile.specialization.boundaries → what it should not do

# Or resolve the best match for a task:
best = service.agent_profiles.find_best_match(task_context)

spec-kitty agent profile list
spec-kitty agent profile show implementer

Step Contracts — Structured action definitions that link public actions (specify, plan, implement, review) to doctrine artifacts via DelegatesTo. Each contract defines ordered steps; each step may delegate to a tactic, directive, or procedure by kind and candidate list.

contract = service.mission_step_contracts.get("implement")
for step in contract.steps:
    if step.delegates_to:
        # Load the referenced doctrine artifact
        artifact = getattr(service, step.delegates_to.kind + "s").get(
            step.delegates_to.candidates[0]
        )

Discovering Available Artifacts

# List all artifacts of a kind
spec-kitty doctrine list --kind directive
spec-kitty doctrine list --kind tactic
spec-kitty doctrine list --kind paradigm

# Show detail for one artifact
spec-kitty doctrine show DIRECTIVE_034

# List agent profiles
spec-kitty agent profile list

Shipped artifacts live in src/doctrine/<kind>/shipped/. Project-local overrides live in .kittify/<kind>/. Two-source loading merges both, with project artifacts taking precedence on field-level merge.

Template sets (from src/doctrine/missions/):

• software-dev-default — Core development workflow
• plan-default — Goal-oriented planning
• documentation-default — Documentation creation (Divio)
• research-default — Research and evidence gathering

Default tool registry: spec-kitty, git

Interview Profiles

Minimal (8 questions — fast bootstrap):

| Question | Governance use | |---|---| | project_intent | Policy summary, preamble | | languages_frameworks | Styleguide selection (e.g., Python) | | testing_requirements | testing.framework, testing.min_coverage | | quality_gates | Quality Gates section | | review_policy | quality.pr_approvals, Branch Strategy | | performance_targets | performance.cli_timeout_seconds | | deployment_constraints | branch_strategy.rules |

Comprehensive (11 questions — adds 4 more):

| Question | Governance use | |---|---| | documentation_policy | Added to Project Directives | | risk_boundaries | Added to Project Directives | | amendment_process | Amendment Process section | | exception_policy | Exception Policy section |

answers.yaml Schema

schema_version: "1.0.0"
mission: "software-dev"
profile: "minimal"
answers:
  project_intent: "..."
  languages_frameworks: "..."
  testing_requirements: "..."
  quality_gates: "..."
  review_policy: "..."
  performance_targets: "..."
  deployment_constraints: "..."
  # comprehensive only:
  documentation_policy: "..."
  risk_boundaries: "..."
  amendment_process: "..."
  exception_policy: "..."
selected_paradigms:
  - "<project-paradigm>"
selected_directives:
  - "<project-directive>"
available_tools:
  - "spec-kitty"
  - "git"
  - "<project-tool>"

---

Step 1: Check Current State

spec-kitty charter status --json

Reports synced or stale, current and stored hashes, library doc count, and per-file sizes. If stale, run sync before relying on governance config.

---

Step 2: Discover the Charter Change

For agent-mediated governance setup and revision, the preferred discovery surface is the chat itself, not the CLI questionnaire.

Recommended flow:

1. Inspect the repo quickly.
2. If a charter already exists, listen for the new guidance the human-in-command is flagging: a charter addition, course correction, observed agent failure, desired norm, or policy change. Ask only the minimum follow-up needed to encode it precisely.
3. If no charter exists or the user asks to start over, ask a short targeted governance interview in chat.
4. Synthesize .kittify/charter/interview/answers.yaml directly.
5. Run spec-kitty charter generate --from-interview --json.

Use the CLI interview only as a fallback when the user explicitly wants the CLI prompt loop or wants deterministic defaults.

CLI defaults path (fallback only):

spec-kitty charter interview --mission-type software-dev --profile minimal --defaults --json

CLI comprehensive path (fallback only):

spec-kitty charter interview --mission-type software-dev --profile comprehensive

Key flags: --profile minimal|comprehensive, --defaults, --json, --selected-paradigms, --selected-directives, --available-tools. See references/charter-command-map.md for all flags.

Output: .kittify/charter/interview/answers.yaml

---

Step 3: Generate the Charter

spec-kitty charter generate --from-interview --json

Key flags: --mission, --template-set, --force, --from-interview, --json.

Generation triggers an automatic sync, so governance.yaml and directives.yaml are written immediately.

Output: .kittify/charter/charter.md, .kittify/charter/references.yaml, and extracted YAML files.

To commit the generated charter inputs, use:

spec-kitty safe-commit --message "chore: generate project charter" \
  .kittify/charter/interview/answers.yaml \
  .kittify/charter/charter.md \
  .kittify/charter/references.yaml \
  .gitignore

---

Step 4: Load Context for Workflow Actions

Do not preload all action contexts after generation.

The runtime calls context automatically during slash commands. Manual invocation is useful only for debugging one immediate action, and should avoid consuming first-load state:

spec-kitty charter context --action specify --json --no-mark-loaded

Load context iteratively at the action boundary, not as part of charter setup.

---

Step 5: Sync After Manual Edits

spec-kitty charter sync --json
spec-kitty charter sync --force --json   # re-extract even if unchanged

Sync is idempotent — skips extraction when the charter hash is unchanged unless --force is passed.

---

Programmatic Doctrine Access (DoctrineService)

DoctrineService is the single entry point for programmatic access to all doctrine artifacts. It lazily instantiates repositories on first access.

from doctrine.service import DoctrineService

service = DoctrineService(shipped_root, project_root)

Available Repositories

| Property | Returns | Artifacts | |---|---|---| | service.agent_profiles | AgentProfileRepository | Agent role profiles with DDR-011 matching | | service.directives | DirectiveRepository | Numbered project rules (TEST_FIRST, etc.) | | service.tactics | TacticRepository | Reusable implementation approaches (TDD, ZOMBIES, etc.) | | service.styleguides | StyleguideRepository | Language/domain writing style guides | | service.toolguides | ToolguideRepository | Tool-specific operational guidance | | service.paradigms | ParadigmRepository | High-level development paradigms | | service.procedures | ProcedureRepository | Multi-step reusable workflow primitives | | service.mission_step_contracts | MissionStepContractRepository | Structured action contracts with delegation |

Common Repository Operations

All repositories share a consistent pattern:

# List all artifacts of a kind
all_tactics = service.tactics.list_all()

# Get a specific artifact by ID
tactic = service.tactics.get("tdd-red-green-refactor")

# Save a project-local artifact (procedures, step contracts)
service.procedures.save(my_procedure)

Agent Profile Resolution

Agent profiles support weighted context-based matching. When the runtime needs to assign an agent to a task, it resolves the best profile:

from doctrine.agent_profiles.profile import TaskContext

context = TaskContext(
    languages=["python"],
    frameworks=["<project-test-runner>", "typer"],
    file_patterns=["src/**/*.py"],
    domain_keywords=["cli", "testing"],
)

profile = service.agent_profiles.find_best_match(context)
# profile.purpose.mandate → what this agent is responsible for
# profile.specialization.boundaries → what it should not do
# profile.initialization_declaration → startup context text

Profiles support hierarchy (specializes_from field). Language-specific profiles can specialize from implementer, inheriting base capabilities and adding stack-specific ones.

Action-Scoped Doctrine via Action Indices

Each mission action (specify, plan, implement, review) has an action index that lists which doctrine artifacts are relevant to that step:

from doctrine.missions.action_index import load_action_index

index = load_action_index(missions_root, "software-dev", "implement")
# index.directives → ["TEST_FIRST"]
# index.tactics → ["tdd-red-green-refactor", "zombies-tdd"]
# index.procedures → ["implementation-handoff"]

The charter context builder uses these indices internally. When you call spec-kitty charter context --action implement, only the doctrine artifacts listed in the implement action index are included.

MissionStepContract: Structured Action Contracts

Step contracts define the structure of each public action and link to doctrine artifacts via DelegatesTo:

contract = service.mission_step_contracts.get("implement")
for step in contract.steps:
    if step.delegates_to:
        # step.delegates_to.kind → ArtifactKind (e.g., "tactic")
        # step.delegates_to.candidates → ["tdd-red-green-refactor", ...]
        pass

This is the bridge between the mission execution surface and the doctrine knowledge layer. Step contracts say what to do; doctrine artifacts say how.

---

Iterative Context Loading Pattern

Agents should load doctrine context iteratively, not all at once. The architecture supports this through depth-controlled context and per-artifact retrieval.

The Pattern

1. At session init: Resolve agent profile. Load initialization_declaration.
2. At each step boundary: Call charter context --action <action>. First call gets bootstrap (depth-2), subsequent calls get compact (depth-1).
3. Mid-step, when guidance needed: Pull specific tactic or directive by ID through DoctrineService.
4. Never: Load the full doctrine catalog into prompt context.

Why This Matters

Each doctrine artifact consumes tokens. Loading all directives, tactics, paradigms, and styleguides at session start wastes context on artifacts that are irrelevant to the current action. Action indices exist specifically to scope which artifacts matter for each step.

---

When Doctrine Constrains Runtime

Doctrine constrains runtime behavior when the charter has been generated and the agent is executing a workflow action (specify, plan, implement, review). The specific constraints come from the project's own charter — load them with spec-kitty charter context --action <action> --json rather than assuming fixed policy values.

Doctrine does NOT constrain when:

• The user works outside a mission.
• No charter has been generated.
• The action is not a workflow action (specify, plan, implement, review).

---

Governance Anti-Patterns

1. Editing derived files — governance.yaml, directives.yaml, and library/*.md are overwritten by sync/generate. Edit charter.md.
2. Skipping the interview — produces generic defaults; the charter is most valuable with project-specific decisions.
3. Stale charter — an outdated charter silently injects wrong policy. Run status to check, sync to fix.
4. Legacy path assumptions — canonical path is .kittify/charter/charter.md, not .kittify/memory/.
5. Upfront context dump — loading all doctrine at session start wastes tokens and dilutes relevance. Use action-scoped loading and pull specific artifacts on demand.

See references/doctrine-artifact-structure.md for the full anti-pattern table.

---

References

• references/charter-command-map.md -- Full CLI command reference with all flags and output fields
• references/doctrine-artifact-structure.md -- File layout, authority classes, and data flow