The harness a step-by-step guide v0.1.0 · alpha

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.

analyze→plan→implement→review→frozen spec

Three rules hold the whole thing up:

Work lives in a spec pack — a folder under 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

NeedWhyCheck
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 --global

You 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.

Why a script and not 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.
Node 22+ is the floor and it is real: the CLI runs from compiled JavaScript (not TypeScript source), verified on both 22 and 24. Uninstall: 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 harness

You 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:

ModeMeaning
createthe destination is absent
samebytes already match — nothing to do
refusediffers and no --force — nothing is written, exit 3
updatediffers and --force is set
skipno 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 --yes

Know what landed where

SurfaceSkillsAgentHooks
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 --remove

Removes 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.

Re-running the installer is safe. Matching files read same; nothing duplicates. To converge drift after editing skills in the harness source, add --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-wave

A 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.

Any time, see the standing picture: 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 pending

The 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.

The write guard runs alongside: edits into machine-managed trees (the corpus goldens, generated wiki code pages) are refused with the reason. Hand edits there fight the engines — the guard makes the fight loud. HARNESS_ALLOW_MACHINE_EDITS=1 overrides when you truly mean it.

09Command reference

treadle do — the loop plane

CommandWhat it does
do init <packDir>birth a pack (--title, --why)
do add question|decision|taskstage 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

CommandWhat 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|resolvethe 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

FlagMeaning
--agent, --scopesurface and level (project | global)
--skills, --no-agents, --no-hookscomponent choice
--dry-run, --jsoninspect the plan; machine form (exit 3 on refuses)
--forceoverwrite drift; remove exactly the listed leftovers
--yesconfirm writes outside the repo (global scope)
--removedelete exactly the recorded install

10The trust rules

11Troubleshooting

SymptomCause 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

TermPlain meaning
packone wave of work: a folder with the spec JSON and its artifacts
specpack/0.3the JSON format the machine writes and reads
stagewhere a pack is: awaiting_owner → planning → in_progress → in_review → delivered
evidence rowa recorded run: task, result, command, exit code, revision, claim
claimwho acted: human:owner or agent:<name>
bundlethe wiki directory the knowledge plane reads
anchora citation to a real location — path and line, never memory
freshness stampwhich commit the wiki last saw; stale means re-stamp
findings ledgerwhere normative claims wait for a human yes or no
red-formanthe adversarial reviewer: assumes the work is wrong, tags findings BLOCKER / DEFECT / SMELL with evidence

Shared background app

After building and installing the CLI (Node 22 or newer), run treadle start serve and open its reported browser address. On native Windows use ./install.ps1; on Linux/macOS use ./install.sh.

treadle project connect /absolute/path/to/project
treadle status serve
treadle context --workspace /absolute/path/to/project --json
treadle stop serve

Project harness installation for Codex, Claude or pi ensures the service and enrolls the explicit workspace after successful wiring. Reload and trust the host hooks. Closing a session leaves the app running; after a stop, the next session event restarts it. Global installation and no-hooks mode require an explicit project connect.

Generate native artifacts with treadle package harness --agent claude|codex|pi --out /absolute/new/directory, selecting one agent. Choose native or compatibility wiring for each host. The artifact points to the local runtime; regenerate if it moves. Codex IDE plugin availability differs from CLI/desktop; inactive hooks use manual connect/context. Cross-platform source support does not itself establish native host witnesses.

Current source setup and clone recovery — 2026-10-12

The source installers now select main by default. The private repository root supports frozen pnpm installation through a shared setup helper; dependencies and builds remain in the nested workspace. Historical examples above retain their original commands. Use the current README for installation.

corepack pnpm install --frozen-lockfile
corepack pnpm run setup

Choose either root setup command. Installers also link the CLI globally. Target-project initialization uses that installed CLI and does not install the application's dependencies. Local hook scripts and runtime pointers need initialization on each machine after cloning.

wukong init harness --agent copilot --scope project --hooks-only --no-agents --root .

This repair preserves project guides, agents, and skills. Full init keeps its backup safeguards; use no-project-guide to preserve instructions during full component installation. Reload Copilot from the project root after init.