agentic-harness

Purpose

agentic-harness is a Claude Code plugin used to set up, evaluate, and maintain an "agentic harness" in an existing code repository. It focuses on the project-local agents, skills, and orchestrators needed to make the repository work well with Claude Code, rather than directly completing the user's domain work. Its goal is to replace prompts improvised in each session and build a dedicated team for the project, automatically routed by Claude Code.

Main capabilities

• Tailor-made: The generated agents and skills mirror the repository's tech stack, domain, and task types, rather than using generic templates.
• Single entry point: The orchestrator is registered in CLAUDE.md as a hard gate, ensuring every prompt goes through the correct process.
• Coordinate rather than duplicate: When the project already has a spec-driven system or issue tracker, the orchestrator coordinates with it (activating specs, resuming handoffs, pulling ready work, and writing status back), without reimplementing it.
• No lock-in: For spec systems and trackers, it only recommends the most suitable option and delegates installation to that tool's own installer.
• Maintainable and traceable: Every change to the harness must be approved before being written, and is recorded in the change history.
• Learn and improve: harness-review reads the repository's repeated activities and work patterns, and periodically proposes improvements to harness-setup; harness-feedback turns each run into structured, privacy-safe feedback used to improve the tool itself.

Usage

The plugin provides multiple skills, which can be invoked directly (such as /agentic-harness:harness-setup) or triggered by Claude based on context.

• harness-setup: Writer. Analyzes the project, designs the agent team and the skills it uses, generates them into .claude/, builds the orchestrator, and registers the entry pointer in CLAUDE.md. It can also extend an existing harness, apply review context, and record changes.
• harness-review: Read-only. Takes inventory of the harness, detects drift, evaluates the actual usage effectiveness of skills and agents, and generates prioritized improvement suggestions for harness-setup to execute.
• harness-feedback: Closed-loop feedback. Reviews a harness run and drafts feedback in a standard format, redact project-identifying details, and submit a GitHub issue to the upstream repository after explicit consent. It can be provided at the end of a harness-setup or harness-review run, or invoked separately via the /feedback command.
• spec-advisor: Detects whether a project lacks a spec-driven development system and recommends the most suitable option (such as GitHub Spec Kit, OpenSpec, BMAD-METHOD, Agent OS, Taskmaster, AWS Kiro, ADR tools), delegating installation to the corresponding system. Offline-first, scans first, does not intervene if a system already exists, and never writes specs itself.
• tracker-advisor: Detects whether a project lacks an issue tracker suitable for agent-driven work, recommends the most suitable option (such as Beads, Backlog.md, git-bug, git-issues, Beans, or GitHub Issues / Linear / Jira via official channels), and delegates installation. Likewise offline-first, scans first, and does not create issues itself.
• visual-advisor: Selects the visual stack used by the generated toolchain: one review interface (such as lavish's in-browser annotation loop, visual-explainer, or static files), at most two generators (diagrams, dashboards, image APIs, design tools), and one style source. Introduces the applicability of visuals in the domain to the user, invites the user to provide their own visual patterns, and presents domain-specific pros and cons (including cost, privacy, and browser runnability). harness-setup then generates a project {domain}-visuals skill to record these choices.
• harness-doctor: Read-only. Uses deterministic scripts to check what the toolchain's tool registry lists on the machine (plugins, skills, MCP servers, CLIs, API key variables) and reports them as ok, missing, disabled, stale, or broken-link. Proposes fixed installation lines, which harness-setup executes after item-by-item approval. Every generated toolchain gets a self-contained {domain}-setup-check skill.

Component collaboration

The toolchain loop is: review → setup → review. harness-review reads and sorts; harness-setup writes and records. When a software project lacks a matching process layer (spec system or tracker), the advisor provides it alongside the loop, and always delegates installation to the chosen system. Visually different: it is a tool role, visual-advisor runs in tool discovery, is provided on every build, and reuses existing visual tools. harness-doctor sits at the very bottom and is a read-only check of what was actually installed.

Coordination and dual-tracker sync

When a project already has a spec system or tracker, harness-setup makes the generated orchestrator coordinate with it: activate the spec workflow with a context hint, and resume after a clean handoff; pull ready work from the tracker at the entry point, and write status back at integration. Only one owner per concern per phase, no duplicated artifacts. Detection signatures, coordination protocols, and per-system coordination mappings are shared under the shared/ directory. When a project runs both a repo-native tracker and a human-facing tracker (Jira, Linear, GitHub Issues), harness-setup can also generate dual-tracker sync: a project-local tracker-sync skill and agent that keep the SaaS tracker as a projection of the repo-native source of truth—continuous one-way push, one-time ingestion of human-created issues, remote status changes treated as suggestions rather than overwrites. Sync state lives in .tracker-sync/ at the repo root; scheduled headless runs only read and report.

Execution modes and feedback loops

harness-setup uses subagents by default. When members need mid-task conversation and the experimental team tool is enabled (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1), it uses agent teams, and always keeps the subagent fallback. Every run is an opportunity to improve the tool: harness-feedback turns a run into structured, privacy-safe feedback and submits it as a GitHub issue to the upstream repository. The feedback format is defined in shared/feedback-format.md and contains eight required sections (summary, type, what was done, choices made, expected outcome, what actually happened/friction, improvement suggestions, environment) plus optional context. Redaction is applied by default, the exact content is shown before submission and explicit consent is required, and nothing is submitted silently. A GitHub Actions check (feedback-check.yml) verifies whether a feedback issue contains the requiredsections, and when missing automatically comments a checklist and labels it needs-info. tests/validate-feedback.sh keeps the format document, issue template, and CI check in sync.

Skills and commands

You can invoke skills directly (/agentic-harness:harness-setup), or let Claude trigger them from context—this is how toolchain skills are expected to run, because Claude Code has merged commands into skills. One deliberate command included with the plugin is /feedback, a discoverable entry point for the kaizen feedback loop; it simply runs the harness-feedback skill (named /feedback rather than /harness-feedback to avoid conflicting with a skill of the same name).

Installation and validation

After any change, run the structural validation suite (requires jq). Before release or submission to the marketplace, also run the same checks as the review pipeline.

Applicable scenarios and limitations

Suitable for software projects that want to deeply integrate Claude Code into an existing code repository and establish maintainable agentic workflows, especially for teams that already have or need a spec-driven system and issue tracker. Limitations include: the plugin does not perform domain work; it does not write specs or issues itself; installation and configuration are delegated to third-party tools; feedback submission requires explicit consent; some features depend on the experimental team tool and external CLIs (such as gh). The project uses the MIT license, see LICENSE for details.