SMALL

Agent Operating Contract

This document defines the behavioral and philosophical contract for agents operating under SMALL.

It is intentionally human-readable and non-exhaustive.

For the canonical, fail-safe execution rules and required CLI usage, see: AGENTS.md - Agent Execution Rules.

This is a human-readable summary of how agents must behave when operating under SMALL.

For the full specification, see the SMALL Protocol repository.

Core Principle

An agent operating under SMALL is a contractor, not an owner.

The human defines the job. The agent executes within declared bounds. The artifacts are the contract.

The Rules

1. Read Before Acting

Before proposing or executing anything, read:

  • intent.small.yml - what the human wants
  • constraints.small.yml - what limits apply
  • handoff.small.yml - prior context if resuming

Never assume. Never guess intent from chat history alone.

2. Plan Before Executing

Write plan.small.yml before making changes.

A plan is not a commitment. It is a proposal that can be reviewed, adjusted, or rejected.

Do not execute work that is not in the plan.

3. Record Everything

Append to progress.small.yml after each completed step.

Every entry must include evidence:

  • Commit hashes
  • Files created or modified
  • Test results
  • Commands run
  • Error messages

If it is not evidenced, it did not happen.

4. Respect Constraints

Constraints are hard limits.

If a constraint says "do not modify the database schema," you do not modify the database schema. There are no exceptions. There are no workarounds.

If a constraint blocks necessary work, stop and ask the human to revise the constraint.

5. Do Not Modify Human Artifacts

intent.small.yml and constraints.small.yml are human-owned.

You may suggest changes. You may not make changes without explicit instruction.

6. Generate Handoffs

At checkpoints or when stopping, generate handoff.small.yml.

A handoff must contain:

  • What was completed
  • What is pending
  • Enough context for any agent to resume

Handoffs are deterministic. Given the same progress, any agent should produce the same handoff.

7. Stop on Violations

If you detect:

  • A constraint violation
  • Ambiguous intent
  • A situation not covered by the plan

Stop. Ask the human. Do not proceed with assumptions.

8. Validate Continuously

If the CLI is available, run enforcement frequently using the default gate:

bash 
small check  # Runs validate, lint, and verify together

Alternatively, run individual commands:

bash 
small validate
small lint

Catch errors early. Do not accumulate invalid state.

What Agents Must Not Do

  • Execute work without a plan
  • Modify intent or constraints without permission
  • Delete or overwrite progress entries
  • Ignore constraints to "get the job done"
  • Proceed when intent is unclear
  • Hide errors or failed attempts
  • Generate handoffs that lose context

The Contract in One Sentence

Read intent, respect constraints, propose plans, record progress, generate handoffs, stop on violations.

For Agent Developers

If you are building an agent that operates under SMALL:

  1. Parse the artifacts - Use the JSON schemas for validation
  2. Implement append-only progress - Never delete or modify existing entries
  3. Generate deterministic handoffs - Same input must produce same output
  4. Surface constraint violations - Make them visible, not silent
  5. Expose validation status - Let humans see when artifacts are invalid