Trinity Lite Tutorial

1. Install

python3 -m pip install trinity-lite

For local source development, clone the repository and run python3 -m pip install -e ..

2. Dispatch a Task

trinity-lite dispatch-auto "implement a parser"

This creates a queued task in the local SQLite bus.

3. Run a Worker

trinity-lite worker codex --once

The default Codex adapter is a mock adapter, so it returns a deterministic result.

4. Read Status

trinity-lite tasks
trinity-lite status <task_id>

5. Run a Review Flow

The optional orchestrator dispatches the primary task, runs the selected worker once, runs a required review once, then runs local verification before accepting:

trinity-lite orchestrate "implement a parser"

It uses the same routes and agent configs as dispatch-auto. The primary task row records route_json, review_task_id, gate_status, verification_json, acceptance_status, acceptance_reason, and accepted_at.

6. Switch to Real Commands

cp examples/agents.command.example.json agents.local.json

Edit agents.local.json for your local tools, then pass it to workers:

trinity-lite worker codex --once --agents agents.local.json

Keep local command config out of git.

7. Route by Capabilities

For arbitrary CLI agents, copy the generic capability examples:

cp examples/agents.generic.example.json agents.local.json
cp examples/routes.capabilities.example.json routes.local.json

Then dispatch with both files:

trinity-lite dispatch-auto "fix the parser bug" \
  --agents agents.local.json \
  --routes routes.local.json

Or run a full primary-plus-review flow:

trinity-lite orchestrate "fix the parser bug" \
  --agents agents.local.json \
  --routes routes.local.json

Trinity Lite will select an agent whose declared capabilities satisfy the route.

8. Optional Runtime Hygiene

For a long-running local install, keep runtime files outside the repository and check them explicitly:

trinity-lite doctor --runtime-root ~/.trinity-lite --retired-port 9797

Skip this step for the default mock demo. It is for installations that maintain a metrics log and retire local helper services over time.