Step 07 · Execution layer · Execution layer · Mission, VM, and alembic.plan.ts ENPT
Alembic Complete Visual Course

Mission, VM, and alembic.plan.ts

Compile human missions into executable specs and run TypeScript plans with hooks.

Read the plain version, or open the technical layer on any section.
1

From intent to execution

@alembic/mission takes a human-friendly MissionOptions object (title, milestones, units with proof commands) and compiles it into an AlembicRunSpec ready for the swarm. It also injects milestone validator tasks automatically.

@alembic/vm loads a user-written alembic.plan.ts module and injects AlembicHooks: phase, agent, parallel, pipeline, mission, swarm, council, and log.

Think of it like… sheet music (mission) is turned into a concert program (run spec), and the conductor (VM) calls musicians (hooks) at the right moments.

Under the hood

The VM checks plans for determinism (no Date.now(), new Date(), or Math.random()) before running. It caches agent and swarm outputs under <runDir>/workflows/<wfId>/cache.json. Mission compiler prefixes task IDs so multiple missions in one plan do not collide in the shared store.

2

In one picture

MissionOptions AlembicRunSpec Swarm drain alembic.plan.ts → AlembicHooks
Missions compile to run specs; the VM loads a plan module and calls hooks that drive the swarm.
3

In the code

# run a goal + plan pair
alembic run --goal GOAL.md --plan alembic.plan.ts --yes --offline

Implementation notes

loadScope in @alembic/forge materializes the run directory. The CLI then calls runPlan with the compiled plan module path. Hooks prefix task IDs and emit phase events so the TUI and web cockpit can render progress.

4

Try it

Generate a plan with alembic plan "...", then run it with alembic run --goal ... --plan .... Inspect the run directory.

Debug: If a plan fails determinism check, what constructs should you remove?
5

Quick check

Which hook runs a compiled mission inside an alembic.plan.ts?