System Context (living)
Who is this for (1)
- Stakeholder Persona: System Architect — Written for the System Architect reader.
| 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
- Focus on actors, external systems, and authority boundaries.
- Capture why interactions exist and what constraints apply.
- Defer internal module detail to
../02_containers/README.mdand../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)
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.
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.
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 | Historical — 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 relay | Historical — 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 Systems | Tracker commands through the local provider | 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).
| 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
- Mission metadata (
meta.json) carries canonical mission identity (mission_id) and target-line intent used for lifecycle routing (2026-04-09-1). - A single resolved
CommitTarget(ref, kind)is the one destination both planning artifacts and status events resolve to. - Worktree invocation does not transfer canonical lifecycle authority; the resolved context is CWD-invariant.
- The single commit-guard decision authorizes or refuses a commit on that
resolved ref — pushing to
origin/mainis outside the guard’s reach entirely.
Boundary and Trade-off Notes
- Host-owned authority is intentional: orchestration and Team Kitty are pluggable, state-mutation authority is not.
- External integrations are optional by design to preserve local-first operation.
- The model favors traceability and deterministic behavior over implicit automation shortcuts.
Decision Traceability
Traceability
- Domain model ADR:
docs/adr/3.x/2026-06-03-1-execution-state-domain-model.md - Canonical execution surface ADR:
docs/adr/3.x/2026-06-07-1-execution-state-canonical-surface.md - ExecutionContext owner + CommitTarget ADR (incl. 2026-06-10 addendum):
docs/adr/3.x/2026-06-03-2-executioncontext-owner-and-committarget.md - Container view:
../02_containers/README.md - Component view:
../03_components/README.md - Hosted boundary: Team Kitty and Zeitgeist, ADR
2026-09-26-3 - Charter service strangler ADR:
2026-10-03-1