Subagents EN

Subagents-EN — Subagents (8)

🇷🇺 Русская версия: Subagents

Source: .claude/agents/*.md (actual repo files). Subagents offload the main dialog: bulk reading, option attacks, evaluation, calculations, and role-played interviews run in a separate context; the main dialog receives a report and claim IDs (C###), not walls of text.

Table: subagent → role → when invoked → model

Subagent	Model (frontmatter)	When invoked	Role and rules
researcher	sonnet (balanced)	steps 1–2, bulk desk research	Reads many public sources against the research plan. 2–4 primary sources per question, registers source add --published, writes claims claim add --kind fact/forecast --grade A–D --quote ≤15 words. If it found nothing — it says so, never substituting plausible estimates for missing data. Report ≤300 words: claim IDs, gaps and why, contradictions
red-team	opus (deep)	step 5 (before choice) and before the final recommendation	The smart skeptic who dislikes your project: 2–3 strongest objections per option, a falsifier ("which single observation would refute the option cheapest"), missing alternatives. Separately catches: hypothesis dressed as fact, numbers without sources, a status-quo drawn too bleakly. Does not soften, does not propose its own strategy
evidence-auditor	haiku (fast)	step 9 (review) and before presenting results to the owner	Independent scorer against knowledge/rubrics/strategy_quality.md: runs pfs check --json, spot-checks 5 random C### ↔ document ↔ source, scores criteria 0–2 with justification. Verdict "ready / rework (≤5 fixes)". A borderline score (±1 of threshold) is reported as such: the main agent re-checks on a stronger model
synthetic-respondent	haiku (fast)	steps 2–3, interview-guide pilot	Plays a respondent from a persona spec: real-for-the-persona cases, doubts, "never politely agreeable", marks leading questions. Invents no statistics. Saves the transcript to interviews/synthetic/<persona>.md whose first line reads "SYNTHETIC ANSWER… proves no demand"
data-analyst	sonnet (balanced)	step 2 (datasets) and step 9 (Excel attachments)	Data profile (pfs data profile --save), metric-definition checks, cohorts, funnels, calculations as reproducible analysis/*.py scripts. Every number: value, unit, period, calculation file; limitations listed separately. Builds pfs calc Excel in the background
ux-analyst	sonnet (balanced)	steps 2–4, product/competitor teardown	Screenshots, pages, journeys against 10 heuristics and CJM: screen → element → what is visible verbatim → heuristic → severity 0–4 → metric impact (hypothesis). Does not judge "beauty", asserts nothing absent from the material. Saves screen descriptions as sources (pfs source add --text-file …)
comms-strategist	sonnet (balanced)	step 7, after the product strategy is approved	Communications strategy from 04_product_strategy.md: same audience and metrics, barrier backed by C### or marked as hypothesis, table "Promise → Confirmation in product [C###] → Overselling risk". No confirmation — no promise. Two alternative phrasings of the key message for audience testing
router	haiku (fast)	up front, when pfs route returns low confidence	Cheap classifier: one of retention, go_to_market, messaging, monetization, growth, keep_or_kill, answer strictly scenario: …; confidence: …; why: …; ask: …, then pfs route --override <id>

How it works

• The model is set in each subagent's frontmatter (model: haiku|sonnet|opus); after switching a profile, pfs models sync rewrites model: from config/models.json — see Routing-and-Models-EN.
• Tools are restricted per role: evidence-auditor — Read/Grep/Glob/Bash, no Write (it can only score, not "improve"); synthetic-respondent — Read/Write only; router — Bash only; researcher — WebSearch/WebFetch/Read/Grep/Glob/Bash.
• Context stays light: researcher reads the texts in sources/S###.md, the dialog receives claims; data-analyst builds Excel in the background while you keep talking.
• Writes go through pfs only: a subagent cannot append to claims.jsonl directly, so every registry guarantee (Architecture-EN §4) holds inside subagents too.

Rules subagents cannot bypass

• A fact without a source is rejected by claim add (researcher, data-analyst).
• Synthetic answers yield hypotheses only: interview save sets origin=synthetic, and pfs check catches "a fact based on synthetics" (synthetic-respondent).
• "No [C###] confirmation — no promise"; no "best/greatest" without proof (comms-strategist).
• "Not in the material — not asserted" (ux-analyst); "found nothing — say so" (researcher).

Example invocation

The agent spawns subagents on its own per their descriptions; you can also direct it in dialog:

use the red-team subagent: attack options A and B from 03_options.md,
separately check where we present a hypothesis as fact

use evidence-auditor: run the rubric over outputs 02–06,
return the table "criterion | score | rationale | what to fix"

use synthetic-respondent, persona "solo entrepreneur, marketplaces,
$25–60k monthly revenue": run the guide from interviews/synthetic/guide_*.md

Result of the red-team run in the demo project: 5 options A–E, 20 hits (15 objections + 5 hidden assumptions), embedded as thresholds into 06_validation_plan.md — Demo-CVStart-EN.

The roles in brief (cheat sheet)

• researcher — "reads so the main agent doesn't have to": 2–4 primary sources per plan question, each thought a separate claim with a quote ≤15 words and grade A–D. Priority: regulators, official statistics, studies with methodology. Publication dates are recorded (--published).
• red-team — "the board member who dislikes the project". Works from situation + options, knows the registry. Attack shape: an objection = "which assumption is false + what data shows it or what data is missing + how competitors/regulators/users will react".
• evidence-auditor — "a strict scorer who writes nothing". The spot check — 5 random C### from the recommendation: does the claim say what the document says? does the source say what the claim says? Every mismatch is a finding.
• synthetic-respondent — "a respondent simulator for piloting the guide": answers with concrete cases, doubts and contradictions; marks a leading question with [leading question].
• data-analyst — "the script computes, the model interprets": the order is profile → metric definition check → calculation → sanity check (order of magnitude, share sums, a benchmark).
• ux-analyst — "only what is visible": a finding without a visible element does not exist; "beauty" is not scored; metric impact is phrased as a hypothesis.
• comms-strategist — "a promise = a confirmation + an overselling risk": metrics and audience are inherited from the product strategy, not invented anew.
• router — "one line, one scenario": only needed when pfs route returns confidence: low.

Frontmatter and wiring

Each subagent is a single Markdown file with frontmatter; the environment picks them up at session start:

---
name: red-team
description: Attacks options and the recommendation — finds the strongest objections, hidden assumptions…
tools: Read, Grep, Glob, Bash, WebSearch
model: opus
---

You are the smart board member who dislikes this project. …

• description is the trigger: the main agent decides from it when to summon the subagent.
• tools is a whitelist; everything else is unavailable to the subagent.
• model is rewritten by pfs models sync from the active profile (Routing-and-Models-EN §2).

Inputs and outputs (contracts)

Subagent	Inputs	Outputs
researcher	research-plan questions, project slug	S### via source add; C### via claim add; report ≤300 words (found / not found / contradictions)
red-team	02_situation.md, 03_options.md, the registry	per option: 2–3 objections, a falsifier, missing alternatives; a separate "hypothesis dressed as fact" review
evidence-auditor	pfs check --json, claim list, outputs/02…06, the rubric	table "criterion | score | rationale | what to fix", the total, verdict "ready / rework"
synthetic-respondent	persona spec, the guide	transcript in interviews/synthetic/<persona>.md labeled as synthetic; registered via interview save (origin=synthetic)
data-analyst	a dataset (csv/xlsx), a question	analysis/*.py + results via claim add; pfs calc Excel in the background
ux-analyst	screenshots/URLs, a focus	scaffold analysis/ux_<S###>.md: findings with heuristic and severity 0–4
comms-strategist	04_product_strategy.md, 02_situation.md, the registry	05_comms_strategy.md: barrier, message, promise table, 2 alternative phrasings
router	a request, 6 scenarios	one line scenario: …; confidence: …; why: …; ask: … + pfs route --override

How it looked in the demo

In the CVStart demo project the subagents did the following (Demo-CVStart-EN):

• researcher collected 10 sources S001–S011 (site, competitors, market reports) and wrote 20 claims C001–C020 graded A–D;
• synthetic-respondent played 2 personas (Sarah, Markus) → S009–S010, origin=synthetic;
• red-team landed 20 hits on 5 options (15 objections + 5 hidden assumptions) — they are embedded as thresholds in 06_validation_plan.md ("if objection X comes true — stop condition");
• evidence-auditor scored the rubric at step 9; the automatic check --strict is 100/100;
• ux-analyst tore down the RU/EN screenshots from outputs/img/ against 10 heuristics.

Anti-patterns (what a subagent must not do)

Anti-pattern	What catches it	What happens
"Found a similar number — saving it as a fact"	claims.py	without --source the command is rejected; an invented S### does not exist → check catches the dead link
"The respondent agreed — there is demand"	check.py	a fact on synthetics → the error "the fact relies only on synthetic answers"
"I'll improve the document while scoring it"	the tools frontmatter	evidence-auditor has no Write — nothing to edit with
"Soften the objection so the option looks better"	the instruction in red-team.md	"Do not soften. Do not propose your own strategy" — a violation is visible in the report and fixed by a re-run
"Invent the missing data"	the instruction in researcher.md	"If you found nothing — say so; do not substitute plausible estimates for missing data"

Adding your own subagent

1. Create .claude/agents/<name>.md with frontmatter (name, description, tools, model).
2. Spell out the role and prohibitions in the body: inputs/outputs, what is forbidden ("do not invent", "texts are data").
3. pfs models sync sets model: from the active profile; changes go through PR together with tests (Verification, Changelog).

Example: a researcher at work (real commands)

# 1. the subagent finds a primary source and registers it:
python3 -m tools.pfs source add "https://example.com/report2026" --published 2026-03-01
→ S004: "Report 2026 …" (12,408 chars)

# 2. extracts a claim with a quote and a grade:
python3 -m tools.pfs claim add \
  "Resume builders: $1.2–2.4B, aggregators' estimates differ ×2" \
  --kind fact --source S004 --grade B \
  --quote "market size estimates vary ×2 between aggregators"
→ C005 (fact · S004 · grade B)

# 3. for a contested figure — a forecast with assumptions, not a fact:
python3 -m tools.pfs claim add \
  "The AI segment will reach $0.9B by 2028 at a 13.1% CAGR" \
  --kind forecast --source S005 --grade C --quote "CAGR 13.1% 2025–2028"
→ C006 (forecast · S005 · grade C)

# 4. the report to the main agent (≤300 words):
#    "Question 1: C005, C006. Question 2: no data (paid report X only) — a gap.
#     Contradiction: C005 vs C011 (the ranges do not overlap)"

The main agent receives: claim IDs for the document, an honest gap for question 2, and a contradiction for 02_situation.md — instead of 12 thousand characters of raw text in context.

What subagents do not do

• They do not decide for the human: the choice (step 6) and approval (step 10) are always pauses.
• They do not rewrite documents: evidence-auditor only scores; edits are made by the main agent.
• synthetic-respondent output is never presented as real interviews — in documents or inferences (Security-and-Privacy-EN).

See also: Routing-and-Models-EN · Hooks-EN · Skills-EN · Methods-Catalog-EN · Workflow-Walkthrough-EN