octocode-cli 1.2.8 → 1.2.10

package/package.json

@@ -1,21 +1,21 @@
 {
   "name": "octocode-cli",
-  "version": "1.2.8",
+  "version": "1.2.10",
   "description": "Interactive CLI installer for octocode-mcp - Configure MCP servers for Cursor, Claude Desktop, and more",
   "keywords": [
-    "octocode",
-    "mcp",
-    "model-context-protocol",
-    "cli",
-    "installer",
-    "cursor",
+    "ai-coding",
     "claude",
     "claude-code",
-    "windsurf",
-    "zed",
+    "cli",
     "cline",
+    "cursor",
     "github",
-    "ai-coding"
+    "installer",
+    "mcp",
+    "model-context-protocol",
+    "octocode",
+    "windsurf",
+    "zed"
   ],
   "author": "Guy Bary <bgauryy@octocodeai.com>",
   "homepage": "https://octocode.ai",
@@ -26,26 +26,9 @@
   },
   "bugs": "https://github.com/bgauryy/octocode-mcp/issues",
   "license": "MIT",
-  "bin": "./out/octocode-cli.js",
-  "dependencies": {
-    "@inquirer/prompts": "^8.1.0",
-    "@octokit/auth-oauth-device": "^8.0.3",
-    "@octokit/oauth-methods": "^6.0.2",
-    "@octokit/request": "^10.0.7",
-    "octocode-shared": "workspace:^",
-    "open": "^11.0.0"
-  },
-  "devDependencies": {
-    "@types/node": "^22.15.29",
-    "@vitest/coverage-v8": "^4.0.16",
-    "eslint": "^9.18.0",
-    "tsx": "^4.21.0",
-    "typescript": "^5.9.3",
-    "vite": "^7.3.0",
-    "vitest": "^4.0.16"
-  },
-  "engines": {
-    "node": ">=20.12.0"
+  "type": "module",
+  "bin": {
+    "octocode-cli": "./out/octocode-cli.js"
   },
   "files": [
     "out",
@@ -54,15 +37,17 @@
     "README.md",
     "LICENSE"
   ],
-  "main": "out/octocode-cli.js",
+  "engines": {
+    "node": ">=20.12.0"
+  },
   "scripts": {
-    "build": "yarn lint && vite build",
-    "build:dev": "vite build",
+    "build": "yarn lint && node build.mjs",
+    "build:dev": "node build.mjs",
     "clean": "rm -rf out/",
-    "prepack": "cp -r ../../skills ./skills",
-    "postpack": "rm -rf ./skills",
     "lint": "eslint src tests",
     "lint:fix": "eslint src tests --fix",
+    "postpack": "rm -rf ./skills",
+    "prepack": "cp -r ../../skills ./skills",
     "start": "node ./out/octocode-cli.js",
     "test": "vitest run --coverage",
     "test:quiet": "vitest run --reporter=dot --silent",
@@ -74,5 +59,19 @@
     "validate:skills:json": "npx tsx scripts/validate-skills-marketplace.ts --json",
     "verify": "yarn lint && yarn typecheck && yarn test && yarn validate:mcp && yarn validate:skills"
   },
-  "type": "module"
+  "devDependencies": {
+    "@inquirer/prompts": "^8.1.0",
+    "@octokit/auth-oauth-device": "^8.0.3",
+    "@octokit/oauth-methods": "^6.0.2",
+    "@octokit/request": "^10.0.7",
+    "@types/node": "^22.15.29",
+    "@vitest/coverage-v8": "^4.0.16",
+    "esbuild": "^0.27.2",
+    "eslint": "^9.18.0",
+    "octocode-shared": "workspace:^",
+    "open": "^11.0.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.16"
+  }
 }

package/skills/README.md

@@ -1,142 +1,70 @@
 # OctoCode Skills
 
-Specialized AI agent skills that extend OctoCode's capabilities.
+Specialized AI agent skills extending OctoCode's capabilities.
 
 ---
 
-## When to Use What
+## Quick Reference
 
-| Your Need | Skill | Example Trigger |
-|-----------|-------|-----------------|
-| Code search, exploration, research (local + external) | **Researcher** | "Find X in codebase", "Where is Y?", "Who calls Z?", "Trace this flow", "How does library X work?" |
-| Complex multi-phase research with sessions & checkpoints | **Research** | "Deep-dive into auth end-to-end", "Compare React vs Vue state", "Research and review PR changes" |
-| Plan implementation steps before coding | **Plan** | "Plan this refactor", "Research & plan this feature" |
-| Technical decisions requiring formal RFC with alternatives | **RFC** | "Create RFC for caching", "Design doc for API v2", "How should we build X?" |
-| Review a pull request or local changes | **PR Reviewer** | "Review PR #123", "Review my changes", "Is this PR safe to merge?" |
-| Repo-wide code quality scan (duplicates, complexity, cycles) | **Local Code Scan** | "Analyze code quality", "Find duplicates", "Find dependency cycles", "Scan for tech debt" |
-| Brutal code criticism with fixes | **Roast** | "Roast my code", "Find code sins", "What's wrong with this?" |
-| Strengthen prompts / agent instructions | **Prompt Optimizer** | "Optimize this SKILL.md", "Agent skips steps" |
-| Generate repo documentation | **Documentation Writer** | "Document this project", "Create developer docs" |
+| Need | Skill | Triggers |
+|------|-------|----------|
+| Code search & exploration | **Researcher** | "Find X", "Where is Y?", "Who calls Z?" |
+| Deep multi-phase research | **Research** | "Deep-dive auth E2E", "Compare X vs Y" |
+| Implementation planning | **Plan** | "Plan this refactor", "Plan this feature" |
+| Formal technical decisions | **RFC** | "Create RFC for X", "Design doc for Y" |
+| PR & local code review | **PR Reviewer** | "Review PR #123", "Review my changes" |
+| Code understanding & implementation | **Engineer** | "How does X work?", "Implement this", "Audit quality" |
+| Brutal code critique | **Roast** | "Roast my code", "Find antipatterns" |
+| Prompt hardening | **Prompt Optimizer** | "Optimize this SKILL.md", "Agent skips steps" |
+| Repo documentation | **Doc Writer** | "Document this project", "Create dev docs" |
 
 ---
 
-## Skills Overview
+## Skills
 
-### 1. OctoCode Researcher
-**Location:** `octocode-researcher/`
+### 1. Researcher
+`octocode-researcher/`
 
-**The default research skill.** Direct code exploration via Octocode MCP tools — local codebase (LSP semantic navigation, search, structure) and external (GitHub, npm/PyPI, PRs). Lightweight, no server needed. Use for most research tasks.
+Default research skill. Direct code exploration via Octocode MCP — local (LSP, search, structure) and external (GitHub, npm/PyPI, PRs). No server needed.
 
-| When | Example |
-|------|---------|
-| Local search + LSP | "Find auth logic", "Where is X defined?", "Who calls Y?" |
-| External research | "How does library X work?", "Find a caching package" |
-| Cross-boundary | "How does our code use dependency Z?" |
+### 2. Research (HTTP Server)
+`octocode-research/`
 
----
-
-### 2. OctoCode Research (HTTP Server)
-**Location:** `octocode-research/`
-
-HTTP server mode for complex, multi-phase research. Adds session management, checkpoints, and persistent context on top of Octocode MCP tools. Phases: Init → Context → Fast-path → Plan → Research → Output. Use when research spans multiple domains and benefits from state persistence.
-
-| When | Example |
-|------|---------|
-| Multi-domain deep dive | "Research how auth works end-to-end" |
-| Comparative analysis | "Compare React vs Vue state management" |
-| Persistent sessions | "Continue researching from last checkpoint" |
+Multi-phase research with session management and checkpoints. Phases: Init > Context > Fast-path > Plan > Research > Output. Use when research spans multiple domains and needs state persistence.
 
----
-
-### 3. OctoCode Plan
-**Location:** `octocode-plan/`
+### 3. Plan
+`octocode-plan/`
 
-Evidence-based implementation planning. Understand → Research (delegates to Researcher/Research) → Plan → Implement. Use when you know the general approach and need actionable steps.
+Evidence-based implementation planning. Understand > Research (delegates to Researcher/Research) > Plan > Implement. For multi-step work needing actionable steps.
 
-| When | Example |
-|------|---------|
-| Multi-step work | "Plan auth refactor", "Plan API v2" |
-| Non-trivial tasks | "Research & plan this feature" |
+### 4. RFC Generator
+`octocode-rfc-generator/`
 
----
+Formal evaluation of technical decisions. Research > Draft RFC with alternatives > Validate > Implementation plan. Use when multiple approaches are viable and trade-offs matter.
 
-### 4. OctoCode RFC Generator
-**Location:** `octocode-rfc-generator/`
+### 5. Engineer
+`octocode-engineer/`
 
-For technical decisions that need formal evaluation. Understand → Research → Draft RFC with alternatives → Validate → Implementation plan. Use when multiple approaches are viable and you need to reason through trade-offs before committing.
+Full-stack code engineering — understand, write, analyze, audit. Combines CLI scanner (dependency graph + AST + 16 structural presets via `@ast-grep/napi`), and Octocode MCP local/LSP tools. Four modes: **Explore**, **Code**, **Analyze**, **Audit**. Enforces architecture-first thinking, TDD, no duplication, dual-layer verification (agentic + deterministic).
 
-| When | Example |
-|------|---------|
-| Technical decisions | "Create RFC for caching layer", "How should we build X?" |
-| Migrations / refactors | "RFC for auth migration", "Design doc for API v2" |
-| Architecture choices | "Should we use Redis or Memcached?", "Propose new pattern" |
+### 6. PR & Code Reviewer
+`octocode-pull-request-reviewer/`
 
----
+Holistic code review: bugs, security, architecture, flow impact. Supports remote PRs and local changes (staged/unstaged). 7 domains, LSP-powered flow tracing, evidence-backed.
 
-### 5. OctoCode Prompt Optimizer
-**Location:** `octocode-prompt-optimizer/`
+> Local mode requires `ENABLE_LOCAL=true` — see [README](https://github.com/bgauryy/octocode-mcp/blob/main/skills/octocode-pull-request-reviewer/README.md)
 
-Turns weak prompts into enforceable protocols. Gates, FORBIDDEN lists, failure analysis. Preserves intent, adds reliability.
+### 7. Roast
+`octocode-roast/`
 
-| When | Example |
-|------|---------|
-| Prompts ignored | "Agent keeps skipping steps" |
-| New/weak instructions | "Optimize this SKILL.md", "Make prompt reliable" |
+Brutal code critique with `file:line` citations. Severity levels: gentle > nuclear. Sin registry, user picks fixes.
 
-*Not for:* Short prompts (<50 lines), already-optimized docs.
-
----
-
-### 6. OctoCode Documentation Writer
-**Location:** `octocode-documentation-writer/`
-
-6-phase pipeline: Discovery → Questions → Research → Orchestration → Writing → QA. Produces 16+ docs with validation.
-
-| When | Example |
-|------|---------|
-| New/outdated docs | "Generate documentation", "Update docs" |
-| Onboarding | "Create docs for new devs" |
-
----
+### 8. Prompt Optimizer
+`octocode-prompt-optimizer/`
 
-### 7. OctoCode Roast
-**Location:** `octocode-roast/`
+Turns weak prompts into enforceable protocols. Gates, FORBIDDEN lists, failure analysis. Preserves intent, adds reliability. Not for short prompts (<50 lines) or already-optimized docs.
 
-Brutal code critique with file:line citations. Severity: gentle → nuclear. Sin registry, user picks fixes. Cites or dies.
-
-| When | Example |
-|------|---------|
-| Code critique | "Roast my code", "Find antipatterns" |
-| Honest feedback | "What's wrong with my code?" |
-
----
-
-### 8. OctoCode Local Code Scan
-**Location:** `octocode-local-code-scan/`
-
-AST-based repo-wide code quality scanner. Detects duplicate function bodies, repeated control-flow patterns, high-complexity functions, dependency cycles, critical dependency chains, and dead modules. Produces a prioritized JSON report with file:line references and suggested fixes. Optionally uses tree-sitter for richer metadata. Pairs with Octocode MCP local + LSP tools for investigation.
-
-| When | Example |
-|------|---------|
-| Code quality audit | "Analyze code quality", "Scan for tech debt" |
-| Duplicate detection | "Find duplicate code", "Find repeated patterns" |
-| Dependency analysis | "Find dependency cycles", "Show critical paths" |
-| Complexity check | "Check complexity", "Find oversized functions" |
-
----
-
-### 9. OctoCode Pull Request & Code Reviewer
-**Location:** `octocode-pull-request-reviewer/`
-
-Holistic code review via Octocode MCP: bugs, security, architecture, flow impact. Supports both **remote PRs** and **local changes** (staged/unstaged). 7 domains, LSP-powered flow tracing, evidence-backed, user checkpoint before deep dive.
-
-> **Local Mode** requires `ENABLE_LOCAL=true` — see [README](https://github.com/bgauryy/octocode-mcp/blob/main/skills/octocode-pull-request-reviewer/README.md)
-
-| When | Example |
-|------|---------|
-| PR review | "Review PR #456", "Check this PR" |
-| Local changes | "Review my changes", "Review staged changes" |
-| Security/impact | "Is this safe to merge?" |
-
----
+### 9. Documentation Writer
+`octocode-documentation-writer/`
 
+6-phase pipeline: Discovery > Questions > Research > Orchestration > Writing > QA. Produces 16+ validated docs.

package/skills/{octocode-code-engineer → octocode-engineer}/.claude/settings.local.json

@@ -12,7 +12,8 @@
       "Bash(npx vitest:*)",
       "Bash(cp:*)",
       "Bash(npx tsc 2>&1 && cp -R /Users/guybary/Documents/octocode-mcp/skills/octocode-local-code-quality/ /Users/guybary/.claude/skills/octocode-local-code-quality/ 2>&1)",
-      "Bash(cat:*)"
+      "Bash(cat:*)",
+      "Bash(npm run:*)"
     ]
   }
 }

package/skills/octocode-engineer/README.md

@@ -0,0 +1,99 @@
+<div align="center">
+  <img src="https://github.com/bgauryy/octocode-mcp/raw/main/packages/octocode-mcp/assets/logo_white.png" width="320" alt="Octocode Logo">
+  <h1>Octocode Code Engineer</h1>
+  <p><strong>AI agent skill for safe, codebase-aware engineering</strong></p>
+</div>
+
+## Why use this skill
+Use this skill when you want an agent to change code without guessing.
+
+It helps you:
+- find existing implementations before adding new code
+- estimate blast radius before refactors and renames
+- detect architecture, quality, dead-code, security, and test issues
+- validate findings with local + LSP evidence before reporting
+- track improvement with file-level findings and hybrid quality ratings
+
+## What it does
+The skill runs a scan + validation workflow:
+1. Map structure: files, functions, flows, dependency graph.
+2. Detect issues: 80+ categories across architecture, quality, dead code, security, and test quality.
+3. Validate critical findings: use local search + LSP navigation instead of raw heuristics only.
+4. Produce artifacts: machine-readable JSON and human-readable summary.
+
+## Key features
+- Architecture analysis: coupling, cycles, chokepoints, dependency critical paths.
+- Code quality analysis: complexity, duplication, risky async patterns, error-boundary gaps.
+- Dead-code hygiene: dead exports/files, unused deps, barrel issues.
+- Security checks: secrets, injection risks, traversal risks, unsafe sinks.
+- Test quality checks: assertion density, mocking hygiene, cleanup issues.
+- AST tools: structural search and AST tree exploration.
+- Hybrid quality ratings (AI + structure): Architecture & Structure, Folder Topology, Naming Quality, Common/Shared Layer Health, Maintainability & Evolvability, Codebase Consistency.
+
+## Rating model behavior
+- Soft-signal scoring (not rigid pass/fail lint rules).
+- Test files are excluded from hybrid ratings unless `--include-tests` is enabled.
+- Generated/minified/vendor paths are excluded from hybrid ratings by default.
+- Advisory categories are downweighted relative to hard defects to reduce noise.
+
+## Requirements
+For full capability, run with Octocode MCP local tools enabled:
+
+```json
+{
+  "mcpServers": {
+    "octocode": {
+      "command": "npx",
+      "type": "stdio",
+      "args": ["octocode-mcp@latest"],
+      "env": {
+        "ENABLE_LOCAL": "true"
+      }
+    }
+  }
+}
+```
+
+Without local tools, scanning still works, but semantic validation is reduced.
+
+## Install
+```bash
+npx octocode-cli skills install --skill octocode-code-engineer
+```
+
+Multi-target install:
+```bash
+npx octocode-cli skills install --skill octocode-code-engineer --targets claude-code,claude-desktop,cursor,codex,opencode
+```
+
+## Common commands
+From `skills/octocode-code-engineer/`:
+
+```bash
+# Fast default scan
+node scripts/run.js --root /path/to/repo --out .octocode/scan/latest
+
+# Include graph + semantic signals
+node scripts/run.js --root /path/to/repo --out .octocode/scan/latest --graph --semantic --flow
+
+# Analyze with tests
+node scripts/run.js --root /path/to/repo --out .octocode/scan/latest --include-tests
+```
+
+## Output files
+Typical outputs in `.octocode/scan/<run>/`:
+- `summary.md`: concise human report and triage guidance
+- `summary.json`: machine-readable overview + hybrid ratings
+- `findings.json`: all findings with category/severity/location
+- `architecture.json`, `code-quality.json`, `dead-code.json` (+ optional `security.json`, `test-quality.json`)
+- `file-inventory.json`: per-file functions/flows/dependencies
+- optional `graph.md`, `ast-trees.txt`
+
+## When not to use this skill
+Use other tools for:
+- syntax/type errors (`tsc`)
+- style formatting/lint policy (ESLint/Prettier)
+- runtime debugging (tests/debugger)
+
+## License
+MIT License © 2026 Octocode — see [LICENSE](https://github.com/bgauryy/octocode-mcp/blob/main/LICENSE).