@harness-engineering/cli 4.1.0 → 4.2.0

package/dist/agents/skills/claude-code/harness-autopilot/SKILL.md

@@ -108,6 +108,37 @@ On return: read `planPath` from `{sessionDir}/handoff.json`. Complexity override
 
 ### EXECUTE
 
+**Pre-dispatch: plan parallelization (standard automatic parallelism).** Before dispatching tasks, decide the safe parallel structure. This is orchestration, not reimplementation — autopilot chooses HOW to dispatch; the persona agents still do the work.
+
+1. Collect the phase's tasks with their `files` and `dependsOn` (from the plan's task headers). Call the `plan_parallelization` MCP tool:
+
+   ```json
+   {
+     "path": "<project-root>",
+     "tasks": [{ "id": "task-1", "files": ["..."], "dependsOn": [] }],
+     "depth": 1
+   }
+   ```
+
+   It returns a `ParallelizationPlan`: `waves[]` (each `{ tasks, severity, firing, analysisLevel }`), `serialized[]`, `cyclic[]`, `narration`.
+
+2. **If `cyclic` is non-empty:** STOP. Surface the cycle and route back to PLAN/APPROVE_PLAN (a dependency cycle is a plan defect). Do not dispatch.
+
+3. **Announce (announce-and-proceed):** emit `narration` verbatim. Do NOT pause here — announcing is not a gate.
+
+4. **Dispatch in dependency order — prerequisites first, then waves in array order:**
+   - First, run every task in `serialized` (high-severity-group / cycle-adjacent members) **serially**, one `harness-task-executor` per task, in listed order. These are cross-bucket prerequisites: they MUST complete before any wave that depends on them.
+   - Then process `waves` **in array order**. The `waves` array is already topologically sorted (earlier waves are prerequisites of later ones). Do NOT reorder waves and do NOT key dispatch off the `firing` field alone — the Phase-2 cross-bucket cap (a wave depending on a serialized/cyclic task is downgraded to `confirm` and marked "cross-bucket prerequisite gates this wave" in `narration`) is only sound if serialized/cyclic ran first and waves run in order.
+
+5. **For each wave, honor its `firing`:**
+   - `auto-dispatch` (multi-task): emit that wave's line from `narration`, then dispatch the wave via the **harness-parallel-agents** skill with **worktree-per-unit isolation** per `docs/guides/agent-worktree-patterns.md` ("Worktree-per-Milestone" / "Parallel Agent Work": one worktree per task, sequential commits, squash-merge at integrate). **Announce and proceed — do NOT stop for confirmation.**
+   - `confirm`: surface the wave and its `narration` line, then take exactly ONE plain-text confirmation — "Dispatch wave [{tasks}] in parallel? (yes / serial)". `yes` → dispatch via harness-parallel-agents (worktree-per-unit). `serial` or decline → run the wave's tasks serially (`harness-task-executor` each). Record the choice in `decisions[]`.
+   - `serialize`, or any single-task wave: run serially via `harness-task-executor`, exactly as today.
+
+6. **Serial fallback is preserved** when a phase has fewer than `minWaveSize` (default 3) independent tasks, when a `confirm` is declined, or when no graph is available and the human does not confirm — honoring the standing "when in doubt, run serially" default.
+
+Each dispatched unit (parallel wave or serial task) then follows the existing per-task contract below (state.json per task, checkpoints, retry budget).
+
 Dispatch harness-task-executor:
 
 ```

package/dist/agents/skills/claude-code/harness-catalog-retrospective/SKILL.md

@@ -0,0 +1,124 @@
+# Harness Catalog Retrospective
+
+> Monthly retrospective over skill-adoption telemetry. Reads `.harness/metrics/adoption.jsonl`, ranks the most-invoked, most-failing, and abandoned-mid-workflow skills, flags ever-invoked skills that have gone quiet, and reports how much of the catalog emits any telemetry at all. Produces a dated Markdown report and surfaces the highlights that warrant follow-up. Compounding-via-learning at the catalog grain.
+
+## When to Use
+
+- On a regular cadence (monthly is the intended grain) to review how the skill catalog is actually being used.
+- After a milestone, to see which skills carried the work and which never fired.
+- When deciding what to prune, fix, or promote in the catalog — the report feeds catalog-rationalization work.
+- NOT as a real-time dashboard — for point-in-time lookups use `harness adoption skills` / `harness adoption recent`.
+- NOT when `.harness/metrics/adoption.jsonl` is absent or empty (the report will be honest but empty; there is nothing to retrospect on yet).
+
+## Process
+
+### Iron Law
+
+**Separate real signal from telemetry gaps before you recommend anything.** The single most common misread of this data is treating "no telemetry" as "abandoned." Adoption records are emitted only from instrumented entry points, so a skill with zero records is usually uninstrumented, not unused. The report's coverage line and the stale-skills section exist to keep that distinction visible — never collapse it.
+
+---
+
+### Phase 1: SCAN — Derive the Report
+
+1. Run the retrospective command from the project root:
+
+   ```bash
+   harness adoption retrospective            # writes docs/retrospectives/<date>.md
+   harness adoption retrospective --no-write # print to stdout without writing a file
+   harness adoption retrospective --json     # structured output for further processing
+   ```
+
+   Optional flags: `--inactive-days <n>` (stale threshold, default 90), `--top <n>` (rows per section, default 10), `--out <path>` (override the output file).
+
+2. The command reads `.harness/metrics/adoption.jsonl` via `readAdoptionRecords`, derives the report via `getCatalogRetrospectiveReport`, and renders it via `renderRetrospectiveMarkdown` (all in `@harness-engineering/core`). Coverage context is computed against the skills discovered under `agents/skills/claude-code/`; when that directory is absent (a consumer project), the coverage line is omitted rather than reporting a false zero.
+
+3. If there are no records, say so plainly and stop: "No adoption telemetry found at `.harness/metrics/adoption.jsonl`. Nothing to retrospect on yet."
+
+### Phase 2: INTERPRET — Signal vs. Noise
+
+Read the report with these discriminations:
+
+- **Coverage line first.** "N/total catalog skills have emitted telemetry" frames everything below it. A low ratio means the rankings describe the _instrumented_ slice, not the whole catalog. State the ratio explicitly in your summary.
+- **Failing skills are not automatically broken.** Some commands fail _by design_ (a gate like `ci.check` returning non-zero on a real violation is the gate working). Before flagging a high failure rate as a problem, note whether the skill is a checker/gate whose failures are expected. Call out only failures that look like defects (crashes, unexpected non-zero on clean input).
+- **Abandoned mid-workflow** uses the broadened definition: an explicit `abandoned` outcome, or a non-completed run that had already reached ≥1 phase. Small counts here are meaningful — a workflow skill people start and bail out of mid-way is a UX signal even at n=1.
+- **Stale skills** are drawn only from _ever-invoked_ skills quiet ≥ the threshold. When the record window is shorter than the threshold, the section says so and reports nothing — do not present that emptiness as "everything is healthy."
+
+### Phase 3: REPORT — Surface and Recommend
+
+1. Confirm where the report was written (`docs/retrospectives/<date>.md`) or present the rendered Markdown.
+2. Summarize the 3–5 findings that actually warrant action, each tied to a section and a number. Prefer specifics ("`cli/review-ci` failed 23/23 — likely a real defect, worth a look") over restating the tables.
+3. When the coverage ratio is the dominant finding (e.g. most of the catalog is uninstrumented), name that as the top follow-up: instrumentation, not pruning, is the lever.
+4. Do not delete, prune, or edit skills from this skill — it reports. Hand any pruning decision to the human or to catalog-rationalization work.
+
+---
+
+## Harness Integration
+
+- **`harness adoption retrospective`** — the CLI entry point (a subcommand of the existing `adoption` command group). Writes `docs/retrospectives/<date>.md` by default.
+- **`getCatalogRetrospectiveReport` / `renderRetrospectiveMarkdown` / `isAbandonedMidWorkflow`** — the pure aggregation + render functions in `@harness-engineering/core` (`packages/core/src/adoption/retrospective.ts`). Callers can supply a fixed `now` and `catalogSkills` for deterministic output.
+- **`readAdoptionRecords`** — reads and parses `.harness/metrics/adoption.jsonl` (read-only; the file is appended by the adoption-tracker hook, never by this skill).
+- **`harness adoption skills` / `recent` / `skill <name>`** — the point-in-time siblings; this skill is the periodic, persisted counterpart.
+
+## Success Criteria
+
+1. The retrospective is derived from `.harness/metrics/adoption.jsonl` without mutating it.
+2. The report ranks top-invoked, top-failing, and abandoned-mid-workflow skills, and flags ever-invoked stale skills.
+3. The report states telemetry coverage (how much of the catalog emits any signal) when the catalog is discoverable.
+4. The stale-skills section notes when the record window is shorter than the inactivity threshold instead of silently reporting zero.
+5. The summary separates real signal (defect-shaped failures, mid-workflow abandonment) from telemetry gaps (uninstrumented skills) and from expected gate failures.
+6. A dated report is written to `docs/retrospectives/<date>.md` (unless `--no-write`/`--json` is requested).
+7. The skill recommends but never prunes, edits, or deletes catalog skills.
+
+## Rationalizations to Reject
+
+| Rationalization                                                                        | Reality                                                                                                                                                             |
+| -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| "756 skills have no telemetry, so 756 skills are abandoned — recommend deleting them." | Zero telemetry almost always means _uninstrumented_, not unused. The coverage line exists to prevent exactly this misread; the fix is instrumentation, not pruning. |
+| "`ci.check` fails 97% of the time — it's broken."                                      | A gate returning non-zero on a real violation is the gate working. Check whether the skill is a checker before flagging its failures as defects.                    |
+| "The stale section is empty, so the catalog is healthy."                               | If the record window is shorter than the threshold, the signal simply cannot fire yet. Empty ≠ healthy; report the window caveat.                                   |
+| "n=1 abandonment is noise, ignore it."                                                 | A workflow skill users start and bail out of mid-way is a UX signal even at low n. Surface it; let the human weigh it.                                              |
+| "I'll prune the low-usage skills while I'm here."                                      | This skill reports; it does not prune. Pruning is a human/catalog-rationalization decision.                                                                         |
+
+## Examples
+
+### Example: Monthly retrospective on the dogfood repo
+
+**Context:** ~67 days of telemetry (3.2k records) across 50 invoked skills, run at month end.
+
+**Phase 1 — SCAN:**
+
+```bash
+harness adoption retrospective
+# → Catalog retrospective written to docs/retrospectives/2026-07-06.md
+#   3246 records · 50 skills · window 67d
+```
+
+**Phase 2 — INTERPRET:** The report's overview leads with `Telemetry coverage: 5/761 catalog skills have emitted telemetry (756 never invoked)`. Top-invoked is dominated by `cli/*` commands; `cli/ci.check` shows a 97% failure rate; the abandoned-mid-workflow section lists four workflow skills at n=1; the stale section is empty with the note that the 67-day window is shorter than the 90-day threshold.
+
+**Phase 3 — REPORT:**
+
+```
+Retrospective written to docs/retrospectives/2026-07-06.md. Findings that warrant action:
+
+1. Coverage is the headline: only 5/761 catalog skills emit any telemetry. The rankings
+   describe the instrumented slice, not the catalog. Top follow-up is instrumentation, not pruning.
+2. `cli/ci.check` failed 97% (721/741) — but it is a gate; non-zero on a real violation is
+   expected. Not flagged as a defect.
+3. `cli/review-ci` failed 23/23 (100%) — defect-shaped, worth a look. Routed to debugging.
+4. Four workflow skills were abandoned mid-run (n=1 each) — low volume, a UX signal to watch.
+5. Stale skills: none — the 67-day window can't satisfy the 90-day threshold yet.
+```
+
+No skills were pruned or edited — the pruning decision is left to the human.
+
+## Gates
+
+- **No mutation of `adoption.jsonl`.** The telemetry file is read-only input.
+- **No catalog edits.** This skill never adds, edits, or deletes skills — it only reports on them.
+- **Coverage must be stated when discoverable.** If the catalog can be scanned, the summary must include the telemetry-coverage ratio so rankings are read in context.
+
+## Escalation
+
+- **When there are no records:** State that telemetry is absent/empty and stop. Suggest confirming the adoption-tracker hook is installed if telemetry is unexpectedly missing.
+- **When coverage is very low:** Name instrumentation as the top follow-up and note that the rankings describe only the instrumented slice.
+- **When a failing skill looks like a real defect:** Flag it specifically (skill, failure count/rate, why it looks defect-shaped) and route it to debugging or an issue, rather than burying it in the table.

package/dist/agents/skills/claude-code/harness-catalog-retrospective/skill.yaml

@@ -0,0 +1,48 @@
+name: harness-catalog-retrospective
+version: '1.0.0'
+description: Monthly retrospective over skill-adoption telemetry — ranks most-invoked, failing, and abandoned-mid-workflow skills, flags stale ones, and reports catalog telemetry coverage
+stability: static
+cognitive_mode: analytical-reporter
+triggers:
+  - manual
+  - on_milestone
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools:
+  - Bash
+  - Read
+  - Glob
+  - Grep
+cli:
+  command: harness skill run harness-catalog-retrospective
+  args:
+    - name: path
+      description: Project root path
+      required: false
+    - name: inactive-days
+      description: 'Inactivity threshold in days for the stale-skills section (default: 90)'
+      required: false
+mcp:
+  tool: run_skill
+  input:
+    skill: harness-catalog-retrospective
+    path: string
+type: rigid
+tier: 2
+phases:
+  - name: scan
+    description: Read adoption telemetry and derive the retrospective report
+    required: true
+  - name: interpret
+    description: Read the rankings and coverage, separating real signal from telemetry gaps
+    required: true
+  - name: report
+    description: Write the dated report and surface highlights plus recommendations
+    required: true
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/claude-code/harness-execution/SKILL.md

@@ -131,6 +131,19 @@ RMH005 (`harness validate`).
 
    - If no roadmap row matches this plan (e.g. ad-hoc execution), skip the claim.
 
+#### Step 0.5: Plan parallelization (standard automatic parallelism)
+
+Before the per-task loop, decide the safe parallel structure so independent tasks dispatch concurrently by default (no human typing "in parallel").
+
+1. Collect this run's tasks with their `files` and `dependsOn` (from the plan's task headers) and call the `plan_parallelization` MCP tool (`{ path, tasks, depth: 1 }`). It returns `ParallelizationPlan` (`waves[]`, `serialized[]`, `cyclic[]`, `narration`).
+2. If `cyclic` is non-empty, STOP and escalate (dependency cycle = plan defect). Do not execute.
+3. Emit `narration` (announce-and-proceed — do not pause).
+4. Run `serialized` tasks first (serially, in order — cross-bucket prerequisites), then process `waves` **in array order** (topologically sorted; do not reorder, do not key off `firing` alone).
+5. Per wave: `auto-dispatch` (multi-task) → dispatch the wave via **harness-parallel-agents** with worktree-per-unit isolation (`docs/guides/agent-worktree-patterns.md`), announce and proceed; `confirm` → one plain-text confirmation, then parallel or serial per the answer; `serialize` / single-task → run through the per-task loop below serially.
+6. **Serial fallback preserved:** when independent tasks < `minWaveSize` (default 3), a `confirm` is declined, or no graph is available and the human does not confirm, run every task through the per-task loop below serially — the standing "when in doubt, run serially" default.
+
+Tasks dispatched into a parallel wave are executed by harness-parallel-agents' focused agents; tasks that fall to serial run through the loop below unchanged.
+
 For each task, starting from current position:
 
 1. **Read task instructions completely** before writing any code.

package/dist/agents/skills/claude-code/harness-parallel-agents/SKILL.md

@@ -2,12 +2,15 @@
 
 > Dispatch independent tasks to concurrent agents, integrate results, and verify no conflicts. Only for truly independent problems.
 
+**Invoked automatically by `harness-autopilot` (and standalone `harness-execution`), not only manually.** When a plan's phase has an auto-dispatch wave, the execution loop calls this skill to run that wave. In that mode the caller supplies worktree-per-unit isolation per `docs/guides/agent-worktree-patterns.md` (one worktree per task, sequential commits, squash-merge on integrate) and has already verified independence via `plan_parallelization`; this skill still owns the focused agent briefs (Step 2), concurrent dispatch (Step 3), and integration/verification (Steps 4–5). Manual invocation (a human asking to "work in parallel") continues to work unchanged.
+
 ## When to Use
 
 - When 3 or more tasks are truly independent (no shared state, no shared files, different subsystems)
 - When tasks involve investigation or implementation in separate parts of the codebase
 - When parallel execution would meaningfully reduce wall-clock time
 - When a plan has tasks explicitly marked as parallelizable
+- When `harness-autopilot`/`harness-execution` reaches an `auto-dispatch` (or confirmed) wave from `plan_parallelization` — this skill is the wave's dispatcher
 - NOT when failures across tasks might be related (investigate serially to find the common cause)
 - NOT when tasks need full system understanding to complete correctly
 - NOT when agents would modify the same files or shared state

package/dist/agents/skills/claude-code/harness-planning/SKILL.md

@@ -256,7 +256,7 @@ Report progress: `**[Phase 2/4]** DECOMPOSE — mapping file structure and creat
 ### Phase 3: SEQUENCE — Order Tasks and Identify Dependencies
 
 1. **Order by dependency.** Types before implementations. Implementations before integrations. Integration tasks (tagged `category: "integration"`) after all implementation tasks. Tests alongside implementations (same task, TDD style).
-2. **Identify parallel opportunities.** Tasks touching different subsystems with no shared state can be marked parallelizable.
+2. **Identify parallel opportunities and record dependency edges.** Tasks touching different subsystems with no shared state can run in parallel. Record each task's real dependencies as `dependsOn` (the task IDs it must follow) in the task header `**Depends on:**` line, and keep the task's `**Files:**` list accurate — together these are exactly the edges `plan_parallelization` consumes (explicit `dependsOn` unioned with file-overlap edges) to build the wave DAG at execution time. A task with no dependencies records `**Depends on:** none`.
 3. **Number tasks sequentially.** Use `Task 1`, `Task 2`, etc. Dependencies reference task numbers.
 4. **Estimate total time.** Sum 2-5 minutes per task. If total exceeds available time, identify a milestone boundary for pausing.
 
@@ -327,6 +327,8 @@ One sentence.
 
 **Depends on:** none | **Files:** path/to/file.ts, path/to/file.test.ts
 
+<!-- `Depends on` lists the task IDs this task must follow (its `dependsOn` edges); `Files` is the independence-checking input. Both feed `plan_parallelization` during execution. -->
+
 1. Create test file with exact test code
 2. Run test — observe failure
 3. Create implementation with exact code

package/dist/agents/skills/codex/harness-autopilot/SKILL.md

@@ -108,6 +108,37 @@ On return: read `planPath` from `{sessionDir}/handoff.json`. Complexity override
 
 ### EXECUTE
 
+**Pre-dispatch: plan parallelization (standard automatic parallelism).** Before dispatching tasks, decide the safe parallel structure. This is orchestration, not reimplementation — autopilot chooses HOW to dispatch; the persona agents still do the work.
+
+1. Collect the phase's tasks with their `files` and `dependsOn` (from the plan's task headers). Call the `plan_parallelization` MCP tool:
+
+   ```json
+   {
+     "path": "<project-root>",
+     "tasks": [{ "id": "task-1", "files": ["..."], "dependsOn": [] }],
+     "depth": 1
+   }
+   ```
+
+   It returns a `ParallelizationPlan`: `waves[]` (each `{ tasks, severity, firing, analysisLevel }`), `serialized[]`, `cyclic[]`, `narration`.
+
+2. **If `cyclic` is non-empty:** STOP. Surface the cycle and route back to PLAN/APPROVE_PLAN (a dependency cycle is a plan defect). Do not dispatch.
+
+3. **Announce (announce-and-proceed):** emit `narration` verbatim. Do NOT pause here — announcing is not a gate.
+
+4. **Dispatch in dependency order — prerequisites first, then waves in array order:**
+   - First, run every task in `serialized` (high-severity-group / cycle-adjacent members) **serially**, one `harness-task-executor` per task, in listed order. These are cross-bucket prerequisites: they MUST complete before any wave that depends on them.
+   - Then process `waves` **in array order**. The `waves` array is already topologically sorted (earlier waves are prerequisites of later ones). Do NOT reorder waves and do NOT key dispatch off the `firing` field alone — the Phase-2 cross-bucket cap (a wave depending on a serialized/cyclic task is downgraded to `confirm` and marked "cross-bucket prerequisite gates this wave" in `narration`) is only sound if serialized/cyclic ran first and waves run in order.
+
+5. **For each wave, honor its `firing`:**
+   - `auto-dispatch` (multi-task): emit that wave's line from `narration`, then dispatch the wave via the **harness-parallel-agents** skill with **worktree-per-unit isolation** per `docs/guides/agent-worktree-patterns.md` ("Worktree-per-Milestone" / "Parallel Agent Work": one worktree per task, sequential commits, squash-merge at integrate). **Announce and proceed — do NOT stop for confirmation.**
+   - `confirm`: surface the wave and its `narration` line, then take exactly ONE plain-text confirmation — "Dispatch wave [{tasks}] in parallel? (yes / serial)". `yes` → dispatch via harness-parallel-agents (worktree-per-unit). `serial` or decline → run the wave's tasks serially (`harness-task-executor` each). Record the choice in `decisions[]`.
+   - `serialize`, or any single-task wave: run serially via `harness-task-executor`, exactly as today.
+
+6. **Serial fallback is preserved** when a phase has fewer than `minWaveSize` (default 3) independent tasks, when a `confirm` is declined, or when no graph is available and the human does not confirm — honoring the standing "when in doubt, run serially" default.
+
+Each dispatched unit (parallel wave or serial task) then follows the existing per-task contract below (state.json per task, checkpoints, retry budget).
+
 Dispatch harness-task-executor:
 
 ```

package/dist/agents/skills/codex/harness-catalog-retrospective/SKILL.md

@@ -0,0 +1,124 @@
+# Harness Catalog Retrospective
+
+> Monthly retrospective over skill-adoption telemetry. Reads `.harness/metrics/adoption.jsonl`, ranks the most-invoked, most-failing, and abandoned-mid-workflow skills, flags ever-invoked skills that have gone quiet, and reports how much of the catalog emits any telemetry at all. Produces a dated Markdown report and surfaces the highlights that warrant follow-up. Compounding-via-learning at the catalog grain.
+
+## When to Use
+
+- On a regular cadence (monthly is the intended grain) to review how the skill catalog is actually being used.
+- After a milestone, to see which skills carried the work and which never fired.
+- When deciding what to prune, fix, or promote in the catalog — the report feeds catalog-rationalization work.
+- NOT as a real-time dashboard — for point-in-time lookups use `harness adoption skills` / `harness adoption recent`.
+- NOT when `.harness/metrics/adoption.jsonl` is absent or empty (the report will be honest but empty; there is nothing to retrospect on yet).
+
+## Process
+
+### Iron Law
+
+**Separate real signal from telemetry gaps before you recommend anything.** The single most common misread of this data is treating "no telemetry" as "abandoned." Adoption records are emitted only from instrumented entry points, so a skill with zero records is usually uninstrumented, not unused. The report's coverage line and the stale-skills section exist to keep that distinction visible — never collapse it.
+
+---
+
+### Phase 1: SCAN — Derive the Report
+
+1. Run the retrospective command from the project root:
+
+   ```bash
+   harness adoption retrospective            # writes docs/retrospectives/<date>.md
+   harness adoption retrospective --no-write # print to stdout without writing a file
+   harness adoption retrospective --json     # structured output for further processing
+   ```
+
+   Optional flags: `--inactive-days <n>` (stale threshold, default 90), `--top <n>` (rows per section, default 10), `--out <path>` (override the output file).
+
+2. The command reads `.harness/metrics/adoption.jsonl` via `readAdoptionRecords`, derives the report via `getCatalogRetrospectiveReport`, and renders it via `renderRetrospectiveMarkdown` (all in `@harness-engineering/core`). Coverage context is computed against the skills discovered under `agents/skills/claude-code/`; when that directory is absent (a consumer project), the coverage line is omitted rather than reporting a false zero.
+
+3. If there are no records, say so plainly and stop: "No adoption telemetry found at `.harness/metrics/adoption.jsonl`. Nothing to retrospect on yet."
+
+### Phase 2: INTERPRET — Signal vs. Noise
+
+Read the report with these discriminations:
+
+- **Coverage line first.** "N/total catalog skills have emitted telemetry" frames everything below it. A low ratio means the rankings describe the _instrumented_ slice, not the whole catalog. State the ratio explicitly in your summary.
+- **Failing skills are not automatically broken.** Some commands fail _by design_ (a gate like `ci.check` returning non-zero on a real violation is the gate working). Before flagging a high failure rate as a problem, note whether the skill is a checker/gate whose failures are expected. Call out only failures that look like defects (crashes, unexpected non-zero on clean input).
+- **Abandoned mid-workflow** uses the broadened definition: an explicit `abandoned` outcome, or a non-completed run that had already reached ≥1 phase. Small counts here are meaningful — a workflow skill people start and bail out of mid-way is a UX signal even at n=1.
+- **Stale skills** are drawn only from _ever-invoked_ skills quiet ≥ the threshold. When the record window is shorter than the threshold, the section says so and reports nothing — do not present that emptiness as "everything is healthy."
+
+### Phase 3: REPORT — Surface and Recommend
+
+1. Confirm where the report was written (`docs/retrospectives/<date>.md`) or present the rendered Markdown.
+2. Summarize the 3–5 findings that actually warrant action, each tied to a section and a number. Prefer specifics ("`cli/review-ci` failed 23/23 — likely a real defect, worth a look") over restating the tables.
+3. When the coverage ratio is the dominant finding (e.g. most of the catalog is uninstrumented), name that as the top follow-up: instrumentation, not pruning, is the lever.
+4. Do not delete, prune, or edit skills from this skill — it reports. Hand any pruning decision to the human or to catalog-rationalization work.
+
+---
+
+## Harness Integration
+
+- **`harness adoption retrospective`** — the CLI entry point (a subcommand of the existing `adoption` command group). Writes `docs/retrospectives/<date>.md` by default.
+- **`getCatalogRetrospectiveReport` / `renderRetrospectiveMarkdown` / `isAbandonedMidWorkflow`** — the pure aggregation + render functions in `@harness-engineering/core` (`packages/core/src/adoption/retrospective.ts`). Callers can supply a fixed `now` and `catalogSkills` for deterministic output.
+- **`readAdoptionRecords`** — reads and parses `.harness/metrics/adoption.jsonl` (read-only; the file is appended by the adoption-tracker hook, never by this skill).
+- **`harness adoption skills` / `recent` / `skill <name>`** — the point-in-time siblings; this skill is the periodic, persisted counterpart.
+
+## Success Criteria
+
+1. The retrospective is derived from `.harness/metrics/adoption.jsonl` without mutating it.
+2. The report ranks top-invoked, top-failing, and abandoned-mid-workflow skills, and flags ever-invoked stale skills.
+3. The report states telemetry coverage (how much of the catalog emits any signal) when the catalog is discoverable.
+4. The stale-skills section notes when the record window is shorter than the inactivity threshold instead of silently reporting zero.
+5. The summary separates real signal (defect-shaped failures, mid-workflow abandonment) from telemetry gaps (uninstrumented skills) and from expected gate failures.
+6. A dated report is written to `docs/retrospectives/<date>.md` (unless `--no-write`/`--json` is requested).
+7. The skill recommends but never prunes, edits, or deletes catalog skills.
+
+## Rationalizations to Reject
+
+| Rationalization                                                                        | Reality                                                                                                                                                             |
+| -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| "756 skills have no telemetry, so 756 skills are abandoned — recommend deleting them." | Zero telemetry almost always means _uninstrumented_, not unused. The coverage line exists to prevent exactly this misread; the fix is instrumentation, not pruning. |
+| "`ci.check` fails 97% of the time — it's broken."                                      | A gate returning non-zero on a real violation is the gate working. Check whether the skill is a checker before flagging its failures as defects.                    |
+| "The stale section is empty, so the catalog is healthy."                               | If the record window is shorter than the threshold, the signal simply cannot fire yet. Empty ≠ healthy; report the window caveat.                                   |
+| "n=1 abandonment is noise, ignore it."                                                 | A workflow skill users start and bail out of mid-way is a UX signal even at low n. Surface it; let the human weigh it.                                              |
+| "I'll prune the low-usage skills while I'm here."                                      | This skill reports; it does not prune. Pruning is a human/catalog-rationalization decision.                                                                         |
+
+## Examples
+
+### Example: Monthly retrospective on the dogfood repo
+
+**Context:** ~67 days of telemetry (3.2k records) across 50 invoked skills, run at month end.
+
+**Phase 1 — SCAN:**
+
+```bash
+harness adoption retrospective
+# → Catalog retrospective written to docs/retrospectives/2026-07-06.md
+#   3246 records · 50 skills · window 67d
+```
+
+**Phase 2 — INTERPRET:** The report's overview leads with `Telemetry coverage: 5/761 catalog skills have emitted telemetry (756 never invoked)`. Top-invoked is dominated by `cli/*` commands; `cli/ci.check` shows a 97% failure rate; the abandoned-mid-workflow section lists four workflow skills at n=1; the stale section is empty with the note that the 67-day window is shorter than the 90-day threshold.
+
+**Phase 3 — REPORT:**
+
+```
+Retrospective written to docs/retrospectives/2026-07-06.md. Findings that warrant action:
+
+1. Coverage is the headline: only 5/761 catalog skills emit any telemetry. The rankings
+   describe the instrumented slice, not the catalog. Top follow-up is instrumentation, not pruning.
+2. `cli/ci.check` failed 97% (721/741) — but it is a gate; non-zero on a real violation is
+   expected. Not flagged as a defect.
+3. `cli/review-ci` failed 23/23 (100%) — defect-shaped, worth a look. Routed to debugging.
+4. Four workflow skills were abandoned mid-run (n=1 each) — low volume, a UX signal to watch.
+5. Stale skills: none — the 67-day window can't satisfy the 90-day threshold yet.
+```
+
+No skills were pruned or edited — the pruning decision is left to the human.
+
+## Gates
+
+- **No mutation of `adoption.jsonl`.** The telemetry file is read-only input.
+- **No catalog edits.** This skill never adds, edits, or deletes skills — it only reports on them.
+- **Coverage must be stated when discoverable.** If the catalog can be scanned, the summary must include the telemetry-coverage ratio so rankings are read in context.
+
+## Escalation
+
+- **When there are no records:** State that telemetry is absent/empty and stop. Suggest confirming the adoption-tracker hook is installed if telemetry is unexpectedly missing.
+- **When coverage is very low:** Name instrumentation as the top follow-up and note that the rankings describe only the instrumented slice.
+- **When a failing skill looks like a real defect:** Flag it specifically (skill, failure count/rate, why it looks defect-shaped) and route it to debugging or an issue, rather than burying it in the table.

package/dist/agents/skills/codex/harness-catalog-retrospective/skill.yaml

@@ -0,0 +1,48 @@
+name: harness-catalog-retrospective
+version: '1.0.0'
+description: Monthly retrospective over skill-adoption telemetry — ranks most-invoked, failing, and abandoned-mid-workflow skills, flags stale ones, and reports catalog telemetry coverage
+stability: static
+cognitive_mode: analytical-reporter
+triggers:
+  - manual
+  - on_milestone
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools:
+  - Bash
+  - Read
+  - Glob
+  - Grep
+cli:
+  command: harness skill run harness-catalog-retrospective
+  args:
+    - name: path
+      description: Project root path
+      required: false
+    - name: inactive-days
+      description: 'Inactivity threshold in days for the stale-skills section (default: 90)'
+      required: false
+mcp:
+  tool: run_skill
+  input:
+    skill: harness-catalog-retrospective
+    path: string
+type: rigid
+tier: 2
+phases:
+  - name: scan
+    description: Read adoption telemetry and derive the retrospective report
+    required: true
+  - name: interpret
+    description: Read the rankings and coverage, separating real signal from telemetry gaps
+    required: true
+  - name: report
+    description: Write the dated report and surface highlights plus recommendations
+    required: true
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/codex/harness-execution/SKILL.md

@@ -131,6 +131,19 @@ RMH005 (`harness validate`).
 
    - If no roadmap row matches this plan (e.g. ad-hoc execution), skip the claim.
 
+#### Step 0.5: Plan parallelization (standard automatic parallelism)
+
+Before the per-task loop, decide the safe parallel structure so independent tasks dispatch concurrently by default (no human typing "in parallel").
+
+1. Collect this run's tasks with their `files` and `dependsOn` (from the plan's task headers) and call the `plan_parallelization` MCP tool (`{ path, tasks, depth: 1 }`). It returns `ParallelizationPlan` (`waves[]`, `serialized[]`, `cyclic[]`, `narration`).
+2. If `cyclic` is non-empty, STOP and escalate (dependency cycle = plan defect). Do not execute.
+3. Emit `narration` (announce-and-proceed — do not pause).
+4. Run `serialized` tasks first (serially, in order — cross-bucket prerequisites), then process `waves` **in array order** (topologically sorted; do not reorder, do not key off `firing` alone).
+5. Per wave: `auto-dispatch` (multi-task) → dispatch the wave via **harness-parallel-agents** with worktree-per-unit isolation (`docs/guides/agent-worktree-patterns.md`), announce and proceed; `confirm` → one plain-text confirmation, then parallel or serial per the answer; `serialize` / single-task → run through the per-task loop below serially.
+6. **Serial fallback preserved:** when independent tasks < `minWaveSize` (default 3), a `confirm` is declined, or no graph is available and the human does not confirm, run every task through the per-task loop below serially — the standing "when in doubt, run serially" default.
+
+Tasks dispatched into a parallel wave are executed by harness-parallel-agents' focused agents; tasks that fall to serial run through the loop below unchanged.
+
 For each task, starting from current position:
 
 1. **Read task instructions completely** before writing any code.

package/dist/agents/skills/codex/harness-parallel-agents/SKILL.md

@@ -2,12 +2,15 @@
 
 > Dispatch independent tasks to concurrent agents, integrate results, and verify no conflicts. Only for truly independent problems.
 
+**Invoked automatically by `harness-autopilot` (and standalone `harness-execution`), not only manually.** When a plan's phase has an auto-dispatch wave, the execution loop calls this skill to run that wave. In that mode the caller supplies worktree-per-unit isolation per `docs/guides/agent-worktree-patterns.md` (one worktree per task, sequential commits, squash-merge on integrate) and has already verified independence via `plan_parallelization`; this skill still owns the focused agent briefs (Step 2), concurrent dispatch (Step 3), and integration/verification (Steps 4–5). Manual invocation (a human asking to "work in parallel") continues to work unchanged.
+
 ## When to Use
 
 - When 3 or more tasks are truly independent (no shared state, no shared files, different subsystems)
 - When tasks involve investigation or implementation in separate parts of the codebase
 - When parallel execution would meaningfully reduce wall-clock time
 - When a plan has tasks explicitly marked as parallelizable
+- When `harness-autopilot`/`harness-execution` reaches an `auto-dispatch` (or confirmed) wave from `plan_parallelization` — this skill is the wave's dispatcher
 - NOT when failures across tasks might be related (investigate serially to find the common cause)
 - NOT when tasks need full system understanding to complete correctly
 - NOT when agents would modify the same files or shared state

package/dist/agents/skills/codex/harness-planning/SKILL.md

@@ -256,7 +256,7 @@ Report progress: `**[Phase 2/4]** DECOMPOSE — mapping file structure and creat
 ### Phase 3: SEQUENCE — Order Tasks and Identify Dependencies
 
 1. **Order by dependency.** Types before implementations. Implementations before integrations. Integration tasks (tagged `category: "integration"`) after all implementation tasks. Tests alongside implementations (same task, TDD style).
-2. **Identify parallel opportunities.** Tasks touching different subsystems with no shared state can be marked parallelizable.
+2. **Identify parallel opportunities and record dependency edges.** Tasks touching different subsystems with no shared state can run in parallel. Record each task's real dependencies as `dependsOn` (the task IDs it must follow) in the task header `**Depends on:**` line, and keep the task's `**Files:**` list accurate — together these are exactly the edges `plan_parallelization` consumes (explicit `dependsOn` unioned with file-overlap edges) to build the wave DAG at execution time. A task with no dependencies records `**Depends on:** none`.
 3. **Number tasks sequentially.** Use `Task 1`, `Task 2`, etc. Dependencies reference task numbers.
 4. **Estimate total time.** Sum 2-5 minutes per task. If total exceeds available time, identify a milestone boundary for pausing.
 
@@ -327,6 +327,8 @@ One sentence.
 
 **Depends on:** none | **Files:** path/to/file.ts, path/to/file.test.ts
 
+<!-- `Depends on` lists the task IDs this task must follow (its `dependsOn` edges); `Files` is the independence-checking input. Both feed `plan_parallelization` during execution. -->
+
 1. Create test file with exact test code
 2. Run test — observe failure
 3. Create implementation with exact code

package/dist/agents/skills/cursor/harness-autopilot/SKILL.md

@@ -108,6 +108,37 @@ On return: read `planPath` from `{sessionDir}/handoff.json`. Complexity override
 
 ### EXECUTE
 
+**Pre-dispatch: plan parallelization (standard automatic parallelism).** Before dispatching tasks, decide the safe parallel structure. This is orchestration, not reimplementation — autopilot chooses HOW to dispatch; the persona agents still do the work.
+
+1. Collect the phase's tasks with their `files` and `dependsOn` (from the plan's task headers). Call the `plan_parallelization` MCP tool:
+
+   ```json
+   {
+     "path": "<project-root>",
+     "tasks": [{ "id": "task-1", "files": ["..."], "dependsOn": [] }],
+     "depth": 1
+   }
+   ```
+
+   It returns a `ParallelizationPlan`: `waves[]` (each `{ tasks, severity, firing, analysisLevel }`), `serialized[]`, `cyclic[]`, `narration`.
+
+2. **If `cyclic` is non-empty:** STOP. Surface the cycle and route back to PLAN/APPROVE_PLAN (a dependency cycle is a plan defect). Do not dispatch.
+
+3. **Announce (announce-and-proceed):** emit `narration` verbatim. Do NOT pause here — announcing is not a gate.
+
+4. **Dispatch in dependency order — prerequisites first, then waves in array order:**
+   - First, run every task in `serialized` (high-severity-group / cycle-adjacent members) **serially**, one `harness-task-executor` per task, in listed order. These are cross-bucket prerequisites: they MUST complete before any wave that depends on them.
+   - Then process `waves` **in array order**. The `waves` array is already topologically sorted (earlier waves are prerequisites of later ones). Do NOT reorder waves and do NOT key dispatch off the `firing` field alone — the Phase-2 cross-bucket cap (a wave depending on a serialized/cyclic task is downgraded to `confirm` and marked "cross-bucket prerequisite gates this wave" in `narration`) is only sound if serialized/cyclic ran first and waves run in order.
+
+5. **For each wave, honor its `firing`:**
+   - `auto-dispatch` (multi-task): emit that wave's line from `narration`, then dispatch the wave via the **harness-parallel-agents** skill with **worktree-per-unit isolation** per `docs/guides/agent-worktree-patterns.md` ("Worktree-per-Milestone" / "Parallel Agent Work": one worktree per task, sequential commits, squash-merge at integrate). **Announce and proceed — do NOT stop for confirmation.**
+   - `confirm`: surface the wave and its `narration` line, then take exactly ONE plain-text confirmation — "Dispatch wave [{tasks}] in parallel? (yes / serial)". `yes` → dispatch via harness-parallel-agents (worktree-per-unit). `serial` or decline → run the wave's tasks serially (`harness-task-executor` each). Record the choice in `decisions[]`.
+   - `serialize`, or any single-task wave: run serially via `harness-task-executor`, exactly as today.
+
+6. **Serial fallback is preserved** when a phase has fewer than `minWaveSize` (default 3) independent tasks, when a `confirm` is declined, or when no graph is available and the human does not confirm — honoring the standing "when in doubt, run serially" default.
+
+Each dispatched unit (parallel wave or serial task) then follows the existing per-task contract below (state.json per task, checkpoints, retry budget).
+
 Dispatch harness-task-executor:
 
 ```