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.
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 llllll 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"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.
./.ai/cli/ai sss hello-trinityThis creates a session capsule on disk — a folder with THINK/,
DO/, SANDBOX/, and a hash-chained audit log.
./.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.
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.jsonThe 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./.ai/cli/ai gogogoEach step runs its work, then a verifier evaluates pass-when predicates. A failed predicate stops the chain — the agent cannot declare itself done.
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,5rrr 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.pyRead the file it prints. Those are the lessons this loop stands behind.
./.ai/cli/ai rrrrrr 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.
./.ai/cli/ai closeOne 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 | 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.
../README.md— the why and the architecture./GETTING_STARTED.md— install + first project./RITUALS.md— full command reference./STORAGE_TAXONOMY.md— where Trinity puts files