harness-engineering

Run architecture enforcement checks: go-arch-lint YAML rules for Go, dependency-cruiser or @softarc/sheriff for TypeScript, depguard, and Factory.ai 4-category framework (grep-ability, glob-ability, architecture boundaries, security). Use when you want to verify layer constraints are not violated, after adding new dependencies, or before opening a PR. Do NOT use for runtime design pattern advice (use architecture-advisor for that).

Implement a feature using Explorer+Workers parallel agents. Use when implementing a non-trivial feature in a single session.

Add Proto harness support to an existing repository. Installs buf.yaml, buf.gen.yaml, review-profile.proto.yaml, and the first .proto file skeleton if none exists.

Diagnose the current repository's Harness Engineering state. Reports which configs are present, which are missing, which linters are installed on PATH, and whether hooks are active.

Bootstrap the current repository with Harness Engineering tooling. Detects TS/Go/Proto stack, installs config templates, CLAUDE.md, lefthook.yml, and .claude/review-profile.yaml.

Run all harness linters and formatters across the entire repository. Use as a manual full-repo sweep when CI fails or before opening a large PR.

Run a multi-perspective PR review using the pr-reviewer-3a skill. Supports standard, mob, deep, and multi modes.

Systematically investigate a bug to identify root cause. Use when root cause is unclear. Hands off to bug-fix-tdd when cause is found.

Pre-PR quality gate — stage files, review comments, run code review, then execute lint/test. Use before creating a PR or committing a logical chunk of work.

Specialized subagent for deep architecture review. Use when analyzing layer boundaries, dependency direction, abstraction levels, and design principle adherence. Model: sonnet (for careful reasoning).

Protocol Buffers harness configuration guidance. Covers buf lint, buf format, buf breaking (wire compatibility detection), protolint (fallback), field number conventions, reserved tags discipline, and Connect RPC/gRPC integration. Use when adding a new .proto service, troubleshooting buf hook failures, designing a breaking-change-safe schema evolution, or setting up buf.yaml. THIS IS THE GAP that most dev playbooks don't fill.

Pre-PR quality gate: stage files, review code comments, run code review, then execute lint/test. Use when ready to create a PR, before committing a logical chunk of work, or before requesting team review. Do NOT use for reviewing someone else's PR (use pr-reviewer-3a).

Review and update code comments in staged files — add missing doc comments, remove obvious/stale comments, and add LLM-friendly context. Use when asked to 'review comments', 'clean up comments', or 'add doc comments' before committing. Do NOT use for logic review (use pr-reviewer-3a).

TypeScript/JavaScript harness configuration guidance. Covers Biome (format), Oxlint (lint), tsc (type check), dependency-cruiser or @softarc/sheriff (architecture boundaries), and Knip (dead code). Use when setting up TS harness, troubleshooting TS lint hook failures, choosing between ESLint and Oxlint, or enforcing layer boundaries in TS monorepos. Do NOT use for Go or Proto — see go-stack / proto-stack.

Go harness configuration guidance. Covers gofumpt (format), golangci-lint v2 with depguard/cyclop/iface/exhaustive, go-arch-lint (layer boundaries), gosec (security), and custom go/analysis analyzers. Use when setting up Go harness, troubleshooting Go lint hook failures, writing .golangci.yml, or declaring architecture rules in .go-arch-lint.yml. Do NOT use for TS or Proto.

Review PRs from Business, Development, and Testing perspectives with 4 modes: standard, mob (broad scan + deep-dive), deep (3-round progressive), multi (parallel personas). Use when reviewing a PR, self-reviewing before merge, or checking a diff. Do NOT use for addressing received comments (use pr-comment-handler).

Broad readiness check before complex work: detect risks, ambiguities, missing context, and dependencies. Use before starting a complex feature, before delegating to a sub-agent, or when unsure if all prerequisites are met. Do NOT use for a quick blocker check.

Evaluate incoming proposals, suggestions, or review comments on 5 axes and produce a principled Accept/Counter/Decline/Defer decision with explicit rationale. Use before acting on any external feedback to avoid blindly following suggestions.

Guide testing strategy and patterns for the current language/framework. Use when planning how to test a feature, choosing between unit/integration/e2e tests, or reviewing test quality across Go or TypeScript projects. Do NOT use for linting test code against Detroit School principles (use detroit-school-lint) or for writing a specific test (use bug-fix-tdd).

Advise on layered architecture patterns for the current language/framework: correct layer boundaries, dependency direction, and anti-pattern detection. Use when designing a new feature's structure, reviewing an architecture decision, or when code violates layer boundaries. Do NOT use for dependency visualization (use dependency-graph) or execution flow tracing (use code-journey).

Deterministic architecture enforcement across languages: go-arch-lint YAML rules for Go, dependency-cruiser or @softarc/sheriff for TypeScript, depguard inside golangci-lint, Factory.ai's 4-category framework (grep-ability, glob-ability, architecture boundaries, security). Use when designing layering for a new service, enforcing Clean Architecture, blocking forbidden imports, or setting up custom analyzers. Do NOT use for runtime design patterns (use architecture-advisor for that).

Monitor a pull request's CI/CD status, diagnose failures, and suggest fixes. Use when asked to 'babysit', 'watch', or 'monitor' a PR, or when CI checks are failing and need diagnosis. Do NOT use for code review (use pr-reviewer-3a) or comment handling (use pr-comment-handler).

Fix bugs by writing a failing test first, then making it pass (Red-Green-Refactor). Use when QA reports a bug, a customer reports an issue, or a regression is found. Do NOT use when root cause is unclear (use bug-investigation first), not for TDD feature development.

Systematically investigate bugs to identify root cause before fixing. Use when root cause is unclear, when asked to investigate a crash or unexpected behavior, or before writing a fix. Also invoked automatically by code-explorer for breakage deep-dives. Do NOT use when root cause is already known (use bug-fix-tdd to fix it).

Bootstrap a repository with Harness Engineering tooling: detect stack (TS/Go/Proto/mixed), install config templates (biome.json, .golangci.yml, .go-arch-lint.yml, buf.yaml, lefthook.yml), copy a pointer-style CLAUDE.md, and wire up .claude/review-profile.yaml. Use this when the user says 'set up harness', 'bootstrap the repo', 'add harness engineering', or runs /harness:init. Do NOT use for modifying existing configs — that's what /harness:check is for.

Determine optimal implementation order based on dependencies, risks, and feature flags. Use when planning sprint execution order, sequencing tasks with dependencies, or deciding what to build first. Do NOT use for estimating complexity (use estimation-poker or similar).

Analyze, respond to, and fix PR review comments, then save learnings to memory. Use when review comments arrive on a PR, when asked to address review feedback. Do NOT use for reviewing a PR yourself (use pr-reviewer-3a), pre-PR checks (use quality-gate).

Multi-model PR review using the 3 Amigos pattern: Claude Sonnet (architect), Gemini 2.5 Pro (bug hunter), DeepSeek (DX reviewer), orchestrated via Mastra. Use when reviewing a PR that needs multi-perspective analysis, when a single-model review has missed bugs before, or when the PR touches critical paths (auth, data layer, proto). Do NOT use Claude Code Max OAuth for these — API keys only, due to ToS. See docs/RATIONALE.md for the design decision.

Production safety guard that blocks destructive commands for the session. Use when user says '/careful', 'production work', or 'cautious mode'. Do NOT activate for local development work. Deactivate with '/careful off'.

Query-driven codebase exploration engine — ask any question about code and get structural answers through automatic multi-analysis. Internally composes code-journey, dependency-graph, bug-investigation, and other skills. Use when onboarding to unfamiliar code, investigating 'how does this work?', or mapping impact before changes. This is the single entry point for all code understanding tasks.

Trace and visualize code execution paths step-by-step with annotations. Use when understanding how a request flows through layers, debugging execution order, or learning how data moves between components. Also invoked automatically by code-explorer for flow analysis. Do NOT use for dependency graphs (use dependency-graph), architecture overviews (use ascii-diagram).

Explains the config protection policy enforced by the pre-config-protect hook. Covers which files are write-protected, why, and what to do when the agent (or you) hits a blocked edit. Use when the user asks 'why can't Claude edit biome.json?', 'how do I disable the config guard?', or when a PreToolUse block message appears. Do NOT use for adding new protected patterns — that's a hook-utils.js code change.

Validate tests against Detroit School (Classical) TDD principles: real objects over mocks, state verification, sociable tests. Use when reviewing test quality, when tests look mock-heavy or brittle, or ensuring tests reflect real behavior. Do NOT use for writing tests (use bug-fix-tdd), full PR review (use pr-reviewer-3a).

Explains how the PostToolUse Write/Edit lint feedback loop works end-to-end: hook routing, Rust-based linter invocation, additionalContext injection, and how to extend it with a new language. Use when debugging why a hook isn't firing, when adding support for a new language, or when understanding why Claude 'knows' about a lint violation without being told. Do NOT use for consumer-facing setup (use harness-setup).

Implement a feature using Explorer+Workers parallel agents for maximum flow efficiency. Use when implementing a non-trivial feature in a single session, especially when 'use flow-parallel', 'implement in parallel', or 'Explorer+Workers' is mentioned. Do NOT use for simple single-file changes or debugging tasks.

3 hooks across 3 events