What Counts As A Program In An Agent OS?

What this article answers (plain language): A program in an agent OS is a bundle of three things — a manifest that declares its identity and capabilities, a reference workspace that gets forked into yours on activation, and a composition manifest that tells the cockpit how to render its surfaces.

A program in an agent OS is the AI equivalent of a .app bundle. It declares what it is, ships its starter substrate, and tells the operating system how it wants to be displayed. Activating it forks the bundle into your workspace. Deactivating leaves your data intact and just removes the program's framing. Most products that call themselves "agent platforms" don't have this concept yet, which is why their use cases bleed into each other.

When we built our first program — alpha-trader, an autonomous trading operations bundle — I expected it would be an opinionated configuration on top of the platform. It turned out to be much more than that. It was an actual bundle in the macOS sense: a directory with a manifest, default templates, persona, capability declarations, and a UI rendering description. That bundle is portable across workspaces. It can be installed and uninstalled. It can ship updates without overwriting operator-authored content. It is, structurally, an application.

The Three Files Every Program Bundle Needs

Every program in our agent OS lives at /programs/{program-slug}/ with three required files at the root:

MANIFEST.yaml — machine-readable program identity. Declares the program slug, status (active, reference, deferred, archived), required platform integrations, declared capabilities, default agent roster, default task templates, and lifecycle phases (e.g., observation → paper execution → live execution). The manifest is what the kernel reads to know whether the program can run in a given workspace.

README.md — human-readable program prose. The operator-facing and architect-facing description of what the program does, who it's for, and how it differs from other programs. The README is what shows up in the program picker.

SURFACES.yaml — composition manifest. A declarative description of how the cockpit should render when this program is active. It speaks in archetypes (Document, Dashboard, Queue, Briefing, Stream) and binds them to substrate paths in the operator's workspace. The compositor reads it on every render.

Plus one required directory:

reference-workspace/ — the bundle's starter substrate. The mandate template, the autonomy defaults, the principles the reviewer should apply, the operator profile prompts, the risk envelope. On program activation, these files get forked into the operator's workspace at the same paths. Files are tagged by tier — canon (program ships authoritative version, re-applied on update), authored (operator must overwrite via guided conversation), placeholder (empty, accumulates from work).

That's the whole bundle. Manifest plus README plus surfaces plus reference workspace. Four pieces of declarative content, no executable code shipped from the program. The kernel does the work. The program just declares.

Why Activation Is A Fork, Not An Install

When you "install" macOS Excel, the binary lives at /Applications/Excel.app/. When you open it, it reads its own templates from inside the bundle. Your spreadsheets live in ~/Documents/. The application doesn't merge into the OS — it stays in its own folder.

An agent OS program works the opposite way. Activation forks the bundle's reference workspace into the operator's workspace at the same paths. Why? Because the operator needs to author the substrate the program will reason against. The reviewer's principles file, the mandate, the risk envelope — these have to be operator-owned, operator-editable, operator-attributed. They can't live inside the program bundle if the program is going to learn from operator authorship.

Forking on activation means the program can ship a great template, the operator can customize it, and program updates can re-apply canon-tier files (the boring infrastructure) without touching authored-tier files (the operator's voice). It's the discipline of every templating system that survived contact with users — Hugo, Jekyll, dotfile managers — applied to AI substrate.

The trade-off: activation has consequences. The operator now owns substrate that resembles the program's worldview. Deactivating doesn't delete it — that would lose operator-authored revisions — it just removes the program's framing from the cockpit. The accumulated work stays.

The Composition Manifest Is The Program's UI

A program doesn't ship UI code. It ships a composition manifest that describes what the cockpit should render. The manifest speaks in surface archetypes:

• Document surfaces (composed output you read)
• Dashboard surfaces (live substrate slices you scan)
• Queue surfaces (pending actionable items)
• Briefing surfaces (periodic curated summaries with pointers)
• Stream surfaces (append-only chronological logs)

The compositor reads the manifest, fetches the bound substrate, and renders the appropriate component. The program doesn't ship the component — that's part of the system component library, kernel-level, shared across every program. Adding a component requires a kernel decision (it benefits every program). Adding a binding to an existing component is application-level (only this program needs it).

This is what makes the cockpit alive. When you activate alpha-trader, your cockpit gets four faces — Mandate, Money Truth, Performance, Tracking — because that's what the program's SURFACES.yaml declared. When you activate a different program, the cockpit looks different, because the manifest is different. The kernel doesn't know about traders. It knows about archetypes and bindings.

What This Lets Operators Do

The program-bundle pattern enables a few things that matter in practice:

Try a program without commitment. Activate alpha-commerce on Monday. Spend a week. Deactivate. Your accumulated data stays; the framing leaves. Activate alpha-trader instead. The cockpit reshapes around the new program's archetypes. None of this is destructive.

Run multiple programs in the same workspace. Each contributes its archetypes to the cockpit. They share substrate where it makes sense (the operator's identity, the workspace mandate) and stay separated where it doesn't (program-specific context domains, program-specific tasks).

Receive program updates that don't overwrite your work. When alpha-trader ships a v2 bundle, the kernel re-applies canon-tier files (boring infrastructure that the operator wouldn't touch anyway). Operator-authored files stay as-is.

Author your own programs. Because a bundle is just markdown and YAML in a directory, anyone can write one. We expect early programs to come from operators in specific verticals — a public-markets trader's program, a Shopify operator's program, a fundraising consultant's program — each shipping their accumulated wisdom as a reference workspace and a cockpit shape.

Why Most "Agent Templates" Don't Count

A lot of agent products ship "templates" — pre-configured workflows you can clone. These aren't programs in the OS sense. They're configuration imports. The differences:

A template fills in your existing schema. A program declares its own. A template is consumed once and forgotten. A program persists, can be updated, can be uninstalled. A template doesn't reshape the UI. A program does — that's what the composition manifest is for.

The reason this matters isn't taxonomic. It's that the agent products with real program bundles can be a platform that other people build for. The products with only templates can't, because there's no way for an outside developer to ship something that the operator can install, run, update, and uninstall as a coherent unit.

Programs are how the agent OS becomes an ecosystem. That's the whole reason the OS pattern won the first time. It's almost certainly why it'll win again.

Key Takeaways

• A program bundle is four things: manifest, README, composition manifest, reference workspace.
• Activation forks the reference workspace into the operator's workspace; deactivation leaves data intact.
• Programs ship declarative substrate, not executable code. The kernel does the work.
• The composition manifest tells the cockpit how to render itself; the kernel ships the components.
• Templates are imports. Programs are installable, updatable, uninstallable applications.
• For the bigger frame, read The Agent OS Is Real (And It's Not a Framework).