Autopoet Docs

Overview

Autopoet ships inside every Workbooks runtime. It is a single supervised worker — one per nexus — that maintains the workspace it lives in: the agents, apps, hooks, and configuration authored as .work files. It is off by default. Nothing self-maintains until an admin arms it, and everything it may ever do is bounded by ceilings you write into the tree before it takes its first beat.

Three ideas carry the whole system:

• Authority is in the files. Ceilings and postures are declared in index.work files and travel with the tree. Governance is a property of your workspace, not a dashboard setting.
• Every change is evaluated in scratch and routed: autonomous merge, human escalation, or rejection.
• Everything learned is data — lessons, weights, reflex rules, ledgers — plain text in the tree, readable by you.

Arming the autopoet

The autopoet runs on a scheduled heartbeat (default: every 15 minutes). Arm it from the desktop app's nexus panel or the CLI:

work autopoet arm             # start the heartbeat (every 15m)
work autopoet arm --every 1h  # custom cadence
work autopoet status          # armed? cadence? time to next beat? last report
work autopoet cycle           # run one beat right now, synchronously
work autopoet disarm          # stop the heartbeat

status tells you whether it's armed, the cadence, milliseconds to the next beat, and a summary of the last cycle: what was sensed, what was proposed, and how each item was routed.

The loop

Each beat runs four phases:

Beats are synchronous and inspectable: work autopoet cycle returns the full report — what was sensed and the result of every item.

Ceilings & grants

A ceiling is the maximum capability set for a subtree, declared in that subtree's index.work:

ceiling do
  grant llm, store
end

Every index is the ceiling marker for everything beneath it. The effective ceiling at any path is the intersection of all ancestor ceilings — deeper indexes can only narrow. An agent's effective grant is:

effective = declared ∩ ceiling(parent) ∩ ceiling(grandparent) ∩ … ∩ ceiling(root)

Three consequences worth internalizing:

• A ceiling do end with no grant line is the tightest ceiling: it grants nothing below it.
• No ceiling block means unbounded at that level — ancestors still apply.
• Widening requires editing an ancestor index, which is above the autopoet's write scope. This is why self-escalation is impossible rather than merely forbidden.

Agents re-resolve their effective grant every turn — a merged ceiling change applies to a long-running agent at its next turn, not its next restart.

Management postures

Declared per agent, or per subtree in an index.work; human-mutable only.

agent :support_inbox do
  management frozen
  grant llm
  …
end

# or for a whole subtree, in its index.work:
management proposed

Effective posture is the most restrictive ancestor (frozen > proposed > managed). The autopoet itself is permanently frozen — its structure is never self-edited.

Leases

A lease is a bounded, expiring grant of one capability to one principal — the sanctioned way to exceed a ceiling temporarily without moving it.

work lease grant scout net --ttl 15m   # unblock scout with +net for 15 minutes
work lease active scout                # what does scout hold right now?
work lease revoke scout net           # end it early
work lease all                        # every live lease in the workspace

• Non-delegable: keyed to the principal. A sub-agent spawned by the lessee inherits nothing.
• Expiring: default TTL 15 minutes; re-granting refreshes, revoking ends it. Nothing accretes.
• Composed at run time: effective grant = (declared ∩ ceilings) ∪ active leases, re-resolved every turn.

Self-edit requests

When an agent needs a change it cannot make itself, it files a typed request and moves on — fire-and-forget, never blocking:

# from inside any agent's shell
request self 'grant +net' --why "3 fetches failed: api.stripe.com unreachable" \
  --evidence "telemetry: net.denied ×3 @ 14:02–14:05" \
  --acceptance "fetch to api.stripe.com succeeds"

The shape:

Requests dedup on target :: change — refiling the same ask with different prose collapses into one item. This typed shape is the injection firewall: prose can lie all it wants; it isn't what gets decided on, and the decision still can't cross the triad.

Eval in scratch

Every candidate change is validated in a throwaway copy of the tree before anything live is touched. Three gates:

1. Parse — every changed file still parses.
2. Purity — indexes stay composition/config only; no logic smuggled into an index.work.
3. Authority — the change respects postures and never lands a triad edit alone, including postures inherited from ancestor indexes.

The result has two orthogonal axes — a change can be perfectly valid and still require a human:

Merges then pass the same gate as human changes — references and capabilities resolve, the tree compiles, checks are green — and hot-propagate to everything referencing the changed file.

Escalations

Anything touching the structural triad — grant, ceiling, management — or any proposed/frozen target arrives on a human's desk with machine-generated reasons:

autopoet.escalation
  target:  agents/scout.work
  change:  grant +net
  reasons: [grant: scout]
  evidence: telemetry net.denied ×3, request req_8f2
  proposal: ready branch — merge, edit, or dismiss

Escalations carry the ready-to-merge branch. Approve and it lands through the normal gate; dismiss and the dismissal is learned — the autopoet stops re-proposing what you've declined, and says so in its lesson.

The knowledge log

Everything the autopoet learns is appended to a durable, human-readable knowledge.work — one lesson per line, topic-tagged, with evidence:

- (routing) escalations mentioning grant+net for scout are approved quickly :: 4/4 approved < 1h
- (rejection) edits to indexes with inline hooks fail purity :: eval fail ×2, purity gate
- (drift) mailer error-rate concern resolves via prompt pin, not model swap :: 3 incidents

work autopoet recall            # everything, most recent last
work autopoet recall routing    # one topic

The log is append-only and idempotent. It is the one thing the autopoet mutates without a human — because learning is data, and data can't escalate.

Plans & handoffs

For goals bigger than one edit, the autopoet is the single planner: it decomposes a goal into ordered, task-scoped subtasks, each carrying a handoff — a self-contained brief (title, task, context, inputs, acceptance, assignee) so the delegated agent runs without ever needing to ask a clarifying question. Delegation is ephemeral: agents are dispatched per-task and released; there is no persistent swarm to manage. Plans and tasks land as events on the workspace bus, so your to-do views and dashboards see them like any other work.

Plasticity

The workspace graph — files, agents, documents, and the references between them — carries learned weights. Co-activation strengthens an edge (bounded, so weights never blow up); disuse decays it; activation spreads, so attention flows along the learned structure. The effect you see: navigation, recall, and the autopoet's own proposals increasingly match how you actually work, and re-adapt within hundreds of events when your workload shifts.

work autopoet weights path/to/file.work   # the learned neighbourhood of any node

Surprise gate

A cheap predictor prices the surprise of every event on the bus. Routine events run on installed reflexes (micro-rules in the tree, TTL-bounded). Surprising events escalate to the full model — and the model's answer installs a new reflex, so novelty is paid for once. The surprise channel doubles as the drift alarm: sustained prediction degradation on the autopoet's own data is exactly what files a drift concern into the next beat.

The economy

Components — prompts, tools, reflex rules, routes — bid from earned wealth to act. Chains that end in verified outcomes are paid along their whole length; what stops earning stops being selected. The ledger is plain data:

work autopoet ledger              # component wealth, earnings, last-paid
work autopoet ledger --ablate R42 # counterfactual: did R42 actually matter?

• Frozen reward: what counts as a good outcome is human-defined and not learnable.
• Pay-to-act: acting costs; chain-stuffing bankrupts the staffer.
• Audits: ablation checks that paid components changed outcomes; tripwire metrics watch for gaming.

The access panel

One pure read shows the whole authority picture — every agent's posture and resolved ceiling, tallies of managed/proposed/frozen, active leases, and any impure indexes:

work autopoet access

This is the page to open before you arm anything: it is the map of what the autopoet could ever touch.

Budgets & bounds

Reference

Defaults

Routes

See also

• The paper — the full definition and scope.
• Glossary — every term of art, one line each.
• FAQ — the questions everyone asks first.