autonomation

Operating doctrine for multi-agent software factories. Toyota Production System and TSMC manufacturing principles translated into artifacts for agentic engineering — schemas, halt conditions, gates, yield dashboards, and rituals that turn a capable agent substrate into one that ratchets every cycle.

Status: v0.0.1 — first slice shipped. The conceptual frame and all six surfaces are in place; playbooks/ is deliberately deferred until real friction-log data exists.

• See INFLUENCES.md for the inherited traditions — Toyota Production System, TSMC, Google SRE — what each contributed and where the syntheses choose sides.
• See STRUCTURE.md for the repo's structural identity — spec + SDKs, OpenTelemetry-shaped.
• See CARRIERS.md for the conceptual frame — loop anatomy, structural rules, seam taxonomy.
• See USAGE.md for the end-to-end consumption flow with code snippets.
• See DESIGN.md for the top-level design, surface inventory, and build order.
• See design/verification.md for verification strategies — how we check that the doctrine actually holds, what's been applied, what's still hand-waved.
• See doctrine/ for the principle documentation — start with prime-directive.md and jidoka.md.
• See plugins/autonomation/ for the Claude Code plugin SDK (skills + agent personas).

Spec + SDKs

Autonomation is a protocol-shaped repo — OpenTelemetry-shaped, specifically. The canonical content is a spec (artifact schemas, seam contracts, event vocabulary, structural rules, and the doctrine that justifies them); the rest is reference SDKs that produce conformant artifacts.

This repo ships two SDKs around the same spec:

• TS / CLI SDK. Import the TS package (import { Halts, Yield, Gates } from "autonomation") or shell out to the autonomation CLI from your runtime. Validators and computation run inline; no agent in the loop.
• Claude Code plugin SDK. Use the plugins/autonomation/ Claude Code plugin. Skills like /autonomation-retrospective instruct an agent through phases and call the CLI for validation. Specialized agent personas (e.g. autonomation-retro-analyst) run in separate lanes from execution.

Both SDKs produce identical artifacts validated by the same schemas. Consumers can replace either or write their own SDK against the spec. See STRUCTURE.md for the layering.

What this is

Autonomation is the doctrine layer for multi-agent software factories. It is not a runtime, learning system, memory layer, or task tracker — those exist as separate concerns in any mature multi-agent system. Autonomation is designed to be useful standalone and to compose with existing components when they're present, supplying the discipline layer most agent systems are missing: explicit halt signals, structured failure taxonomies, yield decomposition, signal-driven kaizen, externalization-as-closure protocols, and versioned interface contracts.

The framing target is a dark factory — multi-agent swarms producing software with minimal human-in-the-loop, where every TPS principle that used to be carried by human attention has to be carried by an artifact instead.

Surfaces

| Surface | Purpose | Status | |---|---|---| | doctrine/ | Cultural layer in artifact form — TPS/TSMC principles with carriers | shipped | | standards/ | Schemas, taxonomies, role contracts (poka-yoke — standardized vocabulary + contracts) | shipped | | halts/ | Andon condition library + halt-signal schema (jidoka) | shipped | | yield/ | Metrics, decomposition, andon stats (yield obsession) | shipped | | rituals/ | Retrospective, trace-walk, tournament, skill-harvest protocols (kaizen) | shipped | | gates/ | Promotion + eval policies (disciplined cadence) | shipped | | playbooks/ | Packaged recipes — kaizen's externalize-the-recipe output | deferred until friction data exists |

See DESIGN.md for the build order with stop-conditions per phase, and USAGE.md for how the surfaces compose at runtime.

Install

npm install autonomation

Experiment Runner Quickstart

Run the deterministic local example:

npm run build
node dist/cli.js experiment run --config examples/experiment/autonomation.experiment.yaml
node dist/cli.js experiment inspect --summary examples/experiment/.autonomation/experiment-summary.json

For a real coding-agent Evolver, point the config at a git repo, choose an editable target file, and use outputDir to collect artifacts:

repoRoot: /path/to/repo
outputDir: .autonomation/my-run

target:
  substrateId: app
  variableId: prompt
  file: prompt.txt
  kind: artifact-content
  contentType: text/plain

evaluator:
  command: [node, eval-objective.mjs]
  metric:
    id: eval.score
    pattern: 'eval\.score:\s+([0-9.]+)'

evolver:
  kind: claude-code
  timeoutMs: 600000
  prompt: Improve prompt.txt so eval.score increases.

objective:
  metric: eval.score
  direction: increase

run:
  cycles: 5
  budgetSeconds: 1800
  stopAfterNoPromotion: 3

allowedPaths:
  - prompt.txt

With outputDir, the runner writes experiment-summary.json, experiment-journal.tsv, and experiment-events.jsonl under that directory unless explicit artifacts.summaryPath, journal.path, or observability.logPath values are configured.

Lineage defaults to in-memory state plus durable summary/journal artifacts. To persist full LineageEntry JSON in git, configure a sidecar branch:

lineage:
  kind: git
  branch: autonomation/lineage/my-run
  dir: .autonomation/lineage

The lineage branch stores .autonomation/lineage/<subtree>/<candidateId>.json and links each candidate back to its retained git snapshot through changeSnapshot.baseCommit and changeSnapshot.headCommit.

After a run, list branchable candidates and turn a candidate or the promoted experiment branch into a normal review branch:

node dist/cli.js experiment candidates --summary examples/experiment/.autonomation/experiment-summary.json
node dist/cli.js experiment branch-candidate \
  --summary examples/experiment/.autonomation/experiment-summary.json \
  --candidate <candidateId> \
  --branch review/my-candidate
node dist/cli.js experiment branch-promoted \
  --summary examples/experiment/.autonomation/experiment-summary.json \
  --branch review/my-experiment

Candidate branches are sourced from retained refs named autonomation/candidates/<candidateId> when available. The promoted branch is sourced from the summary's experimentBranch, or from a retained experiment worktree when no experiment branch exists.

For evolver.kind: agent-workspace, the experiment runner gives the backend the existing candidate git worktree as cwd. If sandbox.enabled is true, the runner uses agent-workspace's sandbox command wrapper against that git worktree; it does not copy the repo into a separate WorkspaceManager directory.

Mini-SWE-agent can be evaluated either as a command shim or natively. The shim prints metric lines that the generic command evaluator can parse:

node dist/cli.js swe eval-mini --config mini-swe-evaluator.yaml

The native experiment config uses the same SWE machinery without a separate script. Candidate git snapshots are projected into a swarmkit-eval matrix arm, evaluated across SWE instances, and the winning git commit is still promoted onto the experiment worktree:

target:
  substrateId: mini-swe-agent
  variableId: agent.src
  file: src/minisweagent/agents/default.py
  kind: code-region
  language: python

evaluator:
  kind: swe
  instancesDir: packages/ts-sdk/src/examples/swe/fixtures
  boxPath: /opt/agent/lib/python3.11/site-packages/minisweagent/agents/default.py
  stepLimit: 40
  costLimit: 2

objective:
  metric: swe.pass_rate
  aggregate: mean
  direction: increase

Optional W&B tracking uses @wandb/sdk and WANDB_API_KEY:

npm install @wandb/sdk
WANDB_API_KEY=... node dist/cli.js experiment run --config autonomation.experiment.yaml

observability:
  trackers:
    - kind: wandb
      project: autonomation
      runName: prompt-optimization
      tags: [experiment]

License

MIT