octocode-cli 1.3.0 → 1.5.0

package/skills/agentic-flow-best-practices/references/agent-collaboration-patterns.md

@@ -0,0 +1,75 @@
+# Agent Collaboration Patterns
+
+Use this to reason about flows between agents, roles, ownership, and communication. Supervisor is one option; choose the collaboration shape that fits the work.
+
+## Technique Map
+
+| Technique | Shape | Use When | Watch For |
+|---|---|---|---|
+| Prompt roles | One agent, named internal roles | Separation is conceptual only | Fake multi-agent complexity |
+| Router | `classify -> specialist/path` | Known categories map to tools/prompts/models | Overrouting ambiguous work |
+| Agents as tools | Manager calls specialist and keeps control | Specialist returns artifact/result | Specialist leaking conversation control |
+| Handoff | Agent transfers user-facing turn | Specialist should own next interaction | Full-history transfer, unclear return |
+| Orchestrator-workers | Planner creates dynamic subtasks | Work is discovered at runtime | Weak task packets, duplicate work |
+| Parallel specialists | Same/different facets run concurrently | Latency, coverage, independent evidence | Merge conflicts, inconsistent criteria |
+| Reviewer/evaluator | Separate judge checks output | Quality/safety needs independent review | Self-approval |
+| Debate/red-team | Advocate + critic + judge | High-stakes tradeoff or risk analysis | Performative disagreement |
+| Blackboard | Agents read/write shared workspace | Coordination through artifacts/state | Concurrent writes, stale facts |
+| Hierarchical team | Leads coordinate subteams | Large domain with nested ownership | Bottlenecks, hidden state |
+| Human-gated team | Agent proposes, human approves | Trust, policy, cost, destructive action | Vague approval prompt |
+| Background worker | Async consolidation/evals/memory | Work can happen after response | Hidden side effects |
+
+Choose **agents-as-tools** when the manager should keep control and specialists return artifacts. Choose **handoff** when a specialist should own the next user-facing turn. Choose **blackboard/shared workspace** when agents coordinate through artifacts instead of direct conversation.
+
+## Role Design
+
+Define roles by responsibility, not titles:
+
+- `owner`: one agent/node owns each state field and artifact.
+- `planner`: decomposes work and assigns packets.
+- `specialist`: performs bounded work with scoped tools/context.
+- `reviewer`: checks output, evidence, risk, and schema.
+- `memoryWriter`: approves durable memory writes.
+- `actor`: performs side effects after gates.
+- `observer`: traces, metrics, evals, cache/memory decisions.
+
+Avoid roles that differ only by wording. If two roles share tools, context, and output type, they may be one role with a clearer prompt.
+
+## Communication Protocol
+
+Each agent boundary should use Zod-backed packets:
+
+```text
+AgentTask: goal, inputs, knownFacts, constraints, allowedTools,
+expectedOutput, stopConditions
+
+AgentResult: status, output, evidence, unknowns, actionNeeded,
+memoryCandidates, traceId
+```
+
+Pass artifact references over full history. Pass decisions separately from evidence. Let workers make local choices inside bounds; return to coordinator when scope, tool permission, confidence, or side effects exceed bounds.
+
+## Common Failure Fixes
+
+| Failure | Fix |
+|---|---|
+| duplicate work | disjoint ownership and task ids |
+| context bloat | packet + artifact refs + input filters |
+| tool bleed | per-agent allowlists |
+| infinite delegation | max turns, budget, terminal states |
+| prose result | Zod-valid `AgentResult` |
+| weak merge | evidence ids and conflict surfacing |
+| memory pollution | one approved memory writer |
+| self-approval | reviewer, eval, or human gate |
+
+## Output Mini-Scheme
+
+```markdown
+Roles: <role -> responsibility/tools/context>
+Collaboration: <router | agents-as-tools | handoff | orchestrator-workers | blackboard | reviewer | hybrid>
+Packets: <AgentTask/AgentResult/Zod schemas>
+State: <owner per field/artifact>
+Flow: <agent -> agent/tool/artifact>
+Gates: <approval/memory/side-effect stops>
+Failure controls: <loop limits, conflict policy, retries>
+```

package/skills/agentic-flow-best-practices/references/pr-review-agent-example.md

@@ -0,0 +1,47 @@
+# Worked Example: PR Review Agent
+
+Compact build-ready example.
+
+```markdown
+## Flow: PR Review Agent
+
+Goal: Fetch a GitHub PR diff/context, produce schema-valid findings, and post only after approval.
+Architecture: Checkpointed workflow/LangGraph. Route is known; durable state and gates matter. Avoid multi-agent until review core works.
+
+State:
+- `prRef`: input, owner/repo/number/headSha
+- `diff`, `contextChunks`, `risk`: working state
+- `findings`: artifact, Zod-valid review output
+- `repoFacts`: memory candidates after approval
+
+Protocols (Zod):
+- `FlowInput`, `DiffPayload`, `ReviewFinding`, `ReviewOutput`
+- `CacheEntry`, `MemoryCandidate`, `HumanGate`, `TraceEvent`, `ErrorEnvelope`
+
+Context packet:
+- goal, summarized diff when large, top relevant chunks, risk, repo instructions
+- constraints: changed lines plus nearby context; no approve/merge/close/post
+- expected output: `ReviewOutput`
+- unknowns: missing files/symbols
+
+Cache/memory:
+- cache by `pr:{owner}/{repo}/{number}:{headSha}`, scope repo/workspace
+- invalidate on new push or changed base
+- never store raw private diffs as memory
+- write approved conventions/facts only, with source and retention
+
+Flow:
+1. `classify`: PR ref -> task/risk; stop if invalid
+2. `retrieve`: diff/context; cache by headSha; retry transient fetch
+3. `reason`: context packet -> `ReviewOutput`; retry once on schema failure
+4. `review`: preview findings; gate post/memory
+5. `act`: post approved comment with idempotency key
+6. `observe`: trace route, tools, cache, errors, memory candidates
+
+Verify:
+- Zod tests for protocols
+- cache hit/miss/stale tests
+- golden SQL injection PR -> high/block finding
+- should-not-remember rejects raw diff/unapproved facts
+- tool failure leaves no partial public comment
+```

package/skills/agentic-flow-best-practices/references/resources.md

@@ -0,0 +1,112 @@
+# Agentic Flow Research Launchpad
+
+Use this as seed material, not a fixed stack. Project-local conventions win. Start with official docs, then inspect GitHub/source when behavior affects design.
+
+Use available source-search tooling first, such as Octocode local/GitHub search. If shell search is appropriate, a useful local query is:
+
+```bash
+rg -n "MCP|OpenAI|ADK|LangGraph|context|memory|cache|handoff|eval|attention|schema|hooks|github" references/resources.md
+```
+
+Research loop:
+
+1. Open the relevant docs URL for concepts and terminology when external docs are allowed.
+2. Search the GitHub/source repo for implementation details, examples, tests, and issues using Octocode or the available source-search tool.
+3. Search within source for `tool`, `handoff`, `memory`, `session`, `callback`, `hook`, `trace`, `schema`, `eval`, `checkpoint`, `middleware`.
+4. Carry forward findings that affect architecture, protocol, context, safety, or verification.
+5. If the project uses another framework, search its official docs and GitHub source the same way.
+
+## Core Patterns
+
+- **Anthropic - Building Effective Agents**: https://www.anthropic.com/engineering/building-effective-agents
+  Patterns: augmented LLM, chains, routing, parallelization, orchestrator-workers, evaluator-optimizer, agents, tool design.
+
+## Protocols And MCP
+
+- **MCP Architecture**: https://modelcontextprotocol.io/docs/learn/architecture
+  Scope, participants, layers, primitives; MCP is context/tool protocol, not orchestration.
+- **MCP Server Concepts**: https://modelcontextprotocol.io/docs/learn/server-concepts
+  Tools, resources, prompts, discovery.
+- **MCP Prompts**: https://modelcontextprotocol.io/docs/concepts/prompts
+  Reusable prompt templates.
+- **MCP GitHub**: https://github.com/modelcontextprotocol/modelcontextprotocol
+  Search source/spec for protocol behavior and examples.
+
+## Agent SDKs And Runtimes
+
+- **OpenAI Agents docs**: https://openai.github.io/openai-agents-python/agents/
+  Agents, tools, handoffs, guardrails, sessions, structured outputs.
+- **OpenAI orchestration**: https://openai.github.io/openai-agents-python/multi_agent/
+  LLM-led vs code-led, agents-as-tools, handoffs, hybrids.
+- **OpenAI lifecycle**: https://openai.github.io/openai-agents-python/ref/lifecycle/
+  RunHooks and AgentHooks around models, tools, agents, handoffs.
+- **OpenAI Agents GitHub**: https://github.com/openai/openai-agents-python
+  Search examples/tests/source for handoff, lifecycle, tracing, tool behavior.
+
+- **Google ADK sessions/state/memory**: https://adk.dev/sessions/
+  Session, state, searchable memory.
+- **Google ADK callbacks**: https://google.github.io/adk-docs/callbacks/
+  Agent/model/tool lifecycle callbacks.
+- **Google ADK GitHub**: https://github.com/google/adk-python
+  Search source/examples for runners, tools, callbacks, memory services.
+
+- **LangGraph overview**: https://docs.langchain.com/oss/python/langgraph
+  Durable stateful agents, persistence, streaming, human-in-loop, memory, tracing.
+- **LangGraph persistence**: https://docs.langchain.com/oss/python/langgraph/persistence
+  Threads, checkpoints, snapshots, cross-thread memory.
+- **LangGraph GitHub**: https://github.com/langchain-ai/langgraph
+  Search source/examples for checkpoints, interrupts, commands, stores, middleware.
+
+- **LangChain docs**: https://docs.langchain.com/
+  Model/tool abstractions, middleware, agents, retrieval, eval-related guides.
+- **LangChain GitHub**: https://github.com/langchain-ai/langchain
+  Search source/examples for tools, structured output, middleware, retrievers.
+
+## Schemas And Structured Output
+
+- **Zod JSON Schema**: https://zod.dev/json-schema
+  Convert Zod to JSON Schema for model/tool/MCP structured-output APIs.
+- **Zod GitHub**: https://github.com/colinhacks/zod
+  Search issues/source for JSON Schema, strict objects, discriminated unions.
+- **JSON Schema**: https://json-schema.org/
+  Cross-language schema interoperability.
+
+## Models, Prompts, Cache
+
+- **OpenAI prompt caching**: https://platform.openai.com/docs/guides/prompt-caching
+  Static-before-dynamic prompts, cached tokens.
+- **OpenAI prompting**: https://platform.openai.com/docs/guides/prompting
+  Prompt versions, variables, eval-linked iteration.
+- **OpenAI reasoning models**: https://platform.openai.com/docs/guides/reasoning
+  Reasoning tokens, effort, output budget, incomplete responses.
+- **OpenAI model comparison**: https://platform.openai.com/docs/models/compare
+  Current context windows, output limits, feature fit.
+
+## Context Attention
+
+- **Deep Agents context engineering**: https://docs.langchain.com/oss/javascript/deepagents/context-engineering
+  Input/runtime context, compression, offloading, summarization, context isolation, skills.
+- **Lost in the Middle**: https://arxiv.org/abs/2307.03172
+  Long-context models can miss middle-position information.
+- **Chroma Context Rot**: https://www.trychroma.com/research/context-rot
+  Adding tokens can degrade usefulness.
+
+## Memory And RAG Baselines
+
+- **LangGraph memory**: https://docs.langchain.com/oss/python/concepts/memory
+  Short-term/thread and long-term memory.
+- **Deep Agents memory**: https://docs.langchain.com/oss/python/deepagents/long-term-memory
+  Agent/user/org memory, read-only vs writable, background consolidation.
+- **mem0 GitHub**: https://github.com/mem0ai/mem0
+  Cross-session memory patterns.
+- **RAG techniques GitHub**: https://github.com/NirDiamant/RAG_Techniques
+  Retrieval pattern examples and eval baselines.
+
+## Collaboration And Interop
+
+- **AutoGen GitHub**: https://github.com/microsoft/autogen
+  Multi-agent conversation and human-in-loop examples.
+- **A2A GitHub**: https://github.com/a2aproject/A2A
+  Agent-to-agent interop protocol ideas.
+- **OpenAI Cookbook GitHub**: https://github.com/openai/openai-cookbook
+  Practical examples for tools, structured outputs, retrieval, agents.

package/skills/octocode-brainstorming/.env.example

@@ -0,0 +1,11 @@
+# Environment variables for octocode-brainstorming
+#
+# Copy this file to .env in the same directory and fill in real values:
+#   cp .env.example .env
+#
+# Do NOT commit .env — it is gitignored.
+# The skill detects Tavily availability by running: node scripts/tavily-search.mjs --check
+
+# Tavily API key — enables AI-powered web research.
+# Get a key at https://app.tavily.com/
+TAVILY_API_KEY=tvly-REPLACE_ME

package/skills/octocode-brainstorming/SKILL.md

@@ -0,0 +1,262 @@
+---
+name: octocode-brainstorming
+description: Idea brainstorming and validation grounded in evidence. Triggers on "brainstorm", "is this worth building", "has anyone built X", "validate my idea", "check if X exists", "research this idea", "what are the prior-art options for Y". Researches GitHub, npm/PyPI, and the web in parallel, then synthesizes a decision-ready brief — not code or designs.
+---
+
+# Octocode Brainstorming — Idea Discovery & Validation
+
+Research-first skill that turns a raw idea into a grounded brief by hitting **every available surface in parallel** — then synthesizes what exists, what's missing, and what's next. No designs, specs, or code.
+
+
+---
+
+## Researcher Mindset
+
+You are a **technical researcher**, not a search-engine wrapper.
+
+- **Assume nothing is novel.** Find who tried it, where they stopped, and why.
+- **Follow the trail.** README → blog → competitor → issues page → hard unsolved problem. Keep pulling threads.
+- **Web ↔ Code cross-pollination.** Web and GitHub are not separate tracks — they feed each other. A blog post names a tool → search its repo on GitHub. A GitHub repo README links to docs → `WebFetch` those docs. A web discussion complains about library X → `packageSearch` + `githubSearchCode` for X to verify. Always use findings from one surface to refine queries on the other.
+- **Go deep when results are thin.** Read code, check issue trackers, inspect PRs, check download trends. Shallow matches are starting points.
+- **Use parallel agents aggressively.** Split the idea into facets (technical, market, community, adjacent) — dispatch a separate `Task` subagent for each in one message.
+- **Force disagreement.** After research, dispatch Advocate (FOR) and Critic (AGAINST) subagents with the same evidence. Agreement = high confidence; disagreement = the real decision.
+- **Synthesize, don't summarize.** Original analysis of what the landscape means, not just a link list.
+
+---
+
+## Hard Gates
+
+Stop and ask the user before proceeding past any of these. State the situation in 1–2 lines, name the options, and recommend one.
+
+1. **Idea too broad** — the idea maps to 3+ unrelated problem spaces and cannot be meaningfully researched in one pass. Stop after the clarify step, before dispatching any subagents. Ask the user to pick one facet or confirm they want a shallow sweep.
+2. **Zero results across surfaces** — after the parallel research phase, all three surfaces (GitHub, packages, web) returned <2 meaningful results each even after synonym expansion. Do not proceed to Advocate vs Critic. Present what you found, flag the gap, and ask: narrow the idea, broaden keywords further, or accept thin evidence?
+3. **Contradictory evidence** — GitHub/packages show a crowded space but web sources say the problem is unsolved (or vice versa). Do not bury the contradiction in the brief. Stop, surface both sides with citations, and ask the user which signal to weight before synthesizing.
+4. **Subagent ceiling reached** — maximum **5 `Task` subagents** per brainstorm session (web slices + Advocate + Critic combined). If more seem needed, synthesize what you have first and ask whether the user wants a second research pass.
+
+Do not silently continue past a hard gate. Do not ask outside of gates — gates exist to reduce bad briefs, not to offload decisions.
+
+---
+
+## Tools
+
+### GitHub & packages — Octocode MCP
+
+| Tool | Use for |
+|------|---------|
+| `packageSearch` | npm/PyPI libraries |
+| `githubSearchRepositories` | Repos by topic, language, stars |
+| `githubViewRepoStructure` | How a similar project is organized |
+| `githubSearchCode` | Confirm a concept is actually implemented |
+| `githubGetFileContent` | Read key files for specific answers |
+| `githubSearchPullRequests` | How similar features were shipped (deep mode) |
+
+**Smart querying:**
+- **Semantic expansion** — don't search only the user's exact words. Generate 2–3 synonym/related queries (e.g. "code review" → also "pull request analysis", "diff feedback", "static analysis AI"). Run them in parallel.
+- **Recency first** — sort by recently updated/pushed. Ignore repos inactive >2 years unless the user asks for historical context. Stale repos are prior art, not competition.
+- **Quality filter** — skip forks, skeleton/tutorial repos, and <10-star repos unless they're the only match. Prefer repos with recent commits, open issues with engagement, and multiple contributors.
+
+### Web — search scripts + WebFetch
+
+Two layers: **search** (find URLs via Tavily) → **read** (`WebFetch` full content) → **follow** (chase leads). Use all three every time.
+
+**Search script** in `scripts/`:
+
+| Script | Key needed | Best for |
+|--------|------------|----------|
+| `tavily-search.mjs` | `TAVILY_API_KEY` | AI-curated, deep research mode |
+
+**Startup — check Tavily:**
+1. Run `node <skill_dir>/scripts/tavily-search.mjs --check`
+2. Exit 0 → ready. Exit 1 → tell user once:
+   > Tavily not configured. Add your key to `<absolute_path_to_skill_dir>/.env`: `TAVILY_API_KEY=tvly-YOUR_KEY_HERE` (get one at https://app.tavily.com/)
+
+**Run searches:**
+```bash
+node <skill_dir>/scripts/tavily-search.mjs --query "<query>" --depth advanced --max-results 8 --time-range year
+```
+
+Tavily: `--depth basic|advanced`, `--topic general|news`, `--time-range day|week|month|year`, `--help`.
+
+**Smart querying:**
+- **Semantic expansion** — generate 2–3 synonym/reframed queries per search pass (e.g. "AI code review" → also "LLM pull request feedback", "automated diff analysis"). Run them in parallel.
+- **Recency first** — default to `--time-range year`. Only widen to all-time if the user asks or the year window returns <3 results.
+- **Quality filter** — prioritize: official docs > technical blog posts > HN/Reddit discussions > general articles. Skip SEO spam, listicles, and paywalled pages. When `WebFetch`-ing, verify the page has substantive content before citing it.
+
+**Research loop:** run Tavily → `WebFetch` best URLs (quality over quantity) → follow leads in fetched pages → repeat until bedrock.
+
+**Subagents:** spawn `Task` (subagent_type `generalPurpose`) for independent web slices. Each runs Tavily + `WebFetch`. Dispatch multiple in one message.
+
+**Subagent template:**
+> Research <slice> for "<idea>".
+> 1. Run `node <skill_dir>/scripts/tavily-search.mjs --query "<q>" --depth advanced --max-results 8`
+> 2. `WebFetch` best URLs.
+> 3. Report: who's doing this, what they got right/wrong, gaps, best URLs with notes. Cite all sources.
+
+### Tavily key setup
+
+Script auto-loads `<skill_dir>/.env`. Set up: `cp <skill_dir>/.env.example <skill_dir>/.env` and fill in the key. Env vars override `.env`.
+
+**Safety:** Never print/log/commit `TAVILY_API_KEY`. The `.env` is gitignored.
+
+### Tavily-down fallback (web research without Tavily)
+
+When Tavily is unavailable (missing key, 401/403, 429/5xx), do not abandon web research. Use this fallback chain:
+
+1. **Seed URLs from GitHub** — GitHub repo READMEs, `awesome-*` lists, and package pages link to docs, blogs, and competitor products. `WebFetch` those URLs. This is your primary URL source when Tavily is down.
+2. **`WebFetch` well-known aggregators** — try `WebFetch` on curated sources relevant to the idea:
+
+Examples:
+   - `https://news.ycombinator.com/` + search path for the topic
+   - `https://www.producthunt.com/` for product-level prior art
+   - `https://alternativeto.net/` for competitive landscape
+   - `https://dev.to/search?q=<topic>` for community discussion
+3. **Follow leads** — every `WebFetch`-ed page may contain links to deeper sources. Follow them the same way Tavily results are followed.
+
+Fallback produces fewer results than Tavily. Flag in the TL;DR: "Web research limited — Tavily unavailable, results seeded from GitHub links and known aggregators."
+
+**Error reporting:**
+- Tavily 401/403 → key invalid. Tell user: update `<absolute_path>/.env`. Switch to fallback chain.
+- Tavily 429/5xx → switch to fallback chain. Continue.
+- Always print **absolute path** to `.env`. Never block on search failures.
+
+---
+
+## Workflow
+
+Clarify → Parallel research → Advocate vs Critic → Synthesize → Present.
+
+### 1. Clarify
+
+If ambiguous, ask one focused question. If clear enough to search, skip.
+
+### 2. Parallel Research
+
+**Every brainstorm must hit all three surfaces.** Main agent handles GitHub + packages via Octocode MCP; subagents handle web slices using Tavily + `WebFetch`.
+
+| Track | Runner | Tools |
+|-------|--------|-------|
+| GitHub prior-art | Main agent | `githubSearchRepositories` → `githubViewRepoStructure` → `githubSearchCode` |
+| Package landscape | Main agent | `packageSearch` |
+| Web — products | Subagent | Tavily → `WebFetch` |
+| Web — community | Subagent | Tavily → `WebFetch` |
+| Web — adjacent angles | Subagent | Tavily → `WebFetch` |
+
+**Cross-pollination pass:** after the initial parallel sweep, use each surface's findings to sharpen the other:
+- Web mentions a tool/library name → `githubSearchRepositories` + `packageSearch` for it
+- GitHub repo links to docs/blog/product page → `WebFetch` it
+- Package README references competitors → search those on both web and GitHub
+- Web discussion names an unsolved problem → `githubSearchCode` to see if anyone solved it in code
+
+**CHECKPOINT — do not proceed to Advocate vs Critic until:**
+1. At least **one cross-pollination query** has been dispatched per surface (web finding → GitHub search, GitHub finding → `WebFetch`, package finding → web or GitHub search).
+2. Results from cross-pollination have been received and incorporated.
+3. If a surface returned zero useful results, at least one synonym-expanded retry was attempted before marking it failed.
+
+Skip cross-pollination only if the **Subagent ceiling** gate fires first — in that case, note "cross-pollination skipped (budget)" in the brief.
+
+**Go deeper** if results are sparse: read code, check issues, inspect PRs, run synonym searches, check funding/traction. Spawn additional subagents (within the 5-subagent ceiling) rather than sequential follow-ups.
+
+**Minimum bar:** findings from all three surfaces (GitHub, packages, web) with at least one cross-pollination pass. Flag explicitly if a track failed.
+
+### 2b. Advocate vs Critic
+
+After research, dispatch **two competing subagents** in one message with the same findings:
+
+**Advocate:**
+> You are the ADVOCATE for "<idea>". Build the strongest case FOR. Cite repos, packages, web sources. Bull case only — not balanced.
+> Research findings: <paste>
+
+**Critic:**
+> You are the CRITIC of "<idea>". Build the strongest case AGAINST. Cite crowded competitors, abandoned repos, complaints, unsolved problems. Bear case only — not encouraging.
+> Research findings: <paste>
+
+### 3. Synthesize
+
+Merge all tracks + Advocate vs Critic. Analyze, don't list.
+
+- Both **agree** → high-confidence signal, lead with these
+- They **disagree** → real decision points, present both sides with evidence
+- Uncountered risk → flag as blocker. Unchallenged strength → flag as best direction.
+
+Every claim needs a source (repo URL, npm page, web URL). Surface contradictions. Look for: prior art, gaps, risks, angles, traction signals.
+
+### 4. Present
+
+```markdown
+# Idea: <one-line restatement>
+
+## TL;DR
+<Crowded, underserved, or contested? 2–3 sentences. Note any research limitations (e.g. Tavily unavailable, cross-pollination skipped).>
+
+## Prior Art (GitHub)
+- **<repo>** — <what, stars, activity>. `<confidence>` <URL>
+
+## Prior Art (Packages)
+- **<package>** — <what, downloads, maintenance>. `<confidence>` <URL>
+
+## Prior Art (Web / Products)
+- **<product>** — <positioning, pricing>. `<confidence>` <URL>
+
+## Bull Case (Advocate)
+<Strongest FOR arguments with evidence.>
+
+## Bear Case (Critic)
+<Strongest AGAINST arguments with evidence.>
+
+## Verdict
+<Agreement, disagreement, key unknowns.>
+
+## Gaps & Opportunities
+- <gap — with source>
+
+## Risks / Known Hard Problems
+- <risk — with source>
+
+## Angles To Pursue
+1. **<angle>** — <why>. Closest prior art: <repo/product/package>.
+
+## Recommended Next Step
+<e.g. "Prototype the hardest unknown first", "Too broad — narrow down", "Ready to build — start with X">
+```
+
+**Confidence markers** — every prior-art entry MUST carry one:
+
+| Marker | Meaning | Criteria |
+|--------|---------|----------|
+| `strong` | Active, validated, high-signal | Stars >500 OR downloads >10k/week OR multiple independent sources confirm |
+| `moderate` | Exists and relevant, but incomplete signal | Stars 50–500 OR downloads 1k–10k/week OR single credible source |
+| `weak` | Thin evidence, stale, or tangential | Stars <50 OR inactive >1 year OR only marketing copy, no independent validation |
+
+Do not omit the marker. If you cannot assess confidence, mark `weak` and note why.
+
+Scale sections to real content — don't pad.
+
+**Present in chat first.** Then ask:
+> Want me to save this brief? I'll write it to `.octocode/brainstorming/<YYYY-MM-DD>-<topic-slug>.md`
+
+Only write if confirmed.
+
+
+---
+
+## Evidence Rules
+
+- GitHub → repo URL + file:line for code + confidence marker. Web → URL + date + confidence marker.
+- Every prior-art claim carries `strong`, `moderate`, or `weak` (see Confidence markers table above).
+- Contradictions → surface both sides, pick on recency/authority. If contradiction triggers the **Contradictory evidence** gate, stop and ask.
+- Marketing copy ≠ validation — mark it `weak` regardless of source authority.
+- Zero prior art is usually a red flag, not a moat. If zero across all surfaces, the **Zero results** gate fires.
+
+---
+
+## Error Recovery
+
+| Situation | Action |
+|-----------|--------|
+| Octocode MCP not installed | Tell user how to install; continue web-only |
+| GitHub rate-limited | Reduce concurrency; continue |
+| Tavily key missing/invalid | Switch to **Tavily-down fallback** chain; tell user absolute path to `.env` |
+| All web tools down | GitHub-only; flag in TL;DR |
+| Idea too broad | **Hard gate 1** fires — ask user to narrow before dispatching subagents |
+| Zero prior art | Synonym-expand and retry once. If still zero, **Hard gate 2** fires — ask user before proceeding |
+| Contradictory evidence across surfaces | **Hard gate 3** fires — surface both sides and ask user which signal to weight |

package/skills/octocode-brainstorming/scripts/tavily-search.mjs

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+/**
+ * Tavily web search for octocode-brainstorming.
+ *
+ * Usage:
+ *   node tavily-search.mjs --query "prior art for X" [--depth basic|advanced] [--max-results 8] [--topic general|news] [--time-range month|year]
+ *   node tavily-search.mjs --check   # exits 0 if key is set, 1 otherwise
+ *
+ * Requires TAVILY_API_KEY in env or in <skill_dir>/.env
+ * Outputs JSON to stdout; progress/errors to stderr. Never prints the key.
+ */
+
+import { readFileSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SKILL_DIR = resolve(__dirname, '..');
+const ENV_PATH = resolve(SKILL_DIR, '.env');
+
+try {
+  const lines = readFileSync(ENV_PATH, 'utf8').split('\n');
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const eqIdx = trimmed.indexOf('=');
+    if (eqIdx === -1) continue;
+    const key = trimmed.slice(0, eqIdx).trim();
+    const val = trimmed.slice(eqIdx + 1).trim().replace(/^["']|["']$/g, '');
+    if (!process.env[key]) process.env[key] = val;
+  }
+} catch { /* .env not present */ }
+
+const ENDPOINT = 'https://api.tavily.com/search';
+
+function die(msg, code = 1) {
+  process.stderr.write(`ERROR: ${msg}\n`);
+  process.exitCode = code;
+}
+
+function parseArgs(argv) {
+  const opts = { query: '', searchDepth: 'advanced', maxResults: 8, topic: 'general', timeRange: 'year', check: false, help: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--help' || a === '-h') { opts.help = true; continue; }
+    if (a === '--check') { opts.check = true; continue; }
+    if (a === '--query' || a === '-q') { opts.query = argv[++i] || ''; continue; }
+    if (a === '--depth') { opts.searchDepth = argv[++i] || 'advanced'; continue; }
+    if (a === '--max-results') { opts.maxResults = Number(argv[++i]) || 8; continue; }
+    if (a === '--topic') { opts.topic = argv[++i] || 'general'; continue; }
+    if (a === '--time-range') { opts.timeRange = argv[++i] || 'year'; continue; }
+    if (!opts.query) { opts.query = a; continue; }
+    die(`Unknown argument: ${a}`); return null;
+  }
+  return opts;
+}
+
+async function search(opts, apiKey) {
+  const body = {
+    query: opts.query,
+    search_depth: opts.searchDepth,
+    topic: opts.topic,
+    max_results: opts.maxResults,
+    include_answer: true,
+    include_raw_content: false,
+    time_range: opts.timeRange,
+  };
+
+  const res = await fetch(ENDPOINT, {
+    method: 'POST',
+    headers: { Authorization: `Bearer ${apiKey}`, 'Content-Type': 'application/json' },
+    body: JSON.stringify(body),
+    signal: AbortSignal.timeout(30_000),
+  });
+
+  if (!res.ok) {
+    const text = await res.text().catch(() => '');
+    die(`Tavily API ${res.status}: ${text}`);
+    return null;
+  }
+  return res.json();
+}
+
+async function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  if (!opts) return;
+
+  if (opts.help) {
+    console.log(`Tavily web search — octocode-brainstorming
+
+Usage:
+  node tavily-search.mjs --query "query" [options]
+  node tavily-search.mjs --check
+
+Options:
+  --query, -q      Search query (required unless --check)
+  --depth          basic or advanced (default: advanced)
+  --max-results    Number of results (default: 8)
+  --topic          general or news (default: general)
+  --time-range     day, week, month, or year (default: year)
+  --check          Exit 0 if TAVILY_API_KEY is set, 1 otherwise
+
+.env file: ${ENV_PATH}`);
+    return;
+  }
+
+  const apiKey = process.env.TAVILY_API_KEY;
+
+  if (opts.check) {
+    if (apiKey) {
+      console.log('tavily: available');
+      process.exitCode = 0;
+    } else {
+      console.log(`tavily: unavailable (TAVILY_API_KEY not set)`);
+      console.log(`Add TAVILY_API_KEY to: ${ENV_PATH}`);
+      process.exitCode = 1;
+    }
+    return;
+  }
+
+  if (!apiKey) {
+    die(`TAVILY_API_KEY is not set. Add it to ${ENV_PATH} or export it in your shell.`);
+    return;
+  }
+  if (!opts.query) {
+    die('--query is required. Use --help for usage.');
+    return;
+  }
+
+  process.stderr.write(`Searching Tavily: "${opts.query}" (depth=${opts.searchDepth}, max=${opts.maxResults})\n`);
+  const result = await search(opts, apiKey);
+  if (result) {
+    result.engine = 'tavily';
+    console.log(JSON.stringify(result, null, 2));
+  }
+}
+
+main().catch(err => die(err.message || String(err)));