convez.ai
AgenteAutomaçãoAvançado
MartinKChen

Harness Claude Code

MartinKChen/harness-claude-code

Orquestrador de desenvolvimento spec-driven com multi-agente e TDD

Ver no GitHub
InicialPluginScore · de 0 a 100

Agente que orquestra um fluxo completo de desenvolvimento: especificações como contrato, implementação dirigida por testes (TDD) e revisão adversarial multi-agente. Automatiza o ciclo de feature, enhancement e bug fixes com descoberta via shell scripts, workflows determinísticos e skill library para padrões backend, frontend, infra e segurança.

Instalação

$npx convez-ai MartinKChen/harness-claude-code

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
v0.42.3
Issues abertas
0
Contribuidores
2

Casos de uso

  • Automatizar ciclo completo feature → implementação → validação com testes
  • Revisar código via agentes especializados (backend, frontend, infra, segurança)
  • Padronizar workflows de desenvolvimento em equipes com DevOps integrado
  • Implementar TDD adversarial com feedback contínuo de múltiplos agentes

Veredito

Harness maduro e opinado para times que já praticam TDD e querem orquestração multi-agente robusta. Stack-agnóstico no fluxo, mas com padrões codificados para Python/FastAPI + React/TypeScript — espere adaptar se usar outra pilha. Referência de implementação de valor real, não turnkey.

README

A tradução para o português deste README ainda está na fila.

harness-claude-code

An opinionated Claude Code plugin that wraps a full product → architecture → implementation → validation workflow. Ships a unified pickup / close-out lifecycle command (/ship, covering feature, enhancement, and bug work — /implement-feature remains as a feature-only fallback) backed by pure-shell discovery scripts that drive GitHub issues and PRs through their lifecycle and by deterministic multi-agent Workflow scripts that own each unit's inner cycle, a roster of role-based agents, a curated skill library covering TDD, coding / frontend / backend / container / observability patterns, git, database migrations, security, and API/module design, and hooks that gate engineer-driven pushes (lint/type/security/test) and capture runtime telemetry.

New here? Start with DESIGN.md — the two ideas this harness is built on (specs-as-contract + orchestration over prompting). This README is the full per-surface catalogue; docs/workflow.html is the visual walkthrough.

Scope & assumptions

Read this before adopting — it sets expectations honestly.

The orchestration is stack-agnostic; the pattern catalogue currently codifies one stack. The lifecycle machinery — the commands, the GitHub-issue label protocol, the agents, the Workflow scripts, the discovery scripts, the review fan-out — makes no language assumptions. What is stack-specific is the content of the pattern-* skills and the project templates. Today they codify the stack we build on:

LayerCurrent coverage
BackendPython 3.12+, FastAPI, SQLAlchemy + Alembic, uv, ruff / mypy / bandit / pytest
FrontendTypeScript, React, Vite, TanStack Query, RHF + Zod, biome
DataPostgreSQL
E2EPlaywright
InfraDocker multi-stage + compose, nginx, OpenTelemetry, GitHub Actions

If you are on this stack, the plugin runs as-is. If you are not, the lifecycle still applies but the pattern catalogue won't fit — that is expected, not a defect. The pattern-engineer-* / pattern-reviewer-* pairing is the deliberate extension seam: add a language or framework by adding a matching engineer/reviewer skill pair (authored via /create-skill), and put coverage substance in the role-neutral pattern-test-coverage so it reaches both sides. The stack-agnostic skills (pattern-engineer-coding-standard, principle-engineer-tdd, operation-git, pattern-architect-deep-module) and every pattern-reviewer-* catalogue are reusable on any stack today, independent of the lifecycle.

The /scaffold-project templates are stack-specific by nature (they materialize a FastAPI + React/Vite + compose stack). Other ADR-declared stacks take the skeleton path — layout + manifests + ci-checks.sh pinned at scaffold time, framework entry owned by the first engineer slice; the rest of the lifecycle is stack-agnostic.

Maturity. This is a young, opinionated harness under active development on a private project; treat it as a reference implementation to adapt, not a turnkey drop-in. The greenfield feature lifecycle is the most exercised path; bug and enhancement lanes are newer.

Prerequisites

The discovery + agent layer is portable, but the execution layer has hard dependencies — check these before running /ship or /implement-feature, or a run will stall partway. A preflight /doctor-style command is on the roadmap; until then, verify manually.

Always required

  • Claude Code with the Workflow tool. The entire execution layer (implement-slice.mjs, fix-bug.mjs) runs as background Workflow scripts. Without the tool, only the single-context reviewer fallback survives — discovery, kickoff, and the whole inner slice cycle do not. There is no graceful degradation for the rest.
  • Model access to opus, sonnet, and haiku — agents and workflow phases pin specific tiers.
  • gh, authenticated (gh auth status clean) — GitHub issues are the source of truth; every label flip, comment, and PR goes through gh.
  • git, jq, and node — used by every discovery / telemetry script and to run the .mjs workflows.

Required for the implementation + scaffold paths (the FastAPI + React/Vite stack the pattern catalogue and /scaffold-project templates codify)

  • docker + docker compose — the engineer pre-push gate boots the stack, and /scaffold-project + the E2E pass run containers.
  • uv (Python backend) and npm / npx (frontend).
  • Security scanners the pre-push gate runs: gitleaks (range backstop; the scaffolded pre-commit hook is the primary secret gate), trivy (fix-aware: only actionable findings block; osv-scanner as fallback), semgrep — plus the per-stack toolchains (uv/ruff/mypy/bandit/pytest, biome/tsc, go, cargo, gradle/maven wrappers, swift).

Install from GitHub

In Claude Code:

/plugin marketplace add MartinKChen/harness-claude-code
/plugin install harness-claude-code@martinchen-marketplace

The first command registers this repo as a marketplace (it reads .claude-plugin/marketplace.json). The second installs the plugin defined in .claude-plugin/plugin.json. To update later, run /plugin marketplace update martinchen-marketplace.

What installing wires up (hooks run shell on your machine)

Installing wires the hooks in hooks/hooks.json, which execute shell locally. Two of the three groups are scoped to the plugin's own engineer worktrees under /tmp/harness-claude-code/<repo>/worktrees/ and are silent no-ops everywhere else — they do not run against your normal working tree:

  • engineer-pre-push.sh (PreToolUse on Bash) — no-ops unless the command is a git push from an engineer worktree, then runs the full CI gate: universal checks (worktree-committed + lockfile-tracked, dep bootstrap, container smoke, Playwright E2E, fix-aware security scans) plus per-surface stack checks that DELEGATE to the project's scripts/ci-checks.sh when it exists (the scaffold's single-sourced gate — hook and CI can't drift) and otherwise fall back to built-in toolchain sets (uv/ruff/mypy/bandit/pytest, biome/tsc/jest-or-vitest, gofmt/vet/golangci-lint/go test -race, cargo fmt/clippy/test, gradlew check/mvnw verify, swift build/test). The worktree-committed check blocks the push if anything is uncommitted — catching a file the engineer authored but never git add-ed, which every disk-reading local gate misses. This is the only hook that runs Docker / scanners, and only inside that sandbox.
  • post-edit-checks.sh / post-edit-dockerfile.sh (PostToolUse on edits) — no-op unless the edited file is inside an engineer worktree, then auto-format the file (ruff format / biome format) or docker build a changed Dockerfile.
  • runtime-telemetry/* (SubagentStart / PreToolUse / SubagentStop) — write one per-dispatch JSON signal under /tmp/harness-claude-code/<repo>/signals/ for engineer / reviewer / axis-reviewer / e2e-author subagents only; a no-op for main-thread tool calls, and never blocks a call.

Nothing phones home — all writes are local /tmp. Skim hooks/ before installing if your environment is sensitive.

Status

As-is — what the harness covers today: end-to-end automation of the greenfield feature lifecycle. Spec / contract generation (product → design → architecture, each a locked interview) → project scaffold (seeds the locked design tokens) → planning → outside-in TDD implementation → code & security review → fix loop → draft PR → merge. GitHub issues are the source of truth; every lifecycle step is idempotent — the orchestrator can re-enter safely. Discovery for each pass runs as pure shell (task-finder.sh) so the loop costs no LLM tokens until there is actual work to dispatch.

A visual walkthrough of how the commands, agents, and labels fit together lives at docs/workflow.html — open it in a browser.

To-be — known gaps on the roadmap:

  • Design / UX as a continuous lane. The design system is now locked up front: /deep-dive-feature runs a design-lead interview (product → design → architecture) that locks the visual language and a surface + navigation inventory — followed by a human-voted designer sample-page duel (ui-ux-pro-max vs taste-skill toolboxes) whose winner lands in docs/design-system/samples/ — /scaffold-project seeds the resulting tokens, and create-feature-issues emits a foundation/shell slice plus a page-reachability gate. Still missing: a dedicated per-feature design review phase (visual polish on shipped pages).
  • SRE in the workflow. The agent exists; nothing dispatches it yet. CI/CD ownership is still manual.
  • Enhancement and bug-fix lifecycles. ✅ Driven by the unified /ship command (superset of /implement-feature, which stays as a feature-only fallback). Bugs: /ship dispatches a read-only analyze engineer that reproduces (browser MCP preferred, Playwright fallback, stack booted either way) and posts a # Bug Analysis comment → human approves the approach → the lighter fix-bug.mjs workflow writes the regression test first, drives it green, reviews, and opens a PR. Enhancements: /create-enhancement-issue creates one feature-shaped kind:enhancement issue (+ linked enhancement/<n>-… branch) without the /deep-dive-feature interview or doc-lock, and /ship routes it through the same implement-slice.mjs cycle as a feature slice. Both lanes run repo-wide (no milestone needed) via /ship with no argument. The only guard: anything that would change an API contract / data model is a feature, not a bug or enhancement — /deep-dive-feature owns those. Refactors: code-quality debt surfaced in a slice/bug review is auto-filed (no user command) as kind:refactor issues by the review triage — behavior-preserving, with a no-e2e ## Tasks body so /ship runs them through implement-slice minus all E2E machinery (unit-test new seams; the existing suite is the regression net). non-functional debt is the exception — it routes to kind:enhancement for the full E2E treatment.

Cost

Honest answer: it is not cheap, and per-unit cost scales with slice size — there's no flat number because a slice's cost is driven by how many review dimensions apply and how many fix rounds it takes to converge. The shape:

  • Discovery is free. ship-finder.sh / task-finder.sh are pure shell — no LLM tokens are spent until there is work to dispatch.
  • The expensive unit is a slice. Per implement-slice run: E2E authoring (only when the slice has an e2e task) + a coverage-gate fan-out + implementation + the pass-E2E loop + a production-code review fan-out of up to ~14 pattern-reviewer-* dimensions (each gating dimension sampled $HCC_ROUND1_SAMPLES× — default 2 — on a gating review's first round, unioned through dedup; anchored re-review rounds run 1), optionally confirmed by a 3-lens adversarial verify (batched ≤10 findings/agent) — opt-in via the verifyLenses arg / $HCC_VERIFY_LENSES, default OFF (without it the dimension reviewer's own severity stands for non-blocking findings; the verdict-driving blockers always face a 2-lens correctness+context floor — neutralised only when both lenses refute on concrete evidence). Fix loops are bounded by progress, not a fixed round cap — they halt to a human after STALL_ROUNDS (3) consecutive non-progressing rounds (the same blocker surviving its own fix), or after CHURN_ROUNDS (3) consecutive churn rounds (new blockers kept appearing on code unchanged since the prior round — reviewer noise, not defects), so a pathological slice escalates rather than burning unboundedly.
  • Model tiers cut the bill. Review prep/publish run on haiku, judgment-bearing review on sonnet, only the discovery interviews + architecture + the analyze-bug engineer dispatch on opus (see the model-tier table under Workflows).
  • You can measure your own. Every fix round logs its token delta (a cost meter in the workflow log), and the runtime-telemetry signals capture per-dispatch and per-skill token usage under /tmp/harness-claude-code/<repo>/signals/.

TODO: publish a representative tokens / $ range per slice from private project runs.

Run a single slice first and read its telemetry before turning /loop /ship loose on a whole milestone.

Commands

Slash commands live in commands/.

CommandPurpose
/deep-dive-featureThree-phase feature deep-dive: product discovery with product-owner, design discovery with design-lead (locks the visual language + surface/navigation inventory) followed by a sample-page duel — 1–2 designer teammates (one per installed toolbox plugin: ui-ux-pro-max / taste-skill) generate plain-HTML candidates and the human votes the winner into docs/design-system/samples/ (one toolbox → solo designer + token proposal, no vote; none → design-lead's own taste, the pre-existing fallback) — then technical discovery with architect. Creates a feature branch, commits each teammate's artifacts, and opens a single PR at the end.
/scaffold-projectGreenfield-only. Reads docs/architecture-decision-record/ for stack + topology and asserts the ADR-published docs/stack.yaml stack manifest exists (owned by the adr writer scope at lock-in; scaffold distills it only as a fallback for older lock-ins — consumed by pattern selection, surface classification, and hooks), materializes backend + frontend + e2e + docker-compose.yaml from templates — or pins layout + manifests + ci-checks.sh via the skeleton path for declared stacks without a template — verifies the template-backed stack boots end-to-end, asserts the design system locked by /deep-dive-feature exists and seeds its tokens into the frontend, wires the gitleaks pre-commit + CI-parity pre-push githooks, then pushes and opens a PR.
/shipUnified lifecycle for all three kinds (feature + enhancement + bug). Superset of /implement-feature. Runs ship-finder.sh once (pure shell, optional milestone — omit it for the repo-wide maintenance lane) to find candidates across five stages: reconcile dead locks, dispatch the read-only analyze engineer for freshly-filed bugs (→ # Bug Analysis comment → human approval gate), launch the per-unit workflow at kickoff (routed by kind: — implement-slice.mjs for feature/enhancement, fix-bug.mjs for bug), and the two PR stages (fix-pr, close-pr). Wrap with /loop /ship [milestone].
/implement-featureDrive one outer pass over a feature milestone's slice lifecycle. The inner slice cycle (author E2E → coverage gate → implement → pass E2E → review → fix → open draft PR) runs inside ONE background implement-slice Workflow per slice, so the command owns only four stages: reconcile dead-workflow locks (0), launch a workflow per eligible slice (1), and the two external-wait PR stages (fix-pr 8, close-pr 9). Runs skills/operation-git/scripts/task-finder.sh once (pure shell, read-only, no LLM) to find candidates, then performs the kickoff lock flip + Workflow launch, reconcile releases, fix-pr Agent dispatch, and Stage 9's squash-merge directly. Wrap with /loop /implement-feature <feature-name> for end-to-end shipping.
/create-agentAuthor a new Claude Code subagent under .claude/agents/<name>.md — walks through naming, model choice, role, and section content, then writes the file.
/create-skillAuthor a new Claude Code skill under .claude/skills/<name>/SKILL.md — walks through naming, summary, triggers, and which optional sections apply.

Lifecycle discovery scripts

The pickup / close-out lifecycle is driven by an umbrella discovery script that runs once per pass, executes its stage scripts in order against a single GitHub-state snapshot, and emits one canonical markdown report. Everything here is pure shell — no LLM, no agent, no skill prompt-include. Every label flip, Workflow launch, Agent dispatch, draft → ready promotion, and squash-merge is owned by the command itself. These scripts are not invoked directly by users. There are two umbrellas:

  • ship-finder.sh [milestone] — the unified finder behind /ship. Five stages — reconcile, analyze-bug, kickoff, fix-pr, close-pr — across all three kinds; milestone is optional (omit for the repo-wide maintenance lane). Each stage delegates to a ship-stage-<name>.sh helper.
  • task-finder.sh <feature-name> — the feature-only fallback behind /implement-feature. Four stages (reconcile / kickoff / fix-pr / close-pr) scoped to one milestone; no bug analyze stage. (Stages 2–7 were retired by the per-slice-Workflow redesign — the inner slice cycle they covered now runs inside one background implement-slice Workflow per slice.)
ship-finder.sh stagePurpose
ship-stage-reconcile.shLists orphaned locks: a slice/bug status:in-progress whose implement-slice / fix-bug Workflow died, an analyze status:in-progress whose analyze-bug engineer died, or a draft PR status:fix-in-progress whose fix-pr engineer died — gated by a runtime-telemetry liveness heartbeat (a fresh last_seen vetoes the reap) with GitHub-activity staleness as the fallback. Emits a release:<action> directive (ready-to-implement / clear-analyze / clear-fix-pr) per orphan.
ship-stage-analyze-bug.shLists freshly-filed kind:bug issues with no status — the bugs /ship should lock (status:in-progress) and dispatch the read-only analyze-bug engineer for.
ship-stage-kickoff.shLists status:ready-to-implement units with zero open blockers, each tagged kind:<feature|enhancement|bug> — the command locks each (status:in-progress) and launches its workflow (implement-slice.mjs for feature/enhancement, fix-bug.mjs for bug).
ship-stage-fix-pr.shLists draft PRs with a merge-blocking signal (failing CI and/or merge conflict), excluding those carrying status:fix-in-progress / status:need-attention.
ship-stage-close-pr.shLists draft PRs that are MERGEABLE with every check rollup state SUCCESS / NEUTRAL / SKIPPED, each tagged merge:<auto|manual> and with its linked unit number resolved from the Closes #<n> line.

(/implement-feature's task-finder-stage-{0,1,8,9}-*.sh helpers are the feature-only analogues of the reconcile / kickoff / fix-pr / close-pr stages above.)

Agents

Subagents live in agents/. Each one is scoped to a single role and is normally driven by a command or skill rather than invoked directly.

AgentModelRole
product-owneropusInterviews the user to clarify a feature, then produces the PRD, Critical Path, and Glossary and updates CLAUDE.md.
design-leadopusInterviews the user to lock the product's visual language and information architecture, producing the design system (docs/design-system/{overview,tokens,components,accessibility}.md), the surface + navigation inventory (docs/design-system/surfaces.md) that closes the orphan-page gap, and a per-surface UI interaction contract skeleton (docs/ui-contract/<screen>.yaml) — the semantic interface (regions, role+accessible-name actions, outcome states) E2E specs drive/assert through, the UI analogue of api-contract; states are filled in per slice downstream (the e2e-author locks each state its specs assert; engineers add frontend-only ones). Read-only / plan-mode; ui-ux-pro-max is its toolbox. Answers designer teammates' requests for the locked interview results during the sample-page duel and folds the human-voted winner's direction into its writer payload.
designersonnetGenerates self-contained plain-HTML sample pages from the locked requirement + design-lead interview results, dispatched by /deep-dive-feature after the design interview. Each instance loads exactly one external toolbox plugin — designer-pro-max → ui-ux-pro-max, designer-taste → taste-skill — and writes uncommitted candidates under docs/design-system/sample-candidates/<name>/; in the duel the human votes the winner (the design-writer moves it into docs/design-system/samples/), and in solo mode (one plugin installed) it also produces the design-system + token proposal.md. Never commits; halts if its named toolbox is missing.
architectopusDesigns a ship-ready architecture without over-engineering, generating an ADR, an implementation-detail document, per-entity docs/data-model/<entity>.yaml + docs/api-contract/<entity>.yaml files, and updating CLAUDE.md when high-level architecture shifts. Reads the locked surface inventory and models the app shell / nav container as a real C4 component.
engineersonnet (opus for analyze-bug)Always-fullstack implementer, routed by dispatch verb. From implement-slice: implement drives backend/frontend slice-checklist tasks through strict outside-in TDD; diagnose-E2E integrates main, boots the stack, runs the slice's E2E specs and categorizes any failures into correlated production-fix groups (returning the diagnosis, editing no code) and fix-E2E drives production code to GREEN for one diagnosed group via TDD — the Pass-E2E phase loops diagnose → serial per-group fixes until green (bails to status:need-attention on a test-case constraint); fix-slice addresses slice-review findings; fix-pr clears one open draft PR of conflict / ci blockers. From /ship's bug lane: analyze-bug (read-only, dispatched on opus) reproduces a kind:bug (browser MCP → Playwright fallback, stack booted either way), root-causes it, and posts a # Bug Analysis comment; fix-bug (inside fix-bug.mjs) writes the regression test first and drives it green. Reads the slice body's ## Tasks checklist as the task ledger, resumes from ticked boxes + the branch's Task: <id> WIP commits, ticks its boxes on completion. Loads the full fullstack pattern set upfront, audits Dockerfile / compose before every push, and pulls per-entity context (data-model, api-contract) on demand. On a frontend task it also reads the slice's already-authored E2E specs read-only — as an affordance reference (the accessible names / roles / nav path the specs query) so the UI matches what the pass-E2E gate looks for, while the Gherkin AC stays the behavioral oracle.
e2e-authorsonnetAuthors and extends Playwright E2E tests for a slice's e2e checklist tasks, dispatched by the implement-slice Workflow with a (slice #, task IDs) pair (Author E2E … / Fix E2E coverage …). Sets up its own slice-scoped worktree rebased onto main, writes tests (locating purely via the UI contract's role+name; locking each behavioral outcome state it asserts in docs/ui-contract/<screen>.yaml at authoring time so the engineer renders to a fixed target — the behavioral-churn fix), smoke-runs them, commits to the slice branch (Task: <id> trailers), pushes, ticks the authored tasks' checklist boxes, and posts a summary comment. PR creation is owned by the workflow's terminal phase; the full Playwright suite is validated by the workflow's pass-E2E phase + CI on the slice PR.
axis-reviewersonnetRead-only single-axis reviewer: applies exactly ONE pattern-reviewer-* catalogue to a slice diff and returns structured findings (no verdict, no comment, no label). The implement-slice fan-out review (runReviewSlice()) spawns one per applicable pattern; the workflow owns dedup, adversarial verification, scoring, the verdict, and posting. Runs in production-code scope (implemented code) or test-coverage scope (authored E2E specs, pre-implementation).
reviewersonnetRead-only single-context fallback reviewer for one slice, used only when the implement-slice fan-out review is unavailable (e.g. the Workflow tool is absent). Collapses the fan-out into one context — applying the same per-axis rules (axis-reviewer) to every applicable pattern-reviewer-* at once on top of the always-on pattern-test-coverage gate — posts one structured # Slice Review comment, and RETURNS the verdict (APPROVE / BLOCK). Flips no label, opens no PR (the calling implement-slice workflow owns the lock, the fix loop, and the terminal PR).
doc-writersonnetPure executor invoked by /deep-dive-feature to materialize the artifacts a read-only interviewer just settled. Routes by dispatch prompt: a product-owner payload → publish the requirement, a design-lead payload → publish the design system + per-surface UI interaction contracts (docs/ui-contract/*), an architect payload → publish the ADR / implementation-detail / api-contract / data-model / runbook set. Pulls its scoped payload from the matching interviewer via SendMessage, then writes and commits — it never decides what to write.
sresonnetOwns the GitHub Actions CI/CD surface — PR validation (lint/type/test, diff-scoped mutation gate, image build, e2e), trunk auto-deploy to dev, and tag-driven release-candidate / release promotions to staging/prod via OIDC, GitHub Environments, and immutable image tags. Defined and ready; not yet auto-dispatched by any command (see the To-be roadmap).

Workflows

Beyond one-shot agent dispatch, the plugin ships deterministic multi-agent orchestration scripts under workflows/, invoked via the Workflow tool. A workflow spawns every agent as a peer in one flat pool, so it can express fan-out that the two-level Agent tree forbids. They ship with the plugin and are invoked by scriptPath against ${CLAUDE_PLUGIN_ROOT} (not by name:, which resolves in the consuming project). See workflows/README.md for the authoring + wiring contract.

There are two unit-cycle workflows — one per kind: of work — and in both the review fan-out is inlined as a function rather than a child workflow. /ship kickoff routes by kind: feature/enhancement slices launch implement-slice.mjs; bugs launch the lighter fix-bug.mjs.

WorkflowLayerWhat it does
implement-slice.mjsPer feature/enhancement slice (launched by /ship or /implement-feature kickoff, one per slice)Owns the whole inner cycle: Prep (parse the slice checklist and derive the Scope Manifest — the closed acIds set + the dontBreak regression guards — carried into both reviews as the closed scope authority) → Author E2E (e2e-author) → Coverage gate (runReviewSlice('test-coverage') + fix loop) → Plan → Implement (engineer, serial groups) → Pass E2E (engineer diagnose → serial per-group fix loop) → Gate review (runReviewSlice('production-code', …, 'gate') over the gating dimensions — spec-compliance / contract / security — + fix loop until APPROVE, judging each task at its owning layer via a per-task discharge ledger; on APPROVE the workflow ticks every AC checkbox — the reviewer-gated verified gate, distinct from the engineer's task-box self-tick which is only a progress claim) → Quality review (runReviewSlice('production-code', …, 'quality') over the code-quality axes — never blocking — as one bounded review/fix cycle + one re-review, the residual triaged into kind:refactor / kind:enhancement issues) → open the merge:auto draft PR (the default; relabel to merge:manual to opt out of auto-close) and release the slice lock. The Author-E2E + Coverage-gate phases stay conditional on the slice having an e2e task — and a slice gets an e2e task only when it closes a cross-surface journey segment, so backend-only slices skip both. Gating fix loops are uncapped on progress — coverage gate and gate review each loop to confidence-to-pass (APPROVE / all tasks ticked) with no fixed round limit, every round logs its token delta (a cost meter), and re-review rounds are anchored: each gets the prior round's findings + the sha it judged, closure-checks them (same title/file, no upward re-grade of unchanged code), and hunts new findings only in the code changed since — convergence instead of an independent re-sample of the whole diff per round. The quality review is the exception — bounded to one fix cycle + one re-review, never a loop (code quality never blocks; its residual becomes tracking issues). halt() flips status:need-attention — the path to a human — on infra failure, on an oscillation stall (the same blocker surviving its own targeted fix for STALL_ROUNDS (3) consecutive rounds, fingerprinted by file + title), OR on churn (CHURN_ROUNDS (3) consecutive rounds each surfacing a NEW blocker on code unchanged since the prior round — under anchored re-review that is reviewer sampling noise, not defects). Genuine progress — retiring blockers while new ones surface on the code the fix actually touched — trips neither guard. A relaunch resumes from durable GitHub state: ticked task boxes skip authoring/implementation, while review passage is read from the SHA-stamped verdict comments via a one-shot reviewEntryAction probe per looping review — the coverage gate is skipped only on a durable APPROVE (ticked e2e boxes prove authoring, not passage: a kill on a BLOCK re-gates), Pass E2E + Gate review are skipped on a gate APPROVE whose **Reviewed tip:** SHA still equals the remote tip (straight to the idempotent AC-tick + PR; the quality pass is likewise skipped when its own comment already exists at that tip), a standing BLOCK with no landed fix dispatches the fix first, and any BLOCK re-seeds the stall + churn streaks from the comment's <!-- resume-state --> marker so the no-progress guards survive kills. Generative phases are single agent() dispatches (shared worktree → serial); the three reviewer phases (coverage gate, gate review, quality review) are runReviewSlice() fan-outs.
fix-bug.mjsPer approved bug (launched by /ship kickoff once a human approved the # Bug Analysis comment)The lighter sibling of implement-slice.mjs — no E2E-authoring phase and no coverage gate. Prep (create the fix/<n>-<intent> branch, pull the approved analysis' regression-test plan) → Fix (write the regression test first — RED on pre-fix code — drive it GREEN, refactor; a completion check then runs the planned regression test itself and re-dispatches the engineer up to STALL_ROUNDS times if it doesn't exist/pass — a silently killed engineer can't carry a partial fix into a gate review that never executes the suite) → Gate review (runReview('gate') over regression coverage / contract / security + fix loop until APPROVE; no AC-tick — a bug has no AC ledger) → Quality review (runReview('quality') over the code-quality axes — never blocking — as one fix cycle + one re-review, residual triaged into kind:refactor / kind:enhancement issues) → open the merge:auto draft PR (the default; relabel to merge:manual to opt out of auto-close) and release the bug lock. The fails-before/passes-after discipline is enforced by the gate review's deletable-code lens (pattern-test-coverage), not a bespoke gate. A relaunch probes the newest # Bug Fix Gate Review comment (a bug has no task checklist, so the verdict comments are the only durable review record): an APPROVE whose stamped tip SHA still matches the remote branch skips Fix + Gate review — and the quality pass too when its own comment exists at that tip; a standing BLOCK routes the first Fix dispatch to the review-feedback verb and re-seeds the loop guards from the comment's resume-state marker.
runReviewSlice() / runReview()inlined function inside each workflowFans review out across isolated pattern-reviewer-* dimensions — one axis-reviewer agent each, with gating dimensions sampled round1Samples× (default 2) on a gating review's first round (independent samples unioned through dedup; anchored re-review rounds run 1) — dedups overlapping findings, optionally adversarially verifies each through three skeptic lenses (batched per dimension, ≤10 findings per agent, so dispatch scales with dimensions × chunks rather than one agent per finding — the cross-lens majority vote is unchanged) — this verify pass is opt-in via the verifyLenses arg (default OFF, since it is itself a self-review); with it off the reviewer's own severity stands for non-blocking findings, while each newly-reported verdict-driving blocker still faces an always-on 2-lens (correctness + context) floor — neutralised only when BOTH lenses refute it on concrete evidence (coverage gap dropped, gate blocker downgraded to MEDIUM and still fixed via the gating-I:M→Fix class) — then posts one # Slice Gate Review / # Slice Quality Review / # E2E Coverage Gate / # Bug Fix Gate Review / # Bug Fix Quality Review comment and RETURNS the verdict — flips no label, opens no PR (the surrounding phases own those). Every verdict comment is also the durable resume record: it carries a **Reviewed tip:** SHA (the exact commit reviewed) and an invisible <!-- resume-state --> marker (the stall + churn streaks), which a relaunch's reviewEntryAction probe consumes to skip already-passed reviews and resume the no-progress guards. Selected by (scope, reviewMode): test-coverage (gate the authored E2E specs pre-implementation against the slice AC + non-happy-paths; the lone test-coverage dim; BLOCK on any gap), production-code + 'gate' (the gating dimensions only — spec-compliance / contract / security; BLOCK on a surviving I:H), and production-code + 'quality' (the code-quality axes only; ADVISORY — never blocks; its findings feed the polish pass + triage). Splitting the old single production review into two passes keeps the gate fix loop from ever paying for the ~10-dimension quality fan-out, and runs the quality pass exactly once. Every selection is bounded by the Scope Manifest (rendered into every dimension agent's and every verifier's context) plus a per-task discharge ledger (each task's owning layer + the covers:/scenario: it discharges there): the coverage gate covers exactly the manifest's acIds + their Gherkin (a behavior with no AC id is not a gap); the gate review requires every finding to ground in a declared acId or a touched-path rule (no prose-synthesized ACs), judges each task at its owning layer (a backend invariant is proven at the backend layer, never demanded through E2E), and treats a missing test for unchanged behavior as at most a Deferred/Nit, never a blocker. Two convergence rules keep the gate fix loop from "finding a different defect every round": a gating I:M is always classed Fix (never Defer — a skipped gating MEDIUM could be re-graded HIGH by a later round and read as a new blocker) with the fix dispatch inlining the Fix-class findings, and re-review rounds are anchored to the prior round's { findings, reviewedSha } (closure-check the priors, hunt new findings only in the hunks changed since). implement-slice ties the two together: on a gate-review APPROVE the AC checkboxes are ticked — the verified gate — then the quality review runs as one review/fix cycle (one engineer fix over the non-gating findings) + one re-review, after which the residual findings are triaged into tracking issues — one per review dimension, routed by kind: non-functional → kind:enhancement (feature-shaped, earns full E2E/integration coverage), every other dimension → kind:refactor (behavior-preserving — a no-e2e ## Tasks checklist so implement-slice skips all E2E machinery; unit-test new seams only). Both land at status:ready-to-review (the human gate), deduped against open issues of that kind, so quality debt is recorded for /ship rather than blocking the slice. fix-bug.mjs mirrors the same two-stage split inline via its own runReview('gate') / runReview('quality') — gate fix loop, then one bounded quality cycle + triage — minus the AC-tick (a bug has no AC ledger), the regression test being its spec-compliance gate (workflow scripts are self-contained — no shared import, so the review block is duplicated by design).

runReviewSlice() pipeline + model tiers

Prep ─► Gating fan-out (spec + security) ─ dedup ─ verify ─►[ GATE ]─► Quality/debt fan-out ─ dedup ─ verify ─► compose ─► Publish

Each phase fans out, dedups, then verifies before the next consumes it — so the gate trips on confirmed blockers, not raw ones (a gating I:H — spec-compliance / contract / security — that survives verification both skips the ~10-dim code-quality debt fan-out for that round and is, by construction, a BLOCK; the debt dimensions run only on the round that clears the gate, so the fix loop doesn't pay for them each round). Phases are split across two model tiers by the kind of work each does — retune in one place via AGENT_MODEL / WRITER_MODEL at the top of the script:

PhaseModelWhy
Prep — read-only worktree, diff vs origin/mainhaikuPure tool-orchestration; carries no review judgment.
Prep · surface classification — touched paths → the surface flags that drive which dimensions run (full scope only)sonnetThe one judgment call in prep: a misclassified path silently drops a whole review dimension via applies(), so it keeps the stronger model (and is biased toward true).
Spec / Quality — one axis-reviewer agent per pattern-reviewer-* dimension; Verify — 3-lens adversarial refutationsonnetThe judgment-bearing review work — pinned to match the single reviewer fallback agent (model: sonnet).
Publish — write + post-comment.sh; return the verdicthaikuA pure executor performing the only write in the workflow.

Scoring (severity → Impact, (Impact, Effort) → Fix/Defer/Nit/Drop — with a gating-dimension I:M always classed Fix, never Defer, so it can't flap into a later-round blocker — full verdict = BLOCK iff a gating-dimension (spec / contract / security) I:H survives; code-quality I:H is deferred debt) runs as plain deterministic JS, not an LLM step, so it is identical across runs.

Worked example: one slice, issue → PR

There's no recorded demo yet (a demo repo / asciinema is on the roadmap). Here is what one feature slice looks like going end to end under /loop /ship <milestone>, traced by GitHub state:

  1. Issue created — create-feature-issues opens #42 labeled kind:feature + status:ready-to-review, body carrying the EARS ACs + a typed task checklist (e2e → backend → frontend), plus a linked feature/42-<intent> branch and any Blocked by chains.
  2. Human marks it ready — flip status:ready-to-review → status:ready-to-implement. With zero open blockers, ship-finder.sh's kickoff stage now lists it.
  3. Kickoff — /ship locks it (status:in-progress) and launches one background implement-slice.mjs. From here the workflow owns the inner cycle; the command only reaps it if it dies and handles the PR afterward.
  4. Inner cycle (one workflow): Prep derives the Scope Manifest → e2e-author writes Playwright specs → coverage-gate fan-out (BLOCK → e2e-author fix loop) → engineers implement the tasks via outside-in TDD → pass-E2E loop (diagnose → per-group fix until green) → gate-review fan-out over the gating dimensions — spec / contract / security (BLOCK on an I:H → anchored fix loop until APPROVE) → on APPROVE the AC checkboxes are ticked → quality-review fan-out over the code-quality axes (never blocking) as one review/fix cycle + one re-review: a single engineer fix over the non-gating findings, one re-review, then the residual findings are triaged into tracking issues — one per review dimension (non-functional → kind:enhancement, the rest → behavior-preserving kind:refactor; both status:ready-to-review, deduped — for the /ship maintenance lane) → a merge:auto draft PR opens with Closes #42. The slice lock is released.
  5. PR stages — subsequent /ship passes clear merge blockers (fix-pr) and, once the PR is MERGEABLE with checks green, squash-merge it (close-pr), which closes #42. The PR carries merge:auto by default, so close-pr lands it without further input; relabel to merge:manual beforehand to review and merge it yourself.

If anything stalls — infra failure, the same blocker surviving 3 consecutive fix rounds, or 3 consecutive rounds of new blockers on unchanged code (reviewer churn) — the workflow flips status:need-attention and stops: the path to a human.

Skills

Skills live in skills/ and auto-activate when their triggers match the task at hand.

Workflow

SkillWhat it does
principle-engineer-tddOutside-in TDD loop — acceptance test → red/green/refactor module loop → adapter contract tests → wiring, with per-step commits.
pattern-test-coverageThe shared, role-neutral catalogue of what makes a test set complete: every AC is discharged at its owning layer (backend integration / frontend / true-E2E — a compound AC fans across layers, each clause pushed to the lowest layer that can prove it and asserted once), plus Gherkin / migration coverage, edge breadth, named-observable assertions, emitted-artifact correctness, E2E selector quality, UI-contract conformance (a component test pinning each declared region/action by role+name — the firewall that moves locator-drift churn out of the browser layer), and the deletable-code spine (the completeness bar, not AC→test count — mechanically dischargeable by diff-scoped mutation testing, whose surviving-mutant report both sides consume instead of eyeballing). Loaded by both the engineer (TDD red phase) and the reviewer (code gate), so it is the single overlay target for coverage substance — a dreamed rule reaches the side that makes the miss, not only the side that catches it.
pattern-exploratory-testingRole-neutral catalogue for chartered, time-boxed exploratory testing of a built, running system — the unscripted, risk-steered investigation scripted AC/Gherkin coverage can't reach. Owns the session shape (charter + time-box + ship/no-ship readout), the tours for steering (feature / data / interruption / error-handling / boundary / money-CRUD), the consistency oracles for spotting a bug with no spec line (history / image / claims / user-expectations / product / purpose / statutes), and the bug-report shape. Built for a pre-release gate agent that drives the live app and recommends SHIP / NO-SHIP — not wired into the implement-slice review fan-out and not a substitute for the pattern-test-coverage gate; it complements scripted coverage and never blocks on a missing AC.
pattern-e2e-coding-standardThe E2E standard for the e2e-author agent — asserts user-visible state only (never a backend internal through the UI; not every AC maps to an E2E assertion); the data-seeding contract: seed via API → respect docs/api-contract/<entity>.yaml (path / verb / status / body), seed direct-to-DB → respect docs/data-model/<entity>.yaml (table / columns / constraints / defaults / FKs); and the driving/asserting contract: query by the role + accessible name (scoped to the regions) and assert on the outcome states declared in docs/ui-contract/<screen>.yaml — locking each E2E-asserted states entry in the contract at authoring time (the author-owned assertion surface the engineer renders to). Halt on a missing or contradictory contract (skeleton gaps are design-lead's lane); never invent shape or selectors.
operation-gitGitHub Flow conventions for commits, branches, PRs, issues, releases, and gh usage.
create-feature-issuesDecomposes a locked-in feature's PRD into thin vertical-slice GitHub issues, each carrying EARS acceptance criteria at the slice level (always present, even backend-only — each AC clause classified by owning layer) and a typed task checklist where every task tags covers: + its own scenario: Gherkin block (Given/When/Then, walked at the task's owning layer — there is no upfront slice-level Gherkin block); an e2e task is emitted only when the slice closes a cross-surface journey segment (one kind:feature issue per slice + linked branch). The feature member of the three issue-creation skills.
create-enhancement-issueCreates one feature-shaped kind:enhancement issue against existing code (Context / Modifies / Scope / AC / Tasks / Don't break) + a linked enhancement/<n>-<intent> branch — no interview, no doc-lock. Guards that the change touches no contract (else it's a feature). /ship runs it through the same implement-slice.mjs cycle as a feature slice.
create-bug-issueCreates one kind:bug issue with a Zone-A symptom body (Summary / Environment / Steps / Expected-vs-actual / Evidence / Severity / Regression) — no status, no branch — so the /ship analyze stage picks it up. The diagnosis is posted later as a # Bug Analysis comment, not written here.
memory-conventionReference doc for how agents consume per-project summarized memory — where the .claude/memory/patterns/<skill>.md overlays live, their file shape, and the precedence rules for applying them on top of a baseline pattern skill. (Runtime telemetry is hook-owned and out of scope.)
dream-summary-memoryThe "dreaming" pass: reads GitHub issues and PRs closed since the last dream run (the cutoff recorded in dream-log.md, not a fixed window) — review/fix comment threads + fix commits, plus PR CI-failure and merge-conflict history — distills the recurring pattern-wise mistakes, and writes additive rule overlays under .claude/memory/patterns/<skill>.md. Autonomous (schedulable); appends an audit entry to .claude/memory/dream-log.md.

Engineer patterns

Bullet-form reminders for production-code authoring. Each is matched 1:1 by a pattern-reviewer-* skill that carries the detailed audit lens — same rules on both sides; the engineer side keeps the terse imperative (it stacks many skills per dispatch), the reviewer side owns detection, severity, examples, and rebuttal apparatus (it loads one axis per dispatch).

SkillWhat it does
pattern-engineer-coding-standardLanguage-agnostic standards — Readability → KISS → DRY → YAGNI, naming, immutability, narrow error handling, parallel-by-default async, strong types, AAA tests.
pattern-engineer-backend-standardFramework-agnostic backend bullets — REST shape, schema-validated input, authorize-before-act + ownership, error envelope, Idempotency-Key, atomic mutations, rate limits, CSRF, logs, /healthz + /readyz, graceful SIGTERM, .env.example lockstep, locked deps.
pattern-engineer-frontend-standardReact bullets — composition-first components, custom hooks, route registration + entry-source reachability (a real inbound path from the shell or parent, not just a passing URL-render test), render to the surface's docs/ui-contract/<screen>.yaml (declared role+accessible-name interface; render to the states the E2E author locked, extend only frontend-only states no E2E covers — the production side of the contract pattern-reviewer-contract audits) + a contract-conformance test that renders the surface and pins every declared region/action by role+name (the executable firewall that lets E2E locate purely by role+name), route-param query guards, onSuccess invalidation, stable mutation returns, idempotency-key rotation, src/lib/api, error boundaries, native a11y, RHF+Zod, mobile-first, Tailwind ↔ tokens.
pattern-engineer-typescriptTypeScript bullets — strict mode + the non-negotiable flags, compilerOptions.types for test matchers, no any, discriminated unions, interface vs type, biome owns import order.
pattern-engineer-pythonPython bullets — uv only, full type annotations, EAFP, modern type hints, Protocol for seams, dataclass DTOs, with for resources, bandit-banned APIs avoided.
pattern-engineer-fastapiFastAPI bullets — APIRouter + prefix, Depends() injection, Pydantic at boundary only, app-level exception handlers, middleware order, trailing-slash, named path constants, async-by-default. FastAPI projects load this INSTEAD of pattern-engineer-api.
pattern-engineer-apiFramework-agnostic HTTP-service wiring for every non-FastAPI web framework (Express / Fastify / NestJS / Hono, Gin / Echo / Chi, Axum / Actix, Spring Boot / Ktor, Vapor, Flask / Django) — contract-first routing, DI through the framework's seam, boundary validation, one exception→envelope layer, request-id ordering, guard-based auth, per-test app factory.
pattern-engineer-nodeNode.js backend runtime bullets — Node LTS pinned + ESM, never block the event loop (*Sync / CPU work off the request path), fail-fast process lifecycle + SIGTERM drain mechanics, one zod-validated typed config module over scattered process.env reads, pino structured logging, AbortSignal.timeout on outbound fetch, stream.pipeline, side-effect-free module top-levels with a createApp() factory.
pattern-engineer-ssrSSR framework bullets (Next.js App Router primary; SvelteKit / Remix / Nuxt mappings) — server/client env + module boundary (public prefix is NOT a security boundary), "use client" at the interaction leaf, route-boundary data fetching, server actions re-validate + re-auth, explicit rendering mode, hydration-safe rendering, per-request isolation, framework redirect/notFound helpers throw.
pattern-engineer-viteVite bullets — pick Vite for CSR; VITE_ prefix on env vars; Vitest setup; route-boundary lazy loading; static-asset imports; dev-server proxy.
pattern-engineer-goGo bullets — gofmt/goimports + golangci-lint + go test -race, every error checked and wrapped with %w, no panic across API boundaries, ctx first param and propagated, consumer-side small interfaces, goroutines with defined exit paths via errgroup, table-driven subtests, thin cmd/ + internal/ layout.
pattern-engineer-rustRust bullets — cargo fmt + clippy -D warnings, no unwrap/expect in production paths, thiserror for libraries / anyhow at edges, ? propagation, borrow over clone, newtypes + exhaustive match, serde at the boundary, no blocking in async (tokio spawn_blocking), forbid(unsafe_code) / // SAFETY:, checked arithmetic on money.
pattern-engineer-javaJava 21 bullets — wrapper-pinned Gradle/Maven + Spotless + ErrorProne, records for DTOs, sealed interfaces + exhaustive switch, Optional return-only, no null collections, try-with-resources, cause-preserving rethrows, BigDecimal for money, java.time only, constructor injection, virtual threads for blocking I/O.
pattern-engineer-kotlinKotlin bullets — Gradle Kotlin DSL + ktlint + detekt, no !! in production, data classes + sealed types + exhaustive when, value class ids, val + read-only collections, structured concurrency (no GlobalScope), withContext(Dispatchers.IO) for blocking work, cooperative cancellation (runCatching swallows CancellationException — rethrow), shallow scope functions.
pattern-engineer-swiftSwift bullets — SwiftPM + SwiftLint + swift-format, no force unwrap / try! / as! in production, value types by default, exhaustive switch on domain enums, domain error enums, async/await structured concurrency + actors + honest Sendable, [weak self] in stored escaping closures, Codable with explicit strategies, Decimal for money.
pattern-engineer-containerMulti-stage Dockerfiles, pinned non-root images, mandatory .dockerignore, migration-aware entrypoints, /healthz endpoints, nginx ordering, deliberate networking/volumes, day-to-day docker compose commands.
pattern-engineer-databaseMigrations across stacks: tool-neutral core (generate from models/schema, chain to head, round-trip test, assert post-state by name, run via the one-shot migrate compose service) plus per-tool idioms (Alembic + pytest-alembic as the deep default, Prisma/Drizzle, Flyway/Liquibase, golang-migrate/Atlas, sqlx/SeaORM); plus runtime schema/index/query patterns.
pattern-engineer-observabilityOpenTelemetry as the only instrumentation API; traces / metrics / logs through OTel with shared resource attributes, semantic-convention names, bounded label cardinality, source-gated structured logs.
pattern-engineer-securityEngineer-facing security brief — non-negotiables + quick-lookup table keyed by surface. Points back to pattern-reviewer-security for canonical bars, detection, and rebuttal apparatus.
pattern-engineer-non-functionalEngineer-facing non-functional guardrails (ISO-25010 / ISTQB quality characteristics) — a thin always-build floor (bounded reads, no N+1, hot-predicate indexes, request/upload caps, outbound timeouts, no event-loop-blocking sync calls, bounded pools, windowed UI lists) plus heavier spec-gated targets (latency / throughput / capacity / availability / resource-ceiling) built only when the slice declares the matching non-functional AC. Security is out of scope (pattern-engineer-security); query/timeout mechanics overlap pattern-engineer-backend-standard by design.

Design

SkillWhat it does
pattern-architect-api-endpointResource-oriented REST conventions: URLs, verbs, response/error shape, pagination, filtering, sorting, versioning, idempotency.
pattern-architect-data-modelData-model shape and naming: predictable naming for tables / columns / constraints / indexes / views, and the SQLAlchemy MetaData convention that emits those names automatically. Every entity decision lands in docs/data-model/<entity>.yaml (ODCS) — the contract engineers, seed helpers, and pattern-reviewer-contract hold as iron.
pattern-architect-deep-moduleOusterhout-style "deep module" design: narrow interfaces, hidden complexity, no shallow wrappers or pass-through layers.

Reviewer patterns

Loaded by the implement-slice fan-out's axis-reviewer agents (one per dimension) and the single-context reviewer fallback. Each skill emits findings in its own shape; they are aggregated into one # Slice Review comment with the verdict (APPROVE / BLOCK).

SkillWhat it does
pattern-reviewer-test-coverageReviewer lens over the shared pattern-test-coverage catalogue — turns a coverage gap into a graded, cited finding (every gap HIGH, blocks the gate; cite AC label + test file; # Code Review shape). The substance it gates against lives in pattern-test-coverage; this skill owns only detection, severity, and reporting.
pattern-reviewer-coding-standardLanguage-agnostic code-quality patterns — large functions / files / deep nesting / mutation / dead code / console.log left behind; performance; best practices; AI-generated-code addendum.
pattern-reviewer-contractConformance audit — every API endpoint matches its docs/api-contract/<entity>.yaml (path / verb / status / body / envelope / idempotency / rate-limit), every ORM model matches its docs/data-model/<entity>.yaml (table / columns / constraint names / relationships), and every routed surface + E2E spec matches its docs/ui-contract/<screen>.yaml (declared regions / role+accessible-name actions / outcome states; specs query only the declared surface). The UI contract's states block lands per slice — E2E-asserted states are e2e-author-locked (code→contract one-way for the engineer, like the skeleton); frontend-only states no E2E covers are engineer-added, and adding that missing entry passes the gate. Diverging from a declared skeleton entry is a one-way code→contract finding.
pattern-reviewer-backend-standardBackend best-practice audit — input-validation mechanics, unbounded queries, N+1, missing timeouts, 5xx leakage, atomic mutations, /healthz shape, log redaction, .env.example lockstep, locked deps. Contract conformance lives in pattern-reviewer-contract.
pattern-reviewer-frontend-standardReact audit — hook correctness, route registration + reachability, UI-contract conformance test (the surface ships a component test pinning each declared region/action by role+name — the firewall the E2E locators depend on), TanStack Query route-param guards, mutation onSuccess + return stability, idempotency-key rotation, API via src/lib/api, error boundaries, native a11y, Tailwind ↔ tokens.
pattern-reviewer-typescriptTypeScript audit — tsconfig.json strictness, compilerOptions.types for test matchers, any usage, ! non-null without invariant, interface vs type, discriminated unions, biome organizeImports.
pattern-reviewer-pythonPython audit — bandit-banned APIs (B310/B602/B314/B506/B101), type annotations, EAFP discipline, modern type hints, Protocol over ABC, dataclass DTOs, context managers, uv-only environment.
pattern-reviewer-fastapiFastAPI audit — APIRouter prefix discipline, Depends() injection, Pydantic at boundary only, exception handlers + error envelope, middleware order, trailing-slash conformance, named path constants, Settings() footgun, dependency_overrides in tests. FastAPI slices run this INSTEAD of pattern-reviewer-api.
pattern-reviewer-apiFramework-agnostic HTTP-service wiring audit for non-FastAPI frameworks — contracted prefix verbatim, DI seam (no globals in handlers), boundary validation + separate request/response models, single exception→envelope layer, request-id middleware order, guard-based auth, env-driven knobs, per-test app factory + in-process test client.
pattern-reviewer-nodeNode.js runtime audit — event-loop blockers (*Sync in request paths), missing unhandledRejection/SIGTERM lifecycle, scattered process.env reads vs one validated config module, console.log in production paths, un-awaited promises, fetch without AbortSignal.timeout, bare .pipe() chains, side-effectful module top-levels / missing createApp() factory.
pattern-reviewer-ssrSSR audit — server secrets reaching the client bundle (CRITICAL), "use client" at the page root, client-side first-render fetch waterfalls, server actions missing re-validation/re-auth, implicit rendering-mode flips, hydration-mismatch sources, module-level per-request state, try/catch swallowing framework redirect()/notFound() throws.
pattern-reviewer-viteVite audit — stack choice, VITE_ prefix discipline, .env.example lockstep, vite.config.ts scope, vitest setup alignment with tsconfig, lazy-load + Suspense fallback, static-asset imports.
pattern-reviewer-goGo audit — discarded/unwrapped errors, panics across API boundaries, context stored in structs or dropped, fire-and-forget goroutines, producer-side fat interfaces, missing -race/golangci-lint gates, slice-aliasing traps, non-table tests.
pattern-reviewer-rustRust audit — unwrap/expect in production paths, anyhow leaking into library APIs, clone-to-satisfy-borrow-checker, catch-all _ arms on domain enums, blocking in async, std Mutex held across .await, unsafe without // SAFETY:, truncating as casts, unchecked arithmetic on money.
pattern-reviewer-javaJava audit — double for money (CRITICAL), lost exception causes, broad catch (Exception), manual close() over try-with-resources, Optional fields/params, null collections, field injection, == on boxed/String, non-exhaustive switch on sealed types, legacy Date/Calendar.
pattern-reviewer-kotlinKotlin audit — !! in production, GlobalScope launches, blocking calls inside suspend without withContext(Dispatchers.IO), swallowed CancellationException (incl. runCatching around suspending code), else arms on sealed when, mutable collection types in signatures, platform-type leaks at Java interop.
pattern-reviewer-swiftSwift audit — force unwrap / try! / as! in production, Task.detached without rationale, @unchecked Sendable without invariant, retain cycles in stored escaping closures, default arms on domain enums, Double for money, default Date Codable strategy, classes where value types belong.
pattern-reviewer-containerDocker / compose audit — multi-stage build, pinned + docker scout-vetted tags, non-root user with writable paths redirected, .dockerignore, backend entrypoint runs migrations before serving, /healthz shape, nginx SPA-fallback ordering, no secrets in image.
pattern-reviewer-databaseMigration audit across stacks — tool-neutral core (code-first, chain to head, round-trip reverts, post-state assertions by name, model ↔ migration parity, both-direction constraint tests, data ≠ schema, migrate before the app) plus per-tool idioms (Alembic/pytest-alembic deep, Prisma/Drizzle, Flyway/Liquibase, golang-migrate/Atlas, sqlx/SeaORM); plus runtime types/FK + RLS indexing/OFFSET/SKIP LOCKED audit.
pattern-reviewer-observabilityOTel audit — no vendor SDKs in src/, no print / console.log, span naming low-cardinality, semantic-convention attributes, errors via record_exception, bounded metric labels, structured JSON logs with trace correlation, batch processors, single SDK bootstrap, sampling lives in the Collector.
pattern-reviewer-securitySelf-contained detailed security catalogue + iteration flow, run in a slice review's gating phase (alongside spec-compliance + contract — a security I:H blocks) when the slice touches backend / frontend code. Fourteen patterns; cites file:line or image:<tag> with each pattern's exact Required end state.
pattern-reviewer-non-functionalReviewer lens over the shared pattern-engineer-non-functional catalogue — turns a non-functional gap into a graded, cited finding under a strict spec-gated severity rule: HIGH (blocks) ONLY when the gap maps to a declared non-functional AC on a touched surface; every thin-floor gap with no NFR AC (unbounded read, N+1, missing timeout, event-loop block, missing index) is MEDIUM (Deferred) or LOW (Nit), never HIGH. A slice with no NFR ACs is therefore never blocked by this lens — it receives only advice. Security is out of scope (pattern-reviewer-security).

Memory (per-consuming-project, always-on)

Engineer and reviewer dispatches start from the baseline pattern skills shipped here, but each consuming project grows its own memory — auto-created on the first engineer/reviewer dispatch, never flowing back upstream into this plugin. Memory has two roots split by lifetime: ephemeral runtime signals under /tmp/harness-claude-code/<repo>/signals/ and durable pattern overlays under $MAIN_ROOT/.claude/memory/ (where <repo> is basename "$MAIN_ROOT" and $MAIN_ROOT is the consuming project's main worktree root). There are three concerns:

  • Writing (telemetry). Every engineer / reviewer / axis-reviewer / e2e-author dispatch writes exactly one signal: /tmp/harness-claude-code/<repo>/signals/<agent-id>.meta.json (keyed on agent_id, not the shared session_id, so parallel dispatches don't collide), recording session/agent id + initial prompt, start / end / duration, invoked skills, token usage (total and per-skill via active-window attribution), a tool → count histogram, and stop reason. Captured entirely by the bundled hooks/runtime-telemetry/ scripts — seeded by a SubagentStart hook whose matcher is the regex ^(.+:)?(engineer|reviewer|axis-reviewer|e2e-author)$ (Claude Code only treats a matcher as a regex when it contains characters outside [A-Za-z0-9_|], so a bare engineer|reviewer would be exact-string alternation and miss the namespaced agent_type plugin agents arrive with). axis-reviewer and e2e-author are included — not just engineer / reviewer — because they own the two longest GitHub-quiet phases (the review fan-out and E2E authoring); their last_seen heartbeat is what keeps the Stage-0 reconcile reaper from false-reaping a live workflow during those phases. No other agent type produces telemetry. One residual gap remains: the default-typed workflow agents (review-prep, surfaces/plan, the 3-lens verify batches, publish) match nothing, so a large verify phase emits no last_seen heartbeat — it's GitHub-quiet and heartbeat-quiet. The window is far smaller than the unbracketed review/E2E phases the matched types cover (it's bracketed by axis-reviewer activity on either side) and well inside the ~30-min staleness threshold, so the reaper won't false-reap there in practice — but it isn't zero.
  • Dreaming. /dream-summary-memory (on demand now, schedulable later) reads the project's GitHub issues and PRs closed in the last 24h — issue review/fix comment threads + fix commits, plus PR CI-failure and merge-conflict history — distills the recurring, pattern-wise mistakes, and writes them as additive rule overlays under .claude/memory/patterns/<skill>.md. It writes autonomously and logs every run to .claude/memory/dream-log.md. One-off bugs and lone merge conflicts are dropped; only generalizable patterns (including repeat CI failures and shared-file conflict hotspots) become memory.
  • Consuming. Every pattern skill (pattern-engineer-*, pattern-reviewer-*) checks .claude/memory/patterns/<skill-name>.md at load time and applies its rules additively (sharpened triggers, project-specific carve-outs, new rules, BAD/GOOD examples worth pinning).

Runtime signals in /tmp are throwaway (the OS reclaims them). .claude/memory/ is a working directory — add /.claude/memory/ to the project's .gitignore. To clear memory: rm -rf /tmp/harness-claude-code/<repo>/ .claude/memory/ (both re-created on the next dispatch).

See skills/memory-convention/SKILL.md for the overlay-reading contract (overlay shape, precedence rules, severity floor, conflict surfacing).

Hooks

Hooks live in hooks/ and are wired up by hooks/hooks.json.

HookWhen it firesWhat it does
engineer-pre-push.shPreToolUse on every Bash call, but no-ops unless the command contains git push and the cwd is an engineer worktree under /tmp/harness-claude-code/<repo>/worktrees/.Runs the fullstack check set against the engineer's worktree before allowing the push. Universal: container presence + lockfile-tracked + worktree-committed + dep-bootstrap, container smoke, Playwright E2E. Stack checks (two tiers): a surface that ships scripts/ci-checks.sh (the scaffold's single-sourced gate, shared with CI and the project's committed githooks) runs exactly that; otherwise the hook detects the build manifest and runs the built-in set for the toolchain (pyproject.toml → uv/ruff/mypy/bandit/pytest, package.json → biome/tsc/jest-or-vitest, go.mod → gofmt/vet/golangci-lint/go test -race, Cargo.toml → fmt/clippy/test, gradlew/mvnw → check/verify, Package.swift → build/test), recording a coverage gap when a toolchain binary is absent. Security scans are fix-aware: gitleaks scans the outgoing range (backstop — the scaffolded pre-commit hook is the primary secret gate); trivy blocks only on ACTIONABLE findings (CVEs with a released fix, secrets, misconfig) while unfixable HIGH/CRITICAL CVEs pass through as advisories the engineer must convert into tracking issues; osv-scanner is the fallback when trivy is absent; semgrep ERROR always blocks (code findings are always fixable). The worktree-committed check denies the push when git status --porcelain is non-empty — the general case of lockfile-tracked, catching any file the engineer authored but never git add-ed (which the test suite and the hook's own checks miss because they read the worktree from disk). On failure, denies the Bash tool call so the engineer sees the failure summary, fixes it, and retries the push.
post-edit-checks.shPostToolUse on Edit / Write / MultiEdit / NotebookEdit, but no-ops unless the edited file is inside an engineer worktree under /tmp/harness-claude-code/<repo>/worktrees/.Runs the language-appropriate auto-formatter in place on the edited file (*.py → ruff format; *.ts/*.tsx/*.js/*.jsx → biome format --write) so trivial format issues are fixed without round-tripping through the agent. Deliberately does not run lint auto-fixers (ruff check --fix / biome check --write) — their unused-import pruning races with multi-step edits; those stay on the pre-push gate.
post-edit-dockerfile.shPostToolUse on Edit / Write / MultiEdit when the file is a Dockerfile / Dockerfile.*, and only inside an engineer worktree.Attempts a docker build against the changed Dockerfile and returns success or the failure tail as additionalContext, so the engineer learns a broken Dockerfile at edit time rather than at pre-push. Gracefully no-ops when docker is not on PATH.
runtime-telemetry/bootstrap.shSubagentStart with matcher: "^(.+:)?(engineer|reviewer|axis-reviewer|e2e-author)$" (regex form — must contain non-[A-Za-z0-9_|] chars or Claude Code falls back to exact-string alternation and misses the namespaced agent_type) — fires automatically when one of those subagents starts.Reads agent_id / agent_type / cwd from the payload, derives the <repo> basename from the main worktree root, auto-creates /tmp/harness-claude-code/<repo>/signals/, and seeds <agent-id>.meta.json with agent identity, started timestamp, cwd, session id, and empty tool_calls / per_skill_tokens / skills_invoked (dispatch_prompt backfilled at stop). Silent no-op if no agent_id. This marker file is the gate (with the matcher) that limits all runtime-telemetry capture to the four heartbeat-bearing dispatch types. axis-reviewer / e2e-author are matched so their last_seen heartbeat keeps the reconcile reaper from false-reaping a live workflow during the long, GitHub-quiet review and E2E-authoring phases.
runtime-telemetry/pre-tool-use.shPreToolUse on every tool call (no matcher).If a <agent-id>.meta.json exists for the firing agent_id, increments meta.json#tool_calls[<tool>] and, when the tool is Read on a */skills/*/SKILL.md file or Skill with a skill parameter, appends the skill name to meta.json#skills_invoked (first-seen order). No agent_id (main-thread call) → no-op. Always exits 0; never blocks a tool call.
runtime-telemetry/subagent-stop.shSubagentStop once per subagent termination.If a <agent-id>.meta.json exists for the firing agent_id, finalizes it with ended_at, duration_ms, total token_usage (summed across all assistant turns), per_skill_tokens (active-window attribution from the transcript), stop_reason, and dispatch_prompt (backfilled from the transcript's first user turn).

Layout

.claude-plugin/
  plugin.json          # plugin manifest
  marketplace.json     # marketplace manifest (lets users install via /plugin marketplace add)
agents/                # role-based subagents
commands/              # slash commands
skills/                # auto-activating skills (one directory per skill)
workflows/             # deterministic multi-agent Workflow scripts (implement-slice + fix-bug, each with inlined review fan-out)
hooks/                 # PreToolUse / PostToolUse / Subagent hooks (pre-push gate, post-edit fixers, runtime telemetry) + hooks.json

Prior art

The skill / agent layout, lifecycle shape, and TDD discipline here draw on ideas from several public Claude Code repos. We reference them for patterns and taste — every skill, agent, command, and hook in this repo is authored ourselves, not imported. No use skills from <other-repo>; the surface area is ours, the influence is theirs.

Ver o original no GitHub

Bom para

Relacionados