Your First Organization

This tutorial builds a two-agent organization from scratch. You’ll write the full TERVOS.yaml, validate it, run it in dev mode, and inspect the audit log. By the end you’ll understand every part of the manifest.

If you want to see something running in under 5 minutes, start with the Quickstart instead.

What We’re Building

A content company with two agents:

• Editor — assigns and reviews work
• Writer — produces content

The Editor manages the Writer. The Writer operates on a $200/month budget.

Step 1 — Create the Manifest

Create a directory and a TERVOS.yaml file:

mkdir my-content-co && cd my-content-co

TERVOS.yaml

schema: tervos/v1
name: "My Content Co"
description: "A two-agent content organization."

governance:
  autonomy_level: supervised

agents:
  editor:
    role: "Editor"
    description: "Assigns writing tasks and reviews completed work for quality."
    model: "claude-sonnet-4-20250514"
    capabilities:
      - content-review
      - task-delegation
    can_delegate_to:
      - writer

  writer:
    role: "Writer"
    description: "Produces first drafts from briefs provided by the Editor."
    model: "claude-sonnet-4-20250514"
    reports_to: editor
    capabilities:
      - long-form-writing
      - research
    budget_monthly_usd: 200

Key fields explained

Field	What it does
schema: tervos/v1	Required. Identifies the manifest version.
governance.autonomy_level	supervised means all actions require at least implicit approval before executing.
can_delegate_to	The Editor can assign tasks to the Writer. The policy engine enforces this.
reports_to	Defines the org hierarchy. The Writer reports to the Editor.
budget_monthly_usd	A per-agent spending cap. The policy engine blocks actions that would exceed it.

See the TERVOS.yaml Manifest Reference for every available field.

Step 2 — Validate

Before running anything, validate the manifest:

tervos validate

Expected output:

✓ TERVOS.yaml is valid
  2 agents defined
  governance: supervised

If you mistype a field or create an invalid reports_to reference, tervos validate will tell you exactly what’s wrong and how to fix it.

Try breaking something deliberately — for example, change reports_to: editor to reports_to: nonexistent and run tervos validate again to see the error format.

Step 3 — Run in Development Mode

tervos start --dev

Development mode:

• Bootstraps both agents immediately with Ed25519 cryptographic identities
• Loads the policy engine with SAFE rules and auto-generated permits from your manifest
• Auto-approves all actions (no manual approval queue)

Expected output:

✓ Organization "My Content Co" bootstrapped
✓ Agent editor activated (did:key:z6Mk...)
✓ Agent writer activated (did:key:z6Mk...)
ℹ  No tasks defined — organization is idle
ℹ  Run tervos audit to inspect the event log

The agents are now active with distinct cryptographic identities. Every action they take will be signed with their DID.

Step 4 — Inspect the Audit Log

tervos audit

You’ll see every event emitted during bootstrap — identity creation, policy evaluation, agent activation:

seq  type                    agent      timestamp
1    org.bootstrapped         —          2026-04-24T05:12:00Z
2    agent.identity.created   editor     2026-04-24T05:12:00Z
3    agent.identity.created   writer     2026-04-24T05:12:00Z
4    policy.loaded            —          2026-04-24T05:12:00Z
5    agent.activated          editor     2026-04-24T05:12:01Z
6    agent.activated          writer     2026-04-24T05:12:01Z

Filter to a specific agent:

tervos audit --agent writer

Filter by event type:

tervos audit --type agent.activated

Step 5 — Add a Third Agent and a Project

Expand the org with a researcher and a real project:

# TERVOS.yaml (updated)
schema: tervos/v1
name: "My Content Co"
description: "A three-agent content organization with active projects."

governance:
  autonomy_level: supervised

agents:
  editor:
    role: "Editor"
    description: "Assigns writing tasks and reviews completed work for quality."
    model: "claude-sonnet-4-20250514"
    capabilities:
      - content-review
      - task-delegation
    can_delegate_to:
      - writer
      - researcher

  researcher:
    role: "Researcher"
    description: "Gathers sources and background material for articles."
    model: "claude-sonnet-4-20250514"
    reports_to: editor
    capabilities:
      - web-research
      - fact-checking
    budget_monthly_usd: 150

  writer:
    role: "Writer"
    description: "Produces first drafts from briefs provided by the Editor."
    model: "claude-sonnet-4-20250514"
    reports_to: editor
    capabilities:
      - long-form-writing
      - research
    budget_monthly_usd: 200

projects:
  launch-article:
    name: "Launch Article"
    description: "Feature article for the product launch."
    owner: editor
    tasks:
      - id: research
        name: "Research competitor landscape"
        assignee: researcher
        priority: high
        acceptance_criteria:
          - "10+ sources cited"
          - "Competitor feature matrix included"

      - id: draft
        name: "Write first draft"
        assignee: writer
        priority: high
        depends_on:
          - research
        acceptance_criteria:
          - "1500+ words"
          - "Includes executive summary"

      - id: review
        name: "Review and edit draft"
        assignee: editor
        priority: medium
        depends_on:
          - draft

Validate the updated manifest:

tervos validate

Run it again:

tervos start --dev

The audit log will now include task assignment events showing the work flowing from Editor → Researcher → Writer → Editor through the policy engine.

What Just Happened

Each run of tervos start --dev demonstrates:

1. Identity layer — every agent gets a unique did:key identity (Ed25519). You can verify authorship of any action by checking the DID.
2. Policy layer — before any action executes, the policy engine checks it against your manifest rules. The can_delegate_to field you wrote is now a hard policy constraint, not a suggestion.
3. Org layer — task lifecycle (queued → assigned → in-progress → completed) is managed by the org runtime.
4. Audit layer — every event is appended to an immutable SQLite event store. tervos audit replays it.

Next Steps

• TERVOS.yaml Manifest Reference — every field, validation rule, and constraint
• CLI Commands — tervos approve, tervos deny, tervos status, and more
• TPS-0.1 Protocol Specification — the full protocol spec defining the event model and policy semantics