@pieerry/harness-kit 3.0.0

package/.claude/plugins/product-manager/guides/prp-guidelines.md

@@ -0,0 +1,64 @@
+# PRP Guidelines
+
+A PRP is a PRD plus curated codebase intelligence plus an agent runbook. If the executor has to leave the document to figure out what to do, the PRP is incomplete.
+
+## Three pillars
+
+### Context
+
+Everything the executor needs, included or linked. Specific:
+- file paths with line numbers when localized
+- existing patterns to mimic, one concrete example each
+- external docs scoped to the relevant section
+- known gotchas (concurrency, idempotency, retries, timezones)
+
+If the codebase has a similar feature already, point to it. Coding agents do their best work by analogy.
+
+### Implementation detail
+
+Pseudocode or numbered steps concrete enough to translate one-to-one. Include:
+- class names, method signatures, return types where decided
+- schema changes with the actual migration file or DDL
+- endpoint definitions: method, path, request/response shape
+- logging, metrics, alert hooks
+
+You do not write the code. You remove every "what should I name this" decision.
+
+### Validation gates
+
+Real commands the executor runs and passes. Vague checks fail.
+
+Bad:
+- "Make sure tests pass"
+
+Good:
+- `./gradlew :billing-service:test --tests "InvoiceValidator*"`
+- `npm --prefix web run typecheck`
+- `./gradlew :billing-service:detekt`
+
+Manual gates count, but must be specific:
+- [ ] Open `https://staging.example.com/invoices/new` and verify the deadline badge renders for region `EU-WEST`.
+
+## A good PRP
+
+1. Executor reads top-to-bottom, never tabs out except to view linked files.
+2. No decisions left for the executor that change scope.
+3. Every TODO has an owner.
+4. Validation block is copy-pasteable.
+
+## Anti-patterns
+
+- Prose mush where bullets would do
+- Restating the PRD instead of linking
+- Hidden scope ("also we should refactor X")
+- Optimism about state ("there is probably a helper for this already")
+- Fabricated file paths or class names
+
+## When to split a PRP
+
+Split if:
+- scope crosses two repos with independent deploy cycles
+- one PR would exceed ~600 lines
+- independent validation gates pass or fail separately
+
+Otherwise keep it one. Context fragmentation costs more than a slightly longer doc.

package/.claude/plugins/product-manager/guides/templates/prd.md

@@ -0,0 +1,89 @@
+# PRD Template
+
+Fill this template when drafting a Product Requirements Document. Keep section numbering. Replace placeholders. Delete sections that do not apply at the current stage.
+
+---
+
+# PRD: {Title}
+
+**Squad:** {squad} | **DRI (PM):** {name} | **Date:** {YYYY-MM-DD}
+**Stage:** Team Kickoff | Planning Review | Solution Review | Launch Readiness
+**Bet:** {link or N/A}
+**Status:** Draft | In Review | Approved | Shipped
+
+## 1) Problem and Hypothesis
+
+**Problem** (2 sentences max): Who suffers, how often, what it costs.
+
+**Hypothesis:** If we {build X}, then {Y metric} will {change by Z}, because {assumption}.
+
+**Strategy fit:** This supports {pillar} because {why now}.
+
+**Evidence:**
+- {user quote / data point / ticket id}
+
+## 2) Customers
+
+| Customer | Why it matters |
+|----------|----------------|
+| {name}   | {context}      |
+
+## 3) Scope and Non-Goals
+
+**In scope:**
+- {bullet}
+
+**Non-goals (max 3):**
+- {what we are NOT doing and why}
+
+**Trade-offs accepted:**
+- {bullet}
+
+## 4) Solution Overview
+
+**Summary:** 2-3 paragraphs.
+
+**User flow:** numbered steps or Mermaid.
+
+**User stories:**
+- As a {persona}, I want {action}, so that {benefit}.
+
+**UX reference:** {Figma or experience expected}.
+
+## 5) Success Metrics
+
+| Metric | Baseline | Target | Horizon |
+|--------|----------|--------|---------|
+| {name} | {value}  | {value}| {N days}|
+
+**Guardrails (must not harm):**
+- {metric}: {range}
+
+**Kill criteria:** If {condition with numeric threshold}, we will {rollback / pause / iterate}.
+
+## 6) Rollout
+
+| Phase | Audience | Duration | Pass criteria |
+|-------|----------|----------|---------------|
+| 1     |          |          |               |
+
+## 7) Risks
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|-----------|--------|------------|
+
+## 8) Owners and Open Questions
+
+**DRI:** {name}
+**Reviewers:** {eng, design, legal, support}
+
+**Open questions:**
+- [ ] {question}, owner @{name}
+
+## 9) Appendix
+
+**Alternatives considered:**
+- {bullet with reason for rejection}
+
+**Research quotes:**
+- {direct quote with source}

package/.claude/plugins/product-manager/guides/templates/prp.md

@@ -0,0 +1,98 @@
+# PRP Template
+
+Fill this template when drafting a Product Requirements Prompt. Keep section numbering. Replace placeholders. Pin every reference to a real file or URL.
+
+---
+
+# PRP: {Title}
+
+**Source PRD:** {path}
+**Target executor:** coding-agent | engineer | mixed
+**Squad:** {squad} | **Tech lead:** {name} | **Date:** {YYYY-MM-DD}
+
+## 1) Goal
+
+One paragraph. What the executor must ship. Tied to the PRD's hypothesis.
+
+## 2) Why
+
+- business value
+- user impact
+- strategic tie
+
+## 3) What
+
+**User-visible behavior:**
+- {bullet}
+
+**Out of scope:**
+- {what NOT to build}
+
+**Success criteria (verifiable):**
+- [ ] {Given/When/Then or measurable check}
+
+## 4) Context
+
+### Repos and files touched
+
+| Repo | File | Change type | Reference |
+|------|------|-------------|-----------|
+| {repo} | {file:line} | new \| modify \| delete | {link or PR id} |
+
+### Patterns to follow
+
+- **Pattern:** {name}
+  **Example in codebase:** `{file:line}`
+  **Why follow it:** {1 sentence}
+
+### External documentation
+
+- {URL}: {what to read, which section}
+
+### Known gotchas
+
+- {gotcha}: {how to handle}
+
+## 5) Implementation blueprint
+
+```
+1. Add {class} at {path}
+2. Wire into {existing class} at {file:line}
+3. Add migration {script name}
+4. Expose endpoint {METHOD /path}
+```
+
+**Data:**
+- Schema changes: {DDL or migration file name}
+- Volumes expected: {rows/day, peak rps}
+
+**Observability:**
+- Logs: {what to log, level, where}
+- Metrics: {metric name + dashboard link}
+- Alerts: {condition: action}
+
+## 6) Validation gates
+
+```bash
+{commands the executor MUST run}
+```
+
+**Manual verification:**
+- [ ] {step that requires human or browser check}
+
+## 7) Rollout
+
+- [ ] Feature flag: {flag name or "none"}
+- [ ] Migration required: {yes/no, plan}
+- [ ] Rollback plan: {one-line description}
+
+## 8) Open items
+
+- [ ] {item}, owner @{name}
+
+## 9) References
+
+- PRD: {path}
+- ADR: {link}
+- Design doc: {link}
+- Dashboards: {link}

package/.claude/plugins/product-manager/guides/writing-style.md

@@ -0,0 +1,71 @@
+# Writing Style
+
+How PRDs and PRPs read .
+
+## Voice
+
+- Direct. Lead with the point.
+- Specific. Real numbers, real names, real quotes. "47% abandon at step 3" beats "many users struggle".
+- Conversational, professional. Contractions ok. Use "we", not "I".
+- Action-oriented. Every section helps a reader decide or act.
+
+## Length
+
+- Shorter beats longer.
+- Vary sentence length. Short ones land harder.
+- One idea per bullet.
+
+## Audience modes
+
+- Internal team: conversational, bullets over paragraphs, "we" framing
+- Executives: lead with so-what, numbers first, decision asked explicitly
+- Engineering (PRP): precise terms, edge cases upfront, constraints visible
+- End users (in product): 8th-grade reading level, benefits before features
+
+## Banned words
+
+Dead giveaways for AI fluff:
+- delve, leverage, utilize, unlock, harness, streamline, robust, cutting-edge
+- "in today's fast-paced world", "at the end of the day", "best-in-class"
+- "I'd be happy to", "Of course!", "Certainly", "Sure!"
+- "Hope this helps", "Let me know if you need anything else"
+
+## Punctuation
+
+- No em-dashes. Use commas, periods, parentheses, or a new sentence.
+- Oxford comma: yes.
+- One space after a period.
+
+## Negative parallelism
+
+Avoid. Lead with the positive:
+- bad: "Don't use X. Use Y."
+- good: "Use Y."
+
+## AI-detector test
+
+If a paragraph sounds like a LinkedIn post, rewrite it. Real human writing:
+- occasional sentence starting with "And" or "But"
+- specific details a generic writer would not know
+- slightly imperfect rhythm
+- mid-paragraph asides
+
+Embed naturally, do not perform.
+
+## Quoting users
+
+Direct quotes with source:
+
+> "By the time I add everything, she remembers 3 more things and I have to edit the cart again." Priya, Mumbai, support ticket #1842
+
+Not:
+
+> "Users often experience frustration with the cart editing experience."
+
+## Tables
+
+Use when you have comparison across 3+ items, structured data with same fields per row, or decision matrices. Otherwise use bullets.
+
+## Diagrams
+
+Mermaid only. Never ASCII art.

package/.claude/plugins/product-manager/hooks/post-eval-prd.sh

@@ -0,0 +1,77 @@
+#!/bin/bash
+# Fires after Edit tool appends the approval marker. Detects the marker,
+# closes the validate phase, runs token accounting, and triggers publish.
+#
+# Registered in .claude/settings.json under PostToolUse > Edit.
+
+set -euo pipefail
+
+FILE_PATH="${CLAUDE_TOOL_FILE_PATH:-}"
+PLUGIN_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+
+case "$FILE_PATH" in
+  *.claude/plugins/product-manager/outputs/prd/*.md) ;;
+  *) exit 0 ;;
+esac
+
+if ! grep -q "<!-- approved:" "$FILE_PATH"; then
+  exit 0
+fi
+
+if grep -q "<!-- published:" "$FILE_PATH"; then
+  exit 0
+fi
+
+echo "[hook] PRD approved, publishing $(basename "$FILE_PATH")" >&2
+
+FEATURE_ID="$(basename "$FILE_PATH" .md)"
+MARKERS_DIR="$PLUGIN_DIR/outputs/.markers"
+mkdir -p "$MARKERS_DIR"
+NOW="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+
+# Close validate phase
+if [ -f "$MARKERS_DIR/${FEATURE_ID}.prd-validate.start" ]; then
+  printf '{"timestamp":"%s"}\n' "$NOW" > "$MARKERS_DIR/${FEATURE_ID}.prd-validate.end"
+fi
+
+# Token accounting for both phases
+python3 "$PLUGIN_DIR/scripts/token-phase.py" \
+  --feature-id "$FEATURE_ID" \
+  --phase "prd-generate" \
+  --plugin-dir "$PLUGIN_DIR" \
+  --prd-path "$FILE_PATH" >&2 || true
+
+python3 "$PLUGIN_DIR/scripts/token-phase.py" \
+  --feature-id "$FEATURE_ID" \
+  --phase "prd-validate" \
+  --plugin-dir "$PLUGIN_DIR" \
+  --prd-path "$FILE_PATH" >&2 || true
+
+# Confluence (optional)
+if [ -n "${JIRA_USERNAME:-}" ] && [ -n "${JIRA_API_TOKEN:-}" ]; then
+  python3 "$PLUGIN_DIR/scripts/confluence-publish.py" \
+    --artifact "$FILE_PATH" \
+    --kind prd >&2 || {
+      echo "[hook] Confluence publish failed but local copy is saved" >&2
+    }
+else
+  echo "[hook] Confluence creds not set (JIRA_USERNAME, JIRA_API_TOKEN). Local save only." >&2
+fi
+
+# Append published marker + inline tokens reference
+TOKENS_FILE="$PLUGIN_DIR/outputs/tokens/${FEATURE_ID}.json"
+if [ -f "$TOKENS_FILE" ]; then
+  TOKENS_LINE=$(python3 -c "
+import json,sys
+with open('$TOKENS_FILE') as f:
+    d=json.load(f)
+t=d.get('totals',{})
+print(f'<!-- tokens: outputs/tokens/${FEATURE_ID}.json in={t.get(\"input\",0)} out={t.get(\"output\",0)} cache_r={t.get(\"cache_read\",0)} -->')
+")
+  printf '\n%s\n' "$TOKENS_LINE" >> "$FILE_PATH"
+fi
+
+printf '\n<!-- published: %s -->\n' "$NOW" >> "$FILE_PATH"
+
+echo "[hook] PRD published" >&2
+exit 0

package/.claude/plugins/product-manager/hooks/post-eval-prp.sh

@@ -0,0 +1,70 @@
+#!/bin/bash
+# Fires after Edit tool appends the approval marker on a PRP.
+# Closes validate phase, runs token accounting, finalizes handoff.
+#
+# Registered in .claude/settings.json under PostToolUse > Edit.
+
+set -euo pipefail
+
+FILE_PATH="${CLAUDE_TOOL_FILE_PATH:-}"
+PLUGIN_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+
+case "$FILE_PATH" in
+  *.claude/plugins/product-manager/outputs/prp/*.md) ;;
+  *) exit 0 ;;
+esac
+
+if ! grep -q "<!-- approved:" "$FILE_PATH"; then
+  exit 0
+fi
+
+if grep -q "<!-- published:" "$FILE_PATH"; then
+  exit 0
+fi
+
+echo "[hook] PRP approved, finalizing handoff for $(basename "$FILE_PATH")" >&2
+
+FEATURE_ID="$(basename "$FILE_PATH" .md)"
+MARKERS_DIR="$PLUGIN_DIR/outputs/.markers"
+mkdir -p "$MARKERS_DIR"
+NOW="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+
+if [ -f "$MARKERS_DIR/${FEATURE_ID}.prp-validate.start" ]; then
+  printf '{"timestamp":"%s"}\n' "$NOW" > "$MARKERS_DIR/${FEATURE_ID}.prp-validate.end"
+fi
+
+python3 "$PLUGIN_DIR/scripts/token-phase.py" \
+  --feature-id "$FEATURE_ID" \
+  --phase "prp-generate" \
+  --plugin-dir "$PLUGIN_DIR" \
+  --prp-path "$FILE_PATH" >&2 || true
+
+python3 "$PLUGIN_DIR/scripts/token-phase.py" \
+  --feature-id "$FEATURE_ID" \
+  --phase "prp-validate" \
+  --plugin-dir "$PLUGIN_DIR" \
+  --prp-path "$FILE_PATH" >&2 || true
+
+if [ -n "${JIRA_USERNAME:-}" ] && [ -n "${JIRA_API_TOKEN:-}" ]; then
+  python3 "$PLUGIN_DIR/scripts/confluence-publish.py" \
+    --artifact "$FILE_PATH" \
+    --kind prp >&2 || true
+fi
+
+# Inline tokens summary
+TOKENS_FILE="$PLUGIN_DIR/outputs/tokens/${FEATURE_ID}.json"
+if [ -f "$TOKENS_FILE" ]; then
+  TOKENS_LINE=$(python3 -c "
+import json,sys
+with open('$TOKENS_FILE') as f:
+    d=json.load(f)
+t=d.get('totals',{})
+print(f'<!-- tokens: outputs/tokens/${FEATURE_ID}.json in={t.get(\"input\",0)} out={t.get(\"output\",0)} cache_r={t.get(\"cache_read\",0)} -->')
+")
+  printf '\n%s\n' "$TOKENS_LINE" >> "$FILE_PATH"
+fi
+
+printf '\n<!-- published: %s -->\n' "$NOW" >> "$FILE_PATH"
+
+echo "[hook] PRP handoff complete" >&2
+exit 0

package/.claude/plugins/product-manager/hooks/post-write-prd.sh

@@ -0,0 +1,56 @@
+#!/bin/bash
+# Fires after Write tool saves a file. If the file is a PRD draft, runs the
+# deterministic sensor pipeline and writes phase markers for token accounting.
+#
+# Registered in .claude/settings.json under PostToolUse > Write.
+
+set -euo pipefail
+
+FILE_PATH="${CLAUDE_TOOL_FILE_PATH:-}"
+PLUGIN_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+
+case "$FILE_PATH" in
+  *.claude/plugins/product-manager/outputs/prd/*.md) ;;
+  *) exit 0 ;;
+esac
+
+# Skip if file already approved (avoid loops)
+if grep -q "<!-- approved:" "$FILE_PATH" 2>/dev/null; then
+  exit 0
+fi
+
+echo "[hook] Running PRD sensors on $(basename "$FILE_PATH")" >&2
+
+FAILURES=()
+for sensor in "$PLUGIN_DIR"/sensors/prd-*.md; do
+  [ -f "$sensor" ] || continue
+  if ! python3 "$PLUGIN_DIR/scripts/sensor-runner.py" \
+        --sensor "$sensor" \
+        --artifact "$FILE_PATH" >&2; then
+    FAILURES+=("$(basename "$sensor")")
+  fi
+done
+
+if [ ${#FAILURES[@]} -gt 0 ]; then
+  echo "" >&2
+  echo "[hook] PRD sensor failures: ${FAILURES[*]}" >&2
+  echo "[hook] Read the messages above and regenerate the failed sections." >&2
+  exit 2
+fi
+
+echo "[hook] PRD sensors passed" >&2
+
+# Token phase markers: only on first save (no validate.start yet)
+FEATURE_ID="$(basename "$FILE_PATH" .md)"
+MARKERS_DIR="$PLUGIN_DIR/outputs/.markers"
+mkdir -p "$MARKERS_DIR"
+NOW="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+
+if [ ! -f "$MARKERS_DIR/${FEATURE_ID}.prd-validate.start" ]; then
+  if [ -f "$MARKERS_DIR/${FEATURE_ID}.prd-generate.start" ]; then
+    printf '{"timestamp":"%s"}\n' "$NOW" > "$MARKERS_DIR/${FEATURE_ID}.prd-generate.end"
+    printf '{"timestamp":"%s","session_id":"%s"}\n' "$NOW" "${CLAUDE_SESSION_ID:-}" > "$MARKERS_DIR/${FEATURE_ID}.prd-validate.start"
+  fi
+fi
+
+exit 0

package/.claude/plugins/product-manager/hooks/post-write-prp.sh

@@ -0,0 +1,61 @@
+#!/bin/bash
+# Fires after Write tool saves a file. If the file is a PRP draft, runs
+# structural sensors plus link validation and writes phase markers.
+#
+# Registered in .claude/settings.json under PostToolUse > Write.
+
+set -euo pipefail
+
+FILE_PATH="${CLAUDE_TOOL_FILE_PATH:-}"
+PLUGIN_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+
+case "$FILE_PATH" in
+  *.claude/plugins/product-manager/outputs/prp/*.md) ;;
+  *) exit 0 ;;
+esac
+
+if grep -q "<!-- approved:" "$FILE_PATH" 2>/dev/null; then
+  exit 0
+fi
+
+echo "[hook] Running PRP sensors on $(basename "$FILE_PATH")" >&2
+
+FAILURES=()
+for sensor in "$PLUGIN_DIR"/sensors/prp-*.md; do
+  [ -f "$sensor" ] || continue
+  if ! python3 "$PLUGIN_DIR/scripts/sensor-runner.py" \
+        --sensor "$sensor" \
+        --artifact "$FILE_PATH" >&2; then
+    FAILURES+=("$(basename "$sensor")")
+  fi
+done
+
+if ! python3 "$PLUGIN_DIR/scripts/link-validator.py" \
+      --artifact "$FILE_PATH" \
+      --repo-root "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" >&2; then
+  FAILURES+=("link-validator")
+fi
+
+if [ ${#FAILURES[@]} -gt 0 ]; then
+  echo "" >&2
+  echo "[hook] PRP sensor failures: ${FAILURES[*]}" >&2
+  echo "[hook] Read the messages above and regenerate the failed sections." >&2
+  exit 2
+fi
+
+echo "[hook] PRP sensors passed" >&2
+
+# Token phase markers
+FEATURE_ID="$(basename "$FILE_PATH" .md)"
+MARKERS_DIR="$PLUGIN_DIR/outputs/.markers"
+mkdir -p "$MARKERS_DIR"
+NOW="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+
+if [ ! -f "$MARKERS_DIR/${FEATURE_ID}.prp-validate.start" ]; then
+  if [ -f "$MARKERS_DIR/${FEATURE_ID}.prp-generate.start" ]; then
+    printf '{"timestamp":"%s"}\n' "$NOW" > "$MARKERS_DIR/${FEATURE_ID}.prp-generate.end"
+    printf '{"timestamp":"%s","session_id":"%s"}\n' "$NOW" "${CLAUDE_SESSION_ID:-}" > "$MARKERS_DIR/${FEATURE_ID}.prp-validate.start"
+  fi
+fi
+
+exit 0

package/.claude/plugins/product-manager/hooks/pre-prp-check.sh

@@ -0,0 +1,48 @@
+#!/bin/bash
+# Fires before Write tool creates a PRP file. Refuses if there is no approved
+# PRD for the same feature slug.
+#
+# Registered in .claude/settings.json under PreToolUse > Write matcher.
+
+set -euo pipefail
+
+FILE_PATH="${CLAUDE_TOOL_FILE_PATH:-}"
+PLUGIN_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+
+case "$FILE_PATH" in
+  *.claude/plugins/product-manager/outputs/prp/*.md) ;;
+  *) exit 0 ;;
+esac
+
+# Allow rewrites of an existing PRP
+if [ -f "$FILE_PATH" ]; then
+  exit 0
+fi
+
+# Extract slug from PRP filename: YYYY-MM-DD-{slug}.md
+PRP_BASENAME="$(basename "$FILE_PATH" .md)"
+SLUG="$(echo "$PRP_BASENAME" | sed -E 's/^[0-9]{4}-[0-9]{2}-[0-9]{2}-//')"
+
+if [ -z "$SLUG" ]; then
+  echo "[hook] PRP filename must follow YYYY-MM-DD-{slug}.md. Got: $PRP_BASENAME" >&2
+  exit 2
+fi
+
+# Look for any approved PRD matching the slug
+MATCHED=""
+for prd in "$PLUGIN_DIR"/outputs/prd/*"-${SLUG}.md"; do
+  [ -f "$prd" ] || continue
+  if grep -q "<!-- approved:" "$prd"; then
+    MATCHED="$prd"
+    break
+  fi
+done
+
+if [ -z "$MATCHED" ]; then
+  echo "[hook] No approved PRD found for slug '$SLUG'." >&2
+  echo "[hook] Run /product-manager:prd first and ensure the PRD has the <!-- approved: --> marker." >&2
+  exit 2
+fi
+
+echo "[hook] PRP gate cleared: source PRD: $(basename "$MATCHED")" >&2
+exit 0