The Experiment Evolves

The project evolves from an MCP-centred experiment into a persistent, observable, and explicitly supervised runtime for multi-step software-engineering work.

Agent Orchestrator

The most important change in the project is not the addition of another model, tool, or user interface. It is a change in architectural responsibility.
What began as an exploration of how agents and Model Context Protocol tools can cooperate evolves towards a supervised orchestration runtime. The current system no longer treats a model response as the workflow. Instead, it treats model calls as one part of a durable process that has an identity, an explicit plan, dependency-aware tasks, policy-controlled actions, recovery stages, operator handoffs, and observable results.

The original question:

How can an AI client discover and invoke useful capabilities through a standard protocol?

The current project addresses a broader and more difficult question:

How can a multi-step software-engineering run remain controlled, recoverable, auditable, and understandable when models, tools, dependencies, and human decisions are all involved?

That shift changes the role of the MCP server. It is no longer merely a thin tool adapter. It has become the boundary of a long-running workflow.

flowchart TD
    A["MCP experiment
Expose capabilities"] --> B["Agent bridge
Delegate model work"]
    B --> C["Workflow coordinator
Plan and sequence tasks"]
    C --> D["Supervised runtime
Persist, observe, recover"]
    D --> E["Engineering platform
Benchmark and improve"]

    style A fill:#e0f2fe,stroke:#0284c7,color:#111827
    style B fill:#dbeafe,stroke:#2563eb,color:#111827
    style C fill:#dcfce7,stroke:#16a34a,color:#111827
    style D fill:#fef3c7,stroke:#d97706,color:#111827
    style E fill:#f3e8ff,stroke:#7c3aed,color:#111827
  

This progression explains many of the design choices in the current codebase. Session identity, manifests, the blackboard, dashboard events, approval gates, circuit-breaker stages, and delegated execution are not isolated additions. Together, they transform an interaction into an operational process.

From a request-response tool to a durable run

A conventional MCP tool call has a short lifecycle: the client sends arguments and receives a result. That works well for bounded operations, but it is insufficient for work that may require classification, planning, parallel tasks, retries, clarification, file changes, commands, and review.

The current orchestrator introduces an opaque session_id as the stable external identity of a run. Internal bundles may change when the system replans, but the caller continues to address the same session. This is a subtle but important maturation: the public identity represents the user’s objective, not a particular implementation of the plan.

  sequenceDiagram
    autonumber
    participant C as IDE or MCP client
    participant S as MCP server
    participant R as Run registry
    participant O as Orchestrator
    participant M as Model provider

    C->>S: run_intake(problem, tools, workspace)
    S->>R: Create stable session_id
    S->>O: Classify and construct manifest
    O-->>S: Plan and analysis
    S-->>C: session_id and prepared run

    loop Until terminal state
        O->>M: Execute bounded model task
        M-->>O: Result or requested action
        O-->>C: Action, clarification, or progress event
        C->>O: Tool result, answer, or guidance
        O->>R: Persist state and evidence
    end

    O-->>C: completed, failed, or aborted
  

Asynchronous execution follows naturally from this design. The caller can start a run, await the next meaningful event, submit a result or clarification, and continue without keeping a single synchronous invocation open for the duration of the workflow.

From an implicit prompt plan to an executable manifest

Earlier agent experiments often embedded planning inside a prompt. The model was asked to reason about the work and then perform it. The current project state separates those concerns.

Planning now produces a validated manifest containing tasks, dependencies, assigned and fallback models, dispatch settings, and completion gates. The plan is data, not hidden reasoning. That makes it inspectable, testable, and suitable for approval before execution begins.

flowchart TD
    I([Intake])
  
    I --> Plan
  
    subgraph Plan[Planning]
        C[Classify]
           
    end
  
    C --> M
    M[Manifest]
  
    subgraph Exec[Execution]
        E[Run]
        G{Gate}
        N[Next Tasks]
        R{{⚙️Recover}}
    end

    M --> A{Approval}
    A -->|✅| E
    A -->|⛔| Plan

    E --> G
    G -->|✅| N
    G -->|👎🏼| R
    R --> E

    N:::ok
    R:::warn

    classDef ok fill:#dcfce7,stroke:#15803d;
    classDef warn fill:#fee2e2,stroke:#dc2626;
    classDef entry fill:#dbeafe,stroke:#1d4ed8,stroke-width:2px;
    classDef recovery fill:#fee2e2,stroke:#dc2626,stroke-width:2px;
  
    class I entry;
    class R recovery;
  

Completion gates are particularly significant. A task is not complete merely because a model says it is complete. The task can require an artifact, repository discovery, a delegated command, an expected outcome, or a known failure signature. This shifts success from conversational confidence toward evidence.

From autonomous tool use to explicit delegated action

The orchestrator deliberately does not become an unrestricted shell operator. File and command actions are requested through explicit handoffs and executed by the calling IDE agent.

This creates a clear trust boundary. This is more than a security measure. It also makes the protocol useful across different IDEs and execution environments. The orchestrator stays focused on coordination, while the caller remains responsible for local effects:

• The orchestrator decides what action is needed.
• The action policy validates whether the request is allowed.
• The caller performs the operation in its own environment and permission context.
• The result is returned to the run and recorded as evidence.

From transient context to shared operational memory

Long-running, multi-agent work needs more than chat history. The project now combines several forms of persisted evidence:

• manifests describing intended work
• status snapshots describing current state
• logs and events
• task result artifacts
• model history and performance data
• shared board.mdblackboard

flowchart TB
    T1["Task worker A"] --> S["Single state manager"]
    T2["Task worker B"] --> S
    T3["Task worker C"] --> S

    S --> B["board.md
shared findings and decisions"]
    S --> J["status.json
current public state"]
    S --> L["logs and workflow events"]
    S --> R["task results and artifacts"]

    B --> D["Dashboard and replanning context"]
    J --> D
    L --> D
    R --> D

    style S fill:#dcfce7,stroke:#15803d,color:#111827
    style B fill:#fef3c7,stroke:#d97706,color:#111827
    style D fill:#f3e8ff,stroke:#7c3aed,color:#111827

  

The blackboard gives workers a common, durable summary of findings and decisions without allowing every task to invent its own competing memory format. The single-scribe approach in the state-management layer is an important safeguard against inconsistent parallel updates.

This also enables replanning without losing the story of the run. A classification correction or newly reported finding can generate a new internal bundle while retaining the public session identity and prior evidence.

This is the project’s central evolution: orchestration is no longer concentrated in one large “agent” abstraction. Responsibility is distributed across explicit planes with focused modules and contracts.

S.H.O.D.A.N is a now supervised, asynchronous workflow runtime that uses MCP as its interaction boundary, configurable models as reasoning workers, the calling IDE as its controlled execution environment, and persisted run artifacts as operational evidence.

This arcticle and the illustrations were created using AI tools and agents.