@pieerry/harness-kit 3.3.1 → 4.0.1

package/README.md

@@ -2,365 +2,217 @@
 
 # harness-kit
 
-Claude Code harness for product + engineering delivery.
-From idea to merged PR, one pipeline.
+From idea to merged PR. One pipeline. Six stages.
 
-[![Version](https://img.shields.io/badge/version-3.3.1-blue.svg)](VERSION)
-[![Claude Code](https://img.shields.io/badge/Claude%20Code-plugin-8b5cf6.svg)](https://claude.ai/code)
-[![Plugins](https://img.shields.io/badge/plugins-2-success.svg)](#layout)
-[![Pipeline](https://img.shields.io/badge/stages-6-informational.svg)](#usage)
+[![Version](https://img.shields.io/badge/version-4.0.1-blue.svg)](VERSION)
+[![Claude Code](https://img.shields.io/badge/Claude%20Code-AGENTS.md-8b5cf6.svg)](https://claude.ai/code)
+[![Agents](https://img.shields.io/badge/agents-2-success.svg)](#agents)
 [![License](https://img.shields.io/badge/license-MIT-lightgrey.svg)](LICENSE)
 
 <br/>
 
 ![harness-kit demo](demo/preview.gif)
 
-<sub>110s walkthrough · install → 6 commands → auto-watch PR until merged. Each command scene names its **guide · ref · sensor · eval**; final summary shows token spend per phase.</sub>
+<sub>~2min walkthrough · agents · skills · install · 6 commands · sensors+evals matrix · auto-watch PR until merged.</sub>
 
 </div>
 
 ---
 
-## What this is
+## What it is
 
-harness-kit turns a target repo into a Claude Code workspace where **product and engineering share one pipeline**. You go from a problem statement to a merged PR through six gated stages — `prd → prp → plan → dev → test → pr` — each producing a markdown artifact, each gated by deterministic sensors and an LLM-judged eval, each accounting for its own token spend.
+Two Claude Code agents — `product-manager` and `staff-software-engineer` — sharing one pipeline:
 
-The pipeline is two Claude Code plugins (`product-manager`, `staff-software-engineer`) wired together by a small shell+python harness that tracks state, runs gates, and renders a live status bar. After a PR opens, an in-session monitor polls GitHub on backoff until the PR merges, then auto-clears state so the next feature starts clean.
-
-**Who it's for:** PMs and engineers who want their `/`-commands to (1) produce real artifacts with named gates, (2) survive session restarts via persisted state, (3) record per-phase token spend so usage is auditable.
-
-**What it's not:** a code generator, a CI replacement, or an opinionated agent framework. It's a thin harness that defers all model work to Claude Code and all VCS work to `git`/`gh`.
-
-**Internal docs use caveman-full style** (drop articles + filler, fragments OK) to save input tokens — see [CLAUDE.md](CLAUDE.md). Generated artifacts (PRDs, PRPs, plans, dev/test/pr reports) stay natural English for external stakeholders. Reference templates and good-example artifacts are deliberately left in natural prose so produced docs inherit the right pattern.
-
----
+```
+prd → prp → plan → dev → test → pr
+```
 
-## Table of Contents
-
-- [Getting Started](#getting-started)
-  - [Install](#install)
-  - [Update](#update)
-  - [Usage](#usage)
-  - [Workflow](#workflow)
-  - [Samples](#samples)
-- [How it works](#how-it-works)
-  - [Anatomy of a stage](#anatomy-of-a-stage)
-  - [Sensors + evals matrix](#sensors--evals-matrix)
-  - [Status bar](#status-bar)
-  - [Live activity indicator](#live-activity-indicator)
-  - [PR monitor](#pr-monitor)
-  - [Token accounting](#token-accounting)
-  - [Session-start auto-clear](#session-start-auto-clear)
-- [Layout](#layout)
-- [Project conventions](#project-conventions)
-- [Tooling](#tooling)
+Each stage produces a markdown artifact, gated by **deterministic sensors** (pass/fail) and a **scored eval** (≥ 8.0). After the PR opens, an in-session monitor watches for merge.
 
 ---
 
-## Getting Started
-
-### Install
+## Install
 
 ```bash
 npm i -g @pieerry/harness-kit
 hk install
 ```
 
-`hk install` writes plugins into `.claude/plugins/`, drops hooks in `.claude/hooks/` (status-line, pipeline tracking, activity tracker), copies state managers to `.claude/scripts/` (`pipeline.py`, `activity.py`, `pr-monitor.py`), registers slash commands under `.claude/commands/`, generates `.claude/settings.json`, and scaffolds `.claude/conventions/` for your project overrides. Run from the target repo or pass `[target]`. Restart Claude Code after.
-
-Reinstalling on top of an existing setup backs up the previous `settings.json` to `.claude/settings.json.bak.{timestamp}` before overwriting, so manual customizations are recoverable.
-
-CLI subcommands:
+Restart Claude Code. Done.
 
-| Command | What it does |
-|---------|--------------|
-| `hk install [target]` | install plugins into target repo (default: cwd) |
-| `hk update [target]` | pull latest source and reinstall |
-| `hk uninstall [target]` | remove plugins, hooks, settings, agents (keeps `outputs/` and `conventions/`) |
-| `hk status [target]` | installed version + active pipeline stage |
-| `hk version` | source version |
-
-No-npm path:
+Without npm:
 
 ```bash
 git clone https://github.com/Pierry/harness-kit ~/.harness-kit
 bash ~/.harness-kit/setup/install.sh
 ```
 
-### Update
+CLI: `hk install` · `hk update` · `hk uninstall` · `hk status` · `hk version`.
 
-For npm installs:
+---
 
-```bash
-npm i -g @pieerry/harness-kit@latest
-hk update
-```
+## Getting started
 
-For git-clone installs:
+Pick the flow that matches the task. All of them share the same pipeline state, so you can switch between them mid-feature.
 
-```bash
-hk update
-```
+### Big task — full pipeline (PM + Eng)
 
-`hk update` pulls latest source (git installs only) and reinstalls. Idempotent. Version is read from the package `VERSION` and recorded in your target at `.claude/.hk-version`. npm users must bump the package first — `hk update` alone won't reach the registry.
+A new feature with stakes, ambiguity, or a Jira ticket attached. You want a written PRD, a thought-through PRP, a plan, code, tests, and a PR.
 
-### Usage
+```
+/product-manager:run     # drafts PRD then PRP, with sensor + eval gates
+/sse:run                 # plans, implements, tests, opens PR, watches for merge
+```
 
-| Command | What it does |
-|---------|--------------|
-| `/product-manager:prd` | Draft a PRD |
-| `/product-manager:prp` | Draft a PRP (needs an approved PRD) |
-| `/product-manager:run` | Full PM pipeline (PRD then PRP) |
-| `/sse:plan` | Generate plan from an approved PRP |
-| `/sse:dev` | Implement the plan, run convention + structure + quality gates |
-| `/sse:test` | Run the project test suite + write a structured test report |
-| `/sse:pr` | Open the draft PR, then auto-arm `pr-monitor` |
-| `/sse:pr-monitor` | Watch the active PR for merge with backoff polling (auto-invoked by `/sse:pr`) |
-| `/sse:run` | Full SSE pipeline (plan, dev, test, pr) |
-| `/pipeline:continue` | Resume the active pipeline at its next pending stage |
-| `/pipeline:reset` | Abandon the active pipeline run (clears state, keeps artifacts) |
+Approve each artifact when prompted. The status bar tracks where you are in the six stages.
 
-Pipeline order: `prd → prp → plan → dev → test → pr`. Each stage gets an approval marker. Approval requires both the sensor gate (pass) and the eval gate (score ≥ 8.0).
+### Spec only — no code yet
 
-You can enter the pipeline at any stage:
+You need the PRD and PRP to align with stakeholders before any engineering work. Stop after the PRP.
 
-- `prd → prp → plan → dev → test → pr` (full PM + SSE)
-- `prd → prp` (PM only, hand off to a separate engineering process)
-- `plan → dev → test → pr` (SSE only, when discovery already happened elsewhere)
+```
+/product-manager:run
+```
 
-Status bar tracks the shape you started with. Close the session and reopen later — `/pipeline:continue` picks up at the next pending stage. `/pipeline:reset` clears the run if you decide to abandon it.
+When eng is ready, hand them the repo and they run `/sse:run` against the approved PRP.
 
-### Workflow
+### Dev only — small change, plan in your head
 
-PM session in this workspace:
+A bug fix, a small enhancement, or a refactor where writing a PRD would be theatre. Skip PM, run engineering directly.
 
 ```
-$ /product-manager:run
-> squad? billing
-> problem? invoice generation fails for multi-currency customers
-> ...
-PRD saved at outputs/prd/2026-05-12-billing-multi-currency.md.
-  sensors: prd-structure ok, prd-acceptance-criteria ok
-  eval:    prd-quality 8.6/10, prd-readiness 8.9/10
-  guides:  prd-guidelines.md, writing-style.md, templates/prd.md
-  refs:    business-info.md, squads/billing/context.md
-  next:    /product-manager:prp
-
-PRP saved at outputs/prp/2026-05-12-billing-multi-currency.md.
-  sensors: prp-structure ok, prp-context-quality ok, prp-links ok
-  eval:    prp-quality 8.4/10, prp-context-readiness 9.0/10
-  guides:  prp-guidelines.md, templates/prp.md
-  refs:    prd/2026-05-12-billing-multi-currency.md
-  next:    /sse:plan (ready for handoff)
+/sse:run                 # plan → dev → test → PR
 ```
 
-Engineering session in the target service repo:
+Or run a single stage if that's all you need:
 
 ```
-$ /sse:run
-> source PRP? outputs/prp/2026-05-12-billing-multi-currency.md
-> area? backend
-Plan saved at outputs/plan/2026-05-12-billing-multi-currency.md.
-  sensors: plan-structure ok (problem, files, gates, scope)
-  eval:    plan-quality 8.3/10
-  guides:  pipeline.md, coding-style.md, skills/backend/SKILL.md
-  refs:    prp/..., conventions/backend.md
-  next:    /sse:dev
-
-Dev complete. branch feat/PROJ-123-multi-currency.
-  files changed: 5
-  commits: 3 (a1b2c3d, d4e5f6g, h7i8j9k)
-  sensors: code-conventions ok, test-coverage ok, dev-structure ok
-  eval:    dev-quality 8.4/10
-  guides:  coding-style.md, commit-style.md, skills/backend/SKILL.md
-  next:    /sse:test
-
-Tests passed.
-  command:  ./mvnw test
-  passed:   24, failed: 0
-  duration: 12.4s
-  sensors:  test-structure ok
-  eval:     test-quality 8.7/10
-  next:     /sse:pr
-
-PR opened: https://github.com/your-org/billing-service/pull/567
-  title:   feat(PROJ-123): timezone-aware deadline check
-  draft:   yes
-  sensors: pr-structure ok
-  eval:    pr-quality 8.9/10
-
-PR monitor armed for #567. First check in 3min, escalates to 30min cap.
+/sse:plan                # just the plan
+/sse:dev                 # just the code (against an approved plan)
+/sse:test                # just the tests
+/sse:pr                  # just open the PR
 ```
 
-Every reply names the actual sensors that ran, evals with scores, and guides loaded — no generic "ok" lines. The `/sse:run` and `/product-manager:run` summaries aggregate the same shape across phases, plus per-phase token totals from `outputs/tokens/{feature_id}.json`.
+### Resume — pick up where you left off
 
-### Samples
+Closed the session, restarted Claude Code, or got interrupted. State persists at `.claude/.pipeline-state.json`.
 
-Reference artifacts ship inside the plugins:
+```
+/pipeline:continue       # next pending stage for the active feature
+/pipeline:reset          # abandon the active run and start fresh
+```
 
-- [good PRD example](.claude/plugins/product-manager/guides/examples/good-prd-example.md)
-- [good PRP example](.claude/plugins/product-manager/guides/examples/good-prp-example.md)
+When the PR merges, the in-session monitor clears state automatically.
 
 ---
 
-## How it works
-
-### Anatomy of a stage
-
-Every stage in the pipeline runs the same loop. Same four ingredients, every time:
-
-| Ingredient | What it is | Example |
-|-----------|------------|---------|
-| **guide** | How to write the artifact. Style + structure rules the LLM follows. | `prd-guidelines.md`, `coding-style.md` |
-| **ref** | Context pulled in before drafting. Org/squad data + prior artifacts. | `business-info.md`, `outputs/prp/...md`, `.claude/conventions/backend.md` |
-| **sensor** | Must-pass structural check. Deterministic, fast. Blocks approval. | `prd-structure`, `prp-links`, `dev-structure`, `test-structure`, `pr-structure`, `code-conventions`, `test-coverage` |
-| **eval** | Scored quality rubric. LLM-judge, threshold 8.0, retried until pass or max attempts. | `prd-quality`, `prp-context-readiness`, `plan-quality`, `dev-quality`, `test-quality`, `pr-quality` |
-
-Sensors are pass/fail. Evals are scored. Approval markers (`<!-- approved: -->`) gate the next stage. Token totals get appended as an inline `<!-- tokens: ... -->` reference after publish.
-
-### Sensors + evals matrix
-
-| Stage | Sensors (deterministic) | Eval (LLM-judge, ≥ 8.0) |
-|-------|-------------------------|--------------------------|
-| `prd` | `prd-structure`, `prd-acceptance-criteria` | `prd-quality`, `prd-readiness` |
-| `prp` | `prp-structure`, `prp-context-quality`, `prp-links` | `prp-quality`, `prp-context-readiness` |
-| `plan` | `plan-structure` | `plan-quality` |
-| `dev` | `code-conventions`, `test-coverage`, `dev-structure` | `dev-quality` |
-| `test` | `test-structure` | `test-quality` |
-| `pr` | `pr-structure` | `pr-quality` |
-
-Document sensors (`*-structure`) are auto-run by the post-write hook when the artifact lands on disk. Code sensors (`code-conventions`, `test-coverage`) are invoked by `/sse:dev` after each commit. Evals are scored by Claude inside the slash command. Convention: sensor files live at `plugins/{plugin}/sensors/{phase}-*.md`; evals at `plugins/{plugin}/evals/{phase}-quality.md`.
-
-### Status bar
-
-The status line follows the active feature through whatever pipeline shape you started. It is dynamic: a `UserPromptSubmit` hook records intent the moment you type a slash command, and `PostToolUse` hooks update state as artifact files land on disk.
+## Use it
 
 ```
-idle · /product-manager:run · /sse:run · /pipeline:continue
-starting sse-run [plan+dev+test+pr] · plan pending · next /sse:plan
-multi-currency [plan+dev+test+pr] · plan drafting · next /sse:plan · sensor: plan-structure
-multi-currency [plan+dev+test+pr] · plan approved · dev pending · next /sse:dev
-multi-currency [prd+prp+plan+dev+test+pr] · prp approved · plan drafting · next /sse:plan
-multi-currency · complete (prd+prp+plan+dev+test+pr)
+/product-manager:run           draft PRD then PRP
+/sse:run                       plan, dev, test, open PR, watch for merge
+/pipeline:continue             resume next pending stage
+/pipeline:reset                abandon active run
 ```
 
-The bracketed list is the pipeline shape — the stages this run will execute. The shape is inferred from the slash command you invoked and extended when you chain commands (e.g. running `/sse:run` after `/product-manager:run` appends `plan+dev+test+pr` to the existing `prd+prp`).
+Need just one stage? Each is its own slash command:
 
-State lives at `.claude/.pipeline-state.json`. Close the session and reopen — the `SessionStart` hook prints a one-line resume hint, and `/pipeline:continue` invokes the next pending stage. `/pipeline:reset` clears the file. Output artifacts under `.claude/plugins/*/outputs/` are never deleted by reset.
+| Stage | Command | Gates |
+|---|---|---|
+| `prd` | `/product-manager:prd` | `prd-structure`, `prd-acceptance-criteria` · `prd-quality`, `prd-readiness` |
+| `prp` | `/product-manager:prp` | `prp-structure`, `prp-context-quality`, `prp-links`, `link-validator` · `prp-quality`, `prp-context-readiness` |
+| `plan` | `/sse:plan` | `plan-structure` · `plan-quality` |
+| `dev` | `/sse:dev` | `code-conventions`, `test-coverage`, `dev-structure` · `dev-quality` |
+| `test` | `/sse:test` | `test-structure` · `test-quality` |
+| `pr` | `/sse:pr` | `pr-structure` · `pr-quality` · auto-arms `/sse:pr-monitor` |
 
-### Live activity indicator
+Sensors block on failure (Claude regenerates). Evals score; threshold 8.0; retried up to 3 times.
 
-While Claude is reading a sensor, eval, or guide, the status bar appends a cyan tag with the file being touched:
-
-```
-multi-currency [plan+dev+test+pr] · plan drafting · next /sse:plan · sensor: plan-structure
-multi-currency [plan+dev+test+pr] · dev drafting · next /sse:dev · guide: coding-style
-multi-currency [plan+dev+test+pr] · plan drafting · next /sse:plan · eval: plan-quality
-```
-
-Mechanism: a `PreToolUse` Read hook (`activity-pre-read.sh`) detects when Claude reads a file under `plugins/*/sensors/`, `plugins/*/evals/`, or `plugins/*/guides/` and writes the activity to `.claude/.activity` with a 60s TTL. The status-line reads it on each render and clears stale entries. The Claude Code top-of-screen "thinking…" indicator is rendered by the CLI itself and cannot be augmented; the bottom status bar is the available channel.
+---
 
-### PR monitor
+## Agents
 
-After `/sse:pr` opens a PR, it auto-invokes `/sse:pr-monitor`, which polls `gh pr view --json state` on backoff and stays in the session until the PR transitions out of `OPEN`.
+Registered in [`AGENTS.md`](./AGENTS.md) at the repo root. Each ships its own sensors, evals, guides, skills.
 
-| Rung | Interval | Attempts | Cumulative |
-|------|----------|----------|------------|
-| 1 | 3 min | 5 | 15 min |
-| 2 | 6 min | 5 | 45 min |
-| 3 | 12 min | 5 | 1h 45m |
-| 4 | 24 min | 5 | 3h 45m |
-| 5 (cap) | 30 min | ∞ | until merged/closed |
+### `product-manager` — turns a problem into an engineering-ready spec
 
-On `MERGED`: notifies and clears both `.pipeline-state.json` and `.pr-monitor-state.json`. On `CLOSED` without merge: stops cleanly. Mechanism: `ScheduleWakeup` in the active session — closing the session ends the monitor.
+- Skills: `prd`, `prp`
+- Sensors: 5 (structure + acceptance criteria + cross-links)
+- Evals: 4 (quality + readiness for each of PRD, PRP)
+- Guides: `pipeline.md`, `prd-guidelines.md`, `prp-guidelines.md`, `writing-style.md`, `templates/`, `examples/`
+- [Full docs →](.claude/agents/product-manager/README.md)
 
-State: `.claude/.pr-monitor-state.json` records PR number, URL, branch, current interval, and attempt counts.
+### `staff-software-engineer` — turns an approved PRP into a merged PR
 
-### Token accounting
+- Skills: `backend`, `web`, `mobile`, `devops` (auto-detected from repo)
+- Sensors: 6 (`plan-structure`, `code-conventions`, `test-coverage`, `dev-structure`, `test-structure`, `pr-structure`)
+- Evals: 4 (`plan`, `dev`, `test`, `pr` quality)
+- Guides: `pipeline.md`, `coding-style.md`, `commit-style.md`, `conventions-override.md`
+- [Full docs →](.claude/agents/staff-software-engineer/README.md)
 
-Every phase has its own start/end marker written to `outputs/.markers/{feature_id}.{phase}-{generate|validate}.{start|end}`. When the artifact is approved, the post-eval hook runs `scripts/token-phase.py` for both phases — it reads the Claude session transcript JSONL, sums input/output/cache-read/cache-creation tokens within each window, and appends an entry to `outputs/tokens/{feature_id}.json`.
+---
 
-Schema:
+## Anatomy of every stage
 
-```json
-{
-  "feature_id": "2026-05-12-billing-multi-currency",
-  "files": { "prd": "outputs/prd/...md", "prp": "outputs/prp/...md" },
-  "phases": [
-    { "phase": "prd-generate", "started_at": "...", "ended_at": "...", "tokens": { "input": 1234, "output": 567, "cache_read": 8910, "cache_creation": 234 }, "attempts": 1 }
-  ],
-  "totals": { "input": 0, "output": 0, "cache_read": 0, "cache_creation": 0 }
-}
 ```
+GUIDE       how to write it           pipeline.md · coding-style.md
+REF         context to pull in        AGENTS.md · prp/<feature>.md · conventions/{area}.md
+SENSOR      must-pass structure       deterministic, blocks approval
+EVAL        scored rubric             LLM-judge, threshold 8.0
+```
+
+Approval marker (`<!-- approved: -->`) gates the next stage. Token spend per phase appended as inline `<!-- tokens: ... -->`.
 
-Each plugin keeps its own `outputs/tokens/{feature_id}.json`. The artifact gets an inline `<!-- tokens: outputs/tokens/{feature_id}.json in=N out=N cache_r=N -->` reference appended after approval so the totals are visible from the artifact itself. Query examples in the [product-manager README](.claude/plugins/product-manager/README.md#token-accounting).
+---
 
-### Session-start auto-clear
+## Status bar
 
-When you reopen a session on a branch whose PR is `MERGED` or `CLOSED` and the pipeline state still has `feature_id: null` (i.e. the run was never linked to a feature), the `SessionStart` hook auto-clears `.pipeline-state.json` and prints:
+Live indicator at the bottom of every Claude Code session:
 
 ```
-previous feature shipped (PR #271 MERGED). pipeline state cleared.
-start next with /product-manager:run or /sse:run
+idle · /product-manager:run · /sse:run · /pipeline:continue
+billing-fix [prd+prp+plan+dev+test+pr] · prp approved · plan drafting · next /sse:plan · sensor: plan-structure
+billing-fix · complete (prd/prp/plan/dev/test/pr)
 ```
 
-This avoids the stale `next /sse:plan` nag after work has already shipped.
+State persists at `.claude/.pipeline-state.json`. Close the session and reopen — `/pipeline:continue` picks up at the next pending stage. When the PR merges, state auto-clears.
 
 ---
 
-## Layout
+## Project conventions
+
+The SSE agent has defaults per area. Override per repo:
 
 ```
-.
-├── .claude/
-│   ├── plugins/
-│   │   ├── product-manager/          PRD + PRP plugin
-│   │   └── staff-software-engineer/  plan, dev, test, pr plugin
-│   ├── commands/                     slash commands per plugin namespace
-│   ├── agents/                       Task-tool-invokable orchestrators
-│   ├── hooks/
-│   │   ├── status-line.sh            pipeline status indicator (with cyan activity)
-│   │   ├── pipeline-prompt.sh        slash-command intent tracking
-│   │   ├── pipeline-postwrite.sh     stage-state from artifact writes
-│   │   ├── pipeline-postedit.sh      stage-state from approval marker
-│   │   ├── pipeline-session-start.sh resume hint + PR-merged auto-clear
-│   │   └── activity-pre-read.sh      surfaces current sensor/eval/guide
-│   ├── scripts/
-│   │   ├── pipeline.py               pipeline state CRUD
-│   │   ├── activity.py               live activity CRUD (60s TTL)
-│   │   ├── pr-monitor.py             PR-watch state + backoff schedule
-│   │   └── stage-card.md             header/footer card convention
-│   ├── .pipeline-state.json          active feature + per-stage state
-│   ├── .pr-monitor-state.json        PR being watched
-│   ├── .activity                     current sensor/eval/guide being touched
-│   └── settings.json                 hooks wiring + permissions
-├── context-library/                  reusable org/squad context
-├── setup/
-│   ├── install.sh                    target-repo installer
-│   └── update.sh                     pull + reinstall
-└── VERSION                           source of truth for installer
+{your-repo}/.claude/conventions/{backend,web,mobile,devops}.md
 ```
 
-Plugin documentation:
-
-- [product-manager](.claude/plugins/product-manager/README.md): PRD and PRP generation, sensor and eval gates, retry loop, token accounting, optional Confluence publish.
-- [staff-software-engineer](.claude/plugins/staff-software-engineer/README.md): plan, dev, test, pr stages with per-project conventions override, document + code sensors, quality evals, PR monitor.
+Only the area files you need. The agent reads them on top of defaults. See [`conventions-override.md`](.claude/agents/staff-software-engineer/guides/conventions-override.md).
 
 ---
 
-## Project conventions
+## Layout
 
-Each target repo can override the SSE plugin defaults with its own files:
+What `hk install` lays down in your repo:
 
 ```
-{repo}/.claude/conventions/
-├── backend.md
-├── web.md
-├── mobile.md
-└── devops.md
+{your-repo}/
+├── AGENTS.md                    agent registry + routing
+├── CLAUDE.md                    workspace style + role
+└── .claude/
+    ├── agents/                  agent definitions (sensors, evals, guides, skills)
+    ├── commands/                slash command entry points
+    ├── hooks/                   status-line + lifecycle hooks
+    ├── scripts/                 pipeline.py · activity.py · pr-monitor.py
+    ├── runtime/
+    │   ├── hooks/<agent>/       per-agent lifecycle (post-write, post-eval, pre-prp-check)
+    │   ├── scripts/<agent>/     per-agent utilities (sensor-runner, token-phase, link-validator)
+    │   └── outputs/{pm,sse}/    generated artifacts, markers, tokens
+    ├── conventions/             your per-repo overrides
+    └── settings.json            hook wiring
 ```
 
-The installer scaffolds `.claude/conventions/README.md` to remind you of the contract. Fill only the area files relevant to the repo. Plugin reads them on top of its defaults. See [conventions-override.md](.claude/plugins/staff-software-engineer/guides/conventions-override.md) for the override mechanics and examples.
+Full path-by-path map in [`AGENTS.md`](./AGENTS.md).
 
 ---
 
@@ -368,12 +220,13 @@ The installer scaffolds `.claude/conventions/README.md` to remind you of the con
 
 | Tool | Why |
 |------|-----|
-| [Claude Code](https://claude.ai/code) | the agent runtime |
-| [git](https://git-scm.com/) | version control + status bar branch detection |
-| [python3](https://www.python.org/) | sensor runner, token accounting, pipeline state, activity tracker, PR monitor |
-| [gh CLI](https://cli.github.com/) | install, update, opening PRs via `/sse:pr`, polling merge via `/sse:pr-monitor` |
+| [Claude Code](https://claude.ai/code) | agent runtime |
+| python3 | sensors, token accounting, pipeline state |
+| [gh CLI](https://cli.github.com/) | opens PR, polls for merge |
+| git | branch + commit ops |
+
+Optional: `jq` for token JSON queries. `JIRA_USERNAME` + `JIRA_API_TOKEN` to publish PRD/PRP to Confluence.
 
-Optional:
+---
 
-- [jq](https://stedolan.github.io/jq/) for querying the token JSON files
-- `JIRA_USERNAME` and `JIRA_API_TOKEN` env vars to enable Confluence publish (details in the [product-manager README](.claude/plugins/product-manager/README.md#confluence-publish))
+MIT. Built on [Claude Code](https://claude.ai/code). Works in any repo Claude Code touches.

package/VERSION

@@ -1 +1 @@
-3.3.1
+4.0.1

package/bin/hk.js

@@ -58,13 +58,18 @@ function cmdUninstall(target) {
     process.exit(1);
   }
   const toRemove = [
-    '.claude/plugins/product-manager',
-    '.claude/plugins/staff-software-engineer',
+    'AGENTS.md',
+    '.claude/agents/product-manager',
+    '.claude/agents/staff-software-engineer',
+    '.claude/agents/product-manager.md',
+    '.claude/agents/staff-software-engineer.md',
     '.claude/commands/product-manager',
     '.claude/commands/sse',
     '.claude/commands/pipeline',
-    '.claude/agents/product-manager.md',
-    '.claude/agents/staff-software-engineer.md',
+    '.claude/runtime/hooks/product-manager',
+    '.claude/runtime/hooks/staff-software-engineer',
+    '.claude/runtime/scripts/product-manager',
+    '.claude/runtime/scripts/staff-software-engineer',
     '.claude/hooks/status-line.sh',
     '.claude/hooks/pipeline-prompt.sh',
     '.claude/hooks/pipeline-postwrite.sh',
@@ -80,6 +85,9 @@ function cmdUninstall(target) {
     '.claude/.activity',
     '.claude/settings.json',
     '.claude/.hk-version',
+    // legacy v3.x layout (best-effort cleanup if still present)
+    '.claude/plugins/product-manager',
+    '.claude/plugins/staff-software-engineer',
   ];
   for (const rel of toRemove) {
     const p = path.join(target, rel);
@@ -89,7 +97,7 @@ function cmdUninstall(target) {
     }
   }
   console.log(`uninstalled harness-kit v${v} from ${target}`);
-  console.log(`note: .claude/conventions/ and outputs/ kept. delete manually if desired.`);
+  console.log(`note: CLAUDE.md, .claude/conventions/, .claude/runtime/outputs/, and .claude/.legacy-v3-backup/ kept. delete manually if desired.`);
 }
 
 function cmdStatus(target) {
@@ -117,9 +125,9 @@ function cmdHelp() {
   console.log(`hk - harness-kit CLI (v${pkgVersion()})
 
 usage:
-  hk install [target]     install plugins into target repo (default: cwd)
-  hk update  [target]     pull latest source and reinstall
-  hk uninstall [target]   remove installed plugins from target
+  hk install [target]     install harness into target repo (default: cwd)
+  hk update  [target]     pull latest source and reinstall (auto-backs up v3.x plugins/)
+  hk uninstall [target]   remove installed harness from target
   hk status  [target]     show installed version + active pipeline stage
   hk version              source version
   hk help                 this message

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pieerry/harness-kit",
-  "version": "3.3.1",
+  "version": "4.0.1",
   "description": "Claude Code harness for product + engineering delivery. From idea to merged PR, one pipeline.",
   "author": "Space Metrics AI",
   "license": "MIT",
@@ -21,7 +21,8 @@
     "product-management",
     "delivery",
     "pipeline",
-    "plugin"
+    "agents-md",
+    "subagent"
   ],
   "bin": {
     "hk": "bin/hk.js",
@@ -35,7 +36,8 @@
     "VERSION",
     "README.md",
     "LICENSE",
-    "CLAUDE.md"
+    "CLAUDE.md",
+    "AGENTS.md"
   ],
   "engines": {
     "node": ">=14.0.0"