@pieerry/harness-kit 3.0.0

package/README.md

@@ -0,0 +1,192 @@
+<div align="center">
+
+# harness-kit
+
+Claude Code harness for product + engineering delivery.
+From idea to merged PR, one pipeline.
+
+[![Version](https://img.shields.io/badge/version-3.0.0-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)
+[![License](https://img.shields.io/badge/license-MIT-lightgrey.svg)](LICENSE)
+
+</div>
+
+---
+
+## Table of Contents
+
+- [Getting Started](#getting-started)
+  - [Install](#install)
+  - [Update](#update)
+  - [Usage](#usage)
+  - [Workflow](#workflow)
+  - [Samples](#samples)
+- [Layout](#layout)
+- [Project conventions](#project-conventions)
+- [Status bar](#status-bar)
+- [Tooling](#tooling)
+
+---
+
+## Getting Started
+
+### Install
+
+```bash
+npm i -g @pieerry/harness-kit
+hk install
+```
+
+`hk install` writes plugins into `.claude/plugins/`, drops the status-line hook in `.claude/hooks/`, generates `.claude/settings.json`, and scaffolds `.claude/conventions/` for your project overrides. Run it from the target repo (or pass an explicit `[target]`). Restart Claude Code after.
+
+CLI subcommands:
+
+| 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 (if you don't want a Node dep):
+
+```bash
+git clone https://github.com/space-metrics-ai/harness-kit ~/.harness-kit
+bash ~/.harness-kit/setup/install.sh
+```
+
+### Update
+
+```bash
+hk update
+```
+
+Pulls latest source and reinstalls. Idempotent. Version is read from the package `VERSION` and recorded in your target at `.claude/.hk-version`.
+
+### Usage
+
+| 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 gates |
+| `/sse:test` | Run the project test suite |
+| `/sse:pr` | Open the draft PR |
+| `/sse:run` | Full SSE pipeline (plan, dev, test, pr) |
+
+Pipeline order: `prd → prp → plan → dev → test → pr`. Each stage gets an approval marker. The status bar tracks the current one.
+
+### Workflow
+
+PM session in this workspace:
+
+```
+$ /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. Score: 8.6/10.
+PRP saved at outputs/prp/2026-05-12-billing-multi-currency.md. Score: 8.4/10.
+```
+
+Engineering session in the target service repo:
+
+```
+$ /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. Score: 8.3/10.
+Dev complete. 5 files changed, 3 commits.
+Tests: 24 passed, 0 failed.
+PR opened: https://github.com/your-org/billing-service/pull/567
+```
+
+Token usage is logged per phase to a shared JSON across both plugins. See the [product-manager README](.claude/plugins/product-manager/README.md#token-accounting) for the schema and query examples.
+
+### Samples
+
+Reference artifacts ship inside the plugins:
+
+- [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)
+
+---
+
+## Layout
+
+```
+.
+├── .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
+│   └── 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
+```
+
+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.
+
+---
+
+## Project conventions
+
+Each target repo can override the SSE plugin defaults with its own files:
+
+```
+{repo}/.claude/conventions/
+├── backend.md
+├── web.md
+├── mobile.md
+└── devops.md
+```
+
+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.
+
+---
+
+## Status bar
+
+The status line follows the active feature through the 6-stage pipeline. Examples:
+
+```
+idle · start /product-manager:run or /sse:run
+multi-currency · prd drafting · next /product-manager:prd
+multi-currency · prd approved · prp pending · next /product-manager:prp
+multi-currency · prp approved · plan pending · next /sse:plan
+multi-currency · plan approved · dev pending · next /sse:dev
+multi-currency · complete
+```
+
+State derives from artifact files plus the `<!-- approved: -->` marker. A feature is "active" when any of its artifacts was modified in the last hour. With no recent activity, the bar shows the idle prompt.
+
+---
+
+## Tooling
+
+| 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, optional Confluence publish |
+| [gh CLI](https://cli.github.com/) | install, update, opening PRs via `/sse:pr` |
+
+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))

package/VERSION

@@ -0,0 +1 @@
+3.0.0

package/bin/hk.js

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+// harness-kit CLI. Thin Node wrapper around setup/*.sh and helpers.
+// Subcommands: install, update, uninstall, status, version, help.
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const PKG_ROOT = path.resolve(__dirname, '..');
+
+function pkgVersion() {
+  try {
+    return fs.readFileSync(path.join(PKG_ROOT, 'VERSION'), 'utf8').trim();
+  } catch {
+    return '0.0.0';
+  }
+}
+
+function targetVersion(target) {
+  try {
+    return fs.readFileSync(path.join(target, '.claude/.hk-version'), 'utf8').trim();
+  } catch {
+    return null;
+  }
+}
+
+function resolveTarget(arg) {
+  return path.resolve(arg || process.cwd());
+}
+
+function runBash(scriptName, target) {
+  const script = path.join(PKG_ROOT, 'setup', scriptName);
+  if (!fs.existsSync(script)) {
+    console.error(`setup script missing: ${script}`);
+    process.exit(1);
+  }
+  const r = spawnSync('bash', [script, target], { stdio: 'inherit' });
+  process.exit(r.status ?? 1);
+}
+
+function cmdInstall(target) {
+  runBash('install.sh', target);
+}
+
+function cmdUpdate(target) {
+  runBash('update.sh', target);
+}
+
+function cmdUninstall(target) {
+  const claudeDir = path.join(target, '.claude');
+  if (!fs.existsSync(claudeDir)) {
+    console.log(`nothing to remove at ${target}`);
+    return;
+  }
+  const v = targetVersion(target);
+  if (!v) {
+    console.log(`no .hk-version found at ${target}. refusing to delete .claude/ blindly.`);
+    process.exit(1);
+  }
+  const toRemove = [
+    '.claude/plugins/product-manager',
+    '.claude/plugins/staff-software-engineer',
+    '.claude/commands/product-manager',
+    '.claude/commands/sse',
+    '.claude/agents/product-manager.md',
+    '.claude/agents/staff-software-engineer.md',
+    '.claude/hooks/status-line.sh',
+    '.claude/settings.json',
+    '.claude/.hk-version',
+  ];
+  for (const rel of toRemove) {
+    const p = path.join(target, rel);
+    if (fs.existsSync(p)) {
+      fs.rmSync(p, { recursive: true, force: true });
+      console.log(`removed ${rel}`);
+    }
+  }
+  console.log(`uninstalled harness-kit v${v} from ${target}`);
+  console.log(`note: .claude/conventions/ and outputs/ kept. delete manually if desired.`);
+}
+
+function cmdStatus(target) {
+  const v = targetVersion(target);
+  const srcV = pkgVersion();
+  if (!v) {
+    console.log(`not installed at ${target}`);
+    console.log(`source version: ${srcV}`);
+    return;
+  }
+  console.log(`installed: v${v}`);
+  console.log(`source:    v${srcV}${v === srcV ? '' : '  (run: hk update)'}`);
+  const statusLine = path.join(target, '.claude/hooks/status-line.sh');
+  if (fs.existsSync(statusLine)) {
+    const r = spawnSync('bash', [statusLine], { cwd: target, encoding: 'utf8' });
+    if (r.stdout) console.log(`pipeline:  ${r.stdout.trim()}`);
+  }
+}
+
+function cmdVersion() {
+  console.log(pkgVersion());
+}
+
+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 status  [target]     show installed version + active pipeline stage
+  hk version              source version
+  hk help                 this message
+
+after install, restart Claude Code and use:
+  /product-manager:prd | :prp | :run
+  /sse:plan | :dev | :test | :pr | :run`);
+}
+
+function main() {
+  const [, , cmd, arg] = process.argv;
+  const target = resolveTarget(arg);
+  switch (cmd) {
+    case 'install':   return cmdInstall(target);
+    case 'update':    return cmdUpdate(target);
+    case 'uninstall': return cmdUninstall(target);
+    case 'status':    return cmdStatus(target);
+    case 'version':
+    case '--version':
+    case '-v':        return cmdVersion();
+    case 'help':
+    case '--help':
+    case '-h':
+    case undefined:   return cmdHelp();
+    default:
+      console.error(`unknown command: ${cmd}`);
+      cmdHelp();
+      process.exit(1);
+  }
+}
+
+main();

package/context-library/README.md

@@ -0,0 +1,38 @@
+# Context Library
+
+Reference material the plugins consult before generating PRDs, PRPs, plans, and PRs. Public-template by default. Fill these in per-org.
+
+## Layout
+
+```
+context-library/
+├── business-info.md          company snapshot (mission, customers, segments)
+├── personal-context.md       per-user role, style, constraints (gitignored)
+├── stakeholder-template.md   stakeholder map template
+├── writing-style.md          internal writing voice (drop pleasantries, etc)
+├── squads/                   per-team folders with squad-specific context
+│   └── README.md
+├── strategy/                 OKRs, roadmaps, frameworks
+│   └── README.md
+├── decisions/                ADR-style records
+│   └── README.md
+├── meetings/                 raw notes that may inform later artifacts
+├── metrics/                  dashboards, baselines, north stars
+├── research/                 customer research, interviews, synthesis
+└── example-prds/             reference artifacts the PM agent reads
+    └── README.md
+```
+
+Only the templated files ship. Add your own content inside each folder. The plugins read whatever is there.
+
+## How plugins use this
+
+- `product-manager` agent reads `business-info.md`, `writing-style.md`, `squads/{squad}/`, and `example-prds/` before drafting a PRD or PRP.
+- `staff-software-engineer` agent reads `decisions/` (for ADRs), `metrics/` (for SLO context), and `squads/{squad}/` (for domain terms).
+- Personal files (`personal-context-*.md`, `writing-style-customer.md`, etc) are gitignored. Each user keeps their own copy locally.
+
+## Conventions
+
+- One topic per file. Short, scannable.
+- Real numbers, real names. Avoid generic prose.
+- Mark unknowns with `NOT FOUND - NEEDS REVIEW: {detail}`.

package/context-library/business-info-template.md

@@ -0,0 +1,39 @@
+# Business Info
+
+> Template. Rename to `business-info.md` and fill in. Keep it short — agents read this on every PRD/PRP.
+
+## Company
+
+- **Name:** {Company}
+- **What we do:** {one-sentence pitch}
+- **Customers:** {segments}
+- **Stage:** {e.g. series B, public, bootstrapped}
+
+## Product surface
+
+- **Core product:** {what the buyer pays for}
+- **Key flows:** {top 3 user journeys}
+- **Distribution:** {self-serve, sales-led, marketplace, etc}
+
+## Teams / Squads
+
+| Squad | Domain |
+|-------|--------|
+| {squad-1} | {what it owns} |
+| {squad-2} | {what it owns} |
+
+## Vocabulary
+
+Internal terms that agents should keep native (don't translate):
+
+- {term-1}: {meaning}
+- {term-2}: {meaning}
+
+## Current bets
+
+- {bet 1, with link to the bet doc if any}
+- {bet 2}
+
+## Out of scope
+
+What the team is explicitly not doing right now. Use to push back on scope creep in PRDs.

package/context-library/decisions/README.md

@@ -0,0 +1,3 @@
+# Decisions
+
+ADR-style records. One file per decision: context, options, decision, consequences. SSE agent reads these before proposing technical plans.

package/context-library/example-prds/README.md

@@ -0,0 +1,3 @@
+# Example PRDs
+
+Reference artifacts the PM agent reads to calibrate voice and structure. Drop your best 3-5 PRDs here. The plugin guides also ship with one canonical good example.

package/context-library/personal-context-template.md

@@ -0,0 +1,31 @@
+# Personal Context
+
+> Template. Copy to `personal-context-{your-name}.md` (gitignored). Used by agents to tailor tone, depth, and references to you.
+
+## Role
+
+- **Title:** {e.g. Senior PM, Staff SWE, EM}
+- **Squad:** {squad}
+- **Tenure:** {how long at the org}
+- **Background:** {prior roles, domains}
+
+## Working preferences
+
+- **Output length:** {short / medium / detailed}
+- **Writing voice:** {formal / casual / technical}
+- **Mermaid vs ASCII:** mermaid only
+- **Language:** {English, Portuguese, etc}
+
+## What I care about
+
+- {priority 1}
+- {priority 2}
+- {priority 3}
+
+## What I don't care about
+
+Things you don't want agents to spend tokens on (e.g. excessive intro paragraphs, restating context, exhaustive alternatives).
+
+## Recurring asks
+
+Patterns you ask for often (e.g. "always include a rollback plan", "always link the related ADR").

package/context-library/squads/README.md

@@ -0,0 +1,32 @@
+# Squads
+
+One folder per squad. Each folder contains squad-specific context the agents will read when drafting artifacts owned by that squad.
+
+## Per-squad layout
+
+```
+squads/
+└── {squad-slug}/
+    ├── domain.md           what the squad owns, key entities, lifecycle
+    ├── stack.md            languages, frameworks, infra, datastores
+    ├── owners.md           tech lead, EM, PM, on-call rotation
+    ├── runbooks/           common incident playbooks
+    └── decisions/          squad-level ADRs
+```
+
+## Slug rules
+
+- kebab-case, short (e.g. `billing`, `checkout`, `growth`).
+- The status-line hook uses the slug as a prefix on artifact filenames: `YYYY-MM-DD-{squad}-{slug}.md`.
+
+## Example
+
+```
+squads/
+├── billing/
+│   ├── domain.md
+│   ├── stack.md
+│   └── owners.md
+└── checkout/
+    └── domain.md
+```

package/context-library/strategy/README.md

@@ -0,0 +1,3 @@
+# Strategy
+
+OKRs, roadmaps, bet docs, north-star framing. Files here are read by the PM agent when drafting PRDs/PRPs to anchor scope to current bets.

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@pieerry/harness-kit",
+  "version": "3.0.0",
+  "description": "Claude Code harness for product + engineering delivery. From idea to merged PR, one pipeline.",
+  "author": "Space Metrics AI",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/space-metrics-ai/harness-kit.git"
+  },
+  "homepage": "https://github.com/space-metrics-ai/harness-kit",
+  "keywords": [
+    "claude-code",
+    "claude",
+    "ai",
+    "harness",
+    "agent",
+    "prd",
+    "prp",
+    "engineering",
+    "product-management",
+    "delivery",
+    "pipeline",
+    "plugin"
+  ],
+  "bin": {
+    "hk": "bin/hk.js",
+    "harness-kit": "bin/hk.js"
+  },
+  "files": [
+    "bin",
+    "setup",
+    ".claude",
+    "context-library",
+    "VERSION",
+    "README.md",
+    "LICENSE",
+    "CLAUDE.md"
+  ],
+  "engines": {
+    "node": ">=14.0.0"
+  }
+}