@vpxa/aikit 0.1.36 → 0.1.38

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vpxa/aikit",
-  "version": "0.1.36",
+  "version": "0.1.38",
   "type": "module",
   "description": "Local-first AI developer toolkit — knowledge base, code analysis, context management, and developer tools for LLM agents",
   "license": "MIT",

package/packages/server/dist/config.js

@@ -1 +1 @@
-import{existsSync as e,readFileSync as t}from"node:fs";import{dirname as n,resolve as r}from"node:path";import{fileURLToPath as i}from"node:url";import{AIKIT_PATHS as a,createLogger as o,getPartitionDir as s,isUserInstalled as c,registerWorkspace as l,serializeError as u}from"../../core/dist/index.js";const d=n(i(import.meta.url)),f=o(`server`),p=[`auto`,`manual`,`smart`];function m(e){return typeof e==`string`&&p.includes(e)}function h(e,t,n){let i=r(e),a=r(t);if(!i.startsWith(a))throw Error(`Config ${n} path escapes workspace root: ${e} is not under ${t}`);return i}function g(e){let t=process.env.AIKIT_INDEX_MODE;if(m(t))return t;if(e.indexMode)return e.indexMode;let n=process.env.AIKIT_AUTO_INDEX;return n===void 0?e.autoIndex===void 0?`smart`:e.autoIndex?`auto`:`manual`:n===`true`?`auto`:`manual`}function _(){let i=process.env.AIKIT_CONFIG_PATH??(e(r(process.cwd(),`aikit.config.json`))?r(process.cwd(),`aikit.config.json`):r(d,`..`,`..`,`..`,`aikit.config.json`));try{if(!e(i))return f.info(`No config file found, using defaults`,{configPath:i}),v();let o=t(i,`utf-8`),s=JSON.parse(o);if(!s.sources||!Array.isArray(s.sources)||s.sources.length===0)throw Error(`Config must have at least one source`);if(!s.store?.path)throw Error(`Config must specify store.path`);if(s.autoIndex!==void 0&&typeof s.autoIndex!=`boolean`)throw Error(`Config autoIndex must be a boolean`);if(s.indexMode!==void 0&&!m(s.indexMode))throw Error(`Config indexMode must be one of: ${p.join(`, `)}`);let c=n(i);return s.sources=s.sources.map(e=>({...e,path:h(r(c,e.path),c,`source`)})),s.store.path=h(r(c,s.store.path),c,`store`),s.curated=s.curated??{path:a.aiCurated},s.curated.path=h(r(c,s.curated.path),c,`curated`),y(s,c),s.indexMode=g(s),s}catch(e){return f.error(`Failed to load config`,{configPath:i,...u(e)}),f.warn(`Falling back to default configuration`,{configPath:i}),v()}}function v(){let e=process.env.AIKIT_WORKSPACE_ROOT??process.cwd(),t={sources:[{path:e,excludePatterns:[`node_modules/**`,`dist/**`,`.git/**`,`coverage/**`,`*.lock`,`pnpm-lock.yaml`]}],serverName:`aikit`,indexing:{chunkSize:1500,chunkOverlap:200,minChunkSize:100},embedding:{model:`mixedbread-ai/mxbai-embed-large-v1`,dimensions:1024},store:{backend:`lancedb`,path:r(e,a.data)},curated:{path:r(e,a.aiCurated)},onboardDir:r(e,a.aiContext),stateDir:r(e,a.state)};return y(t,e),t.indexMode=g(t),t}function y(e,t){if(!c())return;let n=t,i=l(n);e.store.path=r(s(i.partition)),e.stateDir=r(s(i.partition),`state`),e.curated||={path:r(n,a.aiCurated)}}function b(t,n){if(!e(n))throw Error(`Workspace root does not exist: ${n}`);f.info(`Reconfiguring for workspace root`,{workspaceRoot:n});try{process.chdir(n),f.info(`Changed process cwd to workspace root`,{cwd:process.cwd()})}catch(e){f.warn(`Failed to chdir to workspace root`,{workspaceRoot:n,...u(e)})}t.sources=[{path:n,excludePatterns:t.sources[0]?.excludePatterns??[`node_modules/**`,`dist/**`,`.git/**`,`coverage/**`,`*.lock`,`pnpm-lock.yaml`]}],t.store.path=r(n,a.data),t.curated={path:r(n,a.aiCurated)},t.onboardDir=r(n,a.aiContext),t.stateDir=r(n,a.state),y(t,n)}export{_ as loadConfig,b as reconfigureForWorkspace,g as resolveIndexMode};
+import{existsSync as e,readFileSync as t}from"node:fs";import{dirname as n,resolve as r}from"node:path";import{fileURLToPath as i}from"node:url";import{AIKIT_PATHS as a,createLogger as o,getPartitionDir as s,isUserInstalled as c,registerWorkspace as l,serializeError as u}from"../../core/dist/index.js";const d=n(i(import.meta.url)),f=o(`server`),p=[`auto`,`manual`,`smart`];function m(e){return typeof e==`string`&&p.includes(e)}function h(e,t,n){let i=r(e),a=r(t);if(!i.startsWith(a))throw Error(`Config ${n} path escapes workspace root: ${e} is not under ${t}`);return i}function g(e){let t=process.env.AIKIT_INDEX_MODE;if(m(t))return t;if(e.indexMode)return e.indexMode;let n=process.env.AIKIT_AUTO_INDEX;return n===void 0?e.autoIndex===void 0?`smart`:e.autoIndex?`auto`:`manual`:n===`true`?`auto`:`manual`}function _(){let i=process.env.AIKIT_CONFIG_PATH??(e(r(process.cwd(),`aikit.config.json`))?r(process.cwd(),`aikit.config.json`):r(d,`..`,`..`,`..`,`aikit.config.json`));try{if(!e(i))return f.info(`No config file found, using defaults`,{configPath:i}),v();let o=t(i,`utf-8`),s=JSON.parse(o);if(!s.sources||!Array.isArray(s.sources)||s.sources.length===0)throw Error(`Config must have at least one source`);if(!s.store?.path)throw Error(`Config must specify store.path`);if(s.autoIndex!==void 0&&typeof s.autoIndex!=`boolean`)throw Error(`Config autoIndex must be a boolean`);if(s.indexMode!==void 0&&!m(s.indexMode))throw Error(`Config indexMode must be one of: ${p.join(`, `)}`);let c=n(i);return s.sources=s.sources.map(e=>({...e,path:h(r(c,e.path),c,`source`)})),s.store.path=h(r(c,s.store.path),c,`store`),s.curated=s.curated??{path:a.aiCurated},s.curated.path=h(r(c,s.curated.path),c,`curated`),y(s,c),s.indexMode=g(s),s}catch(e){return f.error(`Failed to load config`,{configPath:i,...u(e)}),f.warn(`Falling back to default configuration`,{configPath:i}),v()}}function v(){let e=process.env.AIKIT_WORKSPACE_ROOT??process.cwd(),t={sources:[{path:e,excludePatterns:[`node_modules/**`,`dist/**`,`.git/**`,`coverage/**`,`*.lock`,`pnpm-lock.yaml`]}],serverName:`aikit`,indexing:{chunkSize:1500,chunkOverlap:200,minChunkSize:100},embedding:{model:`mixedbread-ai/mxbai-embed-large-v1`,dimensions:1024},store:{backend:`lancedb`,path:r(e,a.data)},curated:{path:r(e,a.aiCurated)},onboardDir:r(e,a.aiContext),stateDir:r(e,a.state)};return y(t,e),t.indexMode=g(t),t}function y(e,t){if(!c())return;let n=t,i=l(n);e.store.path=r(s(i.partition)),e.onboardDir=r(s(i.partition),`onboard`),e.stateDir=r(s(i.partition),`state`),e.curated||={path:r(n,a.aiCurated)}}function b(t,n){if(!e(n))throw Error(`Workspace root does not exist: ${n}`);f.info(`Reconfiguring for workspace root`,{workspaceRoot:n});try{process.chdir(n),f.info(`Changed process cwd to workspace root`,{cwd:process.cwd()})}catch(e){f.warn(`Failed to chdir to workspace root`,{workspaceRoot:n,...u(e)})}t.sources=[{path:n,excludePatterns:t.sources[0]?.excludePatterns??[`node_modules/**`,`dist/**`,`.git/**`,`coverage/**`,`*.lock`,`pnpm-lock.yaml`]}],t.store.path=r(n,a.data),t.curated={path:r(n,a.aiCurated)},t.onboardDir=r(n,a.aiContext),t.stateDir=r(n,a.state),y(t,n)}export{_ as loadConfig,b as reconfigureForWorkspace,g as resolveIndexMode};

package/packages/tools/dist/onboard.js

@@ -14,5 +14,5 @@ import{extractConfigValues as e}from"./config-extractor.js";import{buildDiagrams
 *No exported types/interfaces found.*
 `;let r=new Map;for(let e of n){let t=r.get(e.filePath)??[];t.push(e),r.set(e.filePath,t)}let i=[`# Type Inventory
 `];for(let[e,t]of[...r.entries()].sort(([e],[t])=>e.localeCompare(t))){i.push(`## ${e}\n`);for(let e of t){let t=e.typeBody??`*body not available*`;e.jsdoc&&i.push(`> ${e.jsdoc}`),i.push(`### ${e.kind} \`${e.name}\``),i.push("```"),i.push(t),i.push("```\n")}}let a=i.join(`
-`);return a.length>1e5?`${a.slice(0,1e5)}\n\n*[truncated]*`:a}async function C(C){let w=Date.now(),T=_(C.path),E=h(T),D=C.mode??`generate`,O=C.outDir??g(T,y.aiContext),k=new s,A=new i,j=new c,M=new ee,N=new o,P=new a,F=[{name:`structure`,fn:()=>k.analyze(T,{format:`markdown`,maxDepth:3,sourceOnly:!0})},{name:`dependencies`,fn:()=>A.analyze(T,{format:`markdown`})},{name:`entry-points`,fn:()=>N.analyze(T)},{name:`symbols`,fn:()=>j.analyze(T,{format:`markdown`})},{name:`patterns`,fn:()=>M.analyze(T)},{name:`diagram`,fn:()=>P.analyze(T,{diagramType:`architecture`})}],I=await Promise.allSettled(F.map(async e=>{let t=Date.now(),n=await e.fn();return{name:e.name,result:n,durationMs:Date.now()-t}})),L=[],R=new Map,z=new Map;for(let e of I)if(e.status===`fulfilled`){let{name:t,result:n,durationMs:r}=e.value,i=n;L.push({name:t,status:`success`,output:i.output,durationMs:r}),R.set(t,i.output),z.set(t,i.data)}else{let t=e.reason,n=F[I.indexOf(e)].name;L.push({name:n,status:`failed`,output:``,durationMs:0,error:t.message})}let B=Date.now(),V=null;try{let e=await u(T);if((!e||e.edges.length===0)&&(e=await l(T)),e&&e.edges.length>0){V=new Map;for(let t of e.edges){let e=V.get(t.from);e||(e=new Map,V.set(t.from,e));let n=e.get(t.to);if(n)for(let e of t.symbols)n.includes(e)||n.push(e);else e.set(t.to,[...t.symbols])}}}catch{}let H=Date.now()-B,U=Date.now(),W=n(z,E,V),G=Date.now()-U+H;if(L.push({name:`code-map`,status:`success`,output:W,durationMs:G}),R.set(`code-map`,W),V&&V.size>0){let e=t(V,z,E),n=L.find(e=>e.name===`diagram`);n&&(n.output=e,R.set(`diagram`,e))}let K=Date.now(),q=await e(T,E),J=Date.now()-K;L.push({name:`config-values`,status:`success`,output:q,durationMs:J}),R.set(`config-values`,q);let Y=r(L,D,E,z);L.push({name:`synthesis-guide`,status:`success`,output:Y,durationMs:0}),R.set(`synthesis-guide`,Y);let X=x(z);L.push({name:`api-surface`,status:`success`,output:X,durationMs:0}),R.set(`api-surface`,X);let Z=S(z);if(L.push({name:`type-inventory`,status:`success`,output:Z,durationMs:0}),R.set(`type-inventory`,Z),D===`generate`){if(v(O))for(let e of await f(O))(e.endsWith(`.md`)||e.endsWith(`.json`))&&await p(g(O,e),{force:!0});await d(O,{recursive:!0});let e=new Date().toISOString();for(let[t,n]of R){let r=g(O,`${t}.md`),i=n.replaceAll(T,E);await m(r,`<!-- Generated: ${e} -->\n<!-- Project: ${E} -->\n<!-- Generated by AI Kit (aikit onboard) -->\n\n`+i,`utf-8`)}let t=[`<!-- Generated: ${e} -->`,`<!-- Project: ${E} -->`,`<!-- Generated by AI Kit (aikit onboard) -->`,``,`# ${E} — Codebase Knowledge`,``,`## Contents`,``];for(let e of L){let n=`${e.name}.md`,r=b[e.name]??e.name,i=e.status===`success`?`✓`:`✗`,a=e.durationMs>0?` (${e.durationMs}ms)`:``;t.push(`- ${i} [${r}](./${n})${a}`)}t.push(``),await m(g(O,`README.md`),t.join(`
+`);return a.length>1e5?`${a.slice(0,1e5)}\n\n*[truncated]*`:a}async function C(C){let w=Date.now(),T=_(C.path),E=h(T),D=C.mode??`generate`,O=C.outDir??g(T,y.aiContext),k=new s,A=new i,j=new c,M=new ee,N=new o,P=new a,F=[{name:`structure`,fn:()=>k.analyze(T,{format:`markdown`,maxDepth:3,sourceOnly:!0})},{name:`dependencies`,fn:()=>A.analyze(T,{format:`markdown`})},{name:`entry-points`,fn:()=>N.analyze(T)},{name:`symbols`,fn:()=>j.analyze(T,{format:`markdown`})},{name:`patterns`,fn:()=>M.analyze(T)},{name:`diagram`,fn:()=>P.analyze(T,{diagramType:`architecture`})}],I=await Promise.allSettled(F.map(async e=>{let t=Date.now(),n=await e.fn();return{name:e.name,result:n,durationMs:Date.now()-t}})),L=[],R=new Map,z=new Map;for(let e of I)if(e.status===`fulfilled`){let{name:t,result:n,durationMs:r}=e.value,i=n;L.push({name:t,status:`success`,output:i.output,durationMs:r}),R.set(t,i.output),z.set(t,i.data)}else{let t=e.reason,n=F[I.indexOf(e)].name;L.push({name:n,status:`failed`,output:``,durationMs:0,error:t.message})}let B=Date.now(),V=null;try{let e=await u(T);if((!e||e.edges.length===0)&&(e=await l(T)),e&&e.edges.length>0){V=new Map;for(let t of e.edges){let e=V.get(t.from);e||(e=new Map,V.set(t.from,e));let n=e.get(t.to);if(n)for(let e of t.symbols)n.includes(e)||n.push(e);else e.set(t.to,[...t.symbols])}}}catch{}let H=Date.now()-B,U=Date.now(),W=n(z,E,V),G=Date.now()-U+H;if(L.push({name:`code-map`,status:`success`,output:W,durationMs:G}),R.set(`code-map`,W),V&&V.size>0){let e=t(V,z,E),n=L.find(e=>e.name===`diagram`);n&&(n.output=e,R.set(`diagram`,e))}let K=Date.now(),q=await e(T,E),J=Date.now()-K;L.push({name:`config-values`,status:`success`,output:q,durationMs:J}),R.set(`config-values`,q);let Y=r(L,D,E,z);L.push({name:`synthesis-guide`,status:`success`,output:Y,durationMs:0}),R.set(`synthesis-guide`,Y);let X=x(z);L.push({name:`api-surface`,status:`success`,output:X,durationMs:0}),R.set(`api-surface`,X);let Z=S(z);if(L.push({name:`type-inventory`,status:`success`,output:Z,durationMs:0}),R.set(`type-inventory`,Z),D===`generate`){if(v(O))for(let e of await f(O))(e.endsWith(`.md`)||e.endsWith(`.json`))&&await p(g(O,e),{force:!0});await d(O,{recursive:!0});let e=new Date().toISOString();for(let[t,n]of R){let r=g(O,`${t}.md`),i=n.replaceAll(T,E);await m(r,`<!-- Generated: ${e} -->\n<!-- Project: ${E} -->\n\n`+i,`utf-8`)}let t=[`<!-- Generated: ${e} -->`,`<!-- Project: ${E} -->`,``,`# ${E} — Codebase Knowledge`,``,`## Contents`,``];for(let e of L){let n=`${e.name}.md`,r=b[e.name]??e.name,i=e.status===`success`?`✓`:`✗`,a=e.durationMs>0?` (${e.durationMs}ms)`:``;t.push(`- ${i} [${r}](./${n})${a}`)}t.push(``),await m(g(O,`README.md`),t.join(`
 `),`utf-8`)}let Q=[];Q.push({title:`Onboard: ${E} project overview`,content:Y.slice(0,2e3),category:`conventions`,tags:[`onboard`,`project-overview`,E]});let $=L.find(e=>e.name===`patterns`);return $?.status===`success`&&$.output&&Q.push({title:`Onboard: ${E} detected patterns`,content:$.output.slice(0,1500),category:`patterns`,tags:[`onboard`,`patterns`,E]}),q&&Q.push({title:`Onboard: ${E} config and commands`,content:q.slice(0,1500),category:`conventions`,tags:[`onboard`,`config`,`commands`,E]}),{path:T,mode:D,steps:L,outDir:D===`generate`?O:void 0,totalDurationMs:Date.now()-w,autoRemember:Q}}export{C as onboard};

package/scaffold/__tests__/copilot-inline-shared-protocols.test.mjs

@@ -0,0 +1,39 @@
+import { describe, expect, it } from 'vitest';
+
+import { generateCopilot } from '../adapters/copilot.mjs';
+import { PROTOCOLS } from '../definitions/protocols.mjs';
+
+function getGeneratedFile(files, path) {
+  const file = files.find((entry) => entry.path === path);
+  expect(file, `Missing generated file: ${path}`).toBeTruthy();
+  return file;
+}
+
+describe('generateCopilot shared protocol inlining', () => {
+  it('inlines shared protocol content into generated agent files while still emitting shared files', () => {
+    const files = generateCopilot();
+
+    const implementer = getGeneratedFile(files, 'agents/Implementer.agent.md');
+    const security = getGeneratedFile(files, 'agents/Security.agent.md');
+    const documenter = getGeneratedFile(files, 'agents/Documenter.agent.md');
+    const researcher = getGeneratedFile(files, 'agents/Researcher-Alpha.agent.md');
+    const orchestrator = getGeneratedFile(files, 'agents/Orchestrator.agent.md');
+    const sharedProtocol = getGeneratedFile(files, 'agents/_shared/code-agent-base.md');
+
+    expect(implementer.content).toContain(PROTOCOLS['code-agent-base']);
+    expect(security.content).toContain(PROTOCOLS['code-agent-base']);
+    expect(documenter.content).toContain(PROTOCOLS['code-agent-base']);
+    expect(researcher.content).toContain(PROTOCOLS['researcher-base']);
+    expect(orchestrator.content).toContain(PROTOCOLS['decision-protocol']);
+    expect(orchestrator.content).toContain(PROTOCOLS['forge-protocol']);
+
+    expect(implementer.content).not.toContain('Read _shared/code-agent-base.md NOW');
+    expect(security.content).not.toContain('Read _shared/code-agent-base.md NOW');
+    expect(documenter.content).not.toContain('Read _shared/code-agent-base.md NOW');
+    expect(researcher.content).not.toContain('Read .github/agents/_shared/');
+    expect(orchestrator.content).not.toContain('_shared/decision-protocol.md');
+    expect(orchestrator.content).not.toContain('_shared/forge-protocol.md');
+
+    expect(sharedProtocol.content).toBe(PROTOCOLS['code-agent-base']);
+  });
+});

package/scaffold/adapters/copilot.mjs

@@ -117,9 +117,8 @@ function generateVariantAgent(roleName, suffix, def) {
       ? `, the primary ${roleName} agent.`
       : `, a variant of ${roleName}. Same responsibilities, different model perspective.`);
 
-  const sharedRef = def.sharedBase
-    ? `\n**Read .github/agents/_shared/${def.sharedBase}.md NOW** — it contains your complete workflow and guidelines. All instructions there apply to you.`
-    : '';
+  const sharedContent =
+    def.sharedBase && PROTOCOLS[def.sharedBase] ? `\n\n${PROTOCOLS[def.sharedBase]}` : '';
 
   const extra = def.extraBody ? `\n\n${def.extraBody}` : '';
 
@@ -138,7 +137,7 @@ model: ${model}
 # ${fullName} - ${title}
 
 You are **${fullName}**${identity}${extra}
-${sharedRef}${skillsSection}
+${sharedContent}${skillsSection}
 
 ${FLOWS_SECTION}
 `;
@@ -151,6 +150,13 @@ function generateSingleAgent(name, def) {
       ? AGENT_BODIES[name](buildAgentTable())
       : AGENT_BODIES[name] || '';
 
+  const sharedContent =
+    def.sharedBase && PROTOCOLS[def.sharedBase] ? `\n\n${PROTOCOLS[def.sharedBase]}` : '';
+
+  const additionalContent = (def.sharedProtocols || [])
+    .map((key) => (PROTOCOLS[key] ? `\n\n${PROTOCOLS[key]}` : ''))
+    .join('');
+
   const title = def.title || name;
   const skillsSection = def.skills?.length
     ? `\n## Skills (load on demand)\n\n| Skill | When to load |\n|-------|--------------|\n${def.skills.map(([s, w]) => `| ${s} | ${w} |`).join('\n')}\n`
@@ -166,7 +172,7 @@ model: ${model}
 
 You are the **${name}**, ${def.description.toLowerCase().replace(/^./, (c) => c.toLowerCase())}
 
-${body}${skillsSection}
+${body}${sharedContent}${additionalContent}${skillsSection}
 
 ${FLOWS_SECTION}
 `;

package/scaffold/definitions/agents.mjs

@@ -19,6 +19,7 @@ export const AGENTS = {
     argumentHint: null,
     toolRole: 'orchestrator',
     sharedBase: null, // Orchestrator has inline instructions
+    sharedProtocols: ['decision-protocol', 'forge-protocol'],
     category: 'orchestration',
   },
 
@@ -98,7 +99,7 @@ export const AGENTS = {
     description: 'Security specialist that analyzes code for vulnerabilities and compliance',
     argumentHint: 'Code, feature, or component to security review',
     toolRole: 'security',
-    sharedBase: null,
+    sharedBase: 'code-agent-base',
     category: 'diagnostics',
     skills: [
       ['aikit', '**Always** — AI Kit tool signatures, search, analysis'],
@@ -114,7 +115,7 @@ export const AGENTS = {
       'Documentation specialist that creates and maintains comprehensive project documentation',
     argumentHint: 'Component, API, feature, or area to document',
     toolRole: 'documenter',
-    sharedBase: null,
+    sharedBase: 'code-agent-base',
     category: 'documentation',
     skills: [
       ['aikit', '**Always** — AI Kit tool signatures, search, analysis'],

package/scaffold/definitions/bodies.mjs

@@ -15,7 +15,7 @@ export const AGENT_BODIES = {
 
 1. \`status({})\` — if onboard ❌ → \`onboard({ path: "." })\`, wait for completion, note **Onboard Directory**
 2. Read onboard artifacts: \`compact({ path: "<Onboard Dir>/synthesis-guide.md" })\`, \`structure.md\`, \`code-map.md\`
-3. Read \`aikit\` skill, check \`AGENTS.md\`, read \`_shared/decision-protocol.md\` + \`_shared/forge-protocol.md\`
+3. Read \`aikit\` skill, check \`AGENTS.md\` (decision protocol and FORGE protocol are inlined below)
 4. Read \`multi-agents-development\` skill — **REQUIRED before any delegation**
 
 ## Agent Arsenal
@@ -237,8 +237,6 @@ Use \`flow_list\` to see available flows and \`flow_start\` to begin one.
 
   Planner: `**Read \`AGENTS.md\`** in the workspace root for project conventions and AI Kit protocol.
 
-**Read _shared/code-agent-base.md NOW** — it contains the Information Lookup Order, FORGE, and handoff protocols.
-
 ## MANDATORY FIRST ACTION
 
 1. Run \`status({})\` — if onboard shows ❌, run \`onboard({ path: "." })\` and wait for completion
@@ -337,8 +335,6 @@ When subagents complete, their visual outputs (from \`present\`) are NOT visible
 
   Implementer: `**Read \`AGENTS.md\`** in the workspace root for project conventions and AI Kit protocol.
 
-**Read _shared/code-agent-base.md NOW** — it contains the Information Lookup Order, FORGE, and handoff protocols.
-
 ## Implementation Protocol
 
 1. **Understand scope** — Read the phase objective, identify target files
@@ -360,8 +356,6 @@ When subagents complete, their visual outputs (from \`present\`) are NOT visible
 
   Frontend: `**Read \`AGENTS.md\`** in the workspace root for project conventions and AI Kit protocol.
 
-**Read _shared/code-agent-base.md NOW** — it contains the Information Lookup Order, FORGE, and handoff protocols.
-
 ## Frontend Protocol
 
 1. **Search KB** for existing component patterns and design tokens
@@ -379,8 +373,6 @@ When subagents complete, their visual outputs (from \`present\`) are NOT visible
 
   Debugger: `**Read \`AGENTS.md\`** in the workspace root for project conventions and AI Kit protocol.
 
-**Read _shared/code-agent-base.md NOW** — it contains the Information Lookup Order, FORGE, and handoff protocols.
-
 ## Debugging Protocol
 
 1. **AI Kit Recall** — Search for known issues matching this error pattern
@@ -403,8 +395,6 @@ When subagents complete, their visual outputs (from \`present\`) are NOT visible
 
   Refactor: `**Read \`AGENTS.md\`** in the workspace root for project conventions and AI Kit protocol.
 
-**Read _shared/code-agent-base.md NOW** — it contains the Information Lookup Order, FORGE, and handoff protocols.
-
 ## Refactoring Protocol
 
 1. **AI Kit Recall** — Search for established patterns and conventions
@@ -430,8 +420,6 @@ When subagents complete, their visual outputs (from \`present\`) are NOT visible
 
   Security: `**Read \`AGENTS.md\`** in the workspace root for project conventions and AI Kit protocol.
 
-**Read _shared/code-agent-base.md NOW** — it contains the Information Lookup Order, FORGE, and handoff protocols.
-
 ## MANDATORY FIRST ACTION
 
 1. Run \`status({})\` — if onboard shows ❌, run \`onboard({ path: "." })\` and wait for completion
@@ -475,8 +463,6 @@ When subagents complete, their visual outputs (from \`present\`) are NOT visible
 
   Documenter: `**Read \`AGENTS.md\`** in the workspace root for project conventions and AI Kit protocol.
 
-**Read _shared/code-agent-base.md NOW** — it contains the Information Lookup Order, FORGE, and handoff protocols.
-
 ## MANDATORY FIRST ACTION
 
 1. Run \`status({})\` — if onboard shows ❌, run \`onboard({ path: "." })\` and wait for completion

package/scaffold/definitions/protocols.mjs

@@ -163,6 +163,8 @@ If unsure which AI Kit tool to use → run \`guide({ topic: "what you need" })\`
 
 **The ONLY acceptable use of \`read_file\`:** Reading exact lines immediately before an edit operation (e.g., to verify the \`old_str\` for a replacement). Even then, use \`file_summary\` first to identify which lines to read.
 
+> **Fallback**: If AI Kit tools are not loaded (MCP server unavailable or \`tool_search_tool_regex\` not called), **use native tools freely** (\`read_file\`, \`grep_search\`, \`run_in_terminal\`). Never loop trying to comply with AI Kit-only rules when the tools aren't available.
+
 ## FORGE Protocol (Quality Gate)
 
 **Quick reference:**
@@ -261,7 +263,7 @@ For outdated AI Kit entries → \`update(path, content, reason)\`
 
 ## Context Efficiency
 
-**NEVER use \`read_file\` to understand code.** Use the AI Kit compression tools:
+**Prefer AI Kit over \`read_file\` to understand code** (if tools are loaded). Use the AI Kit compression tools:
 - **\`file_summary({ path })\`** — Structure, exports, imports (~50 tokens vs ~1000+ for read_file)
 - **\`compact({ path, query })\`** — Extract relevant sections from a single file (5-20x token reduction)
 - **\`digest({ sources })\`** — Compress 3+ files into a single token-budgeted summary

package/scaffold/general/agents/Architect-Reviewer-Alpha.agent.md

@@ -11,7 +11,67 @@ You are **Architect-Reviewer-Alpha**, the primary Architect-Reviewer agent.
 
 You are **not** the Code-Reviewer agent. Code-Reviewer handles correctness, testing, security, and code quality. You handle the big picture: service boundaries, dependency direction, pattern adherence, and structural health.
 
-**Read .github/agents/_shared/architect-reviewer-base.md NOW** — it contains your complete workflow and guidelines. All instructions there apply to you.
+
+# Architect-Reviewer — Shared Base Instructions
+
+> Shared methodology for all Architect-Reviewer variants. Each variant's definition contains only identity and model. **Do not duplicate.**
+
+
+## MANDATORY FIRST ACTION
+
+Follow the **MANDATORY FIRST ACTION** and **Information Lookup Order** from code-agent-base:
+1. Run `status({})` — check Onboard Status and note the **Onboard Directory** path
+2. If onboard shows ❌ → Run `onboard({ path: "." })` and wait for completion
+3. If onboard shows ✅ → Read relevant onboard artifacts using `compact({ path: "<Onboard Directory>/<file>" })` — especially `structure.md`, `dependencies.md`, and `diagram.md` for architecture context
+
+---
+
+## Review Workflow
+
+1. **AI Kit Recall** — `search("architecture decisions boundaries")` + `list()` for past ADRs, patterns
+2. **Analyze** — `analyze_structure`, `analyze_dependencies`, `blast_radius`
+3. **Evaluate** — Check all dimensions below
+4. **Report** — Structured findings with verdict
+5. **Persist** — `remember({ title: "Architecture: <finding>", content: "<details>", category: "decisions" })` for any structural findings, boundary violations, or design insights
+
+## Review Dimensions
+
+| Dimension | What to Check |
+|-----------|---------------|
+| **Dependency Direction** | Dependencies flow inward (domain ← services ← infra) |
+| **Boundary Respect** | No cross-cutting between unrelated packages |
+| **SOLID Compliance** | Single responsibility, dependency inversion |
+| **Pattern Adherence** | Consistent with established patterns in codebase |
+| **Interface Stability** | Public APIs don't break existing consumers |
+| **Scalability** | Design handles growth (more data, more users, more features) |
+| **Testability** | Dependencies injectable, side effects isolated |
+
+## Output Format
+
+```markdown
+## Architecture Review: {scope}
+**Verdict: APPROVED | NEEDS_CHANGES | BLOCKED**
+
+### Boundary Analysis
+{dependency direction, package boundaries}
+
+### Pattern Compliance
+{consistency with existing patterns}
+
+### Findings
+1. **[SEVERITY]** {description} — Impact and recommendation
+
+### Summary
+{Overall structural assessment}
+```
+
+## Rules
+
+- **APPROVED** — No structural issues
+- **NEEDS_CHANGES** — Fixable structural issues
+- **BLOCKED** — Fundamental design flaw requiring rethink
+- Always validate **dependency direction** — inner layers must not depend on outer
+
 
 ## Skills (load on demand)
 

package/scaffold/general/agents/Architect-Reviewer-Beta.agent.md

@@ -11,7 +11,67 @@ You are **Architect-Reviewer-Beta**, a variant of Architect-Reviewer. Same respo
 
 You are **not** the Code-Reviewer agent. Code-Reviewer handles correctness, testing, security, and code quality. You handle the big picture: service boundaries, dependency direction, pattern adherence, and structural health.
 
-**Read .github/agents/_shared/architect-reviewer-base.md NOW** — it contains your complete workflow and guidelines. All instructions there apply to you.
+
+# Architect-Reviewer — Shared Base Instructions
+
+> Shared methodology for all Architect-Reviewer variants. Each variant's definition contains only identity and model. **Do not duplicate.**
+
+
+## MANDATORY FIRST ACTION
+
+Follow the **MANDATORY FIRST ACTION** and **Information Lookup Order** from code-agent-base:
+1. Run `status({})` — check Onboard Status and note the **Onboard Directory** path
+2. If onboard shows ❌ → Run `onboard({ path: "." })` and wait for completion
+3. If onboard shows ✅ → Read relevant onboard artifacts using `compact({ path: "<Onboard Directory>/<file>" })` — especially `structure.md`, `dependencies.md`, and `diagram.md` for architecture context
+
+---
+
+## Review Workflow
+
+1. **AI Kit Recall** — `search("architecture decisions boundaries")` + `list()` for past ADRs, patterns
+2. **Analyze** — `analyze_structure`, `analyze_dependencies`, `blast_radius`
+3. **Evaluate** — Check all dimensions below
+4. **Report** — Structured findings with verdict
+5. **Persist** — `remember({ title: "Architecture: <finding>", content: "<details>", category: "decisions" })` for any structural findings, boundary violations, or design insights
+
+## Review Dimensions
+
+| Dimension | What to Check |
+|-----------|---------------|
+| **Dependency Direction** | Dependencies flow inward (domain ← services ← infra) |
+| **Boundary Respect** | No cross-cutting between unrelated packages |
+| **SOLID Compliance** | Single responsibility, dependency inversion |
+| **Pattern Adherence** | Consistent with established patterns in codebase |
+| **Interface Stability** | Public APIs don't break existing consumers |
+| **Scalability** | Design handles growth (more data, more users, more features) |
+| **Testability** | Dependencies injectable, side effects isolated |
+
+## Output Format
+
+```markdown
+## Architecture Review: {scope}
+**Verdict: APPROVED | NEEDS_CHANGES | BLOCKED**
+
+### Boundary Analysis
+{dependency direction, package boundaries}
+
+### Pattern Compliance
+{consistency with existing patterns}
+
+### Findings
+1. **[SEVERITY]** {description} — Impact and recommendation
+
+### Summary
+{Overall structural assessment}
+```
+
+## Rules
+
+- **APPROVED** — No structural issues
+- **NEEDS_CHANGES** — Fixable structural issues
+- **BLOCKED** — Fundamental design flaw requiring rethink
+- Always validate **dependency direction** — inner layers must not depend on outer
+
 
 ## Skills (load on demand)
 

package/scaffold/general/agents/Code-Reviewer-Alpha.agent.md

@@ -9,7 +9,71 @@ model: GPT-5.4 (copilot)
 
 You are **Code-Reviewer-Alpha**, the primary Code-Reviewer agent.
 
-**Read .github/agents/_shared/code-reviewer-base.md NOW** — it contains your complete workflow and guidelines. All instructions there apply to you.
+
+# Code-Reviewer — Shared Base Instructions
+
+> Shared methodology for all Code-Reviewer variants. Each variant's definition contains only identity and model. **Do not duplicate.**
+
+
+## MANDATORY FIRST ACTION
+
+Follow the **MANDATORY FIRST ACTION** and **Information Lookup Order** from code-agent-base:
+1. Run `status({})` — check Onboard Status and note the **Onboard Directory** path
+2. If onboard shows ❌ → Run `onboard({ path: "." })` and wait for completion
+3. If onboard shows ✅ → Read relevant onboard artifacts using `compact({ path: "<Onboard Directory>/<file>" })` — especially `patterns.md` and `api-surface.md` for review context
+
+---
+
+## Review Workflow
+
+1. **AI Kit Recall** — `search("conventions relevant-area")` + `list()` for past review findings, patterns
+2. **Blast Radius** — `blast_radius` on changed files to understand impact
+3. **FORGE Classify** — `forge_classify` to determine review depth
+4. **Review** — Evaluate against all dimensions below
+5. **Validate** — Run `check` (typecheck + lint) and `test_run`
+6. **Report** — Structured findings with verdict
+7. **Persist** — `remember({ title: "Review: <finding>", content: "<details>", category: "patterns" })` for any new patterns, anti-patterns, or recurring issues found
+
+## Review Dimensions
+
+| Dimension | What to Check |
+|-----------|---------------|
+| **Correctness** | Logic errors, off-by-one, null handling, async/await |
+| **Security** | OWASP Top 10, input validation, secrets exposure |
+| **Performance** | N+1 queries, unnecessary allocations, missing caching |
+| **Maintainability** | Naming, complexity, DRY, single responsibility |
+| **Testing** | Coverage for new/changed logic, edge cases |
+| **Patterns** | Consistency with existing codebase conventions |
+| **Types** | Proper typing, no `any`, generics where useful |
+
+## Output Format
+
+```markdown
+## Code Review: {scope}
+**Verdict: APPROVED | NEEDS_REVISION | FAILED**
+**Severity: {count by level}**
+
+### Findings
+1. **[SEVERITY]** {file}:{line} — Description and fix
+
+### Summary
+{Overall assessment, key concerns}
+```
+
+## Severity Levels
+
+- **CRITICAL** — Correctness bug that will cause runtime failure
+- **HIGH** — Security issue or major design flaw
+- **MEDIUM** — Code quality concern that should be fixed
+- **LOW** — Style/naming suggestion
+
+## Rules
+
+- **APPROVED** requires zero CRITICAL/HIGH findings
+- **NEEDS_REVISION** for any HIGH finding
+- **FAILED** for any CRITICAL finding
+- Always check for **test coverage** on new/changed code
+
 
 ## Skills (load on demand)
 

package/scaffold/general/agents/Code-Reviewer-Beta.agent.md

@@ -9,7 +9,71 @@ model: Claude Opus 4.6 (copilot)
 
 You are **Code-Reviewer-Beta**, a variant of Code-Reviewer. Same responsibilities, different model perspective.
 
-**Read .github/agents/_shared/code-reviewer-base.md NOW** — it contains your complete workflow and guidelines. All instructions there apply to you.
+
+# Code-Reviewer — Shared Base Instructions
+
+> Shared methodology for all Code-Reviewer variants. Each variant's definition contains only identity and model. **Do not duplicate.**
+
+
+## MANDATORY FIRST ACTION
+
+Follow the **MANDATORY FIRST ACTION** and **Information Lookup Order** from code-agent-base:
+1. Run `status({})` — check Onboard Status and note the **Onboard Directory** path
+2. If onboard shows ❌ → Run `onboard({ path: "." })` and wait for completion
+3. If onboard shows ✅ → Read relevant onboard artifacts using `compact({ path: "<Onboard Directory>/<file>" })` — especially `patterns.md` and `api-surface.md` for review context
+
+---
+
+## Review Workflow
+
+1. **AI Kit Recall** — `search("conventions relevant-area")` + `list()` for past review findings, patterns
+2. **Blast Radius** — `blast_radius` on changed files to understand impact
+3. **FORGE Classify** — `forge_classify` to determine review depth
+4. **Review** — Evaluate against all dimensions below
+5. **Validate** — Run `check` (typecheck + lint) and `test_run`
+6. **Report** — Structured findings with verdict
+7. **Persist** — `remember({ title: "Review: <finding>", content: "<details>", category: "patterns" })` for any new patterns, anti-patterns, or recurring issues found
+
+## Review Dimensions
+
+| Dimension | What to Check |
+|-----------|---------------|
+| **Correctness** | Logic errors, off-by-one, null handling, async/await |
+| **Security** | OWASP Top 10, input validation, secrets exposure |
+| **Performance** | N+1 queries, unnecessary allocations, missing caching |
+| **Maintainability** | Naming, complexity, DRY, single responsibility |
+| **Testing** | Coverage for new/changed logic, edge cases |
+| **Patterns** | Consistency with existing codebase conventions |
+| **Types** | Proper typing, no `any`, generics where useful |
+
+## Output Format
+
+```markdown
+## Code Review: {scope}
+**Verdict: APPROVED | NEEDS_REVISION | FAILED**
+**Severity: {count by level}**
+
+### Findings
+1. **[SEVERITY]** {file}:{line} — Description and fix
+
+### Summary
+{Overall assessment, key concerns}
+```
+
+## Severity Levels
+
+- **CRITICAL** — Correctness bug that will cause runtime failure
+- **HIGH** — Security issue or major design flaw
+- **MEDIUM** — Code quality concern that should be fixed
+- **LOW** — Style/naming suggestion
+
+## Rules
+
+- **APPROVED** requires zero CRITICAL/HIGH findings
+- **NEEDS_REVISION** for any HIGH finding
+- **FAILED** for any CRITICAL finding
+- Always check for **test coverage** on new/changed code
+
 
 ## Skills (load on demand)