a·dapt
Agent Development for Autonomous ProducTs

a·dapt

Agent Development for Autonomous ProducTs

A closed loop of coding agents that evolves a software product on its own — discovering user-level scenarios, validating them against the running app like a real user, turning failures into tracked work, fixing them, and dreaming up what to build next. No human in the loop. You just watch the organism think.

Watch the loop an interactive, scroll-driven walkthrough (no install)
every phase implemented & stub-tested suite green — npm test Node · TypeScript plug into any full-stack app
01

The thesis

The scenario is the contract. Reality is the judge. The product adapts to demand like an organism.

adapt is a generic, plug-and-play framework. It is not a coding model — it is the rails around existing elite coding agents (Claude Code & friends): the orchestration, the durable artifacts, the safeguards, and the observability. The agents stay static; the product improves.

scenario = contract

Truth is a real user goal with a visible success condition — not the code, not the agent's memory, not the current UI.

reality is the judge

A change is "done" only when an independent agent confirms the scenario passes in a real browser. No self-approval.

git is the safety net

Every change is a commit on a branch in the target repo. The organism can't destroy work; its whole evolution is replayable.

separation of powers

Generator may read code; the runner may not; the fixer must; the verifier is independent of the fixer. The loop can't rubber-stamp itself.

durable artifacts

Agents talk through versioned files & a run ledger, never fragile chat memory. Messages are disposable; artifacts are authoritative.

demand has a source

Autonomy without pressure is drift. A Dreamer raises the north-star; a Critic keeps the dreams honest.

02

The loop

Nine cooperating roles, each an instance of a coding-agent engine, deliberately given different knowledge and permissions — orchestrated by a deterministic state machine and observed live.

● live
bootstrap

Scout

Runs once at adapt init. Reads the target repo and drafts the north-star the whole loop steers toward.

reads repo · writes north-star.md
● live
demand

Dreamer

Reads the north-star & product, proposes the next ambition — features that add real value.

reads code + explores the live app · no write
● live
demand

Critic

Skeptical product owner. Challenges each dream — real value or bloat? Only survivors advance.

reads code · no write
● live
discovery

Scenario Generator

Turns demands into user-centered, black-box scenarios with stable IDs & success criteria.

reads code (discovery only) + the live app
● live
validate

Runner

Black-box. Drives the running app like a user via Playwright MCP, classifies pass/fail/flaky.

no source access
● live
triage

Failure Triage

Dedupes failures, classifies real bugs, opens tracked work with full evidence (Jira-backed).

inspects the failing page · no code writes
● live
repair

Implementation

Reads the issue, scenario & evidence; makes the smallest safe fix; never closes its own ticket.

reads + writes code
● live
verify

Verification

Independent of the fixer. Reruns the exact scenario in a real browser before anything is "done".

closes work — only after proof
● live
graduate

Graduation

Once a scenario has passed enough times in a row, rewrites it as a deterministic Playwright spec and retires it from the LLM loop.

reads source · writes tests only
● live
spine

Orchestrator + Console

Deterministic state machine, git safety net, attempt limits, crash recovery — streamed to mission control.

built in Phase 0
03

What's built

Every phase is live: the rails + console, the autonomous spine, the demand engine that dreams up new work, the endurance loop that runs it non-stop while graduating proven scenarios into cheap deterministic tests, and the lanes that let several lineages evolve in parallel. Test-driven throughout, every plan independently reviewed before it landed.

① Workspace & config foundation

The plug-and-play boundary — adapt becomes target-specific only at runtime.

  • adapt init scaffolds a .adapt/ workspace inside any repo
  • Zod-validated config (engine, console, Jira, MCP servers, limits, DB hooks)
  • Scenario format — markdown + YAML frontmatter — with a machine-readable registry
  • Exported JSON Schemas for config & scenarios

② Orchestrator & state

The real brain — deterministic, persistent, crash-safe.

  • Lifecycle state machine for scenarios, runs & work-items (every transition validated)
  • SQLite-backed state with an append-only run ledger (the source of truth)
  • Attempt limits & crash recovery — stranded runs resolve to inconclusive on restart

③ Agent harness & live console

Mission control — watch the organism think in real time.

  • Pluggable engine: Claude Code headless adapter (stream-json) + a deterministic stub
  • Event bus → append-only decision log (the primary research artifact)
  • adapt console: a websocket web dashboard — per-agent panes + a decision timeline

④ The autonomous spine — Phase 1

The closed validate → triage → repair → verify loop, stub-tested end-to-end.

  • adapt run-scenarios: a black-box Runner drives the app, writes a schema-validated verdict
  • adapt triage-failures: dedup + classify failures into tracked work-items (Jira via MCP)
  • adapt orchestrate: fix on a branch → independent verify → done / reopen, with attempt limits

⑤ The demand engine — Phase 2

The organism chooses its own work — no success state, it dreams higher.

  • Dreamer proposes ambition (appended to the north-star, git-versioned) + capped demands
  • Critic gates each demand — only survivors become scenarios (no rubber-stamping)
  • Generator turns approved demands into Node-ID'd, validated black-box scenarios
  • adapt evolve: dream → critique → generate → then the whole Phase 1 cycle

⑥ Endurance & graduation — Phase 3

The organism runs on its own — and retires what it has proven.

  • adapt run: loop evolve until a guardrail (max cycles / wall-clock / consecutive errors) or Ctrl-C
  • Graduation: a scenario that passes N times in a row becomes a deterministic Playwright spec — the LLM runner skips it forever
  • Robustness: verifier infra-failures → inconclusive, reopened items re-driven, demands deduped — so a cycle is safe to repeat indefinitely
04

How you use it

adapt is a separate framework you point at a target product. Nothing target-specific lives in adapt; a .adapt/ workspace lives inside the product repo.

zsh — adapt
# 1 · plug adapt into any full-stack project
adapt init ./my-app --app-base-url http://localhost:3000
  created  ./my-app/.adapt/
  created  ./my-app/.adapt/scenarios/examples/example.login.md
  created  ./my-app/.adapt/config.example.json
  created  ./my-app/.adapt/.gitignore
  created  ./my-app/.adapt/north-star.md
  adapt workspace ready at ./my-app/.adapt

# 2 · cp .adapt/config.example.json .adapt/config.json and edit it, then copy a
#     scenario UP out of examples/ — only *.md at the top level of scenarios/ runs

# 3 · run the autonomous loop
adapt run-scenarios ./my-app     # validate scenarios in a real browser
adapt triage-failures ./my-app  # dedup + file work-items
adapt orchestrate ./my-app      # one bounded pass: validate → triage → fix → verify
adapt evolve ./my-app           # the full organism: dream → critique → generate → cycle
adapt run ./my-app --console 4399  # non-stop: loop evolve until a guardrail or Ctrl-C

# 4 · fork parallel lineages off a named baseline
adapt baseline create v1 ./my-app        # tag the current HEAD as a fork point
adapt lane create a ./my-app --baseline v1 # a git worktree with its own ports + db
adapt lane start a ./my-app            # also: lane list | stop | reset | destroy

# 5 · watch it think, live
adapt console ./my-app --port 4399  # one run
adapt monitor ./my-app --port 4500  # every lane, side by side
  adapt console at http://127.0.0.1:4399  (Ctrl-C to stop)
<your-product>/            # adapt is pointed here; agents commit into this repo
  .adapt/                  # per-target workspace (created on init)
    config.json           # target-specific: app URL, db hooks, limits, Jira
    north-star.md         # the "genome" — versioned; watch ambition evolve
    scenarios/            # user-centered scenarios (the contract)
      examples/           # templates only; NOT indexed, NOT run
    scenario-runs/        # append-only run ledger
    work-items/           # tracked failures
    demands/              # what the Dreamer/Critic decided to build next
    baselines/            # named fork points that lanes branch from
    decision-log/         # narrated timeline — the primary deliverable
    state.db              # orchestrator state (gitignored)
05

Roadmap

Build the trustworthy spine first; add autonomous judgment on top. You can only trust a dream once you can trust the verifier.

0✓ complete

Rails & console

Workspace + config, orchestrator state machine, SQLite store & run ledger, agent harness, decision log, live web console. Driven end-to-end by a stub agent.

1✓ complete

The autonomous spine

Scenario Runner → Failure Triage (Jira) → Implementation → independent Verification, wired into adapt orchestrate. Closed-loop validate-and-repair with DB hooks & attempt limits — stub-tested, ready for the first real run.

2✓ complete

Demand engine

Dreamer + Critic (adversarial pairing) + source-aware Scenario Generator, wired into adapt evolve. The loop chooses its own work and the Dreamer appends ambition to the north-star — stub-tested.

3✓ complete

Endurance & graduation

adapt run loops evolve non-stop under guardrails (max cycles / wall-clock / consecutive errors). Proven scenarios graduate into deterministic Playwright specs and leave the LLM loop; verifier-inconclusive handling, reopened re-drive, and demand dedup make a cycle safe to repeat forever — stub-tested.

4✓ complete

Lanes & the multi-lane console

Named baselines tag a fork point; lanes are git worktrees with their own branch, ports, database and optional model, so several lineages evolve from one baseline in parallel. adapt monitor watches them all in one dashboard, with per-lane and global start / pause / continue / restart / stop and a Cycles view that opens each step's prompt and output.

All of it is implemented and stub-tested end to end. The honest open question is real-world endurance: how well the LLM oracle holds up over long unattended runs against a live product.

06

Build log

A living record — every phase appends here. This file is the canonical human-facing history of adapt's own construction.

2026 · 06 · 14 — lane controls & Jira on by default

The monitor gains a control plane

Lanes became drivable from the browser: a control.json per lane carries pause / stop / maxCycles, runContinuous honours it mid-loop, and the monitor grew per-lane and global start / pause / continue / restart / stop buttons. The Cycles view arrived alongside — a pure buildCycles segmenter turning the raw event log into cycles and steps, with each step's INPUT and OUTPUT openable inline. A step's verdict now comes from the agent's exit code rather than the presence of benign stderr. run.maxCycles and run.maxWallClockSeconds default to null (unbounded), so guardrails are an explicit choice. Jira via mcp-atlassian is enabled by default, with PAT and Cloud credentials kept mutually exclusive so an ambient token cannot hijack a self-hosted run.

2026 · 05 · 28 — baselines, lanes & the multi-lane console

Parallel evolutionary lineages

adapt baseline create tags a fork point; adapt lane create spins a git worktree with its own branch, port block, database and optional model. Lanes run the same loop in isolation, so several lineages can evolve from one baseline at once and be compared. adapt monitor watches all of them in one dashboard, streaming from any lane whose loop is live and replaying each lane's decision log otherwise.

2026 · 05 · 26 — Phase 3 merged

Endurance & graduation land on main — the organism is complete

Three plans — robustness carryovers (verifier-inconclusive, reopened re-drive, demand dedup), graduation (proven scenarios → deterministic Playwright specs, retired from the LLM loop), and adapt run (a bounded continuous evolve loop with guardrails). Opus-reviewed with fixes en route (a gray-matter cache-poisoning bug in the frontmatter writer, guardrail-aware pause, explicit stop). 184 tests passing, typecheck clean. adapt now runs on its own — dream → critique → generate → validate → triage → repair → verify, cycle after cycle, until a guardrail or Ctrl-C. Next: the first real run on a live app.

2026 · 05 · 26 — Phase 2 merged

The demand engine lands on main

16 TDD tasks via subagent-driven development (Opus 4.7 throughout) across three plans — Demand model + Dreamer + Critic, the Scenario Generator, and adapt evolve. Plan 7 Opus-reviewed; Plans 8–9 + integration controller-reviewed; fixes en route (a DemandStatus type export, a generator-stub typecheck). 155 tests passing, typecheck clean. The Dreamer now appends ambition to the north-star (append-only, git-versioned) and evolve runs the whole organism — dream → critique → generate → validate → triage → repair → verify — on a stub.

2026 · 05 · 26 — Phase 1 merged

The autonomous spine lands on main

22 TDD tasks via subagent-driven development (Opus 4.7 throughout) across three plans — Runner, Triage + tracker, Implementation + Verification + orchestrate. Every plan Opus-reviewed; findings fixed (verdict guard against illegal transitions, runnable-status filter, a runRole schema-input widening, an as const typecheck break). 126 tests passing, typecheck clean. run-scenarios, triage-failures, and orchestrate close the loop on a stub — next is the first real run.

2026 · 05 · 26 — Phase 0 merged

Rails & console land on main

29 TDD tasks via subagent-driven development across three plans (workspace/config, orchestrator, harness/console). Every plan independently reviewed by Opus 4.7; findings fixed (ledger/recovery consistency, a stream-parser crash guard, ws ordering, dashboard hardening). 74 tests passing, typecheck clean. adapt init and adapt console work end-to-end.

2026 · 05 · 26 — design frozen

Blueprint & Phase-0 plans committed

Brainstormed the full organism, then froze decisions: generic/plug-and-play, Phase-A build order (spine before dreamer), Node + TypeScript, web console, Jira behind a swappable adapter. Three detailed TDD implementation plans written for Phase 0.