agent-workflows

Projektor is MCP-native: AI agents are a first-class client, not an afterthought. Everything a browser user can do, an agent can do over a JSON-RPC MCP endpoint.

Tools for agentic development split into three concerns: running the agents, coordinating them, and tracking the work. The mistake is to treat each concern as its own product. They are not products — they are concerns, and the real product boundary is the API. With MCP as the shared interface, one tool can cut a vertical slice through several concerns and stay coherent, because the interface stays coherent. That is what Projektor is: not one layer, but a slice across two of the three.

Layer	Runs where	What it does	Reference
1 · Lifecycle (implementation)	The client machine	Spawns an isolated workspace per agent (git worktree + branch + terminal), and reaps it cleanly when done	This page (§1)
2 · Coordination	Projektor MCP	Lets parallel agents announce themselves, claim files, and message each other so they don't clobber each other's work	Contributor conventions (Fleet coordination protocol)
3 · Project management	Projektor MCP	The actual work: issues, sprints, wiki, links — and "what should I work on next?"	MCP tool catalog, Connect an agent

Projektor is a single MCP surface spanning layers 2 and 3. Through file claims it also reaches into layer 1 — deciding who may write which file. It owns the nodes of the work state machine; the implementation layer owns the transitions. Projektor never runs a test or judges a diff; it records the outcome. You can use any layer alone — a single agent needs only layer 3 — but the power comes from combining them.

flowchart TB
    human(["Human / lead agent — intent, priorities, final review"])

    subgraph L3["3 · Project management — source of truth"]
        graph3["Issue / epic / sprint graph = shared memory"]
        prio["Prioritise & decompose (machine-readable)"]
        state["State-machine NODES — records verification outcome"]
    end

    subgraph L2["2 · Coordination — communication"]
        prim["Agent-native primitives: file claims · registry · heartbeat"]
        evt["Comments · status · messages = event log / bus"]
        ctx["Context fetch · skills · repo memory"]
    end

    subgraph L1["1 · Lifecycle — runtime"]
        spawn["Spawn · worktrees · job objects"]
        route["Routing: which agent/model handles what"]
        cond["Conditioning: prompt / context optimisation"]
        verify{{"Transitions: tests + human review"}}
    end

    projektor["Projektor — one MCP surface, vertical slice"]
    projektor -.-> graph3
    projektor -.-> prim
    projektor -.-> state

    human --> prio --> graph3 --> prim
    prim <--> evt
    evt --> ctx --> spawn
    spawn --> route --> cond --> verify
    verify -->|pass / fail| state
    state -->|feedback / replan| human

---

1 · Lifecycle: one isolated workspace per agent

Before an agent can coordinate, something has to start it in a place where it can work without stepping on other agents or your main checkout. The durable pattern:

• One git worktree per agent. Each agent gets its own worktree (e.g. <repo>.wt/<name>) on its own branch (wt/<name>). Worktrees beat branch-switching for parallel AI work: every agent edits a physically separate file tree, so there is no "whose turn is it to hold the working directory" contention.
• One terminal/tab per agent, launched into that worktree. On Windows, wrapping the agent's process tree in a Job Object means closing the tab reaps the whole dev-stack subtree — no orphaned node/workerd processes holding file locks.
• Cleanup is close-then-remove, in that order. The naive approach (delete all the worktree directories, then close the tabs) fails on Windows because the OS re-acquires directory handles between the two phases. Closing the tab first releases the locks, so removing the directory always succeeds. Finish with git worktree prune.