A source-level analysis of Kun Chen's FirstMate

From promptto fleet.

FirstMate is not a smarter chat window. It is an agent distribution that compiles conversation into durable files, isolated work, sparse signals, and a governed delivery path.

Meet the practitioner Compare the methods

8durable transitions

3work unit types

6+verified harnesses

1human-facing liaison

00 / The practitioner

Who is Kun Chen?

Kun Chen is a former L8 engineer at Meta, Microsoft, and Atlassian who now publishes open-source agent tooling and long-form, end-to-end demonstrations of his working environment.

His value here is not celebrity or a claim to the one correct workflow. It is that his ideas are unusually inspectable: the repositories are public, the glue scripts are visible, and the videos show the system doing real work rather than stopping at prompting advice.

GitHub profile ↗YouTube channel ↗

Chen presents FirstMate as the layer joining his individual agent tools into one operating workflow.Workflow video, 42:11 ↗

A systems view

He treats the model as one component inside scheduling, memory, isolation, review, testing, and delivery controls.

Evidence you can inspect

FirstMate, treehouse, No Mistakes, and related utilities turn the thesis into code that can be read, run, challenged, and adapted.

The emerging bottleneck

As models become capable of more work, coordinating parallel workers and preserving trustworthy state matters more than adding another clever prompt.

Concise innovation summary

The filesystem becomes the control plane.

FirstMate compiles conversation into typed local files, gives each agent an isolated worktree and explicit lease, reports only sparse durable events, and hands implementation to fresh review and QA contexts. The innovation is the composition: replaceable agents operate inside traditional engineering controls while one liaison protects the human's attention.

01 / Prompt compiler

What actually happens to a prompt

The key move is externalization. A request stops being transient conversation and becomes a chain of small, typed artifacts. Each file has a narrower job than "remember everything."

intake

Resolve and classify

FirstMate identifies the project, then chooses ship work, a read-only scout, or a persistent secondmate domain.

data/projects.md

memory

Make the request durable

The request becomes a backlog record. Dependencies, delivery posture, holds, and ownership stop living only in chat.

data/backlog.md

contract

Compile a worker contract

A task-specific brief replaces every placeholder with the objective, acceptance criteria, constraints, reporting protocol, and authority boundaries.

data/<task-id>/brief.md

runtime

Lease isolated execution

treehouse or Orca provides a disposable worktree. A selected harness starts with the absolute brief path, never the entire captain conversation.

state/<task-id>.meta

signal

Supervise by events

Workers append sparse phase changes. The watcher turns them into durable wakes; current structured state remains authoritative.

state/<task-id>.status

quality

Gate delivery

The worker or FirstMate invokes the configured delivery path. No Mistakes can rebase, review, test, document, lint, open the PR, and watch CI.

branch -> PR -> CI

learning

Preserve the useful residue

Scout findings land in a report. Project knowledge goes to project instructions. Preferences and operational learning go to their designated durable owners.

data/<task-id>/report.md

safety

Prove it landed, then retire

Teardown refuses to discard unlanded ship work. After proof, it returns the worktree, closes the endpoint, clears volatile state, and keeps the durable record.

fm-teardown.sh

The important distinction

Briefs are contracts. Status files are event logs. Meta files are runtime identity. Backlog is durable work state. FirstMate's design repeatedly prevents one artifact from impersonating another.

02 / Filesystem anatomy

A home designed for replacement, not recollection

firstmate/

├── AGENTS.md tracked operating contract

├── bin/ deterministic lifecycle commands

├── .agents/skills/ pull-based procedures

├── data/ durable private memory

│ ├── backlog.md

│ ├── captain.md

│ ├── learnings.md

│ └── <task-id>/brief.md

├── state/ volatile runtime coordination

│ ├── <task-id>.meta

│ ├── <task-id>.status

│ └── .wake-queue

├── config/ local policy and dispatch profiles

└── projects/ registered working clones

Tracked

Share the operating system

Instructions, scripts, and skills can evolve through ordinary engineering review.

Private + durable

Keep the captain's world on disk

Projects, preferences, backlog, learnings, briefs, and reports survive agent replacement without entering the public repo.

Private + volatile

Separate coordination from knowledge

Endpoints, worktrees, wake events, and holds can be reconciled or retired without erasing the long-term record.

Existing project?

Yes. FirstMate imports by cloning and registering, not rewriting.

Choose a project name, delivery mode, and autonomy posture. FirstMate clones the repository under projects/<name> and adds the registry entry. no-mistakes and direct-PR projects need an origin remote; local-only may have none. Only the no-mistakes mode runs no-mistakes init and no-mistakes doctor.

03 / Context rot

The chat is a cache, not the database

Kun's answer to context rot is not a single summarizer. It is a hierarchy of authoritative external state plus bounded reconstruction.

replaceableAgent context

Conversation, compacted summary, current reasoning

Session startLock, drain wakes, load bounded context and fleet digests

/stowRoute uncaptured knowledge to its durable owner before reset

/bearingsRebuild one deterministic current fleet snapshot on demand

WatcherConvert sparse worker events into a durable wake queue

Bounded startup

A compact listing and short status tails keep stale history from consuming the new context.

Typed ownership

Preferences, project facts, fleet facts, task notes, and investigations have different destinations.

Fresh truth

Bearings reads live structured state. It never treats an old status report or raw event tail as current truth.

Restart as non-event

Live backend inventory and durable files let a new FirstMate reconcile work that already exists.

A productive disagreement

Pocock: clear before sediment

Repeated compact-and-continue cycles can accumulate a distorted working story. Fit tasks into a sharp context, then start fresh.

Chen: compact, but anchor elsewhere

Good server-side compaction extends a live liaison. FirstMate limits the risk because disk state, not the summary, owns fleet truth.

04 / On screen

The workflow in Kun's videos

Each frame links to the cited timestamp. Frames are reproduced for critical commentary and remain the property of their creators.

42:11 ↗

FirstMate as the cohesive layer

Kun presents FirstMate after showing the individual tools. The design claim is integration: one conversational liaison over a fleet.

29:46 ↗

The delivery gate

No Mistakes turns a completed edit into a governed pipeline with review, test evidence, documentation, PR creation, and CI follow-through.

37:31 ↗

Parallel work without folder debt

treehouse leases isolated worktrees, so multiple agents can operate without colliding with the primary checkout.

36:31 ↗

A terminal that exposes the fleet

Herdr adds agent status to the terminal workspace model. Visibility becomes part of orchestration, not a separate dashboard.

49:11 ↗

Compaction is useful, not authoritative

Kun favors OpenAI server-side compaction. FirstMate's disk state means the compacted conversation is a convenience layer, not the fleet database.

11:46 ↗

Small global memory

Only stable, universal behavior belongs in the always-loaded instruction file. Project facts and procedures are routed elsewhere.

14:01 ↗

Shared understanding before the spec

Pocock's grill-me phase forces ambiguity into the open before the plan hardens. The specification records a design, rather than inventing one.

66:01 ↗

Feedback loops set the ceiling

Implementation, review, and human QA are separate loops. Fresh context matters because a tired implementer tends to defend its own work.

05 / The wider stack

FirstMate is the integration advantage

Kun's tools target different bottlenecks. The gain comes from composing them into a path where output from one tool is the contract for the next.

shapememoryisolateorchestrateobserveverifyergonomicsreproduce

orchestrate

FirstMate

Fleet control plane

One liaison decomposes requests, dispatches isolated workers, routes decisions, and keeps accepting work without making the human juggle agent sessions.

Cost and limit

The shell-based runtime and state contracts are substantial infrastructure. It pays off only when parallel work is frequent enough.

isolate

treehouse

Worktree lease manager

Reusable worktree pools make isolation cheap, deterministic, and visible. Busy and idle leases replace hand-named folders and cleanup debt.

Cost and limit

It adds another lifecycle to learn, and repository hygiene still matters.

verify

No Mistakes

Delivery gate

A fresh-context pipeline extracts intent, rebases, reviews, tests, documents, lints, opens the PR, and babysits CI. Its init step configures the local gate; doctor verifies that environment, authentication, and daemon are healthy.

Cost and limit

Evidence is only as good as the acceptance criteria, tests, and risk model. It cannot supply product taste.

shape

Lavish

Interactive planning surface

Turns plans and UX proposals into inspectable HTML with annotations and decision controls. Humans react to a concrete artifact instead of a wall of prose.

Cost and limit

A polished artifact can create false confidence if unresolved assumptions are hidden.

verify

gnhf

Bounded verification loop

Lets an agent keep iterating against a verifiable or trusted objective, with token, iteration, and stop limits.

Cost and limit

The loop can optimize the wrong target if the objective is a weak proxy.

ergonomics

AXI tools

Agent-shaped interfaces

Wrappers such as gh-axi expose compact structured output and next-step help, reducing parsing errors and wasted context compared with human-oriented CLIs.

Cost and limit

They create an opinionated compatibility layer that must track upstream tools.

observe

Herdr

Agent-native terminal

Surfaces harness status across workspaces, tabs, and panes. It makes a parallel fleet legible and is designed for cross-platform use.

Cost and limit

FirstMate still treats tmux as the reference backend; alternative backends carry more integration risk.

observe

tmux + WezTerm

Reference runtime and terminal

Durable sessions, keyboard-driven panes, and mature automation give FirstMate a dependable endpoint model.

Cost and limit

Status is less agent-aware than Herdr and session choreography is still visible plumbing.

ergonomics

Neovim + Neogit

Fast code and Git inspection

Keeps review, navigation, and repository state close to the keyboard. It makes the captain's beginning-and-end interventions fast.

Cost and limit

The advantage depends on deep editor fluency.

shape

OpenSuperWhisper

High-bandwidth prompt input

Voice makes it cheap to dump product context, corrections, and follow-up thoughts while FirstMate queues and routes them.

Cost and limit

Faster input increases the need for classification, deduplication, and good briefs.

memory

npx skills

Pull-based procedures

Loads specialized instructions only when needed, keeping the always-on system prompt small.

Cost and limit

Too many overlapping skills can confuse routing and degrade model performance.

reproduce

Nix + dotfiles

Reproducible environment

nix-darwin, home-manager, and centralized dotfiles make the whole agent workstation rebuildable instead of hand-configured.

Cost and limit

The learning curve and configuration surface are significant.

06 / Chen × Pocock

Traditional engineering, applied at two levels

Both reject the idea that more autonomous chat is enough. Pocock concentrates on shaping work and code. Chen adds the runtime that keeps many shaped units moving. Read the companion guide to Pocock's current workflow and Wayfinder ↗ See how Mycelium adds executable application contracts between planning and dispatch ↗

Where does intent become concrete?

Research, prototype, then grill the human until there is shared understanding. Write a PRD only after the design is real.

FirstMate classifies a live request, records it in the backlog, and compiles a task brief with acceptance and authority rules.

Matt shapes the work unit. Kun operationalizes it.

How is context kept sharp?

Tiny system prompts, pull-based skills, fresh contexts per issue, and tasks sized to fit the model's smart zone.

Tiny global memory plus bounded startup digests, authoritative disk state, sparse events, stow, bearings, and server-side compaction.

Both distrust conversation as the sole memory. Matt resets aggressively; Kun also makes restarts routine.

How is work decomposed?

Vertical tracer-bullet issues with explicit dependencies and a durable issue tracker.

Ship, scout, and secondmate units, parallel by default unless there is a real semantic dependency.

Matt emphasizes product slices. Kun adds runtime topology and routing.

How is implementation controlled?

Fresh worktree, TDD, red-green-refactor, then a fresh reviewer context.

Isolated leased worktree, selected harness/model, sparse steering, then a configurable delivery gate.

The same engineering instinct appears at different layers.

Where does the human belong?

Humans must read, test, and impose taste. The code remains the battleground.

Human attention concentrates at requirements and final risk or quality decisions; routine middle work is delegated.

Kun optimizes attention allocation. Matt more strongly warns against losing code-level understanding.

What is the architecture lesson?

Deep modules, small interfaces, strong feedback loops, and codebases that are easy for both people and agents to navigate.

A control plane with explicit state ownership, fail-closed guards, replaceable harnesses, and restart-proof supervision.

Matt designs the factory floor. Kun designs factory operations.

POCOCKwell-shaped work units

CHENrestart-proof fleet operations

COMBINEDan engineering system for LLM labor

07 / Critical verdict

A serious operating system, with operating-system costs

What is unusually strong

Conversation is compiled into narrow, inspectable artifacts.
Restarts and compaction do not own fleet truth.
Isolation is mandatory and teardown fails closed.
Human decisions have an explicit hold and reply path.
Harness, model, terminal backend, and delivery mode are replaceable axes.
Scout reports preserve research without pretending it is code.

What can still go wrong

A poor brief merely distributes misunderstanding faster.
The Bash and file-state surface creates its own maintenance burden.
Automation can distance the captain from code-level reality.
Parallelism increases review load, integration risk, and credential exposure.
Tests and generated evidence can validate the wrong product behavior.
The FirstMate liaison remains a central reasoning and routing bottleneck.

The deepest idea is not "use more agents." It is to give probabilistic workers the same things good engineering teams need: bounded briefs, isolated workspaces, explicit state, feedback loops, independent review, and clear authority.

08 / Adoption ladder

Do not start with the fleet

1
Make one agent reliable
Small AGENTS.md, strong tests, lint, type checks, and a repeatable manual QA path.
2
Externalize the work
Use issue-sized briefs, fresh contexts, isolated worktrees, and explicit acceptance evidence.
3
Separate creation from judgment
Add fresh-context review, interactive planning, and a delivery gate such as No Mistakes.
4
Only then add orchestration
Adopt FirstMate when session juggling and state recovery are the real bottlenecks.