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.

The charter is the single authoritative governance document for a Spec Kitty project. All structured config (governance.yaml, directives.yaml, references.yaml) is derived from it. The doctrine layer (src/doctrine/) provides the reusable knowledge artifacts (directives, tactics, paradigms, styleguides, toolguides, procedures, agent profiles, step contracts) that the charter references.

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. Charter (charter.md) — Human-editable markdown. The single authoritative source. Created via interview or written by hand.

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
        ↓
Charter (charter.md)  ← authoritative 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:

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
   • mypy --strict → testing.type_checking: "mypy --strict"
   • 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: pytest             # Test framework
  type_checking: "mypy --strict" # Type checker
quality:
  linting: ruff                 # 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:

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, pytest, 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, python, pytest, ruff, mypy, uv

Interview Profiles

Minimal (8 questions — fast bootstrap):

Comprehensive (11 questions — adds 4 more):

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:
  - "test-first"
selected_directives:
  - "TEST_FIRST"
available_tools:
  - "spec-kitty"
  - "git"
  - "python"
  - "pytest"
  - "ruff"
  - "mypy"
  - "uv"

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: Run the Charter Interview

Fast path (deterministic defaults):

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

Full interactive interview:

spec-kitty charter interview --mission 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 plus extracted YAML files and library/*.md reference documents.

Step 4: Load Context for Workflow Actions

Load governance context before each workflow action:

spec-kitty charter context --action specify --json
spec-kitty charter context --action plan --json
spec-kitty charter context --action implement --json
spec-kitty charter context --action review --json

The runtime calls context automatically during slash commands. Manual invocation is useful for debugging what governance policy an action receives.

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

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=["pytest", "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). A python-implementer specializes from implementer, inheriting base capabilities and adding language-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