harness-claude

harness-claude

A lean, full-SDLC Claude Code harness — personal, isolated, and testable. It runs a four-phase pipeline (Plan → Implement → Verify → Maintain) backed by scoped subagents, runtime hooks, and cross-session memory. Built to evolve toward eval loops, retrieval, long-running agents, multi-agent orchestration, and computer-use (see ROADMAP.md).

Stack focus: TypeScript/JS (React, Next, Vercel) and Python.

---

Documentation

Guide	Read it for
docs/USAGE.md	Install → full pipeline → reuse-an-existing-codebase → common scenarios
docs/SKILLS.md	Every command + agent, what each does, what it delegates to
docs/HOOKS.md	Exactly what runs on your machine, and how to disable any hook
docs/TROUBLESHOOTING.md	Hooks not firing, slow tsc, MCP, git boundary — fixes
CONTRIBUTING.md	Adding skills/hooks, portability rules, PR checklist
ROADMAP.md	Where this is going (eval loops → retrieval → multi-agent → computer-use)

New here? Start with docs/USAGE.md.

---

Why it's structured as a plugin

It lives in its own repo and installs as a Claude Code plugin/marketplace, so you can:

• Test in isolation — enable it via /plugin, run a real task, judge the result. Toggle it off to fall back. It never overwrites your existing ~/.claude.
• Promote when proven — once it gives production-grade results, make it your default.
• Share later — a plugin repo is already the shareable format; push to GitHub.

---

What's inside

Layer	Where	Count	Role
Rules	rules/	7	always-on guidance (cited by skills; imported by CLAUDE.md)
Skills	skills/<name>/SKILL.md	24	15 atomic /spec … /ship drivers + 5 phase orchestrators + 4 opt-in eval (/eval /extract /benchmark /health)
Agents	agents/*.md	7	scoped subagents the skills delegate to
Hooks	hooks/hooks.json + scripts/hooks/	—	tmux, format, typecheck, quality/design gates, strategic compact, build analysis, memory persistence
MCPs	.mcp.json	3	memory · sequential-thinking · magic (load only when enabled)

The pipeline

PLAN ─────────────► IMPLEMENT ─────► VERIFY ─────────────► MAINTAIN
/spec  /research          /implement     /review  /security-review   /refactor-clean
/plan  /architect         /build-fix     /test    /verify  /ship      /onboard
                  memory: /save-session · /resume-session (cross-cutting)

Phase orchestrators run a whole phase in one command — thin wrappers that sequence the atomic skills, delegate to subagents, and pause for your input at each gate:

Command	Runs
/harness-plan	spec → research → plan → architect*
/harness-implement	implement (TDD) → build-fix
/harness-verify	review → security-review → test → verify → ship
/harness-maintain	onboard* → refactor-clean
/harness	the full pipeline, with a checkpoint between phases

* conditional. Use the atomic skills (/plan, /review, …) when you only want one step.

---

Prerequisites

Requirement	Why	Without it
Claude Code ≥ 2.x	Host for the plugin	—
Node.js ≥ 18	All runtime hooks are Node scripts	Hooks no-op; rest of the harness works
git	Phase gates, /ship, session snapshots	Most value is inside a repo
bash + jq (optional)	Status line only	Status line degrades gracefully

Project tools (prettier, eslint, tsc, ruff, pytest) are not required — the hooks that use them skip silently when absent. See docs/HOOKS.md for exactly what runs on your machine.

---

Install & test (isolated)

# 1) Add this repo as a marketplace — from GitHub, or via a local clone path
claude plugin marketplace add vasuag09/harness-claude        # straight from GitHub
# …or, if you've cloned it locally:
claude plugin marketplace add /path/to/harness-claude

# 2) In Claude Code, enable the plugin
/plugin            # find "harness-claude", enable it

# 3) Verify the pieces loaded
/plugin            # confirm skills/agents/hooks registered
/mcp               # confirm the 3 MCP servers (enable only what you need)

Then run a real task through the pipeline:

/spec    describe the feature you want
/research  /plan  /architect
/implement
/review  /security-review  /test  /verify  /ship

Toggle the plugin off in /plugin to return to your previous setup at any time.

---

Opt-in extras (global — not auto-applied)

These can't live inside an isolated plugin, so they're shipped as configs you apply when ready. Your real ~/.claude stays untouched until you do.