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: