se-harness

An AI-agentic SDLC harness you can bootstrap around any software project — new or existing, any stack, from a single repo to a multi-repo product. AI agents do the work; hooks make sure they can't ship without you.

AI coding agents are good at writing code and bad at process discipline. se-harness wraps a full software-engineering lifecycle around them: it learns your project (scan + interview), builds a memory of your code and domain, staffs it with 12 specialized agents, and runs each goal through requirement → stories → implementation → tests → PR → deploy — pausing at three human-approval gates that are enforced by hooks, not prompts. The agent literally cannot open the PR, push, or deploy until you flip status: approved.

The same goal loop scales from a single repo up to a whole product: single repo, mono-repo, modulith, multi-repo, and hybrid topologies all go through /harness-goal the same way. For the common case (your change touches one repo, even in a multi-repo product) nothing extra happens — no new files, no added ceremony. Only when a change's impact spans 2 or more repos/components does the harness create an inspectable workspace-plan.md, hand it to a workspace-orchestrator agent that works it directly (crossing into an already-cloned sibling repo when a task lives there), and require a combined integration check — not just each piece's own tests — before the usual gates will let anything ship.

One repo serves both ecosystems: Claude Code and GitHub Copilot CLI read the same plugin marketplace.

What you get

• Bootstrap, not boilerplate — /harness-init scans existing repos first (stack + org-convention detection, evidence-based, you confirm) and interviews you only for what it can't detect. Output: AGENTS.md + CLAUDE.md inside idempotent generated-block markers (your hand edits survive re-runs), a committed .harness/ profile, and a gitignored .env.harness for secrets.
• A goal loop with real gates — /harness-goal "Add CSV export" grills you until the requirement is unambiguous, writes .harness/requirements/REQ-001.md, then drives stories → design → parallel implementation in isolated worktrees → unit/integration/e2e tests → PR → deploy. Three gates (requirement, PR evidence, deploy) are blocked by a PreToolUse hook until you approve — exit-2 block on Claude Code, permissionDecision deny on Copilot. The hook reads a command the way a shell does (git -C . push, sudo git push, bash -c 'git push', gh api …/pulls, kubectl apply, npm publish are all caught; a commit message that merely mentions git push is not), and only a requirement's frontmatter status: can unlock it.
• A 12-agent SDLC roster — architect, story-writer, backend/frontend implementers, db-engineer, unit + integration testers, e2e planner/generator/healer, release-manager, and a workspace-orchestrator for multi-component requirements (used only when one applies). Each agent gets only the tools its job needs.
• 3-tier memory — committed project profile, append-only daily/topic logs with typed causal links, and a provenance-tracked domain wiki (ingest/query/lint skills). Tier 1 (structural/code-graph) is an opt-in driver choice — CodeGraph, codebase-memory-mcp, or Graphify (/harness-mem-graphify builds and merges its index, per repo and workspace-wide; /harness-goal queries it for blast radius instead of grepping, when one's configured). Tier 3's domain wiki goes beyond code too: /harness-mem-wiki synthesizes Jira, Confluence, SharePoint, and NAS documents/video (transcribed via Graphify's video extra) into the workspace-level wiki — synthesis only, never a raw copy; the live source stays one MCP call or file-open away.
• Methodology-aware, not methodology-locked — pick se-harness (built-in) (this framework's own loop, zero extra dependencies) or OpenSpec, and /harness-goal actually drives it: OpenSpec's /opsx:propose seeds the requirement, se-harness's own gated implementers still do the work, /opsx:archive closes it out once deployed (/harness-methodology-openspec handles setup). BMAD and Spec Kit install for your own parallel use — honestly labeled as not yet delegated to, rather than implying parity. The choice is recorded in the profile (methodology: se-harness | openspec | spec-kit | bmad), is inherited from the workspace manifest, and can be revisited with /harness-bootstrap --reconfigure methodology.
• Multi-repo aware — declare products in workspace.yaml with a contracts registry; contract-check.sh blocks pushes that change a provided contract and names the consumer repos that would break.
• Workspace-level orchestration — workspace.yaml models single repo, mono-repo, modulith, multi-repo, and hybrid topologies in one additive schema (older manifests work unchanged). /harness-init bootstraps a whole product in one pass — clone from a repos.txt inventory (opt-in, confirmed — never a silent overwrite) or detect a mono-repo's sibling units, ask the shared methodology/structural-memory/org choices once, then loop every unit's own intake itself, no re-invoking per repo. /harness-bootstrap, /harness-sync, and /harness-export offer the same workspace-wide loop — run across every unit, name specific ones, or let the agent suggest units from a real staleness/gap signal. A change spanning 2+ repos gets a real plan (workspace-plan.md), a workspace-orchestrator agent to work it, and a combined integration check before gate-check.sh allows push/PR/deploy — full detail in docs/workspace-orchestration-plan.md.
• Drift-aware sync — /harness-sync detects drift on four axes (profile, recommendations, templates, memory health), shows the diff first, and refreshes only generated blocks. Choices you made (or skipped) earlier are remembered, not forgotten: observability is recorded as a decision — unset, deferred ("not yet", asked again at the next sync), declined (never re-asked) or configured (e.g. Langfuse @ http://localhost:3000) — and /harness-bootstrap --reconfigure <observability|memory|methodology> shows what's in force and lets you change it later. Providers are set up per surface, using their real integrations: Langfuse — the langfuse-observability plugin on Claude Code (keys kept in the OS keychain), native OpenTelemetry export on Copilot CLI (no Langfuse plugin exists; langfuse-otel-env.sh builds the variables from .env.harness); Dash0 — the dash0@claude-plugins-official plugin on Claude Code only (user scope recommended, ingest-only token kept in the keychain). Secrets never go in the profile.
• Exportable — /harness-export compiles the agents and hooks for Copilot and Cursor (Codex reads AGENTS.md natively).
• Upgrade-safe — /harness-update pulls the new plugin version (marketplace first, GitHub fallback) and migrates your project's .harness/ data: one backup, whole-run rollback, chained schema migrations, and hand-edited generated blocks are proposed, never silently overwritten.
• Regression-tested prompts, not just scripts — evals/ holds 194 deterministic offline cases (gates, hooks, scaffolding, plus checks of the eval machinery itself) and model-backed evals of the agents, skills, and the full goal loop (hidden acceptance tests, mutation scoring, a "tries to approve its own requirement" pressure scenario). Local and manual by design — see docs/evals-plan.md.
• No telemetry from se-harness itself — the plugin makes no network calls and collects nothing. The one exception is yours to opt into: if you choose an observability backend (Langfuse, Dash0), that third-party plugin or your own OpenTelemetry export sends session traces to the backend you picked. Declining or deferring sends nothing. See PRIVACY.md.

Install

Claude Code (inside a session):

/plugin marketplace add rbhattarai/se-harness
/plugin install se-harness

GitHub Copilot CLI:

copilot plugin marketplace add rbhattarai/se-harness
copilot plugin install se-harness-copilot@se-harness

Update later: /harness-update (Claude Code) or copilot harness-update — updates the plugin, then migrates this project's .harness/ data; safe to re-run around the restart it needs.

Plugin installs restricted in your org? Both setup guides cover the alternatives — internal GitHub Enterprise import (preferred, updates stay pullable) and offline zip → local-path marketplace, plus a no-plugin prompt-driven fallback: Claude §1.2 · Copilot §1.2–1.3.

Quickstart (5 minutes)

Single repo — in your project, run /harness-init (Claude) or copilot harness-init (Copilot CLI). Existing repos get scanned first; you're interviewed only for what can't be detected. Then /harness-bootstrap for opt-in companion tooling, and your first goal:

/harness-goal "Add CSV export to the reports page"

It writes .harness/requirements/REQ-001.md and the gate hook blocks PR/push/deploy until you flip status: approved.

Multi-repo product — either clone all repos side-by-side yourself and add a workspace.yaml (from templates/workspace.yaml: units, shared org context, and a contracts: registry), or run /harness-init from an empty workspace folder with a repos.txt listing the repos. It clones them for you (opt-in, shows the plan, never overwrites), then offers to bootstrap every repo in the same pass — the methodology/structural-memory/org choices get asked once, not once per repo, and it loops the rest itself rather than telling you to re-invoke it in each one.

Which command, when

Run these in order the first time; after that you mostly just run /harness-goal.

#	When	Command	Why
1	Once per project (or per workspace)	/harness-init	Intake: stack, methodology, org libraries, optional guardrails. Generates .harness/, AGENTS.md, CLAUDE.md. Existing repos get scanned first.
2	Existing code, after init (and after big refactors)	/harness-scan	Detects stack, devops, cloud, internal libraries and conventions from the code; you confirm before anything is merged into the profile.
3	Once, then whenever the stack or libraries change	/harness-conventions	Writes per-area convention docs (rules + internal-library catalog) the agents follow and the PR gate checks. Run library repos first in a multi-repo product. --refresh re-checks stale docs.
4	After init	/harness-bootstrap	Opt-in companion tooling (plugins, MCP servers, Playwright, observability). Can run the conventions step inline, and ends with a "Next commands" list.
5	If you chose codebase-memory-mcp or CodeGraph	/harness-mem-codebase-memory, /harness-mem-codegraph	Install (with confirmation), register with your client, index each repo, refresh. CodeGraph is two unrelated projects — it asks which.
5	If you chose Graphify as structural memory	/harness-mem-graphify	Builds the code index (per repo, plus one merged workspace graph). Re-run after large refactors. Not needed for other memory drivers. Sourcegraph (Cloud or self-hosted) has no index to build: use /harness-mem-sourcegraph instead (connect, verify, and which repos are on the instance).
6	If you configured Jira / Confluence / SharePoint / NAS sources	/harness-mem-wiki [source]	Synthesizes those non-code sources into the domain wiki /harness-goal queries. Needs credentials in the workspace .env.harness; asks before ingesting.
7	If you chose OpenSpec as methodology	/harness-methodology-openspec	Installs and initializes OpenSpec so /harness-goal can drive its propose/archive lifecycle.
8	Every change	/harness-goal "<what you want>"	The delivery loop. Starts with a preflight (conventions + memory ready?), sizes the change, then grill → requirement → story → implement → tests → PR → deploy, with 3 human approval gates.
9	Periodically (weekly, after upgrades)	/harness-sync	Detects drift: stack changes, new recommendations, stale convention docs, template updates, memory health; refreshes only generated content.
10	To use another tool	/harness-export	Compiles agents and hooks for Copilot / Cursor (Codex reads AGENTS.md natively).
11	When a new plugin version is out	/harness-update	Updates the plugin, then migrates .harness/ data safely (backup, rollback, hand-edits preserved).

You never need to remember steps 5-7: /harness-goal's preflight tells you when the code index, the domain wiki or the convention docs are missing or stale, and offers to run the right command.

Want to try it without risking your own repo? See the worked example below, using the companion demo repo demo-loan-app.

Worked example — demo-loan-app

demo-loan-app is a real, live two-app loan product used as this project's own companion demo — not a toy. loan-webapp (borrowers request loans) and lending-webapp (lenders approve/reject them) are separate Express 5 / TypeScript apps sharing a flat-file JSON store, syncing in real time over a webhook + SSE. That shared surface is exactly what the contract registry below is for.

Repo structure (trimmed — each app also has its own test/, eslint.config.js, tsconfig.json, Dockerfile):

demo-loan-app/
├── workspace.yaml              # topology: mono-repo · 2 units · 2 contracts (pre-authored)
├── docker-compose.yml          # both apps + the shared data/ volume
├── contracts/
│   ├── loan-record.md          # shared loan shape — provider: loan-webapp
│   └── notify-webhook.md       # webhook/SSE protocol — provider: lending-webapp
├── data/                       # shared JSON store — a data surface, not a unit (see contracts)
├── loan-webapp/                 # borrower side — https://localhost:3000
│   ├── package.json
│   ├── src/
│   │   ├── app.ts, server.ts, events.ts
│   │   ├── routes/{index,loan}.ts
│   │   ├── views/{index,loan}.ejs
│   │   └── data/loanStore.ts
│   └── test/
└── lending-webapp/               # lender side — https://localhost:3001
    ├── package.json
    ├── src/
    │   ├── app.ts, server.ts, events.ts
    │   ├── routes/{index,lendor,loan}.ts
    │   ├── views/{index,lendor,loan}.ejs
    │   └── data/approverStore.ts
    └── test/

Commands, in order, and what actually happens at each one:

1. git clone https://github.com/rbhattarai/demo-loan-app && cd demo-loan-app — workspace.yaml is already committed here (pre-authored for the demo): topology: mono-repo, both apps as units:, both contracts registered. Neither app has its own .harness/ yet — that's what the next command creates.
2. docker compose up --build — both apps come up (:3000, :3001), sharing data/, syncing live over the webhook/SSE pair. Leave this running.
3. /harness-init (Claude Code) or copilot harness-init (Copilot CLI), run once at the repo root: since workspace.yaml already declares two sibling units, mono-repo detection confirms it rather than proposing it fresh, then asks once whether to bootstrap both units now. Say yes, and it asks the shared questions exactly once — methodology (se-harness built-in / OpenSpec / Spec Kit / BMAD), structural-memory driver (CodeGraph / codebase-memory-mcp / Graphify / defer) — then loops into loan-webapp (stack auto-detected: Node, TypeScript, Express, EJS, Docker — you confirm, nothing else to ask) and lending-webapp (same detection, shared choices inherited silently, no re-asking). Result: AGENTS.md + CLAUDE.md + .harness/ in each app, plus a workspace-level .harness/memory/ at the repo root logging the shared choices.
4. /harness-bootstrap, run at the repo root: offers the same once-asked workspace-wide question — every unit, specific ones, or let it suggest. Installs each unit's recommended companion tooling per its own stack (e.g. Playwright for e2e) and records it in each unit's lockfile. Optional follow-ups, depending on what you chose above: /harness-mem-graphify if you picked Graphify (builds the code index for both apps and a merged graph); /harness-scan then /harness-conventions to turn what the code already does (Express route layering, EJS conventions, the test style) into convention docs the agents follow — worth doing before a real goal, skippable for a first demo; /harness-mem-wiki only if you've configured Jira, Confluence or other non-code sources (this demo has none).
5. cd lending-webapp, then /harness-goal "When a lender rejects a loan, they must give a rejection reason, and the borrower must see it on the loan-webapp dashboard" — this is the flagship cross-unit case:
   • Preflight: checks the convention docs and memory (code index fresh? wiki built?) and offers the fixing command if something is missing — skip it to continue. Then sizes the change: this one is small/medium (two units, one contract field), so it goes straight into the loop; a large goal would be analyzed in Plan mode and split into phases first.
   • Grill + impact map: interrogates the ambiguity (free text or picklist? required on reject only?); the deep-dive step builds an impact map from workspace.yaml — this touches both units, so the count is 2.
   • ⛔ Gate 1: writes REQ-001.md and REQ-001/workspace-plan.md (one row per unit) in the same stop — blocked until you flip status: approved, which approves both at once.
   • workspace-orchestrator works the plan directly: implements the lending-webapp row, crosses into loan-webapp for its row (trivial here — already checked out side by side), isolated worktrees and unit/integration tests either way.
   • Contract impact, automatically: the change adds rejectionReason to the loan record → contract-check.sh flags loan-webapp as an impacted consumer and links a task to the same REQ — you don't have to notice this yourself.
   • Integration check: brings up docker-compose.yml from the combined result and re-verifies — passing each unit's own tests isn't the same as the SSE sync actually working end to end. Only then does the plan reach integration: passed.
   • ⛔ Gate 2 (PR evidence: both rows + integration result) → ⛔ Gate 3 (deploy approval) — same hook-enforced mechanism as a single-repo goal, nothing special-cased for being cross-unit.

Full walkthrough with exact commands, demo-hygiene resets between takes, and smaller single-unit goals to try first: docs/demo/README.md.

Commands

Command	What it does
/harness-init	Intake interview (+ scan for existing repos) → generates all per-project artifacts; clones/loops a whole workspace in one pass
/harness-scan	Brownfield detection: evidence collector → confirm → merge into profile; workspace-wide in one pass
/harness-conventions	Turns detected libraries and code conventions into per-area convention docs (rules, internal-library catalog, golden examples) that agents load before writing code and the PR gate reviews against; workspace-level docs sync into every unit; optional Copilot export
/harness-bootstrap	Recommends companion plugins/CLIs/MCP servers from your profile; opt-in install + lockfile; workspace-wide in one pass. --reconfigure <observability|memory|methodology> revisits an earlier choice
/harness-goal	The goal loop: supervisor over the agent roster, 3 hook-enforced approval gates
/harness-sync	Four-axis drift detection → diff-first report → confirmed refresh of generated blocks; re-asks decisions you deferred; workspace-wide in one pass
/harness-export	Compile agents + hooks for Copilot / Cursor (Codex reads AGENTS.md natively); workspace-wide in one pass
/harness-mem-graphify	Build/maintain Graphify structural-memory indexes — per-repo, and merged at workspace level
/harness-methodology-openspec	Install/init OpenSpec where chosen — /harness-goal drives its actual propose/archive lifecycle
/harness-mem-codebase-memory	Install/register/index/refresh codebase-memory-mcp per repo, with optional cross-repo linking
/harness-mem-codegraph	Install/register/index/refresh CodeGraph (colbymchenry fully; codegraph-ai register-and-verify), with the telemetry choice asked, not assumed
/harness-mem-sourcegraph	Connect the Sourcegraph structural-memory driver (Cloud or self-hosted; user-scope, per-repo or Copilot wiring), verify it works, and report which workspace repos the instance has indexed. Builds nothing — the instance indexes
/harness-mem-wiki	Synthesize Jira/Confluence/SharePoint/NAS docs (any format — pdf, docx, pptx, xlsx, md, txt… via MarkItDown, asks before installing a reader, skips only declined formats, flags scanned files)/NAS video into the workspace-level domain wiki /harness-goal queries
/harness-update	Update the plugin (marketplace first, GitHub fallback), then migrate this project's .harness/ data — backup, whole-run rollback, hand-edited blocks never silently overwritten

Documentation

• Claude Code setup guide — install (+ restricted-org alternatives), single-repo and multi-repo worked examples, extending and publishing
• GitHub Copilot setup guide — CLI plugin, coding agent, VS Code, enterprise rollout, same examples
• Interop matrix — component × platform support, plus verified platform schema notes in docs/claude/ and docs/copilot/
• Demo walkthroughs — over the companion demo-loan-app repo: multi-unit init, contract checking, cross-unit goal (and the README GIF recording guide)
• Eval plan & status — regression evals for the prompts and hooks (evals/): what exists, what's todo, when to run them. Manual, local-only.
• Workspace-orchestration plan — single repo → mono-repo → modulith → multi-repo → hybrid: the impact map, workspace-plan.md, the workspace-orchestrator agent, and the combined integration check, phase by phase

Where it has been used

The harness has been run on all three project shapes it supports:

• Single repo and mono repo — the companion demo-loan-app and finance-portal, which also serve as the pinned fixtures for the eval suite.
• Multi-repo — an enterprise application split across several repositories, run end to end with the workspace manifest, shared scoped configuration and the workspace-wide /harness-init, /harness-bootstrap, /harness-mem-graphify, /harness-mem-wiki, /harness-scan and /harness-sync flow, using the built-in se-harness methodology (requirement, story and architecture documents) rather than OpenSpec. Observability was reconfigured to a local Langfuse after being skipped at init (the case that motivated --reconfigure), and Graphify was configured correctly. The same steps work on any multi-repo project you point it at.

OpenSpec is the only external methodology /harness-goal delegates to; Spec Kit and BMAD have not been tried.

Status

v1.4.0 is the current release: fourteen commands, a 13-agent roster, a 409-test suite in CI, and a separate local eval suite (below). Since v1.3.1 it added a read-only reviewer agent (a design-review step in the /harness-goal gate: Karpathy discipline first, then clean code and SOLID/pattern smells in the diff only). v1.3.1 added a Copilot packaging fix (the plugin bundles its templates and registry; no sibling clone) and lifecycle commands for the Sourcegraph (Cloud or self-hosted), codebase-memory-mcp and CodeGraph structural-memory drivers. v1.2.0 had added /harness-conventions and the convention docs the agents and the PR gate use; a /harness-goal preflight that checks conventions and memory readiness (code index, domain wiki) before the grill; scope triage that sizes a goal and, for large changes, analyzes in Plan mode and splits into phases implemented one at a time; optional org.guardrails (pick from a preset list or write your own) rendered into AGENTS.md; /harness-sync checking convention docs and guardrails; revisitable observability; the eval framework; and the gate hardening it drove (the HITL gate now classifies commands like a shell instead of matching a substring, closing 12 bypass shapes and 5 false positives). Since v1.0.0 (six commands, 199 tests), v1.1.0 had added /harness-mem-graphify, /harness-methodology-openspec, /harness-mem-wiki, the workspace-wide loop shared by /harness-init/-bootstrap/-sync/-export, and /harness-update with schema migrations and hand-edit-safe generated blocks, and made the plugin self-contained (templates/ and registry/ ship inside plugins/se-harness/).

Workspace-level orchestration — single repo → mono-repo → modulith → multi-repo → hybrid, one goal loop that coordinates across repos, with the orchestration overhead scaling to zero for the common single/few-component case — is complete: see docs/workspace-orchestration-plan.md for the full phase-by-phase breakdown, including the handful of open design decisions it was honest enough to leave unresolved rather than claim done (per-component scoping of non-code sources; true parallel execution of independent workspace-plan rows, which today are worked in correct dependency order but one at a time).

Run against two real multi-repo products since v1.0.0 (not just fixtures): a mono-repo on Claude Code, and a 20-repo multi-repo product on Copilot CLI. Both surfaced real gaps, now fixed — a mono-repo detection heuristic that missed a legitimate sibling-directory shape with no formal workspace-tool marker; a Copilot-specific script-vendoring gap in a brand-new workspace root; /harness-init, /harness-bootstrap, /harness-sync, and /harness-export all requiring manual re-invocation per repo instead of looping a whole workspace themselves; and /harness-goal querying structural memory and driving a chosen methodology by name (Graphify, OpenSpec) rather than falling back to Grep/Glob or running its own loop undelegated.

The structural-memory (CodeGraph vs. codebase-memory-mcp vs. Graphify vs. Sourcegraph) and methodology (BMAD vs. Spec Kit vs. OpenSpec vs. se-harness's own loop) bake-offs are both still open by design — pick one, defer, or mix per project — but Graphify and OpenSpec are now the reference implementations with real /harness-goal integration; the other four install but don't change /harness-goal's behavior yet. Also on the roadmap: a web profile-builder. Evals: layer 1 (no model, free) and layer 2 are done and passing; layer 3 has only run its pressure scenario live — status and backlog in docs/evals-plan.md. Full detail, including what's still an open gap: development history · plan and research log in docs/brainstorm.md.

Repo layout

.claude-plugin/marketplace.json      # this repo IS a marketplace — read by Claude Code AND Copilot CLI
.github/plugin/marketplace.json      # GENERATED mirror (Copilot canonical location) — never edit
plugins/se-harness/                  # the harness plugin (source of truth)
  commands/                          # the ten /harness-* commands
  agents/                            # 12-agent SDLC roster (narrow tools per agent)
  skills/                            # context-injector, stack-detector, memory-keeper, wiki-*,
                                      # requirement-grill, coding-discipline
  hooks/hooks.json + scripts/        # gate-check (+ irreversible-cmd.sh classifier), org-validate,
                                      # memory-log, contract-check, workspace-clone/-validate/
                                      # -scan-evidence, render-block (splicer), migrate (+ migrations/),
                                      # doc-extract (+ doc-registry/), new-requirement
plugins/se-harness-copilot/          # Copilot CLI variant — GENERATED by build-copilot-plugin.sh
plugins/se-harness/registry/recommendations.json  # profile → plugin mappings (recommender data; honest gaps)
plugins/se-harness/templates/             # profile/env/requirement/AGENTS/CLAUDE/mcp/workspace/
                                      # workspace-plan + memory seeds
docs/                                # setup guides, interop matrix, platform schema notes, demo guide,
                                      # eval plan/status, development history
tests/                               # 371-test suite run in CI
evals/                               # local, manual regression evals for prompts + hooks (see evals/README.md)

Contributing / publishing

Edit only plugins/se-harness/ (the Claude-first source of truth); regenerate the Copilot variant and marketplace mirror with bash plugins/se-harness/scripts/build-copilot-plugin.sh. Touched a prompt or a hook script? Run bash evals/run-evals.sh (free, ~90 s) — nothing runs it for you; which layer to run after which edit is in docs/evals-plan.md. Full update/extension and marketplace-publishing instructions: Claude guide Parts 5–6 · Copilot guide Parts 10–11.

Note: the Claude Code and Copilot plugin/hook schemas evolve quickly — verify manifests against the Claude plugin docs and Copilot plugin docs before releasing.