--- title: "The Capsule Platform" slug: "capsule-platform-architecture" summary: "A platform architecture paper describing capsules as portable AI work artifacts — self-contained containers that embed context, verifiable history, executable skills, and orchestration logic into a single transferable file." status: "draft" version: "0.5" updated: "2026-05-01" audience: - "partners" - "investors" - "technical adopters" tags: - "capsule" - "platform" - "architecture" - "skills" - "orchestration" - "sdk" - "artifacts" canonical_path: "/research/capsule-platform-architecture" --- # The Capsule Platform ## Portable AI Work Artifacts and Self-Orchestrating Execution ## Abstract Artificial intelligence is transforming how work is created, interpreted, and executed. However, most AI systems today operate within fragmented environments where context, state, and provenance are distributed across documents, databases, and software systems. Capsules introduce a new artifact class designed for AI-mediated collaboration. A capsule is a portable container that embeds structured context, verifiable history, executable skills, and orchestration logic into a single transferable file. Capsules enable work to move between humans, AI systems, and organizations while preserving the context necessary to continue that work. By combining content, state, event history, and embedded capabilities within a deterministic container, capsules allow artifacts to function as self-orchestrating units of collaboration rather than static documents. The Capsule Platform extends this artifact model with an SDK, domain templates, a maturity model for progressive capability, and alignment with the Agent Skills ecosystem — an open standard adopted by over thirty agent products — to ensure capsules are interoperable across the broadest possible range of AI systems. --- ## 1. Introduction Traditional digital work artifacts fall into three categories: documents, databases, and software applications. These layers evolved independently. Documents capture narrative context, databases store structured data, and software executes workflows. In complex collaborative environments, work becomes fragmented across multiple systems. Context must be reconstructed repeatedly as tasks move between teams, tools, and organizations. Artificial intelligence systems further expose the limitations of this architecture. AI agents require access to both structured state and historical context in order to perform meaningful work. When this information is fragmented across systems, AI agents cannot reliably interpret or continue workflows. Capsules address this problem by introducing a new primitive: the portable work artifact. A capsule packages the full working context of an artifact — data, history, skills, and workflow logic — into a single portable file that can be validated, executed, and resumed anywhere. --- ## 2. Capsule Artifacts A capsule is a deterministic container that stores a collaborative artifact and its operational context. Capsules are distributed as `.capsule` files, which are structured ZIP archives containing resources and metadata packaged under strict canonical rules: no compression, fixed timestamps, and lexicographic file ordering for reproducible packages. The current v0.6 shape uses a small set of canonical parts: - `program.md`: the human-readable work product, plan, handoff, and continuation surface - `agents.md`: participants, authority notes, and skill-trust context - `chain/events.jsonl`: append-only provenance - `manifest.json`: content index, participants, version, and package metadata - `payload/`: evidence, datasets, child capsules, generated artifacts, and source material - `skills/`: portable Agent Skills - `provenance/envelope.json`: signed envelope metadata, with optional encryption Older papers described separate `surface.md`, `handoff.md`, `plan.md`, and `state.json` files. The v0.6 redesign deliberately collapsed that surface area. State is computed from the program, participants, payloads, and event chain. Handoff and plan live inside `program.md` where both humans and AI systems can read them without a custom parser. ### Program Layer The human-readable and AI-readable representation of the work. Examples include research papers, reports, compliance summaries, command briefs, and medical notes. This layer enables a foreign runtime to understand the current state without the prior application. ### Agent and Capability Layer The actor roster, trust notes, and embedded skills. This layer explains who participated, what authority they had, and what portable instructions can be used to continue the work. ### Ledger and Envelope Layer An append-only event history describing how the artifact evolved. Each event records the actor performing the action, a timestamp, the action performed, associated data, and a cryptographic hash linking the event to the previous entry. This ledger creates a tamper-evident record of claimed actions and recorded modifications. Verification proves the bytes, hashes, and signatures; trust in the actor and interpretation of the payload remains host policy. The envelope signs package metadata and, when encrypted, lets a verifier check outer integrity before recipient-side decryption. Verification proves the math. Trust still belongs to the receiving host through allowlists, pinned keys, and policy. --- ## 3. Capsule Orchestration A capsule is not merely a container. It is a portable control plane for work. Rather than depending on one external runtime or workflow engine, a capsule carries the context needed for a runtime to decide what to do next. The host still owns execution authority. The capsule records the plan, state, evidence, skill context, and results in a form another host can verify and continue. When an AI system receives a capsule, it can follow a concrete path: open the file, verify the envelope and chain, read `program.md` and `agents.md`, inspect payloads and skills, decide whether it has authority to act, then append or return a result through the host. This model does not require every environment to be identical. A cloud agent, local language model, browser workspace, mobile host, or MCP relay can each participate if it can read the artifact and respect the trust boundary. ### Plan-Driven Execution Each capsule can contain a plan as ordinary markdown inside `program.md`, plus structured references in the manifest and event payloads where needed. Plans are authored so both humans and AI can read them naturally. Plan steps can reference embedded skills for specialized computation, delegate subtasks to child capsules, request human input at decision points, or direct the AI to synthesize results. Hosts can project those steps into DAGs or task queues, but the canonical work record remains the capsule. ### Event Recording Every meaningful action a host chooses to preserve during execution — skill invocations, delegations, absorptions, output validations, human decisions — can be recorded as a chain event with cryptographic linkage to the previous event. This creates a tamper-evident audit trail of recorded actions, not an automatic proof that every real-world step occurred exactly as described. --- ## 4. Embedded Skills and the Agent Skills Ecosystem Capsules embed portable capabilities using the Agent Skills specification, an open standard adopted by over thirty agent products including Claude Code, Cursor, GitHub Copilot, VS Code, Gemini CLI, OpenAI Codex, and others. Each skill is a self-contained directory within the capsule containing a SKILL.md file with instructions, optional executable scripts, and reference material. The format is unchanged from the ecosystem standard — any skills-compatible agent can discover and use capsule-embedded skills without capsule-specific knowledge. Capsules add what the skills specification alone does not provide: package integrity through SHA-256 content indexing, explicit `skill_trust` entries, and a chain where hosts can record skill use and resulting artifacts. Determinism declarations, input/output schemas, and richer invocation governance remain host policy or future manifest extensions, not required v0.6 fields. That preserves skill portability while adding a verifiable boundary around the artifact. This design creates a clear separation of concerns. Skills provide portable capabilities that work across agents. Capsules provide the orchestration, integrity, and provenance layer that makes those capabilities auditable and trustworthy. ### The Capsule Skill The public capsule skill is distributed as an installable Agent Skill. It teaches an AI agent to understand the capsule protocol and bundles local helpers so the agent can open, read, verify, and produce capsules from a single skill installation. Rather than requiring agents to have built-in capsule support, the skill provides the instructions and local helpers needed to work with `.capsule` files. Any agent that supports the Agent Skills specification can gain capsule literacy through that installation. This creates a powerful bootstrapping dynamic: the capsule skill teaches agents about capsules, and capsules carry skills that agents can execute. The skills ecosystem becomes the distribution channel for capsule interoperability. --- ## 5. Capsule Studio Capsule Studio remains a planned direction, but the current working surfaces are more specific: Operator - Demo in `capsule-www` and Capsules.run Operators in `operators`. Operator - Demo is a browser-local workspace for evidence intake, Gemma 4 analysis, open questions, document requests, document updates, recipient envelopes, and downloadable command capsules. Capsules.run Operators is an offline investigative workspace with local Ollama/Gemma, draggable workspace modules, highlight-to-context capture, decision gates, and local export. These are Labs surfaces, not production key-management claims. Browser and local storage are useful for demonstrating the workflow. Real deployment still needs stronger key custody, identity binding, and host policy. Studio can grow out of these surfaces once the file proves its value. It should not precede the evidence that capsules improve continuation, verification, and auditability. Future dynamic view specifications remain a protocol direction, but they must be sandboxed and capability-negotiated before any untrusted capsule UI executes. --- ## 6. Capsule Templates Capsule templates define domain-specific workflows built on the shared capsule protocol. A template is an immutable capsule — called the Original Artifact — that contains a procedure (the plan), embedded skills, output contracts, and an empty surface ready to be filled. When work begins, the template is instantiated into a new session capsule. The template itself is never modified; each use produces an independent session with lineage tracing back to the original. Templates specify required fields and schemas, workflow steps with skill references and dependencies, validation rules, output contracts with required sections and formats, execution permissions, and child capsule behaviors for delegated subtasks. This structure allows organizations to adopt capsules through familiar, repeatable workflows rather than interacting with the protocol directly. A compliance team can distribute a screening template that any AI agent can instantiate and execute. A research group can share a peer review template that produces consistent, auditable review capsules. Templates ensure capsules remain structured and interoperable while allowing different industries to customize workflows for their specific domains. --- ## 7. Capsule Graphs Capsules frequently reference other capsules rather than embedding all context directly. These references form capsule graphs — networks of related artifacts connected through lineage and delegation relationships. A parent capsule can delegate subtasks to child capsules. Each child is a complete, independent capsule with its own plan, skills, event chain, and lifecycle. Children can delegate further, creating arbitrarily deep trees of independently verifiable work units. When a child completes, its results flow back to the parent through absorption events recorded in both chains. This structure allows complex workflows to emerge through networks of independent artifacts rather than through monolithic documents. Capsule graphs enable work to scale while preserving integrity boundaries between artifacts. --- ## 8. Capsule SDK and Developer Interfaces The Capsule SDK surface is now broader than the original architecture draft. JavaScript remains the reference implementation for building, reading, appending to, verifying, encrypting, and packing Capsule v0.6 artifacts. Python has broad test coverage and parity work. Rust is a verifier path. Swift and Kotlin source trees exist, but public claims should stay conservative until compile and parity testing are complete. Core capabilities include building capsules with embedded skills and payloads, reading `program.md`, `agents.md`, manifests, payloads, and event chains, appending events and checkpoints, verifying hash chains and envelope signatures, sealing encrypted capsules for recipients, packing under canonical ZIP rules, and supporting browser validation flows for local and web-based runtimes. The developer surface is intentionally lane-based. The protocol spec, SDK, skills, MCP server, and reference artifacts version independently so adopters can pin only the pieces their harness needs. These interfaces enable AI systems to interpret capsules as machine-readable work artifacts and enable developers to integrate capsule support into their own platforms and automation frameworks. --- ## 9. Capsule Interaction Modes Capsules support several modes of interaction depending on their purpose. In exploration mode, users query capsules conversationally to understand their contents. In execution mode, capsules run structured workflows with defined steps and approvals. Delegation mode allows capsules to spawn child capsules to perform subtasks. Validation mode enables capsules to verify their integrity and event history. In continuation mode, actors resume work from the last recorded state, picking up exactly where the previous participant left off. These interaction modes allow capsules to function as both content artifacts and workflow engines. --- ## 10. Maturity Model The Capsule Maturity Model defines six levels measuring work continuity — the ability for a capsule to carry work across boundaries without losing context, integrity, or verifiability. At Level 0, a capsule is a static artifact: a valid container with content that can be stored and read. At Level 1, it becomes structured enough to parse consistently. Level 2 adds cryptographic verification: canonical packaging, hash chains, and envelope signatures. Level 3 adds executable or resumable context through skills, plans, handoff instructions, and host-mediated actions. Level 4 introduces multi-actor continuity through signed events, forks, embedded child capsules, and relay experiments such as MCP-Hydrate. Level 5 targets cross-environment continuity: the same work can move between local, browser, mobile, cloud, and agent runtimes while retaining enough structure to continue correctly. Each level builds on the previous. A capsule's effective maturity is determined by its contents, not the protocol version — a capsule without embedded skills remains Level 3 regardless of which version created it. --- ## 11. Example Applications Several industries contain workflows well suited to capsule-based artifacts. ### Compliance and Risk Screening Capsules provide verifiable audit trails for regulatory workflows such as sanctions screening and due diligence. A compliance capsule can carry embedded screening skills, execute them against declared data sources, record every result in the event chain, and produce a validated report — all within a single portable file that regulators can independently verify. ### Vendor Management Vendors can distribute standardized due diligence capsules to organizations rather than submitting fragmented documents. Template capsules ensure consistency across submissions while preserving each vendor's specific data and history. ### Research Publication Academic papers can be distributed as interactive capsules containing datasets, citations, experiment histories, and embedded analysis skills. Reviewers receive capsules they can inspect, validate, and extend rather than static PDFs. ### Interactive Journalism Articles can become conversational artifacts where readers explore claims, sources, and context. The event chain records how the article was researched and composed, providing transparency into the editorial process. ### Healthcare Context Patient health capsules can consolidate medical history and provider interactions into portable context artifacts. Embedded skills can perform clinical calculations while the event chain maintains a complete record of every assessment. --- ## 12. Future Directions The capsule artifact model introduces a new approach to collaborative infrastructure. Instead of reconstructing context from distributed systems, capsules allow context to travel with the artifact itself. The near-term roadmap focuses on trust infrastructure — cross-organization signature verification, encryption, and federated identity — that will enable capsules to operate across organizational boundaries with verifiable trust. Beyond that, online anchoring and hosted discovery will allow capsules to participate in networked verification and workflow registries. A declarative dynamic UI layer will enable capsules to carry view specifications that hosts render according to their capabilities, allowing rich, domain-specific interfaces while maintaining portability. The adoption of the Agent Skills ecosystem positions capsules within a growing network of interoperable AI tools. As more agents gain skills support, every capsule becomes accessible to a broader set of AI systems without custom integration. The public capsule skill — teaching any agent to understand the protocol — further accelerates this network effect. Capsules represent an early architecture for an emerging category of collaborative infrastructure where work moves fluidly between humans, AI systems, and organizations without losing continuity, context, or trust.