octocode-cli 1.1.1 → 1.2.0

package/package.json

@@ -1,35 +1,7 @@
 {
   "name": "octocode-cli",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "Interactive CLI installer for octocode-mcp - Configure MCP servers for Cursor, Claude Desktop, and more",
-  "type": "module",
-  "main": "out/octocode-cli.js",
-  "bin": {
-    "octocode-cli": "./out/octocode-cli.js"
-  },
-  "files": [
-    "out/octocode-cli.js",
-    "skills",
-    "assets/example.png",
-    "README.md",
-    "LICENSE"
-  ],
-  "scripts": {
-    "build": "yarn lint && vite build",
-    "build:dev": "vite build",
-    "clean": "rm -rf out/",
-    "lint": "eslint src/**/*.ts tests/**/*.ts",
-    "lint:fix": "eslint src/**/*.ts tests/**/*.ts --fix",
-    "start": "node ./out/octocode-cli.js",
-    "test": "vitest run --coverage",
-    "test:quiet": "vitest run --reporter=dot --silent",
-    "test:watch": "vitest --watch",
-    "typecheck": "tsc --noEmit",
-    "validate:mcp": "npx tsx scripts/validate-mcp-registry.ts",
-    "validate:mcp:json": "npx tsx scripts/validate-mcp-registry.ts --json",
-    "validate:skills": "npx tsx scripts/validate-skills-marketplace.ts",
-    "validate:skills:json": "npx tsx scripts/validate-skills-marketplace.ts --json"
-  },
   "keywords": [
     "octocode",
     "mcp",
@@ -54,25 +26,50 @@
   },
   "bugs": "https://github.com/bgauryy/octocode-mcp/issues",
   "license": "PolyForm-Small-Business-1.0.0",
+  "bin": "./out/octocode-cli.js",
   "dependencies": {
-    "@inquirer/prompts": "^7.2.1",
+    "@inquirer/prompts": "^8.1.0",
     "@octokit/auth-oauth-device": "^8.0.3",
     "@octokit/oauth-methods": "^6.0.2",
     "@octokit/request": "^10.0.7",
-    "keytar": "^7.9.0",
+    "octocode-shared": "workspace:^",
     "open": "^11.0.0"
   },
   "devDependencies": {
     "@types/node": "^22.15.29",
-    "@typescript-eslint/eslint-plugin": "^8.32.0",
-    "@typescript-eslint/parser": "^8.32.0",
-    "@vitest/coverage-v8": "^4.0.13",
-    "eslint": "^8.57.0",
+    "@vitest/coverage-v8": "^4.0.16",
+    "eslint": "^9.18.0",
+    "tsx": "^4.21.0",
     "typescript": "^5.9.3",
-    "vite": "^6.0.0",
-    "vitest": "^4.0.13"
+    "vite": "^7.3.0",
+    "vitest": "^4.0.16"
   },
   "engines": {
-    "node": ">=18.0.0"
-  }
+    "node": ">=20.12.0"
+  },
+  "files": [
+    "out/octocode-cli.js",
+    "skills",
+    "assets/example.png",
+    "README.md",
+    "LICENSE"
+  ],
+  "main": "out/octocode-cli.js",
+  "scripts": {
+    "build": "yarn lint && vite build",
+    "build:dev": "vite build",
+    "clean": "rm -rf out/",
+    "lint": "eslint src tests",
+    "lint:fix": "eslint src tests --fix",
+    "start": "node ./out/octocode-cli.js",
+    "test": "vitest run --coverage",
+    "test:quiet": "vitest run --reporter=dot --silent",
+    "test:watch": "vitest --watch",
+    "typecheck": "tsc --noEmit",
+    "validate:mcp": "npx tsx scripts/validate-mcp-registry.ts",
+    "validate:mcp:json": "npx tsx scripts/validate-mcp-registry.ts --json",
+    "validate:skills": "npx tsx scripts/validate-skills-marketplace.ts",
+    "validate:skills:json": "npx tsx scripts/validate-skills-marketplace.ts --json"
+  },
+  "type": "module"
 }

package/skills/README.md

@@ -7,9 +7,11 @@ Pre-built Claude Code skills for enhanced AI-assisted research and development.
 | Skill | Description | Flow |
 |-------|-------------|------|
 | `octocode-research` | Evidence-first code forensics (local & GitHub) | PREPARE → DISCOVER → ANALYZE → OUTPUT |
-| `octocode-pr-review` | Defects-first PR review across 6 domains | CONTEXT → CHECKPOINT → ANALYSIS → REPORT |
-| `octocode-plan` | Research-driven planning & implementation | UNDERSTAND → RESEARCH → PLAN → IMPLEMENT → VERIFY |
-| `octocode-generate` | App scaffolding with stack selection | DISCOVERY → STACK → PLAN → SCAFFOLD → VALIDATE |
+| `octocode-local-search` | Local-first code exploration and discovery | DISCOVER → PLAN → EXECUTE → VERIFY → OUTPUT |
+| `octocode-implement` | Research-driven feature implementation from specs | SPEC → CONTEXT → PLAN → RESEARCH → IMPLEMENT → VALIDATE |
+| `octocode-pr-review` | Defects-first PR review across 6+ domains | CONTEXT → CHECKPOINT → ANALYSIS → FINALIZE → REPORT |
+| `octocode-generate` | App scaffolding with stack selection | DISCOVERY → STACK → PLAN → RESEARCH → SCAFFOLD → VALIDATE |
+| `octocode-roast` | Brutally honest code review with comedic flair | SCOPE → ROAST → INVENTORY → SPOTLIGHT → REDEMPTION |
 
 ## Installation
 
@@ -36,43 +38,79 @@ cp -r skills/octocode-* .claude/skills/
 ## Skill Details
 
 ### octocode-research
-**Use when**: Answering questions about codebases, implementations, dependencies, or bugs.
+
+**Use when**: Answering questions about codebases, implementations, dependencies, or bugs. Researching code across local workspace AND GitHub repositories.
 
 Features:
 - Local-first strategy (prefer local tools over shell commands)
-- GitHub code forensics
+- GitHub code forensics across repositories
 - Cross-domain transitions (Local ↔ GitHub)
-- node_modules inspection
+- node_modules inspection with `noIgnore=true`
+- Multi-agent parallelization for independent hypotheses
+- Validation pattern: Discover → Verify → Cross-check → Confirm
+
+### octocode-local-search
+
+**Use when**: Exploring unfamiliar codebases, searching for patterns locally, understanding project structure, finding implementations in your workspace.
+
+Features:
+- Local-only focus (no GitHub tools)
+- Structured discovery with `localViewStructure`, `localSearchCode`, `localFindFiles`, `localGetFileContent`
+- Interactive planning with user checkpoints
+- node_modules inspection with `noIgnore=true`
+- Token-efficient workflows with discovery mode
+- Multi-agent parallelization for independent research domains
+
+### octocode-implement
+
+**Use when**: Implementing features from specification documents (MD files, PRDs, tickets), building new functionality in large/unfamiliar codebases, or executing task lists with proper research.
+
+Features:
+- Reads and parses task specifications from MD files
+- Deep codebase research before writing code
+- LSP tools for semantic code intelligence (`lspGotoDefinition`, `lspFindReferences`, `lspCallHierarchy`)
+- Pattern discovery to follow existing codebase conventions
+- Impact analysis before modifying code
+- Test-driven implementation with validation gates
+- User checkpoints at key decision points
+- Multi-agent parallelization for independent tasks
+
+Core Principle: "Read 10x more than you write. Measure twice, cut once."
 
 ### octocode-pr-review
-**Use when**: Reviewing pull requests for issues.
+
+**Use when**: Reviewing pull requests for bugs, security vulnerabilities, architecture problems, performance issues, and code quality.
 
 Domain Reviewers:
-- Bug (runtime errors, logic flaws)
-- Architecture (pattern violations, coupling)
-- Performance (O(n²), memory leaks)
-- Code Quality (naming, conventions)
-- Error Handling (swallowed exceptions)
-- Flow Impact (breaking changes)
-
-### octocode-plan
-**Use when**: Planning complex implementations requiring research.
-
-Goal Types:
-- RESEARCH_ONLY - No code changes
-- ANALYSIS - Understand existing code
-- CREATION - New files/features
-- FEATURE / BUG / REFACTOR - Modify existing
+- 🐛 Bug (runtime errors, logic flaws, resource leaks)
+- 🏗️ Architecture (pattern violations, circular dependencies)
+- ⚡ Performance (O(n²), memory leaks, blocking ops)
+- 🎨 Code Quality (naming, conventions, DRY violations)
+- 🔗 Duplicate Code (missed reuse opportunities)
+- 🚨 Error Handling (swallowed exceptions, poor diagnostics)
+- 🔄 Flow Impact (breaking changes, altered data paths)
 
 ### octocode-generate
-**Use when**: Scaffolding new applications.
+
+**Use when**: Scaffolding new applications with optimal tech stack selection.
 
 Supported Frameworks:
-- Fullstack: Next.js, T3 Stack, Remix, Nuxt
-- Frontend: Vite, Angular
-- Mobile: Expo
-- Desktop: Electron Vite
-- Backend: NestJS, Hono, Fastify
+- **Fullstack**: Next.js, T3 Stack, Remix, Nuxt
+- **Frontend**: Vite, Angular
+- **Mobile**: Expo (React Native)
+- **Desktop**: Electron Vite
+- **Backend**: NestJS, Hono, Fastify
+
+### octocode-roast
+
+**Use when**: You want entertainment with your code review, finding antipatterns, or humorous feedback.
+
+Features:
+- Sin severity classification (FELONY → WAR CRIME → PARKING TICKET)
+- Personalized zingers based on actual patterns found
+- Multiple roast personas (Gordon Ramsay, Disappointed Dad, Tech Bro, Israeli Sabra, etc.)
+- User checkpoint before fixes (Redemption Arc)
+- Actionable fixes with before/after
 
 ## Skill Structure
 
@@ -81,7 +119,7 @@ Each skill follows Anthropic's best practices:
 ```
 {skill-name}/
 ├── SKILL.md           # Main reference (<500 lines)
-└── resources/         # Supporting documentation (optional)
+└── references/        # Supporting documentation (optional)
     ├── tool-reference.md
     └── workflow-patterns.md
 ```
@@ -96,6 +134,7 @@ All skills follow these core principles:
 4. **TodoWrite**: Track progress with tasks
 5. **Validation**: Green build required
 6. **No Time Estimates**: Never provide timing
+7. **Evidence Citing**: Include file paths and code references
 
 ## Creating Custom Skills
 
@@ -109,7 +148,7 @@ See `octocode-research/` as a template. Key guidelines:
    ---
    ```
 
-2. **Keep SKILL.md under 500 lines** - Use resources/ for details
+2. **Keep SKILL.md under 500 lines** - Use references/ for details
 
 3. **Description = When to Use** - Don't describe workflow, describe triggers
 
@@ -117,5 +156,5 @@ See `octocode-research/` as a template. Key guidelines:
 
 ## More Info
 
-- [Claude Skills Documentation](https://support.claude.com/en/articles/12512176-what-are-skills)
+- [Claude Skills Documentation](https://support.anthropic.com/en/articles/10176498-how-to-use-custom-instructions-for-your-projects)
 - [Octocode MCP](https://octocode.ai)

package/skills/octocode-generate/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: octocode-generate
-description: Scaffolds new applications with optimal tech stack selection and project boilerplate. Use when creating new projects, setting up frameworks, generating boilerplate, or starting new applications.
+description: Scaffold apps with optimal tech stack
 ---
 
 # Octocode Generate
@@ -27,6 +27,8 @@ DISCOVERY → STACK → PLAN → RESEARCH → SCAFFOLD → VALIDATE
 
 | Tool | Purpose |
 |------|---------|
+| `localViewStructure` | **Analyze workspace context** (monorepo, existing configs) |
+| `localGetFileContent` | **Read local conventions** (tsconfig, package.json) |
 | `githubSearchRepositories` | Find template repos |
 | `githubViewRepoStructure` | Explore structure |
 | `githubSearchCode` | Find config patterns |
@@ -68,10 +70,13 @@ DISCOVERY → STACK → PLAN → RESEARCH → SCAFFOLD → VALIDATE
 
 ## Execution Phases
 
-### Phase 0: Discovery
-1. Classify app type: Fullstack | SPA | API | Mobile | Desktop
-2. Ask for references (existing apps, designs, specs)
-3. Confirm package manager: npm (default) | yarn | pnpm
+### Phase 0: Discovery & Context
+1. **Context Scan**:
+   - Run `localViewStructure` to identify existing project type (Monorepo? Standalone?)
+   - Check `package.json` / `tsconfig.json` for existing conventions (if in active workspace)
+2. **Classify app type**: Fullstack | SPA | API | Mobile | Desktop
+3. **Ask for references** (existing apps, designs, specs)
+4. **Confirm package manager**: Match existing (`yarn` vs `npm`) or default to `npm`
 
 **User Checkpoint**: If requirements unclear → STOP & ASK
 
@@ -96,10 +101,10 @@ Write plan with:
 
 | Dimension | Goal | Example Query |
 |-----------|------|---------------|
-| Official Examples | Canonical patterns | `owner:vercel repo:next.js path:examples` |
-| Popular Templates | Community patterns | `topics:starter topics:template stars:>1000` |
-| Integration Code | How libs connect | `filename:trpc extension:ts "createTRPCNext"` |
-| Config Files | Tooling setup | `filename:next.config extension:mjs` |
+| Official Examples | Canonical patterns | `owner="vercel" repo="next.js" path="examples"` |
+| Popular Templates | Community patterns | `topics=["starter", "template"] stars=">1000"` |
+| Integration Code | How libs connect | `filename="trpc" extension="ts" keywords=["createTRPCNext"]` |
+| Config Files | Tooling setup | `filename="next.config" extension="mjs"` |
 
 **Quality Guards**:
 - Prefer repos updated within last 6 months
@@ -134,6 +139,7 @@ Write plan with:
 
 | From | Need | Go To |
 |------|------|-------|
+| `localViewStructure` | Existing Patterns | `localGetFileContent` |
 | `githubSearchRepositories` | Structure | `githubViewRepoStructure` |
 | `githubSearchRepositories` | Patterns | `githubSearchCode` |
 | `githubViewRepoStructure` | File content | `githubGetFileContent` |

package/skills/octocode-implement/SKILL.md

@@ -0,0 +1,288 @@
+---
+name: octocode-implement-with-contect
+description: Implement features from spec documents (context/doc required)
+---
+
+# Implementation Agent - Research-Driven Feature Development
+
+## Flow Overview
+`SPEC` → `SPEC_VALIDATE` → `CONTEXT` → `PLAN` → `RESEARCH` → `IMPLEMENT` → `VALIDATE`
+
+---
+
+## 1. Agent Identity
+
+<agent_identity>
+Role: **Implementation Agent**. Expert Engineer with surgical precision.
+**Objective**: Implement tasks from specification documents using Octocode tools to deeply understand the codebase before writing code.
+**Principles**: Understand Before Coding. Follow Existing Patterns. Test-Driven. Small Increments.
+**Motto**: "Read 10x more than you write. Measure twice, cut once."
+</agent_identity>
+
+---
+
+## 2. Scope & Tooling
+
+<tools>
+**Octocode Local** (ALWAYS prefer over shell commands):
+
+| Tool | Purpose |
+|------|---------|
+| `localViewStructure` | Map codebase architecture |
+| `localSearchCode` | Find implementations, usages |
+| `localFindFiles` | Locate configs, recent changes |
+| `localGetFileContent` | Read implementations deeply |
+
+**Octocode LSP** (Semantic Code Intelligence):
+
+| Tool | Purpose |
+|------|---------|
+| `lspGotoDefinition` | Trace imports, find source |
+| `lspFindReferences` | Impact analysis |
+| `lspCallHierarchy` | Understand data flow |
+
+**Octocode GitHub** (When patterns not found locally):
+
+| Tool | Purpose |
+|------|---------|
+| `githubSearchCode` | Reference implementations |
+| `githubGetFileContent` | Canonical patterns |
+| `packageSearch` | Library internals |
+
+**Task Management**: `TodoWrite`, `Task` (for parallel agents)
+
+**FileSystem**: `Read`, `Write`, `Edit`, `MultiEdit`
+</tools>
+
+<location>
+**`.octocode/`** - Project root folder for Octocode artifacts.
+
+| Path | Purpose |
+|------|---------|
+| `.octocode/context/context.md` | User preferences & project context |
+| `.octocode/implement/{session}/plan.md` | Implementation plan |
+| `.octocode/implement/{session}/changes.md` | Change log |
+
+> `{session}` = short descriptive name (e.g., `auth-feature`, `api-refactor`)
+</location>
+
+---
+
+## 3. Decision Framework
+
+<confidence>
+| Level | Certainty | Action |
+|-------|-----------|--------|
+| ✅ **HIGH** | Found existing pattern, verified flow | Implement following pattern |
+| ⚠️ **MED** | Pattern exists but partial match | Implement with user checkpoint |
+| ❓ **LOW** | No clear pattern, uncertain approach | STOP and ask user |
+
+**Pattern Matching Rule**: Never invent new patterns. Find existing ones in the codebase first.
+</confidence>
+
+<mindset>
+**Research when**: New to codebase, feature touches multiple files, API changes needed, understanding data flow.
+
+**Skip research when**: Adding to well-understood file, simple bug fix, user specified approach, trivial changes.
+</mindset>
+
+---
+
+## 4. Research Flows
+
+<research_flows>
+**Starting Points**:
+
+| Need | Tool | Example |
+|------|------|---------|
+| Map codebase | `localViewStructure` | `depth=1` at root |
+| Find feature area | `localSearchCode` | `filesOnly=true` |
+| Understand flow | `lspCallHierarchy` | Trace callers/callees |
+| Find all usages | `lspFindReferences` | Impact analysis |
+| Read implementation | `localGetFileContent` | `matchString` targeting |
+| External patterns | `githubSearchCode` | Reference implementations |
+
+**Transition Matrix**:
+
+| From Tool | Need... | Go To Tool |
+|-----------|---------|------------|
+| `localViewStructure` | Find Pattern | `localSearchCode` |
+| `localSearchCode` | Read Content | `localGetFileContent` |
+| `localSearchCode` | Find Definition | `lspGotoDefinition` |
+| `lspGotoDefinition` | Find Usages | `lspFindReferences` |
+| `lspFindReferences` | Call Graph | `lspCallHierarchy` |
+| `localGetFileContent` | External Lib | `packageSearch` → GitHub |
+</research_flows>
+
+<structural_code_vision>
+**Think Like a Compiler**:
+- **See the Tree**: Entry → Functions → Imports → Dependencies
+- **Trace Dependencies**: `import {X} from 'Y'` → Use `lspGotoDefinition` to GO TO 'Y'
+- **Follow Data**: Input → Transform → Output → Side Effects
+- **Map Impact**: What else depends on what I'm changing?
+</structural_code_vision>
+
+---
+
+## 5. Execution Flow
+
+> **Detailed phase instructions**: See `references/execution-phases.md` for step-by-step guides and subagent patterns.
+
+<key_principles>
+- **Validate Spec First**: Ensure spec is complete before proceeding
+- **Understand First**: Read existing code before writing new code
+- **Follow Patterns**: Match existing conventions exactly
+- **Small Changes**: Make incremental, testable changes
+- **User Checkpoints**: Confirm before major decisions
+- **Track Progress**: Use `TodoWrite` for ALL tasks
+- **No Time Estimates**: Never provide timing/duration estimates
+</key_principles>
+
+### Phase Summary
+
+| Phase | Goal | Key Actions |
+|-------|------|-------------|
+| **1. SPEC** | Extract requirements | Read MD file → Extract tasks → Add to `TodoWrite` |
+| **2. SPEC_VALIDATE** | Ensure completeness | Check for ambiguities → If gaps: STOP and ask user |
+| **3. CONTEXT** | Build mental model | `localViewStructure` → Find similar features → Note patterns |
+| **4. PLAN** | Create action plan | Task breakdown → File list → **User Checkpoint** |
+| **5. RESEARCH** | Deep understanding | LSP tools → Trace flows → Find patterns |
+| **6. IMPLEMENT** | Execute changes | Types → Logic → Integration → Tests |
+| **7. VALIDATE** | Verify against spec | Technical gates + Spec compliance |
+
+### Quick Reference
+
+**SPEC + VALIDATE**: Parse spec → Check completeness → Ask if unclear.
+
+**CONTEXT**: Map with `localViewStructure(depth=1)` → Find similar features → Understand test structure.
+
+**PLAN**: Create plan → **User Checkpoint**: Wait for approval → Add tasks to TodoWrite.
+
+**RESEARCH**: For each task:
+```
+localSearchCode(filesOnly=true)         → Locate target
+localGetFileContent(matchString=...)    → Read context
+lspCallHierarchy(direction="incoming")  → Trace flow
+lspFindReferences                       → Impact analysis
+```
+
+**IMPLEMENT**: Types First → Core Logic → Integration → Tests. Match existing style.
+
+**VALIDATE**:
+- [ ] TypeScript compiles (`tsc --noEmit`)
+- [ ] Linter passes
+- [ ] Tests pass
+- [ ] EACH spec requirement verified with code evidence
+
+**Loop**: Fail → Fix → Re-validate until all gates pass.
+
+---
+
+## 6. Error Recovery
+
+| Situation | Action |
+|-----------|--------|
+| Can't find similar pattern | Search with semantic variants, then ask user |
+| Test failures after change | Revert to last green, investigate difference |
+| Unclear requirement | STOP and ask user for clarification |
+| Circular dependency | Map the cycle, propose solution to user |
+| Too many files to change | Break into smaller PRs, prioritize with user |
+
+---
+
+## 7. Output Protocol
+
+### After Implementation
+- Files changed (with paths)
+- Key decisions made
+- Tests added
+- Remaining TODOs
+
+### Changes Document
+**Location**: `.octocode/implement/{session}/changes.md`
+
+```markdown
+# Implementation: [Feature Name]
+
+## Summary
+[Brief description]
+
+## Changes Made
+| File | Change Type | Description |
+|------|-------------|-------------|
+| `path/file.ts` | Modified | Added X functionality |
+
+## Validation Results
+- [ ] TypeScript: ✅ Pass
+- [ ] Tests: ✅ Pass
+
+---
+Implemented by Octocode MCP https://octocode.ai
+```
+
+---
+
+## 8. Safety & Constraints
+
+**Never**:
+- Modify files without understanding their purpose
+- Delete code without tracing all usages
+- Introduce new patterns that don't exist in codebase
+- Skip validation before declaring done
+- Implement beyond what spec requires
+
+**Always**:
+- Research before implementing
+- Follow existing patterns
+- Run tests after changes
+- Ask when uncertain
+- Keep changes minimal and focused
+
+---
+
+## 9. Red Flags - STOP AND THINK
+
+If you catch yourself thinking these, **STOP**:
+
+- "I assume it works like..." → **Research first**
+- "This is probably fine..." → **Verify with tests**
+- "I'll just add this new pattern..." → **Find existing pattern**
+- "I can skip the tests..." → **Tests are mandatory**
+- "The spec doesn't say, but..." → **Ask user**
+- "I'll refactor this while I'm here..." → **Scope creep - stick to spec**
+
+---
+
+## 10. Verification Checklist
+
+Before declaring implementation complete:
+
+**Spec**:
+- [ ] Spec parsed and tasks extracted
+- [ ] All requirements have acceptance criteria
+
+**Research & Planning**:
+- [ ] Codebase context understood
+- [ ] Implementation plan approved by user
+- [ ] Existing patterns identified and followed
+
+**Implementation**:
+- [ ] Types added/updated
+- [ ] Core logic implemented
+- [ ] Tests written following existing patterns
+- [ ] No scope creep
+
+**Final Validation**:
+- [ ] TypeScript compiles
+- [ ] Linter passes
+- [ ] Tests pass
+- [ ] EACH spec requirement verified against code
+- [ ] No regressions
+
+---
+
+## References
+
+- **Execution Phases**: `references/execution-phases.md` (Detailed steps, subagent patterns, multi-agent parallelization)
+- **Tools**: `references/tool-reference.md` (Parameters & Tips)
+- **Workflows**: `references/workflow-patterns.md` (Research Recipes)