Workflow

• Discovery Batch JSON Schema — browse cloud search output format
• Competitor Research Markdown Format — frontmatter + body section spec
• Extracting Page Text — browse cloud fetch (markdown default; --format raw for HTML)
• Discovery — parallel Bash, not subagents — Wave A/B/C recipes
• Enrichment fan-out — 5 subagents PER competitor
• Legacy: Single-subagent template — quick mode only
• Wave Management — parallelism rule, gate phase, sizing formula
• Report Compilation — compile_report.mjs invocation

Discovery Batch JSON Schema

File: /tmp/competitor_discovery_batch_{N}.json

browse cloud search --output writes a JSON object:

The list_urls.mjs script (run with --prefix competitor) deduplicates across batches.

Competitor Research Markdown Format

File: {OUTPUT_DIR}/{competitor-slug}.md — see references/example-research.md for the full template.

YAML frontmatter fields (used by compile_report.mjs):

• competitor_name (required)
• website (required)
• tagline
• positioning
• product_description
• target_customer
• pricing_model
• pricing_tiers (pipe-separated: Free | Pro $99 | Enterprise Contact)
• key_features (pipe-separated)
• integrations (pipe-separated)
• headquarters
• founded
• employee_estimate
• funding_info
• strategic_diff (one-line for overview table; deeper mode only)

Body sections (in this order — compile_report.mjs parses by heading):

• ## Product
• ## Pricing
• ## Features
• ## Positioning
• ## Comparison vs {user_company} (deeper only)
• ## Mentions
• ## Benchmarks (deeper only)
• ## Research Findings

Mentions line format (parsed into the mentions feed):

SourceType ∈ Benchmark | Comparison | News | Reddit | HN | LinkedIn | YouTube | Review | Podcast | X. Date is optional but preferred.

Extracting Page Text

browse cloud fetch --allow-redirects returns clean markdown by default — no HTML stripping needed. Just cap the length:

If you need the original HTML (e.g. to read the <title> tag or parse markup), add --format raw and strip tags:

Limit to ~3000 chars per page to keep subagent context manageable. For JS-heavy pages (client-rendered pricing tables) where the Fetch API returns thin content, open the page in a browser session and read it: browse open "{url}" --remote then browse get markdown.

Discovery — parallel Bash, not subagents

The main agent runs discovery as 3 parallel browse cloud search Bash calls (one per wave) in a SINGLE message. No subagent layer. Each wave chains its 2-4 queries with && and writes results to /tmp/competitor_discovery_batch_{wave}{N}.json.

Example — main agent issues these three Bash tool calls in parallel in one message:

Why direct Bash and not subagents: each wave is 2-4 browse cloud search calls — agent cold-start + tool-reasoning overhead is bigger than the actual work. Using parallel Bash saves ~1-2 min per run with no quality loss.

Discovery query patterns

Discovery uses three parallel waves (evaluated — all three are additive):

Wave A — Generic alternatives (broad net, lots of noise):

• "alternatives to {user_company}"
• "{user_company} competitors"

Wave B — Precise category queries (uses precise_category from self-research):

• "{precise_category}" verbatim
• "{precise_category_2_3_keywords}" — pick the 3 most distinctive tokens
• Compose with “API”, “cloud”, “for agents”: "cloud {primary_noun} for ai agents", "{primary_noun} infrastructure API"

Wave C — Comparison-page graph (highest-precision single wave):

• "{user_company} vs"
• For each seed competitor from the user’s profile, also run "{seed} vs"
• After the searches, scripts/extract_vs_names.mjs parses "X vs Y" titles across all Wave C results to surface candidate names that don’t appear as URLs.

Evaluation result (tested on a search-API run): Wave A returns ~10% real competitors (mostly AI-tool-listicle aggregators). Wave B returns ~35%. Wave C uniquely surfaces named brands via title parsing that neither A nor B finds. Use all three.

Enrichment fan-out — 5 subagents PER competitor (deep/deeper modes)

For each gated-PASS competitor, launch five parallel subagents, one per lane. Each subagent writes a partial to {OUTPUT_DIR}/partials/{slug}.{lane}.md. After all subagents complete, scripts/merge_partials.mjs unions the partials into one canonical {OUTPUT_DIR}/{slug}.md per competitor (dedup mentions by URL, sort by date desc).

The 5 lanes:

Wave management — launch ALL subagents in ONE message: for N competitors × 5 lanes = 5N subagents, fit them all in a single Agent-tool message. Wall clock then equals the slowest single subagent (~3-5 min) instead of batches × slowest_per_batch. On a real 10-competitor run we measured 25 minutes wasted by self-throttling to 10-per-message — the Agent tool happily runs 50+ in parallel; do not split into batches for “politeness”. The only cap is that each subagent still batches its own Bash operations into a single call.

Merge step (once all partials exist):

Produces one {OUTPUT_DIR}/{slug}.md per competitor with dedup’d Mentions (sorted date desc), Benchmarks, and Findings.

Legacy: Single-subagent template (quick mode only)

In quick mode, keep a single subagent per batch of competitors (no fan-out — Lane 1 only, budget 2-3 calls each).

Wave Management

Key Principle: Maximize Parallelism, Minimize Prompts

Launch ALL subagents needed for a phase in ONE message. No “up to 6 per message” cap — the Agent tool runs them in parallel, so wall clock = slowest single agent regardless of count. On a 10-competitor × 5-lane = 50-subagent enrichment, splitting into 5 batches of 10 cost an extra 20 minutes of wall clock vs one batch of 50 (measured Apr 2026). Each subagent still MUST batch its own Bash operations into a single call.

Discovery Phase

• Run discovery as parallel browse cloud search Bash calls, not subagents. Subagent overhead (cold start + tool reasoning) is bigger than the work. Three Bash tool calls in one message — one per wave (A/B/C) — chain each wave’s searches with &&.
• Each wave’s bash call writes its outputs as /tmp/competitor_discovery_batch_{wave}{N}.json
• After all waves complete, run the following in sequence:

  bashCopy

  # 1. Dedup URLs from all batches
  node {SKILL_DIR}/scripts/list_urls.mjs /tmp --prefix competitor > /tmp/competitor_urls.txt
  
  # 2. Extract candidate names from "X vs Y" titles (Wave C output)
  node {SKILL_DIR}/scripts/extract_vs_names.mjs /tmp --prefix competitor \
    --seed "{user_company},{seed1},{seed2},{seed3}" \
    > /tmp/competitor_vs_names.jsonl

• Filter URLs: Remove blog posts, news articles, AI-tool directories (seektool.ai, respan.ai, agentsindex.ai, toolradar.com, aitoolsatlas.ai, aidirectory.com, vibecodedthis.com, aichief.com, openalternative.co, cbinsights.com, saasworthy.com, softwareworld.com), review aggregators (g2.com, capterra.com, trustradius.com), databases (crunchbase.com, tracxn.com), and the user’s own domain. Keep only candidate company homepages.
• For names from extract_vs_names.mjs that didn’t resolve to a domain, optionally run browse cloud search "{name}" --num-results 3 to resolve the top domain; skip if ambiguous.
• Merge: filtered-URL list ∪ resolved vs_names domains ∪ user-provided seed URLs. Dedup by hostname into /tmp/competitor_candidates.txt.

User-confirm phase (between gate and enrichment — mandatory)

After the gate writes /tmp/competitor_gated.jsonl, the main agent MUST ask the user to confirm the enrichment set before launching subagents. Enrichment is 25 subagents × depth budget per competitor — too expensive to run on guesses.

Present three buckets to the user:

1. PASS — status=PASS rows with title
2. UNKNOWN — status=UNKNOWN (fetch failed; always a silent miss risk — JS-heavy homepages, Cloudflare challenges)
3. Rejected-brand matches — top ~10 REJECT rows whose title contains a seed token or that showed up repeatedly in the Wave C “X vs Y” graph

Then AskUserQuestion with a checkbox list + free-text “add more”. Write the confirmed set to /tmp/competitor_enrichment_set.txt (one URL per line). That file — not /tmp/competitor_passed.txt — is the input to the enrichment subagents.

Known gate blind spots to surface aggressively:

• JS-heavy landing pages return near-empty hero text → gate’s keyword matcher has nothing to bite on
• Cloudflare challenge titles (“Just a moment…”) → obvious false negative
• “Search foundation” / “retrieval backbone” / “agent runtime” — semantic variants of the category don’t lexically match
• Apex domain vs product subdomain (e.g. brave.com the browser vs api-dashboard.search.brave.com the actual API product)

Gate Phase (between discovery and enrichment)

Drop wrong-category candidates BEFORE enrichment burns tool calls on them.

Keyword sources:

• --include ← profile’s category_include_keywords (comma-joined).
• --exclude ← profile’s exclusion_list.

Gate logic (position-aware): REJECT if exclude term in <title>; PASS if include term in <title>; for hybrid titles with both (e.g. “Browser Automation & Web Scraping API”), tiebreak by first 200 chars of hero text; otherwise fall through to hero-wide check. Conservative by default.

Review the output — the main agent SHOULD spot-check both lists and MAY manually re-include a REJECT if it recognizes a known direct competitor whose own marketing is category-ambiguous.

Evaluation on a search-API run (12 candidates): 7/7 real competitors PASSED; 4/4 wrong-category (vector database, scraping/ETL platform, analytics tool, internal-KB search) REJECTED. One split-identity edge (a search vendor that also sells a scraping suite) rejected — acceptable.

Enrichment Phase

Two modes:

• quick mode — single subagent per batch of competitors. Lane A (marketing) only. ~8 competitors per subagent, 2-3 tool calls each. Writes directly to {OUTPUT_DIR}/{slug}.md.
• deep / deeper modes — 5-subagent fan-out PER competitor. Each subagent owns ONE lane (marketing / discussion / social / news / technical). Writes to {OUTPUT_DIR}/partials/{slug}.{lane}.md. Budget: 5-8 calls per subagent (deep), 10-15 (deeper). After all lanes complete, run scripts/merge_partials.mjs to consolidate.
• Launch ALL competitor × lane subagents in a SINGLE Agent tool message. For 10 competitors × 5 lanes = 50 parallel agents in one message. Do NOT split into batches — wall clock becomes the slowest single agent (~3-5 min) instead of batches-times-batch-max (~25 min on 10 competitors split into 5 rounds of 10).

Screenshots Phase (after merge, before compile)

Capture homepage hero screenshot for each competitor:

Requires the browse CLI (npm install -g browse). --mode remote drives a Browserbase session (the script passes --remote on each browse command); use --mode local for local Chrome. Writes one PNG per competitor to {OUTPUT_DIR}/screenshots/{slug}-hero.png. compile_report.mjs auto-embeds the hero in the per-competitor HTML page when present.

Cost: ~10-20s per competitor (serial). Total for 5 competitors ≈ 60s.

Sizing Formula

Error Handling

• If a subagent fails, log and continue with remaining batches
• If >50% of subagents fail in a wave, pause and inform the user
• If browse cloud fetch --allow-redirects fails, try browse open "{url}" --remote + browse get markdown as fallback, or skip that page

Report Compilation

After all enrichment subagents complete, compile all HTML views in one command:

The script:

• Reads all .md files in {OUTPUT_DIR}
• Parses YAML frontmatter + body sections
• Deduplicates by normalized competitor name
• Generates {OUTPUT_DIR}/index.html — overview table (name, tagline, pricing, key features, strategic diff)
• Generates {OUTPUT_DIR}/competitors/{slug}.html — per-competitor deep dive
• Generates {OUTPUT_DIR}/matrix.html — side-by-side feature/pricing grid across competitors
• Generates {OUTPUT_DIR}/mentions.html — chronological feed with source-type pills + client-side filter
• Generates {OUTPUT_DIR}/results.csv — flat spreadsheet
• Opens index.html in the default browser (--open flag)
• Prints a JSON summary to stderr