pi-dev-team 0.2.0

package/agents/vue-reactivity-review.md

@@ -0,0 +1,95 @@
+---
+
+name: vue-reactivity-review
+description: Vue ref/reactive unwrapping pitfalls, watchEffect dependency tracking, reactive proxy escapes, composition API subscription leaks
+tools: Read, Grep, Glob, mcp__codegraph__*, mcp__plugin_repowise_repowise__get_context, mcp__plugin_repowise_repowise__get_symbol, mcp__plugin_repowise_repowise__search_codebase, mcp__plugin_repowise_repowise__get_risk
+model: haiku
+effort: medium
+color: green
+---
+
+# Vue Reactivity Review
+
+Scope:
+- **/*.vue
+- **/*.js
+- **/*.ts
+Cites: [adversarial-review-protocol]
+
+Scope: Vue component and composable files (`.vue`, and `.js`/`.ts` files that
+import from `vue`). Skip this agent entirely if the project has no `vue`
+dependency in `package.json` (or equivalent manifest).
+Covers Vue 3 Composition API (`ref`, `reactive`, `computed`, `watch`,
+`watchEffect`) and Vue 2 Options API reactivity pitfalls.
+
+Output JSON: per `${CLAUDE_PLUGIN_ROOT}/knowledge/review-agent-output-contract.md` (Whole-file load: short, canonical schema).
+
+Status: pass=no reactivity issues, warn=potential concerns, fail=likely silent reactivity breakage
+Severity: error=silent reactivity breakage; warning=potential reactivity concern; suggestion=defensive improvement
+Confidence: high=mechanical Vue fix (wrap in ref/reactive, add dep, use .value); medium=pattern identified but component design may affect the fix; none=requires human judgment
+
+Context needs: full-file
+
+## Skip
+
+Return `{"status": "skip", "issues": [], "summary": "No Vue files in target"}` when:
+
+- No `vue` dependency found in the project manifest (`package.json`, `package-lock.json`, `yarn.lock`, etc.)
+- No `.vue` / `.js` / `.ts` files import from `vue` in the target set
+
+## Detect
+
+Whole-file load: `${CLAUDE_PLUGIN_ROOT}/knowledge/reactive-effect-patterns.md` for cross-framework effect/watcher patterns shared with React and Angular agents before running the Vue-specific checks below.
+
+ref vs reactive unwrapping pitfalls (Vue 3):
+
+- Destructuring a `reactive()` object breaks reactivity — the destructured variables become plain (non-reactive) copies
+- Spreading `reactive()` into a new object (`{ ...state }`) loses tracking — returned object is no longer reactive
+- Using `reactive()` on a primitive (number, string, boolean) — use `ref()` instead; `reactive()` only wraps objects
+- Passing a `reactive()` property directly to a composable parameter — the composable receives the current value, not a reactive reference; use `toRef()` or pass the whole object
+- Forgetting `.value` on a `ref` in `<script setup>` — compiler auto-unwraps refs in templates but not in JS code
+
+ref.value mutation pitfalls:
+
+- Replacing the entire `.value` of a `ref` holding an object with a plain object (`ref.value = { ...newData }`) — creates a new reactive proxy, watch/watchEffect callbacks still track it, but watchers relying on the old proxy reference stop firing
+- Direct array index assignment on a reactive array (`arr[0] = x`) in Vue 2 — use `Vue.set` or `splice`; Vue 3 proxies track this correctly but note it anyway if Vue 2 usage is detected
+
+watchEffect / watch dependency tracking (Vue 3):
+
+- `watchEffect` callback that reads a value via a plain function call that doesn't access the ref inside the effect scope — the effect doesn't track it and won't re-run
+- `watch(source, handler)` with a non-reactive, plain-JS source value — handler never fires because Vue can't track a non-reactive source
+- Accessing deeply nested reactive data inside a `watch` without `deep: true` — misses nested mutations
+- See `${CLAUDE_PLUGIN_ROOT}/knowledge/reactive-effect-patterns.md#effect-self-writes-infinite-loop` for the shared infinite-loop pattern (applies to `watchEffect` writing to its own tracked dep)
+
+Computed property pitfalls:
+
+- `computed()` with a getter that has side effects (should be pure) — makes reactive tracking unpredictable
+- Computed property writing to reactive state (mutable computed without explicit setter)
+- `computed` depending on `ref.value` where the ref is passed as a parameter (not in scope) — always returns the initial value only
+
+Subscription / watcher leaks (Composition API):
+
+- `watch` / `watchEffect` called inside a composable or utility function outside a component setup context without the returned `stop` handle being saved and called on cleanup
+- Event-bus listeners added in `onMounted` without a corresponding `onUnmounted` removal
+- Third-party subscriptions (RxJS `.subscribe()`, `EventSource`, `WebSocket`) opened in `setup()` without cleanup in `onUnmounted`
+
+Options API pitfalls (Vue 2 / Vue 3 Options):
+
+- Properties added to `data()` objects after component creation (not declared in `data()`) — Vue cannot make them reactive retroactively; use `Vue.set` in Vue 2 or declare all fields up front in Vue 3
+- Mutation of a Vuex state property directly instead of via a mutation — bypasses change detection
+
+## Self-Challenge
+
+After producing findings, run the shared challenger loop in `${CLAUDE_PLUGIN_ROOT}/knowledge/adversarial-review-protocol.md` (Whole-file load: the slim shared methodology — The Loop + Output format — read in full), then work these vue-reactivity-review-specific challenges:
+
+- Did you confirm `vue` is actually in the project's dependency tree before flagging any finding?
+- For each destructuring/spread finding, did you verify the source is a `reactive()` object (not a `ref`)? Destructuring a `ref` is fine — you'd lose `.value` access but not reactivity.
+- For each watcher finding, did you confirm the watched source is actually non-reactive, not just passed in an unusual way?
+- Did you check every composable for unregistered `watch`/`watchEffect` stop handles used outside component lifecycle?
+- For Vue 2 array mutation findings, did you confirm the target is a Vue 2 project (Vue 3 proxies handle index assignment correctly)?
+
+Append confidence level (High/Medium/Low) to the `summary` field.
+
+## Ignore
+
+Component composition and prop drilling (component-architecture-review), generic array mutation style (js-fp-review), accessibility (a11y-review), race conditions in non-reactive paths (concurrency-review), security, naming, complexity (handled by other agents)

package/bin/claude

@@ -0,0 +1,258 @@
+#!/usr/bin/env python3
+"""`claude` CLI shim for the pi port of dev-team.
+
+Upstream scripts (orchestrator.py, codebase_recon.py, progress_guardian.py,
+token_efficiency_review.py, mutation-testing helpers, ...) shell out to
+`claude -p ...`. Inside a pi session the pi-dev-team extension puts this
+directory first on PATH, so those calls run pi instead:
+
+  claude -p [--agent NAME] [--model M] [--output-format text|json|stream-json]
+         [--allowedTools "Read Grep ..."] [--append-system-prompt TEXT] [PROMPT]
+    -> pi --mode json -p --no-session [--dev-team-agent NAME] [--dev-team-tier T | --model P/ID]
+          [--tools ...] PROMPT
+
+and print Claude's result envelope, e.g.
+  {"type":"result","subtype":"success","is_error":false,"result":"...","num_turns":2,
+   "total_cost_usd":0.01,"usage":{"input_tokens":...},"session_id":"..."}
+
+Ignored (no pi equivalent needed): --dangerously-skip-permissions, --session-id,
+--max-turns, --verbose, --permission-mode, --settings, --no-session-persistence.
+Unsupported subcommands (mcp, plugin, --resume) exit 1 with a message.
+Set DEV_TEAM_REAL_CLAUDE=/path/to/claude to pass through to a real Claude Code CLI.
+Stdlib only.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+import uuid
+
+IGNORED_WITH_VALUE = {"--session-id", "--max-turns", "--permission-mode", "--settings", "--mcp-config", "--add-dir", "--fallback-model", "--input-format"}
+IGNORED_FLAGS = {"--dangerously-skip-permissions", "--verbose", "--no-session-persistence", "--strict-mcp-config", "--include-partial-messages"}
+TIERS = {"opus", "sonnet", "haiku", "fable", "inherit", "default"}
+TOOL_MAP = {
+    "read": ["read"], "grep": ["grep"], "glob": ["find", "ls"], "ls": ["ls"], "bash": ["bash"],
+    "edit": ["edit"], "multiedit": ["edit"], "write": ["write"], "notebookedit": ["edit"],
+    "skill": ["skill"], "agent": ["dev_team_subagent"], "task": ["dev_team_subagent"], "webfetch": ["web_fetch"],
+    "askuserquestion": ["ask_user"],
+}
+
+
+def fail(msg: str, code: int = 1) -> int:
+    print(f"claude (pi-dev-team shim): {msg}", file=sys.stderr)
+    return code
+
+
+def map_tools(spec: str) -> list[str]:
+    out: list[str] = []
+    for raw in spec.replace(",", " ").split():
+        base = raw.split("(", 1)[0].strip().lower()
+        for t in TOOL_MAP.get(base, []):
+            if t not in out:
+                out.append(t)
+    return out
+
+
+def pi_command() -> list[str]:
+    explicit = os.environ.get("DEV_TEAM_PI_BIN")
+    if explicit:
+        return explicit.split()
+    found = shutil.which("pi")
+    return [found] if found else ["pi"]
+
+
+def model_args(model: str | None) -> list[str]:
+    if not model:
+        return []
+    m = model.strip()
+    if "/" in m:
+        return ["--model", m]
+    low = m.lower()
+    if low in TIERS:
+        return [] if low in ("inherit", "default") else ["--dev-team-tier", low]
+    for tier in ("opus", "sonnet", "haiku", "fable"):
+        if tier in low:  # full Claude ids like claude-sonnet-4-5 -> tier
+            return ["--dev-team-tier", tier]
+    return ["--model", m]
+
+
+def trusted_here(trusted_dir: str, cwd: str) -> bool:
+    """pi trusts per directory: the session's grant covers its own directory, nothing else."""
+    if not trusted_dir:
+        return False
+    return os.path.realpath(cwd) == os.path.realpath(trusted_dir)
+
+
+def main(argv: list[str]) -> int:
+    real = os.environ.get("DEV_TEAM_REAL_CLAUDE")
+    if real:
+        os.execv(real, [real, *argv])
+
+    if argv and argv[0] in ("mcp", "plugin", "config", "update", "doctor", "setup-token", "migrate-installer"):
+        return fail(f"'claude {argv[0]}' has no pi equivalent in this shim (use 'pi {argv[0]}' where it exists).")
+    if "--version" in argv or "-v" in argv:
+        print("2.0.0 (pi-dev-team shim)")
+        return 0
+
+    fmt = "text"
+    agent = None
+    model = None
+    tools: list[str] | None = None
+    append_prompt: list[str] = []
+    system_prompt = None
+    prompt_parts: list[str] = []
+    printing = False
+    i = 0
+    while i < len(argv):
+        a = argv[i]
+        nxt = argv[i + 1] if i + 1 < len(argv) else None
+        if a in ("-p", "--print"):
+            printing = True
+        elif a == "--output-format" and nxt is not None:
+            fmt = nxt
+            i += 1
+        elif a.startswith("--output-format="):
+            fmt = a.split("=", 1)[1]
+        elif a == "--agent" and nxt is not None:
+            agent = nxt
+            i += 1
+        elif a == "--model" and nxt is not None:
+            model = nxt
+            i += 1
+        elif a in ("--allowedTools", "--allowed-tools", "--tools") and nxt is not None:
+            tools = (tools or []) + map_tools(nxt)
+            i += 1
+        elif a in ("--disallowedTools", "--disallowed-tools") and nxt is not None:
+            i += 1
+        elif a == "--append-system-prompt" and nxt is not None:
+            append_prompt.append(nxt)
+            i += 1
+        elif a == "--system-prompt" and nxt is not None:
+            system_prompt = nxt
+            i += 1
+        elif a in ("--resume", "-r", "--continue", "-c"):
+            return fail("session resume is not supported by the shim")
+        elif a in IGNORED_WITH_VALUE:
+            i += 1
+        elif a in IGNORED_FLAGS:
+            pass
+        elif a == "--":
+            prompt_parts.extend(argv[i + 1 :])
+            break
+        elif a.startswith("-") and not prompt_parts:
+            pass  # unknown flag: ignore
+        else:
+            prompt_parts.append(a)
+        i += 1
+
+    if not printing:
+        return fail("only non-interactive `claude -p` is supported; run `pi` for an interactive session")
+
+    prompt = " ".join(prompt_parts).strip()
+    if not prompt and not sys.stdin.isatty():
+        prompt = sys.stdin.read().strip()
+    if not prompt:
+        return fail("no prompt given")
+
+    tmp = tempfile.mkdtemp(prefix="pi-dev-team-shim-")
+    cmd = pi_command() + ["--mode", "json", "-p", "--no-session"]
+    try:  # resources of the pi session that set up this shim (extensions loaded with -e; --no-approve if declined)
+        cmd += [str(x) for x in json.loads(os.environ.get("DEV_TEAM_PI_ARGS", "[]"))]
+    except (ValueError, TypeError):
+        pass
+    if trusted_here(os.environ.get("DEV_TEAM_TRUSTED_DIR", ""), os.getcwd()):
+        cmd.append("--approve")
+    if agent:
+        cmd += ["--dev-team-agent", agent.split(":")[-1]]
+    cmd += model_args(model)
+    if tools is not None:
+        cmd += ["--tools", ",".join(tools) if tools else "read"]
+    if system_prompt:
+        path = os.path.join(tmp, "system.md")
+        with open(path, "w", encoding="utf-8") as fh:
+            fh.write(system_prompt)
+        cmd += ["--system-prompt", path]
+    for n, text in enumerate(append_prompt):
+        path = os.path.join(tmp, f"append-{n}.md")
+        with open(path, "w", encoding="utf-8") as fh:
+            fh.write(text)
+        cmd += ["--append-system-prompt", path]
+    cmd.append(prompt)
+
+    env = dict(os.environ)
+    env.pop("DEV_TEAM_INTERACTIVE", None)
+    try:
+        proc = subprocess.run(cmd, capture_output=True, text=True, env=env, check=False)
+    except FileNotFoundError:
+        return fail("pi executable not found on PATH (set DEV_TEAM_PI_BIN)", 127)
+    finally:
+        shutil.rmtree(tmp, ignore_errors=True)
+
+    result_text = ""
+    turns = 0
+    cost = 0.0
+    usage = {"input_tokens": 0, "output_tokens": 0, "cache_read_input_tokens": 0, "cache_creation_input_tokens": 0}
+    stop_reason = None
+    error_message = None
+    stream_lines: list[str] = []
+    for line in proc.stdout.splitlines():
+        try:
+            ev = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if fmt == "stream-json":
+            stream_lines.append(line)
+        if ev.get("type") != "message_end":
+            continue
+        msg = ev.get("message") or {}
+        if msg.get("role") != "assistant":
+            continue
+        turns += 1
+        u = msg.get("usage") or {}
+        usage["input_tokens"] += u.get("input", 0) or 0
+        usage["output_tokens"] += u.get("output", 0) or 0
+        usage["cache_read_input_tokens"] += u.get("cacheRead", 0) or 0
+        usage["cache_creation_input_tokens"] += u.get("cacheWrite", 0) or 0
+        c = u.get("cost") or {}
+        cost += (c.get("total", 0) if isinstance(c, dict) else c) or 0
+        stop_reason = msg.get("stopReason") or stop_reason
+        error_message = msg.get("errorMessage") or error_message
+        texts = [b.get("text", "") for b in msg.get("content") or [] if isinstance(b, dict) and b.get("type") == "text"]
+        if "".join(texts).strip():
+            result_text = "\n".join(texts)
+
+    is_error = proc.returncode != 0 or stop_reason in ("error", "aborted")
+    if is_error and not result_text:
+        result_text = error_message or proc.stderr.strip()[-2000:] or f"pi exited with {proc.returncode}"
+
+    envelope = {
+        "type": "result",
+        "subtype": "error_during_execution" if is_error else "success",
+        "is_error": is_error,
+        "result": result_text,
+        "num_turns": turns,
+        "total_cost_usd": round(cost, 6),
+        "usage": usage,
+        "session_id": str(uuid.uuid4()),
+        "stop_reason": stop_reason,
+    }
+    if fmt == "json":
+        print(json.dumps(envelope))
+    elif fmt == "stream-json":
+        for line in stream_lines:
+            print(line)
+        print(json.dumps(envelope))
+    else:
+        print(result_text)
+    if proc.stderr and is_error:
+        sys.stderr.write(proc.stderr[-4000:])
+    return 1 if is_error else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

package/docs/upstream/.pages

@@ -0,0 +1 @@
+title: Documentation