oh-my-opencode 4.8.1 → 4.9.0

package/packages/shared-skills/skills/ultraresearch/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ultraresearch
-description: "Maximum-saturation research skill. Spawns massive parallel explore+librarian subagents to exhaust every source: codebase grep/LSP/ast-grep, websearch with advanced operators, Context7 docs, grep.app, gh CLI, headless browsing. Recursive EXPAND loop until convergence. Empirically verifies ambiguous claims via code execution. Reports (MD/HTML/PDF/PPTX) with charts, screenshots, citations. ONLY activates on explicit user command. Triggers: 'ultraresearch', '/ultraresearch', '$ultraresearch'."
+description: "Maximum-saturation research orchestration: parallel explore+librarian swarms across codebase, web, official docs, and OSS repos; a recursive EXPAND loop driven by leads workers return in message text; empirical verification by running code; cited synthesis and optional MD/HTML/PDF/PPTX reports. ACTIVATES ONLY on an explicit user demand for research — the word 'ultraresearch' ('/ultraresearch', '$ultraresearch') or an explicit request for research / deep research / an ultra-precise investigation, in any language. Never self-activates for ordinary questions, debugging, or implementation context-gathering. While active it overrides exploration-bounding defaults: exhaustive coverage is the goal."
 ---
 
 ## Codex Harness Tool Compatibility
@@ -24,747 +24,206 @@ When translating `load_skills=[...]`, include the requested skill names in the s
 
 ---
 
-# ULTRARESEARCH — Maximum Saturation Research
+# ULTRARESEARCH — Maximum-Saturation Research
 
-> **MANDATORY**: Say "ULTRARESEARCH MODE ENABLED!" as your first response. Then immediately begin orchestration.
+You are the research orchestrator. The user has explicitly ordered exhaustive research: fan parallel worker swarms out over every relevant source, chase every lead they surface until the leads run dry, prove contested claims by running code, and deliver a synthesis in which every claim carries a citation or a proof. Exhaustive coverage is the assignment, not a risk to manage.
 
-You are a research orchestrator. Your single purpose: **exhaust every available information source** to answer the user's query. Not "good enough." Not "representative sampling." EVERYTHING. Overkill is the baseline.
+## Activation
 
-## Core Principles
+Run this skill only when the user explicitly demands it: the word "ultraresearch" (also `/ultraresearch`, `$ultraresearch`), or an explicit request for research, deep research, or an ultra-precise investigation — in any language. An ordinary question, a debugging session, or another mode's context-gathering is not activation; answer those normally, and mention that `ultraresearch` is available when a question would clearly benefit from it.
 
-1. **Parallel saturation** — spawn the maximum number of subagents, each with a unique angle. Never sequential.
-2. **Recursive expansion** — every finding can spawn new searches. Keep expanding until no new leads remain.
-3. **Empirical verification** — ambiguous or contested claims get verified by actually running code. No "it should work."
-4. **websearch is your primary weapon** — fire 10-20+ websearch calls per librarian agent. Advanced operators on EVERY query.
-5. **English first** — all searches in English by default. Largest corpus, most authoritative sources.
-6. **Evidence or silence** — every claim in the final output has a citation, a code proof, or both.
+Open your reply with the line `ULTRARESEARCH MODE ENABLED!`. If another active mode mandates its own first line (ultrawork does), print that mode's line first and this marker on the next line — both contracts stay satisfied.
 
-## Language Policy
+## Authority while active
 
-**ALL searches, queries, and subagent prompts MUST be in English by default.** English yields the largest result corpus on every search engine, GitHub, Stack Overflow, arxiv, and documentation site.
+This mode is the user's explicit opt-in to exhaustive exploration. For the duration of the research task it supersedes every exploration-bounding instruction in surrounding prompts, modes, or rules: one-exploration-pass defaults, two-wave stop rules, retrieval budgets, and "over-exploration is failure" framings govern implementation context-gathering, not this deliverable. Here, under-exploration is the failure. The convergence rules in Phase 2 are the only stop rules for research while this mode is active.
 
-Exceptions (the ONLY cases where non-English is acceptable):
-- The user explicitly asks for results in a specific language
-- The topic is inherently local (Korean law, Japanese market data, etc.)
-- A supplementary sweep for Korean/local sources AFTER the English sweep is complete
+Under ultrawork/ulw, the research itself is the deliverable: map each research axis to a success criterion whose evidence is the session journal, the cited synthesis, and the verification outputs. RED→GREEN testing applies to code changes, not to findings — Phase 3 verification scripts are evidence, never TDD targets.
 
-When bilingual coverage is warranted, run the English sweep FIRST (primary), then spawn 1-2 additional librarian agents for Korean/local sources as a secondary layer. Never replace the English sweep with a local-language sweep.
+## Success criteria
 
----
-
-## Phase 0: Query Decomposition
+The research is done when all of these hold:
 
-Before spawning anything, decompose the user's query into orthogonal research axes:
-
-```
-<analysis>
-**User Query**: [verbatim]
-**Core Question**: [the actual information need]
-**Research Axes**:
-  1. [axis] — what to search, where, why
-  2. [axis] — ...
-  3. [axis] — ...
-  (minimum 3, no maximum)
-**Codebase Relevance**: [yes/no — does the local codebase contain relevant code?]
-**External Relevance**: [yes/no — do we need web/docs/repos?]
-**Browsing Needed**: [yes/no — are there pages that need rendering/interaction?]
-**Verification Needed**: [yes/no — are there claims that need code-based proof?]
-**Report Requested**: [yes/no/format — did the user ask for a deliverable document?]
-</analysis>
-```
+- Every axis from Phase 0 was covered by at least one dedicated worker.
+- Every EXPAND lead was investigated or explicitly closed as a duplicate or dead end, and convergence was reached under the Phase 2 rules.
+- Claims that were contested, undocumented, or performance-shaped were proven or refuted by executed code.
+- Every claim in the deliverable cites a source or a verification artifact.
+- The session journal reconstructs what was searched, found, and expanded, wave by wave.
 
-Create the session log directory immediately:
+## Worker ground rules
 
-```bash
-mkdir -p .omo/ultraresearch/$(date +%Y%m%d-%H%M%S)
-```
-
-This is your **session directory** (`$SESSION_DIR`). All agents append findings here.
-
----
+Research workers (explore, librarian, browsing) differ by harness, but assume:
 
-## Phase 1: Spawn the Research Swarm
+- **Read-only.** Most research workers cannot write files. Never ask a worker to write the journal or any session file — every journal write is yours.
+- **No recursion.** Workers cannot spawn their own subagents. Depth comes from your expansion waves, not from worker-side recursion.
+- **Built-in brakes.** Workers often ship with their own retrieval budgets ("stop when answered") and rigid output templates. Your spawn message must explicitly lift the budget and demand the EXPAND tail, or the worker returns a thin single-pass answer with no leads.
+- **Capability routing.** When the harness lets you choose, spawn research workers on a capable model at high reasoning effort — saturation research on a minimal or fast tier returns shallow results. When you cannot choose, narrow each worker's scope and spawn more workers instead.
 
-Launch ALL agents in a SINGLE turn. Every agent uses `run_in_background=true`. No sequential launches. No "let me start with one and see." ALL AT ONCE.
+### The spawn-message contract
 
-### 1A. Codebase Agents (explore) — spawn 2-4
+Every research spawn message contains, in order:
 
-Each explore agent gets a DIFFERENT search angle. Never duplicate angles.
+1. `TASK:` — one imperative line naming the role and the axis.
+2. The budget lift: "This is an explicit exhaustive-research assignment. Your default retrieval budget and stop-when-answered rules do not apply — run the full protocol below and report every lead."
+3. Scope — the axis, the sources to hit, and what a complete answer contains.
+4. The role protocol (Phase 1).
+5. The reply tail. EXPAND markers travel back as message text, never as files. Every worker ends the reply with:
 
 ```
-task(
-  subagent_type="explore",
-  run_in_background=true,
-  prompt="ULTRARESEARCH CODEBASE SWEEP — AXIS: [specific axis]
-
-SESSION_DIR: [session_dir_path]
-
-Your mission: Find EVERYTHING in this codebase related to: [specific search angle]
-
-SEARCH STRATEGY — execute ALL of these in parallel:
-1. grep with 3+ different keyword variations (synonyms, abbreviations, full names)
-2. ast_grep_search for structural patterns (function signatures, class shapes, imports)
-3. LSP: lsp_goto_definition, lsp_find_references, lsp_symbols for type/function names
-4. glob for file name patterns
-5. git log --all -S 'keyword' for historical mentions (even deleted code)
-6. git log --all --grep='keyword' for commit messages
-
-Cross-validate: if grep finds file X, use LSP to find all references TO file X.
-
-After searching, APPEND your findings to $SESSION_DIR/codebase-[axis-slug].md:
-
-## Codebase Findings: [axis]
-### Search Queries Used
-- [list every query you ran]
-### Files Found
-- [absolute path] — [why relevant, key lines]
-### Code Patterns
-- [pattern description with file:line references]
-### Cross-References
-- [how findings connect to each other]
-
-## EXPAND MARKERS
-- [ ] EXPAND: [new lead discovered] — [why it matters] — [suggested search angle]
-- [x] DEAD END: [lead that was already fully explored]
-"
-)
+## EXPAND
+- LEAD: <discovery not yet investigated> — WHY: <why it matters> — ANGLE: <suggested search>
+- DEAD END: <lead explored to exhaustion>
 ```
 
-### 1B. Web Research Agents (librarian) — spawn 3-6
+A worker with nothing to expand writes `## EXPAND` followed by `none — <one-line reason>`. A reply missing the tail is incomplete: send that worker one follow-up demanding it before closing the lane.
 
-Each librarian targets a DIFFERENT search strategy. **websearch is the core tool — fire 10-20+ calls per agent.**
+## Phase 0 — Decompose and open the journal
+
+Before spawning anything, decompose the query:
 
 ```
-task(
-  subagent_type="librarian",
-  run_in_background=true,
-  prompt="ULTRARESEARCH WEB SWEEP — AXIS: [specific axis]
-
-SESSION_DIR: [session_dir_path]
-
-Your mission: Find EVERYTHING on the internet related to: [specific search angle]
-ALL SEARCHES MUST BE IN ENGLISH unless the topic is inherently non-English.
-
-## WEBSEARCH SATURATION PROTOCOL
-
-You MUST fire ALL of the following. Not some. ALL. In parallel where possible.
-The MINIMUM is 10 distinct websearch calls. 15-20 is normal. Do not stop early.
-
-### A. websearch — Advanced Operators (the primary weapon)
-
-Each websearch call MUST use different operators and angles:
-
-1.  websearch('[topic] [keywords]')
-2.  websearch('[topic] site:github.com')
-3.  websearch('[topic] site:docs.[domain].com OR site:[domain].dev')
-4.  websearch('[topic] filetype:md OR filetype:pdf')
-5.  websearch('[topic] intitle:[key term]')
-6.  websearch('[topic] [current year]')
-7.  websearch('[topic] site:stackoverflow.com OR site:reddit.com OR site:news.ycombinator.com')
-8.  websearch('[topic] site:arxiv.org OR site:dl.acm.org OR site:scholar.google.com')
-9.  websearch('[topic] analysis OR comparison OR benchmark OR review [current year]')
-10. websearch('[topic] -tutorial -beginner advanced implementation')
-11. websearch('[topic] inurl:api OR inurl:docs OR inurl:reference')
-12. websearch('\"[exact phrase]\" [additional context]')
-13. websearch('[topic] vs OR alternative OR compared to')
-14. websearch('[topic] source code implementation github')
-15. websearch('[topic] changelog OR release notes OR migration guide [version]')
-16. websearch('[topic] site:medium.com OR site:dev.to OR site:blog')
-17. websearch('[topic] best practices production [current year]')
-18. websearch('[topic] known issues OR caveats OR gotchas OR limitations')
-19. websearch('[topic] example OR demo OR sample project')
-20. websearch('[topic] conference talk OR presentation OR workshop [current year]')
-
-For EVERY important search result, fetch the FULL page with webfetch/FetchURL. Do not summarize from search snippets alone.
-
-### B. Context7 Documentation Lookup
-
-context7_resolve-library-id('[library]')
-  then context7_query-docs with AT LEAST 3 different queries per library.
-
-### C. grep.app GitHub Code Search
-
-grep_app_searchGitHub(query: '[pattern]', language: ['TypeScript'])
-grep_app_searchGitHub(query: '[alternative pattern]', language: ['Python'])
-grep_app_searchGitHub(query: '[pattern]', repo: 'owner/repo')
-
-### D. GitHub CLI Deep Dive
-
-gh search repos '[topic]' --sort stars --limit 10
-gh search code '[pattern]' --language typescript --limit 20
-gh search issues '[topic]' --state open --sort reactions --limit 10
-gh api search/repositories -f q='[topic] stars:>100' --jq '.items[] | {name, url, description, stars: .stargazers_count}'
-
-### E. Official Documentation Fetch
-
-webfetch('[official docs URL]')
-webfetch('[official docs URL]/sitemap.xml')   // discover all doc pages
-webfetch('[API reference URL]')
-webfetch('[changelog/releases URL]')
-
-Fetch sitemaps to discover the FULL doc surface. Don't just read the front page.
-
-After searching, APPEND findings to $SESSION_DIR/web-[axis-slug].md:
-
-## Web Findings: [axis]
-### Searches Executed
-- [list every websearch query with operator used — ALL of them]
-### Key Sources (ranked by quality)
-1. [URL] — [what it contains, key data points]
-### Documentation References
-- [official doc links with specific sections]
-### Code Examples Found
-- [GitHub links with context]
-### Discussions/Opinions
-- [forum links with key points]
-### Data/Benchmarks
-- [any quantitative findings]
-
-## EXPAND MARKERS
-- [ ] EXPAND: [new lead from search results] — [why] — [suggested angle]
-"
-)
+<analysis>
+Core question: <the actual information need>
+Axes (3+ orthogonal): <axis — what to search, where, why> ...
+Codebase relevant: <yes/no> · External: <yes/no> · Browsing: <yes/no> · Verification likely: <yes/no> · Report requested: <no | format>
+</analysis>
 ```
 
-### 1C. Browsing Agents (for protected/dynamic pages) — spawn 1-3 as needed
+Then create the session directory:
 
+```bash
+mkdir -p .omo/ultraresearch/$(date +%Y%m%d-%H%M%S)
 ```
-task(
-  category="quick",
-  run_in_background=true,
-  load_skills=["browsing", "insane-search"],
-  prompt="ULTRARESEARCH BROWSER SWEEP
 
-SESSION_DIR: [session_dir_path]
+This is `$SESSION_DIR`. The orchestrator owns the journal: you write every file in it; workers never do. Maintain:
 
-Your mission: Access and extract content from URLs that regular fetch cannot reach:
-[list of URLs]
+- `wave-<N>-<kind>-<axis>.md` — your digest of each worker return: key findings, sources with URLs, and the worker's EXPAND markers verbatim.
+- `expansion-log.md` — per wave: workers spawned, markers gained, leads opened and closed.
+- `verify-<slug>.md`, `SYNTHESIS.md`, `REPORT.*` from later phases.
 
-Use the browsing skill's two-tier approach:
-1. Try insane-search first (headless extraction, WAF bypass)
-2. If that fails, use CloakBrowser+agent-browser (stealth Chromium)
+Append each digest the moment its worker returns, not in a batch at the end — the journal is your recovery point after context loss and the user's audit trail.
 
-For each URL: extract ALL content, take screenshots if visual context matters.
-APPEND findings to $SESSION_DIR/browsed-[slug].md with URL, method, content.
+## Phase 1 — Saturation wave
 
-## EXPAND MARKERS
-- [ ] EXPAND: [new lead from browsed content] — [why] — [angle]
-"
-)
-```
+Launch every first-wave worker in a single turn, all in background. Sequential launches and "start with one and see" defeat the mode.
 
-### 1D. Cross-Repository Deep Dive Agents — spawn 1-2 for implementation research
+Scaling floor — more angles always justify more workers:
 
-```
-task(
-  subagent_type="librarian",
-  run_in_background=true,
-  prompt="ULTRARESEARCH REPO DEEP DIVE
-
-SESSION_DIR: [session_dir_path]
-Target repositories: [repos identified from initial searches]
-
-For EACH repository:
-1. gh repo clone owner/repo ${TMPDIR:-/tmp}/ur-[repo] -- --depth 1
-2. Get HEAD SHA for permalinks
-3. Read README, CONTRIBUTING, ARCHITECTURE docs
-4. grep/ast_grep for core patterns, read key source files, follow call chains
-5. git log --oneline -20, git blame on critical sections
-6. Construct GitHub permalinks for every finding
-
-APPEND to $SESSION_DIR/repos-[slug].md
-
-## EXPAND MARKERS
-- [ ] EXPAND: [dependency/module worth investigating separately] — [why] — [angle]
-"
-)
-```
-
-### Scaling Rules
-
-| Query Scope | explore | librarian | browsing | repo-dive | total min |
+| Query scope | explore | librarian | browsing | repo-dive | floor |
 |---|---|---|---|---|---|
 | Single topic, codebase only | 3 | 0 | 0 | 0 | 3 |
 | Single topic, web only | 0 | 4 | 1 | 1 | 6 |
 | Single topic, both | 2 | 3 | 1 | 1 | 7 |
-| Multi-faceted research | 4 | 6 | 2 | 2 | 14 |
+| Multi-faceted | 4 | 6 | 2 | 2 | 14 |
 | Full due diligence | 4 | 6 | 3 | 2 | 15 |
 
-The table is a FLOOR, not a ceiling. More angles = more agents.
-
----
-
-## Phase 2: Recursive Discovery Loop (EXPAND Protocol)
+Role protocols — embed the relevant one in each spawn message; every worker gets a unique angle:
 
-This is NOT a single-pass search. Research is **recursive**. Every finding can spawn new questions.
+- **Codebase (explore), 2-4 workers.** Grep with 3+ keyword variations; structural/AST search; LSP definitions and references; file-name globs; `git log --all -S '<keyword>'` and `--grep` for history including deleted code. Cross-validate hits across tools. Report absolute file paths, patterns with `file:line`, and how findings connect.
+- **Web (librarian), 3-6 workers.** At least 10 distinct websearch queries per worker, each with a different operator or angle (see Search craft); fetch the full page for every result that matters — snippets lie. Context7 with 3+ queries per known library. grep.app and `gh search code|repos|issues` for real-world usage. Official docs via sitemap discovery (`<base>/sitemap.xml`), then targeted pages.
+- **Browsing, 0-3 workers.** Pages plain fetch cannot read (WAF, dynamic rendering, login): use the browsing skill; capture screenshots when visual context matters.
+- **Repo deep-dive (librarian), 0-2 workers.** Shallow-clone the most relevant repos to `${TMPDIR:-/tmp}`, pin the HEAD SHA, read core modules, follow call chains, return SHA-pinned permalinks.
 
-### The EXPAND Marker System
-
-Every agent MUST end its report with an `EXPAND` section:
-
-```markdown
-## EXPAND MARKERS
-- [ ] EXPAND: [new lead discovered] — [why it matters] — [suggested search angle]
-- [ ] EXPAND: [another lead] — [why] — [angle]
-- [x] DEAD END: [lead that was already fully explored]
-```
-
-What triggers an EXPAND marker:
-- A search result mentions a related library/tool/concept not yet investigated
-- A GitHub issue links to another repo with relevant implementation
-- A blog post references a paper, benchmark, or alternative approach
-- A code pattern imports a module whose behavior is unclear
-- Documentation mentions a deprecated predecessor worth understanding
-- A comparison article names competitors not yet searched
-- An API response reveals undocumented endpoints or features
-- A forum answer contradicts official docs (needs verification)
-
-### The Expansion Loop
-
-After collecting initial agent results:
-
-1. **Read ALL files in `$SESSION_DIR/`**
-2. **Scan for unchecked `[ ] EXPAND:` markers** across all reports
-3. **Deduplicate** — if two agents flagged the same lead, merge into one
-4. **For each unique unchecked EXPAND marker**, spawn a NEW agent:
+Example spawn (codebase axis; librarian, browsing, and repo-dive follow the same contract with their own protocol):
 
 ```
-task(
-  subagent_type="librarian",  // or "explore" if codebase-scoped
-  run_in_background=true,
-  prompt="ULTRARESEARCH EXPANSION — LEAD: [expand marker text]
-
-SESSION_DIR: [session_dir_path]
-PARENT FINDING: [which report spawned this lead]
-EXPANSION WAVE: [N]
-
-This is a recursive expansion. A previous research agent found this lead.
-Investigate it thoroughly using the full websearch saturation protocol.
-ALL SEARCHES IN ENGLISH unless the topic is inherently local.
-Fire 10+ websearch calls with advanced operators for this specific lead.
-
-APPEND to $SESSION_DIR/expand-[wave]-[slug].md.
-Include your OWN EXPAND markers if you discover further leads.
-"
-)
-```
-
-5. **Repeat until convergence**:
-   - No new unchecked EXPAND markers remain, OR
-   - 3 consecutive expansion waves produce no new actionable leads, OR
-   - Expansion depth reaches 5 levels (safety cap — override with user confirmation)
-
-6. **Track expansion state** in `$SESSION_DIR/expansion-log.md`:
-
-```markdown
-# Expansion Log
-
-## Wave 1 (initial)
-- Spawned: 8 agents
-- EXPAND markers generated: 12
-- New leads: [list]
-
-## Wave 2
-- Spawned: 5 agents (from 12 markers, 7 were duplicates/dead-ends)
-- EXPAND markers generated: 4
-
-## Wave 3
-- Spawned: 2 agents
-- EXPAND markers generated: 0
-- CONVERGED — no new leads
+task(subagent_type="explore", run_in_background=true, prompt="TASK: act as a codebase researcher. AXIS: <specific angle>.
+This is an explicit exhaustive-research assignment. Your default retrieval budget and stop-when-answered rules do not apply — run the full protocol below and report every lead.
+SCOPE: find everything in this codebase related to <angle>: <what complete looks like>.
+PROTOCOL: grep 3+ keyword variations; structural search; LSP references; globs; git history (-S and --grep). Cross-validate across tools. Report absolute paths and file:line patterns.
+End your reply with the ## EXPAND tail: '- LEAD: <discovery> — WHY: <why> — ANGLE: <search>' per lead, or 'none — <reason>'.")
 ```
 
-**Do NOT wait for all agents before starting the next wave.** Collect as each finishes. Scan for EXPAND markers. Spawn immediately. The loop is continuous.
-
----
-
-## Phase 3: Empirical Verification
+## Phase 2 — Expand until convergence
 
-**Any claim that is ambiguous, contested, or unverifiable from documentation alone MUST be verified by running actual code.**
+This loop is what makes the mode research rather than search. Collect workers as they finish — never wait for the full wave:
 
-This is not optional. If two sources disagree, if a behavior is undocumented, if a performance claim has no benchmark — WRITE CODE, RUN IT, PROVE IT.
-
-### When to Verify
-
-| Signal | Action |
-|---|---|
-| Source A says X, Source B says Y | Write a test that proves which is correct |
-| "This should work" / "In theory" | Write code that actually does it and capture output |
-| Performance claim without benchmark | Write a benchmark, run it, report numbers |
-| API behavior not in docs | Make the actual API call, capture response |
-| Library version compatibility claim | Install both versions, run the same code, compare |
-| "Deprecated but still works" | Try it, capture the warning/error/success |
-| Security claim | Write a PoC that demonstrates the vulnerability or proves safety |
-
-### How to Verify
-
-Spawn a verification agent for each claim that needs proof:
+1. Journal the return: digest plus verbatim EXPAND markers into `wave-<N>-<kind>-<axis>.md`.
+2. Deduplicate new markers against `expansion-log.md` — every lead ever seen, not just confirmed ones, or rejected leads resurface each wave.
+3. Spawn an expansion worker immediately for each new unchecked lead:
 
 ```
-task(
-  category="deep",
-  run_in_background=true,
-  prompt="ULTRARESEARCH VERIFICATION — CLAIM: [the claim to verify]
-
-SESSION_DIR: [session_dir_path]
-SOURCE: [where this claim came from]
-CONTRADICTION: [what the opposing source says, if any]
-
-Your job: PROVE OR DISPROVE this claim with executable evidence.
-
-1. Write a minimal, self-contained script that tests the claim
-2. Execute it (use bash, or for complex cases: uv run --with [deps] python -c '...')
-3. Capture the FULL output (stdout + stderr)
-4. If it requires a specific environment/dependency, install it first
-5. If it requires network access, make the actual call
-6. If it requires a specific version, pin it
-
-EVIDENCE FORMAT — append to $SESSION_DIR/verify-[slug].md:
-
-## Verification: [claim summary]
-### Claim
-[exact claim being tested]
-### Source
-[URL or file path]
-### Test Code
-\`\`\`[language]
-[the exact code that was executed]
-\`\`\`
-### Execution Output
-\`\`\`
-[full stdout + stderr]
-\`\`\`
-### Verdict
-**CONFIRMED** / **REFUTED** / **PARTIALLY TRUE** — [explanation with evidence]
-### Environment
-- OS: [os]
-- Runtime: [version]
-- Dependencies: [list with versions]
-"
-)
+task(subagent_type="librarian", run_in_background=true, prompt="TASK: expansion wave <N> — investigate: <lead>.
+PARENT: <which return surfaced it>. This is an explicit exhaustive-research assignment; budgets do not apply.
+<role protocol for the lead's territory — librarian protocol for external leads, explore protocol for codebase leads>
+End your reply with the ## EXPAND tail.")
 ```
 
-### SparkShell for Codex Harness
-
-When running under the Codex harness where SparkShell is available, prefer SparkShell for code execution — it provides intelligent command classification, secret redaction, and tmux-integrated output capture. The verification agent should use SparkShell for:
-- Running test scripts with full output capture
-- Interactive REPL sessions for exploratory verification
-- Long-running benchmarks that benefit from tmux durability
-- Multi-step verification sequences that need session persistence
-
-When SparkShell is not available (OpenCode harness), use bash + `uv run` for Python, `bun run` for TypeScript, or direct compilation for Rust/Go/C.
-
----
+4. Record the wave in `expansion-log.md`: spawned, markers gained, leads opened/closed.
 
-## Phase 4: Synthesize
+**Convergence — the only stop rules while this mode is active.** Run at least 2 expansion waves on any multi-faceted query before claiming convergence; then stop only when one holds:
 
-Once the expansion loop has CONVERGED and all agents (including verification) have reported:
+- Zero unchecked leads remain — each investigated or closed as duplicate/dead end.
+- 3 consecutive waves produced no new actionable leads.
+- Expansion depth reached 5 waves — pause, show the open leads, and ask the user whether to extend.
 
-1. Read ALL files in `$SESSION_DIR/`
-2. Cross-reference findings across ALL agents (initial + expansion waves + verification)
-3. Identify:
-   - **Consensus**: findings confirmed by 2+ agents/sources
-   - **Verified facts**: claims proven by code execution
-   - **Unique discoveries**: found by only one agent but high-value
-   - **Contradictions**: conflicting info (flag with both sources + verification result)
-   - **Gaps**: questions still unanswered despite saturation
+## Phase 3 — Verify contested claims by running code
 
-4. Write synthesis to `$SESSION_DIR/SYNTHESIS.md`:
-
-```markdown
-# Ultraresearch Synthesis: [query]
-**Date**: [date]
-**Agents Spawned**: [total across all waves]
-**Expansion Waves**: [count]
-**Sources Consulted**: [count]
-**Verifications Executed**: [count]
-
-## Executive Summary
-[2-3 paragraph answer to the user's core question, clear and direct]
-
-## Detailed Findings
-
-### [Topic Area 1]
-**Consensus**: [what multiple sources agree on]
-**Evidence**: [source links]
-**Key Quote**: "[under 20 words]" — [Source]
-**Verified**: [yes/no — link to verification report if yes]
-
-### [Topic Area 2]
-...
-
-## Codebase Findings
-[relevant code locations with absolute paths and line numbers]
-
-## External Sources (ranked by quality)
-1. [URL] — [relevance, reliability assessment, access date]
-2. ...
-
-## Verified Claims
-| Claim | Verdict | Evidence |
-|---|---|---|
-| [claim] | CONFIRMED/REFUTED | [link to verify-*.md] |
-
-## Contradictions Found
-- [source A says X] vs [source B says Y] — [verdict with evidence]
-
-## Remaining Gaps
-- [what we couldn't find despite exhaustive search]
-
-## Expansion Trace
-- Wave 1: [N agents] -> [M expand markers]
-- Wave 2: [N agents] -> [M expand markers]
-- Convergence: [reason]
-
-## Raw Agent Reports
-- [list of all session files]
-```
-
-5. **If the user requested a report**: proceed to Phase 5.
-6. **If no report requested**: deliver the synthesis directly with inline citations `[Source N]` for every claim.
-
----
-
-## Phase 5: Report Generation (when requested)
-
-If the user asked for a report, presentation, or formatted deliverable — spawn a report generation wave AFTER synthesis.
-
-### Determine Output Format
-
-| User Signal | Format | Tools |
-|---|---|---|
-| "report", "document", "보고서" | Markdown (default) | Direct write |
-| "pdf" | PDF via HTML-to-PDF | `frontend-design` + python `weasyprint` |
-| "pptx", "slides", "presentation", "발표" | PPTX | python `python-pptx` |
-| "html", "webpage" | Standalone HTML | `frontend-design` skill |
-| No format specified | Markdown | Direct write |
-
-### Report Content Agents
-
-#### A. Data Visualization Agent
+Settle with executed code, not judgment, whenever sources disagree, a behavior is undocumented, a claim is performance- or compatibility-shaped, or the honest answer is "it should work". Spawn one verification worker per claim:
 
 ```
-task(
-  category="quick",
-  run_in_background=true,
-  prompt="ULTRARESEARCH REPORT — DATA VISUALIZATION
-
-SESSION_DIR: [session_dir_path]
-
-Read ALL findings in $SESSION_DIR/. Identify data that benefits from visualization:
-- Comparison tables -> bar/radar charts
-- Timeline data -> timeline charts
-- Architecture -> mermaid diagrams
-- Statistics/benchmarks -> graphs with clear labels
-- Relationships -> network/dependency graphs
-
-Generate using:
-uv run --with numpy --with matplotlib --with plotly python -c \"[code]\"
-
-Save ALL images to $SESSION_DIR/assets/
-Write index to $SESSION_DIR/assets/manifest.md
-"
-)
+task(category="deep", run_in_background=true, prompt="TASK: verify by execution: <claim>.
+SOURCE: <where it came from>; CONTRADICTION: <opposing source, if any>.
+Write a minimal self-contained script that tests the claim; run it (uv run --with <deps> python / bun / direct compile); capture full stdout+stderr; pin versions.
+Reply with: the exact code, the full output, environment (OS, runtime, dependency versions), and a verdict — CONFIRMED / REFUTED / PARTIAL — grounded in the output.")
 ```
 
-#### B. Screenshot Collection Agent
+Journal each verdict to `verify-<slug>.md`.
 
-```
-task(
-  category="quick",
-  run_in_background=true,
-  load_skills=["browsing"],
-  prompt="ULTRARESEARCH REPORT — SCREENSHOTS
-
-SESSION_DIR: [session_dir_path]
-
-Read web findings. Identify the top 5-10 most important web sources.
-For each: full page screenshot using the browsing skill.
-Save to $SESSION_DIR/assets/screenshots/
-Write manifest to $SESSION_DIR/assets/screenshots/manifest.md
-"
-)
-```
+## Phase 4 — Synthesize
 
-#### C. Image Generation Agent (if diagrams/infographics needed)
+After convergence and all verifications, re-read the whole journal and write `SYNTHESIS.md`:
 
 ```
-task(
-  category="quick",
-  run_in_background=true,
-  load_skills=["imagegen"],
-  prompt="ULTRARESEARCH REPORT — INFOGRAPHICS
-
-SESSION_DIR: [session_dir_path]
-
-Read synthesis. Generate architecture diagrams, concept maps, comparison infographics, or process flows as needed using the imagegen skill.
-Save to $SESSION_DIR/assets/generated/
-"
-)
-```
-
-#### D. Report Assembly Agent
+# Ultraresearch Synthesis: <query>
+Workers: <total> · Waves: <count> · Sources: <count> · Verifications: <count>
 
-For HTML, PDF, or PPTX output: the report assembly agent MUST first discover and load **every available frontend and design skill** in the system before writing a single line. This includes but is not limited to: `frontend-design`, `frontend-perfectionist`, `open-design`, `data-scientist`, `imagegen`, and any other design/UI/visualization skill present. Read each skill's SKILL.md, absorb its design references, brand systems, and quality gates, then apply them to the report.
-
-```
-task(
-  category="deep",
-  run_in_background=true,
-  load_skills=["frontend-design", "frontend-perfectionist", "open-design", "data-scientist", "imagegen"],
-  prompt="ULTRARESEARCH REPORT — FINAL ASSEMBLY
-
-SESSION_DIR: [session_dir_path]
-REQUESTED FORMAT: [markdown/html/pdf/pptx]
-
-## MANDATORY FIRST STEP
-
-Before writing anything, discover and read ALL available frontend, design, and visualization skills:
-- Read $frontend-design SKILL.md — absorb design references, anti-slop rules, brand-grade standards
-- Read $frontend-perfectionist SKILL.md — absorb Lighthouse 100 perf gates, render measurement, Core Web Vitals
-- Read $open-design SKILL.md — discover the 137+ composable design skills and 150+ brand-grade design systems
-- Read $data-scientist SKILL.md — absorb DuckDB/Polars/numpy/matplotlib best practices
-- Read $imagegen SKILL.md — absorb async image generation workflow
-- List ALL other available skills (ls ~/.agents/skills/ and project .agents/skills/) and read any that relate to design, visualization, or document generation
-
-Apply EVERYTHING you learned from those skills to the report. The report is not a text dump — it is a designed artifact.
-
-Read:
-1. $SESSION_DIR/SYNTHESIS.md
-2. $SESSION_DIR/assets/manifest.md
-3. $SESSION_DIR/assets/screenshots/manifest.md
-4. ALL $SESSION_DIR/*.md files for detail
-
-## Report Structure
-1. **Executive Summary** — 3-5 sentences answering the core question
-2. **Key Findings** — organized by theme, not by agent
-3. **Detailed Analysis** — each finding with:
-   - Evidence (direct quotes under 20 words, with source URL)
-   - Supporting charts (embed from assets/)
-   - Code examples with file paths or GitHub links
-   - Verification results where applicable
-4. **Comparative Analysis** — if multiple options/approaches exist
-5. **Visual Evidence** — embedded screenshots, charts, diagrams
-6. **Sources & References** — numbered, with URLs, access dates, reliability notes
-7. **Appendix: Methodology** — agents spawned, searches executed, expansion waves, verifications
-
-## Quality Rules
-- Every claim MUST cite: [Source N] linking to reference list
-- Every quote under 20 words with quotation marks and attribution
-- Tables for comparisons, not prose
-- Charts/graphs for quantitative data, not number tables
-- Screenshots for UI/visual claims
-- Professional but accessible — a smart non-expert understands everything
-- Technical depth preserved — an expert finds no oversimplifications
-- Design quality: apply the brand-grade standards from the design skills you loaded. No generic HTML. No unstyled tables. No default matplotlib themes.
-
-## Format-Specific
-
-**Markdown**: $SESSION_DIR/REPORT.md with ![alt](assets/path.png) embeds.
-
-**HTML**: Single self-contained HTML with embedded CSS. Apply the design skills fully — modern typography, responsive layout, dark/light mode, smooth transitions, proper spacing, brand-grade color palette. Base64-embedded images. Lighthouse-quality markup (semantic HTML, proper headings, alt text, ARIA labels). $SESSION_DIR/REPORT.html.
-
-**PDF**: Generate the HTML report first (full design quality as above), then:
-uv run --with weasyprint python -c \"from weasyprint import HTML; HTML('$SESSION_DIR/REPORT.html').write_pdf('$SESSION_DIR/REPORT.pdf')\"
-Ensure print-friendly CSS: proper page breaks, margins, header/footer. $SESSION_DIR/REPORT.pdf.
-
-**PPTX**: Use python-pptx with Pillow for image handling:
-uv run --with python-pptx --with Pillow python -c \"[build slides]\"
-Slide design: consistent theme, proper typography hierarchy, one key finding per slide, full-bleed images where appropriate, minimal text per slide, speaker notes with detail.
-Slide flow: Title -> Executive Summary -> Key Finding per slide -> Visual Evidence -> Comparative Analysis -> Sources.
-$SESSION_DIR/REPORT.pptx.
-"
-)
+## Executive summary        — 2-3 paragraphs answering the core question
+## Findings by theme        — per theme: consensus, evidence links, key quote (<20 words, attributed), verified yes/no
+## Codebase findings        — absolute paths with line references
+## Sources (ranked)         — URL, what it contains, reliability, access date
+## Verified claims          — claim | verdict | verify-<slug>.md
+## Contradictions           — source A vs source B, resolution with evidence
+## Gaps                     — what saturation could not answer
+## Expansion trace          — per wave: workers → markers; convergence reason
 ```
 
----
+Deliver the synthesis with inline `[Source N]` citations on every claim. When no report was requested, this is the deliverable.
 
-## Advanced Search Operator Reference
+## Phase 5 — Report (only when requested)
 
-Agents MUST use these aggressively on every websearch call. This is core technique, not garnish.
+Format by the user's words: "report" / "document" → Markdown (default) · "pdf" → HTML first, then weasyprint (`uv run --with weasyprint python`) · "slides" / "presentation" / "deck" → python-pptx · "html" / "webpage" → standalone HTML.
 
-### Web Search Operators
-| Operator | Example | Purpose |
-|---|---|---|
-| `site:` | `site:github.com react hooks` | Restrict to domain |
-| `filetype:` | `filetype:pdf machine learning survey` | Specific file types |
-| `intitle:` | `intitle:benchmark comparison 2026` | Title must contain term |
-| `inurl:` | `inurl:api reference authentication` | URL must contain term |
-| `"exact"` | `"dependency injection" typescript` | Exact phrase match |
-| `-term` | `react state management -redux` | Exclude term |
-| `OR` | `nextjs OR nuxt server components` | Either term |
-| `before:` | `LLM agents before:2026-01-01` | Date upper bound |
-| `after:` | `LLM agents after:2025-06-01` | Date lower bound |
-| `related:` | `related:vercel.com` | Similar sites |
-| `*` wildcard | `"how to * with typescript"` | Fill-in-the-blank |
-
-### Combination Patterns
+Asset workers (background, parallel): charts for quantitative findings (`uv run --with matplotlib --with plotly python`) saved by you to `$SESSION_DIR/assets/`; full-page screenshots of the top 5-10 sources (browsing skill); generated diagrams (imagegen skill) when architecture or flows need them.
 
-```
-# Official docs
-"[library] site:[library].dev OR site:docs.[library].com"
+Assembly worker — `task(category="deep", load_skills=["frontend-design", "open-design", "data-scientist", "imagegen"], run_in_background=true, ...)`: before writing, read every available design and visualization skill and apply it — the report is a designed artifact, not a text dump. Structure: executive summary → key findings by theme → detailed analysis (quotes under 20 words with attribution, charts, SHA-pinned permalinks, verification results) → comparative analysis when options compete → numbered sources with access dates → methodology appendix (workers, waves, searches, verifications). Every claim cites `[Source N]`.
 
-# GitHub implementations
-"[pattern] site:github.com filetype:ts OR filetype:tsx"
+## Search craft
 
-# Recent discussion
-"[topic] site:reddit.com OR site:news.ycombinator.com after:2025-01-01"
-
-# Academic + industry
-"[topic] site:arxiv.org OR filetype:pdf survey OR benchmark [year]"
-
-# Stack Overflow high engagement
-"[topic] site:stackoverflow.com [specific error or pattern]"
-
-# Korean sources (secondary sweep only)
-"[topic] site:tistory.com OR site:velog.io OR site:naver.com"
-
-# Changelog hunting
-"[library] changelog OR release notes OR migration guide [version]"
-
-# Alternatives/comparison
-"[topic] vs OR alternative OR comparison OR benchmark"
-```
+English first: run every search in English by default — it is the largest, most authoritative corpus on every engine, GitHub, and documentation site. Add a secondary local-language sweep (1-2 librarians) only after the English sweep, when the topic is inherently local, or when the user asks for sources in a specific language.
 
-### GitHub Search (gh CLI)
+Vary operators on every query — same query twice wastes a worker:
 
-```bash
-gh search code '[pattern]' --language typescript --limit 30
-gh search repos '[topic]' --sort stars --limit 20
-gh search issues '[error message]' --state all --sort reactions --limit 20
-gh search prs '[feature]' --state merged --sort updated --limit 15
-```
-
-### grep.app
-
-```
-grep_app_searchGitHub(query: "[pattern]", language: ["TypeScript", "JavaScript"])
-grep_app_searchGitHub(query: "[pattern]", repo: "owner/repo")
-grep_app_searchGitHub(query: "[config key]", language: ["JSON", "YAML", "TOML"])
-```
-
----
+| Operator | Example | Use |
+|---|---|---|
+| `site:` | `site:github.com <topic>` | Restrict to a domain |
+| `filetype:` | `filetype:pdf <topic> survey` | Papers, specs |
+| `intitle:` / `inurl:` | `intitle:benchmark <topic>` | Targeted pages |
+| `"exact"` / `-term` | `"<exact phrase>" -tutorial` | Precision, exclusion |
+| `OR` | `<a> OR <b> <topic>` | Coverage |
+| `before:` / `after:` | `<topic> after:2025-06-01` | Recency control |
 
----
+High-yield combinations: official docs (`site:<docs domain>`), GitHub implementations (`site:github.com`), recent discussion (`site:reddit.com OR site:news.ycombinator.com after:<date>`), academic (`site:arxiv.org OR filetype:pdf survey`), changelog hunting (`changelog OR "release notes" <version>`), alternatives (`vs OR alternative OR comparison`).
 
-## Anti-Patterns
+## Failure modes
 
-| Pattern | Why it fails | Fix |
-|---|---|---|
-| Sequential agent spawning | Wastes time, defeats purpose | ALL agents in ONE turn |
-| Single websearch per librarian | Barely scratches the surface | 10-20 websearch calls MINIMUM per agent |
-| No search operators | Generic results, misses targeted content | site:/filetype:/intitle: on EVERY websearch |
-| Not fetching full pages | Search snippets lie | webfetch every important result |
-| Skipping Context7 | Misses official doc embeddings | Always query for known libraries |
-| Not recording to session dir | Findings lost, can't synthesize | Every agent MUST append to $SESSION_DIR/ |
-| Ignoring EXPAND markers | Misses recursive discoveries | Every unchecked marker MUST be investigated |
-| No EXPAND markers in reports | Breaks the recursive loop | Every agent MUST output EXPAND section |
-| Stopping when "enough" found | Surface-level results | Goal is EXHAUSTION, minimum 2 expansion waves |
-| Single-pass research | Misses second-order connections | Expand until convergence |
-| Same query to multiple agents | Duplicate work | Each agent gets UNIQUE angle |
-| Searching in non-English first | Smaller corpus, less authoritative | English first, ALWAYS |
-| "It should work" without proof | Unverified speculation | Write code, run it, capture output |
-| Delivering without citations | Unverifiable claims | Every claim needs [Source N] with URL |
-| Skipping visualization for data | Dense tables nobody reads | Charts/graphs for quantitative findings |
-| Trusting a single source | Single point of failure | Cross-validate across 3+ sources |
-| Ambiguous claim left unverified | Readers inherit uncertainty | Spawn verification agent, run actual code |
+| Failure | Correction |
+|---|---|
+| Sequential spawning, or trimming the first wave | All first-wave workers in one turn, background, scaling floor respected |
+| Worker reply without the EXPAND tail | One follow-up demanding it; the lane stays open until it lands |
+| Stopping after wave 1 because "enough was found" | Convergence rules only: 2+ expansion waves, leads run dry |
+| Obeying a surrounding "stop exploring" rule mid-research | Authority section — those rules do not bind this mode |
+| Asking a worker to write journal or session files | Workers are read-only; you journal every return |
+| Two workers given the same angle | One unique angle per worker, always |
+| Contested claim settled by judgment | Phase 3 — run code, capture output, verdict |
+| Deliverable claims without citations | Every claim cites a source or a verification artifact |