From 6dfe2228e25a05aa64702f103b62629250dab320 Mon Sep 17 00:00:00 2001 From: Giovanni Costagliola Date: Mon, 1 Jun 2026 16:18:49 +0200 Subject: [PATCH] feat(agentic-harness): always offer tool research and maintenance (v0.2.0) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit harness-setup now treats tool research and tool maintenance as a standard part of the plan it presents — asked every run, not skipped until requested. Step 0 also explicitly accepts an optional user-provided starting context. The opt-in framing was the bug: the skill never *asked*, so a build could silently skip tool research. Fixed at the source — Step 1b is reframed from 'never automatic / on request' to 'always offered, run on acceptance'. The safeguard is unchanged: running happens only on an explicit yes, and each tool is still adopted only by a separate per-tool yes. Also: maintenance.md §7 makes tool-maintenance review an always-offered step on existing-harness flows; harness-review flags a missing tools registry as a finding; deliverable checklist asserts the user was asked. Minor bump to 0.2.0 (plugin.json, marketplace.json, repo README) with a changelog entry. --- .claude-plugin/marketplace.json | 2 +- README.md | 2 +- agentic-harness/.claude-plugin/plugin.json | 2 +- agentic-harness/README.md | 5 ++++ .../skills/harness-review/SKILL.md | 6 ++-- agentic-harness/skills/harness-setup/SKILL.md | 28 +++++++++++++++---- .../harness-setup/references/maintenance.md | 8 ++++-- .../references/tool-discovery.md | 17 +++++------ 8 files changed, 49 insertions(+), 21 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 1bf7dd4..41a84dd 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -14,7 +14,7 @@ "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", + "version": "0.2.0", "category": "engineering", "tags": ["harness", "agents", "skills", "scaffolding", "orchestration", "multi-agent", "meta-skill"] }, diff --git a/README.md b/README.md index 5c5c2c4..649fd2b 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ 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 | +| [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.2.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 | diff --git a/agentic-harness/.claude-plugin/plugin.json b/agentic-harness/.claude-plugin/plugin.json index a62ff7f..ccba896 100644 --- a/agentic-harness/.claude-plugin/plugin.json +++ b/agentic-harness/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "agentic-harness", - "version": "0.1.0", + "version": "0.2.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", diff --git a/agentic-harness/README.md b/agentic-harness/README.md index b28c12d..a28bff5 100644 --- a/agentic-harness/README.md +++ b/agentic-harness/README.md @@ -26,3 +26,8 @@ Invoke a skill directly (`/agentic-harness:harness-setup`) or let Claude trigger ## Inspired by The harness concept is inspired by prior work in the community; this is an independent implementation. Credit lives in the repository README. + +## Changelog + +- **0.2.0** — `harness-setup` now always offers tool research (and, on an existing harness, tool maintenance) as part of the plan it presents, and accepts an optional user-provided starting context. Running still requires explicit acceptance, and per-tool adoption is unchanged. `harness-review` flags a missing tools registry as a finding. +- **0.1.0** — Initial release: `harness-setup` and `harness-review`, shared concept docs, and the optional tool-discovery step. diff --git a/agentic-harness/skills/harness-review/SKILL.md b/agentic-harness/skills/harness-review/SKILL.md index b0304b7..7b191af 100644 --- a/agentic-harness/skills/harness-review/SKILL.md +++ b/agentic-harness/skills/harness-review/SKILL.md @@ -70,8 +70,10 @@ From these, classify each skill and agent as **used**, **unused**, **bypassed** happens but around the harness), or **drifted** (present but out of sync). Apply the same lens to registered tools: is each one still used, and is there now a better alternative for its role? Flag tools that look unnecessary or superseded — as findings for `harness-setup`, not -changes you make. The method for reading each signal and making the call is in -`references/usage-assessment.md`. This step is strictly read-only. +changes you make. If there is no tools registry at all, treat that as a finding too — +recommend that `harness-setup` offer tool research — since a harness with no considered +tooling is more often an oversight than a decision. The method for reading each signal and +making the call is in `references/usage-assessment.md`. This step is strictly read-only. ## Step 5: Validate diff --git a/agentic-harness/skills/harness-setup/SKILL.md b/agentic-harness/skills/harness-setup/SKILL.md index 6407e3d..2e200d7 100644 --- a/agentic-harness/skills/harness-setup/SKILL.md +++ b/agentic-harness/skills/harness-setup/SKILL.md @@ -27,8 +27,11 @@ context*, this skill is what acts on it. Always check the current state first, then pick the path. Do not start generating until the plan is confirmed. -1. Read `.claude/agents/`, `.claude/skills/`, and the harness section of `CLAUDE.md`. -2. Branch on what you find: +1. **Take the user's starting context, if any.** This skill accepts an optional context at + the start — domain notes, constraints, tools already in use, or a review context from + `harness-review`. Read it and fold it into everything below. +2. Read `.claude/agents/`, `.claude/skills/`, and the harness section of `CLAUDE.md`. +3. Branch on what you find: - **New build** — no harness, or empty agent/skill dirs → run Steps 1–7 in full. - **Extend** — a harness exists and the request adds or changes an agent or skill → run only the needed steps, per the extension matrix in `references/maintenance.md`. @@ -36,7 +39,15 @@ plan is confirmed. an interactive improvement pass (see `references/maintenance.md`). - **Sync** — the files and the `CLAUDE.md` record disagree → reconcile and record the correction. -3. Summarize what you found and the plan you propose; get the user's confirmation. +4. Present the plan and confirm it before generating. Tool research and tool maintenance are + part of a good harness, so make them part of the plan you present **every run** — don't + wait to be asked: + - **Always ask whether to run tool discovery** (Step 1b), on a new build or an extension. + - **On an existing harness** (extend / apply-review-context / sync), **also ask whether to + run a tool-maintenance review** of the registered `tools.md` (see + `references/maintenance.md`). + Record the answers. Asking is the default; a "no" is a fine answer, but a silent skip is + not. Running happens only on a yes — see Step 1b. ## Step 1: Analyze the domain @@ -47,10 +58,13 @@ plan is confirmed. 4. Read the user's technical level from the conversation and match your wording to it. Explain a term like "assertion" or "schema" when the cues suggest it is unfamiliar. -## Step 1b: Discover tools — optional, on request +## Step 1b: Discover tools — always offered, run on acceptance -Run this only when the user asks for it ("find tools / MCPs / plugins for this project"). -It is never automatic. It can run inside a build or standalone against an existing harness. +Step 0 always offers tool research as part of the plan; run this step when the user accepts. +It can also be triggered on its own later, against an existing harness. Offering is the +default; running is gated on that yes — and adopting any individual candidate is gated on a +separate, explicit per-tool yes (Step 3). Those two gates are the safeguard: the user is +always asked, and nothing is installed behind their back. This skill proposes nothing of its own — the candidates come from a live search, not a built-in catalog: @@ -199,6 +213,8 @@ Before calling a setup or change complete: - [ ] The orchestrator's first phase does a context check (initial / follow-up / partial). - [ ] The `CLAUDE.md` pointer is registered (goal + trigger + change history). - [ ] The change-history table records this change. +- [ ] The user was asked whether to run tool research (and, on an existing harness, tool + maintenance), and the answer was recorded — whatever they chose. - [ ] If tool discovery ran: nothing was adopted without explicit approval, and accepted tools are registered by role (with alternatives) in the orchestrator's `tools.md`. diff --git a/agentic-harness/skills/harness-setup/references/maintenance.md b/agentic-harness/skills/harness-setup/references/maintenance.md index 08da66e..5cc5c64 100644 --- a/agentic-harness/skills/harness-setup/references/maintenance.md +++ b/agentic-harness/skills/harness-setup/references/maintenance.md @@ -100,8 +100,12 @@ For an audit-fix-sync request on an existing harness: ## 7. Periodic tool review If the harness has a tools registry (`references/tools.md` under the orchestrator, produced -by the tool-discovery step), the tools in it are not permanent. Re-evaluate them -periodically — not on a fixed clock, but when a signal warrants it: +by the tool-discovery step), the tools in it are not permanent — they fall out of use, stop +being maintained, or get overtaken. So on any run against an existing harness (extend, apply +a review context, or sync), **always offer a tool-maintenance review** as part of the plan — +the same way `harness-setup` Step 0 offers tool discovery on a build. Offering is the +default; run it when the user accepts. When you do, weigh each registered tool against these +signals: - A registered tool is no longer being used by any agent or skill. - A tool has stopped being maintained, or a better alternative has appeared. diff --git a/agentic-harness/skills/harness-setup/references/tool-discovery.md b/agentic-harness/skills/harness-setup/references/tool-discovery.md index 8cd3a60..202f113 100644 --- a/agentic-harness/skills/harness-setup/references/tool-discovery.md +++ b/agentic-harness/skills/harness-setup/references/tool-discovery.md @@ -1,16 +1,17 @@ # Tool discovery -How the optional, on-request tool-discovery step works: how to brief the search subagent, -how candidates are accepted, and how accepted tools are registered so agents and skills can -use them without hard-coding a tool name. Supplements Step 1b. +How the tool-discovery step works: how to brief the search subagent, how candidates are +accepted, and how accepted tools are registered so agents and skills can use them without +hard-coding a tool name. Supplements Step 1b. ## When it runs -Only when the user asks ("find tools / MCPs / plugins for this project"). It is never part of -an automatic build. It runs equally well during an initial build or standalone against an -existing harness. This skill ships **no catalog of recommendations** — every candidate comes -from a live search and the local configuration, and nothing is adopted without the user's -explicit approval. +Step 0 of `harness-setup` always offers tool research as part of the plan; this step runs +when the user accepts. It can also be triggered on its own ("find tools / MCPs / plugins for +this project"), and runs equally well during an initial build or standalone against an +existing harness. Offering is automatic; running is not — and no individual tool is adopted +without a separate explicit yes. This skill ships **no catalog of recommendations** — every +candidate comes from a live search and the local configuration. ## Step 1: Brief the search subagent