Skip to content

Instantly share code, notes, and snippets.

@danialhasan
Last active December 15, 2025 17:15
Show Gist options
  • Select an option

  • Save danialhasan/0ae864d7566aacda8dc197f4082a4604 to your computer and use it in GitHub Desktop.

Select an option

Save danialhasan/0ae864d7566aacda8dc197f4082a4604 to your computer and use it in GitHub Desktop.

Shafan's Journey: SF Demo MVP User Story

Date: 2025-12-15 Purpose: Reverse-engineer ticket specs from end-user experience Protagonist: Shafan (beta tester, SF Demo target user)


Executive Summary

This document traces what Shafan actually SEES and DOES when using Squad with all SF Demo MVP features implemented. By designing from the user's perspective first, we can validate that our backend system designs create a coherent experience.

Key Insight: We have comprehensive backend specs but lack a unified UI journey document.


Act 1: Setup (Already Works)

Scene 1: Sign In

Shafan opens Squad Desktop.
→ Signs in with username/password 
→ Lands on workspace dashboard

Status: ✅ Works today

UI Elements:

  • Auth modal
  • Workspace selector
  • Dashboard with recent activity

Scene 2: Connect His Claude CLI

Shafan clicks "Connect CLI"
→ Squad detects his ~/.claude/credentials.json
→ Runs connection test: claude -p "if you can hear me, say hello"
→ Shows: "Claude Code connected - shafan@..."
→ Green checkmark appears

Connection Test Flow:

  1. Detect ~/.claude/credentials.json exists
  2. Run claude -p "if you can hear me, say hello" to confirm harness works
  3. If successful → Green checkmark, connected state
  4. If credentials expired → See "Expired Credentials" flow below

Expired Credentials Flow:

┌─────────────────────────────────────────────────┐
│ ⚠️ CLI Credentials Expired                      │
├─────────────────────────────────────────────────┤
│ Your Claude CLI credentials have expired.       │
│                                                 │
│ To refresh:                                     │
│ 1. Open your terminal                           │
│ 2. Run claude                                   │
│ 3. Run /login                                   │
│ 4. Complete authentication                      │
│ 5. Return here and click "Refresh Auth"         │
│                                                 │
│ [Refresh Auth]                                  │
└─────────────────────────────────────────────────┘

Status: 🟡 Partial - connection works, expired creds handling missing

UI Elements Needed:

  • Harness connection card (with connection status indicator)
  • Expired credentials warning modal
  • Refresh auth button
  • Connection test spinner/progress

Scene 2.5: Connect Integrations

Shafan clicks "Integrations" in sidebar
→ Sees list of available integrations
→ Connects GitHub, Linear, Slack (via OAuth)
→ Squad now has access to these data sources

Why This Matters: Data sources are accessed via MCP servers, but can only be accessed AFTER integrations are connected. The Director needs these to fully understand context when planning.

Available Integrations (MVP):

  • GitHub — Repository access for code context
  • Linear — Issue/ticket context
  • Slack — Communication context (optional)
  • Google Drive — Doc context (optional)

Connection Flow:

┌─────────────────────────────────────────────────┐
│ 🔌 Integrations                                 │
├─────────────────────────────────────────────────┤
│ Connect services to give Squad full context     │
│                                                 │
│ ┌─────────────────────────────────────────────┐ │
│ │ 🐙 GitHub                    [Connect]      │ │
│ │    Repository access for code context       │ │
│ └─────────────────────────────────────────────┘ │
│                                                 │
│ ┌─────────────────────────────────────────────┐ │
│ │ 📊 Linear                    [Connect]      │ │
│ │    Issue tracking context                   │ │
│ └─────────────────────────────────────────────┘ │
│                                                 │
│ ┌─────────────────────────────────────────────┐ │
│ │ 💬 Slack                     [Connect]      │ │
│ │    Team communication context               │ │
│ └─────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────┘

Status: ❌ Not implemented - Integration UI needed

UI Elements Needed:

  • Integrations page/drawer
  • Integration cards with connect buttons
  • OAuth flow handling
  • Connected status indicators
  • MCP server status (behind the scenes)

Act 2: The Task (Director Interaction)

Scene 3: Start a Conversation

Shafan types in Director chat:
"I want to add a dark mode toggle to the settings page"

What Director Does (ALL VISIBLE to Shafan):

  1. Spawns Explore subagent to understand codebase
  2. Crawls connected integrations (GitHub, Linear, etc.) via MCP servers
  3. Depth-progressive planning (9 levels: business → contracts → code)
  4. Creates "container" with frozen contracts

Key Insight: NOTHING is hidden. Shafan sees:

  • Every subagent spawned
  • Every tool call made
  • All reasoning from the Director
  • All data sources being accessed

These are visualized via JSON streamed from the Claude Code harness.

What Shafan SEES (Left Panel - Data Stream):

┌─────────────────────────────────────────────────┐
│ 🤖 Talking to: Director (Orchestrator)          │
├─────────────────────────────────────────────────┤
│ You: I want to add a dark mode toggle to the    │
│      settings page                              │
│                                                 │
│ Director: Let me understand your codebase...    │
│                                                 │
│ ┌─ Subagent: Explore ─────────────────────────┐ │
│ │ 🔍 Scanning project structure               │ │
│ │ ├─ Read: src/components/settings/...        │ │
│ │ ├─ Read: src/stores/...                     │ │
│ │ ├─ Tool: mcp_github.list_files              │ │
│ │ └─ Tool: mcp_linear.get_related_issues      │ │
│ └─────────────────────────────────────────────┘ │
│                                                 │
│ Director: Based on my analysis of your codebase │
│           and related Linear tickets...         │
└─────────────────────────────────────────────────┘

What Shafan SEES (Right Panel - Director State):

┌─────────────────────────────────────────────────┐
│ ⚡ Director State                               │
├─────────────────────────────────────────────────┤
│ 🟠 Planning                                     │
│ │ Analyzing codebase and connected integrations │
│                                                 │
│ Data Sources Accessed:                          │
│ • GitHub: danialhasan/squad (5 files)           │
│ • Linear: SQD-24, SQD-27 (related tickets)      │
│                                                 │
│ Subagents Active: 1                             │
│ └─ Explore: Scanning settings components        │
└─────────────────────────────────────────────────┘

After Director Completes Analysis:

┌─────────────────────────────────────────────────┐
│ Director: I've analyzed your project. Here's    │
│           my plan:                              │
│                                                 │
│ ┌─────────────────────────────────────────────┐ │
│ │ ## Dark Mode Implementation                 │ │
│ │                                             │ │
│ │ 1. Create theme store (Pinia) - ~2 hours   │ │
│ │ 2. Add toggle component - ~1 hour          │ │
│ │ 3. Wire CSS variables - ~2 hours           │ │
│ │ 4. Persist preference - ~30 min            │ │
│ │                                             │ │
│ │ **Parallelization:** 2 engineers can work  │ │
│ │ simultaneously on (1,4) and (2,3)          │ │
│ └─────────────────────────────────────────────┘ │
│                                                 │
│ Do you want me to proceed?                      │
│                                                 │
│ [Approve Plan] [Modify Plan] [Cancel]           │
└─────────────────────────────────────────────────┘

Observability Features:

  • Shafan CAN see contracts/schemas being created
  • Shafan CAN drill into each step for detail
  • Shafan CAN see all tool calls in real-time
  • Shafan CAN see reasoning from Director

Status: ❌ Not implemented - Director chat exists but not observability UI

UI Elements Needed:

  • Plan card with structured breakdown
  • Subagent activity panel (showing Explore agent work)
  • Tool call log (mcp_github, mcp_linear, etc.)
  • Data sources accessed indicator
  • Effort estimates per task
  • Parallelization indicator
  • Approve/Modify/Cancel buttons

Scene 4: Shafan Approves

Shafan clicks [Approve Plan]

What Shafan SEES (Squad Spawning - ALL VISIBLE):

┌─────────────────────────────────────────────────┐
│ 🤖 Talking to: Director (Orchestrator)          │
├─────────────────────────────────────────────────┤
│ Director: Spawning Squad for "Dark Mode"...     │
│                                                 │
│ ┌─ Tool Call: meta_mcp.spawn_squad ───────────┐ │
│ │ squad_name: "Dark Mode Implementation"       │ │
│ │ manager_count: 1                             │ │
│ │ engineer_count: 1                            │ │
│ │ constraints: [...]                           │ │
│ └─────────────────────────────────────────────┘ │
│                                                 │
│ ┌─ Tool Call: meta_mcp.spawn_manager ─────────┐ │
│ │ manager_id: "manager-alpha"                  │ │
│ │ mission: "Dark Mode Implementation"          │ │
│ │ container: { frozen_contracts: [...] }       │ │
│ └─────────────────────────────────────────────┘ │
│                                                 │
│ ┌─ Tool Call: meta_mcp.spawn_engineer ────────┐ │
│ │ engineer_id: "engineer-alpha"                │ │
│ │ assigned_to: "manager-alpha"                 │ │
│ │ worktree: "dark-mode-eng-alpha"              │ │
│ └─────────────────────────────────────────────┘ │
│                                                 │
│ Director: Squad spawned! Manager is now         │
│           coordinating 1 engineer.              │
└─────────────────────────────────────────────────┘

Right Panel Updates:

┌─────────────────────────────────────────────────┐
│ ⚡ Squads                               1       │
├─────────────────────────────────────────────────┤
│ 🟢 Dark Mode Squad                   2 agents   │
│    Active                                       │
└─────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────┐
│ 🎯 Missions                            1        │
├─────────────────────────────────────────────────┤
│ DARK MODE SQUAD                                 │
│ │ Dark Mode Implementation                      │
│ │ Add dark mode toggle to settings page         │
└─────────────────────────────────────────────────┘

Tool Calls Visualized (from Meta-MCP server):

  • meta_mcp.spawn_squad — Creates the Squad container
  • meta_mcp.spawn_manager — Spins up Manager with mission
  • meta_mcp.spawn_engineer — Spins up Engineer(s) in worktrees

Transition: UI shows Squad in "Agents" tab, Shafan can now watch execution


Act 3: Execution (Multi-Agent Orchestra)

Scene 5: Manager Takes Over

Key Insight: NOTHING is behind the scenes. Shafan sees:

  • Manager spinning up worktrees
  • Engineers moving to work in them
  • All tool calls, reasoning, and state changes

UI Layout:

Left Panel - Agent Data Stream:

┌─────────────────────────────────────────────────┐
│ 💬 Talking to: Manager (Manager) ▾   Status: 🟢 │
│                                                 │
│ Type below or use quick commands to steer agent │
│                                                 │
│                                     0 events  ↻ │
├─────────────────────────────────────────────────┤
│                                                 │
│ [Agent logs stream here - all tool calls,       │
│  reasoning, file reads, file writes visible]    │
│                                                 │
│ Manager: Setting up worktrees for engineers...  │
│                                                 │
│ ┌─ Tool Call: git worktree add ───────────────┐ │
│ │ path: .worktrees/dark-mode-eng-alpha         │ │
│ │ branch: feat/dark-mode-theme-store           │ │
│ └─────────────────────────────────────────────┘ │
│                                                 │
│ Manager: Assigning Engineer Alpha to theme      │
│          store implementation...                │
│                                                 │
└─────────────────────────────────────────────────┘

Right Panel - Squad State:

┌─────────────────────────────────────────────────┐
│ 🎯 Squad & Mission                              │
├─────────────────────────────────────────────────┤
│ Squad                                           │
│ Dark Mode Squad                                 │
│                                                 │
│ Mission                                         │
│ Dark Mode Implementation                        │
│                                                 │
│ [Healthy SaaS] [RUN]                           │
│                                                 │
│ 2 agents active · 45 tests · 12 receipts        │
└─────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────┐
│ 🤖 Agent State                                  │
├─────────────────────────────────────────────────┤
│ Manager                            [INTEGRATE]  │
│ Manager                                         │
│                                                 │
│ 🟢 Coordinating                                 │
│ │ Container oversight and PR reviews for        │
│ │ dark mode implementation                      │
│                                                 │
│ Coordinates squad activities, breaks down       │
│ missions into tasks, and ensures constraints    │
│ are met. Routes work to engineers based on      │
│ expertise and current load.                     │
└─────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────┐
│ ⚡ Squad Roster                                  │
├─────────────────────────────────────────────────┤
│ 🟢 Manager                         [INTEGRATE]  │
│                                                 │
│ 🟢 Engineer Alpha                      [GREEN] >│
│                                                 │
│ 🟢 Engineer Bravo                     [REFINE] >│
└─────────────────────────────────────────────────┘

Engineer View (when Shafan clicks into an Engineer):

Engineer cards are BASIC for MVP - just logs, no fancy status cards yet. When Shafan clicks Engineer Alpha in the roster:

Key Insight: Engineers leverage subagent orchestration for TDD phases. Each phase can spawn specialized subagents.

┌─────────────────────────────────────────────────┐
│ 💬 Talking to: Engineer Alpha ▾     Status: 🟢  │
├─────────────────────────────────────────────────┤
│ Engineer Alpha: Starting TDD cycle for          │
│                 ThemeStore implementation...    │
│                                                 │
│ ┌─ Subagent: test-writer (RED phase) ───────────┐ │
│ │ 📝 Writing failing test for ThemeStore        │ │
│ │ ├─ Tool: Write → theme.test.ts                │ │
│ │ ├─ Tool: Bash → pnpm test                     │ │
│ │ └─ Result: FAIL (expected)                    │ │
│ └─────────────────────────────────────────────┘ │
│                                                 │
│ Engineer Alpha: RED phase complete. Spawning    │
│                 implementation subagent...      │
│                                                 │
│ ┌─ Subagent: implementer (GREEN phase) ─────────┐ │
│ │ 🔧 Implementing ThemeStore to pass tests      │ │
│ │ ├─ Tool: Read → existing store patterns       │ │
│ │ ├─ Tool: Write → src/stores/theme.ts          │ │
│ │ ├─ Tool: Bash → pnpm test                     │ │
│ │ └─ Result: PASS ✓                             │ │
│ └─────────────────────────────────────────────┘ │
│                                                 │
│ Engineer Alpha: GREEN phase complete. Verifying │
│                 in real environment...          │
│                                                 │
│ ┌─ Subagent: verifier ──────────────────────────┐ │
│ │ 🔍 Verifying ThemeStore in Electron app       │ │
│ │ ├─ Tool: electron-mcp.launch_app              │ │
│ │ ├─ Tool: electron-mcp.click → settings        │ │
│ │ ├─ Tool: electron-mcp.click → dark mode toggle│ │
│ │ ├─ Tool: electron-mcp.screenshot              │ │
│ │ └─ Result: Theme toggled successfully ✓       │ │
│ └─────────────────────────────────────────────┘ │
│                                                 │
│ Engineer Alpha: Verification complete.          │
│                 Ready for Manager review.       │
└─────────────────────────────────────────────────┘

Verification Subagent Tools (by app type):

App Type Verification Tool Example
Electron Desktop electron-mcp Click UI, take screenshots, verify state
Full Stack Web chrome-devtools Navigate, inspect DOM, check console
Backend API curl / httpie Call endpoints against API contracts
CLI Tool Bash Run commands, verify output

What Shafan CAN Do:

  • Click into ANY agent's data stream
  • See ALL tool calls in real-time
  • Interact with agents directly (type in chat)
  • Pause execution
  • Drill down into any activity

What's Visible (NOTHING hidden):

  • Manager creating worktrees
  • Engineers moving to work in them
  • TDD cycle: RED → RESEARCH → GREEN → INTEGRATE → REFACTOR → FIRE
  • All file reads/writes
  • All test runs
  • All reasoning

Status: 🟡 Partial - Basic agent view exists, needs full observability wiring

UI Elements Needed:

  • Agent data stream panel (left side)
  • Squad roster with status badges (right side)
  • Agent state panel (right side)
  • Tool call visualization in stream
  • Click-to-drill-down into agents
  • Pause/Cancel controls

Scene 6: Receipts Flow In Real-Time

Key Insight: Receipts live on the RIGHT side of the Agent view, alongside Squad Roster and Agent State. The LEFT side is reserved for the chat/data stream.

Right Panel - Receipts Section (from screenshot):

┌─────────────────────────────────────────────────┐
│ 📋 Receipts                                  6  │
├─────────────────────────────────────────────────┤
│ ○                                               │
│ │  [DB Proof] [GREEN]    12/15/2025, 10:19:32 AM│
│ │  [success]                                    │
│ │                                               │
│ │  Verified proration calculations in DB        │
│ │  👤 Engineer Alpha                            │
│ │                                               │
│ ├──────────────────────────────────────────────│
│ │  [Test] [GREEN]        12/15/2025, 10:18:45 AM│
│ │  [success]                                    │
│ │                                               │
│ │  ThemeStore toggle test passed                │
│ │  👤 Engineer Alpha                            │
│ │                                               │
│ ├──────────────────────────────────────────────│
│ │  [Code] [INTEGRATE]    12/15/2025, 10:17:30 AM│
│ │  [pending review]                             │
│ │                                               │
│ │  stores/theme.ts (+45 lines)                  │
│ │  👤 Engineer Alpha                            │
└─────────────────────────────────────────────────┘

Receipt Types:

  • [DB Proof] — Database verification
  • [Test] — Test execution results
  • [Code] — Code changes/diffs
  • [PR] — Pull request created
  • [Research] — Explore agent findings

Receipt Status Badges:

  • [GREEN] — Passing/success
  • [RED] — Failing (expected in TDD)
  • [INTEGRATE] — Ready for integration
  • [REFINE] — Needs refinement

What Shafan Can Do:

  • Click any receipt to expand full details
  • See which engineer produced it
  • See timestamp of every action
  • Track progress through receipts count
  • Filter by type (future)

Layout Context:

┌─────────────────────────────────────────────────────────────┐
│                        Agent View                           │
├──────────────────────────────┬──────────────────────────────┤
│                              │  Squad & Mission             │
│  LEFT: Data Stream           │  Agent State                 │
│  (Chat + Tool Calls)         │  Squad Roster                │
│                              │  Constraints                 │
│                              │  Receipts ← HERE             │
└──────────────────────────────┴──────────────────────────────┘

Status: 🟡 Partial - ReceiptStream.vue exists but not wired to real WebSocket

UI Elements Needed:

  • Receipts panel in right sidebar
  • Receipt cards with type badges
  • Timestamp display
  • Engineer attribution
  • Click-to-expand detail view
  • WebSocket connection for real-time updates

Scene 6.5: Guardrails Interaction

Key Insight: Guardrails control how code changes are applied. This mirrors Claude Code's permission structure!

Three Guardrail Modes:

Mode Description When to Use
Plan Mode No changes allowed Review-only, planning phase
Auto-Apply Edits Apply with approval for dangerous ops Normal development
Bypass Permissions Apply all changes automatically Trusted automation

Forbidden Commands (Preset Out of Box): These ALWAYS require permission in Auto-Apply mode (not in Bypass):

  • rm, rm -rf — File deletion
  • git push --force — Destructive git operations
  • Database drop/truncate — Data destruction

Who Approves?

In Squad, the normal Claude Code human↔agent interaction is replaced with:

  • Engineer proposes changes
  • Manager reviews and approves/rejects

BUT Shafan can jump into any agent's data stream and interact directly!

Guardrails UI (in Project Settings):

┌─────────────────────────────────────────────────┐
│ ⚙️ Guardrails                                   │
├─────────────────────────────────────────────────┤
│ Edit Application Mode:                          │
│ ○ Plan Mode (review only)                       │
│ ● Auto-Apply Edits (with safety checks)         │
│ ○ Bypass Permissions (full autonomy)            │
│                                                 │
│ Forbidden Commands:                             │
│ ┌─────────────────────────────────────────────┐ │
│ │ rm -rf                              [Remove]│ │
│ │ git push --force                    [Remove]│ │
│ │ DROP TABLE                          [Remove]│ │
│ │ [+ Add Command]                             │ │
│ └─────────────────────────────────────────────┘ │
│                                                 │
│ [Save Settings]                                 │
└─────────────────────────────────────────────────┘

Status: ❌ Not implemented - Guardrails UI needed

UI Elements Needed:

  • Guardrails settings panel
  • Mode radio buttons
  • Forbidden commands list
  • Add/remove command controls

Scene 7: Code Diffs Appear

Key Insight: Code diffs appear in the Engineer's data stream. Application depends on Guardrails mode and Manager approval.

The Flow (Engineer → Manager → Apply):

  1. Engineer proposes code change in their data stream
  2. Manager reviews and approves/rejects (with reasoning)
  3. If approved, change is applied (based on Guardrails mode)

Engineer's Data Stream (proposing change):

┌─────────────────────────────────────────────────┐
│ 💬 Talking to: Engineer Alpha        Status: 🟢 │
├─────────────────────────────────────────────────┤
│ Engineer Alpha: I've implemented the ThemeStore.│
│                 Here's the proposed change:     │
│                                                 │
│ ┌─ Proposed Edit: stores/theme.ts ────────────┐ │
│ │   1 │ + import { defineStore } from 'pinia' │ │
│ │   2 │ +                                     │ │
│ │   3 │ + export const useThemeStore = ...    │ │
│ │  ...│ + [45 lines total]                    │ │
│ └─────────────────────────────────────────────┘ │
│                                                 │
│ Engineer Alpha: Ready for Manager review.       │
└─────────────────────────────────────────────────┘

Manager's Data Stream (reviewing):

┌─────────────────────────────────────────────────┐
│ 💬 Talking to: Manager              Status: 🟢  │
├─────────────────────────────────────────────────┤
│ Manager: Reviewing Engineer Alpha's change...   │
│                                                 │
│ ┌─ Review: stores/theme.ts ───────────────────┐ │
│ │ Changes: +45 lines                          │ │
│ │ Tests: ✓ Passing                            │ │
│ │ Coverage: 94%                               │ │
│ └─────────────────────────────────────────────┘ │
│                                                 │
│ Manager: APPROVED. Reasoning: Tests pass,       │
│          follows Pinia conventions, coverage    │
│          meets threshold. Applying change.      │
│                                                 │
│ ┌─ Tool Call: Apply Edit ─────────────────────┐ │
│ │ file: src/stores/theme.ts                    │ │
│ │ status: Applied successfully                 │ │
│ └─────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────┘

Shafan Can Intervene:

Shafan can jump into any agent's stream and override:

  • Type in Engineer's stream to suggest changes
  • Type in Manager's stream to reject/approve manually
  • Pause execution to review before approval

Example - Shafan Intervenes:

┌─────────────────────────────────────────────────┐
│ 💬 Talking to: Manager              Status: 🟢  │
├─────────────────────────────────────────────────┤
│ Manager: Reviewing Engineer Alpha's change...   │
│                                                 │
│ Shafan: Hold on, I want to review this first.   │
│         Show me the full diff.                  │
│                                                 │
│ Manager: Of course. Here's the full diff:       │
│                                                 │
│ ┌─ Full Diff: stores/theme.ts ────────────────┐ │
│ │ [Full side-by-side diff displayed]          │ │
│ └─────────────────────────────────────────────┘ │
│                                                 │
│ Shafan: Looks good. Proceed with approval.      │
│                                                 │
│ Manager: Approved and applying.                 │
└─────────────────────────────────────────────────┘

Status: ❌ Not implemented - Need diff visualization + approval flow

UI Elements Needed:

  • Diff visualization in data stream
  • Manager review card
  • Approval/rejection reasoning display
  • Human intervention capability (chat input)
  • Full diff expansion view

Act 4: Code Lifecycle (Git + GitHub)

Scene 8: PRs Created

Key Insight: PR creation is visible as tool calls in the Engineer's data stream. NOTHING happens behind the scenes.

Engineer's Data Stream (creating PR):

┌─────────────────────────────────────────────────┐
│ 💬 Talking to: Engineer Alpha        Status: 🟢 │
├─────────────────────────────────────────────────┤
│ Engineer Alpha: All tests passing. Creating PR. │
│                                                 │
│ ┌─ Tool Call: Bash ─────────────────────────────┐ │
│ │ command: git checkout -b feat/dark-mode-theme │ │
│ │ result: Switched to new branch                │ │
│ └─────────────────────────────────────────────┘ │
│                                                 │
│ ┌─ Tool Call: Bash ─────────────────────────────┐ │
│ │ command: git add -A && git commit -m "..."    │ │
│ │ result: [feat/dark-mode-theme 7a8b9c0]        │ │
│ └─────────────────────────────────────────────┘ │
│                                                 │
│ ┌─ Tool Call: mcp_github.create_pull_request ──┐ │
│ │ title: "feat(theme): Add ThemeStore"          │ │
│ │ body: "## Summary\n- Dark mode toggle..."     │ │
│ │ base: main                                    │ │
│ │ head: feat/dark-mode-theme                    │ │
│ │ draft: false                                  │ │
│ │                                               │ │
│ │ ✓ Created: PR #101                            │ │
│ └─────────────────────────────────────────────┘ │
│                                                 │
│ Engineer Alpha: PR #101 created and linked.     │
└─────────────────────────────────────────────────┘

Right Panel - PR Receipt Added:

┌─────────────────────────────────────────────────┐
│ 📋 Receipts                                 13  │
├─────────────────────────────────────────────────┤
│ ○                                               │
│ │  [PR] [INTEGRATE]    12/15/2025, 10:42:15 AM  │
│ │  [pending review]                             │
│ │                                               │
│ │  PR #101: feat(theme): Add ThemeStore         │
│ │  +94 lines · 3 files · ✓ tests passing        │
│ │  👤 Engineer Alpha                            │
│ │  [View on GitHub →]                           │
│ │                                               │
│ ├──────────────────────────────────────────────│
│ │  [PR] [INTEGRATE]    12/15/2025, 10:43:02 AM  │
│ │  [pending review]                             │
│ │                                               │
│ │  PR #102: feat(ui): Add DarkModeToggle        │
│ │  +67 lines · 2 files · ✓ tests passing        │
│ │  👤 Engineer Bravo                            │
│ │  [View on GitHub →]                           │
└─────────────────────────────────────────────────┘

Manager's Data Stream (orchestrating PRs):

┌─────────────────────────────────────────────────┐
│ 💬 Talking to: Manager              Status: 🟢  │
├─────────────────────────────────────────────────┤
│ Manager: Both engineers have created PRs.       │
│          Initiating code review...              │
│                                                 │
│ ┌─ Subagent: code-reviewer ─────────────────────┐ │
│ │ 🔍 Reviewing PR #101                          │ │
│ │ ├─ Checking: Code style compliance            │ │
│ │ ├─ Checking: Test coverage                    │ │
│ │ ├─ Checking: Type safety                      │ │
│ │ └─ Result: ✓ Approved                         │ │
│ └─────────────────────────────────────────────┘ │
│                                                 │
│ ┌─ Subagent: code-reviewer ─────────────────────┐ │
│ │ 🔍 Reviewing PR #102                          │ │
│ │ ├─ Checking: Code style compliance            │ │
│ │ ├─ Checking: Test coverage                    │ │
│ │ ├─ Checking: Type safety                      │ │
│ │ └─ Result: ✓ Approved                         │ │
│ └─────────────────────────────────────────────┘ │
│                                                 │
│ Manager: Both PRs reviewed and approved.        │
│          Ready for FIRE gate validation.        │
└─────────────────────────────────────────────────┘

Shafan Can Intervene:

Shafan can jump into any agent's stream to:

  • Request changes to PR title/description
  • Ask for additional tests before review
  • Hold PR creation until manual review
  • Add comments to the PR via the Manager

Example - Shafan Requests Changes:

┌─────────────────────────────────────────────────┐
│ 💬 Talking to: Manager              Status: 🟢  │
├─────────────────────────────────────────────────┤
│ Shafan: Wait, PR #101 needs a migration guide   │
│         in the description. Add that.           │
│                                                 │
│ Manager: Understood. Updating PR description... │
│                                                 │
│ ┌─ Tool Call: mcp_github.update_pull_request ──┐ │
│ │ pr_number: 101                                │ │
│ │ body: "## Summary\n...\n## Migration\n..."    │ │
│ │ ✓ Updated                                     │ │
│ └─────────────────────────────────────────────┘ │
│                                                 │
│ Manager: PR #101 updated with migration guide.  │
└─────────────────────────────────────────────────┘

PR Attribution:

  • PRs are created from user's GitHub account (via connected integration)
  • Co-authored-by: Squad Engineer Alpha squad@trysquad.ai
  • Commit message format: type(scope): description (conventional commits)

Status: ❌ Not implemented - No gh CLI / mcp_github integration yet

UI Elements Needed:

  • PR receipt card (in Receipts panel)
  • Tool call visualization for git/gh operations
  • Code-reviewer subagent activity display
  • View on GitHub link
  • PR status badges (draft, review, approved, merged)
  • Human intervention chat input

Act 5: Governance (FIRE Gate)

Scene 9: FIRE Gate Validation

Key Insight: FIRE Gate validation runs as visible tool calls in the Manager's stream. Shafan sees every check being executed.

Manager's Data Stream (initiating FIRE Gate):

┌─────────────────────────────────────────────────┐
│ 💬 Talking to: Manager              Status: 🟢  │
├─────────────────────────────────────────────────┤
│ Manager: All PRs reviewed. Initiating FIRE Gate │
│          validation before merge...             │
│                                                 │
│ ┌─ Tool Call: fire_gate.validate ───────────────┐ │
│ │ squad_id: "dark-mode-squad"                   │ │
│ │ prs: [101, 102]                               │ │
│ │ require_human_approval: true                  │ │
│ └─────────────────────────────────────────────┘ │
│                                                 │
│ ┌─ FIRE Gate Validation ────────────────────────┐ │
│ │ 🔍 Checking evidence...                       │ │
│ │                                               │ │
│ │ ├─ Tests: Scanning receipts...                │ │
│ │ │  ✓ 12/12 tests passed (PR #101)             │ │
│ │ │  ✓ 8/8 tests passed (PR #102)               │ │
│ │                                               │ │
│ │ ├─ Coverage: Calculating...                   │ │
│ │ │  ✓ 91% > 80% threshold                      │ │
│ │                                               │ │
│ │ ├─ Lint: Checking receipts...                 │ │
│ │ │  ✓ 0 errors, 0 warnings                     │ │
│ │                                               │ │
│ │ ├─ Types: Checking receipts...                │ │
│ │ │  ✓ No type errors                           │ │
│ │                                               │ │
│ │ ├─ Code Review: Checking receipts...          │ │
│ │ │  ✓ Approved by code-reviewer                │ │
│ │                                               │ │
│ │ └─ Result: ✓ ALL CHECKS PASSED                │ │
│ └─────────────────────────────────────────────┘ │
│                                                 │
│ Manager: FIRE Gate passed. Awaiting human       │
│          approval to merge.                     │
└─────────────────────────────────────────────────┘

Right Panel - FIRE Gate Status (in Agent State area):

┌─────────────────────────────────────────────────┐
│ 🔥 FIRE Gate                           PENDING  │
├─────────────────────────────────────────────────┤
│ Validation Results:                             │
│ ✓ Tests passed (20/20)                          │
│ ✓ Coverage: 91% (threshold: 80%)                │
│ ✓ PRs created (2)                               │
│ ✓ Lint: 0 errors                                │
│ ✓ Types: 0 errors                               │
│ ✓ Code review: Approved                         │
│                                                 │
│ ⚠️ Awaiting human approval                      │
│                                                 │
│ Evidence: 14 receipts · 2 PRs                   │
│                                                 │
│ [Approve & Merge] [Request Changes] [Reject]    │
└─────────────────────────────────────────────────┘

What FIRE Gate Checks (from receipts):

Check Receipt Type Required
Tests Pass [Test] receipts ✓ Yes
Coverage Calculated from test receipts ✓ Yes
Lint Clean [Lint] receipts ✓ Yes
Types Clean [Type] receipts ✓ Yes
Code Reviewed [Review] receipts ✓ Yes
PR Created [PR] receipts ✓ Yes

FIRE = Facts, Iteration, Receipts, Evidence:

  • Facts: Concrete proof, not claims
  • Iteration: TDD cycle completed
  • Receipts: Every action has a receipt
  • Evidence: All checks verifiable

Status: ❌ Not implemented - Contract exists but 501 stub

UI Elements Needed:

  • FIRE Gate panel (in right sidebar or modal)
  • Check status indicators (✓/❌/⏳)
  • Evidence count summary
  • Approve/Request Changes/Reject buttons
  • Click-to-expand check details
  • Receipt links for each check

Scene 10: What If FIRE Fails?

Key Insight: Failures are visible in the data stream with actionable details. Shafan sees exactly what failed and why.

Manager's Data Stream (FIRE fails):

┌─────────────────────────────────────────────────┐
│ 💬 Talking to: Manager              Status: 🟠  │
├─────────────────────────────────────────────────┤
│ Manager: FIRE Gate validation in progress...    │
│                                                 │
│ ┌─ FIRE Gate Validation ────────────────────────┐ │
│ │ 🔍 Checking evidence...                       │ │
│ │                                               │ │
│ │ ├─ Tests: ✓ 20/20 passed                      │ │
│ │ ├─ Coverage: ❌ FAILED                        │ │
│ │ │     72% < 80% threshold                     │ │
│ │ │     Missing coverage:                       │ │
│ │ │     • DarkModeToggle.vue:23-31             │ │
│ │ │     • stores/theme.ts:45-52                │ │
│ │ ├─ Lint: ✓ 0 errors                          │ │
│ │ ├─ Types: ✓ 0 errors                         │ │
│ │ ├─ Code Review: ✓ Approved                   │ │
│ │                                               │ │
│ │ └─ Result: ❌ VALIDATION FAILED              │ │
│ └─────────────────────────────────────────────┘ │
│                                                 │
│ Manager: FIRE Gate failed. Coverage at 72%,     │
│          threshold is 80%. Awaiting decision.   │
└─────────────────────────────────────────────────┘

Right Panel - FIRE Gate Status (failed):

┌─────────────────────────────────────────────────┐
│ 🔥 FIRE Gate                           ❌ FAILED │
├─────────────────────────────────────────────────┤
│ Validation Results:                             │
│ ✓ Tests passed (20/20)                          │
│ ❌ Coverage: 72% (threshold: 80%)  [Details ↓]  │
│ ✓ PRs created (2)                               │
│ ✓ Lint: 0 errors                                │
│ ✓ Types: 0 errors                               │
│ ✓ Code review: Approved                         │
│                                                 │
│ ┌─ Coverage Details ────────────────────────────┐│
│ │ Missing coverage in:                         ││
│ │ • DarkModeToggle.vue (lines 23-31)           ││
│ │   - toggleTheme() edge cases                 ││
│ │ • stores/theme.ts (lines 45-52)              ││
│ │   - persistPreference error handling         ││
│ └─────────────────────────────────────────────┘│
│                                                 │
│ [Request More Tests] [Override (Admin)] [Cancel]│
└─────────────────────────────────────────────────┘

Shafan Clicks [Request More Tests]:

┌─────────────────────────────────────────────────┐
│ 💬 Talking to: Manager              Status: 🟢  │
├─────────────────────────────────────────────────┤
│ Shafan: Request more tests.                     │
│                                                 │
│ Manager: Understood. Assigning coverage fix to  │
│          Engineer Alpha...                      │
│                                                 │
│ ┌─ Tool Call: meta_mcp.assign_task ─────────────┐ │
│ │ engineer: "engineer-alpha"                    │ │
│ │ task: "Add test coverage for:"                │ │
│ │       - "DarkModeToggle.vue:23-31"            │ │
│ │       - "stores/theme.ts:45-52"               │ │
│ │ type: "coverage-fix"                          │ │
│ └─────────────────────────────────────────────┘ │
│                                                 │
│ Manager: Engineer Alpha will add missing tests. │
│          Returning to TDD cycle...              │
└─────────────────────────────────────────────────┘

Engineer Alpha's Data Stream (fixing coverage via subagents):

┌─────────────────────────────────────────────────┐
│ 💬 Talking to: Engineer Alpha        Status: 🟢 │
├─────────────────────────────────────────────────┤
│ Engineer Alpha: Received coverage fix request.  │
│                 Spawning test-writer subagent...│
│                                                 │
│ ┌─ Subagent: test-writer (coverage fix) ────────┐ │
│ │ 📝 Adding edge case tests for coverage        │ │
│ │ ├─ Tool: Read → DarkModeToggle.vue:23-31      │ │
│ │ ├─ Tool: Write → DarkModeToggle.test.ts       │ │
│ │ │   + describe('toggleTheme edge cases')      │ │
│ │ ├─ Tool: Read → stores/theme.ts:45-52         │ │
│ │ ├─ Tool: Write → theme.test.ts                │ │
│ │ │   + describe('persistPreference errors')    │ │
│ │ └─ Result: 4 new test cases added             │ │
│ └─────────────────────────────────────────────┘ │
│                                                 │
│ ┌─ Subagent: verifier ──────────────────────────┐ │
│ │ 🔍 Running tests with coverage                │ │
│ │ ├─ Tool: Bash → pnpm test --coverage          │ │
│ │ ├─ Coverage: 84% (✓ threshold met)            │ │
│ │ ├─ Tool: electron-mcp.launch_app              │ │
│ │ ├─ Tool: electron-mcp.click → dark mode       │ │
│ │ └─ Result: All edge cases verified ✓          │ │
│ └─────────────────────────────────────────────┘ │
│                                                 │
│ Engineer Alpha: Coverage at 84%, verified in    │
│                 app. Pushing to PR...           │
└─────────────────────────────────────────────────┘

Admin Override Option:

If Shafan clicks [Override (Admin)]:

┌─────────────────────────────────────────────────┐
│ ⚠️ Admin Override                               │
├─────────────────────────────────────────────────┤
│ You are about to override a FIRE Gate failure.  │
│                                                 │
│ Failed checks:                                  │
│ • Coverage: 72% < 80% threshold                 │
│                                                 │
│ Override reason (required):                     │
│ ┌─────────────────────────────────────────────┐ │
│ │ Shipping urgently for demo. Will fix later.  │ │
│ └─────────────────────────────────────────────┘ │
│                                                 │
│ This will be logged as a governance exception.  │
│                                                 │
│ [Confirm Override] [Cancel]                     │
└─────────────────────────────────────────────────┘

Status: ❌ Not implemented

UI Elements Needed:

  • FIRE Gate failure state (red indicator)
  • Failed check expansion with details
  • Request More Tests flow
  • Admin Override modal with reason input
  • Governance exception logging

Scene 11: Shafan Approves & Merge

Key Insight: Merge is a visible tool call sequence. Shafan sees PRs being merged in real-time.

Shafan Clicks [Approve & Merge]:

Manager's Data Stream (executing merge):

┌─────────────────────────────────────────────────┐
│ 💬 Talking to: Manager              Status: 🟢  │
├─────────────────────────────────────────────────┤
│ Shafan: Approve and merge.                      │
│                                                 │
│ Manager: Human approval received. Merging PRs...│
│                                                 │
│ ┌─ Tool Call: mcp_github.merge_pull_request ───┐ │
│ │ pr_number: 101                                │ │
│ │ merge_method: "squash"                        │ │
│ │ commit_title: "feat(theme): Add ThemeStore"   │ │
│ │                                               │ │
│ │ ⏳ Merging...                                  │ │
│ │ ✓ Merged! SHA: a1b2c3d                        │ │
│ └─────────────────────────────────────────────┘ │
│                                                 │
│ ┌─ Tool Call: mcp_github.merge_pull_request ───┐ │
│ │ pr_number: 102                                │ │
│ │ merge_method: "squash"                        │ │
│ │ commit_title: "feat(ui): Add DarkModeToggle"  │ │
│ │                                               │ │
│ │ ⏳ Merging...                                  │ │
│ │ ✓ Merged! SHA: d4e5f6g                        │ │
│ └─────────────────────────────────────────────┘ │
│                                                 │
│ ┌─ Tool Call: meta_mcp.complete_squad ──────────┐ │
│ │ squad_id: "dark-mode-squad"                   │ │
│ │ status: "completed"                           │ │
│ │ receipts: 15                                  │ │
│ │ prs_merged: 2                                 │ │
│ └─────────────────────────────────────────────┘ │
│                                                 │
│ Manager: ✅ All PRs merged successfully!        │
│          Squad execution complete.              │
└─────────────────────────────────────────────────┘

Right Panel - Completion State:

┌─────────────────────────────────────────────────┐
│ ✅ Execution Complete                           │
├─────────────────────────────────────────────────┤
│ Dark Mode Implementation                        │
│ Successfully merged to main                     │
│                                                 │
│ ┌─ Summary ─────────────────────────────────────┐│
│ │ Duration        1h 23m                       ││
│ │ Engineers       2                            ││
│ │ Files changed   5                            ││
│ │ Lines added     +161                         ││
│ │ PRs merged      2                            ││
│ │ Receipts        15                           ││
│ │ Test coverage   91%                          ││
│ │ FIRE Gate       ✓ Passed                     ││
│ └─────────────────────────────────────────────┘│
│                                                 │
│ 🏆 Squad Performance                            │
│ • TDD cycles completed: 4                       │
│ • Code review: Auto-approved                    │
│ • Human interventions: 0                        │
│ • Governance exceptions: 0                      │
│                                                 │
│ [View Timeline] [View PRs] [View Receipts]      │
│                                                 │
│ [Start New Task]                                │
└─────────────────────────────────────────────────┘

Receipt Timeline View (click "View Timeline"):

┌─────────────────────────────────────────────────┐
│ 📊 Receipt Timeline                             │
├─────────────────────────────────────────────────┤
│ 10:15 AM  [Plan]    Director created container  │
│ 10:16 AM  [Spawn]   Squad created (1M + 2E)     │
│ 10:17 AM  [Test]    Engineer A: RED (expected)  │
│ 10:19 AM  [Code]    Engineer A: ThemeStore      │
│ 10:20 AM  [Test]    Engineer A: GREEN           │
│ 10:22 AM  [Test]    Engineer B: RED (expected)  │
│ 10:25 AM  [Code]    Engineer B: Toggle.vue      │
│ 10:26 AM  [Test]    Engineer B: GREEN           │
│ 10:30 AM  [Review]  Code-reviewer: Approved     │
│ 10:35 AM  [PR]      PR #101 created             │
│ 10:36 AM  [PR]      PR #102 created             │
│ 10:40 AM  [FIRE]    Validation started          │
│ 10:41 AM  [FIRE]    ✓ All checks passed         │
│ 10:42 AM  [Merge]   PR #101 merged              │
│ 10:42 AM  [Merge]   PR #102 merged              │
│ 10:43 AM  [Done]    Squad completed             │
└─────────────────────────────────────────────────┘

Merged PRs View (click "View PRs"):

┌─────────────────────────────────────────────────┐
│ 🔗 Merged Pull Requests                         │
├─────────────────────────────────────────────────┤
│ ✓ PR #101: feat(theme): Add ThemeStore          │
│   Merged at 10:42 AM · +94 lines                │
│   [View on GitHub →]                            │
│                                                 │
│ ✓ PR #102: feat(ui): Add DarkModeToggle         │
│   Merged at 10:42 AM · +67 lines                │
│   [View on GitHub →]                            │
└─────────────────────────────────────────────────┘

What Shafan Can Do Next:

  • View full receipt timeline (audit trail)
  • Click through to merged PRs on GitHub
  • Review individual receipts for detail
  • Start a new task with the Director

Status: ❌ Not implemented - No completion view

UI Elements Needed:

  • Completion summary panel
  • Execution metrics display
  • Receipt timeline view
  • Merged PRs list
  • Performance indicators
  • Start New Task CTA
  • Navigation to Director for new tasks

UI Component Inventory

Exists (Needs Wiring)

Component Location Status
ReceiptStream.vue apps/desktop/ui/src/components/squad-ops/ UI exists, not wired
EngagementTimeline.vue apps/desktop/ui/src/components/squad-ops/ UI exists, not wired
useCliBridge.ts apps/desktop/ui/src/composables/ Composable exists
AgentView.vue apps/desktop/ui/src/views/ Layout exists (matches screenshots)
SquadRoster.vue apps/desktop/ui/src/components/ Roster exists, needs wiring

Needs Creation

Component Purpose Scene Priority
HarnessConnectionCard.vue CLI connection + expired creds 2 P1
IntegrationsPanel.vue OAuth integrations setup 2.5 P1
SubagentActivityPanel.vue Observe subagent work (agent-agnostic) 3, 4, 5, 7, 8, 9, 10, 11 P1
ToolCallLog.vue Show MCP tool calls 3, 4, 5, 8-11 P1
PlanApprovalCard.vue Director plan approval 3 P1
SquadSpawnVisualization.vue Show Squad creation tool calls 4 P1
AgentDataStream.vue Left panel agent logs 5 P1
ReceiptsPanel.vue Right panel receipts list 6 P1
GuardrailsSettings.vue Edit modes, forbidden commands 6.5 P1
DiffVisualization.vue Inline diff in data stream 7 P1
ManagerReviewCard.vue Manager approval reasoning 7 P1
PRReceiptCard.vue Pull request receipt in panel 8 P1
CodeReviewerActivity.vue Show code-reviewer subagent 8 P1
FIREGatePanel.vue Governance validation (right panel) 9 P1
FIREGateCheckItem.vue Individual check with expand 9, 10 P1
AdminOverrideModal.vue Override with reason input 10 P1
CoverageFixFlow.vue Request more tests interaction 10 P2
CompletionSummary.vue Final success panel 11 P1
ReceiptTimeline.vue Chronological receipt view 11 P1
MergedPRsList.vue List of merged PRs 11 P2
PerformanceMetrics.vue TDD cycles, interventions 11 P2

Gap Analysis: Backend vs UI

System Backend Design Backend Impl UI Design UI Impl
CLI Connection 🟡 Partial ✅ NEW
Integrations OAuth 🟡 Partial ✅ NEW
Director Chat ❌ Stub ✅ NEW
Subagent Observability ✅ NEW
Tool Call Visualization ✅ Harness JSON 🟡 Partial ✅ NEW
Squad Spawn ✅ Meta-MCP ✅ NEW
Agent Data Stream 🟡 Partial ✅ Exists 🟡 Partial
Receipt Stream 🟡 Partial ✅ Exists 🟡 Partial
Guardrails ✅ NEW
Manager Approval Flow ✅ NEW
Code Diff ✅ ADR-025 ✅ NEW
PR Creation ✅ mcp_github ✅ NEW
Code Review Subagent ✅ NEW
FIRE Gate ✅ Contract ❌ 501 ✅ NEW
FIRE Failure Handling ✅ NEW
Admin Override 🟡 Implied ✅ NEW
PR Merge ✅ mcp_github ✅ NEW
Completion Summary 🟡 Implied ✅ NEW
Receipt Timeline ✅ NEW
Performance Metrics 🟡 Implied ✅ NEW

Key Design Principles

  1. NOTHING is hidden — Shafan sees all tool calls, subagents, reasoning
  2. Left panel = Data Stream — Chat, tool calls, agent logs
  3. Right panel = State — Squad info, roster, constraints, receipts
  4. Click-to-drill-down — Can jump into any agent's stream
  5. Human can intervene — Type in any agent's stream to steer
  6. Guardrails mirror Claude Code — Plan mode, auto-apply, bypass
  7. Agent View is agent-agnostic — Same UI components work for Director, Manager, Engineer

Subagent Orchestration Patterns

Key Insight: All persistent agents (Director, Manager, Engineer) leverage subagent orchestration. Since the Agent View is agent-agnostic, the same SubagentActivityPanel component visualizes subagent work regardless of which agent is being viewed.

Director Subagents

Subagent Purpose MCP Tools Used
explore Codebase discovery before planning Glob, Grep, Read
researcher Look up docs, patterns, best practices WebSearch, WebFetch, context7
integration-crawler Pull context from connected services mcp_github, mcp_linear, mcp_slack
planner Create depth-progressive container Write (plan files)

Manager Subagents

Subagent Purpose MCP Tools Used
code-reviewer Review PRs before FIRE gate mcp_github.get_pull_request, Read
task-router Break down work, assign to engineers meta_mcp.assign_task
integrator Merge worktrees, resolve conflicts Bash (git), mcp_github
validator Run FIRE gate checks fire_gate.validate

Engineer Subagents

Subagent Purpose MCP Tools Used
test-writer RED phase - write failing tests Write, Bash (pnpm test)
implementer GREEN phase - implement to pass Read, Write, Bash
verifier Verify in real environment electron-mcp, chrome-devtools, curl
refactorer REFACTOR phase - clean up code Read, Write, Edit
researcher RESEARCH phase - look up patterns WebSearch, context7, Read

UI Implication

Since subagent orchestration is universal across agent types, the SubagentActivityPanel component must:

  • Work identically whether viewing Director, Manager, or Engineer
  • Show subagent name, purpose, and current tool call
  • Allow click-to-expand for full subagent activity
  • Display nested subagent activity (subagents can spawn subagents)
┌─────────────────────────────────────────────────┐
│ [Any Agent]: Starting task...                   │
│                                                 │
│ ┌─ Subagent: [name] ([purpose]) ────────────────┐ │
│ │ [emoji] [description of work]                │ │
│ │ ├─ Tool: [tool_name] → [target]              │ │
│ │ ├─ Tool: [tool_name] → [target]              │ │
│ │ └─ Result: [outcome]                         │ │
│ └─────────────────────────────────────────────┘ │
│                                                 │
│ [Any Agent]: Subagent complete. [next step]...  │
└─────────────────────────────────────────────────┘

This pattern repeats across all scenes where agents do work (3, 4, 5, 7, 8, 9, 10, 11)


Recommended Approach

  1. Use this journey as the source of truth for UI components
  2. Derive ticket specs from each Scene's UI Elements Needed
  3. Frontend tickets reference specific scenes
  4. Backend tickets provide APIs that scenes require
  5. Integration tickets wire frontend to backend

Scene Summary (Updated)

Scene Name Key UI Element Status
1 Sign In Auth modal ✅ Works
2 Connect CLI HarnessConnectionCard 🟡 Partial
2.5 Connect Integrations IntegrationsPanel ❌ New
3 Start Conversation SubagentActivityPanel + ToolCallLog ❌ New
4 Approve Plan SquadSpawnVisualization ❌ New
5 Manager Takes Over AgentDataStream + SquadRoster 🟡 Partial
6 Receipts Flow ReceiptsPanel (right side) 🟡 Partial
6.5 Guardrails GuardrailsSettings ❌ New
7 Code Diffs DiffVisualization + ManagerReviewCard ❌ New
8 PRs Created PRReceiptCard + CodeReviewerActivity ❌ New
9 FIRE Gate FIREGatePanel + FIREGateCheckItem ❌ New
10 FIRE Fails FIREGatePanel (error) + AdminOverrideModal ❌ New
11 Completion CompletionSummary + ReceiptTimeline ❌ New

Tool Calls Reference (Meta-MCP + mcp_github)

Meta-MCP Tools (Squad orchestration)

Tool Purpose Used In Scene
meta_mcp.spawn_squad Create Squad container 4
meta_mcp.spawn_manager Spin up Manager agent 4
meta_mcp.spawn_engineer Spin up Engineer agent 4
meta_mcp.assign_task Route task to engineer 10
meta_mcp.complete_squad Mark Squad as done 11
fire_gate.validate Run FIRE Gate checks 9, 10

MCP GitHub Tools

Tool Purpose Used In Scene
mcp_github.create_pull_request Create PR from branch 8
mcp_github.update_pull_request Update PR description 8
mcp_github.merge_pull_request Merge PR to main 11
mcp_github.list_files Get repo file list 3

MCP Linear Tools

Tool Purpose Used In Scene
mcp_linear.get_related_issues Find related tickets 3

Created: 2025-12-15 ~03:15 ET Updated: 2025-12-15 ~08:50 UTC — Acts 1-3 revision based on CTO feedback Updated: 2025-12-15 ~09:30 UTC — Acts 4-5 updated with full observability

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment