@pieerry/harness-kit 3.3.1 → 4.0.0

package/setup/install.sh

@@ -1,7 +1,8 @@
 #!/usr/bin/env bash
-# harness-kit installer. Copies plugins, status-line hook, and
-# settings.json into a target repo. Reads VERSION at the repo root and records
-# it in the target.
+# harness-kit installer (v4). Copies agents, runtime hooks/scripts,
+# root hooks/scripts, slash commands, AGENTS.md/CLAUDE.md, and writes
+# the wiring settings.json into a target repo. Reads VERSION at the
+# repo root and records it in the target.
 #
 # Usage:
 #   bash /path/to/harness-kit/setup/install.sh [target-dir]
@@ -14,8 +15,8 @@ TARGET="${1:-${TARGET:-$(pwd)}}"
 
 VERSION="$(cat "$SOURCE_ROOT/VERSION" 2>/dev/null || echo "0.0.0")"
 
-if [ ! -d "$SOURCE_ROOT/.claude/plugins/product-manager" ]; then
-  echo "missing plugins at $SOURCE_ROOT/.claude/plugins/"
+if [ ! -d "$SOURCE_ROOT/.claude/agents/product-manager" ]; then
+  echo "missing agents at $SOURCE_ROOT/.claude/agents/"
   echo "clone the repo first, then re-run: git clone https://github.com/Pierry/harness-kit ~/.harness-kit"
   exit 1
 fi
@@ -33,47 +34,61 @@ else
   echo "harness-kit v$VERSION installing at $TARGET"
 fi
 
-# Copy plugin support code (hooks, scripts, guides, sensors, evals, skills, outputs)
-mkdir -p "$TARGET/.claude/plugins"
-for plugin in product-manager staff-software-engineer; do
-  rm -rf "$TARGET/.claude/plugins/$plugin"
-  cp -R "$SOURCE_ROOT/.claude/plugins/$plugin" "$TARGET/.claude/plugins/$plugin"
+# Migrate legacy v3.x layout if detected. Backs up to .claude/.legacy-v3-backup/.
+if [ -d "$TARGET/.claude/plugins" ]; then
+  echo "  detected legacy v3.x plugins/ — backing up to .claude/.legacy-v3-backup/"
+  STAMP="$(date +%Y%m%d-%H%M%S)"
+  mkdir -p "$TARGET/.claude/.legacy-v3-backup"
+  mv "$TARGET/.claude/plugins" "$TARGET/.claude/.legacy-v3-backup/plugins.$STAMP"
+fi
+
+# 1) AGENTS.md + CLAUDE.md at the repo root.
+cp "$SOURCE_ROOT/AGENTS.md" "$TARGET/AGENTS.md"
+if [ ! -f "$TARGET/CLAUDE.md" ]; then
+  cp "$SOURCE_ROOT/CLAUDE.md" "$TARGET/CLAUDE.md"
+fi
+
+# 2) Agent definitions (sensors, evals, guides, skills, README + orchestrator .md)
+mkdir -p "$TARGET/.claude/agents"
+for agent in product-manager staff-software-engineer; do
+  rm -rf "$TARGET/.claude/agents/$agent"
+  cp -R "$SOURCE_ROOT/.claude/agents/$agent" "$TARGET/.claude/agents/$agent"
+  cp "$SOURCE_ROOT/.claude/agents/$agent.md" "$TARGET/.claude/agents/$agent.md"
+done
+
+# 3) Per-agent runtime hooks + scripts (NOT outputs — that's target-side state)
+mkdir -p "$TARGET/.claude/runtime/hooks" "$TARGET/.claude/runtime/scripts" "$TARGET/.claude/runtime/outputs/pm/.markers" "$TARGET/.claude/runtime/outputs/sse/.markers"
+for agent in product-manager staff-software-engineer; do
+  rm -rf "$TARGET/.claude/runtime/hooks/$agent"
+  cp -R "$SOURCE_ROOT/.claude/runtime/hooks/$agent" "$TARGET/.claude/runtime/hooks/$agent"
+  rm -rf "$TARGET/.claude/runtime/scripts/$agent"
+  cp -R "$SOURCE_ROOT/.claude/runtime/scripts/$agent" "$TARGET/.claude/runtime/scripts/$agent"
 done
 
-# Re-resolve symlinks in SSE scripts
-for f in "$TARGET/.claude/plugins/staff-software-engineer/scripts/"*; do
+# Re-resolve symlinks in SSE scripts (point at PM's shared utilities)
+for f in "$TARGET/.claude/runtime/scripts/staff-software-engineer/"*; do
   if [ -L "$f" ]; then
     name="$(basename "$f")"
     rm "$f"
-    ln -sf "../../product-manager/scripts/$name" "$f"
+    ln -sf "../product-manager/$name" "$f"
   fi
 done
 
-# Copy slash commands and Task-invokable agents
-mkdir -p "$TARGET/.claude/commands" "$TARGET/.claude/agents"
+# 4) Slash commands
+mkdir -p "$TARGET/.claude/commands"
 for ns in product-manager sse pipeline; do
   rm -rf "$TARGET/.claude/commands/$ns"
   cp -R "$SOURCE_ROOT/.claude/commands/$ns" "$TARGET/.claude/commands/$ns"
 done
-for agent in product-manager staff-software-engineer; do
-  cp "$SOURCE_ROOT/.claude/agents/$agent.md" "$TARGET/.claude/agents/$agent.md"
-done
-
-# Clean up legacy plugin layout from older installs
-for plugin in product-manager staff-software-engineer; do
-  rm -rf "$TARGET/.claude/plugins/$plugin/commands" \
-         "$TARGET/.claude/plugins/$plugin/agents" \
-         "$TARGET/.claude/plugins/$plugin/.claude-plugin"
-done
 
-# Copy harness-kit hooks (status-line + pipeline tracking + live activity)
+# 5) Root harness hooks (status-line + pipeline tracking + live activity)
 mkdir -p "$TARGET/.claude/hooks"
 for h in status-line.sh pipeline-prompt.sh pipeline-postwrite.sh pipeline-postedit.sh pipeline-session-start.sh activity-pre-read.sh; do
   cp "$SOURCE_ROOT/.claude/hooks/$h" "$TARGET/.claude/hooks/$h"
   chmod +x "$TARGET/.claude/hooks/$h"
 done
 
-# Copy harness-kit scripts (pipeline state, activity tracker, PR monitor, stage-card)
+# 6) Root harness scripts (pipeline state, activity, PR monitor, stage-card)
 mkdir -p "$TARGET/.claude/scripts"
 for s in pipeline.py activity.py pr-monitor.py; do
   cp "$SOURCE_ROOT/.claude/scripts/$s" "$TARGET/.claude/scripts/$s"
@@ -81,7 +96,11 @@ for s in pipeline.py activity.py pr-monitor.py; do
 done
 cp "$SOURCE_ROOT/.claude/scripts/stage-card.md" "$TARGET/.claude/scripts/stage-card.md"
 
-# Settings.json (back up existing if content differs)
+# 6.5) Strip any __pycache__/.pyc that hitched a ride from the source repo
+find "$TARGET/.claude" -name __pycache__ -type d -prune -exec rm -rf {} + 2>/dev/null || true
+find "$TARGET/.claude" -name "*.pyc" -type f -delete 2>/dev/null || true
+
+# 7) settings.json (back up existing if content differs)
 if [ -f "$TARGET/.claude/settings.json" ]; then
   STAMP="$(date +%Y%m%d-%H%M%S)"
   BACKUP="$TARGET/.claude/settings.json.bak.$STAMP"
@@ -99,8 +118,8 @@ cat > "$TARGET/.claude/settings.json" <<'EOF'
       "Bash(npm:*)",
       "Bash(gh:*)",
       "Bash(jq:*)",
-      "Read(outputs/**)",
-      "Write(outputs/**)"
+      "Read(.claude/runtime/outputs/**)",
+      "Write(.claude/runtime/outputs/**)"
     ],
     "deny": [
       "Bash(rm -rf:*)",
@@ -128,7 +147,7 @@ cat > "$TARGET/.claude/settings.json" <<'EOF'
       {
         "matcher": "Write",
         "hooks": [
-          { "type": "command", "command": "[ -x .claude/plugins/product-manager/hooks/pre-prp-check.sh ] && bash .claude/plugins/product-manager/hooks/pre-prp-check.sh; exit 0" }
+          { "type": "command", "command": "[ -x .claude/runtime/hooks/product-manager/pre-prp-check.sh ] && bash .claude/runtime/hooks/product-manager/pre-prp-check.sh; exit 0" }
         ]
       },
       {
@@ -142,18 +161,18 @@ cat > "$TARGET/.claude/settings.json" <<'EOF'
       {
         "matcher": "Write",
         "hooks": [
-          { "type": "command", "command": "[ -x .claude/plugins/product-manager/hooks/post-write-prd.sh ] && bash .claude/plugins/product-manager/hooks/post-write-prd.sh; exit 0" },
-          { "type": "command", "command": "[ -x .claude/plugins/product-manager/hooks/post-write-prp.sh ] && bash .claude/plugins/product-manager/hooks/post-write-prp.sh; exit 0" },
-          { "type": "command", "command": "[ -x .claude/plugins/staff-software-engineer/hooks/post-write-sse.sh ] && bash .claude/plugins/staff-software-engineer/hooks/post-write-sse.sh; exit 0" },
+          { "type": "command", "command": "[ -x .claude/runtime/hooks/product-manager/post-write-prd.sh ] && bash .claude/runtime/hooks/product-manager/post-write-prd.sh; exit 0" },
+          { "type": "command", "command": "[ -x .claude/runtime/hooks/product-manager/post-write-prp.sh ] && bash .claude/runtime/hooks/product-manager/post-write-prp.sh; exit 0" },
+          { "type": "command", "command": "[ -x .claude/runtime/hooks/staff-software-engineer/post-write-sse.sh ] && bash .claude/runtime/hooks/staff-software-engineer/post-write-sse.sh; exit 0" },
           { "type": "command", "command": "[ -x .claude/hooks/pipeline-postwrite.sh ] && bash .claude/hooks/pipeline-postwrite.sh; exit 0" }
         ]
       },
       {
         "matcher": "Edit",
         "hooks": [
-          { "type": "command", "command": "[ -x .claude/plugins/product-manager/hooks/post-eval-prd.sh ] && bash .claude/plugins/product-manager/hooks/post-eval-prd.sh; exit 0" },
-          { "type": "command", "command": "[ -x .claude/plugins/product-manager/hooks/post-eval-prp.sh ] && bash .claude/plugins/product-manager/hooks/post-eval-prp.sh; exit 0" },
-          { "type": "command", "command": "[ -x .claude/plugins/staff-software-engineer/hooks/post-eval-sse.sh ] && bash .claude/plugins/staff-software-engineer/hooks/post-eval-sse.sh; exit 0" },
+          { "type": "command", "command": "[ -x .claude/runtime/hooks/product-manager/post-eval-prd.sh ] && bash .claude/runtime/hooks/product-manager/post-eval-prd.sh; exit 0" },
+          { "type": "command", "command": "[ -x .claude/runtime/hooks/product-manager/post-eval-prp.sh ] && bash .claude/runtime/hooks/product-manager/post-eval-prp.sh; exit 0" },
+          { "type": "command", "command": "[ -x .claude/runtime/hooks/staff-software-engineer/post-eval-sse.sh ] && bash .claude/runtime/hooks/staff-software-engineer/post-eval-sse.sh; exit 0" },
           { "type": "command", "command": "[ -x .claude/hooks/pipeline-postedit.sh ] && bash .claude/hooks/pipeline-postedit.sh; exit 0" }
         ]
       }
@@ -172,16 +191,16 @@ if [ ! -f "$TARGET/.claude/conventions/README.md" ]; then
   cat > "$TARGET/.claude/conventions/README.md" <<'EOF'
 # Project Conventions
 
-Override staff-software-engineer plugin defaults for this repo. Create files as needed:
+Override staff-software-engineer defaults for this repo. Create files as needed:
 
 - backend.md
 - web.md
 - mobile.md
 - devops.md
 
-When a file exists here, plugin reads it on top of defaults. Rules in this folder win.
+When a file exists here, the agent reads it on top of defaults. Rules in this folder win.
 
-See `.claude/plugins/staff-software-engineer/guides/conventions-override.md` for the full reference.
+See `.claude/agents/staff-software-engineer/guides/conventions-override.md` for the full reference.
 EOF
 fi
 

package/setup/update.sh

@@ -3,6 +3,11 @@
 # the installer. For npm installs, you must upgrade the package first:
 #   npm i -g @pieerry/harness-kit@latest
 #
+# v3.x → v4.x migration: install.sh detects a legacy .claude/plugins/ tree in
+# the target and backs it up to .claude/.legacy-v3-backup/ before laying down
+# the v4 structure (.claude/agents/, .claude/runtime/, AGENTS.md). Custom
+# edits inside the legacy tree are preserved in the backup for manual merge.
+#
 # Usage:
 #   bash /path/to/harness-kit/setup/update.sh [target-dir]
 

package/.claude/plugins/product-manager/scripts/confluence-publish.py

@@ -1,205 +0,0 @@
-#!/usr/bin/env python3
-"""
-Publish a PRD or PRP to Confluence.
-
-Reads credentials from environment:
- - JIRA_USERNAME (email)
- - JIRA_API_TOKEN (API token)
-
-Targets the Confluence at https://YOUR-DOMAIN.atlassian.net.
-
-Usage:
- confluence-publish.py --artifact PATH.md --kind {prd|prp}
-
-Exit 0 on success, 1 on failure. Stays silent on routine output, prints
-errors to stderr.
-"""
-
-import argparse
-import base64
-import html
-import json
-import os
-import re
-import sys
-import urllib.request
-from pathlib import Path
-
-CONFLUENCE_BASE = "https://YOUR-DOMAIN.atlassian.net/wiki/rest/api/content"
-SPACE_KEY = "TET1"
-
-# Parent page IDs per kind. Override via env if needed.
-PARENT_IDS = {
- "prd": os.environ.get("CONFLUENCE_PARENT_PRD", "11351457795"),
- "prp": os.environ.get("CONFLUENCE_PARENT_PRP", "11351457795"),
-}
-
-
-def md_to_storage(md: str) -> str:
- """Minimal Markdown to Confluence storage XHTML.
- Good enough for headings, paragraphs, fenced code, lists, tables.
- For richer rendering, swap for a real converter later.
- """
- lines = md.splitlines()
- out: list[str] = []
- in_code = False
- in_list: str | None = None # 'ul' or 'ol'
- in_table = False
-
- def close_list():
- nonlocal in_list
- if in_list:
- out.append(f"</{in_list}>")
- in_list = None
-
- def close_table():
- nonlocal in_table
- if in_table:
- out.append("</tbody></table>")
- in_table = False
-
- for line in lines:
- if line.startswith("```"):
- close_list()
- close_table()
- if not in_code:
- lang = line[3:].strip() or "none"
- out.append(
- f'<ac:structured-macro ac:name="code">'
- f'<ac:parameter ac:name="language">{html.escape(lang)}</ac:parameter>'
- f'<ac:plain-text-body><![CDATA['
- )
- in_code = True
- else:
- out.append("]]></ac:plain-text-body></ac:structured-macro>")
- in_code = False
- continue
-
- if in_code:
- out.append(line)
- continue
-
- h = re.match(r"^(#{1,6})\s+(.+)$", line)
- if h:
- close_list()
- close_table()
- level = len(h.group(1))
- out.append(f"<h{level}>{html.escape(h.group(2))}</h{level}>")
- continue
-
- if re.match(r"^[-*]\s+", line):
- close_table()
- if in_list != "ul":
- close_list()
- out.append("<ul>")
- in_list = "ul"
- item = re.sub(r"^[-*]\s+", "", line)
- out.append(f"<li>{html.escape(item)}</li>")
- continue
-
- if re.match(r"^\d+\.\s+", line):
- close_table()
- if in_list != "ol":
- close_list()
- out.append("<ol>")
- in_list = "ol"
- item = re.sub(r"^\d+\.\s+", "", line)
- out.append(f"<li>{html.escape(item)}</li>")
- continue
-
- if line.startswith("|") and "|" in line[1:]:
- close_list()
- cells = [c.strip() for c in line.strip("|").split("|")]
- if not in_table:
- out.append("<table><tbody>")
- in_table = True
- out.append(
- "<tr>"
- + "".join(f"<th>{html.escape(c)}</th>" for c in cells)
- + "</tr>"
- )
- elif all(re.fullmatch(r":?-+:?", c) for c in cells):
- # separator row, skip
- pass
- else:
- out.append(
- "<tr>"
- + "".join(f"<td>{html.escape(c)}</td>" for c in cells)
- + "</tr>"
- )
- continue
-
- # paragraph or blank
- close_list()
- close_table()
- if line.strip():
- out.append(f"<p>{html.escape(line)}</p>")
-
- close_list()
- close_table()
- return "\n".join(out)
-
-
-def extract_title(md: str) -> str:
- for line in md.splitlines():
- m = re.match(r"^#\s+(.+)$", line)
- if m:
- return m.group(1).strip()
- return "Untitled"
-
-
-def main() -> int:
- parser = argparse.ArgumentParser()
- parser.add_argument("--artifact", required=True, type=Path)
- parser.add_argument("--kind", required=True, choices=["prd", "prp"])
- args = parser.parse_args()
-
- username = os.environ.get("JIRA_USERNAME")
- token = os.environ.get("JIRA_API_TOKEN")
- if not username or not token:
- print("[confluence-publish] JIRA_USERNAME/JIRA_API_TOKEN not set", file=sys.stderr)
- return 1
-
- md = args.artifact.read_text(encoding="utf-8")
- title = extract_title(md)
- storage = md_to_storage(md)
-
- payload = {
- "type": "page",
- "title": title,
- "ancestors": [{"id": PARENT_IDS[args.kind]}],
- "space": {"key": SPACE_KEY},
- "body": {"storage": {"value": storage, "representation": "storage"}},
- }
-
- auth = base64.b64encode(f"{username}:{token}".encode()).decode()
- req = urllib.request.Request(
- CONFLUENCE_BASE,
- data=json.dumps(payload).encode("utf-8"),
- method="POST",
- headers={
- "Authorization": f"Basic {auth}",
- "Content-Type": "application/json",
- "Accept": "application/json",
- },
- )
-
- try:
- with urllib.request.urlopen(req, timeout=20) as resp:
- data = json.loads(resp.read().decode("utf-8"))
- page_url = data.get("_links", {}).get("base", "") + data.get(
- "_links", {}
- ).get("webui", "")
- print(f"[confluence-publish] published: {page_url}", file=sys.stderr)
- return 0
- except urllib.error.HTTPError as e:
- body = e.read().decode("utf-8", errors="replace")
- print(f"[confluence-publish] HTTP {e.code}: {body[:500]}", file=sys.stderr)
- return 1
- except Exception as e:
- print(f"[confluence-publish] error: {e}", file=sys.stderr)
- return 1
-
-
-if __name__ == "__main__":
- sys.exit(main())

package/.claude/plugins/staff-software-engineer/README.md

@@ -1,90 +0,0 @@
-# Staff Software Engineer Plugin
-
-Native Claude Code plugin for the engineering team. Drives plan, dev, test, and pr stages across backend, web, mobile, and devops. Per-project conventions in each repo's `.claude/conventions/` override plugin defaults.
-
-## Slash commands
-
-- `/sse:plan`: generate an implementation plan from an approved PRP
-- `/sse:dev`: implement the plan in code, run convention gates
-- `/sse:test`: run the project test suite
-- `/sse:pr`: open the draft PR
-- `/sse:run`: full pipeline, plan to pr
-
-Also invokable as sub-agent via Task tool with `subagent_type: "staff-software-engineer"`.
-
-## Tree
-
-```
-.claude/plugins/staff-software-engineer/
-├── .claude-plugin/plugin.json
-├── agents/staff-software-engineer.md sub-agent
-├── commands/
-│ ├── plan.md /sse:plan
-│ ├── dev.md /sse:dev
-│ ├── test.md /sse:test
-│ ├── pr.md /sse:pr
-│ └── run.md /sse:run
-├── skills/
-│ ├── backend/SKILL.md Java/Spring defaults
-│ ├── web/SKILL.md Vue defaults
-│ ├── mobile/SKILL.md iOS/Android defaults
-│ └── devops/SKILL.md CI/IaC defaults
-├── hooks/ phase markers, sensor gates
-├── scripts/ symlinks to product-manager scripts
-├── guides/
-│ ├── pipeline.md retry, approval, token accounting
-│ ├── coding-style.md team code style
-│ ├── commit-style.md Conventional Commits with TICKET
-│ └── conventions-override.md how project overrides work
-├── sensors/ plan structure, code conventions, test coverage
-├── evals/ plan quality rubric
-└── outputs/
- ├── plan/ generated plans
- ├── dev/ dev summaries
- ├── test/ test results
- ├── pr/ opened PR records
- ├── tokens/ per-feature phase tokens JSON
- └── .markers/ phase start/end markers (transient)
-```
-
-## How conventions work
-
-The plugin holds team defaults per area. Each project repo can override by adding:
-
-```
-{repo-root}/.claude/conventions/{area}.md
-```
-
-Example for the `recon-service` repo:
-
-```
-recon-service/.claude/conventions/backend.md
-```
-
-Plugin skills read both. Project rules win. See `guides/conventions-override.md`.
-
-## Where to edit
-
-| Change | File |
-|--------|------|
-| Pipeline order | guides/pipeline.md |
-| Retry count | guides/pipeline.md (Max attempts) |
-| Plan template/rules | skills/backend/SKILL.md (etc per area), commands/plan.md |
-| Eval threshold | evals/plan-quality.md (Threshold) |
-| Code style | guides/coding-style.md |
-| Commit format | guides/commit-style.md |
-| Test command detection | commands/test.md |
-| PR template | commands/pr.md, hooks/post-eval-pr.sh |
-| Sensors | sensors/*.md |
-
-## Connects to PM plugin
-
-`/sse:run` reads the latest approved PRP from `.claude/plugins/product-manager/outputs/prp/`. The feature_id flows through: PM plugin creates `2026-05-12-billing-tz-fix`, SSE plugin reuses the same id and writes its phases to the same `outputs/tokens/{feature_id}.json` file (per `guides/pipeline.md`).
-
-Full lifecycle in one JSON: PRD generate, PRD validate, PRP generate, PRP validate, plan generate, plan validate, dev, test, pr.
-
-## Setup
-
-Hooks registered in `.claude/settings.json` under PostToolUse. Token script reused from the PM plugin via symlinks in `scripts/`.
-
-PR opening requires the `gh` CLI authenticated. `pr.md` command details ticket detection and template.