The cairn-method

The cairn-method is a working discipline, not a feature. cairn gives an agent a durable place to keep work; the cairn-method is how an agent uses that place so a fresh session can pick the work back up. It is a loop with four phases: research, plan, implement, validate. Two heartbeat writes hold the phases together — observe and handoff — and one orienting read, task_bootstrap, re-enters the loop after a reset. The method ships as a skill (cairn-method) and six bundled prompts, so the agent reading this page can load the same discipline that authored it.

Why a method and not just tools

A model can call the fourteen tools without any method and get nothing durable. The graph fills with tasks that have no observations, plans whose phases never settle, handoffs that summarize nothing a next session can act on. The tools are necessary but insufficient on their own. What makes the work resumable is the order the agent writes in — what it records, when, and against which task.

The cairn-method names that order. It says: orient before writing, record findings as they surface, structure the plan as a graph the frontier can read, advance only on a real gate, and leave a summary the next session reads first. Each rule maps onto a tool or a query that already exists. The method is the contract between the agent and its future self.

The loop

The method runs as a loop across sessions, not a script inside one. A session enters by orienting, does one kind of work, and leaves a trail. The next session — the same agent after a context reset, or a different one — enters the same way and continues. This section is the cross-session heartbeat — orient, record, hand off; the four work phases (next section) run inside it.

Orient. A session begins with task_bootstrap. One call returns the task's state, its neighbors, any open handoffs, and the recent observations. An explicit task_id switches the current-task pointer to that task; with no task_id, it orients on the current task and adopts it only when one is not yet set. Called with neither a task_id nor a current task, it returns No task to bootstrap; pass task_id or select a task first. task_bootstrap records no event, so re-entering costs nothing — the call repeats freely whenever the thread is lost.

Record. Throughout the work, observe is the heartbeat — the cheapest write cairn has. It appends one freeform observation to the current task and returns Observed on <task>. It does not move the pointer and it does not need a status change to justify it. The cairn-method favors liberal observation over a mandated cadence: a research finding, a red-then-green test, a constraint hit, a decision made. These observations are what task_search later retrieves, so a finding written once need never be re-derived.

Hand off. When the work spans sessions, handoff scaffolds a resumable note. The one-line summary comes first and is the load-bearing field a resuming session reads before anything else; the tool returns Handoff scaffolded for <task> at <path> and writes a skeleton, which a rich body then overwrites. The summary is the contract; the file supplements the live timeline and observations, and never contradicts them. When the two disagree, the live stream wins.

This loop is recursive: the page you are reading was produced by an agent running it — see What cairn is for that story in full.

The four phases

Inside the loop, the work itself moves through four phases. Each ships as a prompt — research, plan, implement, validate — and each leans on the cairn-method skill for the discipline rather than restating it. Two more prompts, handoff and resume, wrap the loop's heartbeat and re-entry. Six prompts in total.

Research documents what is. Before anything changes, research documents the codebase as it stands — findings, not prescriptions. Every claim carries a file:line or a source URL; hypotheses stay phrased as hypotheses until a root cause is reproduced. The method requires a current task before any current-scoped write, because observe and the knowledge query both resolve against it, and every finding then sinks through observe. It also expects a task_search before re-investigation, since the answer may already be in the graph.

Plan structures the work as a graph. A plan in cairn is a task DAG, not a markdown file — the graph is the source of truth. Phases are child tasks created with task_fork (default edge phase-of); real prerequisite ordering is a depends-on edge added with task_link. Because task_fork makes the new child current unconditionally, the method always names the parent with from=<parent>. Each phase carries its own acceptance and is independently verifiable. There is no scaffold tool; the edges are built with the tools above.

Implement advances on real gates. Work moves through the DAG one ready phase at a time, asking (query "plan-frontier") for the next phase whose every depends-on predecessor is settled. A phase can be advanced without moving the pointer: passing task_id=<phase> to observe and task_update_status targets it while the plan stays current. The gate is irreducible — no phase reaches completed until its build, tests, and typecheck actually pass. The passing output advances the DAG, not vibes.

Validate is independent and skeptical. A separate pass runs the gates itself rather than trusting a self-reported result, reviews the code against the DAG, and reports honestly. It reads (query "plan") for completion status, (query "stale-phases") for phases active under a finished parent, and timeline to reconstruct what was actually done. It classifies findings as matches, deviations, or potential issues, each with a file:line, and refuses to green-light advancement while build or test failures remain.

These phases are documentarian and test-first by design. The method documents what is, not what should be; it writes the failing test first, for the right reason; it leaves zero TODO/FIXME/HACK in shipped code. It treats honest deviation as content — when reality differs from the plan, the agent pauses, surfaces the gap, gets a decision, and records it with observe.

Where the method is overkill

The cairn-method earns its weight when work outlives a single context window — multi-session efforts, plans with real phase ordering, or several agents touching the same tree. It is overkill for a one-off task finished in one sitting and never resumed. For a single quick change, a task_create and one observe is the whole method; forking phases and writing a handoff for work that ends in the same turn is ceremony, not continuity. The full loop is for the case where a reset would otherwise cost the context — that is what cairn exists for. When it would not, a plainer note wins.

Related

• What cairn is — continuity for agents, and the recursive loop in depth
• Plans, phases, and the frontier — why a plan is a DAG and how the frontier picks the ready work
• Tasks, observations, and handoffs — the three nouns the loop writes
• The current-task pointer — what task_bootstrap and task_fork move, and what task_id leaves alone
• Serve cairn over MCP — exposing the tools, the six prompts, and the cairn-method skill over MCP