Skip to content

Latest commit

 

History

History
216 lines (166 loc) · 6.3 KB

quickstart.md

File metadata and controls

216 lines (166 loc) · 6.3 KB

Quickstart — 60 seconds with Trinity

stamp: KERNEL-GITHUB-V1-0295

Goal: run one verified session from this kernel tree, see the audit trail. Time: about a minute of typing, plus thinking time.

Humans do not need this page to start. Open the repo in your AI agent and say the task. This tour is for watching the kernel, or for the agent to follow when you ask it to run the hello-trinity loop.

Before you start

There is no global ai install. From the kernel tree (this checkout) use the bundled launcher. Full install for a linked project lives in docs/GETTING_STARTED.md.

Confirm the launcher:

./.ai/cli/ai lll

lll is a read-only snapshot — git state, active session, recent audit events. If you see a panel, the kernel is wired.

A GitHub clone already has a git baseline. If you are running from a local export folder that is not a git checkout yet, create one before the session:

git init
git add .
git commit -m "Import Trinity kernel"

Hello Trinity — a complete session

The task is deliberately tiny — create a one-line note file — so you can watch the whole governed loop open, execute, verify, and close green in about a minute. Real code sessions run through the exact same loop.

1. Open a session

./.ai/cli/ai sss hello-trinity

This creates a session capsule on disk — a folder with THINK/, DO/, SANDBOX/, and a hash-chained audit log.

2. Clarify the goal (five short questions)

./.ai/cli/ai vvv \
  --answer "1=Create hello/trinity.md containing the line 'Trinity verified this.'" \
  --answer "2=Only the hello/ folder — nothing else" \
  --answer "3=Do not touch anything outside hello/" \
  --answer "4=hello/trinity.md exists and contains that exact line" \
  --answer "5=None — it is a trivial note"

The five questions are Goal, Scope, Constraint, Acceptance, Risk. Trinity refuses to plan until they are answered.

3. Lock in the plan

A plan envelope is just a JSON file — steps, budgets, allowed paths, and acceptance checks. Trinity rejects the envelope on budget breach or missing fields, so nothing silently overruns. A ready-to-run example for this exact task ships at ../examples/plan.json:

For a generic (non-hello-world) starting point, see ../.ai/examples/plan_envelope.min.json.

{
  "goal": "Create a note at hello/trinity.md containing the line 'Trinity verified this.'",
  "estimated_duration_minutes": 5,
  "estimated_iterations": 1,
  "estimated_tool_calls": 3,
  "target": "hello/",
  "allowed_paths": [
    "hello/**"
  ],
  "steps": [
    {
      "n": 1,
      "title": "Create hello/trinity.md containing the line 'Trinity verified this.'",
      "estimate_min": 2,
      "risk": "low"
    }
  ],
  "forbidden_paths": [
    "docs/specs/**",
    ".ai/policies/**",
    ".ai/schemas/**",
    ".ai/audit/**"
  ],
  "acceptance": [
    {
      "id": "A1",
      "description": "the note file exists",
      "command": "test -f hello/trinity.md",
      "required": true,
      "expect_exit": 0
    },
    {
      "id": "A2",
      "description": "it contains the required line (the work actually happened)",
      "command": "grep -q 'Trinity verified this.' hello/trinity.md",
      "required": true,
      "expect_exit": 0
    }
  ]
}

Run it straight from the shipped example — no need to type it out:

./.ai/cli/ai nnn --plan-envelope=examples/plan.json

4. Do the work

The plan describes one step. Do it — in a real session this is the part the coding agent performs:

mkdir -p hello && echo "Trinity verified this." > hello/trinity.md

5. Checkpoint the execution

./.ai/cli/ai gogogo

Each step runs its work, then a verifier evaluates pass-when predicates. A failed predicate stops the chain — the agent cannot declare itself done.

6. Confirm the goal is really yours

Trinity will not let an AI self-certify the goal. Mark the five answers as human-confirmed before you close:

./.ai/cli/ai vvv --confirm 1,2,3,4,5

7. Write the walkthrough

rrr blocks RETRO→DONE with exit 24 unless the current session has operator-authored THINK/RETRO_LESSONS.md (at least 300 characters, two canonical headings, and the session id). The gate is not waived for the tutorial. Fill it from the shipped template:

python3 examples/write_hello_lessons.py

Read the file it prints. Those are the lessons this loop stands behind.

8. Close the loop

./.ai/cli/ai rrr

rrr runs the acceptance gates (the file exists and contains the line), checks the walkthrough, writes the structured retro, and hands lessons to memory-cli. Because the work is proven, the goal is confirmed, and the walkthrough is present, the session reaches DONE.

9. Archive the capsule

./.ai/cli/ai close

What just happened?

One governed loop produced artifacts you can audit at any time:

  • A signed audit chain at .ai/audit/events.ndjson
  • A frozen plan envelope at .state/plan.json
  • Operator lessons at THINK/RETRO_LESSONS.md
  • An acceptance + forbidden-path + walkthrough gate at rrr
  • An archived capsule after close

No step could be skipped, no claim could be self-certified.

Today's commands & coming aliases

Today Coming (alias) Purpose
sss start open a session capsule
vvv verify answer the five clarifying Qs
nnn plan lock in a budgeted plan envelope
gogogo go execute the plan with checkpoints
ddd done human-decided promote + deploy
rrr retro acceptance gates + write retro
lll look read-only state snapshot

The short codes are the canonical entrypoints today. The English aliases ship in a later release; both will resolve to the same underlying command.

Where to go next