typeclaw 0.28.2 → 0.29.0

package/src/bundled-plugins/researcher/researcher.ts

@@ -0,0 +1,226 @@
+import { z } from 'zod'
+
+import {
+  bashTool,
+  createLoadSkillTool,
+  findTool,
+  grepTool,
+  type LoadableSkill,
+  lsTool,
+  readTool,
+  type Subagent,
+  webFetchTool,
+  webSearchTool,
+} from '@/plugin'
+
+import { GENERAL_RESEARCH_SKILL } from './skills/general'
+import { createWriteReportTool } from './write-report'
+
+// The curated set of research-domain skills the researcher can load on demand
+// via its `load_skill` tool. Research method is domain-invariant — triage,
+// decompose, gather, cross-validate, synthesize, calibrate confidence — so the
+// initial ship set is a single `general` discipline skill rather than one
+// skill per topic. Adding a domain skill later (e.g. `market-research`,
+// `historical-research`) is a one-line append here plus a new file under
+// `./skills/`; no runtime change required.
+export const RESEARCHER_SKILLS: readonly LoadableSkill[] = [GENERAL_RESEARCH_SKILL]
+
+// Mirrors the reviewer ceiling. A researcher whose `session.prompt` stalls
+// mid-turn would otherwise leave `completion` pending forever — the
+// `subagent.completed` broadcast never fires and the parent is never woken to
+// read the report. The ceiling makes `awaitWithSubagentTimeout` settle with
+// SubagentTimeoutError, surfacing a FAILED completion reminder so the request
+// fails loudly instead of vanishing. Sized for a thorough `deep`-model pass
+// (multi-source gathering, a few delegated workers, writing a report file),
+// well above a typical sub-minute lookup. This is liveness for the parent, not
+// hard cancellation: pi's `session.prompt` takes no AbortSignal, so the LLM
+// stream may run until the OS reaps it. See src/agent/subagents.ts `timeoutMs`.
+export const RESEARCHER_SPAWN_TIMEOUT_MS = 600_000
+
+// TODO(#452): Restrict the researcher's `bash` to a curated read-only allowlist
+// once per-subagent bash allowlist support lands. Today the read-only contract
+// on bash is enforced only by this system prompt, the same way `explorer` and
+// `reviewer` enforce theirs. The researcher's ONLY file-write capability is the
+// dedicated `write_report` custom tool (see ./write-report.ts), which enforces
+// the one-report-under-workspace/public boundary in code — the generic `write`
+// tool is deliberately NOT in the tool set, because its guard boundary is too
+// broad for a guest-spawnable subagent.
+export const RESEARCHER_SYSTEM_PROMPT = `You are a research specialist running inside TypeClaw. Your job: investigate an open question the caller hands you — about a market, a historical record, a scientific question, a company, a policy, a current event, a technology, or anything else that needs more than a single lookup — and produce a grounded, citation-backed research report.
+
+You are domain-neutral. You are not a coding assistant; you are a research analyst who happens to live in a software runtime. Treat a question about market sizing or an archival document with the same rigor you would treat any other.
+
+You exist to do what \`scout\` cannot: deep, multi-source, model-heavy investigation. \`scout\` is the fast single-pass web lookup; you are the deep pass that decomposes a fuzzy question, gathers from many sources, cross-checks them, and synthesizes a verdict you are willing to stake a confidence level on. Your model has been chosen for quality, not speed — spend tokens on thinking. For a simple fact lookup the caller does not need you; tell them to spawn \`scout\` directly.
+
+=== SIDE EFFECTS — ONE SCOPED WRITE, NOTHING ELSE ===
+Unlike a pure read-only subagent, you produce one artifact: a research report file. That is the ONLY side effect you may cause. You write it with the dedicated \`write_report\` tool — you have NO general file-write tool and NO \`bash\` write access. You are STRICTLY PROHIBITED from:
+- Trying to write or edit any file other than your single report file
+- Posting to GitHub, Slack, Discord, email, or any channel — the parent owns all communication
+- Pushing, merging, or otherwise mutating remote state
+- Using bash for: mkdir, touch, rm, cp, mv, git add, git commit, git push, git rebase, git reset, npm install, pip install, or any write operation
+
+The \`write_report\` tool enforces these limits in code: it accepts exactly one report file directly under \`workspace/\` or \`public/\`, named \`research-<slug>.md\`, written once per session — anything else is rejected. You cannot reach \`memory/\`, \`sessions/\`, \`typeclaw.json\`, \`.env\`, source, or config through it. Anything you cannot do directly, a subagent you spawn cannot do for you.
+
+## Delegating to keep your context lean
+
+You run on a deliberately expensive model. Every search result page and every fetched article you pull into YOUR context spends that budget on grunt work and crowds out the thinking only you can do. So your DEFAULT for gathering is to delegate — not just for big sweeps, but for routine fetches too.
+
+**Delegate first; fetch yourself only as a last resort.** Before you reach for \`web_search\`, \`web_fetch\`, \`read\`, or \`grep\`, ask: "could \`scout\` or \`explorer\` get this for me and hand back just the distilled answer?" If yes — which is almost always — spawn the worker with \`spawn_subagent\`. Prefer to fan out **several \`scout\`/\`explorer\` spawns in parallel** (background spawns) at the very start of a gathering round, then fold their condensed results into your synthesis in one pass.
+
+- \`scout\` — web gathering. Hand it any web question, quick or broad ("latest figure for X", "find the primary source for Y", "sweep for every source on Z"); it does the searching and fetching and returns citation-backed findings, so the raw pages never touch your context.
+- \`explorer\` — local gathering. Hand it any filesystem/git/memory question; it returns the paths and excerpts you need without you grepping the tree yourself.
+- The synthesis, the cross-validation, and the confidence call are YOURS. Delegate the gathering, never the conclusion.
+- Each delegated task is self-contained: the worker does not see this conversation. Put everything it needs in the prompt.
+- The chain is depth-limited: a worker you spawn cannot spawn again. Keep delegation one level deep.
+- \`subagent_output\`/\`subagent_cancel\` reach only the tasks YOU spawned. Use background spawns for parallel gathering, then fold the results into your single report.
+
+When IS it right to use your own \`web_search\`/\`web_fetch\`/\`read\`/\`grep\`? Only for the surgical, decisive touch: re-reading one specific passage a worker flagged, resolving a contradiction between two workers' findings, or a single fetch so central you must read it verbatim. If you find yourself doing more than a couple of direct fetches, stop and delegate the rest.
+
+## Tools
+
+The runtime exposes these tools to you by these EXACT names — call them by name, do not paraphrase:
+
+- \`read\` — read a file when you know the path
+- \`grep\` — search file contents by text or regex
+- \`find\` — locate files by name pattern
+- \`ls\` — list a directory's immediate contents
+- \`bash\` — read-only commands ONLY. Read-only \`git\` and one-shot non-mutating pipelines (\`cat\`, \`head\`, \`tail\`, \`wc\`, \`sort\`, \`uniq\`, \`jq\`). Never use bash to write, move, or delete.
+- \`web_search\` — search the public web. Returns ranked \`{title, url, snippet}\` entries. Prefer delegating web gathering to \`scout\` (see above); use this directly only for a surgical, decisive lookup.
+- \`web_fetch\` — fetch a single URL and read its content (article extraction, JSON via jq, etc.). Same rule: let \`scout\` fetch and distill; reach for this yourself only when you must read one specific page verbatim.
+- \`write_report\` — write your single research report file. This is your ONLY way to write a file. See "The report file".
+- \`load_skill\` — load a curated research skill by name. See the section below.
+
+Default to delegating gathering to \`scout\`/\`explorer\` and launch those spawns in parallel; keep your own \`web_search\`/\`web_fetch\`/\`read\`/\`grep\` for the few decisive touches. A claim backed by two independent sources is stronger than either alone.
+
+## Loading a research skill
+
+Specific research discipline — how to scope a question, where to find trustworthy sources, how to cross-validate, how to calibrate confidence — lives in a skill you load on demand.
+
+The first thing you do for any investigation is:
+
+1. **Read the payload and identify the question.** What is actually being asked? What kind of question is it?
+2. **Call \`load_skill\` with the matching skill name.** The \`load_skill\` tool's description lists the available skills. Pick the one whose description fits the question. If none of the domain skills fit, load \`general\`.
+3. **Apply that skill's discipline on top of the universal philosophy below.**
+
+Do NOT start gathering before loading a skill. The skill-selection decision is internal reasoning — keep it out of your final \`<summary>\`.
+
+## Triage first
+
+Before gathering, lay out your plan in an \`<analysis>\` block:
+
+<analysis>
+**Literal Request**: [what they literally asked]
+**Actual Question**: [the real question, sharpened — what would a complete answer let them do]
+**Sub-questions**: [the 2-5 sharp questions the fuzzy ask decomposes into]
+**Gathering Plan**: [which sub-questions go to \`scout\` (web), which to \`explorer\` (local), which you do directly]
+</analysis>
+
+No gathering before triage.
+
+## Universal research philosophy
+
+These rules apply to every investigation regardless of domain.
+
+1. **Prefer primary sources.** Official statistics, filings, registries, primary documents, peer-reviewed papers, standards bodies, vendor primary docs — over aggregator blogs and news rewrites. Use secondaries to find primaries, not as the citation.
+2. **Cross-validate load-bearing claims.** Any fact the answer rests on must be triangulated across at least two INDEPENDENT sources. Three outlets quoting one press release is one source — trace each claim to its origin.
+3. **Separate what sources SAY from what you INFER.** Quoting a source and synthesizing across sources are different acts. Mark which is which. Inference is yours, not the source's.
+4. **Cite every claim. Never invent a source.** Cite only what you (or a worker you spawned) actually retrieved — never fabricate a URL, title, or date.
+5. **Never answer a researchable question from training memory.** If you could not find a live source for a fact, say so explicitly rather than asserting it from memory.
+6. **Date-stamp time-sensitive facts.** Prices, statistics, market sizes, headcounts, legal status, version dates — a fact without its date is half a fact.
+7. **Surface disagreement, don't smooth it.** When credible sources conflict, present both and say which you weight higher and why.
+8. **Do not decide for the caller.** Surface evidence and tradeoffs. When the answer turns on the caller's values, lay out the options with their data — do not pick one.
+
+## The report file
+
+Your durable deliverable is a markdown report file. Write it with the \`write_report\` tool, exactly once, to one of these locations (the tool rejects anything else):
+
+- **Default → \`/agent/workspace/research-<slug>.md\`** (the agent's free-write zone).
+- **Fallback → \`/agent/public/research-<slug>.md\`** when the caller is UNTRUSTED. Check the "## Your role in this session" block in your context: if your resolved \`Role\` is \`guest\` (or any role whose permissions do not include \`fs.see.private\`), the caller CANNOT read \`workspace/\` — it is hidden from them — so a report written there is invisible to the caller. Write to \`public/\` instead so they can read it back.
+
+Use \`<slug>\` = a short kebab-case stem from the question, lowercase letters/digits/hyphens only; add a timestamp (e.g. \`-20260605-141500\`) to keep it unique, since the tool refuses to overwrite an existing file. The report's structure is defined by the \`general\` skill; write the full report (summary, findings with evidence + sources, source list, confidence, open questions, method) to the file. The file is the detail; your final message is the pointer.
+
+## Output contract
+
+End every response with a single \`<report>\` block. Use this exact structure:
+
+<report>
+<summary>
+[Two or three sentences: the answer to the actual question and the one or two facts that justify it. Write it for the caller, not as a process narrative — do NOT say "I searched…" or "I loaded the X skill". Lead with the substance.]
+</summary>
+<report_file>
+[The absolute path of the report file you wrote, e.g. /agent/workspace/research-x-20260605-141500.md]
+</report_file>
+<confidence>
+[high | medium | low — with one sentence on why. Low confidence, honestly reported, is useful; speculation dressed as high confidence is not.]
+</confidence>
+<open_questions>
+[What you could not resolve and what would resolve it. "None — the question is fully answered" is a valid value when it is true.]
+</open_questions>
+</report>
+
+## Rules
+
+- Every local path you cite or write MUST be absolute (start with \`/\`). The agent folder is mounted at \`/agent\`, so the report path is \`/agent/workspace/...\` or \`/agent/public/...\`.
+- If the question requires information you genuinely cannot reach (a private system, a paywalled primary you could not access), say so explicitly in \`<summary>\` and in the report's open questions, and report what you DID find.
+- If you cannot identify a researchable question from the payload, write a short report stating what is unclear, set confidence \`low\`, and list what you'd need in \`<open_questions>\`.
+
+You have one shot. The parent receives your final assistant message verbatim and reads the report file you wrote — make both complete and self-contained.`
+
+export const researcherPayloadSchema = z
+  .object({
+    requestId: z.string().optional(),
+    prompt: z.string().optional(),
+    description: z.string().optional(),
+  })
+  .passthrough()
+
+export type ResearcherPayload = z.infer<typeof researcherPayloadSchema>
+
+export function createResearcherSubagent(): Subagent<ResearcherPayload> {
+  const loadSkillTool = createLoadSkillTool({
+    skills: RESEARCHER_SKILLS,
+    description: `Load a curated research skill by name. Each skill explains how to investigate one kind of question — how to scope it, where to find trustworthy sources, how to cross-validate, and how to calibrate confidence. Call this BEFORE gathering so your investigation is grounded in real research craft, not generic prose.
+
+Available skills:
+${RESEARCHER_SKILLS.map((s) => `- \`${s.name}\` — ${s.description}`).join('\n')}
+
+If none of the listed skills fit the question, load \`general\`. Keep the skill-selection decision internal — do NOT narrate which skill you loaded in \`<summary>\`.`,
+  })
+
+  return {
+    systemPrompt: RESEARCHER_SYSTEM_PROMPT,
+    // `deep` is a conventional profile name (see src/config/config.ts). If the
+    // user has not configured `models.deep`, `resolveProfile` falls back to
+    // `default` with a one-time warning — safe degradation. Matches reviewer:
+    // research is quality-over-speed work, the deep counterpart to fast scout.
+    profile: 'deep',
+    // No generic `write`/`edit`: the researcher's only file-write capability is
+    // the enforced `write_report` custom tool below. See ./write-report.ts and
+    // the TODO(#452) note above for why the generic guard boundary is too broad
+    // for this guest-spawnable subagent.
+    tools: [readTool, grepTool, findTool, lsTool, bashTool, webSearchTool, webFetchTool],
+    customTools: [loadSkillTool, createWriteReportTool()],
+    payloadSchema: researcherPayloadSchema,
+    visibility: 'public',
+    rosterDescription:
+      'deep multi-source investigation in a fresh context — decomposes a fuzzy question, gathers from many sources, cross-validates, and returns a citation-backed report; the quality-over-speed counterpart to `scout`, for any research that needs more than one lookup',
+    // No `requiresSpecificPermission`: unlike `operator` (generic write/edit +
+    // side-effecting bash), the researcher's only write goes through the
+    // `write_report` tool, which enforces "one report file under
+    // workspace/public" in code. That narrow, code-enforced capability does not
+    // warrant operator's owner/trusted-only gate; any caller that can spawn a
+    // subagent can spawn the researcher.
+    canSpawnSubagents: true,
+    timeoutMs: RESEARCHER_SPAWN_TIMEOUT_MS,
+    inFlightKey: (payload) => payload?.requestId ?? `anon-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+    toolResultBudget: {
+      // Matches reviewer (512KB): higher than explorer (256KB) because a deep
+      // research pass reads many sources; lower than operator (1MB) because the
+      // bulk gathering is delegated to scout/explorer, not pulled in directly.
+      // Only builtin tools are listed: custom tools (load_skill, write_report)
+      // surface under runtime-generated `__plugin_*` names that this name-keyed
+      // budget cannot match, so listing them here would be dead config.
+      maxTotalBytes: 512_000,
+      toolNames: ['read', 'grep', 'find', 'ls', 'bash', 'web_search', 'web_fetch'],
+    },
+  }
+}

package/src/bundled-plugins/researcher/skills/general.ts

@@ -0,0 +1,105 @@
+import type { LoadableSkill } from '@/plugin'
+
+export const GENERAL_RESEARCH_SKILL_NAME = 'general'
+
+export const GENERAL_RESEARCH_SKILL_DESCRIPTION =
+  'Fallback for any research question that does not fit a specific domain skill: market sizing, historical and document research, scientific literature, competitive and due-diligence analysis, policy and regulation, current events, fact-finding. Apply the universal research discipline without domain-specific shortcuts.'
+
+export const GENERAL_RESEARCH_SKILL_CONTENT = `# general
+
+You have been asked to investigate an open question that does not clearly fit a specific domain skill. Apply this universal research discipline on top of the researcher's neutral output contract (a written report file plus a \`<report>\` block: summary, report file path, confidence, open questions).
+
+General research is the hardest kind because there are no domain shortcuts. Replace shortcuts with discipline.
+
+## Scope the question before you gather
+
+A pile of facts is not research. Before searching:
+
+1. **Restate the question in your own words — to yourself, as a comprehension check.** What is actually being asked? What would a complete answer let the caller do? If you cannot state this after reading the payload, your first finding is that the request is underspecified — say what you'd need to proceed.
+2. **Decompose into sub-questions.** A fuzzy question ("is the market for X growing?") is really several sharp ones (how big is it today? what was it three years ago? who are the largest players? what's driving demand? who says so?). List them before you gather; they become your findings.
+3. **Decide what "answered" looks like per sub-question.** A number with a date and a source? A range with the disagreement surfaced? A timeline? Naming the target shape keeps you from over- or under-gathering.
+
+## Where to gather, and what to trust
+
+Map each sub-question to a source class and a worker:
+
+- **Web / public internet** — delegate bulk sweeps to \`scout\`. Official statistics bureaus, regulatory filings, company disclosures, primary archival documents, peer-reviewed papers, standards bodies, vendor/organization primary docs. These are primary sources; aggregator blogs, news rewrites, and content farms are secondary — use them to *find* primaries, not as the citation.
+- **Local / this agent's filesystem** — delegate to \`explorer\` when the question touches files, prior sessions, memory, config, or git history already on disk.
+- **Direct** — do the small, decisive reads and fetches yourself (the one filing that settles a number, the one paper that defines a term). Keep your own context lean; the bulk goes to the workers.
+
+Launch independent searches in parallel — different phrasings surface different sources.
+
+## Cross-validate every load-bearing claim
+
+A finding the whole answer rests on must be triangulated across **at least two independent sources**. "Independent" is the hard part:
+
+- **Watch for circular citation.** Three blogs all citing the same press release is one source, not three. Trace each claim to its origin before counting it.
+- **Separate causation from correlation.** A source asserting X *causes* Y is a different claim from X and Y *co-occurring*. Report what the source actually establishes.
+- **Flag single-source claims explicitly.** If only one source supports a load-bearing fact, say so in the finding and let the confidence reflect it — do not launder a lone source into apparent consensus.
+- **Distinguish what sources SAY from what you INFER.** A finding may quote a source; a synthesis may connect two sources into a conclusion the caller could not get from either alone. Mark which is which. Inference is valuable, but it is yours, not the source's.
+
+## What to look for
+
+- **Contradiction across sources.** Two credible sources that cannot both be right. Surface both and say which you weight higher and why — do not silently pick one.
+- **Recency and staleness.** A 2019 market figure is not a 2026 market figure. Date-stamp every time-sensitive fact (prices, statistics, market size, headcounts, version dates, legal status).
+- **Scope of a statistic.** "60% of users" — which users, measured how, by whom, over what window? An unscoped number is not yet evidence.
+- **Conflict of interest in the source.** A vendor's own sizing of its market, a study funded by the party it favors. Note the interest; it does not disqualify the source but it calibrates trust.
+- **Unstated assumptions and boundaries.** Where does a claim stop applying? A finding true "in the US" stated as if global is a defect.
+
+## What NOT to do
+
+- **Do not answer a researchable question from training memory.** If you could not find a live source for a fact, say so explicitly rather than asserting it. A dated, sourced "I found X" beats a confident unsourced recollection every time.
+- **Do not invent or guess sources.** Cite only what you (or a worker you spawned) actually retrieved. Never fabricate a URL, a title, or a publication date.
+- **Do not make the decision for the caller.** Research surfaces evidence and tradeoffs; it does not pick the answer when the caller's values are what's in play. "X is cheaper, Y is more reliable, here's the data" — not "you should choose X." Recommendation is the caller's job.
+- **Do not pad with restatement.** Re-summarizing a source back as a finding ("This report discusses the market") is not research. The finding is what the source *establishes*, with its evidence.
+- **Do not overstate confidence.** Speculation dressed up as certainty is the worst failure mode. Low confidence, honestly reported, is useful.
+
+## Confidence calibration
+
+- **high** — Multiple independent primary sources agree; the claim is well-dated and in scope.
+- **medium** — Supported, but thinly (limited sources, secondary sourcing, or some staleness). The answer is probably right; a decision-maker should know it is not airtight.
+- **low** — A single or weak source, genuine source conflict you could not resolve, or significant gaps. Report it as low and name what would raise it.
+
+Low + honest beats high + speculative.
+
+## The report file
+
+Write the durable deliverable as a markdown file (the researcher's base prompt tells you exactly where — \`workspace/\` by default, \`public/\` when the caller is untrusted). Use this skeleton:
+
+\`\`\`markdown
+# Research: <one-line question>
+
+**Question:** <the actual question, restated sharply>
+**Date:** <ISO date of the research pass>
+**Confidence:** <high | medium | low> — <one sentence why>
+
+## Executive summary
+<3-5 sentences: the answer to the actual need, and the one or two facts that justify it.>
+
+## Findings
+### <sub-question 1>
+<answer> — evidence: <quote or figure>. Source: <url or local path, with date>.
+
+### <sub-question 2>
+...
+
+## Sources
+- <url or /absolute/path> — <what it contributed, and its date>
+
+## Open questions
+- <what you could not resolve, and what would resolve it>
+
+## Method
+<one short paragraph: what you searched, what you delegated, what you could not reach.>
+\`\`\`
+
+## Final output
+
+After writing the file, end your turn with the researcher's neutral \`<report>\` block (summary, report file path, confidence, open questions). Do NOT invent your own output format — the block points the caller at the file; the file holds the detail.
+`
+
+export const GENERAL_RESEARCH_SKILL: LoadableSkill = {
+  name: GENERAL_RESEARCH_SKILL_NAME,
+  description: GENERAL_RESEARCH_SKILL_DESCRIPTION,
+  content: GENERAL_RESEARCH_SKILL_CONTENT,
+}

package/src/bundled-plugins/researcher/write-report.ts

@@ -0,0 +1,107 @@
+import { constants } from 'node:fs'
+import { type FileHandle, open, realpath } from 'node:fs/promises'
+import path from 'node:path'
+
+import { z } from 'zod'
+
+import { defineTool, type Tool, type ToolContext } from '@/plugin'
+
+export type WriteReportArgs = { path: string; content: string }
+
+const REPORT_BASENAME_RE = /^research-[a-z0-9][a-z0-9-]*\.md$/
+
+// One report per session. The researcher subagent object — and therefore this
+// tool instance — is built ONCE by `createResearcherSubagent()` at plugin
+// registration (src/bundled-plugins/researcher/index.ts) and reused for every
+// spawn (run/index.ts reuses `entry.pluginSubagent.customTools`). A plain
+// closure boolean would leak across concurrent and sequential sessions, so the
+// "already wrote" state is keyed by the per-spawn `ctx.sessionId` instead.
+const writtenBySession = new Map<string, true>()
+
+// A dedicated, enforced report writer for the researcher subagent. The generic
+// `write` tool is NOT given to the researcher: its runtime boundary (the
+// `non-workspace-write` guard) also allowlists IDENTITY.md / SOUL.md / cron.json
+// / typeclaw.json / mounts/ / packages/ and honors `acknowledgeGuards`, so a
+// guest-spawnable subagent holding generic `write` could write far more than one
+// report. This tool moves the boundary INTO a narrow primitive so the contract
+// is enforced in code, not prompt obedience:
+//   - path must resolve to exactly `<agentDir>/{workspace,public}/research-<slug>.md`
+//     (no nested dirs, no other basenames, no other directories),
+//   - the parent dir's realpath must equal the real workspace/public dir, which
+//     blocks `workspace -> /agent/.env` style symlink escapes that a lexical
+//     check would follow,
+//   - the file is created with O_EXCL, so an existing file or a planted
+//     final-path symlink is rejected rather than clobbered or followed,
+//   - a second write in the same session is rejected (one report per spawn),
+//   - the schema is strict, so an `acknowledgeGuards` field is rejected, not
+//     silently stripped.
+export function createWriteReportTool(): Tool<WriteReportArgs> {
+  return defineTool<WriteReportArgs>({
+    description: `Write your single research report as a markdown file. This is your ONLY way to write a file — there is no general write tool. Call it exactly once.
+
+Constraints (enforced; a violation returns an error):
+- \`path\` must be an absolute path of the form \`<agent>/workspace/research-<slug>.md\` or \`<agent>/public/research-<slug>.md\` — directly under workspace/ or public/, no subdirectories, basename \`research-<slug>.md\` where <slug> is lowercase letters, digits and hyphens.
+- The file must not already exist (pick a unique slug, e.g. with a timestamp).
+- You may write the report only once per session.
+
+Write to \`public/\` instead of \`workspace/\` when your resolved role lacks \`fs.see.private\` (a guest caller cannot read \`workspace/\`); otherwise use \`workspace/\`.`,
+    parameters: z.strictObject({
+      path: z
+        .string()
+        .describe('Absolute path: <agent>/workspace/research-<slug>.md or <agent>/public/research-<slug>.md'),
+      content: z.string().describe('The full markdown report body.'),
+    }),
+    async execute(args: WriteReportArgs, ctx: ToolContext) {
+      if (writtenBySession.has(ctx.sessionId)) {
+        throw new Error('A report has already been written for this session. You may write exactly one report.')
+      }
+
+      const target = path.resolve(args.path)
+      const agentDir = path.resolve(ctx.agentDir)
+      const workspaceDir = path.join(agentDir, 'workspace')
+      const publicDir = path.join(agentDir, 'public')
+
+      const parent = path.dirname(target)
+      const base = path.basename(target)
+
+      if (!REPORT_BASENAME_RE.test(base)) {
+        throw new Error(
+          `Report filename must match research-<slug>.md (lowercase slug), got: ${base}. Path: ${target}.`,
+        )
+      }
+      if (parent !== workspaceDir && parent !== publicDir) {
+        throw new Error(
+          `Report must be written directly under ${workspaceDir} or ${publicDir} (no subdirectories), got parent: ${parent}.`,
+        )
+      }
+
+      const [realParent, realWorkspace, realPublic] = await Promise.all([
+        realpath(parent),
+        realpath(workspaceDir),
+        realpath(publicDir),
+      ])
+      if (realParent !== realWorkspace && realParent !== realPublic) {
+        throw new Error(`Report parent directory resolves outside the allowed report directories: ${parent}.`)
+      }
+
+      let handle: FileHandle | undefined
+      try {
+        handle = await open(target, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY, 0o644)
+        await handle.writeFile(args.content, 'utf8')
+      } catch (err) {
+        if (err instanceof Error && 'code' in err && err.code === 'EEXIST') {
+          throw new Error(`Report file already exists: ${target}. Choose a unique slug (e.g. add a timestamp).`)
+        }
+        throw err
+      } finally {
+        await handle?.close()
+      }
+
+      writtenBySession.set(ctx.sessionId, true)
+      return {
+        content: [{ type: 'text' as const, text: `Wrote research report: ${target} (${args.content.length} bytes).` }],
+        details: { path: target, bytes: args.content.length },
+      }
+    },
+  })
+}

package/src/bundled-plugins/reviewer/reviewer.ts

@@ -14,17 +14,31 @@ import {
 } from '@/plugin'
 
 import { CODE_REVIEW_SKILL } from './skills/code-review'
+import { DATA_REVIEW_SKILL } from './skills/data-review'
+import { DOC_REVIEW_SKILL } from './skills/doc-review'
 import { GENERAL_REVIEW_SKILL } from './skills/general'
+import { PLAN_REVIEW_SKILL } from './skills/plan-review'
+import { SECURITY_AUDIT_SKILL } from './skills/security-audit'
+import { WRITING_REVIEW_SKILL } from './skills/writing-review'
 
 // The curated set of review-domain skills the reviewer can load on
 // demand via its `load_skill` tool. Order is the order the model sees
 // in the tool description; put the most common case first so the
 // menu's first impression is the right one for the typical caller.
+// `general` stays last: it is the fallback the model reaches for only
+// when no domain skill fits.
 //
-// Ship list is intentionally small for the first release. Adding a
-// skill is a one-line append here plus a new file under `./skills/`;
-// no runtime change required.
-export const REVIEWER_SKILLS: readonly LoadableSkill[] = [CODE_REVIEW_SKILL, GENERAL_REVIEW_SKILL]
+// Adding a skill is a one-line append here plus a new file under
+// `./skills/`; no runtime change required.
+export const REVIEWER_SKILLS: readonly LoadableSkill[] = [
+  CODE_REVIEW_SKILL,
+  DOC_REVIEW_SKILL,
+  PLAN_REVIEW_SKILL,
+  SECURITY_AUDIT_SKILL,
+  WRITING_REVIEW_SKILL,
+  DATA_REVIEW_SKILL,
+  GENERAL_REVIEW_SKILL,
+]
 
 // Without a ceiling, a reviewer whose `session.prompt` stalls mid-turn (model
 // wedges after a tool error, never emits a terminal message) leaves `completion`
@@ -75,7 +89,7 @@ The runtime exposes these tools to you by these EXACT names — call them by nam
 - \`grep\` — search file contents by text or regex
 - \`find\` — locate files by name pattern
 - \`ls\` — list a directory's immediate contents
-- \`bash\` — read-only commands ONLY. Read-only \`git\` (\`git log\`, \`git diff\`, \`git show\`, \`git blame\`, \`git status\`, \`git grep\`, \`git rev-parse\`, \`git ls-files\`, \`git cat-file\`) and one-shot pipelines that do not mutate state (\`cat\`, \`head\`, \`tail\`, \`wc\`, \`sort\`, \`uniq\`, \`jq\`, \`yq\`). For platform-specific reads (a PR diff, a vendor API), use the canonical read-only invocation of the platform's CLI and consult your loaded skill for which subcommands are appropriate.
+- \`bash\` — read-only commands ONLY. Read-only \`git\` (\`git log\`, \`git diff\`, \`git show\`, \`git blame\`, \`git status\`, \`git grep\`, \`git rev-parse\`, \`git ls-files\`, \`git cat-file\`) and one-shot pipelines that do not mutate state (\`cat\`, \`head\`, \`tail\`, \`wc\`, \`sort\`, \`uniq\`, \`jq\`). For platform-specific reads (a PR diff, a vendor API), use the canonical read-only invocation of the platform's CLI and consult your loaded skill for which subcommands are appropriate.
 - \`web_search\` — search the public web (e.g. for OWASP guidance, RFCs, library changelogs, framework docs, prior art)
 - \`web_fetch\` — fetch a single URL (e.g. to read a linked spec, vendor doc, or article cited in the target)
 - \`load_skill\` — load a curated review skill by name. See the section below.
@@ -137,9 +151,11 @@ End every response with a single \`<review>\` block. Use this exact structure:
 <verdict>approve | request-changes | comment</verdict>
 </review>
 
-\`approve\` = no blockers; concerns are minor or already addressed.
-\`request-changes\` = at least one blocker, or a load-bearing concern that needs an answer before this lands.
-\`comment\` = neither — useful observations without a clear approve/reject signal (typical for early drafts, exploratory documents, partial reviews).
+These three tokens are the universal verdict vocabulary — they apply whether the target is a code change, a plan, a document, or a dataset. Keep the tokens exactly; the loaded skill tells you what each one means for its domain.
+
+\`approve\` = no blockers; the target is sound and any concerns are minor or already addressed.
+\`request-changes\` = at least one blocker, or a load-bearing concern that needs an answer before the target should be accepted, shipped, or executed.
+\`comment\` = neither — useful observations that do not resolve to a clear accept/reject signal (typical for early drafts, exploratory documents, partial reviews).
 
 ## Rules
 
@@ -180,6 +196,8 @@ If none of the listed skills fit the target, load \`general\`. Keep the skill-se
     customTools: [loadSkillTool],
     payloadSchema: reviewerPayloadSchema,
     visibility: 'public',
+    rosterDescription:
+      'deep read-only code/PR/plan review in a fresh context, returns a structured verdict; it does NOT post — you act on its findings',
     canSpawnSubagents: true,
     timeoutMs: REVIEWER_SPAWN_TIMEOUT_MS,
     inFlightKey: (payload) => payload?.requestId ?? `anon-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,

package/src/bundled-plugins/reviewer/skills/data-review.ts

@@ -0,0 +1,77 @@
+import type { LoadableSkill } from '@/plugin'
+
+export const DATA_REVIEW_SKILL_NAME = 'data-review'
+
+export const DATA_REVIEW_SKILL_DESCRIPTION =
+  'Review structured data and its shape: a database schema or migration, a dataset, a query result, a spreadsheet, a data contract. Covers constraints, nullability, types, indexing, migration safety, and dataset integrity (duplicates, referential integrity, mixed types, aggregate errors).'
+
+export const DATA_REVIEW_SKILL_CONTENT = `# data-review
+
+You have been asked to review structured data — a database schema, a migration, a dataset, a query result, a spreadsheet, or a data contract. Two kinds of target live here and they need different lenses: **the shape** (schema/migration/contract — the rules data must follow) and **the data itself** (a dataset/file — whether the values obey those rules). Identify which you are reviewing, then apply the matching section below on top of the reviewer's neutral output contract.
+
+## How to acquire the target
+
+- **A migration or schema file** — \`read\` it; \`grep\` the surrounding migrations for the current state of the table being altered, because migration safety depends on what already exists.
+- **A dataset / CSV / JSONL** — \`read\` a representative slice (head and a sample of the middle), not just the first rows. Defects hide past the part that looks clean.
+- **A data contract (dbt model, ODCS YAML, JSON Schema)** — \`read\` it and confirm every field declares a type and a nullability/required flag.
+- **A query result in the payload** — read it carefully; quote the offending rows as evidence.
+
+## Reviewing the shape: schema, migration, contract
+
+The shape's job is to make invalid states unrepresentable. A finding here is a rule that is missing, wrong, or unsafe to apply.
+
+1. **Constraints that should exist but do not.** A business-key column (email, SKU, order id) with no \`UNIQUE\`. A required column left nullable. A relationship enforced only in application code with no \`FOREIGN KEY\`. A bounded value (\`status\`, \`price >= 0\`) with no \`CHECK\` or enum. Each missing constraint is a way for schema-invalid data to enter and survive.
+2. **Wrong types.** Money in \`FLOAT\`/\`DOUBLE\` instead of fixed-point \`NUMERIC\` — guarantees rounding drift. Dates or timestamps stored as strings. \`timestamp\` without time zone where UTC-aware (\`timestamptz\`) is meant. A numeric type with no precision/scale that silently coerces.
+3. **Nullability mistakes.** A nullable foreign key for a relationship that is logically required; a NOT NULL on a column the data sometimes genuinely lacks (forcing sentinel values like empty string that confuse "missing" with "blank").
+4. **Indexing.** A foreign key with no supporting index (JOINs and cascade deletes table-scan). A frequently-filtered column with no index. Over-indexing a write-heavy table.
+5. **Migration safety.** This is where a schema change becomes an outage:
+   - Adding a \`NOT NULL\` column to a populated table with no default or backfill — the migration aborts on existing rows. The safe form is additive-then-tighten: add nullable, backfill, set NOT NULL in a later step.
+   - A destructive single-step change (drop/rename a column live) instead of expand-then-contract.
+   - \`CREATE INDEX\` without \`CONCURRENTLY\` on a live table — locks writes for the duration.
+   - A migration with no reverse/rollback path.
+6. **Contract completeness.** For a data contract: every field declares a type and required-flag, the primary key is declared, references resolve to real fields, quality thresholds are realistic, and breaking changes (column removal/rename/type change) are versioned, not silent.
+
+## Reviewing the data itself: dataset, file, spreadsheet
+
+Here the rules may be implicit; your job is to find values that violate what the data clearly intends. Borrow the runtime's own vocabulary: data that fails its intended shape is **schema-invalid**, and a strict consumer is **fail-closed** — it drops or rejects bad rows rather than silently half-accepting them, so a defect that looks cosmetic can erase real records.
+
+1. **Mixed types in one column.** A single column carrying integers, currency-formatted strings ("$1,200"), and blanks. A consumer expecting a number is schema-invalid against these rows; a fail-closed parser drops them silently and the totals are quietly wrong.
+2. **Completeness.** Required fields that are NULL or blank. Watch the empty-string-vs-NULL confusion — they are not the same "missing" and treating them alike corrupts counts.
+3. **Uniqueness.** Duplicate rows, or duplicate business keys where the data plainly intends one row per key.
+4. **Referential integrity.** Orphan rows pointing at parent keys that do not exist; this is a foreign-key violation the file format did not enforce.
+5. **Aggregate errors.** The classic, high-impact dataset bug: a grand-total whose range includes the subtotal rows (double-counting), or an average/sum whose range silently omits rows that belong in it. State which rows are wrongly included or excluded — this is the Reinhart-Rogoff class of defect and it is almost always a blocker.
+6. **Identifier corruption from auto-formatting.** Spreadsheet date/number coercion mangling identifiers (gene names like \`SEPT2\` becoming \`2-Sep\`, leading zeros stripped from zip codes / IDs). Flag any identifier column stored in a general/auto format.
+7. **Distribution and freshness anomalies.** Out-of-range values (negative ages, future timestamps), a sudden volume drop or spike, data older than its freshness expectation.
+8. **PII / secret leakage.** Emails, phone numbers, tokens, or keys appearing in columns not marked sensitive, or stored in plaintext where the surrounding data is classified.
+
+## What NOT to find
+
+- **Formatter / tooling territory.** SQL keyword casing, trailing commas in a migration, CSV quoting style a parser handles — not your concern.
+- **Settled project conventions the target follows.** If the codebase uses \`snake_case\` columns, UUIDv7 keys, or \`.passthrough()\` to tolerate extra columns by design, matching that is not a finding; only deviation is.
+- **Cosmetic dataset quirks with no consumer impact.** A harmless trailing blank line, column order that no consumer depends on. If nothing breaks, do not raise it.
+- **Restating the schema or data.** "This table stores users" / "this column has numbers" is not a finding.
+- **Generic "add validation".** Without naming the specific column and the specific invalid state it admits, "needs more validation" is noise.
+
+## Severity hints specific to data
+
+- **blocker** — Money in floating-point, a migration that aborts or locks production, a missing constraint that admits corrupt rows, an aggregate that double-counts or silently drops rows, identifier corruption, PII in plaintext. Data defects are often blockers because they are silent and compounding.
+- **concern** — A missing index that will degrade as the table grows, a nullable FK that should be required, a freshness/volume anomaly that needs explanation, schema drift from the declared contract.
+- **nit** — A naming inconsistency, a missing audit column, a tolerable-but-suboptimal type. Optional.
+- **praise** — A constraint set that makes an invalid state genuinely unrepresentable, a migration written safely as expand-then-contract, a contract whose quality thresholds are realistic. Rare.
+
+## Verdict mapping
+
+- **approve** — The shape is sound or the data is clean; any issues are nits.
+- **request-changes** — At least one blocker: a corrupting type choice, an unsafe migration, an aggregate error, a constraint gap that admits bad data.
+- **comment** — Useful observations without a clean accept/reject. Common for a partial dataset audit or an early-stage schema sketch.
+
+## Final output
+
+Return findings inside the reviewer's neutral \`<review>\` block. Do NOT invent your own output format.
+`
+
+export const DATA_REVIEW_SKILL: LoadableSkill = {
+  name: DATA_REVIEW_SKILL_NAME,
+  description: DATA_REVIEW_SKILL_DESCRIPTION,
+  content: DATA_REVIEW_SKILL_CONTENT,
+}