Automaton

A workflow harness for Claude Code, Codex, and OpenCode

The chat window forgets. Artifacts don’t.

Watch the session on the right die mid-change and lose nothing. That is the whole idea: the work lives in files, not in the conversation.

npx @appautomaton/automaton install --claude
GitHub npm

Bet: a page that teaches the operating model in one scroll beats a feature pitch. You are reading that bet.

01 The problem

Long agent tasks lose the plot.

Anyone who has pushed an agent through a multi-day change knows the shape of the failure. The context window compacts and the reasons disappear. A fresh session re-reads half the repository to rediscover Tuesday’s decisions. “Done” arrives with no evidence attached.

None of that is a model problem. It is a memory architecture problem: the work lived in the conversation, and the conversation is the one thing guaranteed to vanish.

02 The operating model

Keep the work outside the window.

human yes human yes frame SPEC.md plan PLAN.md execute slices · commits verify fresh evidence verified terminal

The double bars are gates: the run stops there and waits for a human yes. Everything a stage produces is a file the next session can reload.

Stages with hard edges

A human approves the spec before planning starts, and authorizes execution before code changes. Verification re-derives results from fresh command output, never from the agent’s recollection of what it did.

Artifacts as contracts

SPEC.md and PLAN.md are reloadable contracts, not meeting notes. A fresh session reads them and continues where the last one stopped, because every decision was written down when it was made.

State as evidence

A small state file is the cursor and per-slice commits are the ledger. Recovery reconciles the plan against git history, so a resumed session trusts evidence over memory.

03 The proof

This page is a run.

We built this page with the harness. It is change 2026-07-05-automaton-landing-page, scoped in an office-hours dialogue, bounded by a spec, and held to eight acceptance criteria. The paper trail below is real.

SPEC.md

Bet: a single page that teaches the operating model in one scroll converts curious developers better than a feature pitch would.

Constraint: hand-authored static page, no build step, no framework. Fonts and libraries load from CDNs; nothing persisted locally.

.agent/work/…/SPEC.md

DESIGN.md

Typography: Zodiak and Author via the Fontshare CDN. The trending cluster (Inter, Geist, Instrument Sans, General Sans, Space Grotesk) was researched and ruled out by name.

Code face: your system’s own mono. A CLI tool should speak in your terminal’s voice.

.agent/work/…/DESIGN.md

Acceptance criteria

  • Authored assets under 100 KB, graphics in SVG
  • No font or library files committed, CDN only
  • Readable with JS disabled and fonts blocked
  • Both color schemes, no overflow at 360 px
  • Copy passes the project’s anti-slop scan
verified before deploy

04 The token economy

Instructions compete with your code for the same window.

Automaton’s entry points are deliberately small, and depth loads only when a trigger fires. The prompt budget is enforced in CI: a skill that grows past its word ceiling fails the build until someone consciously raises it.

Automaton: ~4k tokens Automaton ~4k Superpowers: ~7k tokens Superpowers ~7k Trellis: ~9k tokens Trellis ~9k GSD: ~25k tokens GSD ~25k gstack: ~28k tokens gstack ~28k Instruction tokens a model holds to complete one typical unit of work

In-house measurement across each harness’s default workflow, July 2026. Midpoints shown. Method notes live in the repository, and the point survives the error bars.

05 Verified

Install it where your agent works.

Copy-based install. Everything Automaton adds to your project is plain, inspectable markdown, recorded in a receipt so uninstall removes exactly what install created.

npx @appautomaton/automaton install --claude
npx @appautomaton/automaton install --codex
npx @appautomaton/automaton install --opencode

Then read the operating model in the repository, or start from the npm package. The depth stays in the repo on purpose: one home per contract.