KNOWLEDGE FIRST · THEN A TIGHT LOOP
Spec-driven development,
with the machine as the clerk
This guide takes you from an empty terminal to delivered, frozen specs. You will install one CLI, teach it to your coding agent, and run a loop where every claim carries evidence and every write carries a human's name.
01What this is
The harness has two planes. The knowledge plane
(know) turns a repository into an anchored wiki: every
page cites a location, a freshness stamp says when it went stale.
The loop plane (do) carries
work from idea to done through one frozen spec at a time.
Three rules hold the whole thing up:
- Evidence or it did not happen. A status changes only on a recorded, observable result. A task is never "done" because someone said so.
-
Agents propose. Humans accept. Every write path
wants a claim like
human:owneroragent:pi. The machine refuses to guess your intent. - Supersede, never rewrite. New conclusions make new artifacts. History stays as evidence.
docs/specs/<name>/ holding one JSON file plus
markdown artifacts. The JSON (specpack/0.3 format) is
the machine's truth: questions, decisions, tasks, evidence,
verdicts. The machine writes it; humans approve it.
02What you need
| Need | Why | Check |
|---|---|---|
| Node.js 22+ | the CLI runs on it | node --version |
| pnpm 9 | the workspace's package manager | corepack enable then pnpm --version |
| git | packs, recall, worktrees | git --version |
| a coding agent optional | the harness installs its skills into one | pi · Claude Code · Codex · GitHub Copilot |
No API keys. No accounts. Everything runs on your machine.
03Install the CLI
Two paths, both proven in clean-room tests on Node 22 and 24. Pick the one that fits you.
The one-command install (from the repository)
curl -fsSL https://raw.githubusercontent.com/phanijapps/engram-dev/main/install.sh | bash
The script clones the repository to ~/.engram-dev,
installs with the frozen lockfile, builds, and links the CLI
globally. It prints the uninstall commands when it finishes.
The developer install (from your clone)
git clone https://github.com/phanijapps/engram-dev harness
cd harness/treadle
corepack enable
pnpm install
pnpm build
# link the CLI globally — one command, from the cli package
cd packages/cli && pnpm link --globalYou should see the two planes listed: do and know.
Prove the install (the honest way)
treadle do where .
nothing in flight — every spec is delivered or closed.
The command always exits 0 — it is a report, not a
gate. If you see usage help instead, the link missed.
npm i -g <git-url>? The
harness is a pnpm workspace whose packages speak the
workspace: protocol — every npm-based remote
mechanism was tested and recorded broken in the
install-paths spec (five of them, with transcripts). The
script wraps the native mechanism; a registry publish is the
recorded successor that retires the question.
cd ~/.engram-dev/treadle/packages/cli && pnpm unlink --global.
04Install into your coding agent
The harness ships skills (the SDD loop), one agent (red-forman, the adversarial reviewer), and hooks (a write guard and session recall). One command puts them where your agent reads.
Run the installer
treadle init harnessYou will be asked three things:
- Your coding agent — pi · Claude Code · Codex · GitHub Copilot
- Install level — this project, or global (user directories)
- Skills and hooks — space toggles, enter accepts
Read the plan, then let it write
The installer never writes before it shows you exactly what it will do. Every row carries a mode:
| Mode | Meaning |
|---|---|
| create | the destination is absent |
| same | bytes already match — nothing to do |
| refuse | differs and no --force — nothing is written, exit 3 |
| update | differs and --force is set |
| skip | no wiring for this component in the installed manifest |
# preview only — writes nothing
treadle init harness --agent pi --scope project --dry-run
# the same install, scripted (no prompts, ever)
treadle init harness --agent pi --scope project --yesKnow what landed where
| Surface | Skills | Agent | Hooks |
|---|---|---|---|
| pi | .pi/skills/ |
.pi/agents/ |
.pi/extensions/ (real extensions) |
| Claude Code | .claude/skills/ |
.claude/agents/ |
.claude/settings.json (merged, foreign keys kept) |
| Codex | .codex/skills/ |
.codex/agents/ |
a recall prompt + ~/.codex/config.toml notify |
| Copilot | .github/skills/ |
.github/agents/ |
Local Copilot CLI: .github/hooks/wukong.json. Cloud runtime setup is separate. |
Copilot correction, 2026-10-11: GitHub documents Copilot hooks. Wukong now installs local CLI session and prompt hooks. Session hooks supply context; prompt hooks reconnect the local app. Cloud hooks run in a separate sandbox; they cannot reach your desktop's localhost service.
Workspace instructions, 2026-10-12: full project init creates
AGENTS.md with observed commands, repository paths, wiki retrieval,
and SDLC guidance. Existing instructions are preserved byte-for-byte in
AGENTS.backup.md; a differing backup blocks replacement.
Use --no-project-guide to keep root instructions untouched.
Global and --hooks-only installs do not generate the guide.
Removal preserves both documents; --dry-run and --json
are read-only previews for install and removal. The shared search-kb
skill supplies read-only OKF context to the SDLC skills.
Undo it, exactly
treadle init harness --agent pi --scope project --removeRemoves exactly what the recorded install wrote — and refuses any path outside the install roots, even if the state file was edited. Foreign files are never touched.
--force.
05Set up a new project
A project is a git repository plus two directories the loop owns:
docs/specs/ (the packs) and wiki/ (the
knowledge). You will birth the first pack, interview it in the
room, and approve it.
Birth the pack
mkdir my-app && cd my-app && git init
treadle do init docs/specs/first-wave \
--title "First wave — the core loop" \
--why "The user can sign in and out"
The machine writes the born shape:
docs/specs/first-wave/first-wave.json at revision
1. Stage: awaiting_owner.
Ask the questions you cannot answer
The loop is honest about what it does not know. Anything the evidence cannot supply becomes a question for you — asked once, batched:
treadle do add question docs/specs/first-wave \
--id Q-1 --kind choice \
--question "Sessions: server-side store or JWT?" \
--options "server-side" "jwt" \
--default "server-side"Open the room and answer
treadle do interview docs/specs/first-waveA local page opens (localhost, no auth — it is yours). You answer the questions with your owner claim and approve the pack. The room blocks until you do; Ctrl-C escapes.
treadle do answer docs/specs/first-wave --q Q-1 \
--by human:owner --expected-revision 3 --text "server-side"Shape the work: decisions, then tasks
# a decision is a proposal until a human accepts it
treadle do add decision docs/specs/first-wave \
--id D-1 --decision "Sessions live server-side" --because "revocable"
# every task carries an observable verification
treadle do add task docs/specs/first-wave \
--id T-1 --title "The session table" \
--verify-cmd "pnpm test" \
--verify-expect "the session round-trip test passes"
Approve the pack when the shape is right:
treadle do approve docs/specs/first-wave --by human:owner.
06Run the loop
One task at a time. Evidence every time. The cycle:
Take the next ready task
treadle do next docs/specs/first-wave
task T-1 — the session table … (the frozen slice)
next hands out the first task whose dependencies
are done. The task's context is frozen at handout — if the
files it points at move, the task reports drift and waits.
Do the work, then prove it
# …work… then run the task's own verify command, unpiped
pnpm test; echo "exit=$?"Record the evidence
treadle do record docs/specs/first-wave \
--task T-1 --result pass \
--cmd "pnpm test" --exit 0 \
--expected-revision 7 \
--by agent:pi \
--notes "session round-trip green"The record wants the revision you hold. If the pack moved under you, the record refuses — re-read, re-run, re-record. That refusal is the loop protecting you from stale work.
Check alignment, close the wave
treadle do check docs/specs/first-wave
alignment: 0 violation(s), 0 gap(s) — gaps are reported, never guessed
treadle do close docs/specs/first-wave --by human:owner
closed by human:owner: the record is frozen
check proves every requirement is served by a
story, every task satisfies one, no id dangles. Close freezes
the record — history, not rewrite.
treadle do library docs/specs serves a local,
readable surface of every pack — stages, evidence, reviews.
07Use on an existing project
Brownfield work begins with knowledge, not code. You build the wiki first, then run the same loop on top of it.
Scaffold the wiki by hand
mkdir -p wiki/systems wiki/domain
cat > wiki/index.md <<'EOF'
---
okf_version: "0.2"
---
# Systems
* [The build](systems/build.md) - how this repo builds
EOF
Pages carry frontmatter — type,
title, description — and cite their
sources with paths. Quote the version string exactly:
"0.2".
Ground every page in the code
The build-kb skill (installed into your agent in
step 04) walks the repository and writes pages that cite
path locations — never memory. Anchored claims
first:
treadle know search wiki "how does auth work"
treadle know read wiki systems/auth
treadle know validate wiki
conformant: 0 error(s), 0 warning(s)Run the ritual (end every session fresh)
treadle know fingerprints . wiki # record source hashes
treadle know stamp wiki --workspace . # freshness stamp
treadle know anchors wiki --workspace .
treadle know validate wiki
treadle know status wiki --workspace .
freshness: fresh … findings: 0 pendingThe stamp records the commit it saw. Stale after new commits is normal — re-stamp at session close and the wiki tells the truth again.
Then change things through the loop
Birth a pack per change (step 05), ground the analysis in the
wiki (know search before every question to the
owner), and implement against frozen tasks. The wiki and the
specs converge: pages cite code, specs cite pages.
08Recall and the hard gate
The harness remembers where work dangles. Fresh sessions start oriented; "continue" never guesses.
Ask where work stands
treadle do where .
work in flight (2):
checkout in_review next: T-3 rev 12
search in_progress Q open: 1 evidence 2026-10-10
more than one is open: ASK which one continues. never guess.Live packs across roots and git worktrees. Delivered work and the archive are never listed.
Let the session start oriented
The session-recall hook (installed in step 04)
injects that block when a session starts — pi sees it as a
message, Claude Code as context, Codex reads the taught prompt.
And the hard gate: when more than one spec is
open and your first message is continue-shaped
("continue", "go on", "resume"…), the loop
asks which one — enforced on pi and Claude Code,
taught on the rest.
HARNESS_ALLOW_MACHINE_EDITS=1
overrides when you truly mean it.
09Command reference
treadle do — the loop plane
| Command | What it does |
|---|---|
do init <packDir> | birth a pack (--title, --why) |
do add question|decision|task | stage the spec's shape |
do interview <packDir> | serve the room; block until approved |
do answer <packDir> | record an owner answer (--by human:owner) |
do approve <packDir> | the approval act — a human claim |
do next <packDir> | hand out the next ready task |
do record <packDir> | record evidence: task, result, cmd, exit, revision |
do check <packDir> | alignment: violations and gaps, honestly counted |
do status <packDir> | stage, revision, open questions |
do events <packDir> | the pack's event journal |
do where <workspace> | recall: every dangling pack, every worktree |
do library <specsRoot> | the standing local surface of every pack |
do close <packDir> | freeze the record (--by human:owner) |
treadle know — the knowledge plane
| Command | What it does |
|---|---|
know search <bundle> <query…> | weighted search; --type, --tag, --limit |
know read <bundle> <cid> | a concept plus its neighborhood (--depth) |
know validate <bundle> | conformance: errors, warnings, info — never vibes |
know links <bundle> | every cross-link, broken ones named |
know findings list|propose|resolve | the normative ledger — a human accepts or declines |
know fingerprints <ws> <bundle> | record source hashes |
know anchors <bundle> | re-anchor pages to changed sources |
know stamp <bundle> | the freshness stamp |
know status <bundle> | fresh or stale, counts, findings — one screen |
treadle init — the installer
| Flag | Meaning |
|---|---|
--agent, --scope | surface and level (project | global) |
--skills, --no-agents, --no-hooks | component choice |
--dry-run, --json | inspect the plan; machine form (exit 3 on refuses) |
--force | overwrite drift; remove exactly the listed leftovers |
--yes | confirm writes outside the repo (global scope) |
--remove | delete exactly the recorded install |
10The trust rules
- Exit codes are verified, never piped away. A green you did not watch is not green.
-
Claims name their actor.
human:ownerfor your acts,agent:<name>for the machine's. No claim, no write. - The corpus is truth. Behavior changes move golden files deliberately; the diff is reviewed in the commit.
- Advisory signals stay advisory. Trust tiers surface; they never reject. Gaps are reported, never guessed.
11Troubleshooting
| Symptom | Cause and fix |
|---|---|
exit 2, "missing and no TTY" |
The installer needs the flags in scripts. Use the exact command it prints. |
exit 3, rows marked refuse |
Destinations differ. Read the diff, then --force if you mean it. |
pack_refused_to_load |
The JSON shape broke a rule — the message names the file and the reason. Fix the source, never hand-set a stage. |
deliverable stage mismatch |
A stage was hand-set. Delete the stored stage; deriveStage computes it from tasks and questions. |
| record refused — revision moved | The pack changed under you. Re-read it, re-run the verify, record against the revision you now hold. |
wiki non-conformant |
Read the error lines: frontmatter missing, index/log structure, attested shapes. Warnings never block. |
| recall says "unavailable" | The hook could not run the CLI. Check treadle --version; if the link is gone, re-run install.sh or pnpm link --global from treadle/packages/cli. |
12Glossary
| Term | Plain meaning |
|---|---|
| pack | one wave of work: a folder with the spec JSON and its artifacts |
| specpack/0.3 | the JSON format the machine writes and reads |
| stage | where a pack is: awaiting_owner → planning → in_progress → in_review → delivered |
| evidence row | a recorded run: task, result, command, exit code, revision, claim |
| claim | who acted: human:owner or agent:<name> |
| bundle | the wiki directory the knowledge plane reads |
| anchor | a citation to a real location — path and line, never memory |
| freshness stamp | which commit the wiki last saw; stale means re-stamp |
| findings ledger | where normative claims wait for a human yes or no |
| red-forman | the adversarial reviewer: assumes the work is wrong, tags findings BLOCKER / DEFECT / SMELL with evidence |