| name | harness-overview |
| description | Use when the user wants to audit or understand the agent harness itself — its hooks, skills, agents, or commands — or asks "what's in this harness", "how does this harness work", or "harness overview". |
| user-invocable | true |
| tier | util |
Run: `bash "$(git rev-parse --show-toplevel)/bin/harness-update-check"`
- `UPGRADE_AVAILABLE ` → tell the user: "agent-harness is available (you have ). Run `/harness-update` to pull it in." Then continue.
- `JUST_UPGRADED ` → tell the user: "agent-harness upgraded → ." Then continue.
- No output → continue silently.
Quality Harness Overview
Complete documentation of the agent harness — hooks, skills, agents, and commands.
Hosts
HARNESS_HOST (set in hooks/config.sh) selects the workspace host. Three values are supported:
conductor — Conductor parallel-workspace mode (default if ~/conductor/workspaces is detected).claude-code — standalone Claude Code CLI.pi — standalone Pi CLI (https://pi.dev/docs/latest). Uses TypeScript extensions instead of shell hooks.
Hooks (Claude Code / Conductor)
| Hook | Event | Matcher | Purpose |
|---|
config.sh | (sourced) | — | Central project configuration — edit this to customize |
bash-guard.sh | PreToolUse | Bash | Blocks commits on main, --no-verify, destructive ops on source files |
protected-files.sh | PreToolUse | Edit|Write|MultiEdit | Blocks edits to .env, hooks, settings, lockfile |
init.sh | SessionStart | startup | Injects branch, commits, changes, handoff notes |
context-reinject.sh | SessionStart | resume|compact | Lighter context re-injection after compaction |
post-edit.sh | PostToolUse | Edit|Write|MultiEdit | Auto-format + lint (async); DB migration on schema change |
stop.sh | Stop | — | Run tests, typecheck, write handoff, macOS notification |
failure-log.sh | PostToolUseFailure | — | Log failures to .claude/logs/failures.jsonl |
pre-compact.sh | PreCompact | — | Save transcript snapshot before compaction |
config-audit.sh | ConfigChange | — | Log config changes to .claude/logs/config-changes.jsonl |
Pi Extensions (HARNESS_HOST=pi)
Pi targets use TypeScript extensions instead of shell hooks. They live at .pi/extensions/<name>/index.ts and are loaded automatically by .pi/settings.json.
| Extension | Event | Purpose |
|---|
bash-guard | tool_call (bash) | Blocks commits on main, --no-verify, destructive ops |
protected-files | tool_call (edit/write) | Blocks edits to .env, hooks, settings, lockfile |
init | before_agent_start | Injects branch + commits + handoff into the system prompt |
context-reinject | session_compact | Lighter context re-injection after compaction |
post-edit | tool_result (edit/write) | Auto-format + lint (async); DB migration on schema change |
stop | agent_end | Run tests, typecheck, write handoff, macOS notification |
failure-log | tool_result (error) | Log failures to .pi/logs/failures.jsonl |
pre-compact | session_before_compact | Save transcript snapshot before compaction |
task-tool | (registered tool) | Dispatch sub-agents (replaces Claude Code's Task tool) |
config-audit is not ported (Pi has no ConfigChange event). conductor-context is not applicable (Pi doesn't compose with Conductor in v1).
Skills
Process & Workflow
| Skill | Purpose |
|---|
weekly-goals/ | Load current week's goals, guard capacity, align work to priorities |
demo-script/ | Generate customer-story demo scripts for the current week |
plan-sprint/ | Break weekly goals into executable project plans |
deep-plan/ | Plan complex multi-system workstreams with architecture analysis |
ad-hoc-plan/ | Quick plan for a single mid-sprint task |
build-plan/ | Execute a sprint plan autonomously end-to-end |
ship/ | Full shipping pipeline (test → lint → commit → push → PR) |
sync/ | Switch back to main and pull latest |
worktree/ | Git worktree management for parallel work |
harness-update/ | Pull latest harness into this project; preserves config and local-only skills |
Quality & Verification
| Skill | Purpose |
|---|
tdd/ | Test-driven development workflow |
self-verify/ | Quick browser-based UI verification |
e2e-verify/ | Full E2E Chrome verification |
dev-server/ | Start/stop/monitor dev server |
pre-deploy/ | Full go/no-go pre-deployment quality gate |
db-review/ | Review database migrations for safety |
security-review/ | 15-phase comprehensive security audit |
Operations
| Skill | Purpose |
|---|
incident/ | Structured incident response for production issues |
harness-overview/ | This document |
Agents
| Agent | Model | Purpose |
|---|
builder.md | Sonnet | Full edit access, follows project conventions |
validator.md | Opus | Read-only, runs tests/lint/security checks |
e2e-tester.md | Sonnet | Browser automation, UI verification |
migration-validator.md | Haiku | Read-only, verifies DB migration completeness |
Commands
| Command | Purpose |
|---|
/orchestrate <task> | Decompose task → builder → validator → iterate |
/harness-health | Check all harness components are working |
Configuration
All project-specific values live in .claude/hooks/config.sh. Edit it once when installing in a new project:
HARNESS_PKG_MGR="pnpm"
HARNESS_SRC_DIRS="src|lib"
HARNESS_TEST_CMD="pnpm test"
HARNESS_APP_NAME="My App"
Workflow
The full workflow from planning to shipping:
/weekly-goals → /demo-script → /plan-sprint → /build → /sync
(why) (what) (how) (do it) (reset)
Adding Project-Specific Skills
To add skills for your project, create <skill-name>/SKILL.md in skills/. The skill loader discovers them automatically. Skills in this harness are generic — your project-specific skills extend them without modifying the base.
