@msdavid/pi-distro 0.2.0

package/harnesses/pi-distro-one/README.md

@@ -0,0 +1,50 @@
+# pi-distro-one
+
+A complete Claude Code–style coding agent configuration for pi. The primary capability is
+spawning and coordinating autonomous sub-agents; everything else — web research, browser
+automation, live shell, model routing, task management — is integrated in support of that.
+
+This is a personal draft shot at using the most popular pi coding packages to closely
+resemble the capabilities of Claude Code. It's opinionated and not for everyone — but it
+makes a great starting point to fork and make your own.
+
+## What it sets up
+
+- **`AGENTS.md`** — an explore-before-acting working methodology: investigate before
+  implementing, surface interpretations and tradeoffs, make surgical changes, keep
+  solutions simple, execute against verifiable goals, and treat documentation as part of
+  the implementation.
+- **`.pi/settings.json`** — high thinking level, one-at-a-time steering, hidden thinking
+  blocks, and hardware cursor.
+- **`.pi/extensions/claude-statusline.ts`** — a Claude-style status-line footer
+  (model | dir | thinking level | context-window bar gauge + cache % | git branch status).
+  Auto-enables on session start and **auto-expands tool outputs** (the Ctrl+O effect) so
+  full output is visible by default. Toggle with the `/claude-statusline` command.
+
+## Packages installed (all project-local)
+
+| Package | What it does |
+|---------|-------------|
+| `npm:@tintinweb/pi-subagents` | Claude Code–style autonomous sub-agents — spawn specialized agents in isolated sessions with own tools/prompt/model/thinking; parallel execution, live widget, mid-run steering, resumption (**primary capability**) |
+| `npm:pi-web-access` | Web search, URL fetching, GitHub cloning, PDF/video extraction |
+| `npm:pi-agent-browser-native` | Real browser automation and web interaction |
+| `npm:pi-bash-live-view` | Live terminal rendering for shell commands |
+| `npm:@yeliu84/pi-model-router` | Model routing / fallback across providers |
+| `npm:@robhowley/pi-openrouter` | OpenRouter provider integration |
+| `npm:@juicesharp/rpiv-todo` | Task list management |
+| `npm:pi-goal` | Persistent autonomous goals — `/goal` loops until complete, paused, or budget-limited |
+| `npm:@trevonistrevon/pi-loop` | Cron/event-based agent re-wake loops + background process monitoring — schedule agents to re-wake on time/events |
+| `npm:@juicesharp/rpiv-ask-user-question` | Structured questionnaire the model puts to the user (typed options instead of guessing) |
+
+## Prerequisites
+
+- **Auth and model routing** are not part of this distro — configure those independently
+  (e.g. set `defaultProvider` and `defaultModel` in your global `~/.pi/settings.json`,
+  or use OpenRouter via the `@robhowley/pi-openrouter` package installed above).
+- **Restart pi** after deploying — packages and extensions load at startup.
+
+## When to use
+
+- You want a Claude Code–like experience in pi.
+- You work on complex tasks that benefit from multi-agent coordination.
+- You want an opinionated, batteries-included setup to fork and customize.

package/harnesses/pi-distro-one/files/.pi/extensions/claude-statusline.ts

@@ -0,0 +1,220 @@
+/**
+ * Claude-style status line for pi.
+ *
+ * Clones the Claude Code footer format:
+ *   <model> | <dir> | <style> | [████████░░] 80% | 45% cached | <branch (status)>
+ *
+ * - model       : active model name/id
+ * - dir         : basename of ctx.cwd
+ * - style       : current thinking level (pi's analog of Claude's "output style")
+ * - context     : UTF-8 bar gauge of context-window usage (eighths resolution),
+ *                 colored by level (accent → warning → error), plus usage % and
+ *                 cache-read % (same token math as the Claude Code statusLine
+ *                 command in ~/.claude/settings.json)
+ * - git         : branch from footerData + dirty(!)/untracked(?) markers, refreshed
+ *                 in the background so render() never spawns a process
+ *
+ * Auto-enables on session start. Also auto-expands tool outputs on session start
+ * (the Ctrl+O effect) so full output is visible by default. Toggle the status line
+ * with the /claude-statusline command.
+ */
+
+import { execSync } from "node:child_process";
+import { basename } from "node:path";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { AssistantMessage } from "@earendil-works/pi-ai";
+import { truncateToWidth } from "@earendil-works/pi-tui";
+
+const REFRESH_MS = 2000;
+
+/** Eighth-block characters for sub-cell bar precision (index = eighths, 0 = empty). */
+const EIGHTHS = ["", "▏", "▎", "▍", "▌", "▋", "▊", "▉", "█"];
+const BAR_WIDTH = 10;
+
+interface GitCache {
+	branch: string | null;
+	dirty: boolean;
+	untracked: boolean;
+}
+
+export default function (pi: ExtensionAPI) {
+	let enabled = false;
+	let timer: ReturnType<typeof setInterval> | undefined;
+	let gitCache: GitCache = { branch: null, dirty: false, untracked: false };
+
+	function refreshGit(cwd: string): void {
+		try {
+			// One porcelain call gives us both dirty (staged/modified) and untracked flags.
+			const out = execSync("git status --porcelain=v1 -z", {
+				cwd,
+				encoding: "utf8",
+				stdio: ["ignore", "pipe", "ignore"],
+				timeout: 1500,
+			});
+			let dirty = false;
+			let untracked = false;
+			// -z separates records with NUL. Each record: <XY><space><path>\0...
+			const records = out.split("\0").filter((r) => r.length > 0);
+			for (const rec of records) {
+				const xy = rec.slice(0, 2);
+				if (xy === "??") {
+					untracked = true;
+				} else {
+					dirty = true;
+				}
+				if (dirty && untracked) break;
+			}
+			gitCache = { ...gitCache, dirty, untracked };
+		} catch {
+			// Not a git repo, or git unavailable — clear flags.
+			gitCache = { ...gitCache, dirty: false, untracked: false };
+		}
+	}
+
+	function startTimer(ctx: ExtensionContext): void {
+		stopTimer();
+		refreshGit(ctx.cwd);
+		timer = setInterval(() => refreshGit(ctx.cwd), REFRESH_MS);
+		// Don't keep the event loop alive solely for footer refreshes.
+		if (timer && typeof timer.unref === "function") timer.unref();
+	}
+
+	function stopTimer(): void {
+		if (timer) {
+			clearInterval(timer);
+			timer = undefined;
+		}
+	}
+
+	/**
+	 * Render a fixed-width UTF-8 bar gauge for a fraction in [0,1].
+	 * Filled cells use full blocks; the boundary cell uses an eighth-block for
+	 * sub-cell precision. Returns [filled, empty] strings for separate coloring.
+	 */
+	function barGauge(fraction: number): { filled: string; empty: string } {
+		const clamped = Math.max(0, Math.min(1, fraction));
+		const totalEighths = Math.round(clamped * BAR_WIDTH * 8);
+		const fullCells = Math.floor(totalEighths / 8);
+		const remainder = totalEighths % 8;
+		const filled = "█".repeat(fullCells) + (remainder > 0 ? EIGHTHS[remainder] : "");
+		const filledWidth = fullCells + (remainder > 0 ? 1 : 0);
+		const empty = "░".repeat(Math.max(0, BAR_WIDTH - filledWidth));
+		return { filled, empty };
+	}
+
+	function enable(ctx: ExtensionContext): void {
+		enabled = true;
+		startTimer(ctx);
+
+		ctx.ui.setFooter((tui, theme, footerData) => {
+			const unsub = footerData.onBranchChange(() => {
+				gitCache = { ...gitCache, branch: footerData.getGitBranch() };
+				tui.requestRender();
+			});
+			gitCache = { ...gitCache, branch: footerData.getGitBranch() };
+
+			return {
+				dispose: () => {
+					unsub();
+					stopTimer();
+				},
+				invalidate() {},
+				render(width: number): string[] {
+					const segments: string[] = [];
+
+					// 1. Model
+					const model = ctx.model;
+					segments.push(theme.fg("accent", model?.name ?? model?.id ?? "no-model"));
+
+					// 2. Cwd basename
+					segments.push(theme.fg("dim", basename(ctx.cwd) || ctx.cwd));
+
+					// 3. Style -> thinking level (pi's analog of output style).
+					// getThinkingLevel() lives on the ExtensionAPI (pi), not on ctx.
+					segments.push(theme.fg("dim", pi.getThinkingLevel()));
+
+					// 4. Context: bar gauge + usage % + cache %.
+					// Use pi's own context estimate (ctx.getContextUsage) — it represents the
+					// current context size of the most recent request, matching Claude Code's
+					// `context_window.current_usage`. Summing per-message usage would double-
+					// count, since each request's input already includes prior context.
+					const usage = ctx.getContextUsage();
+					const usedPct = usage?.percent ?? 0;
+
+					// Cache-read % comes from the last assistant message's usage (the most
+					// recent request): cacheRead / (input + cacheWrite + cacheRead).
+					let cachePct = 0;
+					const branch = ctx.sessionManager.getBranch();
+					for (let i = branch.length - 1; i >= 0; i--) {
+						const e = branch[i];
+						if (e.type === "message" && e.message.role === "assistant") {
+							const u = (e.message as AssistantMessage).usage;
+							const totalInput = u.input + u.cacheWrite + u.cacheRead;
+							cachePct = totalInput > 0 ? Math.floor((u.cacheRead * 100) / totalInput) : 0;
+							break;
+						}
+					}
+
+					const { filled, empty } = barGauge(usedPct / 100);
+					const barColor = usedPct >= 95 ? "error" : usedPct >= 80 ? "warning" : "accent";
+					const bar = theme.fg(barColor, filled) + theme.fg("dim", empty);
+					const pctLabel = theme.fg("dim", `${Math.floor(usedPct)}%`);
+
+					let ctxInfo = `${bar} ${pctLabel}`;
+					if (cachePct > 0) ctxInfo += theme.fg("dim", ` | ${cachePct}% cached`);
+					segments.push(ctxInfo);
+
+					// 5. Git: branch (!dirty ?untracked)
+					if (gitCache.branch) {
+						let status = "";
+						if (gitCache.dirty) status += "!";
+						if (gitCache.untracked) status += "?";
+						const gitInfo = status ? `${gitCache.branch} (${status})` : gitCache.branch;
+						segments.push(theme.fg("dim", gitInfo));
+					}
+
+					// Join with dim separators.
+					const sep = theme.fg("muted", " | ");
+					const line = segments.join(sep);
+
+					return [truncateToWidth(line, width)];
+				},
+			};
+		});
+	}
+
+	function disable(ctx: ExtensionContext): void {
+		enabled = false;
+		stopTimer();
+		ctx.ui.setFooter(undefined);
+	}
+
+	// Auto-enable on every (re)start, and auto-expand tool outputs (the Ctrl+O effect).
+	pi.on("session_start", async (_event, ctx) => {
+		enable(ctx);
+		ctx.ui.setToolsExpanded(true);
+	});
+
+	pi.on("session_shutdown", async (_event, _ctx) => {
+		stopTimer();
+	});
+
+	// Refresh git right after a turn settles (catches file writes from the agent).
+	pi.on("turn_end", async (_event, ctx) => {
+		if (enabled) refreshGit(ctx.cwd);
+	});
+
+	// Manual toggle.
+	pi.registerCommand("claude-statusline", {
+		description: "Toggle the Claude-style status line footer",
+		handler: async (_args, ctx) => {
+			if (enabled) {
+				disable(ctx);
+				ctx.ui.notify("Claude status line: off", "info");
+			} else {
+				enable(ctx);
+				ctx.ui.notify("Claude status line: on", "info");
+			}
+		},
+	});
+}

package/harnesses/pi-distro-one/files/AGENTS.md

@@ -0,0 +1,166 @@
+# Quick Rules
+
+- Never commit or push until I explicitly ask
+- **Always update documentation** when planning, implementing, or refactoring
+  - Update README, docs/, inline comments, docstrings, and any related docs
+  - Include documentation updates as explicit steps in plans
+- **EYU** = Explain Your Understanding of the request and wait for approval
+  - Example: User says "EYU" → Summarize what you understood, then stop and wait
+
+---
+
+# Approach to Changes
+
+Before planning or implementing any changes, adopt a "deep researcher" mindset.
+
+## Core Principle
+
+**Understand before you act.** Don't jump to implementation. Your first instinct should be to explore the codebase, not to write code.
+
+## Surface, Don't Hide
+
+- **Present interpretations, don't pick silently.** If a request has more than one reasonable reading, lay them out and let me choose.
+- **Surface tradeoffs and push back.** If a simpler approach exists, say so. If the request seems wrong or overcomplicated, challenge it before building it.
+- **Name confusion instead of papering over it.** If something is still unclear after investigating, stop and say exactly what's confusing.
+- Investigate what the code can answer (see "When uncertain, investigate more"); *ask* only about genuine intent or scope ambiguity the code can't resolve.
+
+## When to Explore vs Plan
+
+- **Always explore first** before any plan or implementation
+- **Default behavior**: Explore → Implement
+- **When user says "EYU"**: Explain understanding → Wait for approval → Explore → Plan/Implement
+
+## Before Any Task
+
+1. **Find existing examples first.** Use grep, glob, or read files to locate similar features. Study at least 2-3 examples of how comparable things are implemented before proposing changes.
+
+2. **Map the full surface area.** For any change, actively investigate:
+   - How are similar things structured and named? (conventions, patterns)
+   - What's the full lifecycle? (creation, registration, configuration, persistence, cleanup)
+   - What are all integration points? (UI, menus, context menus, commands, keybindings, APIs)
+   - What files document this? (README, docs/, inline comments, docstrings)
+   - What tests exist for similar features? How do they test this kind of thing?
+   - What registries, configs, or manifests need updating?
+
+3. **Learn the local conventions.** Every codebase has its own patterns. Discover them before writing new code. Match the existing style exactly.
+
+4. **Think in systems.** A request to "add X" means "integrate X into the existing system." Understand the system's architecture first.
+
+5. **When uncertain, investigate more.** Read more files. Run the code. Check tests. Don't guess—know.
+
+6. **Update all documentation.** Treat documentation as part of the implementation, not an afterthought. Update README, docs/, docstrings, inline comments, and any related documentation files. If the change affects public APIs, update their documentation first.
+
+## In Practice
+
+When given a task:
+- Start by exploring, not planning (unless SYP is requested)
+- Use tools to read related code before proposing changes
+- List all affected files/areas before making edits
+- Identify all documentation that needs updating (README, docs/, docstrings, comments)
+- Ask clarifying questions if the scope seems larger than implied
+
+---
+
+# Implementation Principles
+
+Once you understand the task, these govern how you write the code.
+
+## Simplicity First
+
+Write the minimum code that solves the problem. Nothing speculative.
+
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- No "flexibility" or "configurability" I didn't request.
+- No error handling for scenarios that can't actually happen.
+- If you wrote 200 lines and it could be 50, rewrite it.
+- Gut check: *"Would a senior engineer call this overcomplicated?"* If yes, simplify.
+
+(This is about not writing unnecessary code; the File Size Limits below are about splitting code that has already grown too large — a different problem.)
+
+## Surgical Changes
+
+Touch only what you must. Clean up only your own mess.
+
+When editing existing code:
+- Don't "improve" adjacent code, comments, or formatting.
+- Don't refactor things that aren't broken.
+- If you notice unrelated dead code, *mention* it — don't delete it.
+- (Matching existing style is already required under "Learn the local conventions" — it holds here too, even when you'd do it differently.)
+
+When your changes create orphans:
+- Remove imports/variables/functions that *your* changes made unused.
+- Don't remove pre-existing dead code unless I ask.
+
+**The test:** every changed line should trace directly to my request.
+
+## Goal-Driven Execution
+
+Define success criteria up front, then loop until they're verified.
+
+Turn vague tasks into verifiable goals:
+- "Add validation" → write tests for invalid inputs, then make them pass.
+- "Fix the bug" → write a test that reproduces it, then make it pass.
+- "Refactor X" → confirm tests pass before and after.
+
+For multi-step work, state a brief plan with a check per step:
+1. [Step] → verify: [check]
+2. [Step] → verify: [check]
+
+Strong success criteria let you loop independently; weak ones ("make it work") force constant clarification — so define them precisely. (those gate *whether* you start; success criteria define *when you're done*.)
+
+---
+
+# Code Quality Guidelines
+
+## File Size Limits
+
+| Type | Warning | Consider Split | Must Split |
+|------|---------|----------------|------------|
+| Python | 500 | 600 | 700 |
+| TypeScript (general) | 400 | 500 | 600 |
+| React components | 200 | 300 | 400 |
+| Next.js pages/routes | 300 | 400 | 500 |
+| Custom hooks | 100 | 150 | 200 |
+| Utility/service files | 400 | 500 | 600 |
+
+## Test File Size Limits
+| Type | Warning | Consider Split | Must Split |
+|------|---------|----------------|------------|
+| Python tests | 800 | 1000 | 1200 |
+| TypeScript tests | 600 | 800 | 1000 |
+| React component tests | 400 | 500 | 600 |
+| Hook tests | 200 | 300 | 400 |
+| E2E/integration tests | 800 | 1000 | 1200 |
+
+When a test file approaches these limits, first consider whether the module under test should be split before splitting the test file.
+
+## Verify, don't guess
+
+- If you find yourself reconstructing an API, function signature, config key, or
+  command flag from memory, stop and confirm it before writing it. Memory of these
+  is the single biggest source of confident-but-wrong code.
+- Check the right source for the kind of doubt:
+  - Project conventions, types, helpers, existing patterns → search the codebase.
+  - External library/framework behavior, versions, deprecations → search online,
+    preferring official docs and the library's changelog over blog posts or older
+    Stack Overflow answers.
+- A search is cheap; a wrong assumption is expensive to debug. When unsure whether
+  it's worth checking, check.
+- When a non-obvious choice rests on something you looked up, note the source in one
+  line (e.g. "per React 19 docs") so it can be verified.
+- Treat anything that may have changed since your training cutoff — latest versions,
+  new APIs, deprecations — as something to look up, not recall.
+
+## When debugging
+
+- State your current hypothesis for the cause before each fix attempt. If it's the
+  same hypothesis as the last failed attempt, do not try another variation — the
+  diagnosis is suspect, not just the fix. Gather new information instead.
+- After 2 failed attempts, stop iterating and treat your understanding of the problem
+  as the thing that's wrong. Re-examine the premise.
+- Get fresh ground truth instead of reasoning from memory: read the actual error
+  message in full, read the actual source of the function involved, and search the
+  literal error text online — others have usually hit it.
+- Never repeat a fix that already failed.
+- If you're stuck after re-examining, surface the competing hypotheses to me rather than continuing to guess.

package/harnesses/pi-distro-one/files/settings.json

@@ -0,0 +1,9 @@
+{
+  "defaultThinkingLevel": "high",
+  "showHardwareCursor": true,
+  "steeringMode": "one-at-a-time",
+  "transport": "auto",
+  "hideThinkingBlock": true,
+  "collapseChangelog": true,
+  "treeFilterMode": "all"
+}

package/harnesses/pi-distro-one/harness.md

@@ -0,0 +1,79 @@
+---
+name: pi-distro-one
+title: pi-distro-one
+description: "A Claude Code–style coding agent distribution built around autonomous sub-agent spawning and coordination, with web research, browser automation, live shell, model routing, and task management in support. Includes a Claude-style status line and an explore-before-acting approach."
+version: 0.3.0
+tags: [full-config, claude-code-style]
+---
+
+# pi-distro-one
+
+A complete interactive coding agent configuration that attempts to mimic as closely as
+possible the functionality of today's Claude Code. The primary capability is spawning and
+coordinating autonomous sub-agents; the remaining functionality is integrated in support
+of that.
+
+## Bundled files
+The following bundled files are provided under `files/` and should be placed into the
+target project. For any path that already exists, do NOT overwrite — show the user a diff
+and ask whether to overwrite, keep theirs, or merge. Merge JSON settings field-by-field.
+Append AGENTS.md content under a delimited section if one exists.
+
+- `files/AGENTS.md` → `./AGENTS.md`
+- `files/settings.json` → `./.pi/settings.json` (merge with existing settings)
+- `files/.pi/extensions/claude-statusline.ts` → `./.pi/extensions/claude-statusline.ts`
+
+## pi packages to install
+Use `pi install -l` to install the following **project-locally** (writes to
+`./.pi/settings.json` on success, leaves settings untouched on failure). Confirm with the
+user before each install. Do NOT pre-add these to the bundled `settings.json` `packages`
+array — `pi install -l` is the single registration mechanism.
+
+- `npm:@tintinweb/pi-subagents` — Claude Code–style autonomous sub-agents: spawn
+  specialized agents in isolated sessions, each with its own tools, system prompt, model,
+  and thinking level; parallel execution, a live monitoring widget, mid-run steering, and
+  session resumption (the primary capability of this distribution)
+- `npm:pi-web-access` — web search, URL fetching, GitHub cloning, PDF/video extraction
+- `npm:pi-agent-browser-native` — real browser automation and web interaction
+- `npm:pi-bash-live-view` — live terminal rendering for shell commands
+- `npm:@yeliu84/pi-model-router` — model routing / fallback across providers
+- `npm:@robhowley/pi-openrouter` — OpenRouter provider integration
+- `npm:@juicesharp/rpiv-todo` — task list management
+- `npm:pi-goal` — persistent autonomous goals: `/goal` loops until complete, paused, or
+  budget-limited, so long-running objectives survive across turns without manual babysitting
+- `npm:@trevonistrevon/pi-loop` — cron/event-based agent re-wake loops and background
+  process monitoring: schedule agents to re-wake on time or events and keep long-running
+  or background work alive without manual babysitting
+- `npm:@juicesharp/rpiv-ask-user-question` — structured questionnaire the model can put to
+  the user when it would otherwise guess, with typed options instead of free-form replies
+  (reduces ambiguous decisions and keeps the user in the loop on judgment calls)
+
+**Tool-name conflict check:** before installing, cross-check each package's purpose
+against the already-active tools in the target project (run `pi list`). If a package
+overlaps an existing tool — either an exact name collision or semantic redundancy
+(different names, similar function) — offer **skip / replace / keep both / cancel** instead
+of installing blindly. (Exact name collisions are non-fatal in pi — project-local tools
+shadow global ones — but redundancy leaves a confusing duplicate tool set.)
+
+## Custom extension (bundled)
+`files/.pi/extensions/claude-statusline.ts` is a Claude-style status-line footer
+(model | dir | thinking level | context-window bar gauge + cache % | git branch status).
+It auto-enables on session start and is toggleable via the `/claude-statusline` command.
+It also **auto-expands tool outputs** on session start (the Ctrl+O effect) so full output
+is visible by default, while keeping thinking blocks hidden for a clean working view.
+Deploy it to `./.pi/extensions/claude-statusline.ts`; pi loads it via jiti on next start
+(no build step). It depends only on pi core (`@earendil-works/pi-coding-agent`,
+`@earendil-works/pi-ai`, `@earendil-works/pi-tui`) — all provided as peer deps.
+
+## Settings (bundled)
+`files/settings.json` provides the agent's defaults: high thinking level, one-at-a-time
+steering, hidden thinking blocks, and hardware cursor. Tool outputs are auto-expanded on
+start (via the status-line extension). Merge with any existing `.pi/settings.json`
+field-by-field. Auth and model/provider configuration are not part of this distribution —
+configure those independently.
+
+## Context
+The bundled `AGENTS.md` is an explore-before-acting working methodology: investigate
+before implementing, surface interpretations and tradeoffs, make surgical changes, keep
+solutions simple, execute against verifiable goals, and treat documentation as part of the
+implementation. Deploy it to `./AGENTS.md` so the agent follows these conventions.

package/harnesses/web-fullstack/README.md

@@ -0,0 +1,25 @@
+# web-fullstack
+
+A full-stack React/Node project configuration with web research, code review, and a
+restricted tool set.
+
+## What it sets up
+
+- **`AGENTS.md`** — frontend and backend conventions, testing guidance, and a code
+  review process tailored to React/Node projects.
+- **`.pi/settings.json`** — sensible defaults with a restricted tools allowlist (only
+  the essential tools, keeping the agent focused).
+- **`.pi/prompts/review.md`** — a review prompt template for on-demand structured code
+  reviews.
+
+## Packages installed
+
+- **`npm:pi-browse`** — web search (Brave / DuckDuckGo / Exa / Gemini) and content
+  extraction. Used for documentation lookup, API verification, and research.
+
+## When to use
+
+- You're building a React/Node full-stack application.
+- You want web research built in for looking up docs and APIs.
+- You want a structured code review workflow.
+- You prefer a restricted tool set over the full default set.

package/harnesses/web-fullstack/files/.pi/prompts/review.md

@@ -0,0 +1,12 @@
+# Code Review
+
+Review the changes for: correctness, security, performance, accessibility, and test coverage.
+Provide specific, actionable feedback referencing line numbers or code blocks.
+
+## Checklist
+
+- **Correctness**: Does the code do what it claims? Are edge cases handled?
+- **Security**: Are inputs validated? Are secrets handled safely? Any injection risks?
+- **Performance**: Are there unnecessary re-renders, N+1 queries, or blocking operations?
+- **Accessibility**: Are semantic HTML elements used? Are interactive elements keyboard-accessible?
+- **Test coverage**: Are the new behaviors tested? Do existing tests still pass?

package/harnesses/web-fullstack/files/AGENTS.md

@@ -0,0 +1,37 @@
+# Project Instructions — Full-Stack Web
+
+Guidance for working in this React/Node full-stack project.
+
+## Frontend Conventions (React/Next.js)
+
+- Use TypeScript for all frontend code.
+- Prefer function components with hooks over class components.
+- Use named exports for components; default export only for page components.
+- Co-locate component styles using CSS Modules or Tailwind utility classes.
+- Keep components small and composable — extract reusable logic into custom hooks.
+- Use `next/navigation` (App Router) for routing in Next.js projects.
+
+## Backend Conventions (Node/Express)
+
+- Use TypeScript for all backend code.
+- Structure API routes with clear separation: controller → service → data layer.
+- Validate all request inputs with a schema validation library (e.g. zod, typebox).
+- Return consistent error response shapes: `{ error: { code, message, details? } }`.
+- Use environment variables for configuration; never hardcode secrets.
+- Prefer async/await over callback chains.
+
+## Testing
+
+- Write tests alongside the code they verify (co-located `*.test.ts` or `__tests__/`).
+- Use Vitest or Jest for unit/integration tests.
+- Use Playwright or Cypress for end-to-end tests.
+- Aim for meaningful coverage of business logic, not 100% line coverage.
+- Run tests in CI on every pull request.
+
+## Code Review Process
+
+- All changes require at least one approving review before merge.
+- Use the review prompt template at `.pi/prompts/review.md` for structured reviews.
+- Focus reviews on: correctness, security, performance, accessibility, and test coverage.
+- Provide specific, actionable feedback. Reference line numbers or code blocks.
+- Approve only when all blocking comments are resolved.

package/harnesses/web-fullstack/files/settings.json

@@ -0,0 +1,11 @@
+{
+  "tools": [
+    "read",
+    "bash",
+    "edit",
+    "write",
+    "grep",
+    "find",
+    "ls"
+  ]
+}

package/harnesses/web-fullstack/harness.md

@@ -0,0 +1,40 @@
+---
+name: web-fullstack
+title: Full-Stack Web
+description: "React/Node project with web-research + review skills, review-oriented context, and a sensible tools allowlist."
+version: 0.1.0
+tags: [web, react, node]
+---
+
+# Full-Stack Web
+
+## Bundled files
+The following bundled files are provided under `files/` and should be placed into the
+target project. For any path that already exists, do NOT overwrite — show the user a diff
+and ask whether to overwrite, keep theirs, or merge. Merge JSON settings objects field by
+field. Append (not replace) `AGENTS.md` content under a clearly-delimited section.
+
+- `files/AGENTS.md` → `./AGENTS.md`
+- `files/settings.json` → `./.pi/settings.json` (merge with existing settings)
+- `files/.pi/prompts/review.md` → `./.pi/prompts/review.md`
+
+## pi packages to install
+Use `pi install -l` to install the following **project-locally** (writes to `./.pi/settings.json`
+on success, and does nothing on failure). Confirm with the user before each install. Do NOT
+pre-add these packages to the bundled `settings.json` — `pi install -l` is the single source
+of truth that registers a package, so that a failed install never leaves a dangling entry
+in settings.
+
+- `npm:pi-browse` — web search (Brave/DuckDuckGo/Exa/Gemini) and content extraction for
+  documentation lookup and API verification
+
+## Context
+This harness sets up a full-stack web project with React/Node conventions. The bundled
+`AGENTS.md` contains frontend and backend conventions, testing guidance, and a code review
+process. The `settings.json` restricts the tools allowlist to the essential set. A review
+prompt template is included under `.pi/prompts/` for on-demand code reviews.
+
+## Skills / prompts
+- The `pi-browse` package (installed above) provides web research capabilities.
+- A review prompt template is bundled at `files/.pi/prompts/review.md` and deployed to
+  `./.pi/prompts/review.md`. Use it to run structured code reviews on changes.