AI agents can claim work is done. Trinity makes them prove it.
You do not memorize Trinity commands. You remember your AI agent.
Open this folder in Claude Code, Cursor, Codex, Gemini, or Warp. Tell
the agent the work in plain language. It reads CLAUDE.md / AGENTS.md
/ GEMINI.md / WARP.md and runs the protocol.
Your job: state intent, and approve when Trinity asks. The agent's job: know the rituals, produce evidence, stop when a gate refuses.
Trinity is a CLI-first control layer for those agents. It coordinates vendor AI harnesses, verifies their work, and records decisions as auditable artifacts.
Core rule:
No artifact = no trust.
No verification = no completion.
No authority = no transition.
AI coding agents are powerful, but their claims are not reliable evidence.
They may say:
- tests pass, but no test artifact exists
- a bug is fixed, but no reproduction was verified
- a deploy is safe, but no rollback path was recorded
- a file was changed correctly, but no diff was inspected
Trinity turns AI-assisted work into an evidence-driven workflow:
Human intent
|
v
AI proposes / executes within scope
|
v
Trinity captures artifacts
|
v
Verifier checks evidence
|
v
Policy / Human decides promotion
Read the one-page explanation: WHY_TRINITY.md
Before Trinity:
User: Fix the login bug.
Agent: Done. Tests pass.
Problem: there is no trustworthy evidence.
After Trinity:
User: Fix the login bug.
Trinity requires:
1. a scoped plan
2. bounded execution
3. diff and test artifacts
4. verifier verdict
5. explicit promotion authority
If the agent cannot produce the artifact, the work cannot be promoted.
New here? Clone the repo, open it in your AI coding agent, and say what you want done. Optional hands-on kernel tour:
docs/quickstart.md. Ritual names are for the agent, not a human cheat sheet.
- Architecture generation: Trinity v2
- Core freeze: v1.0 (operator TAG 2026-09-14,
CORE-v1.0-TAGGED-0294) - Kernel public docs: stamp
KERNEL-GITHUB-V1-0295 - License: Apache-2.0
- Release evidence:
docs/releases/TRINITY_CORE_V1_0_FROZEN.md - First public runtime line (historical):
docs/releases/TRINITY_V0_1_0_RELEASE_EVIDENCE.md
Behavioral proof, not just test count:
- State machine safety
- Gate enforcement
- Audit chain integrity
- Tool contract compliance
- Verifier verdict behavior
- Operator command sequence
- Human approval requirements for risky transitions
This checkout is the kernel. It is not the development monorepo, the
session archive, or the live audit chain. Export with
docs/GITHUB_EXPORT.md before a public push.
Human Owner
|
v
Trinity Control Layer
|
+-- Intent / Scope / Constraints
+-- Session capsule + state machine
+-- Bounded AI execution
+-- Artifact capture
+-- Verifier + policy gates
+-- Audit chain
|
v
Promotion only with evidence
Worker layer:
Claude Code / Codex / Cursor / Gemini
|
v
Vendor AI proposes and executes
Trinity does not replace the agent. Trinity governs the work.
1. Clone this repo
2. Open the folder in your AI coding agent
3. Say the task in your own words
4. Approve gates when the agent asks
You should not need sss / vvv / nnn in your head. If the agent is
lost, point it at this README. If you want to watch the kernel by hand,
use docs/quickstart.md.
Run the CLI test suite:
python3 -m pytest .ai/cli/tests -qThese short codes are the agent protocol. They are not the first thing a human should learn.
sss -> vvv -> nnn -> gogogo -> rrr -> close
ddd is optional (deploy decision). It is not on the happy path.
| Ritual | Purpose |
|---|---|
sss |
Start a session capsule and initial state |
vvv |
Define goal, scope, constraints, acceptance, risk |
nnn |
Normalize into plan, steps, and artifacts |
gogogo |
Explicit execution gate |
rrr |
Retro and memory handoff through memory-cli index |
close |
Close the session with explicit final state |
ddd |
Optional deploy decision (VERIFIED → PROMOTED → DEPLOYED) |
Reference: docs/RITUALS.md
Start here:
- Why Trinity:
WHY_TRINITY.md - Origin story:
docs/ORIGIN.md - Ritual reference:
docs/RITUALS.md - Getting started:
docs/GETTING_STARTED.md - Architecture:
docs/ARCHITECTURE.md - Storage taxonomy:
docs/STORAGE_TAXONOMY.md - Version lineage:
docs/VERSION_LINEAGE.md - GitHub-safe export:
docs/GITHUB_EXPORT.md
Operator guide: docs/operator-guide-en/00_README.md
Specs:
<kernel-root>/
├── AGENTS.md # Generic agent entrypoint
├── CLAUDE.md # Claude Code entrypoint
├── GEMINI.md # Gemini CLI entrypoint
├── WARP.md # Warp entrypoint
├── .ai/ # Trinity kernel
│ ├── cli/ # Python CLI kernel commands
│ ├── sessions/ # Session capsules (empty in a public export)
│ └── audit/ # Hash-chain audit log (genesis-only in a public export)
└── docs/
├── specs/ # Canonical implementation specs and contracts
├── releases/ # v1.0 freeze stamp + historical v0.1.0 evidence
└── operator-guide-en/
This repository previously contained earlier experimental Trinity Protocol
materials. Core v1.0 is the operator freeze. v0.1.0 remains the first
public runtime line and is not rewritten.
Version story:
Trinity Protocol v2 = architecture / constitution generation
Core v1.0 = operator TAG / PRODUCTION READY / FROZEN
Runtime v0.1.0 = first public executable runtime line (historical)
Tool Contract = v1.0 freeze candidate, v1.1 draft working spec
For the Trinity ritual flow, rrr delegates to memory-cli index.
memory-cli learn appears in legacy/spec materials as a historical or
non-ritual memory surface and must not be used by rrr.