feat: add agentic-harness plugin (harness-setup + harness-review)

.claude-plugin/marketplace.json

@@ -10,6 +10,14 @@
     "license": "MIT"
   },
   "plugins": [
+    {
+      "name": "agentic-harness",
+      "source": "./agentic-harness",
+      "description": "Stand up, assess, and maintain an agentic harness in an existing repo — generate project-specific agent teams and the skills they use, then assess how effectively they are used",
+      "version": "0.1.0",
+      "category": "engineering",
+      "tags": ["harness", "agents", "skills", "scaffolding", "orchestration", "multi-agent", "meta-skill"]
+    },
     {
       "name": "developer-tools",
       "source": "./developer-tools",

CLAUDE.md

@@ -47,3 +47,9 @@ This is a static marketplace — no build steps. Plugins are collections of mark
 ## Shell script conventions
 
 Scripts must be macOS (BSD) compatible — no `grep -P`, no `head -n -1`. Use `grep -E`/`grep -oE` and `awk` instead. Avoid `((VAR++))` with `set -e` (fails when VAR=0); use `VAR=$((VAR + 1))`.
+
+## Git / PR Working Policy
+- Worktree usage: disabled
+- Worktree location: n/a (topic branch in main checkout)
+- Base branch: main
+- Recorded on: 2026-06-01

README.md

@@ -6,13 +6,16 @@ A curated collection of [Claude Code](https://claude.com/claude-code) plugins fo
 
 | Plugin | Description | Category | Version |
 |--------|-------------|----------|---------|
+| [agentic-harness](./agentic-harness) | Stand up, assess, and maintain an agentic harness — generate project-specific agent teams and the skills they use, then assess how effectively they are used | Engineering | 0.1.0 |
 | [developer-tools](./developer-tools) | Developer environment tooling — devcontainer generation, stack detection, infrastructure config | Engineering | 2.4.0 |
 | [human-resources](./human-resources) | HR interview workflow — job descriptions, pre-screening, interview prep, evaluation, compliance | Human Resources | 0.2.0 |
 | [kaizen](./kaizen) | Continuous improvement loops — recursive optimization engine with profiles for Claude Code usage, refactoring, and process improvement | Engineering | 1.0.0 |
 | [plantuml](./plantuml) | PlantUML diagrams — policy-driven authoring, rendering, lint, validate, review, advisor, and migrate | Documentation | 1.0.0 |
 | [project-management](./project-management) | SOW writing, review, estimation, and PMI-compliant PERT analysis — integrated project management pipeline | Operations | 1.0.0 |
 | [tech-writing](./tech-writing) | Technical writing support — documentation structure, style guides, content review | Documentation | 0.1.0 |
 
+> The [`agentic-harness`](./agentic-harness) plugin is inspired by the open-source `harness` plugin by revfactory (Apache-2.0). It is an independent reimplementation under MIT, with its own structure and prose.
+
 ## Installation
 
 Add this marketplace to Claude Code:

agentic-harness/.claude-plugin/plugin.json

@@ -0,0 +1,22 @@
+{
+  "name": "agentic-harness",
+  "version": "0.1.0",
+  "description": "Stand up, assess, and maintain an agentic harness in an existing repo. A meta-tool that generates project-specific agent teams and the skills they use, then assesses how effectively they are used. Two skills: harness-setup (build, extend, maintain) and harness-review (read-only assessment).",
+  "author": {
+    "name": "MrBogomips",
+    "url": "https://github.com/MrBogomips"
+  },
+  "license": "MIT",
+  "keywords": [
+    "harness",
+    "agentic-harness",
+    "agent-team",
+    "skill-architect",
+    "meta-skill",
+    "orchestration",
+    "scaffolding",
+    "agent-scaffolding",
+    "multi-agent",
+    "claude-code-plugin"
+  ]
+}

agentic-harness/README.md

@@ -0,0 +1,28 @@
+# agentic-harness
+
+Stand up, assess, and maintain an **agentic harness** inside an existing repository — the project-local agents, skills, and orchestrator that make a repo work well with Claude Code.
+
+This plugin does not do your domain work. It builds and maintains the agents and skills that do.
+
+## The two skills
+
+- **`harness-setup`** — the writer. Analyzes the project, designs an agent team and the skills they use, generates them into `.claude/`, builds an orchestrator, and registers a pointer in `CLAUDE.md`. Also extends an existing harness, applies a review context, and records every change.
+- **`harness-review`** — read-only. Inventories the harness, detects drift, and assesses how effectively the skills and agents are actually used (from project memory, the `CLAUDE.md` pointer, and the `.claude/` inventory), then produces a prioritized *review context* that `harness-setup` can act on.
+
+The loop: **review → setup → review again.**
+
+## Skills, not commands
+
+Invoke a skill directly (`/agentic-harness:harness-setup`) or let Claude trigger it from context. This plugin ships no slash commands — Claude Code merged commands into skills.
+
+## Execution modes
+
+`harness-setup` defaults to an **agent team** and falls back to **subagents** when the experimental team tools are unavailable. See `shared/execution-modes.md`.
+
+## Relationship to `kaizen`
+
+`kaizen` optimizes assets against measured KPIs. `agentic-harness` builds, assesses, and maintains the harness those assets live in. They compose.
+
+## Inspired by
+
+The harness concept is inspired by prior work in the community; this is an independent implementation. Credit lives in the repository README.

agentic-harness/shared/claude-md-pointer.md

@@ -0,0 +1,61 @@
+# The CLAUDE.md pointer
+
+A target project's `CLAUDE.md` is loaded into context at the start of every session. That
+makes it the right place to record that a harness exists and when it should fire — and the
+wrong place for anything the file system already holds.
+
+## Register a minimal pointer
+
+After a harness is built or changed, write (or update) one short section in the target
+project's `CLAUDE.md`. It carries three things and nothing more:
+
+1. The harness's **goal**, in one line.
+2. The **trigger rule** — which orchestrator skill to use, and for which kind of request.
+3. A **change-history** table.
+
+This is enough for a fresh session: the trigger rule routes domain requests to the
+orchestrator, and the orchestrator handles the rest from the files under `.claude/`.
+
+### Template
+
+````markdown
+## Harness: {domain}
+
+**Goal:** {one line on what this harness produces}
+
+**Trigger:** For {domain} work, use the `{orchestrator-skill-name}` skill. Answer simple
+questions directly.
+
+**Change history:**
+| Date | Change | Target | Reason |
+|------|--------|--------|--------|
+| {YYYY-MM-DD} | Initial setup | All | — |
+````
+
+## What not to put here
+
+Leave these out of `CLAUDE.md`:
+
+- The agent list or the skill list — they live in `.claude/agents/` and `.claude/skills/`,
+  and the orchestrator already knows them. Copying them here creates a second source of
+  truth that drifts.
+- The directory structure — readable straight from the file system.
+- Detailed execution rules — they belong in the skills and the orchestrator.
+
+The pointer is a signpost, not a manifest. Keep it small enough that it stays correct.
+
+## The change-history table
+
+Every write to the harness appends a row. The columns are fixed:
+
+| Date | Change | Target | Reason |
+|------|--------|--------|--------|
+| 2026-04-05 | Initial setup | All | — |
+| 2026-04-07 | Added QA agent | `agents/qa.md` | deliverable-quality gaps reported |
+| 2026-04-10 | Added tone guidance | `skills/content-writer` | output read as too stiff |
+
+The table earns its place: it shows how the harness has evolved and why, which makes
+regressions visible and gives the next reviewer a starting point. Recording history is a
+required step of every harness write — not an optional courtesy.
+
+On periodic review this table can be pruned, preserving valuable information and keeping it readable.

agentic-harness/shared/execution-modes.md

@@ -0,0 +1,85 @@
+# Execution modes
+
+A harness coordinates more than one agent. There are three ways to run that coordination.
+Pick one per harness — or, in hybrid, one per phase — and state the choice explicitly in
+the orchestrator.
+
+## Before you choose: the team-tools caveat
+
+The agent-team mode depends on experimental tools: `TeamCreate`, `SendMessage`,
+`TaskCreate`/`TaskUpdate`, `TeamDelete`. These are **not guaranteed to be available** in a
+given Claude Code build, session, or permission setup. Treat their presence as a runtime
+fact to check, not an assumption.
+
+Because of that, every team-mode harness must define a **subagent fallback**. The subagent
+mode uses only the `Agent` tool, which is broadly available. A harness that can only run as
+a team is brittle; a harness that prefers a team and falls back to subagents is not. Build
+the fallback at the same time as the team path, not later.
+
+When the team tools are missing, do not fail — re-route to the subagent equivalent
+(`Agent` with `run_in_background`) and note in the run that team coordination was
+unavailable. The mapping below makes that re-route mechanical.
+
+## The three modes
+
+| Mode | Use when | Mechanism |
+|------|----------|-----------|
+| **Agent team** (default) | Two or more agents collaborate and benefit from real-time exchange — sharing findings, challenging each other, reconciling conflicts | Members run as peers; coordinate via `TeamCreate` + `SendMessage` + a shared task list (`TaskCreate`/`TaskUpdate`) |
+| **Subagent** (fallback and lightweight default) | A single agent's work, or several independent jobs where only the result matters and inter-agent talk would be overhead | The orchestrator calls the `Agent` tool directly; parallelize with `run_in_background` and collect return values |
+| **Hybrid** | Phases differ in character — e.g. independent collection, then consensus integration | Choose the mode per phase; state each phase's mode in the orchestrator |
+
+The team mode is the *preferred* default when agents genuinely need to talk: cross-checking
+and shared discovery raise quality in a way isolated subagents cannot. But "preferred" is
+conditional on the tools being present and on the work actually needing coordination. When
+either is false, subagents are the right call, not a downgrade.
+
+## Decision order
+
+1. Is this a single agent? → **subagent**. One agent needs no team.
+2. Two or more agents: do they need to exchange information mid-task (challenge findings,
+   resolve conflicts, hand off partial state)? → if yes, **agent team**; if no — only the
+   final results combine — **subagent** is enough and cheaper.
+3. Are the team tools unavailable? → **subagent fallback**, using the mapping below.
+4. Do phases differ markedly in whether coordination helps? → **hybrid**, mode stated per
+   phase.
+
+## Team-to-subagent fallback mapping
+
+When team mode is unavailable, translate it mechanically:
+
+| Team-mode mechanism | Subagent equivalent |
+|---------------------|---------------------|
+| `TeamCreate` + member prompts | One `Agent` call per member, each with its role prompt |
+| Parallel members | `Agent` calls with `run_in_background: true`, collected after |
+| `SendMessage` between members | No direct channel — members can't talk; route shared context through files the orchestrator writes and each agent reads |
+| `TaskCreate`/`TaskUpdate` shared list | The orchestrator holds the task list itself and assigns work in the spawn prompts |
+| Leader synthesis after team | Orchestrator reads each agent's output file/return value and integrates |
+
+The cost of the fallback is real: subagents cannot debate or revise each other mid-flight.
+Where the team relied on that, compensate by adding an explicit integration or review step
+that reconciles the independent outputs afterward.
+
+## Data-passing per mode
+
+State the data-passing method inside the orchestrator. Match it to the mode:
+
+| Method | How | Mode | Fits |
+|--------|-----|------|------|
+| Message-based | direct member-to-member via `SendMessage` | team | real-time coordination, lightweight state hand-off |
+| Task-based | shared work state via `TaskCreate`/`TaskUpdate` | team | progress tracking, dependency management |
+| File-based | write and read files at agreed paths | team + subagent | large or structured deliverables, audit trail |
+| Return-value-based | the `Agent` tool's return message | subagent | the orchestrator collects results directly |
+
+- **Team mode:** task-based for coordination + file-based for deliverables + message-based
+  for live exchange.
+- **Subagent mode:** return-value-based for results + file-based for anything large.
+- **Hybrid:** apply the matching combination per phase, and check the hand-off at phase
+  boundaries — when a team phase feeds a subagent phase, the team's output files become the
+  subagent's inputs.
+
+### File-passing convention
+
+- Keep intermediate work under a `_agents_workspace/` directory in the working tree.
+- Name files `{phase}_{agent}_{artifact}.{ext}` — e.g. `01_analyst_requirements.md`.
+- Write only the final deliverable to the user's target path; preserve `_agents_workspace/` for
+  later inspection rather than deleting it.

agentic-harness/shared/harness-model.md

@@ -0,0 +1,55 @@
+# The harness model
+
+A *harness* is the project-local configuration that lets a repository work well with
+agents. It has three parts, and keeping them separate is what makes a harness
+maintainable.
+
+## The three parts
+
+| Part | Question it answers | Where it lives |
+|------|---------------------|----------------|
+| **Agent** | *Who* does the work | `.claude/agents/{name}.md` |
+| **Skill** | *How* the work is done | `.claude/skills/{name}/SKILL.md` |
+| **Orchestrator** | *When*, and *in what order*, the agents collaborate | a skill, usually `.claude/skills/{domain}-orchestrator/` |
+
+An **agent** is an expert role: a persona, its working principles, its input/output
+contract, and — in team mode — how it communicates with other agents. An agent is small.
+It says who is acting and what that actor cares about, not the step-by-step procedure.
+
+A **skill** is procedural knowledge: the workflow an agent follows, the format it
+produces, the references it consults. A skill can be large. It says how a job is done,
+independent of who does it.
+
+An **orchestrator** is a skill whose subject is the team itself. Where individual skills
+describe one agent's job, the orchestrator describes the collaboration: which agents take
+part, what each produces, how their outputs flow together, and how failures are handled.
+
+## Why separate who from how
+
+The separation is not bookkeeping. It buys three concrete things:
+
+- **Reuse.** A skill written for "how to review an API contract" is usable by any agent
+  that needs it, in this project or the next. Bind the procedure to a single named agent
+  and it stops being portable.
+- **Independent change.** When a deliverable is weak, you revise the skill. When you need
+  a new kind of reviewer, you add an agent. When the workflow order is wrong, you edit the
+  orchestrator. Each fault has one obvious place to fix it.
+- **Survival across sessions.** An agent defined only inline in a prompt vanishes when the
+  session ends. An agent defined as a file is there next time, with its protocol intact
+  and its memory.
+
+## The file rule
+
+Every agent is a file under `.claude/agents/`, even when it uses a built-in type
+(`general-purpose`, `Explore`, `Plan`). Put the built-in type in the call that spawns the
+agent; put the role, principles, and protocol in the file. A role written only into a
+spawn prompt is not reusable and carries no collaboration contract — so it is not part of
+the harness.
+
+## How the parts connect
+
+One agent uses one or more skills; a skill may be shared by several agents. The
+orchestrator names the agents and points each at its skills. The pointer in the target
+project's `CLAUDE.md` names only the orchestrator and its trigger rule — see
+`claude-md-pointer.md`. Nothing in the harness duplicates what the file system already
+states: the agent and skill lists live in `.claude/`, not in `CLAUDE.md`.