octocode-cli 1.2.5 → 1.2.7

package/skills/{octocode-local-search → octocode-researcher}/references/tool-reference.md

@@ -1,11 +1,15 @@
-# Local Tools Reference
+# Tools Reference
 
-Complete parameter reference for Octocode Local tools.
+Complete parameter reference for Octocode tools (Local + External).
 
 **Required Fields (ALL queries)**: `mainResearchGoal`, `researchGoal`, `reasoning`
 
 ---
 
+# Part 1: Local Tools
+
+---
+
 ## localViewStructure
 
 Explore local directory structure with filtering and sorting.
@@ -257,72 +261,151 @@ Parallelize independent searches (max 5 queries per call):
 
 ---
 
-## Error Recovery
+# Part 2: External Tools (GitHub & Packages)
+
+## githubSearchCode
+
+Search code across GitHub repositories.
+
+```typescript
+{
+  query: string;          // Search query (required) — GitHub code search syntax
+  owner?: string;         // Filter by repo owner
+  repo?: string;          // Filter by repo name (requires owner)
+  language?: string;      // Filter by language
+  path?: string;          // Filter by file path
+  extension?: string;     // Filter by file extension
+  filename?: string;      // Filter by filename
+  resultsPerPage?: number; // Results per page
+  pageNumber?: number;    // Page number
+}
+```
 
-| Situation | Action |
-|-----------|--------|
-| Empty results | Try semantic variants (auth → login, security, credentials) |
-| Too many results | Add filters (path, type, include, excludeDir) |
-| File too large | Use `matchString` or `charLength` pagination |
-| Path not found | Verify with `localViewStructure` first |
-| Path is directory | Use `localViewStructure` instead |
-| .gitignore blocking | Use `noIgnore: true` (for node_modules) |
-| Special chars in pattern | Use `fixedString: true` |
+**Tips:**
+- Narrow to `owner`/`repo` ASAP for faster, more relevant results
+- Use `path` to scope searches (e.g., `path:src/auth`)
+- Use `extension` to filter by file type
+- Combine with `githubGetFileContent` to read matched files
 
 ---
 
-## Common Patterns
+## githubSearchRepositories
 
-### 1. Discovery → Read Pattern
-```json
-// Step 1: Find files
-{ "pattern": "useAuth", "path": "src", "filesOnly": true }
+Find repositories by topic, language, stars.
 
-// Step 2: Read implementation (from step 1 results)
-{ "path": "src/hooks/useAuth.ts", "matchString": "export function useAuth", "matchStringContextLines": 20 }
+```typescript
+{
+  query: string;          // Search query (required)
+  language?: string;      // Filter by language
+  sort?: "stars" | "forks" | "updated"; // Sort order
+  order?: "asc" | "desc";
+  resultsPerPage?: number;
+  pageNumber?: number;
+}
 ```
 
-### 2. Trace Imports Pattern
-```json
-// Step 1: Find import
-{ "pattern": "import.*from 'axios'", "path": "src", "filesOnly": true }
+**Tips:**
+- Use for discovering repos when you don't know the exact name
+- Sort by `stars` for popular/battle-tested repos
+- Sort by `updated` for actively maintained repos
+
+---
+
+## githubViewRepoStructure
 
-// Step 2: Check node_modules
-{ "pattern": "export default axios", "path": "node_modules/axios/lib", "noIgnore": true }
+Explore external repo directory layout.
+
+```typescript
+{
+  owner: string;          // Repo owner (required)
+  repo: string;           // Repo name (required)
+  branch?: string;        // Branch name (default: main/master)
+  path?: string;          // Sub-path within repo
+  depth?: number;         // Directory depth (1-5)
+}
 ```
 
-### 3. Recent Changes Pattern
-```json
-// Step 1: Find recent files
-{ "path": "src", "name": "*.ts", "modifiedWithin": "3d" }
+**Tips:**
+- Use BEFORE `githubGetFileContent` to understand layout
+- Start `depth: 1` at root, drill with `depth: 2` on specific dirs
+- Identify `src/`, `lib/`, `packages/` for entry points
+
+---
+
+## githubGetFileContent
 
-// Step 2: Search within those files
-{ "pattern": "TODO|FIXME", "path": "src/auth", "contextLines": 2 }
+Read files from external GitHub repos.
+
+```typescript
+{
+  owner: string;          // Repo owner (required)
+  repo: string;           // Repo name (required)
+  path: string;           // File path (required)
+  branch?: string;        // Branch name
+  matchString?: string;   // Pattern to find within file
+  matchStringContextLines?: number; // Lines around match
+}
 ```
 
-### 4. Large File Pagination
-```json
-// Window 1
-{ "path": "dist/bundle.js", "charLength": 4000, "charOffset": 0 }
+**Tips:**
+- Use `matchString` for large files (avoid reading entire file)
+- Use LAST in the external flow — after search/structure exploration
+- Generate full GitHub URLs for references: `https://github.com/{owner}/{repo}/blob/{branch}/{path}`
 
-// Window 2
-{ "path": "dist/bundle.js", "charLength": 4000, "charOffset": 4000 }
+---
+
+## githubSearchPullRequests
 
-// Window 3
-{ "path": "dist/bundle.js", "charLength": 4000, "charOffset": 8000 }
+Search PRs by query, state, labels.
+
+```typescript
+{
+  query: string;          // Search query (required)
+  owner?: string;         // Repo owner
+  repo?: string;          // Repo name
+  state?: "open" | "closed" | "merged";
+  sort?: "created" | "updated" | "comments";
+  order?: "asc" | "desc";
+  resultsPerPage?: number;
+  pageNumber?: number;
+}
 ```
 
+**Tips:**
+- Use `state: "merged"` for understanding change history
+- Combine with `githubGetFileContent` to read files from specific commits
+- Narrow to `owner`/`repo` for relevant results
+
 ---
 
-## Anti-Patterns
+## packageSearch
 
-| Bad | Good |
-|-----|------|
-| `fullContent: true` on large files | `matchString` or `charLength` |
-| Shell `grep` command | `localSearchCode` |
-| Shell `find` command | `localFindFiles` |
-| Shell `cat` command | `localGetFileContent` |
-| Reading entire codebase | Targeted discovery then content |
-| Ignoring hints | Follow hints for next steps |
-| Hard-coded paths | Verify with `localViewStructure` |
+Search npm/PyPI packages by name or keyword.
 
+```typescript
+{
+  query: string;          // Package name or keyword (required)
+  registry?: "npm" | "pypi"; // Registry to search (default: npm)
+  resultsPerPage?: number;
+}
+```
+
+**Tips:**
+- Use to find repo URL for a package, then follow with `githubViewRepoStructure`
+- Returns package metadata: name, description, version, repo URL, downloads
+- Use FIRST when investigating an external dependency
+
+---
+
+## Query Batching (External)
+
+GitHub tools support batching (max 3 queries per call):
+
+```json
+{
+  "queries": [
+    { "query": "useState", "owner": "facebook", "repo": "react" },
+    { "query": "useEffect", "owner": "facebook", "repo": "react" }
+  ]
+}
+```

package/skills/{octocode-local-search → octocode-researcher}/references/workflow-patterns.md

@@ -1,6 +1,10 @@
 # Workflow Patterns
 
-Common research flows for local code exploration.
+Common research flows for local and external code exploration.
+
+---
+
+# Part 1: Local Patterns
 
 ---
 
@@ -355,7 +359,7 @@ localSearchCode(error message) → trace throw/catch → find root cause
 
 ---
 
-## Anti-Patterns
+## Anti-Patterns (Local)
 
 | Bad | Good |
 |-----|------|
@@ -370,9 +374,194 @@ localSearchCode(error message) → trace throw/catch → find root cause
 
 ---
 
-## Checklist
+# Part 2: External Patterns
+
+## Pattern 11: Package Discovery
+
+**Use when**: Finding the right library, comparing packages, evaluating options.
+
+```
+packageSearch(keyword) → githubViewRepoStructure → githubGetFileContent(README)
+```
+
+**Steps:**
+1. **Search**: Find packages matching use case
+2. **Evaluate**: Check stars, downloads, last update
+3. **Explore**: View repo structure of top candidates
+4. **Read**: Check README, examples, source quality
+
+**Example Flow:**
+```json
+// 1. Search packages
+{ "query": "rate-limiter express", "registry": "npm" }
+
+// 2. View top result repo
+{ "owner": "express-rate-limit", "repo": "express-rate-limit", "depth": 2 }
 
-Before completing research:
+// 3. Read README
+{ "owner": "express-rate-limit", "repo": "express-rate-limit", "path": "README.md" }
+
+// 4. Read source
+{ "owner": "express-rate-limit", "repo": "express-rate-limit", "path": "src/lib.ts", "matchString": "export" }
+```
+
+**Pitfall**: Stopping at npm metadata → always read the actual source.
+
+**Success Criteria**: Found best package with evidence (stars, maintenance, API quality).
+
+---
+
+## Pattern 12: External Repo Exploration
+
+**Use when**: Understanding how another project implements something.
+
+```
+githubSearchRepositories → githubViewRepoStructure → githubSearchCode → githubGetFileContent
+```
+
+**Steps:**
+1. **Find Repo**: Search by topic/keyword or use known repo
+2. **Map Structure**: View repo layout
+3. **Search Pattern**: Find the specific implementation
+4. **Read Source**: Get implementation details
+
+**Example Flow:**
+```json
+// 1. Find repo (skip if known)
+{ "query": "nextjs authentication", "sort": "stars" }
+
+// 2. Map structure
+{ "owner": "vercel", "repo": "next.js", "depth": 1 }
+
+// 3. Search for auth patterns
+{ "query": "getServerSession", "owner": "vercel", "repo": "next.js", "path": "packages" }
+
+// 4. Read implementation
+{ "owner": "vercel", "repo": "next.js", "path": "packages/next/src/server/auth.ts", "matchString": "getServerSession" }
+```
+
+**Pitfall**: Searching too broadly → narrow to specific owner/repo ASAP.
+
+**Success Criteria**: Found specific implementation with line references.
+
+---
+
+## Pattern 13: Dependency Source Investigation
+
+**Use when**: Need to understand how an imported library works internally.
+
+```
+packageSearch → get repo URL → githubViewRepoStructure → githubSearchCode → githubGetFileContent
+```
+
+**Steps:**
+1. **Find Package**: Get repo URL from package metadata
+2. **Map Layout**: Understand library structure
+3. **Search**: Find the exported function/class
+4. **Read**: Get the implementation
+
+**Example Flow:**
+```json
+// 1. Find package repo URL
+{ "query": "zod", "registry": "npm" }
+
+// 2. View structure
+{ "owner": "colinhacks", "repo": "zod", "depth": 2 }
+
+// 3. Search for specific feature
+{ "query": "z.object", "owner": "colinhacks", "repo": "zod", "path": "src" }
+
+// 4. Read implementation
+{ "owner": "colinhacks", "repo": "zod", "path": "src/types.ts", "matchString": "object(" }
+```
+
+**Pitfall**: Only reading installed node_modules version → canonical GitHub source shows latest intent.
+
+**Success Criteria**: Understand how the dependency works at the source level.
+
+---
+
+## Pattern 14: PR Archaeology
+
+**Use when**: Understanding why code changed, tracing regression origins, reviewing decisions.
+
+```
+githubSearchPullRequests → read PR files → trace changes
+```
+
+**Steps:**
+1. **Search PRs**: Find merged PRs matching the topic
+2. **Read Context**: Get PR description and changed files
+3. **Trace Changes**: Read specific files at that point in time
+
+**Example Flow:**
+```json
+// 1. Find relevant PRs
+{ "query": "fix auth token refresh", "owner": "myorg", "repo": "backend", "state": "merged" }
+
+// 2. Read changed files from PR
+{ "owner": "myorg", "repo": "backend", "path": "src/auth/tokenRefresh.ts", "matchString": "refreshToken" }
+```
+
+**Pitfall**: Reading only PR titles → read the actual changed files.
+
+**Success Criteria**: Understood the change motivation and implementation.
+
+---
+
+## Pattern 15: Cross-Boundary Research (Local + External)
+
+**Use when**: Local code uses external library, need to understand both sides.
+
+```
+LOCAL: localSearchCode(import) → lspGotoDefinition
+EXTERNAL: packageSearch → githubSearchCode → githubGetFileContent
+MERGE: Compare and document
+```
+
+**Steps:**
+1. **Local**: Find how the dependency is used locally
+2. **External**: Find how the dependency works at source
+3. **Merge**: Compare usage with intended API
+
+**Example Flow:**
+```json
+// LOCAL — find usage
+{ "pattern": "import.*from 'next-auth'", "path": "src", "filesOnly": true }
+// → then lspGotoDefinition on the import, lspFindReferences for all usages
+
+// EXTERNAL — find source
+{ "query": "next-auth", "registry": "npm" }
+// → then githubViewRepoStructure + githubSearchCode + githubGetFileContent
+
+// MERGE: Is local usage correct? Are there missed features? Breaking changes?
+```
+
+**Pitfall**: Researching one side only → always trace both local usage AND external implementation.
+
+**Success Criteria**: Understand both sides and their interaction.
+
+---
+
+## Anti-Patterns (External)
+
+| Bad | Good |
+|-----|------|
+| **`gh api` for GitHub** | **`githubSearchCode` / `githubGetFileContent`** |
+| **`WebFetch` for GitHub** | **Octocode GitHub tools** |
+| **`npm search` in shell** | **`packageSearch`** |
+| **Guessing owner/repo** | **`packageSearch` or `githubSearchRepositories` first** |
+| **Reading entire large files** | **`matchString` targeting** |
+| **Broad GitHub search** | **Narrow to owner/repo ASAP** |
+| **Skipping structure** | **`githubViewRepoStructure` before reading** |
+
+---
+
+# Checklists
+
+## Local Research Checklist
+
+Before completing local research:
 
 - [ ] **Goal defined?** (Atomic question)
 - [ ] **Code evidence found?** (Line numbers/paths)
@@ -381,3 +570,14 @@ Before completing research:
 - [ ] **Gaps documented?**
 - [ ] **User checkpoint offered?** (Continue/Save)
 
+## External Research Checklist
+
+Before completing external research:
+
+- [ ] **Repo/package found via search?** (Not guessed)
+- [ ] **Structure explored first?** (`githubViewRepoStructure`)
+- [ ] **References include full GitHub URLs?** (With line numbers)
+- [ ] **Source verified?** (Read actual code, not just metadata)
+- [ ] **Gaps documented?**
+- [ ] **User checkpoint offered?** (Continue/Save)
+

package/skills/octocode-rfc-generator/SKILL.md

@@ -0,0 +1,223 @@
+---
+name: octocode-rfc-generator
+description: Research-driven RFC and design document generator. Use when the user asks to "create an RFC", "write a design doc", "propose a migration", "how should we architect X", "evaluate options for X", "write a technical proposal", "compare approaches", or needs a technical decision document before coding. Outputs a validated RFC with research evidence, alternatives, recommendation, and implementation plan. For planning with implementation, use octocode-plan instead.
+---
+
+# RFC Agent — Research, Reason, Plan
+
+`UNDERSTAND` → `RESEARCH` → `DRAFT RFC` → `VALIDATE` → `DELIVER`
+
+**Output**: `.octocode/rfc/RFC-{meaningful-name}.md`
+
+---
+
+## Identity & Principles
+
+<agent_identity>
+**Role**: RFC Agent — Technical Decision Maker.
+**Objective**: Research deeply, reason about alternatives, write a validated RFC, then produce an implementation plan anchored to it.
+**Core loop**: Understand → Research → Write evidence-based RFC → Validate → Deliver.
+
+**Principles**:
+- **Big picture first** — understand the full system flow before zooming into details. Every decision affects something upstream or downstream.
+- **Never hallucinate** — if you don't know, research. If research is empty, say "unknown" — never fabricate evidence, references, or claims.
+- **Architecture over patching** — solve the root cause, not the symptom. Ask "why does this problem exist?" before "how do I fix it?"
+- **Simple over clever** — the best solution is the simplest one that solves the problem. If the design needs a paragraph to explain a single decision, it's too complex.
+- **Research before writing** — no RFC content without evidence. Every claim traces to research.
+- **Alternatives are mandatory** — never just "do X" (npm: "even if it seems like a stretch").
+- **Motivation is king** — most important section (Rust, React, npm agree).
+- **Drawbacks build trust** — honest cost analysis makes proposals credible.
+- **Quality over speed** — a clean RFC prevents months of rework. But timely over perfect — a good RFC now beats a perfect one never.
+- **No time estimates** — never provide duration estimates.
+- **Ask when stuck** — if uncertain, research more or ask user.
+</agent_identity>
+
+---
+
+## Setup
+
+<mcp_discovery>
+Before starting, detect available research tools.
+
+**Check**: Is `octocode-mcp` available as an MCP server?
+Look for Octocode MCP tools (e.g., `localSearchCode`, `lspGotoDefinition`, `githubSearchCode`, `packageSearch`).
+
+**If Octocode MCP exists but local tools return no results**:
+> Suggest: "For local codebase research, add `ENABLE_LOCAL=true` to your Octocode MCP config."
+
+**If Octocode MCP is not installed**:
+> Suggest: "Install Octocode MCP for deeper research:
+> ```json
+> {
+>   "mcpServers": {
+>     "octocode": {
+>       "command": "npx",
+>       "args": ["-y", "octocode-mcp"],
+>       "env": {"ENABLE_LOCAL": "true"}
+>     }
+>   }
+> }
+> ```
+> Then restart your editor."
+
+Proceed with whatever tools are available — do not block on setup.
+</mcp_discovery>
+
+<tools>
+**Local codebase** — use Octocode local search + LSP tools:
+`localSearchCode`, `localViewStructure`, `localFindFiles`, `localGetFileContent`, `lspGotoDefinition`, `lspFindReferences`, `lspCallHierarchy`
+
+**External research** — use Octocode external search tools:
+`githubSearchCode`, `githubSearchRepositories`, `githubGetFileContent`, `githubSearchPullRequests`, `packageSearch`
+
+The MCP server knows how to use these tools — just call them with your research goal.
+
+**Delegation via skills** (when available):
+
+| Need | Delegate to |
+|------|-------------|
+| Local codebase research | `octocode-researcher` skill (local track) |
+| External research (GitHub, packages, PRs) | `octocode-researcher` skill (external track) |
+</tools>
+
+---
+
+## Execution
+
+### Phase 1: Understand
+
+Clarify the problem before doing anything.
+
+1. **What** is the problem? Define in 1-2 sentences.
+2. **Why** does it need an RFC? (multiple valid approaches, broad impact, architecture decision, new technology)
+3. **Who** is affected? (packages, services, teams)
+4. **What** are the constraints? (tech stack, compatibility, performance)
+5. Check `.octocode/context/context.md` for project context.
+
+Present to user:
+```
+Problem: {statement}
+Scope: {what's affected}
+Constraints: {key constraints}
+Proceed with research?
+```
+
+If problem is unclear → ask user. Do not proceed without clarity.
+If this is a trivial single-file change → suggest skipping RFC, switch to plan mode directly.
+
+---
+
+### Phase 2: Research
+
+Dual-track research using Octocode MCP tools.
+
+**Track A — Local codebase**:
+- How does the codebase handle this today?
+- Which files, modules, packages are impacted?
+- What patterns and abstractions exist?
+- What dependencies are involved?
+- Where does the current approach break down?
+
+**Track B — External best practices** (GitHub + npm + web):
+- How do major projects solve this? (GitHub repos, PRs)
+- What packages/libraries exist? (npm, PyPI)
+- What are known trade-offs and pitfalls?
+- Any prior art or benchmarks?
+
+**Which tracks to run**:
+
+| Scenario | Tracks | Example |
+|----------|--------|---------|
+| Most RFCs | Both A + B in parallel | "Add caching layer" — need local API flow + external cache patterns |
+| Internal refactor | A only (skip B) | "Move auth logic from service X to shared module Y" |
+| Greenfield, no existing code | B only (skip A) | "Choose a database for the new service" |
+| Technology evaluation | B heavy, A light | "Should we use Redis or Memcached?" |
+
+When both tracks run, spawn them as parallel agents. When comparing multiple technologies, spawn separate agents per domain.
+
+**Quality bar**:
+- Every finding is a **code reference** (file + line) or a **URL** (docs, blog, benchmark)
+- Each reference explains **how it supports the RFC thesis** — not just "see this" but "proves X because Y"
+- Key claims verified with a second source
+
+When local and external findings disagree: local conventions win → official external docs → community patterns. If conflict persists → present both in RFC with trade-offs.
+
+---
+
+### Phase 3: Draft RFC
+
+Write the RFC using the template in `references/rfc-template.md`. Core sections:
+
+| # | Section | Purpose |
+|---|---------|----------|
+| 1 | **Summary** | One paragraph — reader understands the core idea |
+| 2 | **Motivation** | Problem, current state (file refs), evidence, impact. Most important section. |
+| 3 | **Guide-Level Explanation** | Teach it as if already implemented — examples, naming/terminology, adoption strategy, docs impact |
+| 4 | **Reference-Level Explanation** | Technical design, diagrams, API changes, corner cases, compatibility & adoption |
+| 5 | **Drawbacks** | Honest costs — simpler alternatives?, breaking changes, blast radius |
+| 6 | **Rationale & Alternatives** | Minimum 2 alternatives + comparison matrix + trade-offs |
+| 7 | **Prior Art** | What exists already — lessons from others |
+| 8 | **Unresolved Questions** | Open questions: before acceptance / during implementation / out of scope / bikeshedding |
+| 9 | **References** | Local (`file:line`) + External (full URLs) |
+| 10 | **Implementation Plan** | Phased steps, risk mitigations, testing strategy, rollout plan |
+
+Every claim traces to research. No unsubstantiated recommendations.
+
+---
+
+### Phase 4: Validate
+
+Self-review the RFC. Check:
+
+- [ ] Problem statement is specific — a reader understands _why_ without prior context
+- [ ] Current state documented with actual file references from research
+- [ ] At least 2 alternatives with evidence-backed trade-offs
+- [ ] Recommendation follows logically from the comparison
+- [ ] Drawbacks are honest, not hand-waved
+- [ ] Risks have mitigations
+- [ ] All references are real (file:line or full URLs from research)
+- [ ] No claims without evidence — if you can't prove it, move it to Unresolved Questions
+- [ ] Implementation steps ordered by dependency, not preference
+
+**Evidence discipline**: Every claim needs a **code reference** (`file:line` with full URL) or a **URL** (docs, benchmark, blog). Each must explain **how it supports the RFC thesis** — not just "see this" but "proves X because Y".
+
+**Reasoning traps to watch for**:
+- **Anchoring** — Don't fall in love with your first idea. Research alternatives with equal rigor.
+- **Confirmation bias** — Actively search for evidence AGAINST your recommendation.
+- **Sunk cost** — If research reveals your initial approach is wrong, pivot.
+- **False dichotomy** — "X or Y" is rarely complete. Look for hybrids, phased rollouts, or "do nothing".
+- **Handwaving risks** — "Low risk" without evidence = unknown risk.
+- **Appeal to popularity** — "Everyone uses X" is not a reason. WHY do they use it, and does that reason apply here?
+
+If any check fails → fix before presenting.
+
+---
+
+### Phase 5: Deliver
+
+Present the RFC summary to user:
+```
+RFC: {Title}
+Recommendation: {1-2 sentences}
+Alternatives: {count} considered
+Risk: {Low|Medium|High}
+```
+
+Then ask: **"Do you want to start implementing this RFC?"**
+
+- **Yes** → Save to `.octocode/rfc/RFC-{meaningful-name}.md`, then switch to the agent's default plan mode to execute the Implementation Plan.
+- **No** → Save to `.octocode/rfc/RFC-{meaningful-name}.md`.
+
+---
+
+## Error Recovery
+
+| Situation | Action |
+|-----------|--------|
+| Research returns empty | Broaden scope, try semantic variants |
+| No external patterns | Ask user for known references |
+| Greenfield (no local code) | Focus external research, note "no existing implementation" |
+| Conflicting approaches | Present both as alternatives |
+| Blocked after 2 attempts | Summarize → ask user |
+| Scope too broad | Suggest splitting into multiple RFCs |
+