SMALL (Schema, Manifest, Artifact, Lineage, Lifecycle) is a protocol for durable, agent-legible project state.

Conceptual Model

The SMALL acronym defines five conceptual primitives that form the protocol's intellectual foundation:

• Schema - Defines the structure and validation rules for all data
• Manifest - Declares what exists and what is intended
• Artifact - Concrete, versioned output governed by schemas
• Lineage - Tracks provenance and dependencies between artifacts
• Lifecycle - Governs state transitions and workflow phases

These primitives are the conceptual building blocks. They are not file names-they are the abstract model that any SMALL implementation must respect.

Execution Artifacts (v1.0.0)

In v1.0.0, the SMALL conceptual model is operationalized via five canonical YAML files stored in a .small/ directory. These execution artifacts implement the SMALL model for agent workflows:

• intent.small.yml - Human-owned project intent/goals (implements Manifest)
• constraints.small.yml - Human-owned constraints/requirements (implements Schema governance)
• plan.small.yml - Agent-owned execution plan (implements Lifecycle)
• progress.small.yml - Agent-owned progress tracking (implements Lineage)
• handoff.small.yml - Shared resume entrypoint (implements Artifact handoff)

These are not a renaming of the SMALL acronym. They are the concrete execution state that implements the abstract SMALL model.

SMALL replaces implicit, opaque agent state with explicit, machine-verifiable contracts. Each artifact is validated against a JSON Schema and has clear ownership rules.

All files follow the pattern: <name>.small.yml

Intent

Intent declares the goal. Owned by humans.

small_version: "1.0.0"
owner: "human"
intent: "Add user authentication to the API"
scope:
  include:
    - "src/auth/**"
  exclude:
    - "src/database/**"
success_criteria:
  - "All auth endpoints return correct status codes"
  - "Tests pass"

Constraints

Constraints declare hard limits. Owned by humans.

small_version: "1.0.0"
owner: "human"
constraints:
  - id: "no-db-changes"
    rule: "Do not modify database schema"
    severity: "error"
  - id: "require-tests"
    rule: "All changes must include tests"
    severity: "error"

Plan

Plan defines the proposed approach. Owned by agents, reviewed by humans.

small_version: "1.0.0"
owner: "agent"
tasks:
  - id: "task-1"
    title: "Create auth middleware"
    status: "pending"
  - id: "task-2"
    title: "Implement login endpoint"
    status: "pending"

Plans are disposable and may be regenerated at any time.

Progress

Progress records execution history. Owned by agents, append-only.

small_version: "1.0.0"
owner: "agent"
entries:
  - timestamp: "2025-01-15T10:00:00.123456789Z"
    task_id: "task-1"
    status: "completed"
    summary: "Created auth middleware"
    evidence:
      - type: "commit"
        ref: "abc123"

Progress entries are immutable once written. New entries are appended.

Handoff

Handoff provides a deterministic resume point. Shared between humans and agents.

small_version: "1.0.0"
owner: "agent"
summary: "Auth middleware complete. Login endpoint pending."
replayId:
  value: "a1b2c3d4e5f6..."
  source: "auto"

Agents resuming work MUST read handoff.small.yml first.

Ownership Rules

Invariants

The following invariants are non-negotiable:

1. Secrets Never Stored

No secrets, API keys, or passwords may be stored in any artifact.

2. Progress Must Be Verifiable

Every progress entry MUST include evidence (commit hash, command output, test result, etc.).

3. Plan is Disposable; Progress is Not

• plan.small.yml may be replaced at any time
• progress.small.yml is append-only and immutable

4. Handoff is the Only Resume Entrypoint

Agents MUST read handoff.small.yml to resume work. Direct reconstruction from plan and progress is not permitted.

5. Version Consistency

All artifacts MUST have small_version: "1.0.0" (exact string match).

Schema Validation

All artifacts validate against JSON Schemas:

• intent.small.yml → intent.schema.json
• constraints.small.yml → constraints.schema.json
• plan.small.yml → plan.schema.json
• progress.small.yml → progress.schema.json
• handoff.small.yml → handoff.schema.json

Schemas are defined using JSON Schema Draft 2020-12.

Design Principles

• Schema-first: validation is non-optional
• Ownership-governed: who can write what is explicit
• Append-only progress: history is immutable
• Deterministic handoff: resumption is reproducible
• Agent-legible: state is explicit, addressable, automatable

For usage guidance, see How to Use SMALL. The authoritative specification text is vendored from small-protocol at vendor/small-protocol/spec/small/v1.0.0/SPEC.md.