This spec is intentionally boring on purpose: deterministic primitives scale. Chaos doesn't.

Conceptual Primitives

SMALL stands for Schema, Manifest, Artifact, Lineage, Lifecycle. These five conceptual primitives form the protocol's intellectual foundation:

Schema

Defines the structure and validation rules for all data. Schemas are the contracts that govern what is valid. Every artifact conforms to a schema. Validation is non-optional.

Manifest

Declares what exists and what is intended. The manifest describes the state of the world: what artifacts exist, what goals are declared, what constraints apply. It is the source of truth for project intent.

Artifact

A concrete, versioned output governed by schemas. Artifacts are the tangible products of work-files, commits, test results. They are addressable, verifiable, and immutable once finalized.

Lineage

Tracks provenance and dependencies between artifacts. Lineage answers: where did this come from? What depended on it? Lineage enables auditability and reproducibility.

Lifecycle

Governs state transitions and workflow phases. Lifecycle defines the valid states an artifact can be in and the transitions between them: pending, in_progress, completed, blocked, etc.

Execution Artifacts (v1.0.0)

In v1.0.0, the SMALL conceptual model is operationalized via five canonical YAML files stored in .small/. These are concrete execution state-not a renaming of the acronym primitives.

Each execution artifact is governed by a JSON Schema and used by agents and CLIs to manage workflow state.

Intent

intent.small.yml declares the goal of the work. Owned by humans.

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

Intent answers: what are we trying to achieve and how will we know we succeeded?

Constraints

constraints.small.yml declares 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: "no-new-deps"
    rule: "Do not add new dependencies without approval"
    severity: "error"
  - id: "require-tests"
    rule: "All changes must include tests"
    severity: "error"

Constraints answer: what must the agent NOT do, regardless of how it approaches the goal?

Plan

plan.small.yml defines the proposed execution approach. Owned by agents.

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"
    depends_on: ["task-1"]
  - id: "task-3"
    title: "Add route protection"
    status: "pending"
    depends_on: ["task-1"]
  - id: "task-4"
    title: "Write tests"
    status: "pending"
    depends_on: ["task-2", "task-3"]

Plans are disposable. They may be regenerated or replaced at any time. What matters is progress.

Progress

progress.small.yml 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"
  - timestamp: "2025-01-15T10:30:00.456789012Z"
    task_id: "task-2"
    status: "in_progress"
    summary: "Starting login endpoint implementation"

Progress entries are immutable. Once written, they cannot be deleted or modified. Timestamps must be strictly increasing.

Handoff

handoff.small.yml provides a deterministic resume point. Shared between humans and agents.

small_version: "1.0.0"
owner: "agent"
summary: "Auth middleware complete. Login endpoint in progress."
replayId:
  value: "a1b2c3d4e5f6789..."
  source: "auto"
current_task: "task-2"
completed_tasks: ["task-1"]
pending_tasks: ["task-3", "task-4"]

Handoff is the only valid resume entrypoint. Agents MUST read handoff.small.yml first when resuming work.

Canonical Relationships

flowchart LR
  subgraph Human-Owned
    A[Intent] --> C[Plan]
    B[Constraints] --> C
  end

  C --> D[Progress]
  D --> E[Handoff]
  E -.-> C

Intent and constraints inform the plan. The plan drives progress. Progress feeds into handoff. Handoff enables resumption.

Ownership Rules

Design Guarantees

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