octocode-cli 1.3.0 → 1.5.0

package/out/chunks/chunk-UCZCF3BQ.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { createRequire as __createRequire } from 'module';
+import { fileURLToPath as __fileURLToPath } from 'url';
+import { dirname as __dirname_fn } from 'path';
+const require = __createRequire(import.meta.url);
+const __filename = __fileURLToPath(import.meta.url);
+const __dirname = __dirname_fn(__filename);
+import{a as r}from"./chunk-V64AXUWB.js";var i=new Set;function e(){process.stdout.write("\x1B[?25h")}var o=!1;function l(){o||(o=!0,process.on("exit",e),process.on("SIGINT",()=>{e(),process.exit(0)}),process.on("SIGTERM",()=>{e(),process.exit(0)}),process.on("uncaughtException",n=>{e(),console.error("Uncaught exception:",n),process.exit(1)}))}var h=class{text;frames;i;timer;constructor(t=""){this.text=t,this.frames=["\u280B","\u2819","\u2839","\u2838","\u283C","\u2834","\u2826","\u2827","\u2807","\u280F"],this.i=0,this.timer=null}start(t,s=0){t&&(this.text=t),this.timer&&(clearInterval(this.timer),this.timer=null),l(),i.add(this),process.stdout.write("\x1B[?25l");let u=" ".repeat(s);return this.timer=setInterval(()=>{let c=this.frames[this.i++%this.frames.length];process.stdout.write(`\r${u}${r("cyan",c)} ${this.text}`)},80),this}clear(){return this.timer&&(clearInterval(this.timer),this.timer=null),i.delete(this),process.stdout.write("\r\x1B[2K"),process.stdout.write("\x1B[?25h"),this}stop(t="\u2713",s="green"){return this.timer&&(clearInterval(this.timer),this.timer=null),i.delete(this),process.stdout.write(`\r\x1B[2K${r(s,t)} ${this.text}
+`),process.stdout.write("\x1B[?25h"),this}succeed(t){return t&&(this.text=t),this.stop("\u2713","green")}fail(t){return t&&(this.text=t),this.stop("\u2717","red")}info(t){return t&&(this.text=t),this.stop("\u2139","blue")}warn(t){return t&&(this.text=t),this.stop("\u26A0","yellow")}update(t){return this.text=t,this}};export{h as a};

package/out/chunks/command-help-specs-JZXVSLZ5.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { createRequire as __createRequire } from 'module';
+import { fileURLToPath as __fileURLToPath } from 'url';
+import { dirname as __dirname_fn } from 'path';
+const require = __createRequire(import.meta.url);
+const __filename = __fileURLToPath(import.meta.url);
+const __dirname = __dirname_fn(__filename);
+import{k as o}from"./chunk-OQBJTZWK.js";import"./chunk-UCZCF3BQ.js";import"./chunk-CVNNNSMQ.js";import"./chunk-7476PETK.js";import"./chunk-V64AXUWB.js";import"./chunk-YBBF4DTY.js";function C(n){let m=o(n);return m?e(m):void 0}function e(n){let{handler:m,...d}=n;return d}export{C as findStaticCommandHelp};

package/out/chunks/commands-XBFPLHSQ.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { createRequire as __createRequire } from 'module';
+import { fileURLToPath as __fileURLToPath } from 'url';
+import { dirname as __dirname_fn } from 'path';
+const require = __createRequire(import.meta.url);
+const __filename = __fileURLToPath(import.meta.url);
+const __dirname = __dirname_fn(__filename);
+import{a,b,c,d,e,f,g,h,i,j,k}from"./chunk-OQBJTZWK.js";import"./chunk-UCZCF3BQ.js";import"./chunk-CVNNNSMQ.js";import"./chunk-7476PETK.js";import"./chunk-V64AXUWB.js";import"./chunk-YBBF4DTY.js";export{e as authCommand,h as cacheCommand,k as findCommand,a as installCommand,c as loginCommand,d as logoutCommand,g as mcpCommand,f as skillsCommand,i as statusCommand,j as syncCommand,b as tokenCommand};

package/out/chunks/help-P7TCOYAJ.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { createRequire as __createRequire } from 'module';
+import { fileURLToPath as __fileURLToPath } from 'url';
+import { dirname as __dirname_fn } from 'path';
+const require = __createRequire(import.meta.url);
+const __filename = __fileURLToPath(import.meta.url);
+const __dirname = __dirname_fn(__filename);
+import{a as n,b as e,c as p}from"./chunk-V64AXUWB.js";import"./chunk-YBBF4DTY.js";function r(t){let o=["",`  ${n("magenta",e("\u{1F50D}\u{1F419} octocode "+t.name))}`,"",`  ${t.description}`,""];if(t.usage&&(o.push(`  ${e("USAGE")}`),o.push(`    ${t.usage}`),o.push("")),t.options&&t.options.length>0){o.push(`  ${e("OPTIONS")}`);for(let s of t.options){let i=s.short?`-${s.short}, `:"    ",u=`--${s.name}`,a=s.hasValue?" <value>":"",l=s.default!==void 0?p(` (default: ${s.default})`):"";o.push(`    ${n("cyan",i+u+a)}${l}`),o.push(`        ${s.description}`)}o.push("")}process.stdout.write(`${o.join(`
+`)}
+`)}export{r as showCommandHelp};

package/out/chunks/main-help-ULF5PAQY.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { createRequire as __createRequire } from 'module';
+import { fileURLToPath as __fileURLToPath } from 'url';
+import { dirname as __dirname_fn } from 'path';
+const require = __createRequire(import.meta.url);
+const __filename = __fileURLToPath(import.meta.url);
+const __dirname = __dirname_fn(__filename);
+import{a as i,b as l,d as r}from"./chunk-7476PETK.js";import{a as o,b as e,c as t}from"./chunk-V64AXUWB.js";import"./chunk-YBBF4DTY.js";function $(){let n=[];for(let c of i){let a=l.filter(s=>r(s.name)===c);if(a.length!==0){n.push(`    ${t(c)}`);for(let s of a)n.push(`    ${o("cyan",s.name)}`)}}return n}function d(){let n=$(),c=l.length,a=["",`  ${o("magenta",e("\u{1F50D}\u{1F419} Octocode CLI"))}`,"",`  ${e("USAGE")}`,`    ${o("magenta","octocode")} <command> [options]                    ${t("manage Octocode")}`,`    ${o("magenta","octocode")} tools                                  ${t("list all tools")}`,`    ${o("magenta","octocode")} tools <name>                           ${t("show input schema")}`,`    ${o("magenta","octocode")} tools <n1> <n2> ...                    ${t("batch input schemas")}`,`    ${o("magenta","octocode")} tools <name> --queries '<json>'        ${t("run a tool")}`,`    ${o("magenta","octocode")} instructions                           ${t("MCP instructions + all schemas")}`,"",`  ${e("COMMANDS")}  ${t("(manage Octocode configuration)")}`,`    ${o("magenta","install")}          Configure octocode-mcp for an IDE`,`    ${o("magenta","auth")}             Manage GitHub authentication`,`    ${o("magenta","login / logout")}   Sign in or out of GitHub`,`    ${o("magenta","status / token")}   Show auth status or print token`,`    ${o("magenta","skills")}           Install/remove bundled Octocode skills`,`    ${o("magenta","mcp")}              Manage MCP marketplace`,`    ${o("magenta","sync")}             Sync MCP configs across IDEs`,`    ${o("magenta","cache")}            Inspect and clean Octocode cache`,"",`  ${e("TOOLS")}  ${t(`(${c} tools \u2014 run directly from terminal)`)}`,...n,"",`  ${e("OPTIONS")}`,`    ${o("cyan","--json")}            Raw JSON output`,`    ${o("cyan","-h, --help")}        Show this help`,`    ${o("cyan","-v, --version")}     Show version`,"",`  ${e("EXAMPLES")}`,`    ${o("yellow","octocode tools")}                                                          ${t("# list")}`,`    ${o("yellow","octocode tools localSearchCode")}                                          ${t("# schema")}`,`    ${o("yellow","octocode tools localSearchCode githubSearchCode")}                         ${t("# batch schemas")}`,`    ${o("yellow",`octocode tools localSearchCode --queries '{"path":".","pattern":"fn"}'`)}  ${t("# run")}`,`    ${o("yellow","octocode instructions")}                                                   ${t("# full context")}`,"",`    ${o("yellow","octocode install --ide cursor")}`,`    ${o("yellow","octocode skills install --targets claude-code,cursor")}`,"",o("magenta",`  \u2500\u2500\u2500 \u{1F50D}\u{1F419} ${e("https://octocode.ai")} \u2500\u2500\u2500`),""];process.stdout.write(`${a.join(`
+`)}
+`)}export{d as showHelp};

package/out/chunks/prompts-5E6VKRX5.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { createRequire as __createRequire } from 'module';
+import { fileURLToPath as __fileURLToPath } from 'url';
+import { dirname as __dirname_fn } from 'path';
+const require = __createRequire(import.meta.url);
+const __filename = __fileURLToPath(import.meta.url);
+const __dirname = __dirname_fn(__filename);
+import{a,b,c,d,e,f,g,h,i}from"./chunk-CVNNNSMQ.js";import"./chunk-YBBF4DTY.js";export{f as Separator,d as checkbox,b as confirm,c as input,h as isInquirerLoaded,g as loadInquirer,e as search,a as select,i as selectWithCancel};

package/out/chunks/spinner-URV2OX6O.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { createRequire as __createRequire } from 'module';
+import { fileURLToPath as __fileURLToPath } from 'url';
+import { dirname as __dirname_fn } from 'path';
+const require = __createRequire(import.meta.url);
+const __filename = __fileURLToPath(import.meta.url);
+const __dirname = __dirname_fn(__filename);
+import{a}from"./chunk-UCZCF3BQ.js";import"./chunk-V64AXUWB.js";import"./chunk-YBBF4DTY.js";export{a as Spinner};

package/out/chunks/tool-command-M6VA7P2F.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { createRequire as __createRequire } from 'module';
+import { fileURLToPath as __fileURLToPath } from 'url';
+import { dirname as __dirname_fn } from 'path';
+const require = __createRequire(import.meta.url);
+const __filename = __fileURLToPath(import.meta.url);
+const __dirname = __dirname_fn(__filename);
+import{a,b,c,d,e,f,g,h,i,j,k,l}from"./chunk-7476PETK.js";import"./chunk-V64AXUWB.js";import"./chunk-YBBF4DTY.js";export{a as TOOL_CATEGORIES,b as TOOL_DEFINITIONS,k as executeToolCommand,c as findToolDefinition,e as getDisplayFields,d as getToolCategory,i as getToolsContextString,j as printToolsContext,f as showAvailableTools,h as showMultipleToolSchemas,g as showToolHelp,l as toolCommand};

package/out/octocode-cli.js

@@ -5,4 +5,4 @@ import { dirname as __dirname_fn } from 'path';
 const require = __createRequire(import.meta.url);
 const __filename = __fileURLToPath(import.meta.url);
 const __dirname = __dirname_fn(__filename);
-import{c as m}from"./chunks/chunk-V64AXUWB.js";import"./chunks/chunk-YBBF4DTY.js";var d=new Set(["ide","method","m","output","o","hostname","H","git-protocol","p","type","t","skill","k","targets","mode","model","resume","r","id","client","c","search","category","env","config","tool","queries","input","responseCharLength","responseCharOffset"]),_=new Set(["help","h","version","v","force","source","json","status","dry-run","installed","repos","skills","logs","all","tools","local","lsp","api","list","schema","tools-context"]),x=new Set(["output","responseCharLength","responseCharOffset","tool","queries"]);function h(e,o){return _.has(o)?!1:d.has(o)?!0:e.command==="tool"||typeof e.options.tool=="string"}function g(e=process.argv.slice(2)){let o={command:null,args:[],options:{}},t=0;for(;t<e.length;){let i=e[t];if(i.startsWith("--")){let[n,s]=i.slice(2).split("=");s!==void 0?o.options[n]=s:h(o,n)&&t+1<e.length&&!e[t+1].startsWith("-")?(o.options[n]=e[t+1],t++):o.options[n]=!0}else if(i.startsWith("-")&&!i.startsWith("--")&&i.length>2){let n=i.slice(1),[s,r]=n.split("=");if(x.has(s))r!==void 0?o.options[s]=r:h(o,s)&&t+1<e.length&&!e[t+1].startsWith("-")?(o.options[s]=e[t+1],t++):o.options[s]=!0;else{let l=n,a=l[l.length-1];if(l.length===1&&d.has(a)&&t+1<e.length&&!e[t+1].startsWith("-"))o.options[a]=e[t+1],t++;else for(let c of l)o.options[c]=!0}}else if(i.startsWith("-")&&i.length>1){let n=i.slice(1),s=n[n.length-1];if(n.length===1&&d.has(s)&&t+1<e.length&&!e[t+1].startsWith("-"))o.options[s]=e[t+1],t++;else for(let r of n)o.options[r]=!0}else o.command||typeof o.options.tool=="string"?o.args.push(i):o.command=i;t++}return!o.command&&typeof o.options.tool=="string"&&(o.command="tool",o.args=[o.options.tool,...o.args]),o}function C(e){return!!(e.options.help||e.options.h)}function w(e){return!!(e.options.version||e.options.v)}async function P(){return import("./chunks/commands-M3QTWKWE.js")}async function H(){return import("./chunks/command-help-specs-CQ3RBLP6.js")}async function p(){return import("./chunks/tool-command-VHFLPIHY.js")}async function u(){return import("./chunks/main-help-HXFAFHPG.js")}async function I(){return import("./chunks/help-XPXP46ZT.js")}function A(){console.log(),console.log("  Use octocode-cli --tool <toolName> --queries '<json-stringified-input>'."),console.log(`  Example: octocode-cli --tool localSearchCode --queries '{"path":".","pattern":"runCLI"}'`),console.log()}function L(){console.log("octocode-cli v1.3.0")}async function y(e){let o=g(e);if(o.options["tools-context"]===!0){let{printToolsContext:n}=await p();return await n(),!0}if(C(o)){if(o.command==="tool"&&typeof o.options.tool=="string"&&typeof o.args[0]=="string"){let{showToolHelp:s}=await p();if(await s(o.args[0]))return!0}if(o.command==="tool"){let{showHelp:s}=await u();return s(),!0}if(o.command){let[{findStaticCommandHelp:s},{showCommandHelp:r}]=await Promise.all([H(),I()]),l=s(o.command);if(l)return r(l),!0;let[{findCommand:a},{showHelp:c}]=await Promise.all([P(),u()]),f=a(o.command);return f?(r(f),!0):(c(),!0)}let{showHelp:n}=await u();return n(),!0}if(w(o))return L(),!0;if(!o.command)return!1;if(o.command==="tool")return typeof o.options.tool!="string"?(A(),process.exitCode=1,!0):(await(await p()).executeToolCommand(o)||(process.exitCode=1),!0);let{findCommand:t}=await P(),i=t(o.command);return i?(await i.handler(o),!0):(console.log(),console.log(`  Unknown command: ${o.command}`),console.log("  Run 'octocode-cli --help' to see available commands."),console.log(),process.exitCode=1,!0)}async function T(){let{showHelp:e}=await import("./chunks/main-help-HXFAFHPG.js");e()}async function O(){await y()||await T()}function S(){process.stdout.write("\x1B[?25h"),console.log(),console.log(m("  Goodbye! \u{1F44B}")),process.exit(0)}process.on("SIGINT",S);process.on("SIGTERM",S);O().catch(e=>{e?.name==="ExitPromptError"&&(console.log(),console.log(m("  Goodbye! \u{1F44B}")),process.exit(0)),console.error("Error:",e),process.exit(1)});
+import{c as d}from"./chunks/chunk-V64AXUWB.js";import"./chunks/chunk-YBBF4DTY.js";var p=new Set(["ide","method","m","output","o","hostname","H","git-protocol","p","type","t","skill","k","local","limit","l","targets","mode","model","resume","r","id","client","c","search","category","env","config","tool","queries","input","responseCharLength","responseCharOffset","target","backup-path"]),S=new Set(["help","h","version","v","force","source","json","status","dry-run","installed","repos","skills","logs","all","tools","full","direct","lsp","api","list","schema","tools-context","check","rollback","install","yes","y","validate","sync"]),T=new Set(["output","responseCharLength","responseCharOffset","tool","queries"]);function h(t,o){return S.has(o)?!1:p.has(o)?!0:t.command==="tool"||typeof t.options.tool=="string"}function g(t=process.argv.slice(2)){let o={command:null,args:[],options:{}},e=0;for(;e<t.length;){let i=t[e];if(i.startsWith("--")){let[s,n]=i.slice(2).split("=");n!==void 0?o.options[s]=n:h(o,s)&&e+1<t.length&&!t[e+1].startsWith("-")?(o.options[s]=t[e+1],e++):o.options[s]=!0}else if(i.startsWith("-")&&!i.startsWith("--")&&i.length>2){let s=i.slice(1),[n,r]=s.split("=");if(T.has(n))r!==void 0?o.options[n]=r:h(o,n)&&e+1<t.length&&!t[e+1].startsWith("-")?(o.options[n]=t[e+1],e++):o.options[n]=!0;else{let a=s,c=a[a.length-1];if(a.length===1&&p.has(c)&&e+1<t.length&&!t[e+1].startsWith("-"))o.options[c]=t[e+1],e++;else for(let m of a)o.options[m]=!0}}else if(i.startsWith("-")&&i.length>1){let s=i.slice(1),n=s[s.length-1];if(s.length===1&&p.has(n)&&e+1<t.length&&!t[e+1].startsWith("-"))o.options[n]=t[e+1],e++;else for(let r of s)o.options[r]=!0}else o.command||typeof o.options.tool=="string"?o.args.push(i):o.command=i;e++}return!o.command&&typeof o.options.tool=="string"&&(o.command="tool",o.args=[o.options.tool,...o.args]),o}function w(t){return!!(t.options.help||t.options.h)}function C(t){return!!(t.options.version||t.options.v)}async function P(){return import("./chunks/commands-XBFPLHSQ.js")}async function H(){return import("./chunks/command-help-specs-JZXVSLZ5.js")}async function l(){return import("./chunks/tool-command-M6VA7P2F.js")}async function u(){return import("./chunks/main-help-ULF5PAQY.js")}async function _(){return import("./chunks/help-P7TCOYAJ.js")}function I(){console.log(),console.log("  Use octocode --tool <toolName> --queries '<json-stringified-input>'."),console.log(`  Example: octocode --tool localSearchCode --queries '{"path":".","pattern":"runCLI"}'`),console.log()}function A(){console.log("octocode v1.5.0")}async function y(t){let o=g(t);if(o.options["tools-context"]===!0){let{printToolsContext:s}=await l();return await s(),!0}if(w(o)){if(o.command==="tool"&&typeof o.options.tool=="string"&&typeof o.args[0]=="string"){let{showToolHelp:n}=await l();if(await n(o.args[0]))return!0}if(o.command==="tool"){let{showHelp:n}=await u();return n(),!0}if(o.command==="tools"){if(typeof o.args[0]=="string"){let{showToolHelp:r}=await l();if(await r(o.args[0]))return!0}let{showAvailableTools:n}=await l();return await n(),!0}if(o.command){let[{findStaticCommandHelp:n},{showCommandHelp:r}]=await Promise.all([H(),_()]),a=n(o.command);if(a)return r(a),!0;let[{findCommand:c},{showHelp:m}]=await Promise.all([P(),u()]),f=c(o.command);return f?(r(f),!0):(m(),!0)}let{showHelp:s}=await u();return s(),!0}if(C(o))return A(),!0;if(!o.command)return!1;if(o.command==="tool")return typeof o.options.tool!="string"?(I(),process.exitCode=1,!0):(await(await l()).executeToolCommand(o)||(process.exitCode=1),!0);if(o.command==="tools"){let{executeToolCommand:s}=await l();return await s(o)||(process.exitCode=1),!0}if(o.command==="instructions"){let{printToolsContext:s}=await l();return await s(),!0}let{findCommand:e}=await P(),i=e(o.command);return i?(await i.handler(o),!0):(console.log(),console.log(`  Unknown command: ${o.command}`),console.log("  Run 'octocode --help' to see available commands."),console.log(),process.exitCode=1,!0)}async function L(){let{showHelp:t}=await import("./chunks/main-help-ULF5PAQY.js");t()}async function N(){await y()||await L()}function x(){process.stdout.write("\x1B[?25h"),console.log(),console.log(d("  Goodbye! \u{1F44B}")),process.exit(0)}process.on("SIGINT",x);process.on("SIGTERM",x);N().catch(t=>{t?.name==="ExitPromptError"&&(console.log(),console.log(d("  Goodbye! \u{1F44B}")),process.exit(0)),console.error("Error:",t),process.exit(1)});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "octocode-cli",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "description": "Interactive CLI installer for octocode-mcp - Configure MCP servers for Cursor, Claude Desktop, and more",
   "keywords": [
     "ai-coding",
@@ -27,7 +27,9 @@
   "bugs": "https://github.com/bgauryy/octocode-mcp/issues",
   "license": "MIT",
   "type": "module",
-  "bin": "./out/octocode-cli.js",
+  "bin": {
+    "octocode": "./out/octocode-cli.js"
+  },
   "files": [
     "out",
     "skills",
@@ -66,7 +68,7 @@
     "@vitest/coverage-v8": "^4.0.16",
     "esbuild": "^0.27.2",
     "eslint": "^9.18.0",
-    "octocode-mcp": "workspace:^",
+    "octocode-mcp": "^15.0.0",
     "octocode-shared": "workspace:^",
     "open": "^11.0.0",
     "tsx": "^4.21.0",

package/skills/README.md

@@ -1,84 +1,86 @@
 # OctoCode Skills
 
-Specialized AI agent skills extending OctoCode's capabilities.
+Specialized AI agent skills extending OctoCode. 19 skills live under `skills/`.
 
 ---
 
-## Quick Reference
-
-| Need | Skill | Triggers |
-|------|-------|----------|
-| Install & configure Octocode | **Install** | "Install octocode", "Set up octocode", "Configure MCP", "Get started" |
-| 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" |
-| Design system & UI architecture | **Design** | "Generate DESIGN.md", "Design system for this app", "Design review" |
-| Repo documentation | **Doc Writer** | "Document this project", "Create dev docs" |
+## Skill Lookup
+
+| Skill | Directory | Use For |
+|-------|-----------|---------|
+| **Install** | `octocode-install/` | Set up OctoCode, auth, IDE MCP, and skills. |
+| **CLI** | `octocode-cli/` | Run Octocode tools from the shell. |
+| **Researcher** | `octocode-researcher/` | Fast code search, symbol lookup, and file discovery. |
+| **Research** | `octocode-research/` | Multi-phase investigations with checkpoints. |
+| **Brainstorming** | `octocode-brainstorming/` | Validate ideas with prior art and market evidence. |
+| **Plan** | `octocode-plan/` | Build evidence-backed implementation plans. |
+| **RFC Generator** | `octocode-rfc-generator/` | Compare approaches and write technical proposals. |
+| **Engineer** | `octocode-engineer/` | Understand, implement, refactor, and audit code. |
+| **PR Reviewer** | `octocode-pull-request-reviewer/` | Review PRs or local diffs for defects and risk. |
+| **Roast** | `octocode-roast/` | Brutal but actionable code-quality critique. |
+| **Prompt Optimizer** | `octocode-prompt-optimizer/` | Harden prompts, skills, and agent instructions. |
+| **Design** | `octocode-design/` | Generate design-system and UI architecture guidance. |
+| **Doc Writer** | `octocode-documentation-writer/` | Produce comprehensive project documentation. |
+| **News** | `octocode-news/` | Research recent AI, DevTools, web, and security updates. |
+| **Search Skill** | `octocode-search-skill/` | Find, preview, and download agent skills. |
+| **Chrome DevTools** | `octocode-chrome-devtools/` | Open Chrome via CDP, generate inspection scripts, trace errors to source. |
+| **Agentic Flow Best Practices** | `agentic-flow-best-practices/` | Design agentic workflow patterns, agent collaboration, MCP/tool boundaries, context, memory scopes, caching, prompts, model settings, gates, and verification. |
+| **Stats** | `octocode-stats/` | Render Octocode usage dashboards from local stats files. |
 
 ---
 
-## Skills
+## Skill Details
 
-### 1. Install
-`octocode-install/`
+### Install
+Guided setup for OctoCode CLI/MCP, authentication, IDE config, and skill installation.
 
-Step-by-step setup for macOS and Windows: install via `npx octocode-cli`, choose an auth method (GitHub OAuth, PAT, GitLab, Bitbucket), configure your IDE, and install skills. Includes efficient skill usage guide.
+### CLI
+Terminal workflow for Octocode tools, including code search, file reads, repo search, PR search, and package lookup.
 
-### 2. Researcher
-`octocode-researcher/`
+### Researcher
+Default targeted research skill for local/GitHub code exploration, LSP navigation, callers, references, and package research.
 
-Default research skill. Direct code exploration via Octocode MCP — local (LSP, search, structure) and external (GitHub, npm/PyPI, PRs). No server needed.
+### Research
+Stateful deep research flow for broad, multi-step questions that need phases, checkpoints, and evidence synthesis.
 
-### 3. Research (HTTP Server)
-`octocode-research/`
+### Brainstorming
+Evidence-first idea validation across GitHub, package ecosystems, and web sources; outputs a decision brief.
 
-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.
+### Plan
+Turns researched context into concrete implementation steps, risks, tests, and execution order.
 
-### 4. Plan
-`octocode-plan/`
+### RFC Generator
+Creates technical decision docs with alternatives, trade-offs, recommendation, and rollout plan.
 
-Evidence-based implementation planning. Understand > Research (delegates to Researcher/Research) > Plan > Implement. For multi-step work needing actionable steps.
+### Engineer
+Architecture-aware engineering skill for exploration, coding, analysis, audits, refactors, and quality checks.
 
-### 5. RFC Generator
-`octocode-rfc-generator/`
+### PR Reviewer
+Holistic review of remote PRs or local changes, focused on bugs, security, architecture, flow impact, and tests.
 
-Formal evaluation of technical decisions. Research > Draft RFC with alternatives > Validate > Implementation plan. Use when multiple approaches are viable and trade-offs matter.
+### Roast
+Entertaining severity-ranked critique with concrete fixes for code smells, antipatterns, and maintainability issues.
 
-### 6. Engineer
-`octocode-engineer/`
+### Prompt Optimizer
+Improves long prompts and agent instructions with gates, failure-mode controls, and enforceable protocols.
 
-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).
+### Design
+Builds practical UI/design-system guidance for visual language, components, accessibility, performance, and responsiveness.
 
-### 7. PR & Code Reviewer
-`octocode-pull-request-reviewer/`
+### Doc Writer
+Documentation pipeline for onboarding, architecture, APIs, workflows, and validated developer docs.
 
-Holistic code review: bugs, security, architecture, flow impact. Supports remote PRs and local changes (staged/unstaged). 7 domains, LSP-powered flow tracing, evidence-backed.
+### News
+Scans recent AI, developer tooling, web platform, security, and notable-repo updates into a concise report.
 
-> Local mode requires `ENABLE_LOCAL=true` — see [README](https://github.com/bgauryy/octocode-mcp/blob/main/skills/octocode-pull-request-reviewer/README.md)
+### Search Skill
+Searches GitHub for `SKILL.md` files, scores relevance, previews results, and downloads selected skill folders.
 
-### 8. Roast
-`octocode-roast/`
+### Chrome DevTools
+Opens Chrome with CDP WebSocket debugging, generates a custom inspection script per task, runs it live, and traces errors back to source code using Octocode local tools. Covers network, console, performance, DOM, CSS, screenshots, iframes, service workers, and any CDP domain. Includes script self-review, CDP error retry, and multi-target routing.
 
-Brutal code critique with `file:line` citations. Severity levels: gentle > nuclear. Sin registry, user picks fixes.
+### Agentic Flow Best Practices
+Designs practical agentic flows by choosing the simplest reliable pattern, shaping context packets, defining MCP/tool and skill boundaries, planning session/agent/shared memory scopes, tuning model configuration, and adding gates and verification where risk demands it.
 
-### 9. Prompt Optimizer
-`octocode-prompt-optimizer/`
-
-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.
-
-### 10. Design
-`octocode-design/`
-
-Dynamic design-system and UI architecture skill for client apps. Generates `DESIGN.md` using Octocode MCP local tools first, then adapts depth by project maturity (existing vs new). Covers visual language, styling strategy, component architecture, framework constraints, accessibility, performance, responsive behavior, SEO, and implementation mapping.
-
-> See [README](https://github.com/bgauryy/octocode-mcp/blob/main/skills/octocode-design/README.md)
-
-### 11. Documentation Writer
-`octocode-documentation-writer/`
-
-6-phase pipeline: Discovery > Questions > Research > Orchestration > Writing > QA. Produces 16+ validated docs.
+### Stats
+Renders an Octocode MCP usage dashboard from `${OCTOCODE_HOME}/stats.json` or `~/.octocode/stats.json`, including saved tokens/chars, cache hits, errors, and rate limits.

package/skills/agentic-flow-best-practices/SKILL.md

@@ -0,0 +1,280 @@
+---
+name: agentic-flow-best-practices
+description: Use when the user asks to design, review, implement, debug, or evaluate an agentic workflow or AI-agent harness: MCP tools/resources/prompts, multi-agent routing or handoffs, agent memory/context/cache, Zod/JSON-schema protocols, human gates, observability, evals, or production safety. Do not use for ordinary app code, generic prompt writing, or model comparison unless an agentic flow boundary is involved.
+---
+
+# Agentic Flow Best Practices
+
+This skill is a compact thinking framework for agentic systems. It should help an agent choose the simplest reliable design, reason about the harness, and avoid wasting context.
+
+## Reference Routing
+
+Load references when they help the current decision:
+
+- `references/resources.md`: research launchpad with official docs, GitHub/source repos, and search hints for MCP, agent frameworks, context, memory, caching, and long-context risks.
+- `references/pr-review-agent-example.md`: compact build-ready workflow example.
+- `references/agent-collaboration-patterns.md`: compact guide to flows between agents, roles, handoffs, agents-as-tools, routing, review, and shared workspaces.
+
+When framework/protocol behavior matters, verify from official docs or source. Prefer project-local conventions first; use Octocode MCP tools when available. Carry evidence only when it changes the design.
+
+## Operating Loop
+
+Use this loop for substantial agentic-flow work:
+
+1. Understand the user-visible outcome, non-goals, risk, and deployment surface.
+2. Map what each model/agent sees and what each tool, memory, cache, or side effect can change.
+3. Choose the smallest pattern that satisfies the outcome; name the rejected heavier option when useful.
+4. Define protocols at boundaries: inputs, outputs, tools, handoffs, memory writes, gates, traces, and errors.
+5. Design state, context, memory, cache, permissions, and ownership before adding agents.
+6. Add gates, evals, observability, and rollout controls proportional to risk.
+7. Output a compact design or review with assumptions, unknowns, and next verification steps.
+
+Stop when the chosen pattern, contracts, gates, and verification plan are clear enough for the user's next decision. Ask one focused question only when a missing fact changes architecture, permissions, or side effects.
+
+## Agentic Flow Brain
+
+For any agentic flow, focus on the dimensions that affect the decision:
+
+| Dimension | Question |
+|---|---|
+| Outcome | What user-visible job is done, and what is out of scope? |
+| User experience | What should the user approve, see, interrupt, resume, or recover from? |
+| Autonomy | Prompt, workflow, graph, tool-using agent, or multi-agent? |
+| Runtime | Who owns the loop: code, protocol client, framework runtime, graph engine, or custom harness? |
+| Tools/MCP | What tools/resources/prompts exist, who may call them, and what needs approval? |
+| Identity | Which user, tenant, agent, service account, or policy grants each action? |
+| Visible surface | What does each agent actually see: messages, instructions, MCP prompts/resources, tools, schemas, memory, retrieval, and examples? |
+| Protocols | Which Zod schemas govern input, node output, tool result, handoff, memory, cache, gate, trace, and errors? |
+| Context | What is static, retrieved, summarized, offloaded, isolated in subagents, or passed by artifact reference? |
+| Memory | What is session state, checkpoint, agent-private, shared, user/project/org memory, artifact, or cache? |
+| Data | What data can cross tenants, tools, models, logs, caches, memories, and artifacts? |
+| Models | Which model class, reasoning effort, output budget, temperature, and fallback fit each node? |
+| Safety | Where can the flow leak data, trust poisoned context, take irreversible action, or write bad memory? |
+| Reliability | What retries, idempotency keys, timeouts, cancellation, and concurrency controls exist? |
+| Observability | Can traces show route, schema version, model config, tool calls, cache decisions, errors, tokens, cost? |
+| Evals | What golden, adversarial, schema, memory, and tool-failure tests prove behavior? |
+| Rollout | How will versions, migrations, flags, canaries, and rollback work? |
+
+Think first, then choose the smallest design that satisfies the outcome. The answer should feel like tradeoff reasoning, not a completed form.
+
+## Pattern Choice
+
+Start simple; add autonomy only when it solves a real constraint.
+
+- Direct answer or augmented LLM: low-risk response, one model call, retrieval, tools, or memory.
+- Deterministic pipeline or prompt chain: fixed parsing, transforms, validation, idempotency, and gated subtasks.
+- Router/model router: known categories need distinct prompts, tools, or models.
+- Parallel, map-reduce, or orchestrator-workers: independent facets, large inputs, speed, or runtime-discovered subtasks.
+- Evaluator-optimizer or reviewer: clear criteria and independent quality/safety review help.
+- Graph/state machine or autonomous loop: durable execution, checkpoints, resume, human gates, or `plan -> act -> observe -> update -> stop`.
+- Agents as tools, handoff, supervisor, or blackboard: separation needs distinct context, tools, permissions, ownership, or shared artifacts.
+- Background consolidation: memory, evals, or summaries can run after the user-facing response.
+
+
+Framework fit is contextual, not a ranking: plain code for deterministic/small workflows; MCP for exposing tools/resources/prompts, not orchestration; SDKs or ADK-style runtimes when lifecycle, sessions, tools, tracing, and structured outputs are modeled; graph runtimes for durable state, persistence, human-in-loop, and long-running agents. Use names like OpenAI Agents SDK, Google ADK, LangChain, and LangGraph as examples to research, not required dependencies.
+
+## Coverage Checks
+
+Check these areas when they affect the decision:
+
+- Product: user intent, interruption/resume, preview UX, explanation, and escalation path.
+- Access: auth, tenant isolation, tool allowlists, service accounts, and audit trails.
+- Data: PII/secrets handling, retention, redaction, training/logging policy, and cross-model sharing.
+- Operations: deployment target, queueing, concurrency, cancellation, idempotency, rollback, and cost/latency budgets.
+- Governance: human gates, policy checks, memory approval, provenance, and delete/export behavior.
+- Evolution: prompt/schema/tool versioning, cache invalidation, migrations, eval drift, and compatibility.
+
+## Nodes And State
+
+Describe the flow as nodes, not transcript history. For important nodes, capture:
+
+- `purpose`: why this node exists.
+- `inputSchema` / `outputSchema`: Zod schemas or artifact contracts.
+- `tools`: allowed tools and why.
+- `state`: fields read/written and owner.
+- `cache`: key, scope, freshness, invalidation, or `none`.
+- `memory`: search/write/ignore plus consent and retention.
+- `failure`: retry, ask, fallback, stop, or gate.
+- `sideEffects`: files, APIs, messages, deploys, payments, memory writes.
+- `runControl`: timeout, cancellation, resume, idempotency, and concurrency behavior.
+
+Common nodes: `classify`, `retrieve`, `compute`, `reason`, `delegate`, `review`, `act`, `observe`.
+
+## Zod Protocols
+
+Agentic systems communicate through protocols. Agent-to-agent, node-to-node, agent-to-tool, cache, memory, gate, trace, and side-effect boundaries should have runtime-validated schemas. In TypeScript, use Zod as the source of truth; in other runtimes, use an equivalent schema library and keep JSON Schema interoperability.
+
+Define the contracts that exist:
+
+- `FlowInput`, `NodeInput`, `NodeOutput`
+- `AgentTask`, `AgentResult`, `AgentHandoff`
+- `ToolCall`, `ToolResult`, `ErrorEnvelope`
+- `MemoryQuery`, `MemoryCandidate`, `MemoryWrite`
+- `CacheEntry`, `HumanGate`, `TraceEvent`
+- `PolicyDecision`, `RunControl`, `ArtifactRef`
+
+Zod rules:
+
+- Define Zod first; infer TypeScript types from schemas.
+- `safeParse` runtime boundaries before trusting data.
+- Generate JSON Schema from Zod/equivalent schemas for model/tool/MCP structured-output APIs.
+- Version schemas with prompts, tools, cache, memory, and model changes.
+- Use discriminated unions for routes, outcomes, and errors.
+- Represent ambiguity explicitly: `unknown`, `not_found`, `not_allowed`, `redacted`.
+- Keep schemas small and composable; avoid giant shared state blobs.
+- Attach provenance to decision facts: source path/URL/tool id/trace id/timestamp.
+
+Minimal packet shape: `AgentTask` should include `goal`, `inputs`, `knownFacts`, `constraints`, `allowedTools`, `expectedOutput`, and `stopConditions`. `AgentResult` should include `status`, `output`, `evidence`, `unknowns`, and `memoryCandidates`.
+
+## Context Engineering
+
+Attention is finite. Large context windows raise the ceiling but do not guarantee the model uses all tokens well; relevant facts buried in the middle can be missed. More context can lower signal-to-noise, duplicate facts, increase cost/latency, and create conflicting instructions.
+
+Pass packets, not full history:
+
+```text
+goal, inputs, knownFacts, decisions, openQuestions, constraints,
+artifacts, expectedOutput
+```
+
+Before expanding context:
+
+1. Reuse validated cache.
+2. Retrieve the smallest relevant chunk.
+3. Summarize with sources and omissions.
+4. Ask if the missing fact changes architecture.
+5. Pass broader context only when narrower context fails.
+
+Token efficiency rules:
+
+- Dedupe, rank, chunk, summarize, and retrieve on demand.
+- Keep one source of truth per fact; pass the freshest cited version plus references.
+- Prefer artifact paths, URLs, cache keys, trace ids over copied content.
+- Keep stable instructions/examples before dynamic input for prompt caching; do not rewrite cacheable prefixes casually.
+- Strip secrets, stale facts, speculation, and irrelevant history.
+- Use context isolation: subagents inspect heavy artifacts and return compact Zod-valid results.
+- Reserve output budget for visible answer and hidden reasoning tokens.
+
+## Agent-Visible Surface
+
+Review what each agent/model call actually receives, not only what the architecture diagram intends:
+
+- Messages: system, developer, user, framework wrappers, skill text, node prompt.
+- MCP surface: server instructions, tool names/descriptions, input schemas, output schemas, prompts, resources, and error text.
+- Context surface: retrieved chunks, memory snippets, cache summaries, examples, prior decisions, artifacts, and hidden runtime facts exposed to the LLM.
+- Action surface: allowed tools, approval gates, side effects, retries, and fallback instructions.
+
+Check for duplicated or conflicting instructions across prompts, skills, MCP prompts, tool descriptions, schemas, memory, and retrieved docs. Keep one source of truth; place stable invariant instructions in the harness or stable prefix, and pass changing facts through compact task packets.
+
+## Memory Scopes
+
+Separate memory, state, cache, and artifacts.
+
+- Runtime and LLM-visible context: clients/auth/request ids stay outside the model unless needed; task packets and retrieved chunks stay small and fresh.
+- Working state, session state, and checkpoints: keep run/thread/resume data separate from durable facts.
+- Agent-private, shared-flow, and user/project/org memory: define owner, scope, consent, retention, and conflict behavior.
+- External knowledge, artifacts, and cache: cite retrieval, version artifacts, and key caches by tenant/scope/freshness without secrets.
+
+
+Memory rules:
+
+- Prefer working/session state until a fact proves it should persist.
+- Long-term memory needs scope, owner, source, createdAt, retention, delete behavior, confidence.
+- Read shared memory as evidence unless it is a trusted policy source.
+- Prefer one writer per memory scope; workers propose `MemoryCandidate`s.
+- Use append-only or conflict-aware shared memory when multiple agents write.
+- Test should-remember and should-not-remember cases.
+
+## MCP, Tools, And Skills
+
+MCP exposes capabilities to AI apps:
+
+- `tools`: actions such as search, file/API/db calls, comments, deploys.
+- `resources`: context data such as files, schemas, tickets, logs.
+- `prompts`: reusable templates or interaction starters.
+
+Design tools like APIs: narrow names, clear docs, Zod/JSON schemas, example usage, error shapes, auth/retention notes, tool allowlists, and approval gates for destructive/costly/external actions.
+
+Use skills for reusable procedural knowledge. Keep `SKILL.md` concise; move optional depth to references/scripts.
+
+## Multi-Agent Flow
+
+Use multiple agents when separation helps: expertise, tools, permissions, context windows, latency, review, or user-facing ownership. If specialists do not need separate tools/context, they may be prompt sections. For collaboration techniques, read `references/agent-collaboration-patterns.md`.
+
+Handoff packet:
+
+```text
+goal, inputs, knownFacts, constraints, allowedTools,
+expectedOutput, stopConditions
+```
+
+Common issues:
+
+| Issue | Fix |
+|---|---|
+| vague ownership | one owner per state field/artifact |
+| full-history handoff | handoff packet + artifact refs |
+| supervisor bottleneck | workers decide locally inside bounds |
+| tool bleed | per-agent tool allowlist |
+| infinite delegation | max turns, budgets, terminal states |
+| prose return | Zod-valid `AgentResult` |
+| self-approval | separate reviewer/test/human gate |
+| memory conflict | one memory writer or approval gate |
+
+## Prompting And Models
+
+Node prompts should define role, node goal, inputs, tool permissions, decision criteria, output schema, failure behavior, and evidence rules. Leave thinking room for ambiguous architecture, memory scope, tool choice, or tradeoffs; use firm instructions at schema/tool/memory/cache/side-effect boundaries.
+
+Model/config checks:
+
+- Smaller model: classification, extraction, formatting.
+- Stronger reasoning model: planning, coding, tradeoffs, high-risk decisions.
+- Long-context model: retrieval-heavy tasks, still curated.
+- `max_output_tokens`: includes visible output and, for reasoning models, hidden reasoning.
+- `reasoning effort`: more deliberation for harder decisions, more cost/latency.
+- `temperature`: higher for ideation, lower for structured consistency.
+- Trace model, prompt/schema version, tool version, cache decision, token use, latency, cost.
+
+## Cache, Gates, Verification
+
+Cache small validated results keyed by normalized input, prompt/model/tool/data versions, scope, and freshness. Cache safety invariant: no secrets, raw private data without policy, tenant-crossing data, or hidden unkeyed state. Memory and cache solve different problems.
+
+Prompt-cache safety:
+
+- Provider prompt caching depends on stable message/prefix/tool-schema bytes; changing system/developer messages, tool descriptions, schemas, MCP prompts, or prefix order can invalidate reuse or make cache assumptions unsafe.
+- Keep cacheable instructions and examples stable, then append volatile user input, retrieval, memory, and runtime facts later.
+- Include prompt version, model/config, tool description/schema version, MCP server/tool version, data source version, and tenant/scope in app cache keys.
+- Do not cache LLM outputs when hidden inputs, retrieved context, or tool results that shaped the answer are missing from the key.
+
+Consider gates before destructive/costly/external side effects, durable memory writes, cross-tenant cache risk, new auth/billing/deploy ownership, conflicting evidence, or vague prompts that trigger action.
+
+Verification by risk:
+
+- Sketch: chosen architecture, rejected alternative, biggest risk.
+- Implementation: Zod tests, cache hit/miss/stale, golden path, tool permissions, gates.
+- Production: evals, adversarial cases, traces, memory privacy, idempotency, retry, cost/latency budgets.
+
+## Output Scheme
+
+Use this as a flexible schema, not a required template. Select fields that help the user understand and build the flow.
+
+Include the useful fields: `Goal`, `Decision`, `Runtime`, `Roles`, `Protocols`, `Context`, `Memory`, `Tools/MCP`, `Lifecycle`, `Models`, `Flow`, `Run control`, `Rollout`, and `Verification`.
+
+## Recovery
+
+- If requirements are broad, first return a sketch with assumptions and one decisive question.
+- If framework behavior is uncertain, mark it unknown and verify against official docs/source before locking architecture.
+- If tool, auth, tenant, or memory policy is unclear, gate side effects and design for least privilege.
+- If context is too large, switch to retrieval, map-reduce, or subagent summaries with cited artifact refs.
+- If eval criteria are missing, propose golden, adversarial, and tool-failure cases before implementation.
+
+## Anti-Patterns
+
+- Multi-agent before the core loop is proven.
+- Full history where a compact packet works.
+- Session state, memory, cache, and artifacts mixed together.
+- Agent communication through prose instead of Zod protocols.
+- Broad MCP/tools without auth, retention, validation, and gates.
+- More context instead of better retrieval/dedupe/summarization.
+- Larger model instead of fixing context, tools, schemas, or evals.
+- A `reason` node deciding and executing risky action.