Jonas Notes

Pathfinder Orchestration Architecture

6 min read

Pathfinder Orchestration Architecture

Purpose

This note describes the current architecture for how Pathfinder operates as an orchestrator-first assistant, while Cursor-backed workers handle heavier implementation and longer-running technical execution.

The design goal is simple:

  • keep the main conversation lean
  • preserve clarity of decisions and intent
  • offload deep implementation work into isolated workers
  • retain a clean control plane for review, iteration, and follow-up

High-Level Model

flowchart TD
    U[Jonas] --> M[Main Chat / Pathfinder]
    M --> O[Orchestration Layer]
    O --> D[Clarify requirements]
    O --> P[Package work]
    O --> R[Review outputs]
    O --> N[Decide next step]

    P --> A[ACP helper / manager]
    P --> C[Cursor workers]
    P --> S[Subagents / isolated sessions]

    A --> W[Implementation execution]
    C --> W
    S --> W

    W --> X[Code changes / analysis / logs / artifacts]
    X --> R
    R --> U

Interpretation

  • Jonas interacts primarily with Pathfinder in the main chat.
  • The main chat is the control plane for intent, strategy, and review.
  • Heavy execution gets pushed into workers rather than bloating the main conversation.
  • Results come back to Pathfinder for validation, summarization, and steering.

Core Architectural Principle

flowchart LR
    A[Main chat] -->|focus on| B[Strategy + decisions + review]
    C[Workers] -->|focus on| D[Implementation + debugging + deep analysis]
    B --> E[Low token burn]
    D --> F[High execution bandwidth]

The architecture deliberately separates:

  • thinking with the human from
  • doing work in execution contexts

That prevents the main chat from becoming a noisy transcript of every technical detail.

Roles and Responsibilities

1. Pathfinder (main session)

Pathfinder should primarily act as:

  • orchestrator
  • reviewer
  • requirements shaper
  • decision-support layer
  • progress summarizer

Pathfinder should not be the default place where all implementation happens.

2. Cursor-backed workers

Workers are the execution engine for:

  • code changes
  • repo analysis
  • debugging loops
  • protocol spelunking
  • long-running implementation tasks
  • isolated experiments

3. ACP layer

The ACP layer provides a reusable way to drive worker execution more systematically.

Known current components:

  • acp/client.js
  • acp/run.js
  • acp/README.md
  • acp-manager/ for the minimal manager implementation

Logical Component Diagram

graph TD
    U[Jonas]
    P[Pathfinder Main Session]
    OC[OpenClaw Runtime]
    ACP[ACP Helper]
    MGR[ACP Manager]
    CW[Cursor Worker Sessions]
    FS[Workspace / Repos / Files]
    OUT[Summaries / Reviews / Decisions]

    U --> P
    P --> OC
    OC --> ACP
    OC --> CW
    ACP --> MGR
    MGR --> CW
    CW --> FS
    FS --> CW
    CW --> OUT
    OUT --> P
    P --> U

Control Flow

Standard execution path

sequenceDiagram
    participant J as Jonas
    participant P as Pathfinder
    participant W as Worker / Cursor / ACP
    participant F as Repo / Files

    J->>P: Describe goal or problem
    P->>P: Clarify intent and shape task
    P->>W: Delegate packaged work
    W->>F: Analyze / edit / run / inspect
    F-->>W: Files, results, logs, diffs
    W-->>P: Outcome summary + artifacts
    P->>P: Review correctness and intent match
    P-->>J: Concise summary, findings, next decision

Why this flow exists

This structure optimizes for:

  • cleaner human interaction
  • lower token burn in the main chat
  • better separation of strategy vs execution
  • easier iteration when work needs multiple passes

Main Chat vs Worker Boundary

flowchart TB
    subgraph Main_Chat[Main Chat / Pathfinder]
        MC1[Clarify requirements]
        MC2[Decide architecture]
        MC3[Choose next action]
        MC4[Review worker outputs]
        MC5[Summarize deltas]
    end

    subgraph Workers[Workers / ACP / Cursor]
        WK1[Inspect repository]
        WK2[Write or modify code]
        WK3[Run commands/tests]
        WK4[Debug failures]
        WK5[Generate implementation artifacts]
    end

Rule of thumb

Keep in the main chat:

  • problem framing
  • design choices
  • review conclusions
  • user-facing summaries

Push into workers:

  • repeated tool use
  • large codebase reading
  • deep debugging
  • mechanical edits
  • iterative implementation loops

ACP-Centric Execution Path

flowchart TD
    T[Task defined in main chat] --> H[ACP helper]
    H --> G[ACP protocol/session management]
    G --> M[ACP manager]
    M --> J[Job state / queue / callbacks]
    J --> W[Cursor-backed execution worker]
    W --> R[Result payload]
    R --> P[Pathfinder review]

Current status

  • ACP is working end-to-end.
  • Basic flows such as initialize, authenticate, session creation, prompting, and streamed updates have been validated.
  • A minimal manager exists as a first usable orchestration layer.

Decision Pipeline

flowchart LR
    A[User intent] --> B[Requirement shaping]
    B --> C[Delegation decision]
    C --> D[Worker execution]
    D --> E[Review and validation]
    E --> F[Decision / merge / iterate / stop]

This is the practical loop Pathfinder should keep enforcing.

Design Goals

1. Token efficiency

The main chat should not be the storage location for every log line, trace, or debugging branch.

2. Better parallelism

Distinct threads of work can be split into:

  • isolated sessions
  • subagents
  • Cursor/ACP workers

This allows multiple streams to move without collapsing into one giant conversation.

3. Stronger review discipline

Pathfinder remains responsible for:

  • checking whether implementation matches intent
  • spotting gaps or regressions
  • deciding when to iterate again
  • translating raw execution into useful human summaries

4. Clear control plane

The human should be able to think at the architecture/decision layer without drowning in implementation detail.

Tradeoffs

flowchart TD
    A[Benefits] --> A1[Cleaner main thread]
    A --> A2[More scalable execution]
    A --> A3[Better specialization]
    A --> A4[Higher parallel throughput]

    B[Costs] --> B1[More coordination overhead]
    B --> B2[Need clear task packaging]
    B --> B3[Review discipline becomes critical]
    B --> B4[Execution context can drift if poorly scoped]

Main tradeoff

This architecture is better than a single monolithic assistant loop only if orchestration quality stays high.

If delegation is vague, workers can drift. If review is weak, mistakes propagate. If summaries are poor, the human loses situational awareness.

So the system depends on Pathfinder being good at:

  • scoping
  • delegation
  • synthesis
  • review

Current Operating Rules

Default behavior

  • Pathfinder is orchestrator-first.
  • Cursor-backed workers are the implementation backend.
  • Main chat stays focused on:
    • strategy
    • clarifications
    • decisions
    • review summaries
  • Long technical work should produce delta-only updates where possible.

Practical policy

When a task becomes:

  • repetitive
  • implementation-heavy
  • log-heavy
  • repo-heavy
  • or likely to take multiple iterative passes

…it should usually move into a worker context.

Example Operating Pattern

flowchart TD
    A[Jonas asks for feature/debug task] --> B[Pathfinder clarifies requirements]
    B --> C[Task packaged for worker]
    C --> D[Worker inspects codebase]
    D --> E[Worker implements or investigates]
    E --> F[Worker returns diff/findings]
    F --> G[Pathfinder reviews]
    G --> H{Good enough?}
    H -->|Yes| I[Summarize and close]
    H -->|No| J[Refine task and re-delegate]
    J --> D

Where This Is Headed

The likely steady-state architecture is:

  1. Pathfinder as control/orchestration interface
  2. ACP as the preferred structured execution path
  3. Cursor workers as the practical implementation substrate
  4. Main chat as decision log + review layer

Cursor CLI remains useful as a fallback, but the more durable direction is ACP-based orchestration.

One-Paragraph Summary

Pathfinder is evolving into an orchestration-first assistant architecture: the main session stays focused on intent, strategy, and review, while Cursor-backed workers and ACP-driven execution contexts handle implementation, debugging, and deeper technical work. The key design objective is to preserve clarity and token efficiency without losing execution power, using Pathfinder as the control plane and workers as the execution plane.

Backlinks