harness-setup

Cross-harness operational lifecycle suite for AI coding agents. Three skills, five prompt-commands, and project templates that make any repository reliable to work in across sessions and across Claude Code, Pi, and oh-my-pi.

What it does

A fresh, context-free session should be able to answer five questions from the repo alone: what is this, how do I run it, how do I verify it, what's done, what's next. This suite makes that true by operationalizing five subsystems:

Subsystem	Job	Artifacts
Instructions	Tell the agent what to do and in what order	AGENTS.md, CLAUDE.md, docs/
State	Track what's done, in progress, and next	progress.md, feature_list.json, decisions.md
Verification	Prove work is done; only a passing check counts as evidence	init.ps1/init.sh, feature_list.json evidence
Scope	Constrain to one feature at a time; no overreach	feature_list.json (WIP=1)
Lifecycle	Initialize at start, hand off + clean up at end	session-start, session-wrap, session-handoff.md, clean-state-checklist.md

The lifecycle

   ┌─────────────┐
   │ harness-init │  (once per repo)
   │  stamp files │  AGENTS.md · progress.md · feature_list.json · decisions.md
   │  seed scope  │  session-handoff.md · clean-state-checklist.md · init.ps1/.sh
   │  baseline ✔  │  → cold-start test passes
   └──────┬──────┘
          │
          v
   ┌─────────────┐      next session
   │ session-start│ <───────────────────────────┐
   │  orient from │  pwd · progress · features ·  │
   │  repo files  │  handoff · git log · init/verify
   │  fix baseline│  pick ONE feature, confirm    │
   └──────┬──────┘                                │
          │                                       │
          v                                       │
   ┌─────────────┐                                │
   │    work      │  implement the one feature     │
   │  (WIP = 1)   │  run its verification          │
   │  verify ✔    │  evidence, not confidence      │
   └──────┬──────┘                                │
          │                                       │
          v                                       │
   ┌─────────────┐                                │
   │ session-wrap │  verify · update state ·       │
   │  handoff +   │  write session-handoff.md ·    │
   │  clean state │  clean-state check · commit    │
   └──────┬──────┘                                │
          │                                       │
          └─────────► (reset / new session) ──────┘

Install

Option A: Installer script

# Unix/macOS
./install/install.sh

# Windows PowerShell
.\install\install.ps1

# With symlinks/junctions instead of copies (optional)
./install/install.sh --link
.\install\install.ps1 -Link

The installer detects which harness directories exist (~/.claude, ~/.pi, ~/.omp) and copies skills + prompt-commands into each. It is idempotent — safe to re-run to update.

Option B: Pi install

pi install /path/to/harness-setup

This works because package.json includes "keywords": ["pi-package"] and "pi": { "skills": [...], "prompts": [...] }.

Option C: Manual copy

Copy whichever directories you need:

From	To (Claude Code)	To (Pi)	To (oh-my-pi)
skills/*	~/.claude/skills/	~/.pi/agent/skills/	~/.omp/agent/skills/
prompts/*	~/.claude/commands/	~/.pi/agent/prompts/	~/.omp/agent/commands/

Skills

harness-init

Trigger: "make this repo agent-ready", "set up the harness", starting serious work in a repo with no AGENTS.md / progress.md / feature_list.json.

One-time setup. Inspects the repo, stamps lifecycle files (AGENTS.md, CLAUDE.md, progress.md, feature_list.json, decisions.md, session-handoff.md, clean-state-checklist.md, init.ps1/init.sh), detects install/verify/start commands, seeds the feature list from the project goal, offers to add CI/devcontainer/quality scaffolding when missing, makes a baseline commit, and runs a cold-start test.

session-start

Trigger: "let's continue", "pick up where we left off", "what's next", "resume".

The start-of-session ritual. Reads progress.md, feature_list.json, session-handoff.md, checks git history, runs the init/verify path, fixes a broken baseline before anything else, then picks exactly one highest-priority feature and confirms the next step. If no harness exists, recommends running harness-init.

session-wrap

Trigger: "wrap up", "stop here", "done for now", or when context is running low.

The end-of-session ritual. Runs verification, applies the definition-of-done gate, updates feature_list.json and progress.md, records decisions, writes session-handoff.md, runs the clean-state checklist, and commits a safe restart point. If triggered by low context, writes the handoff artifact first.

Prompt-commands

Available as /command-name in Claude Code and oh-my-pi, or via the Pi prompts directory.

Command	What it does
/init-harness	Triggers harness-init with an optional project goal
/resume-work	Triggers the session-start ritual
/wrap-session	Triggers the session-wrap ritual
/context-low	Emergency handoff — writes session-handoff.md immediately for a clean reset
/review-gate	Skeptical six-dimension evaluation before accepting work as done

Templates

harness-init stamps these files into the target project root:

Template	Purpose
AGENTS.md	Routing instruction file — the map, not the manual
CLAUDE.md	One-line pointer to AGENTS.md
progress.md	Durable session log + Current Verified State
feature_list.json	Machine-readable scope, one feature in_progress at a time
decisions.md	Why non-obvious choices were made (survives context resets)
session-handoff.md	Compact "where we are / what's next" for the next session
clean-state-checklist.md	End-of-session gate
init.ps1 / init.sh	Standardized boot + verify (Windows + unix)

And optionally scaffolds project infrastructure:

Template	Purpose
ci/ci-workflow.yml	Lint + typecheck + test on push
ci/commit-lint.yml	Conventional commit enforcement
ci/changelog-check.yml	Changelog format validation
devcontainer/devcontainer.json	VS Code / Codespaces ready
quality/thresholds.md	File/function/nesting guidelines

Docs

Progressive-disclosure references. Not required for the skills to function, but linked from them for the "why."

Doc	What it explains
harness-model.md	The five subsystems — why each matters and what happens without it
the-lifecycle.md	The full loop diagram: init → start → work → wrap → reset
context-management.md	Routing files, progressive disclosure, sub-agents, reset vs. compaction
method-map.md	Failure mode → smallest fix → which artifact addresses it
project-scaffolding.md	Why CI, devcontainers, and quality thresholds help agents

Design rules

• Keep the root instruction file a map, not a manual (routing + invariants; details in docs/).
• Repo is the memory. Handoff = committed files, never a chat summary.
• Verification is silent on success, verbose on failure.
• One feature in_progress. Done = behavior verified, not code written.
• Prefer the smallest artifact that fixes the observed failure mode (the method-map principle).
• Skills stay short and self-contained; name == directory; description always present.
• Markdown only — no TypeScript, no build step. One source of truth works across all three harnesses.

Cross-harness compatibility

Mechanism	Claude Code	Pi	oh-my-pi
Skills	~/.claude/skills/	~/.pi/agent/skills/	~/.omp/agent/skills/
Prompt-commands	~/.claude/commands/ → /name	~/.pi/agent/prompts/ → /name	~/.omp/agent/commands/ → /name

All three harnesses implement the same Agent Skills standard. A single SKILL.md with name + description frontmatter works unmodified in all three.

Method map

When you see a specific failure, add the smallest artifact that addresses it:

Failure mode	Primary fix	Artifact
Cold-start confusion	Make the repo the system of record	progress.md (+ harness-init)
Scope sprawl	Restrict active scope to one feature	feature_list.json (WIP=1)
Premature completion	Bind completion to recorded evidence	clean-state-checklist.md, the verify path
Fragile startup	Standardize setup + verification	init.ps1 / init.sh
Weak handoff	End with an explicit handoff	session-handoff.md (via session-wrap)
Lost rationale	Persist the "why" outside chat	decisions.md
Context rot	Route + progressively disclose	AGENTS.md as a map, docs/
Subjective review	Score against fixed categories	/review-gate
No clean exit	Make clean state part of "done"	clean-state-checklist.md

References

• Anthropic: Effective harnesses for long-running agents
• Anthropic: Harness design for long-running application development
• OpenAI: Harness engineering
• HumanLayer: Skill issue — harness engineering for coding agents
• Learn Harness Engineering — lecture course + projects
• Awesome Harness Engineering

License

MIT