feat(agentic-harness): mandatory pre-write change-manifest approval (v0.3.0)

.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"]
     },

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 |

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",

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.

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.

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.

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: