From d8f35a2864b6282d4e1f324e51cccf4d70c33f09 Mon Sep 17 00:00:00 2001 From: Giovanni Costagliola Date: Mon, 1 Jun 2026 16:48:07 +0200 Subject: [PATCH] feat(agentic-harness): mandatory pre-write change-manifest approval (v0.3.0) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit harness-setup gains Step 2b: before creating, updating, or deleting anything — and before installing or uninstalling any tool — it presents an explicit change manifest (every agent, skill, orchestrator, pointer, and tool action) and writes nothing until the user formally approves the list. Mandatory on every path (new build, extend, apply-review-context, sync). Distinct from the Step 0 plan confirmation (approach, pre-design) and the per-tool acceptance (selection): this is the final go on the concrete artifact list. Tool registration/install/uninstall is deferred to after the manifest approval; tool-discovery.md and maintenance.md are aligned, and the deliverable checklist gains the manifest-approval precondition. Minor bump to 0.3.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 | 1 + agentic-harness/skills/harness-setup/SKILL.md | 35 +++++++++++++++++-- .../harness-setup/references/maintenance.md | 8 +++-- .../references/tool-discovery.md | 4 +++ 7 files changed, 46 insertions(+), 8 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 41a84dd..3a535ca 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.2.0", + "version": "0.3.0", "category": "engineering", "tags": ["harness", "agents", "skills", "scaffolding", "orchestration", "multi-agent", "meta-skill"] }, diff --git a/README.md b/README.md index 649fd2b..8ed37d2 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.2.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.3.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 ccba896..4a87171 100644 --- a/agentic-harness/.claude-plugin/plugin.json +++ b/agentic-harness/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "agentic-harness", - "version": "0.2.0", + "version": "0.3.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 a28bff5..e1ec68e 100644 --- a/agentic-harness/README.md +++ b/agentic-harness/README.md @@ -29,5 +29,6 @@ The harness concept is inspired by prior work in the community; this is an indep ## Changelog +- **0.3.0** — `harness-setup` adds a mandatory pre-write approval gate (Step 2b): it presents an explicit change manifest — every agent, skill, orchestrator, pointer, and tool it will create, update, remove, install, or uninstall — and writes nothing until the user formally approves the list, on every path. - **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-setup/SKILL.md b/agentic-harness/skills/harness-setup/SKILL.md index 2e200d7..2123833 100644 --- a/agentic-harness/skills/harness-setup/SKILL.md +++ b/agentic-harness/skills/harness-setup/SKILL.md @@ -47,7 +47,8 @@ plan is confirmed. 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. + not. Running happens only on a yes — see Step 1b. This confirms the approach; the concrete + list of files and tools is approved separately at Step 2b, before anything is written. ## Step 1: Analyze the domain @@ -75,7 +76,8 @@ built-in catalog: tools already available, so you don't propose what is already there. 2. Present each candidate with the **role** it would fill, what it does, and its trade-off. The user **accepts or rejects each one explicitly**. Adopt only what is accepted. -3. Register accepted tools **by role** in the tools registry under the orchestrator — a +3. Accepted tools become install/register rows in the Step 2b manifest; once that is + approved, register them **by role** in the tools registry under the orchestrator — a `tools.md` file in `.claude/skills/{domain}-orchestrator/references/`. It is a lookup of role → preferred tool → alternative (for when the preferred one is unavailable) → status. Agents and skills reference a tool by its **role**, never by a hard tool name, so the @@ -104,6 +106,33 @@ covers them. criteria table is in `references/agent-design-patterns.md`. Prefer a few focused agents over many thin ones; coordination cost grows with team size. +## Step 2b: Approve the change manifest — required before any write + +Before creating, updating, or deleting anything — and before installing or uninstalling any +tool — present a single explicit **change manifest** and get the user's formal approval. This +is mandatory on every path: new build, extend, apply-review-context, sync. Nothing is written +to `.claude/` or `CLAUDE.md`, and no tool is installed or removed, until the user approves it. + +This is not the Step 0 plan confirmation. Step 0 agrees the approach before the design exists; +the manifest is the concrete, itemized list of exactly what this run will touch, produced once +the design is settled. Writes and installs change the user's repository and environment and are +awkward to undo — one explicit sign-off on the exact list is what keeps the run from making a +change the user did not expect. + +Present it as concrete items, each labelled with its action and target: + +| Action | Target | +|--------|--------| +| create / update / remove | `.claude/agents/{name}.md` (one row per agent) | +| create / update / remove | `.claude/skills/{name}/` (one row per skill) | +| create / update | `.claude/skills/{domain}-orchestrator/` | +| update | `CLAUDE.md` (harness pointer + change-history row) | +| install / uninstall | `{role} -> {tool}` (only if tool discovery or maintenance proposed it) | + +List only the rows that apply. If the user amends the list — drops an agent, declines a tool, +renames a skill — revise and present it again; the approval is of the final list. Once +approved, carry out exactly what was approved in Steps 3–6 — no extra files, no extra installs. + ## Step 3: Generate the agent definitions Write every agent as a file under `.claude/agents/{name}.md` — including agents that use a @@ -200,6 +229,8 @@ orchestrator) are in `references/maintenance.md`. Before calling a setup or change complete: +- [ ] The full change manifest (agents / skills / orchestrator / pointer / tools to create / + update / remove / install / uninstall) was formally approved before any write. - [ ] Every agent is a file under `.claude/agents/` — including built-in types. - [ ] Skills exist under `.claude/skills/` with valid `name` + `description` frontmatter. - [ ] One orchestrator, with data flow, error handling, and test scenarios. diff --git a/agentic-harness/skills/harness-setup/references/maintenance.md b/agentic-harness/skills/harness-setup/references/maintenance.md index 5cc5c64..a105d0d 100644 --- a/agentic-harness/skills/harness-setup/references/maintenance.md +++ b/agentic-harness/skills/harness-setup/references/maintenance.md @@ -90,7 +90,8 @@ For an audit-fix-sync request on an existing harness: composition; produce a discrepancy list; report it to the user. (Read-only inventory and usage assessment are `harness-review`'s job — call it for the deeper read.) 2. **Change incrementally.** Add, modify, or remove one agent or skill at a time. Sync after - each change rather than batching. + each change rather than batching. Present each change in the Step 2b manifest and get + approval before writing — the pre-write approval is mandatory here too. 3. **Record history.** Append the date, change, target, and reason to the `CLAUDE.md` table. 4. **Validate.** Re-check the changed agents and skills structurally; if the change affects triggering, re-check the descriptions; for large changes (an architecture change, or @@ -114,8 +115,9 @@ signals: The split follows the rest of this plugin: assessing whether a tool is still earning its place is a read activity, so it belongs to `harness-review` (it reads the registry as one of -its usage signals); swapping, adding, or retiring a tool is a write, so it comes back here. -When you change the registry, update the affected row's `Last reviewed` date, keep every +its usage signals); swapping, adding, or retiring a tool is a write, so it comes back here — +and a retirement is an uninstall row in the Step 2b manifest, approved before it is carried +out. When you change the registry, update the affected row's `Last reviewed` date, keep every role's alternative current, and record the change in the `CLAUDE.md` history like any other. Because agents and skills reference tools by role, swapping the tool behind a role needs no edits to their files. diff --git a/agentic-harness/skills/harness-setup/references/tool-discovery.md b/agentic-harness/skills/harness-setup/references/tool-discovery.md index 202f113..8a20ee3 100644 --- a/agentic-harness/skills/harness-setup/references/tool-discovery.md +++ b/agentic-harness/skills/harness-setup/references/tool-discovery.md @@ -58,6 +58,10 @@ themselves. ## Step 4: Register accepted tools +Registration and any install or uninstall is a write, so it happens only after the change +manifest is approved (`harness-setup` Step 2b). For a standalone tool run, present a +tools-only manifest and get approval before writing. + Record accepted tools **by role** in the registry under the orchestrator: `.claude/skills/{domain}-orchestrator/references/tools.md`. One registry per harness; the orchestrator owns it. The schema: