octocode-cli 1.3.1 → 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-OCTZP2TO.js")}async function H(){return import("./chunks/command-help-specs-CQ3RBLP6.js")}async function p(){return import("./chunks/tool-command-HOSMVLNK.js")}async function u(){return import("./chunks/main-help-35HX2UDQ.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-35HX2UDQ.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.1",
+  "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,6 +1,6 @@
 # OctoCode Skills
 
-Specialized AI agent skills extending OctoCode. 15 skills live under `skills/`.
+Specialized AI agent skills extending OctoCode. 19 skills live under `skills/`.
 
 ---
 
@@ -23,6 +23,9 @@ Specialized AI agent skills extending OctoCode. 15 skills live under `skills/`.
 | **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. |
 
 ---
 
@@ -72,3 +75,12 @@ Scans recent AI, developer tooling, web platform, security, and notable-repo upd
 
 ### Search Skill
 Searches GitHub for `SKILL.md` files, scores relevance, previews results, and downloads selected skill folders.
+
+### 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.
+
+### 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.
+
+### 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.

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

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

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

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