‹ Aigile Playbook Architecture
Engineering Playbook · Architecture Reference

Homogeneous Runtime Architectures

Internal execution boundaries and observability seams within each platform
Hard seam — context lost, no native bridge
Soft seam — partial bridge, human or artifact mediated
No seam — native coordination
Observability Plane insertion point

Claude Code

Anthropic — Local CLI + Desktop + Remote
Runtime execution boundaries and seams
flowchart TD DEV([👤 Developer]) -->|"prompt or
/command"| MAIN subgraph LOCAL ["🖥️ LOCAL — Single Session"] MAIN["Main Session
200k context
state: full
tools: all"] MAIN -->|"Task()
run_in_background:false
sync"| SUB1["Subagent A
own context
tools: scoped
state: isolated"] MAIN -->|"Task()
run_in_background:false
sync"| SUB2["Subagent B
own context
tools: scoped
state: isolated"] SUB1 -.->|"result only
no context
transfer"| MAIN SUB2 -.->|"result only
no context
transfer"| MAIN end subgraph WORKTREE ["🌿 WORKTREE ISOLATION — Parallel Sessions"] WT1["Session A
--worktree feature-auth
own branch
own filesystem
full context"] WT2["Session B
--worktree bugfix-123
own branch
own filesystem
full context"] WT1 -.-|"❌ HARD SEAM
no shared context
no messaging
git merge only"| WT2 end subgraph TEAMS ["👥 AGENT TEAMS — Experimental"] TL["Team Lead
full session
orchestrates"] TM1["Teammate 1
own context
own session
independent"] TM2["Teammate 2
own context
own session
independent"] TL -->|"TeamCreate
TaskCreate"| TM1 TL -->|"TeamCreate
TaskCreate"| TM2 TM1 <-->|"SendMessage
✅ peer messaging
native"| TM2 TM1 -.->|"TaskUpdate
shared task board"| TL TM2 -.->|"TaskUpdate
shared task board"| TL end subgraph REMOTE ["📱 REMOTE CONTROL — Local runs, remote steers"] RC["claude remote-control
local session
full tool access
full context"] RC -->|"steered from
browser / mobile
via Anthropic relay"| RC RC -.-|"⚠️ SOFT SEAM
context stays local
relay is stateless
no trace continuity"| RELAY["Anthropic relay
stateless bridge
no context stored"] end subgraph CI ["🔁 CI/CD HEADLESS — Pipeline execution"] HL["claude -p
headless mode
no interactive session
no /resume"] HL -.-|"❌ HARD SEAM
no session continuity
each run is fresh
no shared state"| MAIN end LOCAL -.-|"❌ HARD SEAM
no context bridge
between worktrees
and main session"| WORKTREE LOCAL -.-|"❌ HARD SEAM
subagent internal
reasoning not
exposed to main"| TEAMS OBS(["🔭 Observability Plane
OTel insertion point
across all boundaries"]) MAIN -->|"metrics + events
native OTLP"| OBS SUB1 -->|"SubagentStop
hook event"| OBS TM1 -->|"TeammateTool
events"| OBS HL -->|"metrics + events
per run"| OBS RC -->|"metrics + events"| OBS style LOCAL fill:#fdf0ec,stroke:#c84b2f,color:#1a1a1a style WORKTREE fill:#f3f0fa,stroke:#6450b4,color:#1a1a1a style TEAMS fill:#eef7f1,stroke:#2d7a4f,color:#1a1a1a style REMOTE fill:#fdf6e3,stroke:#b08a2e,color:#1a1a1a style CI fill:#fdf0ec,stroke:#c84b2f,color:#1a1a1a style MAIN fill:#f7ece8,stroke:#c84b2f,color:#1a1a1a style SUB1 fill:#f7ece8,stroke:#c84b2f,color:#7a7468 style SUB2 fill:#f7ece8,stroke:#c84b2f,color:#7a7468 style WT1 fill:#f0ecfc,stroke:#6450b4,color:#1a1a1a style WT2 fill:#f0ecfc,stroke:#6450b4,color:#1a1a1a style TL fill:#eef7f1,stroke:#2d7a4f,color:#1a1a1a style TM1 fill:#fdf6e3,stroke:#b08a2e,color:#1a1a1a style TM2 fill:#fdf6e3,stroke:#b08a2e,color:#1a1a1a style RC fill:#fdf6e3,stroke:#b08a2e,color:#1a1a1a style RELAY fill:#fdf6e3,stroke:#b08a2e,color:#7a7468 style HL fill:#f7ece8,stroke:#c84b2f,color:#1a1a1a style OBS fill:#f3f0fa,stroke:#6450b4,color:#1a1a1a style DEV fill:#f3f0fa,stroke:#6450b4,color:#1a1a1a
Boundary Seam type What crosses What doesn't cross Failure recovery
Main session → Subagent ⚠ Soft Prompt, tool scope, result text Subagent's internal reasoning, intermediate tool calls Main session retries via new Task() call — internal trace lost
Session → Worktree session ❌ Hard Git history (shared repo) Context window, conversation, session state Manual git merge — no automated return path, no context
Team Lead → Teammate ✅ None Tasks, SendMessage, shared task board on disk Lead's full conversation history (teammates start fresh) TaskUpdate + SendMessage — native coordination channel
Local session → Remote Control ⚠ Soft Commands, approvals via relay Context stored in relay — relay is stateless Local session continues — relay reconnect restores control only
Interactive → Headless CI ❌ Hard CLAUDE.md, hooks, skills (via filesystem) Session state, conversation history, /resume not available Each CI run is isolated — no session continuity, no shared trace

The subagent reasoning gap

The main session sees a subagent's final result text. It does not see the subagent's intermediate tool calls, its internal reasoning steps, or which files it read before writing. This is the most common lost context in Claude Code workflows.

Worktrees — filesystem isolation, not context isolation

Each worktree session is a completely independent Claude Code process. They share git history but nothing else. When you merge worktrees, git handles the code. But the reasoning that produced that code — what the agent tried, what failed, why it chose this approach — is gone.

Observability Plane insertion

Claude Code emits OTel metrics and events natively. The gap is traces — causal spans that link main session → subagent → tool call → result. The Observability Plane adds these, giving you the full reasoning chain across every boundary that native OTel misses.

GitHub Copilot

GitHub / Microsoft — VS Code + Cloud Coding Agent
Runtime execution boundaries and seams
flowchart TD DEV([👤 Developer]) -->|"types in
Copilot Chat
or /prompt"| VSCODE subgraph VSCODE ["💻 VS CODE — Local, Interactive, Synchronous"] direction TB AGM["Agent Mode
single session
sequential only
user present"] AGM -->|"subagent
invocation"| SA1["Subagent A
(builder)
own context
sequential"] SA1 -.->|"result
report back"| AGM AGM -->|"subagent
invocation"| SA2["Subagent B
(validator)
own context
sequential"] SA2 -.->|"result
report back"| AGM SA1 -.-|"❌ HARD SEAM
no peer messaging
no shared state
sequential only"| SA2 end subgraph BKGD ["🌿 BACKGROUND AGENTS — Local, Async, Worktree-isolated"] direction TB BG1["Background Agent 1
auto worktree
own branch
no user present"] BG2["Background Agent 2
auto worktree
own branch
no user present"] BG1 -.-|"❌ HARD SEAM
no agent-to-agent
communication
git merge only"| BG2 BG1 -.-|"⚠️ SOFT SEAM
no context bridge
back to VS Code
session"| AGM end subgraph CLOUD ["☁️ CODING AGENT — Cloud, Async, GitHub Actions"] direction TB GHA["GitHub Actions
runner
isolated env
no user present
no terminal"] CCA["Copilot Coding Agent
reads repo + issue
writes code
runs tests
self-reviews"] GHA --> CCA CCA -->|"self-review
1 pass before
PR open"| CCA end subgraph PR ["📋 PULL REQUEST — Handoff artifact"] PR_NODE["Pull Request
code diff
CI status
review comments
the unit of output"] end VSCODE -->|"developer
commits + pushes"| PR_NODE CLOUD -->|"Copilot opens
PR automatically"| PR_NODE PR_NODE -.-|"❌ HARD SEAM
CI fail has no
native path back
to VS Code session"| VSCODE PR_NODE -.-|"⚠️ SOFT SEAM
@copilot comment
triggers new
Cloud session
(no context from
previous session)"| CLOUD DEV -->|"issue/PR event
triggers async"| CLOUD DEV -->|"⚠️ human must
approve CI run
(GitHub policy)"| HUMAN_CI["⚠ Human CI Gate
required by GitHub
for Copilot PRs"] HUMAN_CI -->|"approved"| CI["CI Pipeline"] CI -->|"✅ pass"| MERGE["Merge"] CI -->|"❌ fail"| PR_NODE OBS(["🔭 Observability Plane
OTel insertion point"]) AGM -->|"session logs
no OTel native"| OBS CCA -->|"Actions logs
no OTel native"| OBS CI -->|"CI results"| OBS style VSCODE fill:#edf2fb,stroke:#2a5fa5,color:#1a1a1a style BKGD fill:#e8eef8,stroke:#2a5fa5,color:#1a1a1a style CLOUD fill:#edf2fb,stroke:#2a5fa5,color:#1a1a1a style PR fill:#eef7f1,stroke:#2d7a4f,color:#1a1a1a style AGM fill:#edf2fb,stroke:#2a5fa5,color:#1a1a1a style SA1 fill:#edf2fb,stroke:#2a5fa5,color:#7a7468 style SA2 fill:#edf2fb,stroke:#2a5fa5,color:#7a7468 style BG1 fill:#e8eef8,stroke:#2a5fa5,color:#7a7468 style BG2 fill:#e8eef8,stroke:#2a5fa5,color:#7a7468 style GHA fill:#edf2fb,stroke:#2a5fa5,color:#1a1a1a style CCA fill:#edf2fb,stroke:#2a5fa5,color:#1a1a1a style PR_NODE fill:#eef7f1,stroke:#2d7a4f,color:#1a1a1a style HUMAN_CI fill:#fdf6e3,stroke:#b08a2e,color:#1a1a1a style CI fill:#eef7f1,stroke:#2d7a4f,color:#1a1a1a style MERGE fill:#eef7f1,stroke:#2d7a4f,color:#1a1a1a style OBS fill:#f3f0fa,stroke:#6450b4,color:#1a1a1a style DEV fill:#f3f0fa,stroke:#6450b4,color:#1a1a1a
Boundary Seam type What crosses What doesn't cross Failure recovery
VS Code agent → subagent ⚠ Soft Prompt, result text Peer messaging (none), parallel execution (none) Orchestrator re-invokes sequentially — no retry memory
VS Code subagent → subagent ❌ Hard Nothing — fully sequential All context, no peer messaging Must route through orchestrator — no direct communication
Background agent → background agent ❌ Hard Git history (shared repo) All context, no peer communication Manual git merge — reasoning lost
VS Code session → background agent ❌ Hard Files on disk, git branch Session context, conversation history No return path — background agent is fire-and-forget
Cloud agent → VS Code ❌ Hard PR diff, CI results, review comments Agent reasoning, tool call trace, session context No native return path — human reads PR, manually continues
CI failure → cloud agent retry ⚠ Soft @copilot comment triggers new session Previous session context (each session starts fresh) New agent session — must re-read PR to understand failure
Human CI approval gate ❌ Hard Human clicks approve Automation cannot bridge this — GitHub policy Cannot be bypassed — breaks fully unattended flows

Sequential subagents — no peer layer

Unlike Claude Code Agent Teams, Copilot subagents in VS Code agent mode cannot communicate with each other. All coordination routes through the orchestrating session. Builder finishes → orchestrator reads result → orchestrator prompts validator. There is no direct builder ↔ validator channel.

Cloud agent context isolation

Each Copilot coding agent session in GitHub Actions starts fresh. When a CI failure triggers a new agent session via @copilot comment, that session has no memory of what the previous session tried, what it thought, or why it made its decisions. It reconstructs from the PR diff and repo state only.

The mandatory human CI gate

GitHub requires a human to approve CI workflow runs on Copilot PRs. This is a deliberate security policy — not a bug — to prevent autonomous agents from running arbitrary code in CI environments. It means fully unattended agent-to-CI-to-merge flows are architecturally impossible in Copilot today.

Observability Plane insertion

Copilot emits session logs (GitHub Actions) but no OTel. The Observability Plane must ingest these logs and correlate them with structured events to reconstruct a trace. Unlike Claude Code, there is no native OTLP endpoint — the insertion requires a webhook or log-scraping adapter at the CI boundary.
Seam Comparison: Claude Code vs Copilot (homogeneous)
Seam category Claude Code GitHub Copilot
Agent-to-agent messaging ✅ SendMessage (Agent Teams) ❌ not available
Shared task state across agents ✅ TaskCreate/Update on disk ❌ not available
Subagent internal trace ❌ result text only ❌ result text only
Parallel agent execution ✅ run_in_background + worktrees ⚠ background agents (no coordination)
Context across worktree boundary ❌ git only ❌ git only
Cloud→local return path on failure ⚠ headless CI → human ❌ cloud agent → human only
Native OTel telemetry ✅ metrics + events (no traces) ❌ session logs only
Mandatory human gate ⚠ permission prompts (configurable) ❌ CI approval required (policy)
Session resumption ✅ /resume across sessions ❌ each cloud session starts fresh