🏗️ Deterministic Workflows with Archon

Archon is the “harness builder” created by Cole Medin. It lets you build workflows that orchestrate multiple coding agent sessions for larger tasks. The fundamental difference from a pure loop: you define the process, not the agent. In a pure loop, the agent decides how to make progress. In Archon, you define the steps, and the agent executes within each one.

Cole Medin explains the direct motivation: "O Archon é meu criador de harness; ele nos permite criar fluxos de trabalho que orquestram várias sessões de agentes de programação para lidar com tarefas maiores." The idea is that a workflow like "fix GitHub issue" doesn’t need an agent deciding how to solve it. The process is known: extract context, classify, research, implement, validate, create a PR.

Archon's most classic workflow is "Fix GitHub Issue." Cole Medin uses this day to day: "Most of the input for my day-to-day work is issues in a repo. Either I'll create them or someone else will." The workflow follows a fixed sequence of steps, each with a specific role.

The key point: "We're not having the agent drive the entire thing. It's more deterministic because we set up the process in this workflow file." You define the steps, Archon ensures they run in the right order, and each step runs in an isolated session with the ideal model for that task.

The fundamental principle of Archon is counterintuitive: the fewer decisions the agent makes, the better the result. Cole Medin makes this explicit: "We want to actually take the decision away from the coding agent as much as we can, only applying the reasoning of the LLM when we actually need it to write the code."

// Step deterministico: nao precisa de LLM
async function extractIssueNumber(input: string): Promise<number> {
  const match = input.match(/issues\/(\d+)/);
  if (!match) throw new Error("Invalid issue URL");
  return parseInt(match[1], 10);
}

// Step deterministico: API call pura
async function fetchIssueContext(owner: string, repo: string, num: number) {
  const res = await fetch(
    `https://api.github.com/repos/${owner}/${repo}/issues/${num}`,
    { headers: { Authorization: `token ${process.env.GITHUB_TOKEN}` } }
  );
  return res.json();
}

// Step LLM: aqui sim o agente precisa raciocinar
async function classifyIssue(context: IssueContext): Promise<"bug" | "feature"> {
  // Roda num modelo barato (Haiku, Kimi K2.7)
  const response = await llm.complete({
    model: "haiku",
    prompt: `Classify this GitHub issue as "bug" or "feature":\n${context.title}\n${context.body}`
  });
  return response.trim() as "bug" | "feature";
}

One of the biggest problems with a pure loop using /loop or /routines: "You're just using one model for pretty much everything. That's part of the problem of why it's so expensive." In Archon, each workflow node can use a different model, optimizing cost without sacrificing quality.

Cole Medin demonstrates this in practice: "We can use Cloud Code for the implementation. And then we can use Codex for the review. And then for all of our context loading and exploration up front, we can use a smaller model like Kimi K 2.7." This is model routing applied to agent workflows.

One of the biggest weaknesses of the basic loop: if the terminal closes, you lose everything. Archon solves this by storing all the state in an external database. "Estou armazenando aqui todos os loops que executamos, os diferentes eventos e logs, para que possamos sempre retomar um fluxo de trabalho mais tarde."

-- Cada run tem um ID e estado persistente
CREATE TABLE workflow_runs (
  id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  workflow_id TEXT NOT NULL,
  status      TEXT DEFAULT 'running', -- running | paused | completed | failed
  input       JSONB NOT NULL,
  state       JSONB DEFAULT '{}',
  created_at  TIMESTAMPTZ DEFAULT now(),
  updated_at  TIMESTAMPTZ DEFAULT now()
);

-- Cada step registra sua execucao
CREATE TABLE step_executions (
  id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  run_id      UUID REFERENCES workflow_runs(id),
  step_name   TEXT NOT NULL,
  status      TEXT DEFAULT 'pending', -- pending | running | completed | failed
  input       JSONB,
  output      JSONB,
  model_used  TEXT,
  tokens_used INTEGER DEFAULT 0,
  started_at  TIMESTAMPTZ,
  finished_at TIMESTAMPTZ
);

-- Logs de conversacao para replay
CREATE TABLE conversation_logs (
  id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  run_id      UUID REFERENCES workflow_runs(id),
  step_name   TEXT NOT NULL,
  role        TEXT NOT NULL, -- system | user | assistant
  content     TEXT NOT NULL,
  created_at  TIMESTAMPTZ DEFAULT now()
);

Cole Medin emphasizes: "Todas as minhas conversas e bases de código em que trabalho com o Archon ficam salvas, e é muito fácil retomar qualquer trabalho que eu esteja fazendo." With the state in a Postgres database (Neon), you can resume workflows after a crash, view the complete history of each run, and audit agent decisions.

Archon solves many problems of a pure loop, but introduces its own complexity. It’s worth being honest about the trade-offs.