SMALL (Schema, Manifest, Artifact, Lineage, Lifecycle) is a formal state protocol that makes AI-assisted work legible, auditable, and resumable by separating durable state from ephemeral execution.
It defines versioned machine-readable artifacts that replace ephemeral chat history with durable project state.
Solo by default. Collaborative by choice. SMALL preserves the state around AI-assisted work so another run, machine, or operator can inspect and resume it.
This 31-second demonstration uses the released small v1.1.0 binary against an existing SMALL-enabled repository. The commands and state transitions are real, not simulated output.
Watch full quality: MP4 · WebM · v1.1.0 release notes
What the demonstration verifies
- strict validation of existing canonical SMALL state;
- explicit migration to the v2.0.0 session profile;
- solo mode as the default;
- session creation and an explicit transition to collaborative mode; and
- a final strict validation pass.
- An agent framework
- A prompt format
- A workflow engine
- A multi-agent system
SMALL is a governance and continuity layer.
| Artifact | Owner | Purpose |
|---|---|---|
intent.small.yml |
Human | Declares what the work is |
constraints.small.yml |
Human | Declares what must not change |
plan.small.yml |
Agent | Proposed execution steps |
progress.small.yml |
Agent | Verified execution evidence |
handoff.small.yml |
System | Serialized resume checkpoint |
Every v1 artifact declares small_version: "1.0.0" and validates against the
v1 schemas. V2 uses a separate JSON session/event layout and its own schemas;
it does not add fields to these v1 YAML files.
This repository implements SMALL Protocol v1.0.0 and the separately versioned v2.0.0 session profile.
- v1.0.0 is stable
- v1 workspaces remain single-writer and are never automatically migrated
- v2 defaults to solo sessions and enables collaboration only through an explicit mode transition
- Both versions have separate authoritative schemas and invariants
The authoritative specification is located at:
spec/small/v1.0.0/
|- SPEC.md
|- schemas/
`- examples/
The session-capable contract is in spec/small/v2.0.0/. See
SMALL 2.0.0 session profile for migration and use.
Want to inspect finished state instead of reading the specification first? Open the examples gallery for a real v2 durable session, the 31-second terminal demonstration, and focused v1 protocol labs.
New to SMALL? Start here:
- Getting Started Guide - Answers "Do I manually type these files?" and walks through the workflow
- Agent Operating Contract - Required reading for AI agents using SMALL
Human workflow: Edit intent.small.yml and constraints.small.yml. The agent handles the rest.
Agent workflow: Read .small/ first, respect ownership rules, validate before claiming success, handoff when stopping.
| Document | Description |
|---|---|
| Getting Started | First-time user guide with examples |
| Agent Operating Contract | Behavioral rules for AI agents |
| CLI Guide | Detailed command reference with error handling |
| Installation | Install via npm global package or curl installer |
| Quick Start | Initialize and validate a SMALL workspace |
| CLI Reference | Command summary table |
| Invariants | Non-negotiable protocol rules |
| Enterprise Integration | Git, CI/CD, and audit patterns |
| Philosophy | Design rationale and non-goals |
| FAQ | Frequently asked questions |
| Execution Model | Single-writer design and concurrency |
| Session Profile v2 | Solo/collaborative sessions, reconciliation, evidence, and migration |
| Examples Gallery | Runnable v1 labs and a complete v2 durable-session workspace |
| Development | Building, testing, and schema updates during development |
| Releasing | Maintainer release process and npm publish policy |
| Docs Sync | Canonical docs sync model, mapping, and verification gates |
Run all commands from your repository root.
# Install
npm i -g @small-protocol/small
small version
# Verify the install works end-to-end
small selftest
# Initialize
small init --intent "My project description"
# Diagnose workspace health (read-only)
small doctor
small health
# Reconstruct task evidence from durable SMALL state
small reconstruct --task task-1
# Validate
small validateInstall alternatives (including curl installer) are documented in Installation.
The CLI supports unmigrated v1.0.0 workspaces and explicit v2.0.0 session-profile workspaces.
See the v1.0.0 release notes for the original launch details.
Pre-built binaries are available on the GitHub Releases page. See Installation for checksum verification and PATH setup.
Apache License 2.0. See LICENSE.