English | 简体中文 | 繁體中文 | 日本語 | 한국어 | Português (Brasil) | Türkçe | Русский | Tiếng Việt | ไทย

AI coding harness package manager + composition orchestrator — it assembles the best of the open-source ecosystem into one executable engine, wired by the three-layer BDD → SDD → TDD methodology.

harnessed is an orchestration brain + prompt library, driving native subagent spawn through three fast, pure-function CLIs — harnessed gates (which sub-workflows fire), harnessed prompt (spawn-ready prompt for a sub), and harnessed checkpoint (record progress).

Not affiliated with, endorsed by, or sponsored by Harness Inc. (see NOTICE)

---

📦 Quick Install

Standalone binary (recommended) - per-platform, self-updates via harnessed update:

# macOS (Apple Silicon) / Linux (x64)
curl -fsSL https://raw.githubusercontent.com/easyinplay/harnessed/main/install.sh | bash

# Windows (x64)
irm https://raw.githubusercontent.com/easyinplay/harnessed/main/install.ps1 | iex

The standalone binary embeds its runtime: harnessed itself needs neither external Node.js nor Bun. Upstream components may still require Node/npm, Git, Bun, Python, or browser system libraries.

The binary installer offers setup with your consent in interactive sessions. Do not repeat it if it completed successfully. If setup was skipped or failed, or you installed noninteractively, run harnessed setup.

Via Bun (secondary recommendation; optional):

bun install -g harnessed && bun run --bun harnessed setup

For later Bun commands, use bun run --bun harnessed; the bare harnessed shim may still invoke Node.js.

Via npm (supported alternative; Node.js >= 22 required):

Bun is not required for this channel; Node.js >= 22 remains supported.

npm install -g harnessed && harnessed setup

Windows PowerShell 5.x does not support &&. For either package channel, run the install command first, then run setup only if installation succeeds. bash / zsh / PowerShell 7+ / cmd.exe support the chain.

Tip

🚀 The much-loved Agent Teams and Subagent features are auto-enabled in harnessed based on the task! No need to manually configure CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS — harnessed setup writes it to ~/.claude/settings.json automatically. Pattern A full-stack three-way / Pattern C 4-specialist and other multi-agent workflows work out of the box.

---

⏱️ First 5 Minutes

The shortest path from zero to a running workflow:

Step 1 is a prompt inside your host, not a shell command. In Claude Code, use:

/auto "your first requirement"

In Codex, use:

$auto "your first requirement"

Both start the default end-to-end workflow after setup for that host. The shell examples below use the binary/npm channel; for a Bun-managed install, replace the leading harnessed with bun run --bun harnessed.

# 2. Lost? Run harnessed with no arguments — it tells you where you are + what's next
harnessed
#   → you-are-here dashboard (active phase + per-step status) + a NEXT: auto|manual|done line
#   no need to remember status / next / resume — one command (comet `/comet` analog, read-only)
#   add --json for machine-readable output

# 3. Resume any time after an interruption
harnessed            # same you-are-here view
harnessed resume     # continue from the latest checkpoint

Want finer control over which stage runs and when? See the 3 modes below.

---

✨ TL;DR

How it works: harnessed assembles the best open-source Claude Code agents (gstack, GSD, superpowers, planning-with-files) and orchestrates them into one workflow via opinionated composition skills. It does not vendor upstream code — manifests describe install/check, and composition skills conduct the multi-upstream collaboration (so an upstream upgrade is just a re-install, never a manual code sync).

🔁 The operating loop

Discuss → Plan → Build → Verify → Ship, closed by a Learn loop — machine-executed across the three-layer stack (gstack governance · GSD orchestration · superpowers TDD · checkpoint evidence). Raw agent work drifts; harnessed turns it into a source-of-truth path where progress and evidence persist instead of living in chat. Learning is automatic: every completed workflow appends its failure/loop/reject signals to .planning/LEARNINGS.md, which are injected into the next cycle — this is always-on, not gated on the optional Retro. Retro (/retro) is a separate, optional milestone summary.

flowchart LR
  R(["⓪ Research<br/>multi-source investigate<br/>(optional)"]):::opt --> D
  D(["① Discuss<br/>3-layer clarify"]) --> P(["② Plan<br/>persist spec + tasks"])
  P --> T(["③ Task<br/>TDD build + checkpoint"])
  T --> V(["④ Verify<br/>independent review + evidence gate"])
  V --> S(["⑤ Ship<br/>release-preflight → tag-ready (publish via CI)"])
  S -. "milestone summary" .-> RT(["Retro<br/>(optional)"]):::opt
  V -. "fail / gap" .-> T
  S == "🔁 Learn — learnings captured on every workflow completion → injected next cycle" ==> D
  classDef opt stroke-dasharray:5,opacity:0.8

Loading

---

🧱 What is the three-layer stack?

harnessed's three-layer stack is a software-engineering implementation of the established BDD → SDD → TDD nesting: three nested feedback loops, each answering a different question. The three layers are the loops (the stable theory); harnessed composes the open-source ecosystem into each loop — and the components overlap, which is exactly what a composition orchestrator arbitrates.

Layer	Loop	Question it answers	Composed from (overlapping)
① Behavior	BDD	What to build + how we know it's done	gstack /office-hours governance · GSD discuss · superpowers brainstorming → acceptance criteria
② Spec	SDD	How it's structured	GSD plan-phase → requirements / design / tasks · contracts (Spec Kit / ECC patterns)
③ Implementation	TDD	Does it actually work	superpowers TDD red-green · subagent execution · GSD verify-work · harnessed completion gate

The loops are nested lenses, not phases — the classic Cucumber BDD-outer + TDD-inner double-loop, extended with a GenAI-era SDD spec ring into a triple-loop. harnessed runs the default outer→inner traversal as its 5-stage cadence, plus the back-edges it ships today: Verify kicks failing work back to Task, a subagent that hits a gray area round-trips to clarification before continuing, and every shipped cycle feeds learnings back into the next Discuss. (Finer-grained structured back-edges — e.g. a contract contradiction routing straight to Spec, an ambiguous requirement to Behavior — are on the roadmap, not shipped. harnessed is the linear-cadence realization of the triple-loop; the full routed graph is its evolution path.)

The components overlap — that's the point. GSD threads through all three loops as the orchestration backbone, gstack spans Behavior + Review, superpowers spans Behavior (brainstorm) + Implementation (TDD). harnessed wires them — and arbitrates the overlap — into one engine. Two cross-cutting disciplines run through every layer: karpathy principles (how to code — simplicity-first, surgical diffs) + mattpocock moves (on-demand tactical tools like /diagnosing-bugs, /grill-with-docs).

Mapped to the runtime loop above: Discuss = Behavior (BDD) · Plan = Spec (SDD) · Build = Implementation (TDD), then Verify + Ship close it with evidence gates.

---

Wait — can harnessed really go toe-to-toe with upstream giants like superpowers / gstack / GSD? Of course — we stand on the shoulders of giants. See further, Newton said. 🧐 ... (whispers) Though on closer look, more like the parrot perched on said shoulder. Eh — parrots mimic; we orchestrate. 🦜

---

🎯 Key Differentiators

• Three-layer stack machine-executed — the BDD→SDD→TDD nested triple-loop (what's that?), composed from gstack + GSD + superpowers (overlapping, GSD as the backbone) with karpathy 4 principles + mattpocock 23 moves as cross-cutting disciplines
• No vendoring of upstream — manifests describe install/check; on upstream upgrade users just re-install to get the latest version
• Composition Skill — in-house workflow skills act as the conductor's baton, orchestrating multiple upstreams in concert. 1 super-master /auto + 5 stage masters + 20 sub-workflows + 2 standalones = 28 namespace-layered workflows, full 5-stage machine-execution (/auto one-shot across stages / /discuss /plan /task /verify /ship single stage / 20 three-layer-stack subs / /research /retro 2 standalones)
• L0 Discipline Substrate — global cross-stage behavior baseline (karpathy principles + output-style + language + operational + priority + protocols), applied universally
• Package manager mindset — install dependency graph auto-resolves, doctor health check, install-base one-shot full install
• Unified entry point — users face /discuss /plan /task /verify /ship master slash commands without learning each upstream's terminology; sub commands explicitly invoke a single stage (e.g. /discuss-strategic runs only the strategic-layer clarification)
• Forward continuation — harnessed next / harnessed advance carry you across tasks and phases: when one finishes, the next is derived from .planning/ disk state (a phase is done when its PLAN has a matching SUMMARY) — no queue to maintain, so a mid-stream new phase is picked up automatically, and resume re-derives from disk. A per-turn NEXT-UNIT breadcrumb points at what's next

---

🆚 vs Native Claude Code / Codex

Native agents give you primitives; harnessed wires them into a methodology. Where a native cell says a primitive "exists," you still design, wire, and maintain it yourself per project — harnessed ships it pre-composed and engine-driven.

Dimension	Native Claude Code	Native Codex	harnessed
Workflow / methodology	Primitives only — you design the flow each time	Fewer primitives — freestyle per prompt	Codified Discuss→Ship 5-stage three-layer-stack engine — BDD + SDD + TDD loops + 2 cross-cutting (Review + Ship)
Instruction injection	CLAUDE.md + skills + hooks exist, but static & wired by hand	AGENTS.md + skills (~/.agents/skills) + hooks — also static & wired by hand	Per-turn breadcrumb hook + task-scoped routing + learnings injected each cycle
State / progress	Chat context — lost on /clear / compaction	Chat context — no persistence layer	On-disk .planning/ + workflows.json per-repo ledger + checkpoint evidence
Cross-session recovery	Re-explain the context by hand	Re-explain the context by hand	harnessed status --recover: you-are-here + next step
Verification / "done"	Agent self-reports "done"	Agent self-reports "done"	Independent review subagents + fail-CLOSED evidence guard (missing artifact = not done)
Subagent orchestration	Subagents + Agent Teams available, but orchestrated by hand	spawn_agent / send_input / wait_agent exist — also orchestrated by hand; no Agent-Teams equivalent	gates → prompt → spawn → checkpoint; Agent Teams auto-enabled per task
Learning loop	None	None	LEARNINGS.md auto-captured + injected into the next cycle
Platform reach	Claude Code only	Codex only	Cross-harness — Claude Code and Codex both first-class (hooks / agent roles / spawn dispatch / doctor --matrix / host-rendered prose)

Native agents win on zero-setup, zero-overhead for trivial one-off edits. harnessed earns its keep the moment work spans multiple steps, sessions, or subagents — where freestyle drift and lost-in-chat state start costing you.

Don't take our word for it — we ran the experiment. A published A/B evidence pack (docs/evidence/2026-07-b1/) compares /auto against bare Claude Code on 4 machine-graded tasks, full transcripts included. Honest headline: on small, fully-specified tasks both arms score 100% and bare is 4-5× cheaper — use bare (or auto-lite) there. The orchestration value claim lives in fuzzy-spec / multi-session territory, which that experiment deliberately does not cover; bring us a real task from that territory and we'll run the same protocol on it.

---

🚀 Quick Start — 3 Options

In order of increasing user intervention:

🎯 Auto Mode (Recommended for newcomers / don't want to think hard)

/auto "requirement X"

# For large requirements you can explicitly stage (usually not needed — AI auto-judges and routes in;
# force it if you believe it's a large requirement):
/auto "requirement X" --staged

Don't want to think hard, or just getting started — let harnessed handle everything. Runs the full 6 stages (research conditional → discuss → plan → task → verify → retro mandatory) without stopping. AI 1-shot auto-judges requirement complexity, suggests switching to --staged mode for large requirements (stops after each stage for review); before starting prompts "Do you have a clear understanding of the requirement?" — if no → auto-runs /research multi-source investigation; ends with mandatory /retro summary. Fail-fast on failure, resume via harnessed resume.

📂 Stage Mode (Recommended for power users / want to review intermediate results)

/discuss "requirement X"          # Strategic + Phase + Subtask 3-layer clarification
/plan "requirement X"             # Architecture (conditional) + plan persistence
/task "subtask-1"                 # 4 subs serial (clarify → code → test → deliver)
/verify "phase-1"                 # 10 subs conditional verification

Want to decide which stage to start from / review intermediate outputs — 5 masters callable independently, and each master still auto-fans-out all of that stage's subs internally.

🔬 Surgical Mode (Expert mode / you know what you want)

/discuss-phase "..."        # Run only Phase-layer clarification
/plan-architecture "..."    # Run only architecture review
/verify-paranoid "..."      # Run only the Paranoid Staff Engineer review
# ... pick any of the other 20 sub-workflows

"I'm an expert, I'll decide myself" — skip the master, invoke a sub-workflow directly. Suits advanced users who know exactly which sub they need, or reuse of a single step.

---

📐 5-Stage Flow Diagram

graph TD
  RS([⓪ /research — pre-stage multi-source investigation, optional]):::optional
  subgraph Discuss[① Discuss — Strategic Clarification]
    DM[/discuss master/]
    DS[discuss-strategic]
    DP[discuss-phase]
    DT[discuss-subtask]
    DM --> DS & DP & DT
  end
  subgraph Plan[② Plan — Task Planning]
    PM[/plan master/]
    PA[plan-architecture]
    PP[plan-phase]
    PM --> PA & PP
  end
  subgraph Task[③ Task — Execution]
    TM[/task master/]
    TC[task-clarify]
    TCo[task-code]
    TT[task-test]
    TD[task-deliver]
    TM --> TC --> TCo --> TT --> TD
  end
  subgraph Verify[④ Verify — Verification]
    VMs[/verify master/]
    VP[verify-progress]
    VC[verify-code-review]
    VPa[verify-paranoid]
    VQ[verify-qa]
    VS[verify-security]
    VD[verify-design]
    VE[verify-eval-review]
    VV[verify-validate-phase]
    VSi[verify-simplify]
    VM[verify-multispec]
    VMs --> VP & VC & VPa & VQ & VS & VD & VE & VV & VSi & VM
  end
  subgraph Ship[⑤ Ship — Release]
    SMs[/ship master/]
    SP[ship-preflight]
    SMs --> SP
  end
  RT([⑥ /retro — milestone summary, optional]):::optional
  RS --> Discuss
  Discuss --> Plan --> Task --> Verify --> Ship
  Ship --> RT
  classDef optional stroke-dasharray:5 5,fill:#f5f5f5,color:#666

Loading

Dashed boxes = optional standalones (/research pre-strategic investigation / /retro post-milestone summary); solid boxes = main 5-stage cadence (Ship stops at tag-ready; publish.yml CI does the actual publish).

28-Workflow Overview Table

Slash cmd	Stage	Type	Capability / Upstream	Brief
/auto	All	Super-master	masterOrchestrator (across 6 stages)	One-shot full 6-stage run (research conditional → discuss → plan → task → verify → retro mandatory); AI 1-shot complexity judge + understanding check + mandatory retro; --staged opt-in stage gate
/discuss	① Discuss	Master	masterOrchestrator	3 subs parallel gate-eval (chain-isolation rule)
/discuss-strategic	① Discuss	Sub	gstack /office-hours + /plan-ceo-review + planning-with-files	Strategic layer — mandatory governance for new features / new milestones / product direction (findings.md persisted)
/discuss-phase	① Discuss	Sub	GSD /gsd-discuss-phase + planning-with-files	Phase layer — ≥2 open decisions / gray-area clarification (findings.md + knowledge.md persisted)
/discuss-subtask	① Discuss	Sub	superpowers brainstorming + /grill-with-docs	Subtask layer — ≥2 approaches / core algorithm / API contract (ephemeral short discussion, not persisted)
/plan	② Plan	Master	masterOrchestrator	Serial invoke of 2 subs (architecture conditional → phase always)
/plan-architecture	② Plan	Sub	gstack /plan-eng-review	Architecture layer — mandatory governance gate for complex architecture
/plan-phase	② Plan	Sub	GSD /gsd-plan-phase + planning-with-files /plan	Plan layer — persists task_plan.md + progress.md
/task	③ Task	Master	masterOrchestrator	Serial invoke of 4 subs per subtask (clarify → code → test → deliver)
/task-clarify	③ Task	Sub	superpowers brainstorming + /grill-with-docs conditional	Subtask startup clarification gate
/task-code	③ Task	Sub	karpathy 4 principles + /improve-codebase-architecture / /diagnosing-bugs conditional	Subtask coding + cross-session progress.md sync
/task-test	③ Task	Sub	superpowers TDD red-green-refactor + /diagnosing-bugs conditional	TDD mandatory for core logic (alias mattpocock /tdd)
/task-deliver	③ Task	Sub	harnessed checkpoint completion gate + Agent Teams conditional	Until verbatim COMPLETE + R20.10 max_iter fallback
/verify	④ Verify	Master	masterOrchestrator	10 subs conditional dispatch by scenario
/verify-progress	④ Verify	Sub	GSD /gsd-verify-work + /gsd-progress	Mandatory serial starting point — UAT acceptance + state sync
/verify-code-review	④ Verify	Sub	code-review multi-subagent fan-out	High-confidence findings in parallel
/verify-paranoid	④ Verify	Sub	gstack /review (Paranoid Staff Engineer)	Mandatory for critical-module pre-PR
/verify-qa	④ Verify	Sub	gstack /qa + playwright-cli / @playwright/test / webapp-testing	End-to-end QA (has_ui_changes conditional)
/verify-security	④ Verify	Sub	gstack /cso	OWASP / auth / secrets (has_auth_or_secrets conditional)
/verify-design	④ Verify	Sub	gstack /design-review + ui-ux-pro-max + design-taste-frontend	Design system consistency (has_design_changes conditional)
/verify-eval-review	④ Verify	Sub	GSD /gsd-eval-review	AI phase eval coverage audit (has_ai_phase conditional; pairs with plan-side gsd-ai-integration-phase)
/verify-validate-phase	④ Verify	Sub	GSD /gsd-validate-phase	Nyquist requirement→test coverage backfill (requires_coverage_audit conditional)
/verify-simplify	④ Verify	Sub	code-simplifier	Final serial simplification
/verify-multispec	④ Verify	Sub	4-specialist Agent Team Pattern C	Critical release / large refactor PR escalation (mutual SendMessage cross-examination)
/ship	⑤ Ship	Master	masterOrchestrator	Release stage after Verify — preflight → delegate PR/deploy to gstack /ship → publish via CI (tag-ready boundary)
/ship-preflight	⑤ Ship	Sub	harnessed release-preflight	Read-only release-readiness gate (CHANGELOG [Unreleased] / version / git-clean / tag-absent); blocks on failure
/research	Standalone	Standalone	Tavily / Exa MCP + ctx7 + GSD /gsd-discuss-phase	Multi-source investigation (Stage ① alternate)
/retro	Standalone	Standalone	gstack /retro + planning-with-files RETROSPECTIVE.md	Project / milestone close-out summary

Master orchestrator auto gate-routes to the right sub (chain-isolation rule — non-firing subs are transparently declared skipped). Direct sub invocation also bypasses the master to run a single stage, e.g. /discuss-strategic "new feature X".

---

⚡ Usage Flow

5-stage three-layer-stack methodology — recommended driving via the 5 master orchestrators in series:

/discuss  →  /plan  →  /task  →  /verify  →  /ship
   ①         ②        ③         ④           ⑤

Stage	Master	Main sub-workflows	Upstream collaboration
① Discuss	/discuss	strategic / phase / subtask (3 in parallel)	gstack /office-hours + GSD /gsd-discuss-phase + superpowers brainstorming
② Plan	/plan	architecture (conditional) → phase	gstack /plan-eng-review + GSD /gsd-plan-phase + planning-with-files
③ Task	/task	clarify → code → test → deliver (4 serial per subtask)	karpathy principles + mattpocock moves + superpowers TDD + harnessed completion gate
④ Verify	/verify	progress → 5 parallel conditional → simplify (+ multispec critical)	GSD /gsd-verify-work + code-review + gstack /review / /qa / /cso / /design-review + code-simplifier
⑤ Ship	/ship	preflight (release-readiness gate) → delegate PR/deploy	harnessed release-preflight + gstack /ship + publish.yml CI (tag-ready boundary)

Practical example:

# 1. Install workflow upstreams (one line installs gstack + GSD + superpowers + planning-with-files)
harnessed setup

# 2. Run the 5-stage cadence inside Claude Code
/discuss "new feature X"          # Strategic + Phase + Subtask 3-layer clarification
/plan "new feature X"             # Architecture (conditional) + plan (task graph persisted)
/task "subtask-1: API contract"   # 4 subs serial per subtask
/verify "phase-1"                 # 10 subs conditional
/ship                             # release-preflight gate → PR/deploy (tag-ready; publish via CI)

# 3. Resume after interruption (any time)
harnessed resume

You can also invoke subs directly to bypass the master and run just one layer, e.g. /verify-paranoid runs only the Paranoid Staff Engineer review.

📊 Detailed mermaid + full stage walkthroughs: docs/WORKFLOW.md

---

🗂️ Architecture (5-stage namespace-layered)

1. Directory Structure

harnessed/
├── manifests/                  # L1: upstream description layer (NOT vendored)
├── workflows/                  # L6: composition skills (5-stage conductor's baton)
│   ├── discuss/                # Stage ① 3 layers (strategic + phase + subtask)
│   │   ├── auto/               # /discuss master gate-route
│   │   ├── strategic/          # /discuss-strategic (gstack /office-hours + /plan-ceo-review)
│   │   ├── phase/              # /discuss-phase (GSD /gsd-discuss-phase)
│   │   └── subtask/            # /discuss-subtask (superpowers brainstorming)
│   ├── plan/                   # Stage ② (architecture + phase task graph)
│   ├── task/                   # Stage ③ (clarify + code + test + deliver)
│   ├── verify/                 # Stage ④ (progress + code-review + paranoid + qa + cso + design + simplify + multispec)
│   ├── ship/                   # Stage ⑤ (preflight release-readiness gate → delegate PR/deploy to gstack /ship; tag-ready)
│   ├── research/               # standalone Stage ① alternate
│   ├── retro/                  # standalone post-⑤ milestone close
│   ├── capabilities.yaml       # L5a: ~100 entries, 7 categories SoT
│   ├── defaults.yaml           # ralph_max_iterations per workflow phase
│   ├── judgments/              # L5a: three-layer-stack criteria + parallelism + tdd + fallback + rules-routing
│   │   ├── strategic-gate.yaml
│   │   ├── phase-gate.yaml
│   │   ├── subtask-gate.yaml
│   │   ├── parallelism-gate.yaml         # L5b execution mechanism routing
│   │   ├── tdd-gate.yaml
│   │   ├── fallback.yaml                 # 3 rules: skip_with_transparency + override + chain_isolation
│   │   ├── web-design-routing.yaml       # UI design tool routing
│   │   ├── web-testing-routing.yaml      # E2E / browser testing tool routing
│   │   ├── web-search-routing.yaml       # Web search / doc fetch routing
│   │   └── stage-routing.yaml            # master orchestrator sub-stage routing
│   └── disciplines/            # L0: global cross-stage behavior baseline
│       ├── karpathy.yaml       # 4 principles + ≤200L
│       ├── output-style.yaml   # BLUF + no-emoji + no-em-dash
│       ├── language.yaml       # zh-Hans default + English preserve
│       ├── operational.yaml    # biome preempt + A7 + commit safety
│       ├── priority.yaml       # skill conflict arbitration
│       └── protocols.yaml      # cc-handoff design doc self-contained
├── routing/                    # L4: routing engine SSOT (decision_rules.yaml)
├── schemas/                    # L3: JSON Schema (IDE / CI consume)
├── src/                        # L4: TS engine (platform + workflow + routing + cli + installers + checkpoint + audit + state)
├── tests/                      # vitest unit + integration + dogfood (R8.1 dogfood-first)
├── scripts/                    # CI gate (check-workflow-schema, transparency-verdict, state-archive)
├── .planning/                  # project memory (STATE + ROADMAP + REQUIREMENTS + per-phase + milestones)
└── docs/adr/                   # architecture decision records

2. Logical Layering (8 layers)

┌────────────────────────────────────────────────────────────┐
│ L7 User-facing slash cmd + harnessed CLI                    │
│   /discuss /plan /task /verify /ship (master) + 20 sub + /research /retro + /auto super-master
│   + direct gstack invoke (30+ optional): /office-hours /review /qa /...
├────────────────────────────────────────────────────────────┤
│ L6 Workflow orchestration (workflows/<stage>/<sub>/)         │
├────────────────────────────────────────────────────────────┤
│ L5b Execution Mechanism (orthogonal): subagent / Agent Teams │
│   / main session + harnessed completion gate                │
│   parallelism-gate.yaml: default subagent → escalate 5 triggers │
│   Pattern A full-stack three-way / B opposing hypotheses / C multi-dim review │
├────────────────────────────────────────────────────────────┤
│ L5a Capability + Judgment + Defaults SoT                    │
│   capabilities.yaml (7 categories) + judgments/ (10 files) + │
│   defaults.yaml                                              │
├────────────────────────────────────────────────────────────┤
│ L4  Runtime engine (workflow / routing / handlers)           │
├────────────────────────────────────────────────────────────┤
│ L3  TypeBox schema + CI gate                                 │
├────────────────────────────────────────────────────────────┤
│ L2  Installer + Manifest engine                              │
├────────────────────────────────────────────────────────────┤
│ L1  Upstream components (NOT vendored)                       │
├────────────────────────────────────────────────────────────┤
│ L0  Discipline Substrate (applies globally)                  │
│   karpathy principles + output-style + language + operational + │
│   priority + protocols (applied universally to L1-L7)       │
└────────────────────────────────────────────────────────────┘

3. Cross-cutting Capabilities (capabilities.yaml — 7 categories, ~100 entries)

behavioral (6):       karpathy-guidelines + output-style + language + operational + priority + protocols
tool-slash-cmd (~60): gstack 30+ optional + gsd 10+ + mattpocock 12 high-frequency + etc.
tool-mcp (3):         chrome-devtools-mcp / tavily-mcp / exa-mcp
tool-cli (3):         ctx7 / gws / completion-gate
tool-plugin (2):      planning-with-files / @playwright/test
tool-bundled (2):     webapp-testing / playwright-cli
agent-platform (3):   agent-teams-create / send-message / shutdown

4. Data Flow Example (user invokes /discuss "new feature X")

[L7] User invokes /discuss "new feature X"
  ↓
[L6] workflows/discuss/auto/workflow.yaml master orchestrator
  ↓
[L5a] judgments.strategic-gate.fires + phase-gate.fires + subtask-gate.fires (3-way parallel eval)
  ↓
[L4] judgmentResolver.ts (4-level ref split) + exprBuilder.ts (expr-eval evaluate)
  ↓
[L0] discipline.priority-hierarchy arbitrates tool conflicts / output-style formats output
  ↓
[fires=true sub] → invoke sub-workflow (/discuss-strategic / /discuss-phase / /discuss-subtask)
  ↓ for each sub:
      ├─ behavioral_layer: karpathy-guidelines (always-on)
      ├─ tools_available: planning-with-files / ctx7 / mattpocock by-condition
      ├─ parallelism: judgments.parallelism-gate.<route>.fires (L5b mechanism)
      └─ phase invocations execute via capability template interpolation
  ↓
[fallback.yaml chain-isolation] 3 layers judged independently, not serially dependent
[Skip transparency declaration] non-firing subs → "⚠️ Skipped <sub> because <reason>"
  ↓
planning-with-files /plan (cross-cutting tool) → write artifacts to .planning/<phase-id>/
  ↓
[L4] state.ts writeCurrentWorkflow (proper-lockfile) + audit.append (12-field JSONL)

5. Decision Routing Matrix (rules-based, codified in judgments + capabilities)

Scenario	Default → Escalate
Parallelism mechanism	subagent → Agent Teams Pattern A/B/C (5 triggers)
UI design primary plan	two-stage: ui-ux-pro-max (audience / interaction logic / design axis — structure) → design-taste-frontend (anti-slop visual polish overlay, cross-agent taste-skill)
E2E browser exploration	playwright-cli (one-line Bash, token-efficient)
E2E commit-able TS	@playwright/test default
E2E Python backend linkage	webapp-testing
Performance / a11y / memory diagnostics	chrome-devtools-mcp
Web search (keyword)	Tavily MCP default
Web search (descriptive / academic)	Exa MCP
Library API docs	ctx7 CLI
GitHub URL	gh CLI
Single URL fetch	WebFetch built-in
Gmail / Drive / Calendar	gws CLI
Architecture review (complex)	gstack /plan-eng-review
TDD mandatory (core algorithm)	superpowers TDD OR mattpocock /tdd
Critical module PR	gstack /review
Large refactor PR multi-dim review	4-specialist Agent Team Pattern C
Cross-session hand-off	discipline.protocols self-contained design doc
/auto complexity for large requirements	AI 1-shot judge → auto-suggest --staged (n abort suggests manual /discuss)
/auto requirement understanding	prompt before start → n auto-adds /research multi-source investigation

---

🛠️ Operational Commands

These are harnessed's own maintenance commands (setup / health check / backup-rollback / state recovery, etc.). For day-to-day feature development just use the slash commands above — you usually don't need these.

v4.0 — orchestration brain. Slash commands run clarification in the main Claude Code session (so questions reach you), then spawn CC-native subagents (enabling Agent Teams + clarification round-trips). harnessed provides the gate evaluation (harnessed gates) and spawn-ready prompts (harnessed prompt); the main session does the spawning. harnessed run remains for CI/headless use.

CLI Commands

Command	Description
harnessed setup	One-time setup; installs workflow skills to ~/.claude/skills/ + MCP to ~/.claude.json
harnessed gates <master>	Evaluate which sub-workflows fire for a master stage (JSON: fire/skip/parallelism). Used by slash commands to orchestrate native spawns.
harnessed prompt <sub>	Output a spawn-ready prompt (role + checklist + disciplines + completion/clarification protocols) for a sub-workflow.
harnessed checkpoint <action> <sub>	Record sub-workflow start/complete/fail to ~/.claude/harnessed/checkpoints/.
harnessed checkpoint adopt [--from <host>]	Cross-host relay: read-only copy of the other host's active workflow slot into this host's state root; the source is never modified; --from <host> overrides the inferred source host.
harnessed (no args)	Zero-arg you-are-here: active-workflow dashboard + NEXT: auto|manual|done + run hint; --json machine-readable; no active workflow → onboarding hint (comet /comet analog, read-only).
harnessed next	Deterministic next-step contract. Within a workflow: NEXT: auto|manual|done. When the workflow's subs are all resolved it falls through to the next cross-unit (next phase/task derived from .planning/ disk state) with an exit-code contract (0 advance · 2 done · 10 blocked).
harnessed advance	Forward continuation — print the next work unit (next phase/task) across the milestone and the command to run it. Print-only (the main session runs the next /auto); refuses to step past an incomplete earlier phase (--force overrides); --json drives a while harnessed advance --json; do :; done loop.
harnessed reject <sub>	Mark a sub as user-rejected (terminal, distinct from failed).
harnessed compact [--tokens <n>]	Summarize+evict resolved ledger entries (G6-safe: fail_count>0 never evicted); auto-triggers on checkpoint complete --tokens.
harnessed workflows	List in-flight workflows (one per repo).
harnessed learn "<lesson>"	Append a prose learning to this repo's .planning/LEARNINGS.md.
harnessed run <name>	Run a workflow via in-process SDK spawn (CI/headless mode). Slash commands use CC-native spawn instead.
harnessed resume	Resume from the most recent checkpoint after a session interruption
harnessed status	Current phase + lock holder
harnessed doctor	Health check (Node / MCP / jq / Win bash / routing / token budget / skill integrity / GateGuard conflict / update-available / stale hooks, etc.). The stale hooks check flags orphaned harnessed Stop/UserPromptSubmit entries in ~/.claude/settings.json that point at a deleted bin/*.mjs — the cause of a MODULE_NOT_FOUND error on every prompt after a raw npm uninstall -g harnessed. Fix: run harnessed uninstall (it strips them) before removing the package.
harnessed update [--check|--rollback [version]|--upstreams|--migration-report]	Self-update, channel-aware: binary installs replace themselves in place from GitHub releases (sha256 + ed25519-signature verified — releases ship <asset>.sha256.sig, signed-release contract since 4.32.19; the replaced version is banked for rollback); npm installs run npm i -g harnessed@latest. --check reports the latest version; --rollback [version] (binary installs only) atomically restores a banked previous binary — npm installs are pointed at npm i -g harnessed@<version>; --upstreams re-runs the base manifests; --migration-report is a read-only stale-state inventory
harnessed release-preflight	Read-only release-readiness gate (CHANGELOG [Unreleased] / version / git-clean / tag-absent); exits 1 if not ready. The Ship-stage gate.
harnessed retro --done	Reset the retro-reminder phase counter after running /retro (clears the per-turn RETRO-DUE nudge).
harnessed install <name>	Install an upstream manifest
harnessed uninstall [name]	Reverse uninstall — runs the manifest's declared spec.uninstall teardown (cmd + $HOME-confined, idempotent cleanup_paths) for the skill-installing methods (npm-cli / git-clone-with-setup / npx-skill-installer); other methods keep their per-method reverse
harnessed backup	Snapshot backup management
harnessed rollback <timestamp>	One-line rollback of a backup snapshot (EOL preserve + sha1 verify) — distinct from update --rollback, which restores a previous compiled binary
harnessed gc	Clean up expired backups
harnessed audit-log	Routing transparency log query (supports --filter jq expression)

Flags

All commands apply (immediate write) by default — no flag needed. Advanced users can add --dry-run to preview.

Flag	Description
--dry-run	Preview without writing to disk (advanced opt-in)
--non-interactive	CI / scripted scenarios
--system	Allow L4 global install (otherwise downgrade to L1 npx ephemeral)
--yes	Skip interactive confirm on uninstall
--json	Machine-readable stdout (zero-arg dashboard / next / advance, etc.); errors that escape to the process root also emit a single-line {"error":{"message":…}} envelope on stdout, so JSON.parse(stdout).error is a reliable failure probe
--full-diff	Expand diffs folded above 200 lines
--no-color	Force nocolor (even on TTY)
--task <text>	run — task description (passed as workflow gateContext.task)
--task-stdin	run — read task description from stdin until EOF (avoids shell-escape on quotes/$/`)

---

❓ FAQ

Q1. Do I still need to install superpowers / gstack / GSD upstreams after installing harnessed?

Yes, but the user experience = one command:

harnessed setup  # Auto-installs gstack + GSD + superpowers + planning-with-files; 28 workflow skills land in ~/.claude/skills/ + Agent Teams env var auto-written to ~/.claude/settings.json

Think brew install <formula> pulling the full dependency set — you don't need to brew install each dependency separately.

Q2. Why not just vendor superpowers / gstack into the harnessed repo?

4 reasons:

1. Differentiation philosophy — harnessed is the "assembly-ist package manager" counterposed to the "all-in-one self-built" camp. Vendoring = losing the wedge → becoming yet another plugin pack
2. License + attribution nightmare — vendoring 4-5 actively maintained upstreams = a complex license patchwork
3. Upstream upgrades flip direction — current manifest description lets users re-install for the latest version on upstream upgrade; vendoring forces manual code sync and falls perpetually behind
4. Bus factor 1 — a single maintainer keeping 4-5 vendored upstreams in sync = accelerated burnout

Q3. gstack / GSD / superpowers all look like plan/discuss tools — aren't they overlapping?

No. They are different stages of the three-layer stack:

Stage	Upstream	Responsibility
Governance	gstack	Multi-role decision gates (CEO / EM / Designer / Paranoid Engineer)
Brainstorming	superpowers	Subtask design clarification, alternative comparison
Orchestration	GSD	High-level phase task graph + dependency analysis
Persistence	planning-with-files	Persists task_plan.md / progress.md / findings.md

/discuss /plan /task /verify /ship — the 5 masters string the 5 stages together; each master internally delegates to its sub. Each stage does a different thing and feeds the next. No merging.

Q4. Do workflow phases run automatically or wait for the user?

Depends on the pause field in workflows/<name>/SKILL.md frontmatter:

• pause: human_review → blocks waiting for user approval (governance gate / final lock, e.g. /discuss-strategic gstack /office-hours + /plan-architecture /plan-eng-review lock-in gate)
• No pause → auto-chains to the next phase

Each phase output is written to ~/.claude/harnessed/checkpoints/; after a session interruption harnessed resume continues from the latest checkpoint.

Q5. Is harnessed itself a CC plugin?

A hybrid:

• npx harnessed@latest setup runs the Node.js CLI (bin/harnessed) — or use the standalone binary from the one-line installer (no Node.js required)
• setup installs workflow skills (markdown) into ~/.claude/skills/, loaded by the Claude Code runtime
• /discuss / /plan / /task / /verify etc. are slash commands inside CC that trigger skill execution
• The CLI and the CC skills share the ~/.claude/harnessed/checkpoints/ state directory

---

License

Apache-2.0 — see NOTICE (includes Harness Inc. trademark disclaimer)

Support development: