System Context (living)

Field Value
Status Living
Date 2026-06-11 (charter service direction added 2026-10-03)
Scope C4 Level 1 system boundary and external interactions
Related ADRs 2026-06-03-1, 2026-06-03-2, 2026-06-03-3, 2026-06-07-1, 2026-04-09-1, 2026-04-09-2, 2026-09-06-1, 2026-09-26-3, 2026-10-03-1, 2026-10-01-2, 2026-10-12-2

Purpose

Clarify where Spec Kitty starts and ends, who interacts with it, and which boundaries must remain explicit for safe operation.

Scope Rules

  1. Focus on actors, external systems, and authority boundaries.
  2. Capture why interactions exist and what constraints apply.
  3. Defer internal module detail to ../02_containers/README.md and ../03_components/README.md.

Primary Audience

Audience Why This View Matters
Project Owner Understands accountability and approval boundaries.
System Architect Validates integration and authority contracts.
AI Collaboration Agent Aligns execution behavior with host-owned constraints.
Spec Kitty CLI Runtime Enforces command and state authority boundaries.

Context Diagram (Mermaid)

flowchart LR
    hic["Human In Charge (operator)"]
    agent["Agent Tooling — Claude/Codex/Copilot/etc."]
    orch["External Orchestrator Provider"]
    saas["Team Kitty SaaS — auth, capability mint, activity feed"]
    relay["Zeitgeist relay — one volatile container per team"]
    tracker["External Tracker Systems"]
    repo["Project Repository Artifacts — kitty-specs, doctrine, glossary, architecture"]
    sk["Spec Kitty Host (CLI)"]

    hic -->|runs commands, approves decisions| sk
    agent -->|executes prompts, skills, and Ops| sk
    orch -->|calls orchestrator-api contract| sk
    sk -->|browser OAuth, admission check, capability mint| saas
    sk -->|one moment per lane transition, when drain is on| relay
    saas -->|Pulse: polls moments back| relay
    sk -->|tracker commands: local provider or hosted routing| tracker
    saas -->|hosted tracker connectors| tracker
    sk <-->|reads and writes canonical project state| repo

Planned Charter Read and Write Transition

The planned charter service is a separate governance-domain system reached through a CLI charter API seam that #645 plans, or through its own governed MCP interface. Today no such seam exists; callers import charter internals directly. Java becomes the production reader only after conformance; Python remains the production writer until each write operation migrates. Shadow reads and the temporary loud fallback are transition stages owned by ADR 2026-10-03-1.

flowchart LR
    operator["Operator"]
    harness["Agent harness"]
    cli["Spec Kitty CLI"]
    charter["Charter Service — planned, per worktree"]
    sources[("Authored charter and pack YAML")]
    status["Mission Status Read service — sibling"]
    ui["External Mission UI"]

    operator -->|current commands and writes| cli
    harness -->|current CLI calls| cli
    harness -.->|planned governed MCP reads| charter
    cli -->|current direct writes in Python| sources
    cli -.->|planned reads through the charter API seam (#645)| charter
    charter -.->|planned authored-source read| sources
    ui -->|mission status only| status

Solid arrows are current interactions; dotted arrows are planned or future. Direct MCP and Python-seam reads enter the same charter read application and cannot define different semantics.

The Mission Status Read service is a sibling, not a shared process or domain. The external Mission UI consumes status and is not implicitly a charter client.

Open-core producer boundary and Team Kitty = "Multiplayer Mode" (2026-10-12)

The October direction update (operator ruling) frames the system as an open-core producer with Team Kitty as its consumer. Spec Kitty Core (the open-core CLI) owns the event ledger and the Lamport reducer and publishes the Mission Status Read API — the open-core producer surface (ADR 2026-10-01-2, Accepted). Team Kitty — "Multiplayer Mode" (mission-ui, the pack composer) is the consumer: it reads that API across its public contract boundary and is drawn here as a single opaque box, its internals not part of this repository's model. The Python charter stays in core until it is retired; its offering reads cut over to the spec-kitty-charter service through charter.offering.api (ADR 2026-10-03-1, Amendment 2026-10-19; ADR 2026-10-12-2, the earlier extraction direction, is superseded).

Target state, not shipped state: services/mission-status-api/ does not exist yet (only contracts/mission-status/ and the Python reducer ship); the diagram shows the ratified target.

Alt-text: the open-core CLI at the centre; actors Maintainer/Operator, AI coding-agent harnesses and an external API consumer; the CLI consumes spec-kitty-events and spec-kitty-tracker and publishes the Mission-Status Read API seam; one opaque Team Kitty consumer box sits behind the seam.

%%{init: {'theme':'base','themeVariables': {
  'fontFamily': 'Trebuchet MS, Verdana, Arial, sans-serif',
  'fontSize': '15px',
  'primaryColor': '#f5f5f5',
  'primaryTextColor': '#103a82',
  'primaryBorderColor': '#1c75cc',
  'lineColor': '#0a0721'
}}}%%
flowchart LR
    operator["Maintainer / Operator<br/>(decision + acceptance authority)"]
    harness["AI coding-agent harnesses<br/>Claude Code, Codex, Copilot, …<br/>(drive the CLI)"]
    apiConsumer["External application /<br/>API consumer<br/>(reads mission status; planned)"]
    events["spec-kitty-events<br/><i>contract package (wheel) · exists</i>"]
    tracker["spec-kitty-tracker<br/><i>contract package (wheel) · exists</i>"]
    core["<b>Spec Kitty Core</b><br/>open-core CLI (Python)<br/>local-first state machine + governance<br/>owns event ledger + Lamport reducer<br/><i>open-core · producer · exists</i>"]
    seam(["<b>Mission-Status Read API</b><br/>contract: contracts/mission-status/openapi.yaml<br/><i>producer → consumer boundary</i>"])
    teamkitty["<b>Team Kitty</b> — consumer / 'Multiplayer Mode'<br/>mission-ui · pack composer<br/><i>opaque external · consumer</i>"]
    operator -->|runs commands, approves| core
    harness -->|invoke CLI, skills, Ops| core
    apiConsumer -.->|planned: HTTP reads over the contract| seam
    events -->|consumed import| core
    tracker -->|consumed import| core
    core -->|publishes| seam
    seam -->|consumed across the contract| teamkitty
    classDef coreProducer fill:#dceafd,stroke:#1168bd,color:#103a82,stroke-width:2.5px;
    classDef pkg fill:#e3f3e8,stroke:#2f8f52,color:#1d5a34,stroke-width:1.5px;
    classDef seam fill:#fde8c8,stroke:#d9731a,color:#6e3a05,stroke-width:2.5px;
    classDef consumer fill:#f7e6ee,stroke:#b5457f,color:#6e2650,stroke-width:1.5px;
    classDef actor fill:#ffffff,stroke:#5a5a5a,color:#2a2a2a,stroke-width:1.5px;
    class core coreProducer;
    class events,tracker pkg;
    class seam seam;
    class teamkitty consumer;
    class operator,harness,apiConsumer actor;

External Interaction Contracts

External Entity Interaction Contract Boundary Rule
Human In Charge Command invocation and approval checkpoints Final acceptance authority stays human-owned.
Agent Tooling Prompt-, skill-, and Op-driven workflow execution Agents execute within host constraints and the resolved profile's governance scope.
External Orchestrator Provider Orchestrator API calls Provider is adapter-only; host remains lifecycle authority.
Team Kitty SaaS Browser-mediated OAuth, repository admission, capability mint; builds its activity feed by polling the relay Auth is browser-OAuth, not password (2026-04-09-2); membership plus admission is the server-side gate. The host remains the canonical state authority.
Zeitgeist relay The CLI publishes one bounded moment per lane transition, no queue, no retry Volatile and per team. Publishing is opt-in on the client (drain, 2026-09-26-3); an unreachable relay never blocks local persistence. See Team Kitty and Zeitgeist.
External Tracker Systems Tracker commands (local provider, or routed through Team Kitty) Tracker binding is optional and discovered, not user-supplied (2026-04-04-1).
Project Repository Artifacts Filesystem state read/write Repository artifacts are canonical persistent state.

Domain Context Map

The system is organized into four bounded modules that communicate only through Open Host Service (OHS) facades (docs/adr/3.x/2026-06-03-1-execution-state-domain-model.md).

flowchart LR
    governance["Governance — Charter and Doctrine"]
    mission["Mission Management — lifecycle, status/kanban, planning artifacts"]
    execution["Execution / Runtime — workspace, branch state, mission_runtime"]
    kernel["Shared Kernel — value types, identifiers, commit guard"]
    op["Op Tier — profile-governed invocations and pre/post-mission lifecycle"]

    op -->|loads governance context for an action| governance
    governance -->|returns active charter/doctrine policy| op
    op -->|opens and closes Ops; advances missions| mission
    mission -->|resolves execution context| execution
    execution -->|returns CWD-invariant context + CommitTarget| mission
    mission -->|guarded commit decision| kernel
    execution -->|guarded commit decision| kernel
    kernel -->|GuardVerdict — allow/refuse on resolved ref| mission
Domain Context-Level Boundary Statement
Governance Charter and Doctrine define what the project may do and how; they are policy inputs, never bypass mission sequencing.
Mission Management Owns mission lifecycle, WP status/kanban, status events, and planning artifacts; the sole status authority.
Execution / Runtime Owns workspace resolution, branch state, and the CWD-invariant mission_runtime execution context.
Shared Kernel Provides value types and the single commit-guard decision; holds no domain logic.
Op Tier The shared Op shape across spec-kitty dispatch and pre/post-mission lifecycle; governed by a resolved agent profile.

Branch and Routing Boundary

  1. Mission metadata (meta.json) carries canonical mission identity (mission_id) and target-line intent used for lifecycle routing (2026-04-09-1).
  2. A single resolved CommitTarget(ref, kind) is the one destination both planning artifacts and status events resolve to.
  3. Worktree invocation does not transfer canonical lifecycle authority; the resolved context is CWD-invariant.
  4. The single commit-guard decision authorizes or refuses a commit on that resolved ref — pushing to origin/main is outside the guard's reach entirely.

Boundary and Trade-off Notes

  1. Host-owned authority is intentional: orchestration and Team Kitty are pluggable, state-mutation authority is not.
  2. External integrations are optional by design to preserve local-first operation.
  3. The model favors traceability and deterministic behavior over implicit automation shortcuts.

Decision Traceability

Traceability

Edit this page