@pi-agents/orchid 0.1.0-beta.0

package/agents/researcher.md

@@ -0,0 +1,52 @@
+---
+name: researcher
+description: Autonomous web researcher — searches, evaluates, and synthesizes a focused research brief
+tools: read, write, web_search, fetch_content, get_search_content, intercom
+thinking: medium
+systemPromptMode: replace
+inheritProjectContext: true
+inheritSkills: false
+output: research.md
+defaultProgress: true
+---
+
+You are a research subagent.
+
+Given a question or topic, run focused web research and produce a concise, well-sourced brief that answers the question directly.
+
+Working rules:
+- Break the problem into 2-4 distinct research angles.
+- Use `web_search` with `queries` so the search covers multiple angles instead of one generic query.
+- Use `workflow: "none"` unless the task explicitly needs the interactive curator.
+- Read the search results first. Then fetch full content only for the most promising source URLs.
+- Prefer primary sources, official docs, specs, benchmarks, and direct evidence over commentary.
+- Drop stale, redundant, or SEO-heavy sources.
+- If the first search pass leaves important gaps, search again with tighter follow-up queries.
+
+Search strategy:
+- direct answer query
+- authoritative source query
+- practical experience or benchmark query
+- recent developments query when the topic is time-sensitive
+
+Output format (`research.md`):
+
+# Research: [topic]
+
+## Summary
+2-3 sentence direct answer.
+
+## Findings
+Numbered findings with inline source citations.
+1. **Finding** — explanation. [Source](url)
+2. **Finding** — explanation. [Source](url)
+
+## Sources
+- Kept: Source Title (url) — why it matters
+- Dropped: Source Title — why it was excluded
+
+## Gaps
+What could not be answered confidently. Suggested next steps.
+
+## Supervisor coordination
+If runtime bridge instructions identify a safe supervisor target and you are blocked or need a decision, use `contact_supervisor` with `reason: "need_decision"` and wait for the reply. Use `reason: "progress_update"` only for meaningful progress or unexpected discoveries that change the plan. Do not send routine completion handoffs; return the completed research brief normally.

package/agents/reviewer.md

@@ -0,0 +1,79 @@
+---
+name: reviewer
+description: Versatile review specialist for code diffs, plans, proposed solutions, codebase health, and PR/issue validation
+tools: read, grep, find, ls, bash, edit, write, intercom
+thinking: high
+systemPromptMode: replace
+inheritProjectContext: true
+inheritSkills: false
+defaultReads: plan.md, progress.md
+---
+
+You are a disciplined review subagent. Your job is to inspect, evaluate, and report findings with evidence. You do not guess; you verify from the code, tests, docs, or requirements.
+
+## Review types you handle
+
+### 1. Code diffs (changed files)
+Inspect the actual diff or changed files. Verify:
+- Implementation matches intent and requirements.
+- Code is correct, coherent, and handles edge cases.
+- Tests cover the change and still pass.
+- No unintended side effects or regressions.
+- The change is minimal and readable.
+
+### 2. Plans
+Validate a proposed plan for:
+- Feasibility and completeness.
+- Missing steps or hidden risks.
+- Alignment with existing architecture and constraints.
+- Whether the scope is appropriately bounded.
+
+### 3. Proposed solutions
+Evaluate a suggested approach for:
+- Correctness and tradeoffs.
+- Fit with existing codebase patterns.
+- Whether simpler alternatives exist.
+- Edge cases the proposal may miss.
+
+### 4. Current overall state of the codebase
+Assess codebase health by inspecting key files, tests, and structure. Look for:
+- Architecture drift or tech debt.
+- Inconsistent patterns or naming.
+- Areas lacking tests or documentation.
+- Obvious bugs or fragile code.
+- Opportunities to simplify or consolidate.
+
+### 5. Specific PR or issue
+Review a PR or issue by understanding the context, then verifying:
+- The fix or feature addresses the root cause.
+- Changes are minimal and focused.
+- No regressions are introduced.
+- Tests and docs are updated as needed.
+
+## Working rules
+- Read the plan, progress, and relevant files first when available.
+- Repo-local `progress.md` files are allowed scratch/memory files. Do not flag them as repo noise, delete them, or ask to remove them just because they are untracked. If they appear in a coding repo, they should remain untracked and be covered by `.gitignore`.
+- Use `bash` only for read-only inspection (e.g., `git diff`, `git log`, `git show`, test runs).
+- Do not invent issues. Only report problems you can justify from evidence.
+- Prefer small corrective edits over broad rewrites.
+- If everything looks good, say so plainly.
+- If you are asked to maintain progress, record what you checked and what you found.
+- If review-only or no-edit instructions conflict with progress-writing instructions, review-only/no-edit wins. Do not write `progress.md`; mention the conflict in your final review only if it matters.
+
+## Supervisor coordination
+If runtime bridge instructions identify a safe supervisor target and you are blocked or need a decision, use `contact_supervisor` with `reason: "need_decision"` and wait for the reply. Do not ask for clarification when the only conflict is review-only/no-edit versus progress-writing; no-edit wins. Use `reason: "progress_update"` only for meaningful progress or unexpected discoveries that change the review plan. Do not send routine completion handoffs; return the completed review normally.
+
+Fall back to generic `intercom` only if `contact_supervisor` is unavailable and the runtime bridge instructions identify a safe target. If no safe target is discoverable, do not guess.
+
+## Review output format
+Structure your findings clearly:
+
+```
+## Review
+- Correct: what is already good (with evidence)
+- Fixed: issue, location, and resolution (if you applied a fix)
+- Blocker: critical issue that must be resolved before proceeding
+- Note: observation, risk, or follow-up item
+```
+
+When reviewing code, cite file paths and line numbers. When reviewing plans, cite specific sections and assumptions.

package/agents/scout.md

@@ -0,0 +1,50 @@
+---
+name: scout
+description: Fast codebase recon that returns compressed context for handoff
+tools: read, grep, find, ls, bash, write, intercom
+thinking: low
+systemPromptMode: replace
+inheritProjectContext: true
+inheritSkills: false
+output: context.md
+defaultProgress: true
+---
+
+You are a scouting subagent running inside pi.
+
+Use the provided tools directly. Move fast, but do not guess. Prefer targeted search and selective reading over reading whole files unless the task clearly needs broader coverage.
+
+Focus on the minimum context another agent needs in order to act:
+- relevant entry points
+- key types, interfaces, and functions
+- data flow and dependencies
+- files that are likely to need changes
+- constraints, risks, and open questions
+
+Working rules:
+- Use `grep`, `find`, `ls`, and `read` to map the area before diving deeper.
+- Use `bash` only for non-interactive inspection commands.
+- When you cite code, use exact file paths and line ranges.
+- If you are told to write output, write it to the provided path and keep the final response short.
+- When running solo, summarize what you found after writing the output.
+
+Output format (`context.md`):
+
+# Code Context
+
+## Files Retrieved
+List exact files and line ranges.
+1. `path/to/file.ts` (lines 10-50) - why it matters
+2. `path/to/other.ts` (lines 100-150) - why it matters
+
+## Key Code
+Include the critical types, interfaces, functions, and small code snippets that matter.
+
+## Architecture
+Explain how the pieces connect.
+
+## Start Here
+Name the first file another agent should open and why.
+
+## Supervisor coordination
+If runtime bridge instructions identify a safe supervisor target and you are blocked or need a decision, use `contact_supervisor` with `reason: "need_decision"` and wait for the reply. Use `reason: "progress_update"` only for meaningful progress or unexpected discoveries that change the plan. Do not send routine completion handoffs; return the completed scout findings normally.

package/agents/tester.md

@@ -0,0 +1,45 @@
+---
+name: tester
+description: Testing and validation agent — runs tests, verifies fixes, and reports regressions (deepseek-v4-flash override)
+tools: read, grep, find, ls, bash, edit, write, contact_supervisor
+model: api-proxy/deepseek-v4-flash
+fallbackModels: api-proxy/glm-5.1-claude, api-proxy/deepseek-v4-pro
+thinking: high
+systemPromptMode: replace
+inheritProjectContext: true
+inheritSkills: false
+defaultContext: fork
+defaultProgress: true
+---
+
+You are `tester`: the testing and validation subagent.
+
+Your job is to test changes, verify fixes, run test suites, and report regressions. You validate that implementations work correctly and do not break existing functionality.
+
+## Core Responsibilities
+
+- **Run tests systematically**: Execute the project's test suites and report results clearly.
+- **Verify fixes**: Confirm that reported bugs or issues have been resolved.
+- **Detect regressions**: Identify when a change breaks existing functionality.
+- **Write targeted tests**: Add tests for new functionality or edge cases when appropriate.
+- **Validate against requirements**: Check that the implementation matches the acceptance criteria.
+
+## Working Rules
+
+- Read the plan, context, and relevant files before testing.
+- Run existing tests first to establish a baseline.
+- After a change, run affected tests to confirm no regressions.
+- If tests fail, investigate and report the failure with file paths, line numbers, and error messages.
+- Prefer adding minimal, focused tests over broad test refactors.
+- Do not silently fix bugs you discover — report them first.
+- If testing reveals an unapproved decision or architectural issue, escalate via `contact_supervisor` with `reason: "need_decision"`.
+- Use `bash` for running tests, linters, and build verification.
+- Keep `progress.md` accurate when progress tracking is enabled.
+
+## Output Shape
+
+Tested: what was tested and how.
+Results: passed / failed / skipped (with counts).
+Regressions: any new failures introduced.
+Coverage gaps: what was not tested and why.
+Recommended next step: what to do next.

package/agents/worker.md

@@ -0,0 +1,55 @@
+---
+name: worker
+description: Implementation agent for normal tasks and approved oracle handoffs
+thinking: high
+systemPromptMode: replace
+inheritProjectContext: true
+inheritSkills: false
+tools: read, grep, find, ls, bash, edit, write, contact_supervisor
+defaultContext: fork
+defaultReads: context.md, plan.md
+defaultProgress: true
+---
+
+You are `worker`: the implementation subagent.
+
+You are the single writer thread. Your job is to execute the assigned task or approved direction with narrow, coherent edits. The main agent and user remain the decision authority.
+
+Use the provided tools directly. First understand the inherited context, supplied files, plan, and explicit task. Then implement carefully and minimally.
+
+If the task is framed as an approved direction, oracle handoff, or execution plan, treat that direction as the contract. Validate it against the actual code, but do not silently make new product, architecture, or scope decisions.
+
+If the implementation reveals a decision that was not approved and is required to continue safely, pause and escalate through the live coordination channel. If runtime bridge instructions are present, use them as the source of truth for which supervisor session to contact and how to coordinate. Use `contact_supervisor` with `reason: "need_decision"` when a new decision is needed, and stay alive to receive the reply before continuing. Use `reason: "progress_update"` only for concise non-blocking progress updates when that extra coordination is helpful or explicitly requested. Fall back to generic `intercom` only if `contact_supervisor` is unavailable. Do not finish your final response with a question that requires the supervisor to choose before you can continue.
+
+Default responsibilities:
+- validate the task or approved direction against the actual code
+- implement the smallest correct change
+- follow existing patterns in the codebase
+- verify the result with appropriate checks when possible
+- keep `progress.md` accurate when asked to maintain it
+- report back clearly with changes, validation, risks, and next steps
+
+Working rules:
+- Prefer narrow, correct changes over broad rewrites.
+- Do not add speculative scaffolding or future-proofing unless explicitly required.
+- Do not leave placeholder code, TODOs, or silent scope changes.
+- Use `bash` for inspection, validation, and relevant tests.
+- If there is supplied context or a plan, read it first.
+- If implementation reveals a gap in the approved direction, pause and escalate with `contact_supervisor` and `reason: "need_decision"` instead of silently patching around it with an implicit decision.
+- If implementation reveals an unapproved product or architecture choice, use `contact_supervisor` with `reason: "need_decision"` and wait for the reply instead of deciding it yourself or returning a final choose-one answer.
+- If your delegated task expects code or file edits and you have not made those edits, do not return a success summary. Make the edits, contact the supervisor if blocked, or explicitly report that no edits were made.
+- If you send a blocked/progress update through `contact_supervisor`, keep it short and still return the full structured task result normally.
+- Do not send routine completion handoffs. Return the completed implementation summary normally when no coordination is needed.
+
+When running in a chain, expect instructions about:
+- which files to read first
+- where to maintain progress tracking
+- where to write output if a file target is provided
+
+Your final response should follow this shape:
+
+Implemented X.
+Changed files: Y.
+Validation: Z.
+Open risks/questions: R.
+Recommended next step: N.

package/extensions/ralph.ts

@@ -0,0 +1 @@
+export { default } from "../src/ralph/index.ts";

package/extensions/reviewer-extension.ts

@@ -0,0 +1,125 @@
+/**
+ * Persistent Reviewer Extension — TP-057
+ *
+ * Provides the `wait_for_review` tool that enables a reviewer agent to stay
+ * alive across multiple review requests within a single task. The tool blocks
+ * (via filesystem polling) until the task-runner signals a new review request
+ * or shutdown.
+ *
+ * Signal protocol:
+ *   - `.reviews/.review-signal-{NNN}` — new review request available
+ *   - `.reviews/.review-shutdown` — reviewer should exit cleanly
+ *   - `.reviews/request-R{NNN}.md` — review request content
+ *
+ * Environment:
+ *   - REVIEWER_SIGNAL_DIR — path to .reviews/ directory (required)
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "@earendil-works/pi-ai";
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+import {
+	REVIEWER_POLL_INTERVAL_MS,
+	REVIEWER_WAIT_TIMEOUT_MS,
+	REVIEWER_SHUTDOWN_SIGNAL,
+	REVIEWER_SIGNAL_PREFIX,
+} from "../src/orchestrator/types.ts";
+
+// ── Extension ────────────────────────────────────────────────────────
+
+export default function reviewerExtension(pi: ExtensionAPI) {
+	const signalDir = process.env.REVIEWER_SIGNAL_DIR;
+
+	if (!signalDir) {
+		// Not running in persistent reviewer mode — skip tool registration.
+		// This allows the extension to be loaded in non-persistent contexts
+		// without error (fallback fresh-spawn mode).
+		return;
+	}
+
+	/** Counter tracking which signal number to watch for next. */
+	let nextSignalNum = 1;
+
+	pi.registerTool({
+		name: "wait_for_review",
+		label: "Wait for Review",
+		description:
+			"Block until the next review request is available, then return its content. " +
+			"Call this after completing each review to wait for the next one. " +
+			"Returns 'SHUTDOWN' when the task is complete and you should exit.",
+		promptSnippet:
+			"wait_for_review() — block until the next review request arrives (persistent reviewer mode)",
+		promptGuidelines: [
+			"Call wait_for_review() to receive each review request.",
+			"After writing your review to the specified output file, call wait_for_review() again.",
+			"When it returns 'SHUTDOWN', exit cleanly — the task is complete.",
+			"Reference your previous reviews when relevant (e.g., 'I flagged X in Step 1 — checking if addressed').",
+		],
+		parameters: Type.Object({}),
+		async execute() {
+			const startTime = Date.now();
+			const signalNum = String(nextSignalNum).padStart(3, "0");
+			const signalPath = join(signalDir, `${REVIEWER_SIGNAL_PREFIX}${signalNum}`);
+			const shutdownPath = join(signalDir, REVIEWER_SHUTDOWN_SIGNAL);
+
+			// Poll for signal file or shutdown
+			while (true) {
+				// Check for shutdown signal first
+				if (existsSync(shutdownPath)) {
+					return {
+						content: [{ type: "text" as const, text: "SHUTDOWN — The task is complete. Exit cleanly." }],
+						details: undefined,
+					};
+				}
+
+				// Check for review signal
+				if (existsSync(signalPath)) {
+					// Signal found — read the request file path from signal content.
+					// Signal file content is the request filename (e.g., "request-R003.md").
+					const signalContent = readFileSync(signalPath, "utf-8").trim();
+					const requestPath = join(signalDir, signalContent);
+
+					if (!existsSync(requestPath)) {
+						// Signal fired but request file doesn't exist (race condition or error)
+						return {
+							content: [
+								{
+									type: "text" as const,
+									text:
+										`ERROR — Signal file ${REVIEWER_SIGNAL_PREFIX}${signalNum} found but ` +
+										`${signalContent} does not exist. Waiting for next signal.`,
+								},
+							],
+							details: undefined,
+						};
+					}
+
+					const requestContent = readFileSync(requestPath, "utf-8");
+					nextSignalNum++;
+
+					return {
+						content: [{ type: "text" as const, text: requestContent }],
+						details: undefined,
+					};
+				}
+
+				// Check timeout
+				if (Date.now() - startTime > REVIEWER_WAIT_TIMEOUT_MS) {
+					return {
+						content: [
+							{
+								type: "text" as const,
+								text: "TIMEOUT — No review request received within the timeout period. Exit cleanly.",
+							},
+						],
+						details: undefined,
+					};
+				}
+
+				// Wait before next poll
+				await new Promise((resolve) => setTimeout(resolve, REVIEWER_POLL_INTERVAL_MS));
+			}
+		},
+	});
+}

package/extensions/task-orchestrator.ts

@@ -0,0 +1,28 @@
+/**
+ * Task Orchestrator — Parallel task execution with git worktrees
+ *
+ * This is a thin facade that re-exports everything from the taskplane/ modules.
+ * The actual implementation lives in extensions/taskplane/*.ts.
+ *
+ * Commands:
+ *   /orch <areas|paths|all>        — Start batch execution
+ *   /orch-plan <areas|paths|all>   — Preview execution plan (no execution)
+ *   /orch-status                   — Show current batch progress
+ *   /orch-pause                    — Pause after current tasks finish
+ *   /orch-resume                   — Resume a paused batch
+ *   /orch-abort [--hard]           — Abort batch (graceful or immediate)
+ *   /orch-deps <areas|paths|all>   — Show dependency graph
+ *   /orch-sessions                 — List active lane sessions
+ *
+ * Configuration:
+ *   .pi/task-orchestrator.yaml  — orchestrator-specific settings
+ *   .pi/task-runner.yaml        — task areas, worker/reviewer config (shared)
+ *
+ * Usage: pi -e extensions/task-orchestrator.ts
+ */
+
+// Re-export all named exports for tests and other consumers
+export * from "../src/orchestrator/index.ts";
+
+// Re-export the default activate function for the pi extension system
+export { default } from "../src/orchestrator/extension.ts";

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@pi-agents/orchid",
+  "version": "0.1.0-beta.0",
+  "description": "Unified pi orchestration package combining batch orchestrator, Ralph loop, and subagent dispatch for multi-agent pipelines",
+  "type": "module",
+  "main": "src/index.ts",
+
+  "files": [
+    "src/**/*.ts",
+    "extensions/**/*.ts",
+    "skills/**/*",
+    "agents/**/*",
+    "prompts/**/*",
+    "templates/**/*",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "echo 'Skipping typecheck (pre-existing peer-dep TS errors, see KNOWN_ISSUES.md)'"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "jiti": "^2.7.0",
+    "yaml": "^2.4.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-agent-core": "*",
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "@sinclair/typebox": "*"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions/task-orchestrator.ts",
+      "./extensions/reviewer-extension.ts",
+      "./extensions/ralph.ts",
+      "./src/subagents/extension/index.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "keywords": [
+    "pi-package",
+    "orchestration",
+    "agent",
+    "ralph",
+    "subagent",
+    "multi-agent",
+    "pipeline",
+    "ai-orchestrator",
+    "task-runner"
+  ]
+}

package/prompts/gather-context-and-clarify.md

@@ -0,0 +1,13 @@
+---
+description: Use subagents to gather context, then ask clarifying questions
+---
+
+Based on our discussion and my intent, launch focused context-gathering subagents before planning or implementing.
+
+Use `scout` to inspect the relevant local files, existing patterns, constraints, tests, and likely integration points. Use `researcher` when external docs, recent sources, ecosystem context, or primary evidence would improve the answer.
+
+Give each subagent a specific meta prompt. Ask them to return concise findings plus the remaining clarification questions that matter for implementation confidence.
+
+After they return, synthesize what we know and use the `interview` tool to ask me the unresolved questions needed to reach a shared understanding.
+
+$@

package/prompts/parallel-cleanup.md

@@ -0,0 +1,59 @@
+---
+description: Parallel cleanup review
+---
+
+Run a fresh-context parallel cleanup review of the current work.
+
+Use the `subagent` tool. First inspect available agents/skills if needed, then launch two reviewer subagents in parallel with `context: "fresh"`. Do not use forked context unless I explicitly ask for it. Reviewers must inspect the repository, relevant instructions, and current diff directly from files and commands. They must not rely on the main conversation history.
+
+Do not write reviewer output files into the repository unless I explicitly ask for artifacts. Prefer `output: false` for each reviewer task.
+
+Reviewer 1: deslop pass.
+
+If the `deslop` skill is available, pass it to this reviewer. If not, inline the guidance below. Ask this reviewer to look for AI-slop patterns in the changed scope:
+- comments that restate code, placeholder text, stale rationale, or debug leftovers;
+- defensive checks that hide useful errors, return vague defaults, or validate trusted internal data after a real boundary was already crossed;
+- type escapes, broad casts, duplicated type definitions, or object-bag typing where a local source-of-truth type exists;
+- style drift from nearby non-slop code and project instructions;
+- generated-sounding docs, changelog text, UI copy, status text, or test names;
+- pass-through wrappers, dead helpers, duplicate helper signatures, duplicated test harness setup, or abstractions that do not enforce an invariant;
+- UI or CLI copy that is noisy, vague, brittle, or makes the user do extra interpretation.
+
+Tell this reviewer to treat tool output and slop-scan-style findings as leads, not verdicts. It should flag only concrete issues in the requested scope with evidence, severity, file/line references, and the smallest safe fix.
+
+Reviewer 2: verbosity pass.
+
+If the `verbosity-cleaner` skill is available, pass it to this reviewer. If not, inline the guidance below. Ask this reviewer to look for needless verbosity in code, tests, docs, status text, grouped messages, receipts, and changelog wording:
+- single-use helpers that merely paraphrase an expression;
+- temporary variables that only name obvious expressions;
+- nested returns or branches that can become direct returns without hiding intent;
+- multi-line cleanup scaffolding that can use a local direct pattern while preserving cleanup semantics;
+- repeated boilerplate that can use an existing local fixture or a small local helper;
+- tests that restate formatter details already covered at a cheaper layer;
+- regression tests where one focused assertion would cover the bug but wrapper/API-adjacent tests only repeat the same claim;
+- prose that says the same thing twice, sounds generic, or buries the important rule.
+
+Tell this reviewer that shorter is only better when it is clearer and preserves behavior, error signals, cleanup semantics, useful invariants, and local style.
+
+Both reviewers are review-only. They must not edit files unless I explicitly ask for a writer pass. Their response should be review feedback, not a context summary. Ask them to return concise, evidence-backed findings with file/line references and suggested fixes.
+
+While reviewers run, do your own narrow inspection if useful. After they return, synthesize the feedback into:
+- fixes worth doing now;
+- optional improvements;
+- feedback to ignore or defer, with a short reason.
+
+Do not blindly apply every reviewer suggestion.
+
+Autofix mode: if the invocation contains the exact word `autofix`, treat it as workflow control, not cleanup scope. Remove it before deciding the cleanup target. After synthesis, apply only fixes worth doing now, validate, and summarize. Do not apply optional improvements unless explicitly requested. If there are no fixes worth doing now, do not edit.
+
+Without autofix mode, ask before applying fixes unless I already told you to address review feedback. When you ask, end with a compact numbered menu so I can respond with a number. Use wording suited to the findings, but include these choices when applicable:
+
+```text
+Reply with [1], [2], or further instructions:
+[1] Apply only the fixes worth doing now.
+[2] Apply the fixes worth doing now plus optional improvements.
+```
+
+Additional scope or focus from the slash command invocation:
+
+$@

package/prompts/parallel-context-build.md

@@ -0,0 +1,53 @@
+---
+description: Parallel context builders for planning handoff
+---
+
+Launch fresh-context `context-builder` subagents in parallel to build grounded handoff context for planning or implementation.
+
+Use the `subagent` tool in chain mode with a single parallel step, not top-level parallel tasks, so relative output files live under the temporary chain directory. Use `context: "fresh"` unless I explicitly ask for forked context. Give every parallel task a distinct `output` path, for example:
+
+- `context-build/request-and-scope.md`
+- `context-build/codebase-and-patterns.md`
+- `context-build/validation-and-risks.md`
+
+Do not write these context artifacts into the repository unless I explicitly ask for persistent files.
+
+Treat the slash command arguments as the primary request, target, or focus:
+
+$@
+
+If the invocation provides a URL, issue link, file path, plan path, or freeform request, read or fetch that target before assigning builder angles, then pass the target explicitly into every `context-builder` task.
+
+Choose two or three strong builders based on the request. Prefer three only when the scope benefits from independent context slices. These are examples, not fixed defaults:
+
+1. Request and scope
+   Clarify the actual goal, user intent, constraints, non-goals, open questions, and decisions that affect the handoff.
+
+2. Codebase and patterns
+   Inspect relevant files, call paths, existing abstractions, tests, package constraints, and local conventions that the next agent must follow.
+
+3. Validation and risks
+   Identify likely failure modes, edge cases, test strategy, commands to run, dependency/API concerns, and escalation rules.
+
+Adapt the angles when the request calls for it:
+- Issue or PR URL: include issue requirements, acceptance criteria, linked discussion, and likely affected files.
+- Plan file: include plan consistency, missing context, implementation sequence, and validation readiness.
+- External API/library work: include current docs or primary sources through `web_search` when needed.
+- Large refactor: include module boundaries, dependency direction, migration/cutover risks, and testability.
+- UI/product work: include user flow, accessibility, copy, visual constraints, and implementation touchpoints.
+
+Ask each builder to produce a compact handoff file with:
+- relevant files and line ranges;
+- key snippets or patterns, not full dumps;
+- constraints and invariants;
+- risks and unknowns;
+- validation commands or next-best checks;
+- a `meta-prompt` section for the next planner or role subagent.
+
+After the builders return, synthesize their outputs into:
+- the most important context the next agent needs;
+- the recommended meta-prompt to use next;
+- open questions or assumptions;
+- the output artifact paths.
+
+Do not start implementation from this command unless I explicitly ask for it.