First Run Guide

This page answers the questions new users ask within the first five minutes.

If you want the full protocol specification, see SMALL v1.

After `small init`: What to Do Next

Once you run small init, you have a .small/ directory with scaffolded files. When workspace metadata is enabled, you also get workspace.small.yml. Here's the immediate workflow:

Fill in intent and constraints (human responsibility)
- Edit intent.small.yml with your goal and success criteria
- Edit constraints.small.yml with hard limits the agent must respect
Configure workspace metadata (optional but recommended for CI)
- workspace.small.yml declares the workspace kind (repo-root or examples)
- small check fails if workspace metadata is missing or invalid
Ask your agent to propose a plan (agent responsibility)
- The agent reads intent and constraints, then writes plan.small.yml

Validate the structure

bash

small check  # Default enforcement gate: validate + lint + verify

Execute and track progress (agent responsibility)
- Agent works through the plan, recording progress via CLI commands
- Agent runs small checkpoint or small progress add to track work
- Agent generates handoff.small.yml at checkpoints (includes replayId)
Gate before merge
- Run small check as the default enforcement gate. If check fails, the run is not compliant.
- small verify is also valid for CI-specific enforcement (used internally by check).

This cycle repeats until the work is complete or handed off.

Current CLI Semantics (v1.0.0)

Draft and accept flow

Use draft files for human-owned artifacts when you want review before canonical write:

bash

small draft intent --from path/to/intent.small.yml
small draft constraints --from stdin < constraints.small.yml
small accept intent
small accept constraints

small draft <intent|constraints> requires --from (path, stdin, or -).

ReplayId semantics

Bootstrap progress entries (meta/init, meta/accept-*) are valid without replayId.
After plan creation, run identity is persisted in .small/workspace.small.yml as run.replay_id.
Handoff carries replayId metadata for deterministic resume.

Progress mode semantics

Default mode is signal-first.
Set SMALL_PROGRESS_MODE=audit for verbose apply telemetry.

Strict layout semantics (S4)

Under .small/, only canonical root files are allowed.
Ephemeral runtime files belong under .small-cache/.
small check --strict fails if unknown files or subdirectories appear under .small/.

Common Questions

Do I manually write the `.small/` files?

Sometimes. You write intent.small.yml and constraints.small.yml. These define what you want and what limits apply.

The agent writes:

plan.small.yml (proposed approach)
progress.small.yml (execution log)
handoff.small.yml (resume point)

You may also use small init to scaffold all files with valid empty structures.

Does the agent write the files?

Yes, but only certain ones. The agent proposes plans and records progress. It does not modify your intent or constraints without explicit instruction.

Does the agent run the CLI?

Optionally. An agent can invoke CLI commands like small check or small handoff to check correctness. This is recommended but not required.

The CLI is also used directly by developers to scaffold, validate, and lint artifacts.

What if the plan doesn't match the actual work?

Use the reconciliation pattern. If you complete work that differs from the original plan:

Update plan.small.yml to match the actual work that was completed

Record a reconciliation entry:

bash

small progress add --task meta/reconcile-plan --status completed --evidence "Reconciled plan to match completed work"

This keeps the audit trail accurate without deleting or rewriting progress entries.

Entry Protocol for Agents

Before taking action, agents must establish the current state:

Check for existing handoff

bash

cat handoff.small.yml  # Understand prior context

Capture current state

bash

small status --json  # Machine-readable workspace status

For structured full state

bash

small emit --check --workspace root  # Include enforcement results

This ensures:

No assumptions about task state
Accurate resume context
Enforcement visibility before proceeding

The State Model

SMALL defines a clear division of labor:

Responsibility	Owner
Declare intent	Human
Define constraints	Human
Propose plan	Agent
Execute work	Agent
Record progress	Agent
Generate handoff	Agent or CLI
Validate artifacts	CLI
Enforce invariants	CLI

This separation ensures:

Humans own the "what" and "why"
Agents operate within declared bounds
The CLI enforces correctness
Handoffs enable any agent to resume

The Five Files

A SMALL project contains five artifact types in the .small/ directory.

1. Intent (`intent.small.yml`)

Declares the goal. Written by humans.

yaml

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"

2. Constraints (`constraints.small.yml`)

Declares hard limits. Written by humans.

yaml

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"

3. Plan (`plan.small.yml`)

Proposed approach. Written by agent, reviewed by human.

yaml

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"
  - id: "task-3"
    title: "Add route protection"
    status: "pending"
  - id: "task-4"
    title: "Write tests"
    status: "pending"

4. Progress (`progress.small.yml`)

Execution log. Written by agent via CLI only, append-only.

Do not manually construct this file. Use the CLI to append entries:

bash

small progress add --task task-1 --status completed --evidence "Created auth middleware"
small progress add --task task-2 --status completed --evidence "Implemented login endpoint"

The CLI automatically generates RFC3339Nano timestamps in strict monotonic order. Example result:

yaml

small_version: "1.0.0"
owner: "agent"
entries:
  - timestamp: "2025-01-15T10:00:00.000000000Z"
    task_id: "task-1"
    status: "completed"
    evidence: "Created auth middleware"
  - timestamp: "2025-01-15T10:00:01.000000000Z"
    task_id: "task-2"
    status: "completed"
    evidence: "Implemented login endpoint"

5. Handoff (`handoff.small.yml`)

Resume point. Generated by CLI command.

Do not manually construct this file. Generate it with:

bash

small handoff --summary "Auth middleware and login endpoint complete. Route protection pending."

The CLI automatically computes replayId and includes all necessary resume context:

yaml

small_version: "1.0.0"
owner: "agent"
summary: "Auth middleware and login endpoint complete. Route protection pending."
replayId:
  value: "a1b2c3d4e5f6...64-character-sha256-hash..."
  source: "auto"
links: []

Starter Prompt for Agents

text

You are an AI agent working in a repository that uses SMALL Protocol.

You MUST follow the AGENTS.md - Agent Execution Rules exactly.

Rules:
- Do not assume chat memory.
- Do not invent tasks, timestamps, or state.
- Do not manually edit .small files.
- Do not mark tasks complete except via `small checkpoint`.
- Do not generate a handoff unless `small check --strict` passes.

At the start of every response that involves work:
1. Read AGENTS.md - Agent Execution Rules in full.
2. Read all existing `.small/*.yml` files.
3. Run:
   - `small status --json`
   - `small check --strict`

Then operate strictly using the Ralph loop defined in AGENTS.md:
- refresh state
- select a pending task
- add progress evidence
- apply bounded commands
- checkpoint completion or blockage
- enforce strict check
- handoff when stopping

If intent or constraints are missing or unclear, stop and block the task.
If strict check fails, fix the workspace before continuing.
If you cannot proceed safely, checkpoint as blocked and hand off.

A run is only complete when:
- all tasks are checkpointed
- strict check passes
- a handoff is generated

Minimal Setup

bash

# Initialize SMALL in your project
small init

# Edit intent and constraints
# (use your editor)

# Validate structure
small validate

# Start agent session with the starter prompt above

Next Steps

Agent Operating Contract - Read this first (behavioral and philosophical contract)
AGENTS.md - Agent Execution Rules - Required for execution (canonical, fail-safe rules)
Reference Workflow - Standard execution flow
How to Use SMALL - Full CLI and workflow documentation
SMALL v1 Specification - Complete protocol specification

First Run Guide

After small init: What to Do Next

Current CLI Semantics (v1.0.0)

Draft and accept flow

ReplayId semantics

Progress mode semantics

Strict layout semantics (S4)

Common Questions

Do I manually write the .small/ files?

Does the agent write the files?

Does the agent run the CLI?

What if the plan doesn't match the actual work?

Entry Protocol for Agents

The State Model

The Five Files

1. Intent (intent.small.yml)

2. Constraints (constraints.small.yml)

3. Plan (plan.small.yml)

4. Progress (progress.small.yml)

5. Handoff (handoff.small.yml)

Starter Prompt for Agents

Minimal Setup

Next Steps

After `small init`: What to Do Next

Do I manually write the `.small/` files?

1. Intent (`intent.small.yml`)

2. Constraints (`constraints.small.yml`)

3. Plan (`plan.small.yml`)

4. Progress (`progress.small.yml`)

5. Handoff (`handoff.small.yml`)