Architecture

Pilot’s context intelligence layer provides context engineering — structured loading, persistent memory, and workflow enforcement. This page explains the architecture and integration mechanics.

Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                      Pilot Process                          │
│                                                             │
│  ┌──────────┐    ┌──────────────┐    ┌──────────────────┐  │
│  │ Executor │───▶│  Claude Code  │───▶│  Context Engine   │  │
│  │runner.go │    │  subprocess   │    │  (auto-detected)  │  │
│  └──────────┘    └──────────────┘    └────────┬─────────┘  │
│                                               │             │
│                                               ▼             │
│                        ┌──────────────────────────────┐     │
│                        │       .agent/ Directory       │     │
│                        │                              │     │
│                        │  DEVELOPMENT-README.md       │     │
│                        │  system/ARCHITECTURE.md      │     │
│                        │  system/FEATURE-MATRIX.md    │     │
│                        │  tasks/*.md                  │     │
│                        │  memories/*.md               │     │
│                        │  sops/*.md                   │     │
│                        │  .context-markers/*.md       │     │
│                        │  .nav-config.json            │     │
│                        │  .user-profile.json          │     │
│                        └──────────────────────────────┘     │
└─────────────────────────────────────────────────────────────┘

Integration Flow

When Pilot picks up a task (from GitHub, Telegram, or CLI), execution follows this path:

1. Detection

Pilot’s executor checks for context intelligence during prompt construction:

// internal/executor/runner.go — BuildPrompt()
agentDir := filepath.Join(task.ProjectPath, ".agent")
if _, err := os.Stat(agentDir); err == nil {
    sb.WriteString("Start my Navigator session.\n\n")
}

If .agent/ exists, the prompt is prefixed with the context initialization command. This activates the context engine inside the execution backend.

2. Session Initialization

The context engine performs these steps on activation:

1. Load index — Reads DEVELOPMENT-README.md (~2k tokens)
2. Check context markers — Looks for active markers in .context-markers/
3. Load knowledge graph — Surfaces relevant memories for the current task
4. Load user profile — Applies preferences from .user-profile.json
5. Run workflow check — Determines execution mode (loop/task/direct)

3. Lazy Loading

The context engine never loads all documentation at once. Instead, it uses a demand-driven strategy:

Session Start
    │
    ▼
Load Index (~2k tokens)
    │
    ├─── Task references architecture? ──▶ Load ARCHITECTURE.md (~5k)
    │
    ├─── Task involves specific feature? ──▶ Load relevant task doc (~3k)
    │
    ├─── Task touches integration? ──▶ Load relevant SOP (~2k)
    │
    └─── Otherwise ──▶ Proceed with index only

Token budget per session:

4. Execution Phases

The context engine structures work into observable phases that Pilot tracks for progress display:

Pilot detects these signals from the execution backend’s stream-json output and updates the progress bar in real time.

5. Knowledge Capture

During execution, the context engine automatically captures:

• Technical decisions — Extracted from conversation and stored as decision memories
• Task artifacts — Implementation plans, file change lists, test results
• Concept indexing — Creates nodes in the knowledge graph linking tasks, files, and patterns

After task completion, new knowledge syncs to .agent/memories/.

6. Session Markers

At key points during execution, context markers are created — save points in .agent/.context-markers/ that capture:

• Current task state
• Decisions made so far
• Files modified
• Outstanding work items

These markers enable:

• Resume after break — Pick up exactly where you left off
• Context compaction — Clear conversation memory while preserving knowledge
• Cross-session continuity — New sessions read markers to understand prior work

Knowledge Graph

The knowledge graph is a persistent store that survives across sessions and tasks.

Node Types

How It’s Used

When a new task starts, the context engine queries the graph for:

• Related decisions — What was decided previously about this area?
• Known pitfalls — What went wrong last time?
• Relevant patterns — What approaches worked before?

This eliminates repeated discovery and prevents known mistakes.

Workflow Enforcement

The context engine enforces a mandatory workflow check before every task:

WORKFLOW CHECK
Loop trigger: YES
Complexity: 0.7
Mode: LOOP

Execution Modes

Progress Detection in Pilot

Pilot’s executor parses context engine signals from the execution stream:

// internal/executor/runner.go — phase detection
switch {
case strings.Contains(text, "Navigator Session Started"):
    phase = "navigator"
case strings.Contains(text, "TASK MODE ACTIVATED"):
    phase = "task-mode"
case strings.Contains(text, "PHASE: → RESEARCH"):
    phase = "research"
case strings.Contains(text, "PHASE: → IMPL"):
    phase = "implementing"
case strings.Contains(text, "PHASE: → VERIFY"):
    phase = "verifying"
}

This gives operators real-time visibility into what the context engine is doing inside the execution subprocess.

Claude Code Integration

Context intelligence works alongside Pilot’s Claude Code integration features to provide enhanced execution capabilities.

Session Resume

When use_session_resume is enabled, sessions can be resumed after context compaction or across execution phases. This enables:

• Self-review token savings — Self-review reuses the execution context (~40% savings)
• Cross-phase continuity — Context markers combined with session resume preserve knowledge
• PR fix continuation — CI fix tasks resume with full context via --from-pr

Hooks System

Claude Code hooks run quality checks during execution:

• Stop hook — Runs build and tests before completion (exit 2 = keep fixing)
• PreToolUse:Bash — Blocks destructive commands (rm -rf, force push, DROP TABLE)
• PostToolUse:Edit/Write — Auto-lint after file changes

Hooks complement the context engine’s workflow enforcement by adding runtime guardrails.

Structured Output

With use_structured_output enabled, classifiers use JSON schemas instead of text parsing for:

• Complexity classification (TRIVIAL/SIMPLE/MEDIUM/COMPLEX)
• Effort routing decisions
• Post-execution summary extraction