Skip to content

System Context (living)

Who is this for (1)
FieldValue
StatusLiving
Date2026-06-11 (charter service direction added 2026-10-03)
ScopeC4 Level 1 system boundary and external interactions
Related ADRs2026-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

AudienceWhy This View Matters
Project OwnerUnderstands accountability and approval boundaries.
System ArchitectValidates integration and authority contracts.
AI Collaboration AgentAligns execution behavior with host-owned constraints.
Spec Kitty CLI RuntimeEnforces command and state authority boundaries.

Context Diagram (Mermaid)

runs commands, approves decisions

executes prompts, skills, and Ops

calls orchestrator-api contract

tracker commands: local provider

reads and writes canonical project state

Human In Charge (operator)

Agent Tooling — Claude/Codex/Copilot/etc.

External Orchestrator Provider

External Tracker Systems

Project Repository Artifacts — kitty-specs, doctrine, glossary, architecture

Spec Kitty Host (CLI)

Team Kitty SaaS and the Zeitgeist relay are not part of the current boundary: their client code (auth, zeitgeist_client/, saas_client/, the drain posture) was removed from this repository in #6164. The rows below record them only as history.

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.

current commands and writes

current CLI calls

planned governed MCP reads

current direct writes in Python

planned reads through the charter API seam (#645)

planned authored-source read

mission status only

Operator

Agent harness

Spec Kitty CLI

Charter Service — planned, per worktree

Authored charter and pack YAML

Mission Status Read service — sibling

External Mission UI

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 wall-clock status reducer ((at, event_id), with the #4941 approved-departure lift; CLI lane rows carry no Lamport clock, ADR 2026-02-09-3 Amendment 2026-10-22) 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).

Where the pieces live (#6915): the Mission-Status Read API’s Java service and the mission-status contract live in spec-kitty-events (service/, contracts/, released on the service-v* line); core pins the read service for CI conformance only (pins/read-service.source.yaml) and ships the Python reducer.

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.

runs commands, approves

invoke CLI, skills, Ops

planned: HTTP reads over the contract

consumed import

consumed import

publishes

consumed across the contract

Maintainer / Operator
(decision + acceptance authority)

AI coding-agent harnesses
Claude Code, Codex, Copilot, …
(drive the CLI)

External application /
API consumer
(reads mission status; planned)

spec-kitty-events
contract package (wheel) · exists

spec-kitty-tracker
contract package (wheel) · exists

Spec Kitty Core
open-core CLI (Python)
local-first state machine + governance
owns event ledger + wall-clock status reducer
open-core · producer · exists

Mission-Status Read API
contract: spec-kitty-events contracts/mission-status
producer → consumer boundary

Team Kitty— consumer / 'Multiplayer Mode'
mission-ui · pack composer
opaque external · consumer

External Interaction Contracts

External EntityInteraction ContractBoundary Rule
Human In ChargeCommand invocation and approval checkpointsFinal acceptance authority stays human-owned.
Agent ToolingPrompt-, skill-, and Op-driven workflow executionAgents execute within host constraints and the resolved profile’s governance scope.
External Orchestrator ProviderOrchestrator API callsProvider is adapter-only; host remains lifecycle authority.
Team Kitty SaaSHistorical — removed in #6164. Browser-mediated OAuth, repository admission and capability mint no longer ship in this repository.Recorded for orientation only; no shipped client or transport reaches it.
Zeitgeist relayHistorical — removed in #6164. The CLI no longer publishes lane-transition moments.Not part of the current boundary; an unreachable relay cannot affect local persistence because no publish path exists.
External Tracker SystemsTracker commands through the local providerTracker binding is optional and discovered, not user-supplied (2026-04-04-1).
Project Repository ArtifactsFilesystem state read/writeRepository 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).

loads governance context for an action

returns active charter/doctrine policy

opens and closes Ops; advances missions

resolves execution context

returns CWD-invariant context + CommitTarget

guarded commit decision

guarded commit decision

GuardVerdict — allow/refuse on resolved ref

Governance — Charter and Doctrine

Mission Management — lifecycle, status/kanban, planning artifacts

Execution / Runtime — workspace, branch state, mission_runtime

Shared Kernel — value types, identifiers, commit guard

Op Tier — profile-governed invocations and pre/post-mission lifecycle

DomainContext-Level Boundary Statement
GovernanceCharter and Doctrine define what the project may do and how; they are policy inputs, never bypass mission sequencing.
Mission ManagementOwns mission lifecycle, WP status/kanban, status events, and planning artifacts; the sole status authority.
Execution / RuntimeOwns workspace resolution, branch state, and the CWD-invariant mission_runtime execution context.
Shared KernelProvides value types and the single commit-guard decision; holds no domain logic.
Op TierThe 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