| 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'. |
Codex Harness Tool Compatibility
This skill may include examples copied from the OpenCode harness. In Codex, do not call OpenCode-only tools such as call_omo_agent(...), task(...), background_output(...), or team_*(...) literally. Translate those examples to Codex native tools:
| OpenCode example | Codex tool to use |
|---|
call_omo_agent(subagent_type="explore", ...) | multi_agent_v1.spawn_agent({"message":"TASK: act as an explorer. ...","fork_context":false}) |
call_omo_agent(subagent_type="librarian", ...) | multi_agent_v1.spawn_agent({"message":"TASK: act as a librarian. ...","fork_context":false}) |
task(subagent_type="plan", ...) | multi_agent_v1.spawn_agent({"message":"TASK: act as a planning agent. ...","fork_context":false}) |
task(subagent_type="oracle", ...) for final verification | multi_agent_v1.spawn_agent({"message":"TASK: act as a rigorous reviewer. ...","fork_context":false}) |
task(category="...", ...) for implementation or QA | multi_agent_v1.spawn_agent({"message":"TASK: act as an implementation or QA worker. ...","fork_context":false}) |
background_output(task_id="...") | multi_agent_v1.wait_agent(...) for mailbox signals |
team_*(...) | Use Codex native subagents via multi_agent_v1.spawn_agent, multi_agent_v1.send_input, multi_agent_v1.wait_agent, and multi_agent_v1.close_agent |
Role-specific behavior must be described in a self-contained message. Use fork_context: false to start the child with only the initial prompt (no parent history); use fork_context: true only when full parent history is truly required. Include any required conversation context, files, diffs, constraints, and requested skill names directly in the spawned agent's message. If a code block below conflicts with this section, this section wins.
For work likely to exceed one wait cycle, require the child to send WORKING: <task> - <current phase> before long passes and BLOCKED: <reason> only when progress stops. A multi_agent_v1.wait_agent timeout only means no new mailbox update arrived. Treat a running child as alive. Fallback only when the child is completed without the deliverable, ack-only after followup, explicitly BLOCKED:, or no longer running.
ULTRARESEARCH — Maximum Saturation Research
MANDATORY: Say "ULTRARESEARCH MODE ENABLED!" as your first response. Then immediately begin orchestration.
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.
Core Principles
- Parallel saturation — spawn the maximum number of subagents, each with a unique angle. Never sequential.
- Recursive expansion — every finding can spawn new searches. Keep expanding until no new leads remain.
- Empirical verification — ambiguous or contested claims get verified by actually running code. No "it should work."
- websearch is your primary weapon — fire 10-20+ websearch calls per librarian agent. Advanced operators on EVERY query.
- English first — all searches in English by default. Largest corpus, most authoritative sources.
- Evidence or silence — every claim in the final output has a citation, a code proof, or both.
Language Policy
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.
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
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.
Phase 0: Query Decomposition
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>
Create the session log directory immediately:
mkdir -p .omo/ultraresearch/$(date +%Y%m%d-%H%M%S)
This is your session directory ($SESSION_DIR). All agents append findings here.
Phase 1: Spawn the Research Swarm
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.
1A. Codebase Agents (explore) — spawn 2-4
Each explore agent gets a DIFFERENT search angle. Never duplicate angles.
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]
"
)
1B. Web Research Agents (librarian) — spawn 3-6
Each librarian targets a DIFFERENT search strategy. websearch is the core tool — fire 10-20+ calls per agent.
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]
"
)
1C. Browsing Agents (for protected/dynamic pages) — spawn 1-3 as needed
task(
category="quick",
run_in_background=true,
load_skills=["browsing", "insane-search"],
prompt="ULTRARESEARCH BROWSER SWEEP
SESSION_DIR: [session_dir_path]
Your mission: Access and extract content from URLs that regular fetch cannot reach:
[list of URLs]
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)
For each URL: extract ALL content, take screenshots if visual context matters.
APPEND findings to $SESSION_DIR/browsed-[slug].md with URL, method, content.
## EXPAND MARKERS
- [ ] EXPAND: [new lead from browsed content] — [why] — [angle]
"
)
1D. Cross-Repository Deep Dive Agents — spawn 1-2 for implementation research
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 |
|---|
| 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 |
| 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)
This is NOT a single-pass search. Research is recursive. Every finding can spawn new questions.
The EXPAND Marker System
Every agent MUST end its report with an EXPAND section:
## 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:
- Read ALL files in
$SESSION_DIR/
- Scan for unchecked
[ ] EXPAND: markers across all reports
- Deduplicate — if two agents flagged the same lead, merge into one
- For each unique unchecked EXPAND marker, spawn a NEW agent:
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.
"
)
-
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)
-
Track expansion state in $SESSION_DIR/expansion-log.md:
# 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
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
Any claim that is ambiguous, contested, or unverifiable from documentation alone MUST be verified by running actual code.
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:
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]
"
)
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.
Phase 4: Synthesize
Once the expansion loop has CONVERGED and all agents (including verification) have reported:
-
Read ALL files in $SESSION_DIR/
-
Cross-reference findings across ALL agents (initial + expansion waves + verification)
-
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
-
Write synthesis to $SESSION_DIR/SYNTHESIS.md:
# 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]
- If the user requested a report: proceed to Phase 5.
- 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
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
"
)
B. Screenshot Collection Agent
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
"
)
C. Image Generation Agent (if diagrams/infographics needed)
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
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  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.
"
)
Advanced Search Operator Reference
Agents MUST use these aggressively on every websearch call. This is core technique, not garnish.
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
# Official docs
"[library] site:[library].dev OR site:docs.[library].com"
# GitHub implementations
"[pattern] site:github.com filetype:ts OR filetype:tsx"
# 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"
GitHub Search (gh CLI)
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"])
Anti-Patterns
| 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 |
