← Back to TAHOE

SKILL.md

v1.1.0 · 7151 B · text/markdown

---
name: tahoe
description: Drive TAHOE — Task-Aware Language Harness for Orchestrated Execution (github.com/AlexKay28/tahoe), a human-readable agent DSL with canonical parsing, sealed tamper-evident runs and an event-sourced coordinator. Load BEFORE writing a program.think, sealing or executing a run, using the tahoe CLI (lint, seal, run, resume, status, events, audit, learn, bench, next, submit, ready, claim, renew), or wiring agents to it via the sealed protocol. Triggers - tahoe, program.think, sealed run, seal.txt, WORKLOG.md, evaluation.json, tikhon, atlas (legacy names), запусти tahoe, запечатай прогон, протокол прогона. Do NOT use for publishing skills to the registry - that is `ahood`; for authoring SKILL.md files - `agentic-evolution`; for orchestrating opencode workers - `cli-multiagentic-work`.
---

# TAHOE — Task-Aware Language Harness for Orchestrated Execution

> **Author:** alexkay28 · **Repo:** https://github.com/AlexKay28/tahoe (issues, docs/spec/, CHANGELOG)
> `skill-origin: alexkay/tahoe` — keep this marker so copies stay findable.
> Formerly `tikhon`, briefly `ATLAS` — historical runs under those names are valid evidence, not typos.

A language where an agent's plan is a *program*: canonical parsing, a sealed SHA-256
digest computed before any work, event-sourced execution, and an audit trail that makes
the run — not the model's vibes — the artifact of record.

## Install

```bash
git clone https://github.com/AlexKay28/tahoe && cd tahoe
pip install -e .            # provides the `tahoe` CLI (not on PyPI)
python -m pytest -q         # full suite; green is the contract
```

Dev loop on a clone: `PYTHONPATH=src python3 -m tahoe …` — an installed `tikhon`/old
console script from a previous checkout goes stale silently; always prefer the module
invocation from the repo root (verified repeatedly across sprints 1–2).

## The sealed protocol (the core loop, in order)

1. Write `demo/runs/<run-id>/program.think` — plan the work using ONLY registered commands.
2. `tahoe lint` it. Fix until valid.
3. `tahoe seal program.think > seal.txt` — **BEFORE any source edit**. Never touch
   program.think afterwards; the digest is the run's identity.
4. Execute (worker/coordinator), maintaining `WORKLOG.md` per step: Status / Inputs /
   Actions / Outputs / Evidence.
5. Finish with `solution.md` + `evaluation.json` (task, run_id, seal, terminal_status,
   steps_planned, steps_executed, acceptance map, unresolved, protocol_deviations).
6. **Anything failed or behaved strangely during the run — snap it before the session
   ends**: `ahood snap create` (tags `tahoe`) with what failed, the exact error text and
   the workaround. These snaps are the raw material this skill's Traps section is
   harvested from; a trap left unsnapped will be rediscovered the hard way.

`demo/runs/**` is **evidence, immutable**: never edit, rename or "fix" a historical run —
including its legacy-name mentions. Re-verify anytime: every `seal.txt` must reproduce
byte-identically via `tahoe seal` (42/42 as of sprint 2, 2026-09-12). The digest is
package-name-independent — two full renames (tikhon→ATLAS→TAHOE) left every historical
seal verifying, so rebranding is self-proving (45+ runs, zero drift, 2026-09-12).
Rename passes must grep-gate live code only (`tests/test_branding.py` pattern) and
leave legacy names in DBs and demo dirs alone.

## Multi-worker conventions (45+ sealed runs, sprints 1–2)

- **Documentation seal → run seal**: post a SEALED resolution plan as a comment on each
  issue, then the implementing worker copies that program into its run dir, updates only
  stale path strings, re-seals and executes. The plan cannot drift from the record.
- **Per-merge verification gate**: full pytest suite + all-seal sweep +
  `git status --porcelain` checked against the worker's owned-files contract. Passing
  self-tests is NOT sufficient — read tests against the issue spec (caught
  invented-contract drift twice).
- **Isolation**: one git worktree per worker, one branch per issue; keep `cli.py` owned
  by exactly one worker per wave — merge conflicts only where file ownership overlaps.

## CLI

| Command | Purpose |
|---|---|
| `lint` / `seal` | validate / canonical sha256 digest (`--check` verifies a file against a seal; exit 4 = drifted) |
| `run` / `resume` | execute a sealed program / recover a crashed run (budgets via flags) |
| `status` / `events` / `audit` | lifecycle, ordered event log, invariant audit — all `--json`-capable |
| `next` / `submit` / `ready` / `claim` / `renew` | external-driver bridge (envelopes, claims, heartbeat lease extension) |
| `learn` / `bench` | mine runs into protocol candidates / deterministic benchmark harness |
| exit codes | 0 ok · 1 usage · 2 run failed · 3 audit violations · 4 seal mismatch |

## Language surface

23 registered commands (define, search, fetch, extract, summarize, report, verify,
calculate, check, decompose, hypothesize, compare, rank, challenge, choose, remember,
recall, edit, test, review, solve, prove, delegate), plus: `DONE` gates on a step's own
target, `IF` conditionals, `REVISE/RETIRE`, standalone `CALL protocol.*` child runs,
`KB.*` memory with FTS5 `recall`, `PAR MAX n … BARRIER -> refs`, `SCATTER x IN coll …
GATHER … USING all|any|ranked`, runtime-authored `delegate` plans, ref lists `[E.a, E.b]`.

## Traps (each one cost a real session)

- **`CALL protocol.name(...)` is a standalone line** — no `step.x:` prefix — and must
  pass ALL the protocol's INPUT args (verified in wave 12).
- **`GATHER` must directly follow its `SCATTER` block** (indented body step between);
  anything between them is a parse error (verified in wave 11).
- **`REVISE` must name an earlier node**, never the step's own target (verified in wave 6).
- **DONE supports only its documented operators** — `count()` in DONE is exactly issue
  #36's gap; use `matched(ref, "regex")` meanwhile (hit 2026-09-12 while sealing the
  sprint-2 map).
- **INPUT values are single-line** (#37 in flight) — long single lines are fine, pretty-
  printed JSON is not (hit 2026-09-12).
- **Worker model endpoints cap concurrency** — the internal GLM-5.2 endpoint allows 3
  inflight requests; 7 parallel workers → `Too Many Requests: inflight limit exceeded`
  (verified 2026-09-12, killed a worker).
- **Launching background workers from a tool call that then times out kills them** — the
  timeout's process-group kill ignores nohup. Launch calls must return instantly; poll
  separately (verified 2026-09-12, killed five workers).
- **Merging an uncommitted branch is a silent EMPTY merge** — workers never commit
  (contract); the orchestrator must commit each worktree's branch scope BEFORE
  `git merge` (bit once 2026-09-12; the suite count exposed it).

## Digest versions

Default seals are v1 canonical form. Issue #32 (in flight) adds a v2 digest that
canonicalizes IF-conditions and barrier spelling — historical v1 seals must keep
verifying; treat any claim about v2 as UNKNOWN until it lands and the seal sweep goes
green again.