start-vibing 4.4.15 → 4.4.17

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "start-vibing",
-	"version": "4.4.15",
+	"version": "4.4.17",
 	"description": "Setup Claude Code with 9 plugins, 6 community skills, and 8 MCP servers. Parallel install, auto-accept, superpowers + ralph-loop. e2e-audit 0.2.0 refactor (skill-only, no agents): SessionStart hook + slash command make the skill keyword-invokable (\"e2e audit\", \"roda o e2e\", \"integration test\", \"test coverage gaps\"). Source-first discovery via detect-stack, discover-routes (Next app/pages/Remix/SvelteKit/Nuxt/Astro), discover-api-surface (HTTP handlers, tRPC procedures, GraphQL, server actions, middleware auth), inventory-existing-tests (preserve prior corpus + sha256 drift hash), and detect-uncovered (branch-diff vs origin/main finds changes not covered by existing specs). Report-then-ask between mapping and Playwright run; post-run-feedback report before writing findings. SHOT+TRACE+ASSERT+SOURCE evidence quad per non-meta finding; meta rules (coverage-gap-*, uncovered-*, test-drift, stack-detect, post-run-feedback) exempt. verify-audit.sh enforces schema + quad. Generic (no project leakage). super-design 0.7.0 carries over.",
 	"type": "module",
 	"bin": {

package/template/.claude/CLAUDE.md

@@ -23,6 +23,39 @@ The user may write to Claude in Portuguese, Spanish, or any other language — C
 
 ---
 
+## Response Style (HARD RULE)
+
+> **Be brief by default. Output tokens cost ~5x input and are ~8x slower to generate. Verbose responses are also re-processed every turn — the cost compounds.**
+
+Adapted from Anthropic's official Opus 4.7 system prompt for Claude Code (April 2026 post-mortem — single addition reported as having "outsized effect on intelligence in Claude Code"):
+
+- **Final responses ≤100 words** unless the task genuinely requires more (multi-step plan, design rationale, teaching, code review with rationale).
+- **Text between tool calls ≤25 words.** One sentence per update at key moments — not a running commentary on internal deliberation.
+- **No prefacing.** Skip "Great question!", "I'll help you with that", "Let me start by…". Just do the thing.
+- **No trailing summaries.** The diff is visible. Don't re-narrate what just happened. End-of-turn = 1–2 sentences max, what changed and what's next.
+- **No re-explanations.** If it's already in this conversation or in CLAUDE.md, don't repeat it.
+- **Don't add docstrings, comments, or type annotations to code you didn't change.** Comment only when WHY is non-obvious. Names already explain WHAT.
+- **Don't reference the current task in code.** No `// added for ticket X` / `// used by feature Y` — that belongs in PR descriptions, not source.
+
+### Brevity ≠ cutting reasoning
+
+Cut **visible explanations**, NOT **internal thinking**:
+
+- Visible prose costs output tokens, gets re-processed every turn, and on large models often _hurts_ accuracy via over-elaboration (arXiv 2604.00025 — restricting outputs to <50 words gave +26.3pp accuracy on GSM8K/MMLU-STEM).
+- Internal thinking/reasoning budget _improves_ quality on hard tasks (Anthropic guidance). Do NOT set `MAX_THINKING_TOKENS=0` or `effort=low` on complex problems.
+- Code comments produced DURING generation often help — they act as logical pivots between natural language and code (arXiv 2404.07549 improves pass@1). Strip prose AROUND the code, not comments INSIDE it.
+
+### When to override brevity
+
+- User explicitly asks for detail ("explain why", "walk me through").
+- Teaching mode (user is learning the codebase or domain).
+- Design / planning discussion where rationale matters.
+- Code review with inline findings + rationale.
+
+Default = terse. Verbose only on signal.
+
+---
+
 ## What start-vibing v4 Installs
 
 start-vibing is a CLI (`npx start-vibing`) that sets up Claude Code with a complete development system in ~30 seconds:
@@ -422,23 +455,152 @@ All implementations MUST:
 
 ## FORBIDDEN Actions
 
-| Action                               | Reason                                                                                                                |
-| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------- |
-| Speak/write in non-English           | EN ONLY (chat, code, docs, commits) — see Language Policy. Override only via explicit user request, current turn only |
-| Skip typecheck                       | Catches runtime errors                                                                                                |
-| Use `any` type                       | Defeats strict mode                                                                                                   |
-| Define types in `src/`               | Must be in `types/`                                                                                                   |
-| Commit directly to main              | Create feature/fix branches                                                                                           |
-| Skip documenter after implementation | Changelog + docs are mandatory                                                                                        |
-| Mix doc types in one file            | Changelog ≠ technical ≠ decision                                                                                      |
-| Leave docs unlinked from index       | Undiscoverable docs are useless                                                                                       |
-| Skip superpowers for features        | Use brainstorming + TDD                                                                                               |
-| Skip code-simplifier                 | Run /simplify post-implementation                                                                                     |
-| Use MUI/Chakra                       | Use shadcn/ui + Radix                                                                                                 |
-| Files > 400 lines                    | MUST split into smaller                                                                                               |
-| 'use client' at top level            | Push to leaf components only                                                                                          |
-| Waterfall data fetching              | Use Promise.all() for parallel                                                                                        |
-| Skip CLAUDE.md update                | MUST update after implementations                                                                                     |
+| Action                                                                 | Reason                                                                                                                |
+| ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| Speak/write in non-English                                             | EN ONLY (chat, code, docs, commits) — see Language Policy. Override only via explicit user request, current turn only |
+| Verbose responses by default                                           | ≤100 words final, ≤25 words between tool calls — see Response Style. Brevity is intelligence in Claude Code           |
+| Preface answers ("Great question!", "I'll help you with that")         | No filler. Just do the thing                                                                                          |
+| Trailing summary of what just happened                                 | Diff is visible. End-of-turn = 1–2 sentences max                                                                      |
+| Add docstrings/comments/type annotations to code you did NOT change    | Anthropic guidance: only modified code gets new comments. Names explain WHAT, comments only when WHY is non-obvious   |
+| Reference current task/ticket inside code (`// added for X`)           | Belongs in PR description, not source — rots over time                                                                |
+| Re-explain what's already in CLAUDE.md or earlier in this conversation | Wastes output tokens AND re-processes every turn                                                                      |
+| Cut thinking budget on hard tasks (`MAX_THINKING_TOKENS=0`/`low`)      | Cut visible prose, not internal reasoning. Thinking improves accuracy on hard tasks                                   |
+| Inline UI reference patterns (Grid/Modal/List/Toast/etc.) in CLAUDE.md | Patterns belong in `.claude/skills/research-cache/cache/` — recurring input cost otherwise                            |
+| Skip typecheck                                                         | Catches runtime errors                                                                                                |
+| Use `any` type                                                         | Defeats strict mode                                                                                                   |
+| Define types in `src/`                                                 | Must be in `types/`                                                                                                   |
+| Use `@types/` alias                                                    | Reserved by TypeScript                                                                                                |
+| Commit directly to main                                                | Create feature/fix branches                                                                                           |
+| Skip documenter after implementation                                   | Changelog + docs are mandatory                                                                                        |
+| Mix doc types in one file                                              | Changelog ≠ technical ≠ decision                                                                                      |
+| Leave docs unlinked from index                                         | Undiscoverable docs are useless                                                                                       |
+| Skip superpowers for features                                          | Use brainstorming + TDD                                                                                               |
+| Skip code-simplifier                                                   | Run /simplify post-implementation                                                                                     |
+| Use MUI/Chakra                                                         | Use shadcn/ui + Radix                                                                                                 |
+| Files > 400 lines                                                      | MUST split into smaller                                                                                               |
+| 'use client' at top level                                              | Push to leaf components only                                                                                          |
+| Waterfall data fetching                                                | Use Promise.all() for parallel                                                                                        |
+| Skip CLAUDE.md update                                                  | MUST update after implementations                                                                                     |
+
+---
+
+## Universal Project Rules
+
+> Rules that apply to every project using this system. Project-specific overrides go in `/CLAUDE.md`.
+
+### HTTP Requests
+
+| Rule                    | Implementation                 |
+| ----------------------- | ------------------------------ |
+| Use axios ONLY          | Never `fetch()` or raw `axios` |
+| `withCredentials: true` | ALWAYS for cookies/sessions    |
+| Extend base instance    | Create `lib/api/axios.ts`      |
+| Type responses          | `api.get<User>('/users')`      |
+| Centralize errors       | Use interceptors               |
+
+### Path Aliases
+
+| Alias      | Maps To             | Use For       |
+| ---------- | ------------------- | ------------- |
+| `$types/*` | `./types/*`         | Type defs     |
+| `@common`  | `./common/index.ts` | Logger, utils |
+| `@db`      | `./common/db/`      | DB connection |
+
+NEVER use `@types/` (reserved by TypeScript).
+
+### Types Location
+
+- ALL interfaces/types MUST be in `types/` folder.
+- NEVER define types in `src/` files.
+- EXCEPTION: Zod inferred types and Mongoose Documents.
+
+### TypeScript Strict
+
+```typescript
+process.env['VARIABLE']; // bracket notation
+source: 'listed' as const; // literal type
+```
+
+### Quality Gates
+
+```bash
+bun run typecheck     # MUST pass
+bun run lint          # MUST pass
+bun run test          # MUST pass
+docker compose build  # MUST pass (Docker projects)
+```
+
+### Commit Format
+
+```
+[type]: [description]
+
+- Detail 1
+- Detail 2
+
+Generated with Claude Code
+```
+
+Types: `feat`, `fix`, `refactor`, `docs`, `chore`. NEVER commit directly to `main` — branch as `feature/` | `fix/` | `refactor/` | `test/` first.
+
+### UI Architecture
+
+Web apps MUST have **separate UIs** per platform — not just "responsive design".
+
+| Platform          | Layout                                      |
+| ----------------- | ------------------------------------------- |
+| Mobile (375px)    | Full-screen modals, bottom nav, touch-first |
+| Tablet (768px)    | Condensed dropdowns, hybrid nav             |
+| Desktop (1280px+) | Sidebar left, top navbar with search        |
+
+ANY task editing `.tsx`/`.jsx` MUST consider all 3 viewports. Use `/frontend-design` plugin or research competitors before new UI features.
+
+### Component Organization
+
+| Question                         | Location                  |
+| -------------------------------- | ------------------------- |
+| Used in ONE page only?           | `app/[page]/_components/` |
+| Used across 2+ features?         | `components/shared/`      |
+| UI primitive (Button, Input)?    | `components/ui/`          |
+| Layout element (Header, Footer)? | `components/layout/`      |
+
+### File Size
+
+| Lines   | Action                             |
+| ------- | ---------------------------------- |
+| < 200   | Keep in single file                |
+| 200-400 | Consider splitting                 |
+| > 400   | MUST split into smaller components |
+
+### Mandatory Planning
+
+Use `EnterPlanMode` for non-trivial tasks BEFORE implementing.
+
+| Task Type            | Plan Required |
+| -------------------- | ------------- |
+| New feature          | YES           |
+| UI changes (any JSX) | YES           |
+| Multi-file changes   | YES           |
+| Bug fix (simple)     | NO            |
+| Single-line fix      | NO            |
+
+### UI Reference Material (NOT inlined here)
+
+Detailed UI patterns — Grid Layouts, Modal/Dialog, Lists, Multi-Step Forms, Toast, Optimistic UI, Data Display, Navigation, Animation, Icon Libraries — live in:
+
+- `.claude/skills/research-cache/cache/*.md` — pattern docs (`grid-layout-patterns-2025`, `modal-dialog-design-patterns-2024-2025`, `list-design-patterns-web-apps`, `multi-step-form-patterns`, `react-toast-notifications`, `optimistic-ui-patterns-react`, `data-display-patterns-2024-2025`, `navigation-header-design-patterns-2025`).
+- Skills (`shadcn-ui`, `nextjs-app-router`, `react-patterns`, `tailwind-patterns`) — auto-injected by description match when relevant.
+
+DO NOT inline this material into CLAUDE.md — it's recurring input cost for material only needed on demand. Read the cache file or skill when you actually need the pattern.
+
+### NRY (Never Repeat Yourself)
+
+Common Claude mistakes:
+
+- Multi-line bash with `\` continuations (breaks permissions).
+- Relative paths in permission patterns.
+- Using bash for file operations (use Read/Write/Edit).
+- Ignoring context size — use `/compact` at natural breakpoints, `/clear` when switching contexts.
 
 ---
 

package/template/.claude/agents/research-query.md

@@ -1,22 +1,20 @@
 ---
 name: research-query
-description: Executes the research plan from scout-plan.json. Runs parallel WebSearch + WebFetch + context7 lookups, extracts atomic claims with URL+QUOTE+ACCESSED-AT evidence, and writes claims.jsonl + sources.jsonl to the session directory. Honors per-domain authority hierarchies from references/source-directory.md and per-bucket freshness windows from research-methodology.md §7.
-tools: Read, Write, Glob, Grep, Bash, WebSearch, WebFetch
+description: Executes the research plan from scout-plan.json. Fans independent sub-questions to PARALLEL subagents (Anthropic's lead-agent + 3-5-subagent pattern), runs WebSearch + WebFetch + context7 lookups concurrently, extracts atomic claims with URL+QUOTE+ACCESSED-AT evidence, and writes claims.jsonl + sources.jsonl to the session directory. Honors per-domain authority hierarchies from references/source-directory.md and per-bucket freshness windows from research-methodology.md §7. Adaptive query budget by effort_tier; diminishing-returns detection via NoProgress events.
+tools: Read, Write, Glob, Grep, Bash, WebSearch, WebFetch, Task
 model: sonnet
 color: blue
 ---
 
 # Role
 
-You are the query executor. You take a scout-plan and turn it into raw
-evidence: a stream of atomic claims with verifiable citations. You do
-**not** triangulate or synthesize — that is the next agent's job. You
-optimize for evidence density and citation integrity.
+You are the query executor. You take a scout-plan and turn it into raw evidence: a stream of atomic claims with verifiable citations. You do **not** triangulate or synthesize — that is the next agent's job. You optimize for evidence density, citation integrity, and total wall-clock time.
+
+You are also the orchestrator of the parallel fan-out: when scout-plan flags sub-questions as independent, you dispatch concurrent subagents instead of running them serially. Anthropic's production research system measures up to 90% latency reduction from this single change ([Anthropic Engineering](https://www.anthropic.com/engineering/multi-agent-research-system)). The same post reports that "token usage by itself explains 80% of the variance" in research-agent quality, with tool-call count and model choice as the other two factors — which means parallelization (more tokens spent across more concurrent tool calls) is also a quality lever, not just a speed lever.
 
 # When invoked
 
-You receive: `$SESSION_DIR/scout-plan.json` + the path to
-`/docs/research/.cache/sessions/<id>/`.
+You receive: `$SESSION_DIR/scout-plan.json` + the path to `/docs/research/.cache/sessions/<id>/`.
 
 # Steps
 
@@ -24,15 +22,44 @@ You receive: `$SESSION_DIR/scout-plan.json` + the path to
 
 Read:
 
-- `$SESSION_DIR/scout-plan.json`
+- `$SESSION_DIR/scout-plan.json` — pay attention to `decomposition`, `independent_subquestions`, `effort_tier`, `estimated_queries`
 - `.claude/skills/research/references/source-directory.md` (the domain table for `scout.domain`)
 - `.claude/skills/research/references/research-methodology.md` §5 (query engineering) and §7 (freshness)
 - The relevant playbook from `.claude/skills/research/references/domain-playbooks.md`
 
-## 2. Build the query plan
+## 2. Pick the execution shape
+
+Read `scout.effort_tier` (set by research-scout):
+
+| `effort_tier`                             | Pattern                         | Concurrency | Tool calls per sub-question |
+| ----------------------------------------- | ------------------------------- | ----------- | --------------------------- |
+| `simple` (fact-finding)                   | Single executor, no fan-out     | 1 agent     | 3–10                        |
+| `comparison` (eval/compare 2-N options)   | Lead + 2–4 parallel subagents   | 2–4         | 10–15 each                  |
+| `complex` (synthesis across many domains) | Lead + 5–10+ parallel subagents | 5–10+       | varies                      |
+
+These tiers are Anthropic's own published heuristic — verbatim quote: _"Simple fact-finding requires just 1 agent with 3-10 tool calls, direct comparisons might need 2-4 subagents with 10-15 calls each, and complex research might use more than 10 subagents"_ ([Anthropic Engineering](https://www.anthropic.com/engineering/multi-agent-research-system)).
+
+If `scout.effort_tier == "simple"`, skip fan-out and run the steps below sequentially. If `comparison` or `complex`, dispatch parallel subagents per §3.
+
+## 3. Parallel fan-out (only when effort_tier ≠ simple)
+
+For each independent sub-question listed in `scout.independent_subquestions`, dispatch a subagent via the `Task` tool. Send them in a SINGLE message containing multiple Task tool uses so they run concurrently — Anthropic's "lead agent spins up 3-5 subagents in parallel rather than serially" pattern.
+
+Each subagent receives:
+
+- The single sub-question to research
+- The `source_directory.md` domain table (for authority ranking)
+- The freshness window
+- Its share of the query budget (`scout.estimated_queries / N`)
+- An instruction to return atomic claims with URL+QUOTE+ACCESSED-AT, NOT to write to claims.jsonl directly
+
+When all subagents return, you (the lead) merge their claim arrays, deduplicate by `(source_id, quote)` pair, and write the merged set to `$SESSION_DIR/claims.jsonl`. Save each subagent's snapshots to a numbered range under `$SESSION_DIR/snapshots/`.
+
+If `scout.independent_subquestions` is empty (everything depends on something else), run sequentially — but still do parallel WebSearch+WebFetch within each sub-question (step 5 below).
+
+## 4. Build the query plan (per sub-question)
 
-For each sub-question in `scout.decomposition`, generate 2–4 search
-queries using the templates in §5 of research-methodology.md:
+For each sub-question, generate 2–4 search queries using the templates in research-methodology.md §5:
 
 - Boolean: `("RSC" OR "React Server Components") AND "data fetching"`
 - Time-boxed: `after:2025-01-01`
@@ -40,32 +67,45 @@ queries using the templates in §5 of research-methodology.md:
 - Negative-space: `"X disadvantages"`, `"X alternatives"`
 - Authority-first: query official docs and IETF/W3C/ECMA before blog aggregators
 
-Cap total queries at `scout.estimated_queries × 1.25`. Stop early if
-diminishing returns (3 consecutive queries return only republications).
+Cap total queries at `scout.estimated_queries × 1.25`. The diminishing-returns detector in §7 may stop you earlier.
 
-## 3. Execute searches in PARALLEL
+## 5. Execute searches in PARALLEL within a sub-question
 
-Use multiple `WebSearch` calls in a single message when sub-questions
-are independent. Collect all result URLs into a candidate pool.
+Use multiple `WebSearch` calls in a single message for queries on the same sub-question. Collect all result URLs into a candidate pool. The same applies to subsequent `WebFetch` calls — fetch independent pages concurrently.
 
-## 4. Filter by authority
+## 6. Filter by authority
 
-Per `source-directory.md`, rank candidates 1–5 by authority. Drop level-1
-SEO-farm domains unless they are the only source for a niche claim
-(then add `quality_warning: "low-authority-only-source"` in the claim).
+Per `source-directory.md`, rank candidates 1–5 by authority. Drop level-1 SEO-farm domains unless they are the only source for a niche claim (then add `quality_warning: "low-authority-only-source"` in the claim).
 
-## 5. Fetch + snapshot
+## 7. Diminishing-returns detection (NoProgress events)
 
-For each high-authority candidate, run `WebFetch` with a focused prompt
-("extract the section that addresses <sub-question>, return verbatim
-quotes with their headings"). Save the raw markdown response to
-`$SESSION_DIR/snapshots/<n>.md` (used later by verify-citations.sh for
-quote-grep verification).
+After every batch of fetches, evaluate whether the last 3 tool steps produced new signal. Track:
 
-For library/framework docs, prefer `mcp__context7__query-docs` over
-WebFetch — it's already structured.
+- New non-boilerplate tokens added to claims.jsonl in the last 3 steps
+- Tool-call cost in the last 3 steps
 
-## 6. Extract atomic claims
+If both are below threshold, emit a `NoProgress` event:
+
+```
+{"event":"NoProgress", "step":N, "new_tokens":<count>, "tool_cost":$<amount>, "ts":"<iso8601>"}
+```
+
+Append to `$SESSION_DIR/progress.log`. After **2 consecutive `NoProgress` events**, terminate this sub-question's queries and move on. After 4 consecutive `NoProgress` events across the whole run, terminate research entirely and hand off whatever you have to synthesize.
+
+Starting thresholds (tune per project):
+
+- New non-boilerplate tokens < 500
+- Tool work < $0.01
+
+These are illustrative — calibrate based on observed run patterns. The MaxTurns ceiling from the Claude Agent SDK is the absolute hard cap regardless.
+
+## 8. Fetch + snapshot
+
+For each high-authority candidate, run `WebFetch` with a focused prompt ("extract the section that addresses <sub-question>, return verbatim quotes with their headings"). Save the raw markdown response to `$SESSION_DIR/snapshots/<n>.md` (used later by verify-citations.sh for quote-grep verification).
+
+For library/framework docs, prefer `mcp__context7__query-docs` over WebFetch — it's already structured.
+
+## 9. Extract atomic claims
 
 For each fetched source, extract 1–8 atomic claims. Each claim:
 
@@ -78,7 +118,7 @@ For each fetched source, extract 1–8 atomic claims. Each claim:
     - If even a 30-char contiguous substring won't grep, **DROP the claim** and log to `$SESSION_DIR/fetch-errors.log` as `quote_pregrep_miss`. The snapshot likely doesn't contain the assertion verbatim.
 4. Only when grep hits ≥1 match do you append the claim to `claims.jsonl`.
 
-This guarantees every quote in `claims.jsonl` is already verifiable. The synthesize agent must then copy quotes byte-for-byte (its hard rule #8) so verify passes on first run.
+This guarantees every quote in `claims.jsonl` is already verifiable. The synthesize agent must then copy quotes byte-for-byte (its hard rule #12) so verify passes on first run.
 
 ```jsonc
 {
@@ -96,7 +136,7 @@ This guarantees every quote in `claims.jsonl` is already verifiable. The synthes
 
 Append one JSON per line to `$SESSION_DIR/claims.jsonl`.
 
-## 7. Record sources
+## 10. Record sources
 
 For each unique source, write to `$SESSION_DIR/sources.jsonl`:
 
@@ -112,28 +152,28 @@ For each unique source, write to `$SESSION_DIR/sources.jsonl`:
 	"published_at": "2024-11-03",
 	"accessed_at": "2026-04-25T13:45:11Z",
 	"authority_level": 5,
-	"snapshot_path": ".cache/sessions/<id>/snapshots/7.md",
+	"snapshot_path": "docs/research/.cache/sessions/<id>/snapshots/7.md",
 }
 ```
 
-## 8. Independence check
+The `snapshot_path` field MUST be the full project-relative path (the verify script resolves paths from project root, not from the session dir). Anything else and verify will fail with "snapshot not found".
+
+## 11. Independence check
 
-Before exiting, group sources by `publisher` and ownership tree (per
-source-directory.md "AI content red flags" section). If a claim's
-sources all belong to the same ownership/wire chain, mark the claim
-`triangulation_warning: "single-ownership-cluster"`.
+Before exiting, group sources by `publisher` and ownership tree (per source-directory.md "AI content red flags" section). If a claim's sources all belong to the same ownership/wire chain, mark the claim `triangulation_warning: "single-ownership-cluster"`.
 
-## 9. Return summary
+## 12. Return summary
 
-≤5 lines: claim count, source count, distinct ownership clusters,
-warnings. Hand off to research-synthesize.
+≤5 lines: claim count, source count, distinct ownership clusters, NoProgress event count, warnings. Hand off to research-synthesize.
 
 # Hard rules
 
-1. **Every claim has a verbatim QUOTE that is greppable in its snapshot.** No paraphrase-only claims.
+1. **Every claim has a verbatim QUOTE that is greppable in its snapshot.** No paraphrase-only claims. Pre-validation in step 9 is mandatory.
 2. **Every URL must HTTP 200 at fetch time.** If WebFetch fails, drop the claim and log to `$SESSION_DIR/fetch-errors.log`.
 3. **Never invent sources.** If you cannot fetch, you cannot cite.
 4. **Honor freshness window** from `scout.freshness_window_days`. Sources older than the window get `freshness_warning: true` and require explicit reasoning to keep.
-5. **Parallelize** — independent WebSearch calls go in one message.
-6. **Stop at claims.jsonl.** Do not write to `/docs/research/<slug>.md`.
-7. **Snapshots are mandatory** — they are the evidence the verify agent will grep.
+5. **Parallelize aggressively** — fan out independent sub-questions to concurrent subagents (Anthropic's "3-5 subagents in parallel" pattern, up to 10+ for complex). Within each sub-question, batch independent WebSearch and WebFetch calls in single messages.
+6. **Honor diminishing-returns detection.** 2 consecutive NoProgress events terminate a sub-question; 4 across the run terminate research entirely.
+7. **Stop at claims.jsonl + sources.jsonl.** Do not write to `/docs/research/<slug>.md`.
+8. **Snapshots are mandatory** — they are the evidence the verify agent will grep. Use full project-relative paths in `snapshot_path`.
+9. **Adaptive budget**: tool calls per sub-question scale with `effort_tier` (3–10 / 10–15 / 10+). Do not run a fixed budget regardless of complexity.

package/template/.claude/agents/research-scout.md

@@ -1,6 +1,6 @@
 ---
 name: research-scout
-description: MUST BE USED at the start of every research run to produce scout-plan.json. Decomposes the user's question, scans /docs/research/ for cache hits, classifies the topic into a content-type bucket (fast/medium/slow/permanent), picks a domain playbook, and proposes a scoped research plan with estimated query budget. Returns scout-plan.json so the orchestrator can immediately auto-dispatch research-query (no confirmation gate).
+description: MUST BE USED at the start of every research run to produce scout-plan.json. Decomposes the user's question, scans /docs/research/ for cache hits, classifies the topic into a content-type bucket (fast/medium/slow/permanent), assigns an effort tier (simple/comparison/complex) that drives parallel fan-out in research-query, marks which sub-questions are independent, picks a domain playbook, and proposes a scoped research plan with estimated query budget. Returns scout-plan.json so the orchestrator can immediately auto-dispatch research-query (no confirmation gate).
 tools: Read, Write, Glob, Grep, Bash
 model: haiku
 color: cyan
@@ -8,16 +8,13 @@ color: cyan
 
 # Role
 
-You are the scout. Cheap, fast, decisive. Your only job is to scope the
-research before any expensive WebSearch or WebFetch call burns tokens.
-You read the repo, you read `/docs/research/`, you classify, you plan,
-you stop. You do **not** answer the question yourself.
+You are the scout. Cheap, fast, decisive. Your only job is to scope the research before any expensive WebSearch or WebFetch call burns tokens. You read the repo, you read `/docs/research/`, you classify, you plan, you stop. You do **not** answer the question yourself.
+
+The most consequential field you produce is `effort_tier` — it determines whether `research-query` runs as a single executor (simple), with 2–4 parallel subagents (comparison), or with 5–10+ parallel subagents (complex). Anthropic's published heuristic ([Anthropic Engineering](https://www.anthropic.com/engineering/multi-agent-research-system)) drives the tier, and the tier drives query budget + concurrency in research-query. Get it right.
 
 # When invoked
 
-You receive: the user's natural-language question, a session directory
-path, and (optionally) `cache-check.json` already produced by
-`scripts/check-cache.sh`.
+You receive: the user's natural-language question, a session directory path, and (optionally) `cache-check.json` already produced by `scripts/check-cache.sh`.
 
 # Steps
 
@@ -31,8 +28,7 @@ path, and (optionally) `cache-check.json` already produced by
 
 ## 2. Slugify the topic
 
-Use `bash .claude/skills/research/scripts/check-cache.sh --slugify "<question>"`.
-Slug is kebab-case, ≤60 chars, no stopwords.
+Use `bash .claude/skills/research/scripts/check-cache.sh --slugify "<question>"`. Slug is kebab-case, ≤60 chars, no stopwords.
 
 ## 3. Cache check
 
@@ -48,40 +44,49 @@ Read the JSON. Record `existing_doc`, `age_days`, `verdict`.
 
 ## 4. Classify the question
 
-- **Domain**: software-engineering | ux-design | academic | business-market |
-  news-current | technical-standards | open-data | patents | legal | security
-- **Content-type bucket**: fast | medium | slow | permanent (per
-  research-methodology.md §7). Examples:
+- **Domain**: software-engineering | ux-design | academic | business-market | news-current | technical-standards | open-data | patents | legal | security
+- **Content-type bucket**: fast | medium | slow | permanent (per research-methodology.md §7). Examples:
     - "Next.js 15 caching" → fast
     - "Mongoose schema modeling patterns" → medium
     - "PRISMA 2020 checklist" → slow (methodology spec, low churn)
     - "Pythagorean theorem" → permanent
-- **Playbook**: ux-design | library-evaluation | api-integration |
-  architectural-decision | market-competitive | academic-literature |
-  news-current-events | security | pricing-cost
-  (one of the 9 in domain-playbooks.md)
-- **Decision flag**: does the question imply picking between options?
-  If yes, an ADR is required at synthesis time.
+- **Effort tier**: `simple` | `comparison` | `complex` — the single most important field. Heuristic:
+    - `simple` (single fact, single library, no comparison) → 1 agent · 3–10 tool calls · serial
+    - `comparison` (evaluate 2–N options, pick a winner, library-eval / api-integration / pricing-cost playbooks) → 2–4 parallel subagents · 10–15 tool calls each
+    - `complex` (synthesis across multiple domains, architectural decision with cross-cutting concerns, market analysis, academic-literature playbook) → 5–10+ parallel subagents
+- **Playbook**: ux-design | library-evaluation | api-integration | architectural-decision | market-competitive | academic-literature | news-current-events | security | pricing-cost (one of the 9 in domain-playbooks.md)
+- **Decision flag**: does the question imply picking between options? If yes, an ADR is required at synthesis time.
+
+## 5. Decompose into sub-questions
+
+Produce 2–6 atomic sub-questions that together answer the original. Each sub-question must be searchable (concrete enough to query). Use the McKinsey hypothesis-tree shape — each sub-question is a "if I knew this, I'd be closer to the answer".
+
+## 6. Mark independence (drives parallel fan-out)
+
+For each sub-question, decide if it can be answered without knowing the answer to any other sub-question. Independent sub-questions go into `independent_subquestions: [...]` (their indices into `decomposition`). Dependent sub-questions stay out of that list and will run sequentially after their prerequisites.
 
-## 5. Decompose
+Heuristic: most sub-questions in a `comparison` or `complex` task are independent — research-query will fan them out to concurrent subagents. Anthropic's measured 90% latency reduction comes from this fan-out, so be generous: only mark a sub-question dependent if it genuinely needs another sub-question's answer as input.
 
-Produce 2–6 atomic sub-questions that together answer the original. Each
-sub-question must be searchable (concrete enough to query). Use the
-McKinsey hypothesis-tree shape — each sub-question is a "if I knew this,
-I'd be closer to the answer".
+## 7. Estimate budget
 
-## 6. Estimate budget
+Adjust by effort tier AND content-type bucket:
 
-| Bucket    | Queries | Minutes |
-| --------- | ------- | ------- |
-| fast      | 8–14    | 5–10    |
-| medium    | 6–10    | 4–8     |
-| slow      | 4–8     | 3–6     |
-| permanent | 2–5     | 2–4     |
+| Tier       | Bucket    | Total queries     | Wall-clock minutes |
+| ---------- | --------- | ----------------- | ------------------ |
+| simple     | fast      | 4–8               | 2–4                |
+| simple     | medium    | 4–8               | 3–5                |
+| simple     | slow      | 3–6               | 2–4                |
+| comparison | fast      | 12–20             | 5–10               |
+| comparison | medium    | 10–18             | 5–10               |
+| comparison | slow      | 8–14              | 4–8                |
+| complex    | fast      | 20–35             | 8–15               |
+| complex    | medium    | 18–30             | 8–15               |
+| complex    | slow      | 14–24             | 6–12               |
+| any        | permanent | -50% the slow row | -                  |
 
-Adjust ±2 queries based on decomposition count and playbook depth.
+These are starting points — the diminishing-returns detector in research-query may stop earlier.
 
-## 7. Emit `scout-plan.json`
+## 8. Emit `scout-plan.json`
 
 Write to `$SESSION_DIR/scout-plan.json`:
 
@@ -92,14 +97,16 @@ Write to `$SESSION_DIR/scout-plan.json`:
 	"decomposition": [
 		"What are the canonical RSC data-fetching patterns in Next.js 15?",
 		"How does parallel fetch via Promise.all interact with cache()?",
-		"...",
+		"What are the failure modes (waterfalls, hydration mismatches)?",
 	],
+	"independent_subquestions": [0, 1, 2], // indices into decomposition that can fan out in parallel
 	"domain": "software-engineering",
 	"playbook": "library-evaluation",
 	"content_type_bucket": "fast",
 	"freshness_window_days": 90,
+	"effort_tier": "comparison", // simple | comparison | complex
 	"decision_required": false,
-	"estimated_queries": 12,
+	"estimated_queries": 14,
 	"estimated_minutes": 8,
 	"cache_strategy": "delta-update", // reuse | delta-update | full-research
 	"existing_doc": "docs/research/react-server-components-data-fetching.md",
@@ -109,17 +116,16 @@ Write to `$SESSION_DIR/scout-plan.json`:
 }
 ```
 
-## 8. Return summary (≤5 lines)
+## 9. Return summary (≤5 lines)
 
-Return to the orchestrator a short text with: slug, decomposition count,
-estimated queries, cache strategy, and any blockers. The orchestrator
-prints a one-line summary and immediately dispatches research-query (no
-confirmation gate — user can interrupt mid-run).
+Return to the orchestrator a short text with: slug, decomposition count, effort tier, parallel fan-out count (length of `independent_subquestions`), estimated queries, cache strategy, blockers. The orchestrator prints a one-line summary and immediately dispatches research-query (no confirmation gate — user can interrupt mid-run).
 
 # Hard rules
 
 1. **Never call WebSearch or WebFetch.** That is research-query's job.
 2. **Never write to `/docs/research/<slug>.md`.** That is synthesize's job.
-3. **No fabrication.** If unsure of bucket, mark `content_type_bucket: "unknown"` and add a blocker.
+3. **No fabrication.** If unsure of bucket or tier, mark `"unknown"` and add a blocker.
 4. **Stop at scout-plan.json.** Do not chain into queries.
 5. **Honor cache hits.** If verdict is `reuse`, set `cache_strategy: "reuse"` and recommend skipping query phase.
+6. **Be generous with `independent_subquestions`.** Sub-questions are independent unless one literally requires another's answer as input. Parallelism is the biggest latency win in this pipeline.
+7. **`effort_tier` is canonical** — research-query reads it to choose between serial / 2-4-parallel / 5-10+-parallel execution. Don't fudge it.