@damiangilgonzalez/harness 1.3.7

package/skills/zapier/references/zapier-mcp-tools.md

@@ -0,0 +1,72 @@
+# Zapier MCP — tools, lifecycle, and call sketches
+
+Depth overflow for `SKILL.md`. The hosted Zapier MCP server exposes two layers of tools:
+
+1. **Static meta-tools** — a fixed set (~14; **verify the current list at `docs.zapier.com/mcp`**, it changes) that let an agent discover, enable, configure, and execute actions dynamically. These are always present once the server is connected.
+2. **Enabled app actions** — the specific actions you turned on for this MCP server (e.g. `slack_send_channel_message`). These appear as their own callable tools after you enable them.
+
+Zapier hosts the server (`mcp.zapier.com/api/v1/connect`) and it is closed-source, so treat the exact tool names below as representative, not a contract. Confirm names against the live server's advertised tool list before hardcoding.
+
+## The meta-tool families
+
+| Family | Representative tool(s) | Purpose | Read/write |
+| --- | --- | --- | --- |
+| **Discover** | `discover_zapier_actions` | Search the 40,000+ action catalog by natural language; returns action ids you can enable. | read (free) |
+| **Enable / manage** | `enable_zapier_action`, and list/disable/remove companions | Add a discovered action to this server so it becomes callable; list what is enabled; remove one. | read/config |
+| **Configure** | an edit/config tool | Pre-fill or constrain an enabled action's fields (e.g. pin a default Slack channel). | config |
+| **Execute — read** | `execute_zapier_read_action` | Run a search/find/get/list/lookup action. | read |
+| **Execute — write** | `execute_zapier_write_action` | Run a send/create/update/add/delete action — real side effect. | **write** |
+
+The server distinguishes read from write **in the tool name itself** — that is your safety signal (see the write-safety rule in `SKILL.md`). When in doubt, the verb in the action name (find/get/list = read; send/create/update/delete = write) decides.
+
+## Lifecycle, end to end
+
+```text
+# 1. DISCOVER — what can Slack do here? (free read)
+discover_zapier_actions({ query: "send a message to a Slack channel" })
+  → [ { id: "slack_send_channel_message", label: "Send Channel Message", ... }, ... ]
+
+# 2. ENABLE — make that action callable on this server
+enable_zapier_action({ action: "slack_send_channel_message" })
+  → { enabled: true, tool: "slack_send_channel_message" }
+
+# 3. (optional) CONFIGURE — pin defaults so the agent can't pick the wrong channel
+#    e.g. lock channel = "#alerts", leave text as the only agent-supplied field
+
+# 4. INVOKE — read first if you need to look something up (free-to-just-do)
+execute_zapier_read_action({
+  action: "slack_find_message",
+  inputs: { query: "deploy failed" }
+})
+
+#    …then the write, ONLY after showing the user the exact payload and getting approval
+execute_zapier_write_action({
+  action: "slack_send_channel_message",
+  inputs: { channel: "#alerts", text: "Deploy #4821 succeeded ✅" }
+})
+  → 2 Zapier tasks consumed on success
+```
+
+## Cost accounting
+
+- **2 Zapier tasks per successful tool call.** Failed calls cost nothing.
+- Discovery and enablement are lightweight; the expensive unit is each successful read/write **invocation**.
+- A polling or retrying agent multiplies this fast. Prefer a single precise call; do not loop `discover` in production paths (discover once, enable, then invoke the concrete tool by name).
+- Task quota is your Zapier plan's quota — MCP draws from the same bucket as your Zaps.
+
+## First-connect and error handling
+
+- If no Zapier tools are visible, the server is installed but **not authenticated** — the user must connect it in their client's MCP settings (the client redirects to `mcp.zapier.com` to sign in). Do not call Zapier tools until they appear.
+- `401 / unauthorized` → key expired or missing; re-authenticate at `mcp.zapier.com`.
+- `authentication required` on one app → that app's connection needs its own OAuth; the user connects it at `mcp.zapier.com`.
+- `tool/action not found` → not enabled on this server; discover + enable it, or the user adds it in the dashboard.
+- `rate limit` → space calls out.
+- Empty results are **not** an error — report "nothing found", don't silently retry with broader terms (each retry is real quota if it succeeds).
+
+Translate errors into plain language for the user; never dump the raw 401.
+
+## Handy patterns
+
+- **Scope the key.** Enable only the actions a given agent needs. The MCP key can fire everything enabled on that server, and Enterprise org restrictions are **not** enforced through MCP.
+- **Native MCP beats Zapier for a single app.** If a dedicated app MCP exists (e.g. a native Slack/Notion server), prefer it for that app; use Zapier for long-tail apps and cross-app chains. Never call both for one operation.
+- **Trigger vs action.** MCP invokes actions. To *start* a Zap the user built, POST to its Catch Hook URL instead — no MCP call, no 2-task charge for the trigger itself (the Zap's own steps bill as normal Zapier tasks).

package/targets/_md-block.js

@@ -0,0 +1,62 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { linkOrCopy } from './index.js';
+
+// Shared adapter for every assistant whose "always-on" surface is a plain
+// markdown instructions/rules file (AGENTS.md, copilot-instructions.md, a
+// .windsurf/.roo/.continue rule, …). Skills are symlinked to the shared base;
+// the suggest block is injected between idempotent markers so re-installs and
+// multiple assistants sharing one file never duplicate it.
+const MARK_START = '<!-- rsc-suggest:start -->';
+const MARK_END = '<!-- rsc-suggest:end -->';
+// The exact separator wireHook writes before an appended block, so unwireHook can take
+// back precisely what it gave and leave the rest of the file untouched.
+const SEAM = '\n\n';
+
+export function writeSkill(id, fromDir, toPath) {
+  return linkOrCopy(fromDir, toPath);
+}
+
+export function wireHook(paths, sourceMd, policy = {}) {
+  const full = stripFrontmatter(readFileSync(sourceMd, 'utf8'));
+  const body = policy.codeHooks === false
+    ? `# rsc-suggest — always-on operations layer\n\nRead \`docs/wiki/harness/user-profile.md\` before acting. If the user wants to build, add or change something, route it through \`grill-with-docs\` or \`wayfinder\` then \`to-spec\` before any code, then build it with \`superpowers:writing-plans\` (or \`to-tickets\` then \`implement\` for ticket-sized work) — unless it is a one-line change, typo, or config bump, which skips the chain. Use \`orient\` to keep the user situated and \`suggest\` to offer a missing skill only when the current task needs it. Close with the configured orientation block.\n`
+    : full;
+  const block = `${MARK_START}\n${body}\n${MARK_END}`;
+  let doc = existsSync(paths.hookTarget) ? readFileSync(paths.hookTarget, 'utf8') : '';
+  if (doc.includes(MARK_START)) {
+    doc = doc.replace(new RegExp(`${MARK_START}[\\s\\S]*?${MARK_END}`), block);
+  } else {
+    // Append with a fixed seam, and record nothing else. unwireHook removes exactly this
+    // seam and this block, which is what lets the file come back byte-identical.
+    doc += `${SEAM}${block}\n`;
+  }
+  mkdirSync(dirname(paths.hookTarget), { recursive: true });
+  writeFileSync(paths.hookTarget, doc);
+  return [paths.hookTarget];
+}
+
+// Inverse of wireHook: remove the marked rsc-suggest block from the shared
+// instructions file, leaving the user's own content intact. No-op when absent.
+export function unwireHook(paths) {
+  if (!existsSync(paths.hookTarget)) return [];
+  const doc = readFileSync(paths.hookTarget, 'utf8');
+  if (!doc.includes(MARK_START)) return [];
+  // Remove the block and the seam that introduced it — nothing more.
+  //
+  // This used to end with a document-wide `\n{3,}` -> `\n\n` pass, which tidied blank
+  // lines the author had put hundreds of lines away from anything of ours. In #249 that
+  // file was the project's hand-written constitution: it had already received 95 lines it
+  // never asked for, and giving it back reformatted is the second half of the same damage.
+  // A slightly larger gap is cosmetic; rewriting someone's document is not.
+  const cleaned = doc.replace(
+    new RegExp(`${SEAM.replace(/\n/g, '\\n')}?${MARK_START}[\\s\\S]*?${MARK_END}\\n?`),
+    '',
+  );
+  writeFileSync(paths.hookTarget, cleaned);
+  return [paths.hookTarget];
+}
+
+function stripFrontmatter(md) {
+  return md.replace(/^---\n[\s\S]*?\n---\n?/, '');
+}

package/targets/agent-catalog.js

@@ -0,0 +1,220 @@
+const REVIEW_TOOLS = Object.freeze(['read', 'search']);
+const RESOLVER_TOOLS = Object.freeze(['read', 'search', 'edit', 'shell']);
+
+const reviewerBody = ({ label, scope, probes, escalation = '' }) => `You are the ${label} reviewer. Review the requested diff or pull request; do not edit files.
+
+Boundary: ${scope}
+
+Work from changed lines outward just far enough to verify callers, imports, guards, and tests. Record an **attack list** even when every attack is clean. For each proposed finding, answer before reporting:
+1. What exact changed line supports it?
+2. What concrete input and state produce what wrong result?
+3. Which caller, import, and relevant test did you inspect?
+4. Why do existing guards not reduce the severity?
+
+HIGH and CRITICAL findings require the exact line and the full failure path. If either is missing, lower the severity or omit the finding. Prefer a clean verdict with a useful attack list over speculative volume.
+
+Stack attacks:
+${probes.map((probe) => `- ${probe}`).join('\n')}
+${escalation ? `\n${escalation}\n` : ''}
+Return: scope, attack list, findings ordered by severity, and verdict. A finding names file:line, failure mode, evidence, and the smallest test that would expose it.`;
+
+const resolverBody = ({ label, scope, signals, attempts = 3 }) => `You are the ${label} build resolver. Diagnose and repair one failing build with the smallest stack-correct change.
+
+Boundary: ${scope}
+
+1. Reproduce the named failure and preserve its exact command and first causal diagnostic.
+2. Trace that diagnostic to configuration, dependency, generated code, compiler, linker, or runtime setup.
+3. Change only what is needed for that cause; do not refactor, upgrade broadly, or clean unrelated warnings.
+4. Re-run the narrow failing command, then the nearest relevant test/build gate.
+5. Stop after ${attempts} unsuccessful repair attempts or as soon as the next step requires a refactor or product choice.
+
+Signals to distinguish:
+${signals.map((signal) => `- ${signal}`).join('\n')}
+
+Return the root cause, commands run, files changed, proof of the result, and any remaining blocker.`;
+
+const reviewer = ({ name, label, skills, not, probes, should, shouldNot, tier = 'balanced', escalation }) => ({
+  name,
+  role: 'reviewer',
+  tier,
+  tools: [...REVIEW_TOOLS],
+  skills,
+  desc: `${label} reviewer: inspects changed code for stack-specific failure modes and reports evidence without editing. NOT ${not}.`,
+  routing: { should, shouldNot },
+  body: reviewerBody({ label, scope: `Use for ${skills.join(' or ')} code. NOT ${not}.`, probes, escalation }),
+});
+
+const resolver = ({ name, label, skills, not, signals, should, shouldNot, tier = 'balanced' }) => ({
+  name,
+  role: 'build-resolver',
+  tier,
+  tools: [...RESOLVER_TOOLS],
+  skills,
+  desc: `${label} build resolver: reproduces a failing build and applies the minimum verified repair. NOT ${not}.`,
+  routing: { should, shouldNot },
+  body: resolverBody({ label, scope: `Use for ${skills.join(' or ')} build failures. NOT ${not}.`, signals }),
+});
+
+const REVIEWERS = [
+  reviewer({
+    name: 'django-reviewer', label: 'Django', skills: ['django'], not: 'general Python review or build repair',
+    probes: ['QuerySet evaluation, N+1 reads, and accidental full-table work.', 'Transaction boundaries, row locking, retries, and side effects inside atomic blocks.', 'Migration reversibility, historical models, nullable transitions, and deploy ordering.', 'Authorization at object/query boundaries rather than only at the view.'],
+    should: ['Review a Django ORM diff for query and transaction defects.'], shouldNot: ['Fix a failing Django migration command.'],
+  }),
+  reviewer({
+    name: 'java-reviewer', label: 'Java and Spring', skills: ['java', 'spring-boot'], not: 'Android/Kotlin review or generic build repair',
+    probes: ['Nullability and Optional contracts across public boundaries.', 'Equality, hashing, mutability, and collection aliasing.', 'Spring proxy boundaries: transactions, self-invocation, scopes, and configuration binding.', 'Thread ownership, blocking work, interruption, and resource closure.'],
+    should: ['Review a Spring transaction change.'], shouldNot: ['Repair a Gradle dependency resolution failure.'],
+  }),
+  reviewer({
+    name: 'kotlin-reviewer', label: 'Kotlin Android', skills: ['kotlin-android'], not: 'Java server review or Gradle repair',
+    probes: ['Coroutine scope ownership, cancellation, dispatcher choice, and exception propagation.', 'Lifecycle collection, recomposition stability, and state restoration.', 'Nullable/platform types and sealed-state exhaustiveness.', 'Context/activity retention and Android resource lifetime.'],
+    should: ['Review a coroutine-driven Android screen.'], shouldNot: ['Resolve an Android Gradle Plugin mismatch.'],
+  }),
+  reviewer({
+    name: 'flutter-reviewer', label: 'Flutter', skills: ['flutter'], not: 'native Android review or Flutter build repair',
+    probes: ['Widget identity, keys, rebuild scope, and stale BuildContext use.', 'Controller, subscription, isolate, and animation disposal.', 'Async mounted checks and state changes after teardown.', 'Platform-channel contracts and divergent iOS/Android behavior.'],
+    should: ['Review a Flutter widget state diff.'], shouldNot: ['Fix a CocoaPods build failure.'],
+  }),
+  reviewer({
+    name: 'react-reviewer', label: 'React and Next.js', skills: ['react', 'nextjs'], not: 'Vue review or frontend build repair',
+    probes: ['Render purity, hook dependency identity, stale closures, and effect cleanup.', 'Server/client boundaries, serialization, caching, and request-scoped data.', 'Concurrent rendering races, transitions, hydration, and optimistic rollback.', 'Keys, controlled state, accessibility semantics, and error/loading states.'],
+    should: ['Review a Next.js server/client boundary.'], shouldNot: ['Repair a webpack or Turbopack build.'],
+  }),
+  reviewer({
+    name: 'rust-reviewer', label: 'Rust', skills: ['rust'], not: 'C++ review or Cargo build repair',
+    probes: ['Ownership workarounds that hide lifetime or aliasing defects.', 'Unsafe blocks: stated invariant, pointer provenance, layout, and synchronization.', 'Error propagation, panic reachability, and poisoned/shared state.', 'Async cancellation, Send/Sync assumptions, locks across await, and task lifetime.'],
+    should: ['Review an unsafe Rust boundary.'], shouldNot: ['Fix a Cargo feature conflict.'],
+  }),
+  reviewer({
+    name: 'swift-reviewer', label: 'Swift iOS', skills: ['swift-ios'], not: 'Kotlin review or Xcode build repair',
+    probes: ['Actor isolation, Sendable claims, cancellation, and main-thread ownership.', 'Reference cycles, escaping closures, and resource lifetime.', 'Value/reference semantics, copy-on-write, and mutation through shared state.', 'View identity, navigation state, persistence, and platform availability.'],
+    should: ['Review Swift concurrency changes in an iOS app.'], shouldNot: ['Resolve a signing or linker failure.'],
+  }),
+  reviewer({
+    name: 'go-reviewer', label: 'Go', skills: ['go'], not: 'generic service review or Go build repair',
+    probes: ['Goroutine lifetime, cancellation ownership, channel closure, and races.', 'Error wrapping and identity where callers use errors.Is or errors.As.', 'Interface nil values, slice/map aliasing, loop capture, and deferred cleanup lifetime.', 'API and doc-comment contracts, zero values, receiver choice, and lock copying.'],
+    should: ['Review Go concurrency and error handling.'], shouldNot: ['Repair a missing Go module or compile error.'],
+  }),
+  reviewer({
+    name: 'cpp-reviewer', label: 'C++', skills: ['cpp'], not: 'Rust review or compiler/linker repair',
+    probes: ['Ownership expressed through RAII and any raw pointer whose lifetime is unstated.', 'Dangling views/references, moved-from values, invalidation, and destructor behavior.', 'Bounds, narrowing, signedness, undefined behavior, and exception guarantees.', 'Synchronization, data races, virtual destruction, and unsafe casts.'],
+    should: ['Review a C++ ownership or lifetime diff.'], shouldNot: ['Resolve a CMake or linker failure.'],
+  }),
+  reviewer({
+    name: 'vue-reviewer', label: 'Vue and Nuxt', skills: ['vue-nuxt'], not: 'React review or Vue build repair',
+    probes: ['Reactive identity, destructuring, watcher cleanup, and computed side effects.', 'SSR/client divergence, hydration, route middleware, and request-scoped state.', 'Composable lifetime, provide/inject contracts, and error/loading states.', 'Template keys, accessibility semantics, and unsafe rendered content.'],
+    should: ['Review a Nuxt SSR and hydration diff.'], shouldNot: ['Fix a Vite build.'],
+  }),
+  reviewer({
+    name: 'csharp-reviewer', label: 'C# and .NET', skills: ['csharp-dotnet'], not: 'Java review or dotnet build repair',
+    probes: ['Async cancellation, sync-over-async, disposal, and scoped service lifetime.', 'Nullable annotations versus runtime validation and serializer behavior.', 'LINQ query translation, repeated enumeration, tracking, and transaction scope.', 'Records/equality, mutable shared state, authorization, and configuration binding.'],
+    should: ['Review an ASP.NET or EF Core change.'], shouldNot: ['Repair a NuGet restore failure.'],
+  }),
+  reviewer({
+    name: 'php-reviewer', label: 'PHP and Laravel', skills: ['laravel', 'php'], not: 'Django review or Composer/build repair',
+    probes: ['Request validation, mass assignment, policy scope, and tenant isolation.', 'Eloquent loading, query count, transactions, and queued work after commit.', 'PHP type coercion, nullable boundaries, array shape assumptions, and error conversion.', 'Migration deploy ordering, cache/config behavior, and serialization.'],
+    should: ['Review Laravel authorization and ORM code.'], shouldNot: ['Resolve a Composer dependency error.'],
+  }),
+  reviewer({
+    name: 'typescript-reviewer', label: 'TypeScript', skills: ['typescript'], not: 'framework-specific UI review or TypeScript build repair',
+    probes: ['Runtime validation at boundaries where static types disappear.', 'Unsound assertions, any/unknown narrowing, variance, and optional-property semantics.', 'Promise ownership, rejection paths, cancellation, and event-listener cleanup.', 'Module/export contracts and type/value divergence across build targets.'],
+    should: ['Review a TypeScript library API diff.'], shouldNot: ['Fix tsconfig or bundler errors.'],
+  }),
+  reviewer({
+    name: 'fastapi-reviewer', label: 'FastAPI', skills: ['fastapi'], not: 'generic Python review or environment repair',
+    probes: ['Dependency lifetime and cleanup, override leakage, and request-scoped state.', 'Async blocking, cancellation, background task ownership, and exception mapping.', 'Pydantic input/output boundaries, partial updates, and response data exposure.', 'Authorization per resource, transaction completion, and OpenAPI contract drift.'],
+    should: ['Review a FastAPI endpoint and dependency change.'], shouldNot: ['Repair a Python package installation.'],
+  }),
+  reviewer({
+    name: 'python-reviewer', label: 'Python', skills: ['python'], not: 'FastAPI/Django-specific review or environment repair',
+    probes: ['Async tasks that are never awaited, cancellation loss, and TaskGroup failure propagation.', 'Mutable defaults, late binding, descriptor/protocol behavior, and truthiness edge cases.', 'Context-manager and iterator cleanup, exception chaining, and generator finalization.', 'Shared mutable state, import-time effects, typing/runtime gaps, and process/thread boundaries.'],
+    should: ['Review Python language and asyncio correctness.'], shouldNot: ['Review Django ORM behavior.'],
+  }),
+  reviewer({
+    name: 'postgres-reviewer', label: 'PostgreSQL', skills: ['postgresdb'], not: 'application ORM review or migration execution',
+    probes: ['Lock strength/order, long transactions, deadlocks, and concurrent DDL behavior.', 'Index/operator compatibility, selectivity, null semantics, and query-plan regressions.', 'RLS policy coverage, SECURITY DEFINER/search_path, grants, and tenant isolation.', 'Migration reversibility, constraint validation, backfill batching, and replication effects.'],
+    should: ['Review a PostgreSQL migration and policy diff.'], shouldNot: ['Run or repair application migrations.'],
+  }),
+  reviewer({
+    name: 'rag-reviewer', label: 'RAG', skills: ['rag'], not: 'general ML training review or retrieval implementation',
+    probes: ['Evaluation set leakage, temporal leakage, and mismatch between offline and live queries.', 'Chunk/metadata identity, permission filtering before retrieval, and deletion propagation.', 'Recall/rerank trade-offs, empty retrieval, citation grounding, and abstention.', 'Embedding/model/index version compatibility and rollback behavior.'],
+    should: ['Review a retrieval pipeline for leakage and grounding.'], shouldNot: ['Tune a neural training loop.'],
+  }),
+  reviewer({
+    name: 'mle-reviewer', label: 'production ML', skills: ['machine-learning'], not: 'notebook style review or model training implementation', tier: 'heavy',
+    probes: ['Temporal/entity leakage in splits and features available only after prediction time.', 'Training-serving schema skew, data contracts, null/category drift, and feature ownership.', 'Promotion gates that fail open, canary comparability, monitoring delay, and rollback without retraining.', 'Reproducible artifacts: data/code/model lineage, seeds, environment, and deterministic evaluation.'],
+    should: ['Review an ML promotion and rollback pipeline.'], shouldNot: ['Implement or tune the model.'],
+  }),
+];
+
+const RESOLVERS = [
+  resolver({ name: 'django-build-resolver', label: 'Django', skills: ['django'], not: 'ORM performance review or feature refactoring', signals: ['Migration graph conflicts versus unapplied migrations.', 'Settings/import errors versus database connectivity.', 'Static collection/template failures versus application tests.'], should: ['Fix a failing Django migrate/check command.'], shouldNot: ['Review an ORM diff for N+1 queries.'] }),
+  resolver({ name: 'java-build-resolver', label: 'Java and Spring', skills: ['java', 'spring-boot'], not: 'code review or broad dependency upgrades', signals: ['Compiler diagnostics versus annotation/generated-source failures.', 'Maven/Gradle resolution versus toolchain/JDK mismatch.', 'Spring context/bootstrap failures versus test assertion failures.'], should: ['Fix a Gradle/Maven/Spring build failure.'], shouldNot: ['Review transaction correctness.'] }),
+  resolver({ name: 'kotlin-build-resolver', label: 'Kotlin Android', skills: ['kotlin-android'], not: 'UI/coroutine review or project modernization', signals: ['Kotlin/AGP/Gradle/JDK compatibility.', 'KSP/KAPT/generated source failures.', 'Manifest/resource merge versus compiler diagnostics.'], should: ['Repair an Android Gradle build.'], shouldNot: ['Review Compose state.'] }),
+  resolver({ name: 'flutter-build-resolver', label: 'Flutter', skills: ['flutter'], not: 'widget review or package modernization', signals: ['Dart analyzer/compile errors versus generated-code drift.', 'CocoaPods/Xcode signing versus Android Gradle failures.', 'Plugin platform constraints versus app code failures.'], should: ['Repair a Flutter build failure.'], shouldNot: ['Review widget lifecycle.'] }),
+  resolver({ name: 'react-build-resolver', label: 'React and Next.js', skills: ['react', 'nextjs'], not: 'UI review or broad package upgrades', signals: ['Type/lint failure versus bundler/module resolution.', 'Server/client boundary or static rendering diagnostics.', 'Environment/config presence versus application logic.'], should: ['Repair a Next.js or React production build.'], shouldNot: ['Review hydration correctness.'] }),
+  resolver({ name: 'rust-build-resolver', label: 'Rust', skills: ['rust'], not: 'unsafe-code review or dependency modernization', signals: ['Borrow/type diagnostics versus feature unification.', 'Build-script/native library/linker failures.', 'Toolchain/edition mismatch versus source error.'], should: ['Repair a Cargo build failure.'], shouldNot: ['Review unsafe invariants.'] }),
+  resolver({ name: 'swift-build-resolver', label: 'Swift iOS', skills: ['swift-ios'], not: 'concurrency review or signing-policy changes', signals: ['Swift compiler/generic diagnostics versus package resolution.', 'Linker/module map/generated interface failure.', 'Simulator/device availability versus signing/provisioning.'], should: ['Repair an Xcode or SwiftPM build.'], shouldNot: ['Review actor isolation.'] }),
+  resolver({ name: 'go-build-resolver', label: 'Go', skills: ['go'], not: 'concurrency review or module-wide upgrades', signals: ['Compiler/type error versus generated code drift.', 'Module/version/sum failure versus private module credentials.', 'CGO/toolchain/linker failure versus test failure.'], should: ['Repair a go build failure.'], shouldNot: ['Review goroutine lifetime.'] }),
+  resolver({ name: 'cpp-build-resolver', label: 'C++', skills: ['cpp'], not: 'ownership review or build-system modernization', signals: ['Compiler diagnostic versus template instantiation cause.', 'CMake/configuration/generator failure versus source failure.', 'Undefined reference/ABI/library order versus runtime test failure.'], should: ['Repair a CMake/compiler/linker failure.'], shouldNot: ['Review C++ lifetime safety.'] }),
+  resolver({ name: 'pytorch-build-resolver', label: 'PyTorch', skills: ['machine-learning'], not: 'model-quality review or training redesign', signals: ['Python package/import mismatch versus compiled extension ABI.', 'CUDA/driver/toolkit/architecture incompatibility.', 'Distributed launcher/environment failure versus model code failure.'], should: ['Repair a PyTorch environment or extension build.'], shouldNot: ['Review data leakage or model promotion.'] }),
+];
+
+const SPEC_MINER = {
+  name: 'spec-miner',
+  role: 'spec-miner',
+  tier: 'heavy',
+  tools: ['read', 'search', 'edit'],
+  skills: [],
+  desc: 'Brownfield spec miner: extracts an anchored SDD draft from existing code under a bounded read budget. NOT feature planning or overwriting an approved spec.',
+  routing: {
+    should: ['Extract an initial SDD spec from an existing repository with no specs.'],
+    shouldNot: ['Design a new feature or amend an approved spec in place.'],
+  },
+  body: `You are the brownfield spec miner. Produce an **extracted draft**, never a claim that undocumented intent is approved.
+
+Read at most 40 files or 20,000 lines. Start from entry points, public interfaces, tests, schemas, migrations, configuration, and user-facing documentation. For every inferred invariant, cite a stable repository anchor (symbol plus path; line only as a convenience). Separate observed behavior, inferred requirement, contradiction, and unknown.
+
+Write a new SDD-shaped draft with problem, users, observable behavior, invariants, non-goals, acceptance criteria, source anchors, and open points. Mark status extracted-draft. If the intended slug already has an approved spec, do not edit it: propose a new slug or a revision artifact. Do not plan implementation or invent product intent absent from evidence.
+
+Return the read budget used, artifacts inspected, confidence per requirement, and the draft path.`,
+};
+
+const STACK_AGENTS = Object.freeze([...REVIEWERS, ...RESOLVERS, SPEC_MINER]);
+
+export const STACK_AGENT_BY_SKILL = Object.freeze(Object.fromEntries(
+  ['django', 'java', 'spring-boot', 'kotlin-android', 'flutter', 'react', 'nextjs', 'rust', 'swift-ios', 'go', 'cpp', 'vue-nuxt', 'csharp-dotnet', 'laravel', 'php', 'typescript', 'fastapi', 'python', 'postgresdb', 'rag', 'machine-learning']
+    .map((skill) => [skill, STACK_AGENTS.filter((agent) => agent.skills.includes(skill)).map((agent) => agent.name)]),
+));
+
+export const stackAgents = () => STACK_AGENTS.map((agent) => ({ ...agent, tools: [...agent.tools], skills: [...agent.skills], routing: { should: [...agent.routing.should], shouldNot: [...agent.routing.shouldNot] } }));
+export const stackAgentNames = () => STACK_AGENTS.map((agent) => agent.name);
+export const stackAgentByName = (name) => STACK_AGENTS.find((agent) => agent.name === name);
+
+export function resolveStackAgentNames(skillIds = [], explicitAgentIds = []) {
+  const names = new Set();
+  for (const skill of skillIds) for (const name of STACK_AGENT_BY_SKILL[skill] || []) names.add(name);
+  for (const name of explicitAgentIds) if (stackAgentByName(name)) names.add(name);
+  return [...names].sort();
+}
+
+export function validateAgentCatalog(definitions = STACK_AGENTS) {
+  const errors = [];
+  const seen = new Set();
+  const allowedRoles = new Set(['reviewer', 'build-resolver', 'spec-miner']);
+  for (const agent of definitions) {
+    const prefix = agent?.name || '<unnamed>';
+    if (!agent?.name || seen.has(agent.name)) errors.push(`${prefix}: unique name required`);
+    seen.add(agent?.name);
+    if (!agent?.desc?.includes('NOT ')) errors.push(`${prefix}: description requires a NOT boundary`);
+    if (!allowedRoles.has(agent?.role)) errors.push(`${prefix}: invalid role`);
+    if (!['balanced', 'heavy'].includes(agent?.tier)) errors.push(`${prefix}: tier must be balanced or heavy`);
+    if (!agent?.routing?.should?.length || !agent?.routing?.shouldNot?.length) errors.push(`${prefix}: routing cases required`);
+    if (Buffer.byteLength(agent?.body || '', 'utf8') > 6500) errors.push(`${prefix}: body exceeds 6500 bytes`);
+    if (/everything[- ]claude|affaan|worldflow|\.claude\/plugins\/ecc/iu.test(`${agent?.desc || ''}\n${agent?.body || ''}`)) errors.push(`${prefix}: foreign project vocabulary`);
+    if (agent?.role === 'reviewer' && JSON.stringify(agent.tools) !== JSON.stringify(REVIEW_TOOLS)) errors.push(`${prefix}: reviewer tools must be read-only`);
+    if (agent?.role === 'build-resolver' && JSON.stringify(agent.tools) !== JSON.stringify(RESOLVER_TOOLS)) errors.push(`${prefix}: resolver tools must be bounded`);
+  }
+  return errors;
+}

package/targets/agent-sources.json

@@ -0,0 +1,48 @@
+[
+  {
+    "agent": "go-reviewer",
+    "researchedAt": "2026-09-02",
+    "sources": [
+      {
+        "url": "https://go.dev/wiki/CodeReviewComments",
+        "coverage": ["error identity and wrapping", "goroutine lifetime", "interface values", "receiver and API review"]
+      },
+      {
+        "url": "https://go.dev/doc/comment",
+        "coverage": ["public API comments", "package and symbol contracts"]
+      },
+      {
+        "url": "https://go.dev/doc/contribute",
+        "coverage": ["review evidence and change scope"]
+      }
+    ]
+  },
+  {
+    "agent": "cpp-reviewer",
+    "researchedAt": "2026-09-02",
+    "sources": [
+      {
+        "url": "https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines.html",
+        "coverage": ["RAII and ownership", "lifetime and bounds safety", "concurrency", "exception guarantees"]
+      }
+    ]
+  },
+  {
+    "agent": "python-reviewer",
+    "researchedAt": "2026-09-02",
+    "sources": [
+      {
+        "url": "https://docs.python.org/3.14/library/asyncio-dev.html",
+        "coverage": ["un-awaited coroutines", "blocking async code", "thread boundaries"]
+      },
+      {
+        "url": "https://docs.python.org/3.14/library/asyncio-task.html",
+        "coverage": ["TaskGroup failure propagation", "cancellation", "task lifetime"]
+      },
+      {
+        "url": "https://docs.python.org/3.14/reference/datamodel.html",
+        "coverage": ["descriptors and protocols", "object and iterator lifetime"]
+      }
+    ]
+  }
+]