{
  "markdown": "# Harness Engineering Plugin\n\n[![Version](https://img.shields.io/badge/version-v2.2.0-blue)](CHANGELOG.md)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green)](LICENSE)\n[![Claude Code](https://img.shields.io/badge/Claude%20Code-%E2%89%A51.0.0-orange)](https://docs.claude.com)\n\n**Shift your core engineering work from \"writing code\" to \"designing environments where AI agents work reliably.\"**\n\nHarness Engineering Plugin packages this methodology into ready-to-use Skills, Commands, and Agents -- install and go, no extra configuration needed.\n\n---\n\n## Quick Start\n\n**Step 1: Install**\n\n**Option A -- Marketplace (recommended, auto-updates)**\n\nIn a Claude Code conversation:\n\n```\n/plugin marketplace add https://raw.githubusercontent.com/huangbaixun/harness-engineering/main/.claude-plugin/marketplace.json\n```\n\nAfter subscribing, select it from the plugin list. Claude Code will prompt you when new versions are available.\n\n**Option B -- Clone from GitHub**\n\n```bash\ngit clone https://github.com/huangbaixun/harness-engineering.git\nclaude --plugin-dir ./harness-engineering\n```\n\nGood for local evaluation before committing to long-term use.\n\n**Option C -- Official Marketplace (coming soon)**\n\n```bash\n# Available after Anthropic review\nclaude plugins add harness-engineering\n```\n\nOr search \"Harness Engineering\" in Cowork and click install.\n\n**Step 2: Initialize a new project**\n\nIn Claude Code, say:\n\n> \"Help me initialize this project's Harness\"\n\nAfter initialization, your project gets:\n\n| File | Purpose |\n|------|---------|\n| `CLAUDE.md` | Project memory layer (<=60 lines), the single source of truth |\n| `init.sh` | Session startup script -- runs tool detection before each new session |\n| `.claude/settings.json` | Permission control + Hook registration (incl. SessionStart) |\n| `.claude/hooks/session-start.sh` | SessionStart Hook: restores progress context on session start |\n| `.claude/hooks/` | Type-check, .env protection, auto-format hooks |\n| `.claude/skills/writing-plans/` | Pre-implementation planning Skill (triggers for >30 min or 3+ file tasks) |\n| `.claude/skills/test-driven-development/` | TDD Skill (enforced RED->GREEN->REFACTOR cycle) |\n| `.claude/skills/verification-before-completion/` | Pre-completion verification Skill (4-layer check before marking done) |\n| `docs/architecture.md` | Architecture diagram -- the agent's spatial awareness doc |\n| `docs/claude-progress.json` | Cross-session progress tracking |\n\nVerify readiness: `bash init.sh` -- you should see \"Harness ready\" on success.\n\n**Step 3: Ongoing benefits**\n\nThe SessionStart Hook automatically restores progress context at the start of every session. The harness:writing-plans / harness:test-driven-development / harness:verification-before-completion workflow Skills engage automatically during implementation, ensuring a complete plan -> implement -> verify loop. Commands let you trigger audits, PR reviews, and entropy scans on demand.\n\n---\n\n## Core Skills\n\nAfter installation, these Skills trigger automatically based on your intent -- no need to memorize command names. All Skills use the `harness:` namespace:\n\n| Skill | Trigger | What it does |\n|-------|---------|-------------|\n| **harness:init** | New project / \"set up my Harness\" | Generates complete 6-layer Harness structure (CLAUDE.md + Hooks + templates) |\n| **harness:audit** | \"Agent keeps making the same mistakes\" / legacy project audit | 7-dimension health score + prioritized fix plan |\n| **harness:evolve** | \"CLAUDE.md is too long\" / after new model release | Memory file trimming + Hook adaptation + garbage collection |\n| **harness:using-harness** | Every scenario (1% rule, loaded each session) | Intent recognition, ensures the right Skill is triggered |\n| **harness:writing-plans** | New feature / bug fix (>30 min or 3+ files) | Decomposes into 2-5 min verifiable task blocks with `<action>/<verify>/<done>` triple structure |\n| **harness:canary** | Ready to deploy / release planning | Risk-scored canary deployment runbook with staged rollout, rollback triggers, observability checklists |\n| **harness:archive** | Feature completed, ready to archive | Archives specs to `docs/archive/`, checks doc-code consistency, runs architecture health scan |\n| **harness:test-driven-development** | Any code writing (bound to 1% rule) | Enforces RED->GREEN->REFACTOR cycle -- tests first, then implementation |\n| **harness:verification-before-completion** | Before declaring a task complete | 4-layer check (Functional / Quality / Architecture / Integration) |\n| **harness:brainstorming** | New feature / design task | Turns ideas into specs at `docs/specs/`, gates handoff to writing-plans by features.json/ADR linkage |\n| **harness:executing-plans** | Plan ready to run | Executes a plan from `docs/plans/` task-by-task, blocks on out-of-scope work |\n| **harness:subagent-driven-development** | Plan has independent tasks | Dispatches fresh subagent per task with two-stage review |\n| **harness:dispatching-parallel-agents** | 2+ independent parallel tasks | Parallel dispatch respecting layer dependencies + features.json grounding |\n| **harness:using-git-worktrees** | Need isolated workspace | Sets up worktree with `feature/<features.json-id>` naming convention |\n| **harness:systematic-debugging** | Bug / unexpected behavior | Writes notes to `docs/incidents/`, checks ADR invalidation, prompts canary for prod incidents |\n| **harness:receiving-code-review** | Got review feedback | Reconciles rigid-constraint feedback with features.json; arch feedback → ADR |\n| **harness:requesting-code-review** | Ready to request review | Pre-review checklist gate (rigid constraints satisfied); PR body includes `feature: <id>` |\n| **harness:finishing-a-development-branch** | Implementation complete | Owns `building → done` transition; mandatory `harness:archive` call; canary prompt for deploy-touching changes |\n| **harness:writing-skills** | Authoring/editing skills | Enforces ADR-0004 (evals) + ADR-0009 (4-file vs 2-file structure) |\n\n---\n\n## Slash Commands\n\n| Command | Function | Recommended frequency |\n|---------|----------|----------------------|\n| `/harness:init` | Initialize Harness | Project start |\n| `/harness:audit` | Harness health audit | On demand |\n| `/harness:assign` | Sprint feature assignment -- auto-calculates dependencies + generates claim script | Sprint start |\n| `/harness:canary` | Generate canary deployment runbook with risk assessment | Pre-deploy |\n| `/harness:review-pr` | Comprehensive PR review (quality + security + architecture) | Every PR |\n| `/harness:dump` | Save session progress to claude-progress.json | At ~50% context usage |\n| `/harness:sync-docs` | Doc-code consistency check | Daily |\n| `/harness:scan-arch` | Architecture health scan | Weekly |\n| `/harness:trim` | Trim CLAUDE.md to <=60 lines | After new model release |\n| `/harness:scan-entropy` | Dead code + duplicate implementation + over-coupling detection | Monthly |\n\n---\n\n## Agents\n\n| Agent | Model | Purpose |\n|-------|-------|---------|\n| **security-reviewer** | Opus | Injection vulnerabilities, auth flaws, secret leaks |\n| **code-review-agent** | Sonnet | Architecture compliance, maintainability, tech debt |\n| **coding-agent** | Sonnet | Long-cycle multi-session coding with cross-session handoff |\n| **explore-agent** | Haiku | Codebase exploration, keeps main thread context clean |\n\n---\n\n## Language Templates\n\n`harness:init` supports five tech stacks, automatically selecting the matching template during initialization:\n\n- **TypeScript / Node.js** -- strict mode, pnpm, Jest/Vitest, Biome/ESLint\n- **Python** -- type hints, poetry/uv, pytest, mypy/ruff\n- **Go** -- go modules, golangci-lint, testing\n- **Java** -- JUnit 5 + Mockito + AssertJ, Maven/Gradle, Checkstyle + SpotBugs\n- **Generic** -- Language-agnostic Harness skeleton\n\n---\n\n## Platform Compatibility\n\nThis plugin supports cross-platform Hooks since v1.9.3:\n\n| Feature | Claude Code | Windows |\n|---------|-------------|---------|\n| init.sh auto-detection | Yes | Yes (Git Bash) |\n| Skills / Commands | Yes | Yes |\n| Hooks (polyglot wrappers) | Yes | Yes (Git Bash / MSYS2) |\n\n**Cross-platform Hook mechanism** (v1.9.3): Each hook script comes in three forms -- `.cmd` (polyglot wrapper, valid for both CMD and bash), extensionless (bash logic), and `.sh` (backward compat). `hooks.json` uses the `${CLAUDE_PLUGIN_ROOT:-.}` path variable, working in both plugin-install and local-dev modes. On Windows, Git for Windows bash is auto-detected; if unavailable, the hook silently succeeds without blocking.\n\n---\n\n## Local Installation Verification\n\n```bash\n# Unpack the .skill bundle to a test directory\nunzip harness-engineering.skill -d /tmp/harness-test\n\n# Load the plugin\nclaude --plugin-dir /tmp/harness-test\n```\n\n---\n\n## Design Principles\n\nThis plugin is fully self-bootstrapped (dogfooding) -- Harness Engineering conventions are used to develop the Harness Engineering Plugin itself:\n\n- `CLAUDE.md` <=60 lines, the single source of truth\n- `docs/architecture.md` contains explicit dependency rules\n- `docs/decisions/` has complete ADR records for every key decision (incl. ADR 0007 Claude-Code-only architecture)\n- Hook scripts follow the \"silent on success, visible on failure\" principle\n- Skills use `.claude/` paths directly\n\n---\n\n## Methodology References\n\nThis plugin is built on the [Harness Engineering Practice Manual](references/HarnessEngineering.md) -- synthesizing first-hand practices from Anthropic, OpenAI, InfoQ, and Hacker News, covering long-cycle task harness design, multi-agent architecture, garbage collection systems, and other core patterns.\n\nv1.9.2 integrated workflow design ideas from [obra/superpowers](https://github.com/obra/superpowers): the writing-plans (pre-implementation planning gate), test-driven-development (enforced RED->GREEN->REFACTOR cycle), and verification-before-completion (4-layer completion check) Skills are directly inspired by that project's core practices, deeply integrated with Harness's SessionStart Hook and claude-progress.json cross-session memory system to form a complete \"plan -> implement -> verify -> remember\" loop.\n\nMulti-person collaboration design references the [Team Parallel Development Guide](references/team-parallel-development.md), including features.json parallel field design, Git Worktree isolation, and sprint assignment algorithms.\n\n---\n\n## Contributing\n\nWe welcome new Skills, language templates, and Hook script improvements. See [CONTRIBUTING.md](CONTRIBUTING.md) for details.\n\n---\n\n[Chinese documentation / 中文文档](README.zh-CN.md)\n\n---\n\n<details>\n<summary>Full file listing</summary>\n\n```\nharness-engineering-plugin/\n├── CLAUDE.md                             <- Project memory file (single source of truth, <=60 lines)\n├── .claude-plugin/\n│   └── plugin.json                       <- Claude Code plugin manifest\n├── skills/                               <- Unified harness: namespace\n│   ├── using-harness/SKILL.md            harness:using-harness meta-Skill (1% rule)\n│   ├── init/SKILL.md                     harness:init project initialization\n│   ├── audit/SKILL.md                    harness:audit legacy audit\n│   ├── evolve/SKILL.md                   harness:evolve continuous evolution\n│   ├── archive/SKILL.md                  harness:archive completion archival\n│   ├── canary/SKILL.md                   harness:canary deployment runbook\n│   ├── writing-plans/SKILL.md            harness:writing-plans pre-implementation planning\n│   ├── test-driven-development/SKILL.md  harness:test-driven-development TDD workflow\n│   └── verification-before-completion/SKILL.md  harness:verification-before-completion pre-completion verification\n├── commands/\n│   ├── assign.md                <- /harness:assign (team sprint assignment)\n│   ├── canary.md                <- /harness:canary (deployment runbook)\n│   ├── init.md\n│   ├── audit.md\n│   ├── review-pr.md\n│   ├── dump.md\n│   ├── sync-docs.md\n│   ├── scan-arch.md\n│   ├── trim.md\n│   └── scan-entropy.md\n├── agents/\n│   ├── security-reviewer.md              Opus\n│   ├── explore-agent.md                  Haiku\n│   ├── code-review-agent.md              Sonnet\n│   └── coding-agent.md                   Sonnet\n├── hooks/\n│   └── hooks.json                        <- Hook registration (${CLAUDE_PLUGIN_ROOT:-.} fallback)\n├── scripts/                              <- Each hook in three forms: .cmd / extensionless / .sh\n│   ├── session-start{,.cmd,.sh}          <- SessionStart Hook\n│   ├── stop-typecheck{,.cmd,.sh}\n│   ├── pre-protect-env{,.cmd,.sh}\n│   ├── post-format{,.cmd,.sh}\n│   ├── stop-commit-progress{,.cmd,.sh}\n│   └── post-observe{,.cmd,.sh}\n├── docs/\n│   ├── architecture.md\n│   ├── decisions/                        ADR records (0001-0007)\n│   └── templates/                        Five language stack templates\n├── references/\n│   ├── HarnessEngineering.md             Full methodology manual\n│   ├── team-parallel-development.md      Team parallel development guide\n│   ├── hook-patterns.md\n│   └── anti-patterns.md\n├── evals/\n│   └── evals.json                        Eval index\n├── LICENSE\n├── CONTRIBUTING.md\n└── CHANGELOG.md\n```\n\n</details>\n",
  "bytes": 13170,
  "sha": "61cf0a193ab97c30d3d7fe1320645da4217a3621c9454b48f3b5fae57f1f396e",
  "repo_slug": "huangbaixun/harness-engineering",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_huangbaixun_harness_engineering_harness__b885f90e/readme"
}