Spec Kitty user journey: two developers pair programming with one LLM

pair-programming-two-dev-one-llm.md

User Journey: Mission Collaboration with N Developers and One or More LLM Contexts

Status: DRAFT
Date: 2026-02-15
Primary Contexts: Execution & Review, Collaboration Session & Identity
Supporting Contexts: Mission Orchestration Core, Source-of-Truth Integration, Organization Policy
Related Domain Spec: ../mission-collaboration-platform-ddd/spec.md

Scenario

A team runs a mission with 1 or more developers and one or more LLM contexts. Participants collaborate in real time through local CLI + SaaS without rigid lock-based control.

The initial product slice is observe + decide:

1. Participants can observe mission execution, focus, and warning state in real time.
2. Decision/warning prompts are captured as first-class requests and answered by local driver, remote participant, or another LLM actor.

Actors

1. Participant (human): any developer or reviewer in mission collaboration session.
2. Active Driver (human): participant currently expressing active drive intent.
3. LLM Context (llm): execution context for prompt-step processing.
4. Mission Session Service (SaaS): participant presence, warning timeline, decision inbox, and event broadcast.
5. Local Runtime (CLI): emits canonical collaboration events and handles warning acknowledgements.

Preconditions

1. Story exists in external source of truth (for example Jira/Linear/GitHub).
2. Repo access and local development environment are available for participating developers.
3. Source-of-truth profile is configured.
4. Mission template and execution graph exist.

Journey Map

Phase	Local Participant(s)	SaaS	Key Events
1. Start + Join	First participant starts mission; others join organically.	Session and roster projected live.	MissionStarted, ParticipantInvited, ParticipantJoined, SessionLinked
2. Presence + Intent	Participants set presence and drive intent; multiple active drivers are allowed.	Presence board and intent summary updated continuously.	PresenceHeartbeat, DriveIntentSet, FocusChanged
3. Observe Execution	Prompt step execution progress is streamed to collaborators.	Timeline and current-focus panel update in real time.	PromptStepExecutionStarted, PromptStepExecutionCompleted
4. Advisory Coordination	If focus overlaps create risk, warnings are emitted (not hard-blocked).	Warning panel highlights risk + affected participants.	ConcurrentDriverWarning, PotentialStepCollisionDetected
5. Decide + Acknowledge	Participants explicitly continue/hold and capture rationale.	Decision inbox and audit trail persist answers and actor identity.	WarningAcknowledged, DecisionCaptured, CommentPosted
6. Review + Complete	Team converges through review and closes mission outcome.	Outcome, sync status, and conflict queue are projected.	WPStatusChanged, MissionCompleted, ExternalSyncObserved, ConflictQueuedForHuman

Coordination Rules (Soft Coordination Default)

1. Any participant may set drive intent to active/inactive.
2. Multiple active drivers are valid state.
3. Overlap on same WP/step emits warnings; default behavior is advisory.
4. Progression may continue after explicit acknowledgement.
5. No lock lease is required in default mode.

Observe + Decide Scope (M1)

1. Observe:

• participants and presence
• drive intent per participant
• current focus per participant (WP/step)
• prompt-step execution started/completed
• warning timeline

2. Decide:

• warning acknowledgement actions (continue, hold, reassign, defer)
• comment + decision capture with normalized actor identity
• decision source can be local user, remote user, or LLM actor

CLI/IDE Responsibilities

1. Join mission and set role/focus/drive intent.
2. Emit canonical collaboration events.
3. Run advisory checks before execution and prompt for acknowledgement.
4. Preserve offline queue + replay for collaboration events.
5. Attach commit context to emitted events when repository context is available.

SaaS Responsibilities

1. Materialize and broadcast collaboration state for N participants.
2. Show multiple active drivers and collision-risk warnings.
3. Persist warning acknowledgements, comments, and decisions as auditable timeline entries.
4. Provide decision inbox for pending requests.
5. Keep source-of-truth conflict queue behavior.

Required Event Set (M1)

1. ParticipantInvited
2. ParticipantJoined
3. ParticipantLeft
4. PresenceHeartbeat
5. DriveIntentSet
6. FocusChanged
7. PromptStepExecutionStarted
8. PromptStepExecutionCompleted
9. ConcurrentDriverWarning
10. PotentialStepCollisionDetected
11. WarningAcknowledged
12. CommentPosted
13. DecisionCaptured
14. SessionLinked

Acceptance Scenarios

1. Given 3 participants in one mission run, when two set active drive intent, then both are visible and mission remains executable.
2. Given overlapping focus on same step, when execution is attempted, then warning events are emitted and projected.
3. Given warning prompt, when participant selects continue/hold, then acknowledgement is persisted and actor-attributed.
4. Given intermittent connectivity, when client reconnects, then offline replay preserves event order and warning context.
5. Given remote observer decides on warning, when decision is accepted, then timeline reflects remote actor identity and resulting state.

Product Alignment

1. Local-first execution remains primary.
2. SaaS adds shared visibility, advisory coordination, and governance.
3. MVP uses observe+decide instead of lock-centric control.

Alternate Flows

Not formatted as per main spec, top-of-mind structured alternate flows. I might add more later on.

note: I will be using the term Human In Charge (HiC) to indicate ownership / accountability should always remain with the humans operating / interacting with the system.

Driver Switching / AFK-mode

Context: One of the HiCs wishes to swich roles

1. Driver / Navigator indicates the desire to switch. ( RoleSwitchRequested )
2. Counterpart accepts / denies request. ( RoleSwitchAccepted )
   3.a. System logs event ( RoleSwitchRegistered )
   3.b. System / Agentic service checks current work item status ( in progress -> RoleSwitchPostponed. )
   3.b. Service formally switches roles. ( e.g. RoleSwitchCompleted). Control is transferred

Agentic System Detects Ambiguity

Context:
During PromptStep execution : agentic executor detects anomaly/ambiguity that requires intervention of the human in charge.

1. Agentic executor detects ambiguity that was not previously resolved ( DiscrepancyDetected )
2. Depending on the level of autonomy of the execution ( full auto / AFK mode / monitored / driven ), the agent either:
   2.a. Resolves the ambiguity itself, inferring the best course of action ( AgenticDecisionTaken )
   2.b. Pauses execution, defers to decision making agent for guidancse ( AgenticFeedbackRequested )
   2.c. Pauses execution, defers to Human In Charge to make a decision ( HumanFeedbackRequested)
3. Upon receiving feedback, the operation can continue ( AgenticFeedbackReceived, HumanFeedbackReceived )
   Alternate flow: The decision is made to stop working on the mission altogether until a blocker is resolved. Mission progress is recorded. A new mission is started.