@vpxa/aikit 0.1.16 → 0.1.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vpxa/aikit",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "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/structured-content-guard.d.ts

@@ -14,8 +14,10 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
  *
  * UPDATE: The SDK uses passthrough-style validation which DOES reject
  * unknown keys on strict schemas.  Instead, we build a "zero-value"
- * object from the registered outputSchema (if available) so it always
- * passes validation.
+ * object from the registered outputSchema (Zod or JSON-Schema) so it
+ * always passes validation.  Zod schemas expose `.shape` and `.type`
+ * differently from JSON-Schema's `.properties` and `.type` — the
+ * `buildZeroValue` function handles both formats.
  */
 /**
  * Wrap `server.registerTool` so that every handler result is guaranteed

package/packages/server/dist/structured-content-guard.js

@@ -1 +1 @@
-function e(e){let n=e.registerTool.bind(e);e.registerTool=(e,r,i)=>r?.outputSchema==null?n(e,r,i):n(e,r,async(e,n)=>{let a=await i(e,n);return a.structuredContent??=t(r.outputSchema),a})}function t(e){if(!e)return{};if(e.anyOf){let n=e.anyOf.find(e=>e.type!==`null`);return n?t(n):null}switch(e.type){case`object`:{let n={};if(e.properties)for(let[r,i]of Object.entries(e.properties))n[r]=t(i);return n}case`array`:return[];case`string`:return``;case`number`:case`integer`:return 0;case`boolean`:return!1;default:return{}}}export{e as installStructuredContentGuard};
+function e(e){let n=e.registerTool.bind(e);e.registerTool=(e,r,i)=>r?.outputSchema==null?n(e,r,i):n(e,r,async(e,n)=>{let a=await i(e,n);return a.structuredContent??=t(r.outputSchema),a})}function t(e){if(!e)return{};if(e.anyOf){let n=e.anyOf.find(e=>e.type!==`null`);return n?t(n):null}switch(e.type){case`object`:{let n={},r=e.properties??e.shape;if(r)for(let[e,i]of Object.entries(r))n[e]=t(i);return n}case`array`:return[];case`string`:return``;case`number`:case`integer`:return 0;case`boolean`:return!1;case`nullable`:return null;case`optional`:return;case`record`:return{};default:return{}}}export{e as installStructuredContentGuard};

package/packages/server/dist/tools/flow.tools.js

@@ -1 +1 @@
-import{getToolMeta as e}from"../tool-metadata.js";import{basename as t,join as n,resolve as r}from"node:path";import{z as i}from"zod";import{readFile as a}from"node:fs/promises";import{createLogger as o,serializeError as s}from"../../../core/dist/index.js";const c=o(`flow-tools`);function l(e){return{content:[{type:`text`,text:e}]}}function u(e){return e instanceof Error?e.message:String(e)}function d(o,d){let f=d.sources?.[0]?.path??process.cwd(),p=n(d.stateDir??n(d.sources[0].path,`.aikit-state`),`flows`),m=n(p,`registry.json`),h=n(p,`state.json`);function g(e,n){let i;return i=e.sourceType===`builtin`?r(f,`.github`,`flows`,t(e.installPath),n):r(e.installPath,n),i.replaceAll(`\\`,`/`)}function _(e){return e.sourceType===`builtin`?r(f,`.github`,`flows`,t(e.installPath)).replaceAll(`\\`,`/`):e.installPath.replaceAll(`\\`,`/`)}async function v(){let{FlowRegistryManager:e,FlowStateMachine:t}=await import(`../../../flows/dist/index.js`);return{registry:new e(m),stateMachine:new t(h)}}let y=e(`flow_list`);o.registerTool(`flow_list`,{title:y.title,description:`List all installed flows and their steps`,annotations:y.annotations,inputSchema:{}},async()=>{try{let{registry:e,stateMachine:t}=await v(),n=e.list(),r=t.getStatus(),i={flows:n.map(e=>({name:e.name,version:e.version,source:e.source,sourceType:e.sourceType,format:e.format,steps:e.manifest.steps.map(e=>e.id)})),activeFlow:r.success&&r.data?{flow:r.data.flow,status:r.data.status,currentStep:r.data.currentStep}:null};return l(JSON.stringify(i,null,2))}catch(e){return c.error(`flow_list failed`,s(e)),l(`Error: ${u(e)}`)}});let b=e(`flow_info`);o.registerTool(`flow_info`,{title:b.title,description:`Show detailed information about a specific flow`,annotations:b.annotations,inputSchema:{name:i.string().describe(`Flow name to get info for`)}},async({name:e})=>{try{let{registry:t}=await v(),n=t.get(e);if(!n)return l(`Flow "${e}" not found. Use flow_list to see available flows.`);let r={name:n.name,version:n.version,description:n.manifest.description,source:n.source,sourceType:n.sourceType,format:n.format,installPath:_(n),registeredAt:n.registeredAt,updatedAt:n.updatedAt,steps:n.manifest.steps.map(e=>({id:e.id,name:e.name,skill:g(n,e.skill),produces:e.produces,requires:e.requires,description:e.description})),agents:n.manifest.agents,artifactsDir:n.manifest.artifacts_dir,install:n.manifest.install};return l(JSON.stringify(r,null,2))}catch(e){return c.error(`flow_info failed`,s(e)),l(`Error: ${u(e)}`)}});let x=e(`flow_start`);o.registerTool(`flow_start`,{title:x.title,description:`Start a flow. Sets the active flow and positions at the first step.`,annotations:x.annotations,inputSchema:{flow:i.string().describe(`Flow name to start (use flow_list to see options)`)}},async({flow:e})=>{try{let{registry:t,stateMachine:n}=await v(),r=t.get(e);if(!r)return l(`Flow "${e}" not found. Use flow_list to see available flows.`);let i=n.start(r.name,r.manifest);if(!i.success||!i.data)return l(`Cannot start: ${i.error}`);let a=i.data,o=r.manifest.steps.find(e=>e.id===a.currentStep),s={started:!0,flow:a.flow,currentStep:a.currentStep,currentStepSkill:r&&o?g(r,o.skill):null,currentStepDescription:o?.description??null,totalSteps:r.manifest.steps.length,stepSequence:r.manifest.steps.map(e=>e.id),artifactsDir:r.manifest.artifacts_dir};return l(JSON.stringify(s,null,2))}catch(e){return c.error(`flow_start failed`,s(e)),l(`Error: ${u(e)}`)}});let S=e(`flow_step`);o.registerTool(`flow_step`,{title:S.title,description:`Advance the active flow: complete current step and move to next, skip current step, or redo current step.`,annotations:S.annotations,inputSchema:{action:i.enum([`next`,`skip`,`redo`]).describe(`next: mark current step done and advance. skip: skip current step. redo: repeat current step.`)}},async({action:e})=>{try{let{registry:t,stateMachine:n}=await v(),r=n.load();if(!r)return l(`No active flow. Use flow_start first.`);let i=t.get(r.flow);if(!i)return l(`Flow "${r.flow}" not found in registry.`);let a=n.step(e,i.manifest);if(!a.success||!a.data)return l(`Cannot ${e}: ${a.error}`);let o=a.data,s=o.currentStep?i.manifest.steps.find(e=>e.id===o.currentStep):null,c={flow:o.flow,status:o.status,action:e,currentStep:o.currentStep,currentStepSkill:i&&s?g(i,s.skill):null,currentStepDescription:s?.description??null,completedSteps:o.completedSteps,skippedSteps:o.skippedSteps,totalSteps:i.manifest.steps.length,remaining:i.manifest.steps.filter(e=>!o.completedSteps.includes(e.id)&&!o.skippedSteps.includes(e.id)&&e.id!==o.currentStep).map(e=>e.id)};return l(JSON.stringify(c,null,2))}catch(e){return c.error(`flow_step failed`,s(e)),l(`Error: ${u(e)}`)}});let C=e(`flow_status`);o.registerTool(`flow_status`,{title:C.title,description:`Show the current flow execution state — which flow is active, current step, completed steps, and artifacts.`,annotations:C.annotations,inputSchema:{}},async()=>{try{let{registry:e,stateMachine:t}=await v(),n=t.getStatus();if(!n.success||!n.data)return l(`No active flow. Use flow_start to begin one, or flow_list to see available flows.`);let r=n.data,i=e.get(r.flow),a=i?.manifest.steps.find(e=>e.id===r.currentStep),o=i&&a?g(i,a.skill):null,s={flow:r.flow,status:r.status,currentStep:r.currentStep,currentStepSkill:o,skillPath:o,currentStepDescription:a?.description??null,completedSteps:r.completedSteps,skippedSteps:r.skippedSteps,artifacts:r.artifacts,startedAt:r.startedAt,updatedAt:r.updatedAt,totalSteps:i?.manifest.steps.length??0,progress:i?`${r.completedSteps.length+r.skippedSteps.length}/${i.manifest.steps.length}`:`unknown`};return l(JSON.stringify(s,null,2))}catch(e){return c.error(`flow_status failed`,s(e)),l(`Error: ${u(e)}`)}});let w=e(`flow_read_skill`);o.registerTool(`flow_read_skill`,{title:w.title===`flow_read_skill`?`Flow Read Skill`:w.title,description:`Read the skill or instruction content for a flow step. If step is omitted, reads the current step.`,annotations:w.title===`flow_read_skill`?{readOnlyHint:!0,idempotentHint:!0}:w.annotations,inputSchema:{step:i.string().optional().describe(`Step id or name to read. Defaults to the current step.`)}},async({step:e})=>{try{let{registry:t,stateMachine:n}=await v(),r=n.getStatus();if(!r.success||!r.data)return l(`No active flow. Use flow_start to begin one, or flow_list to see available flows.`);let i=r.data,o=t.get(i.flow);if(!o)return l(`Flow "${i.flow}" not found in registry.`);let s=e??i.currentStep;if(!s)return l(`No current step is available for the active flow.`);let c=o.manifest.steps.find(e=>e.id===s||e.name===s);return l(c?await a(g(o,c.skill),`utf-8`):`Step "${s}" not found in flow "${i.flow}".`)}catch(e){return c.error(`flow_read_skill failed`,s(e)),e instanceof Error&&`code`in e&&e.code===`ENOENT`?l(`Could not read skill file: ${e.message}`):l(`Error: ${u(e)}`)}});let T=e(`flow_reset`);o.registerTool(`flow_reset`,{title:T.title,description:`Reset the active flow, clearing all state. Use to start over or switch to a different flow.`,annotations:T.annotations,inputSchema:{}},async()=>{try{let{stateMachine:e}=await v(),t=e.reset();return t.success?l(`Flow state reset. Use flow_start to begin a new flow.`):l(`Reset failed: ${t.error}`)}catch(e){return c.error(`flow_reset failed`,s(e)),l(`Error: ${u(e)}`)}})}export{d as registerFlowTools};
+import{getToolMeta as e}from"../tool-metadata.js";import{existsSync as t}from"node:fs";import{basename as n,join as r,resolve as i}from"node:path";import{z as a}from"zod";import{readFile as o}from"node:fs/promises";import{createLogger as s,serializeError as c}from"../../../core/dist/index.js";import{homedir as l}from"node:os";const u=s(`flow-tools`);function d(e){return{content:[{type:`text`,text:e}]}}function f(e){return e instanceof Error?e.message:String(e)}function p(s,p){let m=p.sources?.[0]?.path??process.cwd(),h=r(p.stateDir??r(p.sources[0].path,`.aikit-state`),`flows`),g=r(h,`registry.json`),_=r(h,`state.json`);function v(e,t){return i(y(e),t).replaceAll(`\\`,`/`)}function y(e){if(e.sourceType===`builtin`){let r=n(e.installPath),a=i(m,`.github`,`flows`,r);if(t(a))return a.replaceAll(`\\`,`/`);let o=i(l(),`.copilot`,`flows`,r);return t(o)?o.replaceAll(`\\`,`/`):a.replaceAll(`\\`,`/`)}return e.installPath.replaceAll(`\\`,`/`)}async function b(){let{FlowRegistryManager:e,FlowStateMachine:t}=await import(`../../../flows/dist/index.js`);return{registry:new e(g),stateMachine:new t(_)}}let x=e(`flow_list`);s.registerTool(`flow_list`,{title:x.title,description:`List all installed flows and their steps`,annotations:x.annotations,inputSchema:{}},async()=>{try{let{registry:e,stateMachine:t}=await b(),n=e.list(),r=t.getStatus(),i={flows:n.map(e=>({name:e.name,version:e.version,source:e.source,sourceType:e.sourceType,format:e.format,steps:e.manifest.steps.map(e=>e.id)})),activeFlow:r.success&&r.data?{flow:r.data.flow,status:r.data.status,currentStep:r.data.currentStep}:null};return d(JSON.stringify(i,null,2))}catch(e){return u.error(`flow_list failed`,c(e)),d(`Error: ${f(e)}`)}});let S=e(`flow_info`);s.registerTool(`flow_info`,{title:S.title,description:`Show detailed information about a specific flow`,annotations:S.annotations,inputSchema:{name:a.string().describe(`Flow name to get info for`)}},async({name:e})=>{try{let{registry:t}=await b(),n=t.get(e);if(!n)return d(`Flow "${e}" not found. Use flow_list to see available flows.`);let r={name:n.name,version:n.version,description:n.manifest.description,source:n.source,sourceType:n.sourceType,format:n.format,installPath:y(n),registeredAt:n.registeredAt,updatedAt:n.updatedAt,steps:n.manifest.steps.map(e=>({id:e.id,name:e.name,skill:v(n,e.skill),produces:e.produces,requires:e.requires,description:e.description})),agents:n.manifest.agents,artifactsDir:n.manifest.artifacts_dir,install:n.manifest.install};return d(JSON.stringify(r,null,2))}catch(e){return u.error(`flow_info failed`,c(e)),d(`Error: ${f(e)}`)}});let C=e(`flow_start`);s.registerTool(`flow_start`,{title:C.title,description:`Start a flow. Sets the active flow and positions at the first step.`,annotations:C.annotations,inputSchema:{flow:a.string().describe(`Flow name to start (use flow_list to see options)`)}},async({flow:e})=>{try{let{registry:t,stateMachine:n}=await b(),r=t.get(e);if(!r)return d(`Flow "${e}" not found. Use flow_list to see available flows.`);let i=n.start(r.name,r.manifest);if(!i.success||!i.data)return d(`Cannot start: ${i.error}`);let a=i.data,o=r.manifest.steps.find(e=>e.id===a.currentStep),s={started:!0,flow:a.flow,currentStep:a.currentStep,currentStepSkill:r&&o?v(r,o.skill):null,currentStepDescription:o?.description??null,totalSteps:r.manifest.steps.length,stepSequence:r.manifest.steps.map(e=>e.id),artifactsDir:r.manifest.artifacts_dir};return d(JSON.stringify(s,null,2))}catch(e){return u.error(`flow_start failed`,c(e)),d(`Error: ${f(e)}`)}});let w=e(`flow_step`);s.registerTool(`flow_step`,{title:w.title,description:`Advance the active flow: complete current step and move to next, skip current step, or redo current step.`,annotations:w.annotations,inputSchema:{action:a.enum([`next`,`skip`,`redo`]).describe(`next: mark current step done and advance. skip: skip current step. redo: repeat current step.`)}},async({action:e})=>{try{let{registry:t,stateMachine:n}=await b(),r=n.load();if(!r)return d(`No active flow. Use flow_start first.`);let i=t.get(r.flow);if(!i)return d(`Flow "${r.flow}" not found in registry.`);let a=n.step(e,i.manifest);if(!a.success||!a.data)return d(`Cannot ${e}: ${a.error}`);let o=a.data,s=o.currentStep?i.manifest.steps.find(e=>e.id===o.currentStep):null,c={flow:o.flow,status:o.status,action:e,currentStep:o.currentStep,currentStepSkill:i&&s?v(i,s.skill):null,currentStepDescription:s?.description??null,completedSteps:o.completedSteps,skippedSteps:o.skippedSteps,totalSteps:i.manifest.steps.length,remaining:i.manifest.steps.filter(e=>!o.completedSteps.includes(e.id)&&!o.skippedSteps.includes(e.id)&&e.id!==o.currentStep).map(e=>e.id)};return d(JSON.stringify(c,null,2))}catch(e){return u.error(`flow_step failed`,c(e)),d(`Error: ${f(e)}`)}});let T=e(`flow_status`);s.registerTool(`flow_status`,{title:T.title,description:`Show the current flow execution state — which flow is active, current step, completed steps, and artifacts.`,annotations:T.annotations,inputSchema:{}},async()=>{try{let{registry:e,stateMachine:t}=await b(),n=t.getStatus();if(!n.success||!n.data)return d(`No active flow. Use flow_start to begin one, or flow_list to see available flows.`);let r=n.data,i=e.get(r.flow),a=i?.manifest.steps.find(e=>e.id===r.currentStep),o=i&&a?v(i,a.skill):null,s={flow:r.flow,status:r.status,currentStep:r.currentStep,currentStepSkill:o,skillPath:o,currentStepDescription:a?.description??null,completedSteps:r.completedSteps,skippedSteps:r.skippedSteps,artifacts:r.artifacts,startedAt:r.startedAt,updatedAt:r.updatedAt,totalSteps:i?.manifest.steps.length??0,progress:i?`${r.completedSteps.length+r.skippedSteps.length}/${i.manifest.steps.length}`:`unknown`};return d(JSON.stringify(s,null,2))}catch(e){return u.error(`flow_status failed`,c(e)),d(`Error: ${f(e)}`)}});let E=e(`flow_read_skill`);s.registerTool(`flow_read_skill`,{title:E.title===`flow_read_skill`?`Flow Read Skill`:E.title,description:`Read the skill or instruction content for a flow step. If step is omitted, reads the current step.`,annotations:E.title===`flow_read_skill`?{readOnlyHint:!0,idempotentHint:!0}:E.annotations,inputSchema:{step:a.string().optional().describe(`Step id or name to read. Defaults to the current step.`)}},async({step:e})=>{try{let{registry:t,stateMachine:n}=await b(),r=n.getStatus();if(!r.success||!r.data)return d(`No active flow. Use flow_start to begin one, or flow_list to see available flows.`);let i=r.data,a=t.get(i.flow);if(!a)return d(`Flow "${i.flow}" not found in registry.`);let s=e??i.currentStep;if(!s)return d(`No current step is available for the active flow.`);let c=a.manifest.steps.find(e=>e.id===s||e.name===s);return d(c?await o(v(a,c.skill),`utf-8`):`Step "${s}" not found in flow "${i.flow}".`)}catch(e){return u.error(`flow_read_skill failed`,c(e)),e instanceof Error&&`code`in e&&e.code===`ENOENT`?d(`Could not read skill file: ${e.message}`):d(`Error: ${f(e)}`)}});let D=e(`flow_reset`);s.registerTool(`flow_reset`,{title:D.title,description:`Reset the active flow, clearing all state. Use to start over or switch to a different flow.`,annotations:D.annotations,inputSchema:{}},async()=>{try{let{stateMachine:e}=await b(),t=e.reset();return t.success?d(`Flow state reset. Use flow_start to begin a new flow.`):d(`Reset failed: ${t.error}`)}catch(e){return u.error(`flow_reset failed`,c(e)),d(`Error: ${f(e)}`)}})}export{p as registerFlowTools};

package/packages/server/dist/version-check.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{createLogger as a}from"../../core/dist/index.js";import{execFile as o}from"node:child_process";import{homedir as s}from"node:os";const c=a(`server`);function l(){let e=r(n(i(import.meta.url)),`..`,`..`,`..`,`package.json`);try{return JSON.parse(t(e,`utf-8`)).version??`0.0.0`}catch{return`0.0.0`}}function u(e,t){let n=e.split(`.`).map(Number),r=t.split(`.`).map(Number);for(let e=0;e<3;e++){let t=(n[e]??0)-(r[e]??0);if(t!==0)return t>0?1:-1}return 0}function d(){let e=l();fetch(`https://registry.npmjs.org/@vpxa/aikit/latest`,{signal:AbortSignal.timeout(5e3)}).then(e=>{if(e.ok)return e.json()}).then(t=>{if(!t||typeof t!=`object`)return;let n=t.version;n&&u(e,n)<0&&c.warn(`Update available`,{currentVersion:e,latestVersion:n,updateCommand:`aikit upgrade`})}).catch(()=>{})}function f(){try{let n=r(s(),`.copilot`,`.aikit-scaffold.json`);return e(n)?JSON.parse(t(n,`utf-8`)).version??null:null}catch{return null}}function p(){try{let n=r(process.cwd(),`.github`,`.aikit-scaffold.json`);return e(n)?JSON.parse(t(n,`utf-8`)).version??null:null}catch{return null}}let m=`idle`,h=null;function g(){return{state:m,error:h}}function _(){try{let t=l(),a=f(),s=p();if(!(a!=null&&a!==t)&&!(s!=null&&s!==t)||m===`pending`||m===`success`)return;m=`pending`,h=null,c.info(`Scaffold version mismatch — auto-upgrading`,{serverVersion:t,userScaffoldVersion:a,workspaceScaffoldVersion:s});let u=r(n(i(import.meta.url)),`..`,`..`,`..`,`bin`,`aikit.mjs`);if(!e(u)){m=`failed`,h=`aikit CLI binary not found at ${u}`,c.warn(`Cannot auto-upgrade: aikit CLI binary not found`,{binPath:u});return}o(process.execPath,[u,`upgrade`],{timeout:3e4,windowsHide:!0},(e,t,n)=>{e?(m=`failed`,h=e.message,c.warn(`Auto-upgrade failed`,{error:e.message,stderr:n?.slice(0,500)})):(m=`success`,h=null,c.info(`Auto-upgrade complete`))}).unref()}catch(e){m=`failed`,h=e instanceof Error?e.message:String(e),c.warn(`Auto-upgrade check failed`,{error:h})}}export{_ as autoUpgradeScaffold,d as checkForUpdates,l as getCurrentVersion,g as getUpgradeState};
+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{createLogger as a}from"../../core/dist/index.js";import{homedir as o}from"node:os";import{execFile as s}from"node:child_process";const c=a(`server`);function l(){let e=r(n(i(import.meta.url)),`..`,`..`,`..`,`package.json`);try{return JSON.parse(t(e,`utf-8`)).version??`0.0.0`}catch{return`0.0.0`}}function u(e,t){let n=e.split(`.`).map(Number),r=t.split(`.`).map(Number);for(let e=0;e<3;e++){let t=(n[e]??0)-(r[e]??0);if(t!==0)return t>0?1:-1}return 0}function d(){let e=l();fetch(`https://registry.npmjs.org/@vpxa/aikit/latest`,{signal:AbortSignal.timeout(5e3)}).then(e=>{if(e.ok)return e.json()}).then(t=>{if(!t||typeof t!=`object`)return;let n=t.version;n&&u(e,n)<0&&c.warn(`Update available`,{currentVersion:e,latestVersion:n,updateCommand:`aikit upgrade`})}).catch(()=>{})}function f(){try{let n=r(o(),`.copilot`,`.aikit-scaffold.json`);return e(n)?JSON.parse(t(n,`utf-8`)).version??null:null}catch{return null}}function p(){try{let n=r(process.cwd(),`.github`,`.aikit-scaffold.json`);return e(n)?JSON.parse(t(n,`utf-8`)).version??null:null}catch{return null}}let m=`idle`,h=null;function g(){return{state:m,error:h}}function _(){try{let t=l(),a=f(),o=p();if(!(a!=null&&a!==t)&&!(o!=null&&o!==t)||m===`pending`||m===`success`)return;m=`pending`,h=null,c.info(`Scaffold version mismatch — auto-upgrading`,{serverVersion:t,userScaffoldVersion:a,workspaceScaffoldVersion:o});let u=r(n(i(import.meta.url)),`..`,`..`,`..`,`bin`,`aikit.mjs`);if(!e(u)){m=`failed`,h=`aikit CLI binary not found at ${u}`,c.warn(`Cannot auto-upgrade: aikit CLI binary not found`,{binPath:u});return}s(process.execPath,[u,`upgrade`],{timeout:3e4,windowsHide:!0},(e,t,n)=>{e?(m=`failed`,h=e.message,c.warn(`Auto-upgrade failed`,{error:e.message,stderr:n?.slice(0,500)})):(m=`success`,h=null,c.info(`Auto-upgrade complete`))}).unref()}catch(e){m=`failed`,h=e instanceof Error?e.message:String(e),c.warn(`Auto-upgrade check failed`,{error:h})}}export{_ as autoUpgradeScaffold,d as checkForUpdates,l as getCurrentVersion,g as getUpgradeState};

package/scaffold/adapters/copilot.mjs

@@ -64,8 +64,14 @@ function buildToolsYaml(toolRole) {
 }
 
 function copilotModel(agentName) {
-  const base = MODELS[agentName];
-  return base ? `${base} (copilot)` : 'Claude Opus 4.6 (copilot)';
+  const models = MODELS[agentName];
+  if (!models) return 'Auto (copilot)';
+  if (Array.isArray(models)) {
+    if (models.length === 0) return 'Auto (copilot)';
+    if (models.length === 1) return models[0];
+    return `[${models.join(', ')}]`;
+  }
+  return models;
 }
 
 const FLOWS_SECTION = [
@@ -84,13 +90,15 @@ function buildAgentTable() {
     if (def.variants) {
       for (const suffix of VARIANT_GROUPS[name] || []) {
         const fullName = `${name}-${suffix}`;
-        const model = MODELS[fullName] || 'Unknown';
+        const models = MODELS[fullName] || MODELS[name];
+        const model = Array.isArray(models) ? models[0] : models || 'Unknown';
         const varDef = def.variants[suffix] || {};
         const desc = varDef.description || def.description;
         rows.push(`| **${fullName}** | ${desc} | ${model} | ${def.category} |`);
       }
     } else {
-      const model = MODELS[name] || 'Unknown';
+      const models = MODELS[name];
+      const model = Array.isArray(models) ? models[0] : models || 'Unknown';
       rows.push(`| **${name}** | ${def.description} | ${model} | ${def.category} |`);
     }
   }

package/scaffold/definitions/agents.mjs

@@ -75,6 +75,7 @@ export const AGENTS = {
     toolRole: 'refactor',
     sharedBase: 'code-agent-base',
     category: 'implementation',
+    skills: [['aikit', '**Always** — AI Kit tool signatures, search, analysis']],
   },
 
   // ─── Diagnostics ──────────────────────────────────────────────────────
@@ -115,6 +116,10 @@ export const AGENTS = {
     toolRole: 'documenter',
     sharedBase: null,
     category: 'documentation',
+    skills: [
+      ['aikit', '**Always** — AI Kit tool signatures, search, analysis'],
+      ['present', 'When presenting documentation previews or architecture visuals to the user'],
+    ],
   },
 
   Explorer: {
@@ -139,9 +144,10 @@ export const AGENTS = {
     sharedBase: 'researcher-base',
     category: 'research',
     skills: [
-      ['`lesson-learned`', 'When analyzing past changes to extract engineering principles'],
-      ['`c4-architecture`', 'When researching system architecture \u2014 produce C4 diagrams'],
-      ['`adr-skill`', 'When the research involves a technical decision \u2014 draft an ADR'],
+      ['aikit', '**Always** — AI Kit tool signatures, search, analysis'],
+      ['lesson-learned', 'When analyzing past changes to extract engineering principles'],
+      ['c4-architecture', 'When researching system architecture \u2014 produce C4 diagrams'],
+      ['adr-skill', 'When the research involves a technical decision \u2014 draft an ADR'],
     ],
     variants: {
       Alpha: {
@@ -195,9 +201,10 @@ export const AGENTS = {
     sharedBase: 'architect-reviewer-base',
     category: 'review',
     skills: [
-      ['`c4-architecture`', 'When reviewing architectural diagrams or boundary changes'],
+      ['aikit', '**Always** — AI Kit tool signatures, search, analysis'],
+      ['c4-architecture', 'When reviewing architectural diagrams or boundary changes'],
       [
-        '`adr-skill`',
+        'adr-skill',
         'When the review involves architecture decisions \u2014 reference or create ADRs',
       ],
     ],

package/scaffold/definitions/bodies.mjs

@@ -40,26 +40,43 @@ ${agentTable}
 3. After review: \`evidence_map({ action: "gate", task_id })\` → YIELD/HOLD/HARD_BLOCK
 4. Auto-upgrade tier if unknowns reveal contract/security issues
 
-## Workflow
+## Flow-Driven Development
 
-### Phase 1: Planning
-1. Read onboard artifacts → parse goal → identify affected subsystems → \`forge_classify\`
-2. Research: <5 files direct, 5-15 Explorer→Researcher, >15 multiple parallel
-3. Draft plan: 3-10 phases, agent assignments, TDD steps, dependency graph
-4. Batch independent phases for parallel execution
-5. **🛑 STOP — user approval required**
+Orchestrator uses the flow system for structured development. Flows define the step sequence — Orchestrator adds multi-agent orchestration, quality gates, and review protocols on top.
 
-### Phase 2: Implementation Cycle
+### Flow Selection
 
-**🚨 PRE-DISPATCH GATE — complete ALL before ANY \`runSubagent\` call:**
+| Situation | Flow | Steps |
+|-----------|------|-------|
+| Bug fix, small feature, refactoring | \`aikit:basic\` | assess → implement → verify |
+| New feature, major change, multi-file | \`aikit:advanced\` | spec → plan → task → execute → verify |
+| Custom/specialized work | Check \`flow_list\` | Follow flow-specific steps |
 
-1. ✅ \`multi-agents-development\` skill loaded? (Bootstrap step 4 — if not, load NOW)
-2. ✅ Task decomposition table produced? (show user: task → files → agent → parallel batch)
-3. ✅ Independence Check passed per pair? (shared files? shared state? ordering dependency? → must be "No" for parallel)
-4. ✅ Each task ≤ 3 files? (if not, split further)
-5. ✅ Parallel batches identified? (tasks with no dependencies MUST be in same batch)
+**If multiple flows could apply and user hasn't specified → ask user to choose.**
 
-**Decomposition output format** (show this to user before dispatching):
+### Session Start Flow Check
+
+1. \`flow_status\` — check for active flow
+2. If active:
+   - Note current step name and skill path
+   - Read the current step skill with \`flow_read_skill\`
+   - Follow its instructions
+   - When complete: \`flow_step({ action: 'next' })\`
+3. If no active flow:
+   - \`flow_list\` — check ALL available flows (builtin + custom)
+   - Recommend appropriate flow based on task scope
+   - \`flow_start({ flow: '<name>' })\` after user confirms
+
+### Orchestrator Protocols (apply during ALL flow steps)
+
+**PRE-DISPATCH GATE — complete ALL before ANY \`runSubagent\` call:**
+1. ✅ \`multi-agents-development\` skill loaded?
+2. ✅ Task decomposition table produced?
+3. ✅ Independence Check passed per pair?
+4. ✅ Each task ≤ 3 files?
+5. ✅ Parallel batches identified?
+
+**Decomposition output format:**
 
 \`\`\`
 Batch 1 (parallel):
@@ -69,23 +86,35 @@ Batch 2 (after batch 1):
    Task C: [agent] → [file5] — [goal] (depends on A)
 \`\`\`
 
-**Prompt every subagent with** (use \`multi-agents-development\` skill templates):
-1. **Scope** — exact files to touch + boundary (do NOT touch)
+**Subagent prompt template:**
+1. **Scope** — exact files + boundary
 2. **Goal** — acceptance criteria, testable
-3. **Arch Context** — paste actual code snippets from \`compact()\`/\`digest()\`
-4. **Constraints** — patterns, conventions, anti-patterns
+3. **Arch Context** — code snippets from \`compact()\`/\`digest()\`
+4. **Constraints** — patterns, conventions
 5. **FORGE** — tier + evidence requirements
 6. **Self-Review** — checklist before declaring status
 
-**Subagent status protocol**: \`DONE\` | \`DONE_WITH_CONCERNS\` | \`NEEDS_CONTEXT\` | \`BLOCKED\`
+**Subagent status protocol:** \`DONE\` | \`DONE_WITH_CONCERNS\` | \`NEEDS_CONTEXT\` | \`BLOCKED\`
 
-**Per-batch flow**: Dispatch (parallel) → Spec Review → Code Quality Review (Alpha+Beta parallel) → Arch Review (if boundary changes) → Security (if applicable) → \`evidence_map\` gate → **🛑 STOP — present commit message**
+**Additional Orchestrator requirements during flow execution:**
+- Apply the PRE-DISPATCH GATE before any subagent dispatch, regardless of flow
+- Apply FORGE at classification and verification points; pass tier/evidence expectations into subagents and gate with \`evidence_map\`
+- Enforce delegation rules at all times — Orchestrator never implements code directly
+- Use the subagent prompt template for every dispatch so step-specific flow instructions are grounded in actual code context
 
-### Phase 3: Completion
-1. Optional: Refactor pass (separate commit)
-2. Documenter for docs updates
-3. \`remember\` all decisions, patterns, gotchas, conventions
-4. \`reindex({})\` + \`produce_knowledge({ path: "." })\`
+**Per-step review cycle:** Dispatch → Code Review (Alpha+Beta) → Arch Review (if boundary changes) → Security (if applicable) → \`evidence_map\` gate → **🛑 STOP — present results**
+
+### Flow MCP Tools
+
+| Tool | Purpose |
+|------|---------|
+| \`flow_list\` | List installed flows and active flow |
+| \`flow_info\` | Get detailed flow info including steps |
+| \`flow_start\` | Start a named flow |
+| \`flow_step\` | Advance: next, skip, or redo current step |
+| \`flow_status\` | Check current execution state |
+| \`flow_reset\` | Clear flow state to start over |
+| \`flow_read_skill\` | Read the skill content for the current step |
 
 ## Emergency: STOP → ASSESS → CONTAIN → RECOVER → DOCUMENT
 
@@ -167,6 +196,7 @@ Before every tool call, verify:
 | Skill | When to load |
 |-------|--------------|
 | \`multi-agents-development\` | **Before any delegation** — task decomposition, dispatch templates, review pipeline, recovery patterns |
+| \`present\` | When presenting plans, findings, or visual content to the user — dashboards, tables, charts, timelines |
 | \`brainstorming\` | Before creative/design work (Phase 0) |
 | \`session-handoff\` | Context filling up, session ending, or major milestone |
 | \`lesson-learned\` | After completing work — extract engineering principles |
@@ -227,6 +257,17 @@ At session start, check for an active flow:
 5. **Dependency Graph** — For each phase, list dependencies. Group into parallel batches
 6. **Present** — Show plan with open questions, complexity estimate, parallel batch layout
 
+## Flow Integration
+
+When activated as part of a flow (e.g., \`aikit:advanced\` plan step or \`aikit:basic\` assess step):
+1. Check \`flow_status\` for current step context
+2. Read the step's skill file for specific instructions
+3. Follow skill instructions while applying Planner methodology
+4. Produce required artifacts (as specified by the flow step's \`produces\` field)
+5. When complete, report to Orchestrator (do NOT call \`flow_step\` — let Orchestrator advance)
+
+When no flow is active, operate autonomously following normal Planner methodology.
+
 ## Subagent Output Relay
 
 When subagents complete, their visual outputs (from \`present\`) are NOT visible to the user.
@@ -276,6 +317,7 @@ When subagents complete, their visual outputs (from \`present\`) are NOT visible
 | Skill | When to load |
 |-------|--------------|
 | \`brainstorming\` | Before planning any new feature, component, or behavior change — use Visual Companion for architecture mockups |
+| \`present\` | When presenting plans, dependency graphs, or complexity estimates to the user |
 | \`requirements-clarity\` | When requirements are vague or complex (>2 days) — score 0-100 before committing to a plan |
 | \`c4-architecture\` | When the plan involves architectural changes — generate C4 diagrams |
 | \`adr-skill\` | When the plan involves non-trivial technical decisions — create executable ADRs |
@@ -459,6 +501,7 @@ When subagents complete, their visual outputs (from \`present\`) are NOT visible
 
 | Skill | When to load |
 |-------|--------------|
+| \`present\` | When presenting documentation previews, API tables, or architecture visuals to the user |
 | \`c4-architecture\` | When documenting system architecture — generate C4 Mermaid diagrams |
 | \`adr-skill\` | When documenting architecture decisions — create or update ADRs |
 | \`typescript\` | When documenting TypeScript APIs — type signatures, JSDoc patterns |`,

package/scaffold/definitions/models.mjs

@@ -11,29 +11,44 @@
 
 export const MODELS = {
   // ─── Single-role agents ───────────────────────────────────────────────
-  Orchestrator: 'Claude Opus 4.6',
-  Planner: 'Claude Opus 4.6',
-  Implementer: 'GPT-5.4',
-  Frontend: 'Gemini 3.1 Pro (Preview)',
-  Debugger: 'Claude Opus 4.6',
-  Refactor: 'GPT-5.4',
-  Security: 'Claude Opus 4.6',
-  Documenter: 'GPT-5.4',
-  Explorer: 'Gemini 3 Flash (Preview)',
+  Orchestrator: ['Claude Opus 4.6 (copilot)', 'GPT-5.4 (copilot)', 'Auto (copilot)'],
+  Planner: ['Claude Opus 4.6 (copilot)', 'GPT-5.4 (copilot)', 'Auto (copilot)'],
+  Implementer: [
+    'GPT-5.4 (copilot)',
+    'Gemini 3.1 Pro (Preview) (copilot)',
+    'GPT-5.3-Codex (copilot)',
+    'Auto (copilot)',
+  ],
+  Frontend: [
+    'Gemini 3.1 Pro (Preview) (copilot)',
+    'GPT-5.4 (copilot)',
+    'GPT-5.3-Codex (copilot)',
+    'Auto (copilot)',
+  ],
+  Debugger: [
+    'Claude Opus 4.6 (copilot)',
+    'GPT-5.4 (copilot)',
+    'GPT-5.3-Codex (copilot)',
+    'Auto (copilot)',
+  ],
+  Refactor: ['GPT-5.4 (copilot)', 'GPT-5.3-Codex (copilot)', 'Auto (copilot)'],
+  Security: ['Claude Opus 4.6 (copilot)', 'GPT-5.4 (copilot)', 'Auto (copilot)'],
+  Documenter: ['GPT-5.4 (copilot)', 'Gemini 3.1 Pro (Preview) (copilot)', 'Auto (copilot)'],
+  Explorer: ['Gemini 3 Flash (Preview) (copilot)', 'Claude Haiku 4.5 (copilot)', 'Auto (copilot)'],
 
   // ─── Researcher variants (4 models for multi-model decision protocol) ────────────
-  'Researcher-Alpha': 'Claude Opus 4.6',
-  'Researcher-Beta': 'Claude Sonnet 4.6',
-  'Researcher-Gamma': 'GPT-5.4',
-  'Researcher-Delta': 'Gemini 3.1 Pro (Preview)',
+  'Researcher-Alpha': ['Claude Opus 4.6 (copilot)', 'Auto (copilot)'],
+  'Researcher-Beta': ['Claude Sonnet 4.6 (copilot)', 'Auto (copilot)'],
+  'Researcher-Gamma': ['GPT-5.4 (copilot)', 'Auto (copilot)'],
+  'Researcher-Delta': ['Gemini 3.1 Pro (Preview) (copilot)', 'Auto (copilot)'],
 
   // ─── Code-Reviewer variants (2 models for dual review) ───────────────
-  'Code-Reviewer-Alpha': 'GPT-5.4',
-  'Code-Reviewer-Beta': 'Claude Opus 4.6',
+  'Code-Reviewer-Alpha': ['GPT-5.4 (copilot)', 'Auto (copilot)'],
+  'Code-Reviewer-Beta': ['Claude Opus 4.6 (copilot)', 'Auto (copilot)'],
 
   // ─── Architect-Reviewer variants (2 models for dual review) ──────────
-  'Architect-Reviewer-Alpha': 'GPT-5.4',
-  'Architect-Reviewer-Beta': 'Claude Opus 4.6',
+  'Architect-Reviewer-Alpha': ['GPT-5.4 (copilot)', 'Auto (copilot)'],
+  'Architect-Reviewer-Beta': ['Claude Opus 4.6 (copilot)', 'Auto (copilot)'],
 };
 
 /**

package/scaffold/definitions/protocols.mjs

@@ -91,9 +91,11 @@ Your agent file lists domain-specific skills in the **Skills** section. Load the
 
 1. Check if the current task matches a listed skill trigger
 2. If yes → load the skill file before starting implementation
-3. The \`aikit\` skill is **always loaded** — do not re-load it
+3. The following skills are **foundational** — always loaded, do not re-load:
+   - **\`aikit\`** — AI Kit MCP tool reference, search strategies, compression workflows, session protocol. **Required for all tool usage.**
+   - **\`present\`** — Rich content rendering (dashboards, tables, charts, timelines). **Required when producing visual output for the user.**
 
-> If no skills are listed for your agent, rely on AI Kit tools and onboard artifacts.
+> If no additional skills are listed for your agent, rely on AI Kit tools and onboard artifacts.
 
 ---
 
@@ -135,12 +137,32 @@ list()                     // see all stored knowledge entries
 | \`symbol({ name })\` | Find symbol definition + references |
 | \`trace({ symbol, direction })\` | Follow call graph forward/backward |
 | \`compact({ path, query })\` | Read specific section of a file |
-| \`read_file\` | **Only** when you need exact lines for editing |
+| \`read_file\` | **ONLY** when you need exact lines for a pending edit |
 
 ### Step 4: Tool Discovery
 
 If unsure which AI Kit tool to use → run \`guide({ topic: "what you need" })\` for recommendations.
 
+---
+
+## PROHIBITED: Native File Reading Tools
+
+**\`read_file\` / \`read_file_raw\` MUST NOT be used to understand code.** They waste tokens and miss structural information that AI Kit tools provide.
+
+| ❌ NEVER do this | ✅ Do this instead | Why |
+|---|---|---|
+| \`read_file\` to understand a file | \`file_summary({ path })\` | Structure, exports, imports, call edges — **10x fewer tokens** |
+| \`read_file\` to find specific code | \`compact({ path, query })\` | Server-side read + semantic extract — **5-20x reduction** |
+| Multiple \`read_file\` calls | \`digest({ sources })\` | Compresses multiple files into token-budgeted summary |
+| \`grep_search\` / \`textSearch\` | \`search({ query })\` | Hybrid search across all indexed + curated content |
+| \`grep_search\` for a symbol | \`symbol({ name })\` | Definition + references with scope context |
+| Manual code tracing | \`trace({ start, direction })\` | AST call-graph traversal |
+| Line counting / \`wc\` | \`measure({ path })\` | Lines, functions, cognitive complexity |
+| \`fetch_webpage\` | \`web_fetch({ urls })\` | Readability extract + token budget |
+| Web research / browsing | \`web_search({ queries })\` | Structured web results without browser |
+
+**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.
+
 ## FORGE Protocol (Quality Gate)
 
 **Quick reference:**
@@ -239,10 +261,11 @@ For outdated AI Kit entries → \`update(path, content, reason)\`
 
 ## Context Efficiency
 
-Minimize token usage by choosing the right compression tool:
-- **\`compact({ path, query })\`** — Extract relevant sections from a single file (5-20x token reduction vs full read)
+**NEVER use \`read_file\` to understand code.** 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
-- **\`stratum_card({ path })\`** — Generate a reusable T1/T2 context card for files you'll reference repeatedly
+- **\`stratum_card({ files, query })\`** — Generate a reusable T1/T2 context card for files you'll reference repeatedly
 
 **Session phases** — structure your work to minimize context bloat:
 
@@ -424,10 +447,12 @@ When invoked for a decision analysis, you receive a specific question. You MUST:
 
 ## Context Efficiency
 
-- **Prefer \`file_summary\` over \`read_file\`** for understanding structure
-- **Prefer \`compact\` over full reads** when you need specific sections
-- **Use \`digest\`** when synthesizing from 3+ sources
-- **Use \`stratum_card\`** for files you'll reference repeatedly
+- **NEVER use \`read_file\` to understand code** — use AI Kit compression tools instead
+- **\`file_summary\`** for structure (exports, imports, call edges — 10x fewer tokens)
+- **\`compact\`** for specific sections (5-20x token reduction vs read_file)
+- **\`digest\`** when synthesizing from 3+ sources
+- **\`stratum_card\`** for files you'll reference repeatedly
+- **\`read_file\` is ONLY acceptable** when you need exact lines for a pending edit operation
 `,
 
   'code-reviewer-base': `# Code-Reviewer — Shared Base Instructions

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

@@ -2,7 +2,7 @@
 description: 'Primary architecture reviewer'
 argument-hint: Files, PR, or subsystem to architecture-review
 tools: [execute/runInTerminal, read/problems, read/readFile, read/terminalLastCommand, agent/runSubagent, search/changes, search/codebase, search/usages, web/fetch, web/githubRepo, browser/openBrowserPage, browser/readPage, browser/screenshotPage, browser/navigatePage, browser/clickElement, browser/dragElement, browser/hoverElement, browser/typeInPage, browser/runPlaywrightCode, browser/handleDialog, aikit/*]
-model: GPT-5.4 (copilot)
+model: [GPT-5.4 (copilot), Auto (copilot)]
 ---
 
 # Architect-Reviewer-Alpha - The Structural Guardian
@@ -17,8 +17,9 @@ You are **not** the Code-Reviewer agent. Code-Reviewer handles correctness, test
 
 | Skill | When to load |
 |-------|--------------|
-| `c4-architecture` | When reviewing architectural diagrams or boundary changes |
-| `adr-skill` | When the review involves architecture decisions — reference or create ADRs |
+| aikit | **Always** — AI Kit tool signatures, search, analysis |
+| c4-architecture | When reviewing architectural diagrams or boundary changes |
+| adr-skill | When the review involves architecture decisions — reference or create ADRs |
 
 ## Flows
 

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

@@ -2,7 +2,7 @@
 description: 'Architecture reviewer variant — different LLM perspective for dual review'
 argument-hint: Files, PR, or subsystem to architecture-review
 tools: [execute/runInTerminal, read/problems, read/readFile, read/terminalLastCommand, agent/runSubagent, search/changes, search/codebase, search/usages, web/fetch, web/githubRepo, browser/openBrowserPage, browser/readPage, browser/screenshotPage, browser/navigatePage, browser/clickElement, browser/dragElement, browser/hoverElement, browser/typeInPage, browser/runPlaywrightCode, browser/handleDialog, aikit/*]
-model: Claude Opus 4.6 (copilot)
+model: [Claude Opus 4.6 (copilot), Auto (copilot)]
 ---
 
 # Architect-Reviewer-Beta - The Structural Guardian
@@ -17,8 +17,9 @@ You are **not** the Code-Reviewer agent. Code-Reviewer handles correctness, test
 
 | Skill | When to load |
 |-------|--------------|
-| `c4-architecture` | When reviewing architectural diagrams or boundary changes |
-| `adr-skill` | When the review involves architecture decisions — reference or create ADRs |
+| aikit | **Always** — AI Kit tool signatures, search, analysis |
+| c4-architecture | When reviewing architectural diagrams or boundary changes |
+| adr-skill | When the review involves architecture decisions — reference or create ADRs |
 
 ## Flows
 

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

@@ -2,7 +2,7 @@
 description: 'Primary code reviewer'
 argument-hint: File path, PR, or code to review
 tools: [execute/runInTerminal, read/problems, read/readFile, read/terminalLastCommand, agent/runSubagent, search/changes, search/codebase, search/usages, web/fetch, web/githubRepo, browser/openBrowserPage, browser/readPage, browser/screenshotPage, browser/navigatePage, browser/clickElement, browser/dragElement, browser/hoverElement, browser/typeInPage, browser/runPlaywrightCode, browser/handleDialog, aikit/*]
-model: GPT-5.4 (copilot)
+model: [GPT-5.4 (copilot), Auto (copilot)]
 ---
 
 # Code-Reviewer-Alpha - The Quality Guardian

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

@@ -2,7 +2,7 @@
 description: 'Code reviewer variant — different LLM perspective for dual review'
 argument-hint: File path, PR, or code to review
 tools: [execute/runInTerminal, read/problems, read/readFile, read/terminalLastCommand, agent/runSubagent, search/changes, search/codebase, search/usages, web/fetch, web/githubRepo, browser/openBrowserPage, browser/readPage, browser/screenshotPage, browser/navigatePage, browser/clickElement, browser/dragElement, browser/hoverElement, browser/typeInPage, browser/runPlaywrightCode, browser/handleDialog, aikit/*]
-model: Claude Opus 4.6 (copilot)
+model: [Claude Opus 4.6 (copilot), Auto (copilot)]
 ---
 
 # Code-Reviewer-Beta - The Quality Guardian

package/scaffold/general/agents/Debugger.agent.md

@@ -2,7 +2,7 @@
 description: 'Expert debugger that diagnoses issues, traces errors, and provides solutions'
 argument-hint: Error message, stack trace, or description of issue
 tools: [execute/runInTerminal, read/problems, read/readFile, read/terminalSelection, read/terminalLastCommand, agent/runSubagent, edit/createFile, edit/editFiles, search/changes, search/codebase, search/usages, browser/openBrowserPage, browser/readPage, browser/screenshotPage, browser/navigatePage, browser/clickElement, browser/dragElement, browser/hoverElement, browser/typeInPage, browser/runPlaywrightCode, browser/handleDialog, aikit/*]
-model: Claude Opus 4.6 (copilot)
+model: [Claude Opus 4.6 (copilot), GPT-5.4 (copilot), GPT-5.3-Codex (copilot), Auto (copilot)]
 ---
 
 # Debugger - The Problem Solver

package/scaffold/general/agents/Documenter.agent.md

@@ -2,7 +2,7 @@
 description: 'Documentation specialist that creates and maintains comprehensive project documentation'
 argument-hint: Component, API, feature, or area to document
 tools: [execute/runInTerminal, read/problems, read/readFile, read/terminalLastCommand, agent/runSubagent, edit/createFile, edit/editFiles, edit/rename, edit/createDirectory, search/changes, search/codebase, search/usages, web/fetch, web/githubRepo, browser/openBrowserPage, browser/readPage, browser/screenshotPage, browser/navigatePage, browser/clickElement, browser/dragElement, browser/hoverElement, browser/typeInPage, browser/runPlaywrightCode, browser/handleDialog, aikit/*]
-model: GPT-5.4 (copilot)
+model: [GPT-5.4 (copilot), Gemini 3.1 Pro (Preview) (copilot), Auto (copilot)]
 ---
 
 # Documenter - The Knowledge Keeper
@@ -49,9 +49,17 @@ You are the **Documenter**, documentation specialist that creates and maintains
 
 | Skill | When to load |
 |-------|--------------|
+| `present` | When presenting documentation previews, API tables, or architecture visuals to the user |
 | `c4-architecture` | When documenting system architecture — generate C4 Mermaid diagrams |
 | `adr-skill` | When documenting architecture decisions — create or update ADRs |
 | `typescript` | When documenting TypeScript APIs — type signatures, JSDoc patterns |
+## Skills (load on demand)
+
+| Skill | When to load |
+|-------|--------------|
+| aikit | **Always** — AI Kit tool signatures, search, analysis |
+| present | When presenting documentation previews or architecture visuals to the user |
+
 
 ## Flows
 

package/scaffold/general/agents/Explorer.agent.md

@@ -2,7 +2,7 @@
 description: 'Rapid codebase exploration to find files, usages, dependencies, and structural context'
 argument-hint: Find files, usages, and context related to: {topic or goal}
 tools: [read/problems, read/readFile, search/changes, search/codebase, search/usages, search/fileSearch, search/listDirectory, search/textSearch, browser/openBrowserPage, browser/readPage, browser/screenshotPage, browser/navigatePage, browser/clickElement, browser/dragElement, browser/hoverElement, browser/typeInPage, browser/runPlaywrightCode, browser/handleDialog, aikit/*]
-model: Gemini 3 Flash (Preview) (copilot)
+model: [Gemini 3 Flash (Preview) (copilot), Claude Haiku 4.5 (copilot), Auto (copilot)]
 ---
 
 # Explorer - The Rapid Scout

package/scaffold/general/agents/Frontend.agent.md

@@ -2,7 +2,7 @@
 description: 'UI/UX specialist for React, styling, responsive design, and frontend implementation'
 argument-hint: UI component, styling task, or frontend feature
 tools: [execute/createAndRunTask, execute/runInTerminal, read/problems, read/readFile, read/terminalLastCommand, agent/runSubagent, edit/createFile, edit/editFiles, edit/rename, edit/createDirectory, search/changes, search/codebase, search/usages, todo, browser/openBrowserPage, browser/readPage, browser/screenshotPage, browser/navigatePage, browser/clickElement, browser/dragElement, browser/hoverElement, browser/typeInPage, browser/runPlaywrightCode, browser/handleDialog, aikit/*]
-model: Gemini 3.1 Pro (Preview) (copilot)
+model: [Gemini 3.1 Pro (Preview) (copilot), GPT-5.4 (copilot), GPT-5.3-Codex (copilot), Auto (copilot)]
 ---
 
 # Frontend - The UI Specialist

package/scaffold/general/agents/Implementer.agent.md

@@ -2,7 +2,7 @@
 description: 'Persistent implementation agent that writes code following TDD practices until all tasks are complete'
 argument-hint: Implementation task, feature, or phase from plan
 tools: [execute/createAndRunTask, execute/runInTerminal, read/problems, read/readFile, read/terminalLastCommand, agent/runSubagent, edit/createFile, edit/editFiles, edit/rename, edit/createDirectory, search/changes, search/codebase, search/usages, todo, browser/openBrowserPage, browser/readPage, browser/screenshotPage, browser/navigatePage, browser/clickElement, browser/dragElement, browser/hoverElement, browser/typeInPage, browser/runPlaywrightCode, browser/handleDialog, aikit/*]
-model: GPT-5.4 (copilot)
+model: [GPT-5.4 (copilot), Gemini 3.1 Pro (Preview) (copilot), GPT-5.3-Codex (copilot), Auto (copilot)]
 ---
 
 # Implementer - The Code Builder

package/scaffold/general/agents/Orchestrator.agent.md

@@ -1,7 +1,7 @@
 ---
 description: 'Master conductor that orchestrates the full development lifecycle: Planning → Implementation → Review → Recovery → Commit'
 tools: [vscode/memory, vscode/runCommand, vscode/switchAgent, execute/killTerminal, execute/createAndRunTask, execute/runInTerminal, read/terminalSelection, read/terminalLastCommand, read/problems, read/readFile, agent/runSubagent, edit/createFile, edit/editFiles, edit/rename, edit/createDirectory, search/changes, search/codebase, search/usages, web/fetch, web/githubRepo, todo, search/searchSubagent, search/textSearch, browser/openBrowserPage, browser/readPage, browser/screenshotPage, browser/navigatePage, browser/clickElement, browser/dragElement, browser/hoverElement, browser/typeInPage, browser/runPlaywrightCode, browser/handleDialog, vscode/askQuestions, vscode/resolveMemoryFileUri, aikit/*]
-model: Claude Opus 4.6 (copilot)
+model: [Claude Opus 4.6 (copilot), GPT-5.4 (copilot), Auto (copilot)]
 ---
 
 # Orchestrator - The Master Conductor
@@ -21,23 +21,23 @@ You orchestrate the full development lifecycle: **planning → implementation
 
 | Agent | Purpose | Model | Category |
 |-------|---------|-------|----------|
-| **Orchestrator** | Master conductor that orchestrates the full development lifecycle: Planning → Implementation → Review → Recovery → Commit | Claude Opus 4.6 | orchestration |
-| **Planner** | Autonomous planner that researches codebases and writes comprehensive TDD implementation plans | Claude Opus 4.6 | orchestration |
-| **Implementer** | Persistent implementation agent that writes code following TDD practices until all tasks are complete | GPT-5.4 | implementation |
-| **Frontend** | UI/UX specialist for React, styling, responsive design, and frontend implementation | Gemini 3.1 Pro (Preview) | implementation |
-| **Refactor** | Code refactoring specialist that improves structure, readability, and maintainability | GPT-5.4 | implementation |
-| **Debugger** | Expert debugger that diagnoses issues, traces errors, and provides solutions | Claude Opus 4.6 | diagnostics |
-| **Security** | Security specialist that analyzes code for vulnerabilities and compliance | Claude Opus 4.6 | diagnostics |
-| **Documenter** | Documentation specialist that creates and maintains comprehensive project documentation | GPT-5.4 | documentation |
-| **Explorer** | Rapid codebase exploration to find files, usages, dependencies, and structural context | Gemini 3 Flash (Preview) | exploration |
-| **Researcher-Alpha** | Primary deep research agent — also serves as default Researcher | Claude Opus 4.6 | research |
-| **Researcher-Beta** | Research variant — pragmatic analysis with focus on trade-offs and edge cases | Claude Sonnet 4.6 | research |
-| **Researcher-Gamma** | Research variant — broad pattern matching across domains and technologies | GPT-5.4 | research |
-| **Researcher-Delta** | Research variant — implementation feasibility and performance implications | Gemini 3.1 Pro (Preview) | research |
-| **Code-Reviewer-Alpha** | Primary code reviewer | GPT-5.4 | review |
-| **Code-Reviewer-Beta** | Code reviewer variant — different LLM perspective for dual review | Claude Opus 4.6 | review |
-| **Architect-Reviewer-Alpha** | Primary architecture reviewer | GPT-5.4 | review |
-| **Architect-Reviewer-Beta** | Architecture reviewer variant — different LLM perspective for dual review | Claude Opus 4.6 | review |
+| **Orchestrator** | Master conductor that orchestrates the full development lifecycle: Planning → Implementation → Review → Recovery → Commit | Claude Opus 4.6 (copilot) | orchestration |
+| **Planner** | Autonomous planner that researches codebases and writes comprehensive TDD implementation plans | Claude Opus 4.6 (copilot) | orchestration |
+| **Implementer** | Persistent implementation agent that writes code following TDD practices until all tasks are complete | GPT-5.4 (copilot) | implementation |
+| **Frontend** | UI/UX specialist for React, styling, responsive design, and frontend implementation | Gemini 3.1 Pro (Preview) (copilot) | implementation |
+| **Refactor** | Code refactoring specialist that improves structure, readability, and maintainability | GPT-5.4 (copilot) | implementation |
+| **Debugger** | Expert debugger that diagnoses issues, traces errors, and provides solutions | Claude Opus 4.6 (copilot) | diagnostics |
+| **Security** | Security specialist that analyzes code for vulnerabilities and compliance | Claude Opus 4.6 (copilot) | diagnostics |
+| **Documenter** | Documentation specialist that creates and maintains comprehensive project documentation | GPT-5.4 (copilot) | documentation |
+| **Explorer** | Rapid codebase exploration to find files, usages, dependencies, and structural context | Gemini 3 Flash (Preview) (copilot) | exploration |
+| **Researcher-Alpha** | Primary deep research agent — also serves as default Researcher | Claude Opus 4.6 (copilot) | research |
+| **Researcher-Beta** | Research variant — pragmatic analysis with focus on trade-offs and edge cases | Claude Sonnet 4.6 (copilot) | research |
+| **Researcher-Gamma** | Research variant — broad pattern matching across domains and technologies | GPT-5.4 (copilot) | research |
+| **Researcher-Delta** | Research variant — implementation feasibility and performance implications | Gemini 3.1 Pro (Preview) (copilot) | research |
+| **Code-Reviewer-Alpha** | Primary code reviewer | GPT-5.4 (copilot) | review |
+| **Code-Reviewer-Beta** | Code reviewer variant — different LLM perspective for dual review | Claude Opus 4.6 (copilot) | review |
+| **Architect-Reviewer-Alpha** | Primary architecture reviewer | GPT-5.4 (copilot) | review |
+| **Architect-Reviewer-Beta** | Architecture reviewer variant — different LLM perspective for dual review | Claude Opus 4.6 (copilot) | review |
 
 **Parallelism**: Read-only agents run in parallel freely. File-modifying agents run in parallel ONLY on completely different files. Max 4 concurrent file-modifying agents.
 
@@ -57,26 +57,43 @@ You orchestrate the full development lifecycle: **planning → implementation
 3. After review: `evidence_map({ action: "gate", task_id })` → YIELD/HOLD/HARD_BLOCK
 4. Auto-upgrade tier if unknowns reveal contract/security issues
 
-## Workflow
+## Flow-Driven Development
 
-### Phase 1: Planning
-1. Read onboard artifacts → parse goal → identify affected subsystems → `forge_classify`
-2. Research: <5 files direct, 5-15 Explorer→Researcher, >15 multiple parallel
-3. Draft plan: 3-10 phases, agent assignments, TDD steps, dependency graph
-4. Batch independent phases for parallel execution
-5. **🛑 STOP — user approval required**
+Orchestrator uses the flow system for structured development. Flows define the step sequence — Orchestrator adds multi-agent orchestration, quality gates, and review protocols on top.
 
-### Phase 2: Implementation Cycle
+### Flow Selection
 
-**🚨 PRE-DISPATCH GATE — complete ALL before ANY `runSubagent` call:**
+| Situation | Flow | Steps |
+|-----------|------|-------|
+| Bug fix, small feature, refactoring | `aikit:basic` | assess → implement → verify |
+| New feature, major change, multi-file | `aikit:advanced` | spec → plan → task → execute → verify |
+| Custom/specialized work | Check `flow_list` | Follow flow-specific steps |
 
-1. ✅ `multi-agents-development` skill loaded? (Bootstrap step 4 — if not, load NOW)
-2. ✅ Task decomposition table produced? (show user: task → files → agent → parallel batch)
-3. ✅ Independence Check passed per pair? (shared files? shared state? ordering dependency? → must be "No" for parallel)
-4. ✅ Each task ≤ 3 files? (if not, split further)
-5. ✅ Parallel batches identified? (tasks with no dependencies MUST be in same batch)
+**If multiple flows could apply and user hasn't specified → ask user to choose.**
 
-**Decomposition output format** (show this to user before dispatching):
+### Session Start Flow Check
+
+1. `flow_status` — check for active flow
+2. If active:
+   - Note current step name and skill path
+   - Read the current step skill with `flow_read_skill`
+   - Follow its instructions
+   - When complete: `flow_step({ action: 'next' })`
+3. If no active flow:
+   - `flow_list` — check ALL available flows (builtin + custom)
+   - Recommend appropriate flow based on task scope
+   - `flow_start({ flow: '<name>' })` after user confirms
+
+### Orchestrator Protocols (apply during ALL flow steps)
+
+**PRE-DISPATCH GATE — complete ALL before ANY `runSubagent` call:**
+1. ✅ `multi-agents-development` skill loaded?
+2. ✅ Task decomposition table produced?
+3. ✅ Independence Check passed per pair?
+4. ✅ Each task ≤ 3 files?
+5. ✅ Parallel batches identified?
+
+**Decomposition output format:**
 
 ```
 Batch 1 (parallel):
@@ -86,23 +103,35 @@ Batch 2 (after batch 1):
    Task C: [agent] → [file5] — [goal] (depends on A)
 ```
 
-**Prompt every subagent with** (use `multi-agents-development` skill templates):
-1. **Scope** — exact files to touch + boundary (do NOT touch)
+**Subagent prompt template:**
+1. **Scope** — exact files + boundary
 2. **Goal** — acceptance criteria, testable
-3. **Arch Context** — paste actual code snippets from `compact()`/`digest()`
-4. **Constraints** — patterns, conventions, anti-patterns
+3. **Arch Context** — code snippets from `compact()`/`digest()`
+4. **Constraints** — patterns, conventions
 5. **FORGE** — tier + evidence requirements
 6. **Self-Review** — checklist before declaring status
 
-**Subagent status protocol**: `DONE` | `DONE_WITH_CONCERNS` | `NEEDS_CONTEXT` | `BLOCKED`
+**Subagent status protocol:** `DONE` | `DONE_WITH_CONCERNS` | `NEEDS_CONTEXT` | `BLOCKED`
+
+**Additional Orchestrator requirements during flow execution:**
+- Apply the PRE-DISPATCH GATE before any subagent dispatch, regardless of flow
+- Apply FORGE at classification and verification points; pass tier/evidence expectations into subagents and gate with `evidence_map`
+- Enforce delegation rules at all times — Orchestrator never implements code directly
+- Use the subagent prompt template for every dispatch so step-specific flow instructions are grounded in actual code context
 
-**Per-batch flow**: Dispatch (parallel) → Spec Review → Code Quality Review (Alpha+Beta parallel) → Arch Review (if boundary changes) → Security (if applicable) → `evidence_map` gate → **🛑 STOP — present commit message**
+**Per-step review cycle:** Dispatch → Code Review (Alpha+Beta) → Arch Review (if boundary changes) → Security (if applicable) → `evidence_map` gate → **🛑 STOP — present results**
+
+### Flow MCP Tools
 
-### Phase 3: Completion
-1. Optional: Refactor pass (separate commit)
-2. Documenter for docs updates
-3. `remember` all decisions, patterns, gotchas, conventions
-4. `reindex({})` + `produce_knowledge({ path: "." })`
+| Tool | Purpose |
+|------|---------|
+| `flow_list` | List installed flows and active flow |
+| `flow_info` | Get detailed flow info including steps |
+| `flow_start` | Start a named flow |
+| `flow_step` | Advance: next, skip, or redo current step |
+| `flow_status` | Check current execution state |
+| `flow_reset` | Clear flow state to start over |
+| `flow_read_skill` | Read the skill content for the current step |
 
 ## Emergency: STOP → ASSESS → CONTAIN → RECOVER → DOCUMENT
 
@@ -184,6 +213,7 @@ Before every tool call, verify:
 | Skill | When to load |
 |-------|--------------|
 | `multi-agents-development` | **Before any delegation** — task decomposition, dispatch templates, review pipeline, recovery patterns |
+| `present` | When presenting plans, findings, or visual content to the user — dashboards, tables, charts, timelines |
 | `brainstorming` | Before creative/design work (Phase 0) |
 | `session-handoff` | Context filling up, session ending, or major milestone |
 | `lesson-learned` | After completing work — extract engineering principles |

package/scaffold/general/agents/Planner.agent.md

@@ -1,7 +1,7 @@
 ---
 description: 'Autonomous planner that researches codebases and writes comprehensive TDD implementation plans'
 tools: [execute/runInTerminal, read/problems, read/readFile, read/terminalLastCommand, agent/runSubagent, edit/createFile, edit/editFiles, edit/rename, edit/createDirectory, search/changes, search/codebase, search/usages, web/fetch, web/githubRepo, todo, search/searchSubagent, browser/openBrowserPage, browser/readPage, browser/screenshotPage, browser/navigatePage, browser/clickElement, browser/dragElement, browser/hoverElement, browser/typeInPage, browser/runPlaywrightCode, browser/handleDialog, aikit/*]
-model: Claude Opus 4.6 (copilot)
+model: [Claude Opus 4.6 (copilot), GPT-5.4 (copilot), Auto (copilot)]
 ---
 
 # Planner - The Strategic Architect
@@ -38,6 +38,17 @@ You are the **Planner**, autonomous planner that researches codebases and writes
 5. **Dependency Graph** — For each phase, list dependencies. Group into parallel batches
 6. **Present** — Show plan with open questions, complexity estimate, parallel batch layout
 
+## Flow Integration
+
+When activated as part of a flow (e.g., `aikit:advanced` plan step or `aikit:basic` assess step):
+1. Check `flow_status` for current step context
+2. Read the step's skill file for specific instructions
+3. Follow skill instructions while applying Planner methodology
+4. Produce required artifacts (as specified by the flow step's `produces` field)
+5. When complete, report to Orchestrator (do NOT call `flow_step` — let Orchestrator advance)
+
+When no flow is active, operate autonomously following normal Planner methodology.
+
 ## Subagent Output Relay
 
 When subagents complete, their visual outputs (from `present`) are NOT visible to the user.
@@ -87,6 +98,7 @@ When subagents complete, their visual outputs (from `present`) are NOT visible t
 | Skill | When to load |
 |-------|--------------|
 | `brainstorming` | Before planning any new feature, component, or behavior change — use Visual Companion for architecture mockups |
+| `present` | When presenting plans, dependency graphs, or complexity estimates to the user |
 | `requirements-clarity` | When requirements are vague or complex (>2 days) — score 0-100 before committing to a plan |
 | `c4-architecture` | When the plan involves architectural changes — generate C4 diagrams |
 | `adr-skill` | When the plan involves non-trivial technical decisions — create executable ADRs |

package/scaffold/general/agents/README.md

@@ -6,23 +6,23 @@ This directory contains AI agent definitions generated by `@vpxa/aikit init`.
 
 | Agent | Purpose | Model | Category |
 |-------|---------|-------|----------|
-| **Orchestrator** | Master conductor that orchestrates the full development lifecycle: Planning → Implementation → Review → Recovery → Commit | Claude Opus 4.6 | orchestration |
-| **Planner** | Autonomous planner that researches codebases and writes comprehensive TDD implementation plans | Claude Opus 4.6 | orchestration |
-| **Implementer** | Persistent implementation agent that writes code following TDD practices until all tasks are complete | GPT-5.4 | implementation |
-| **Frontend** | UI/UX specialist for React, styling, responsive design, and frontend implementation | Gemini 3.1 Pro (Preview) | implementation |
-| **Refactor** | Code refactoring specialist that improves structure, readability, and maintainability | GPT-5.4 | implementation |
-| **Debugger** | Expert debugger that diagnoses issues, traces errors, and provides solutions | Claude Opus 4.6 | diagnostics |
-| **Security** | Security specialist that analyzes code for vulnerabilities and compliance | Claude Opus 4.6 | diagnostics |
-| **Documenter** | Documentation specialist that creates and maintains comprehensive project documentation | GPT-5.4 | documentation |
-| **Explorer** | Rapid codebase exploration to find files, usages, dependencies, and structural context | Gemini 3 Flash (Preview) | exploration |
-| **Researcher-Alpha** | Primary deep research agent — also serves as default Researcher | Claude Opus 4.6 | research |
-| **Researcher-Beta** | Research variant — pragmatic analysis with focus on trade-offs and edge cases | Claude Sonnet 4.6 | research |
-| **Researcher-Gamma** | Research variant — broad pattern matching across domains and technologies | GPT-5.4 | research |
-| **Researcher-Delta** | Research variant — implementation feasibility and performance implications | Gemini 3.1 Pro (Preview) | research |
-| **Code-Reviewer-Alpha** | Primary code reviewer | GPT-5.4 | review |
-| **Code-Reviewer-Beta** | Code reviewer variant — different LLM perspective for dual review | Claude Opus 4.6 | review |
-| **Architect-Reviewer-Alpha** | Primary architecture reviewer | GPT-5.4 | review |
-| **Architect-Reviewer-Beta** | Architecture reviewer variant — different LLM perspective for dual review | Claude Opus 4.6 | review |
+| **Orchestrator** | Master conductor that orchestrates the full development lifecycle: Planning → Implementation → Review → Recovery → Commit | Claude Opus 4.6 (copilot) | orchestration |
+| **Planner** | Autonomous planner that researches codebases and writes comprehensive TDD implementation plans | Claude Opus 4.6 (copilot) | orchestration |
+| **Implementer** | Persistent implementation agent that writes code following TDD practices until all tasks are complete | GPT-5.4 (copilot) | implementation |
+| **Frontend** | UI/UX specialist for React, styling, responsive design, and frontend implementation | Gemini 3.1 Pro (Preview) (copilot) | implementation |
+| **Refactor** | Code refactoring specialist that improves structure, readability, and maintainability | GPT-5.4 (copilot) | implementation |
+| **Debugger** | Expert debugger that diagnoses issues, traces errors, and provides solutions | Claude Opus 4.6 (copilot) | diagnostics |
+| **Security** | Security specialist that analyzes code for vulnerabilities and compliance | Claude Opus 4.6 (copilot) | diagnostics |
+| **Documenter** | Documentation specialist that creates and maintains comprehensive project documentation | GPT-5.4 (copilot) | documentation |
+| **Explorer** | Rapid codebase exploration to find files, usages, dependencies, and structural context | Gemini 3 Flash (Preview) (copilot) | exploration |
+| **Researcher-Alpha** | Primary deep research agent — also serves as default Researcher | Claude Opus 4.6 (copilot) | research |
+| **Researcher-Beta** | Research variant — pragmatic analysis with focus on trade-offs and edge cases | Claude Sonnet 4.6 (copilot) | research |
+| **Researcher-Gamma** | Research variant — broad pattern matching across domains and technologies | GPT-5.4 (copilot) | research |
+| **Researcher-Delta** | Research variant — implementation feasibility and performance implications | Gemini 3.1 Pro (Preview) (copilot) | research |
+| **Code-Reviewer-Alpha** | Primary code reviewer | GPT-5.4 (copilot) | review |
+| **Code-Reviewer-Beta** | Code reviewer variant — different LLM perspective for dual review | Claude Opus 4.6 (copilot) | review |
+| **Architect-Reviewer-Alpha** | Primary architecture reviewer | GPT-5.4 (copilot) | review |
+| **Architect-Reviewer-Beta** | Architecture reviewer variant — different LLM perspective for dual review | Claude Opus 4.6 (copilot) | review |
 
 ## Multi-Model Pattern
 

package/scaffold/general/agents/Refactor.agent.md

@@ -2,7 +2,7 @@
 description: 'Code refactoring specialist that improves structure, readability, and maintainability'
 argument-hint: Code, component, or pattern to refactor
 tools: [execute/runInTerminal, read/problems, read/readFile, read/terminalLastCommand, agent/runSubagent, edit/createFile, edit/editFiles, edit/rename, edit/createDirectory, search/changes, search/codebase, search/usages, browser/openBrowserPage, browser/readPage, browser/screenshotPage, browser/navigatePage, browser/clickElement, browser/dragElement, browser/hoverElement, browser/typeInPage, browser/runPlaywrightCode, browser/handleDialog, aikit/*]
-model: GPT-5.4 (copilot)
+model: [GPT-5.4 (copilot), GPT-5.3-Codex (copilot), Auto (copilot)]
 ---
 
 # Refactor - The Code Sculptor
@@ -35,6 +35,12 @@ You are the **Refactor**, code refactoring specialist that improves structure, r
 |-------|--------------|
 | `lesson-learned` | After completing a refactor — extract principles from the before/after diff |
 | `typescript` | When refactoring TypeScript code — type patterns, generics, utility types |
+## Skills (load on demand)
+
+| Skill | When to load |
+|-------|--------------|
+| aikit | **Always** — AI Kit tool signatures, search, analysis |
+
 
 ## Flows
 

package/scaffold/general/agents/Researcher-Alpha.agent.md

@@ -2,7 +2,7 @@
 description: 'Primary deep research agent — also serves as default Researcher'
 argument-hint: Research question, problem statement, or subsystem to investigate
 tools: [execute/runInTerminal, read/problems, read/readFile, read/terminalLastCommand, agent/runSubagent, search/changes, search/codebase, search/usages, web/fetch, web/githubRepo, browser/openBrowserPage, browser/readPage, browser/screenshotPage, browser/navigatePage, browser/clickElement, browser/dragElement, browser/hoverElement, browser/typeInPage, browser/runPlaywrightCode, browser/handleDialog, aikit/*]
-model: Claude Opus 4.6 (copilot)
+model: [Claude Opus 4.6 (copilot), Auto (copilot)]
 ---
 
 # Researcher-Alpha - The Context Gatherer
@@ -15,9 +15,10 @@ You are **Researcher-Alpha**, the primary deep research agent. During multi-mode
 
 | Skill | When to load |
 |-------|--------------|
-| `lesson-learned` | When analyzing past changes to extract engineering principles |
-| `c4-architecture` | When researching system architecture — produce C4 diagrams |
-| `adr-skill` | When the research involves a technical decision — draft an ADR |
+| aikit | **Always** — AI Kit tool signatures, search, analysis |
+| lesson-learned | When analyzing past changes to extract engineering principles |
+| c4-architecture | When researching system architecture — produce C4 diagrams |
+| adr-skill | When the research involves a technical decision — draft an ADR |
 
 ## Flows
 

package/scaffold/general/agents/Researcher-Beta.agent.md

@@ -2,7 +2,7 @@
 description: 'Research variant — pragmatic analysis with focus on trade-offs and edge cases'
 argument-hint: Research question, problem statement, or subsystem to investigate
 tools: [execute/runInTerminal, read/problems, read/readFile, read/terminalLastCommand, agent/runSubagent, search/changes, search/codebase, search/usages, web/fetch, web/githubRepo, browser/openBrowserPage, browser/readPage, browser/screenshotPage, browser/navigatePage, browser/clickElement, browser/dragElement, browser/hoverElement, browser/typeInPage, browser/runPlaywrightCode, browser/handleDialog, aikit/*]
-model: Claude Sonnet 4.6 (copilot)
+model: [Claude Sonnet 4.6 (copilot), Auto (copilot)]
 ---
 
 # Researcher-Beta - The Context Gatherer
@@ -15,9 +15,10 @@ You are **Researcher-Beta**, a variant of the Researcher agent optimized for **p
 
 | Skill | When to load |
 |-------|--------------|
-| `lesson-learned` | When analyzing past changes to extract engineering principles |
-| `c4-architecture` | When researching system architecture — produce C4 diagrams |
-| `adr-skill` | When the research involves a technical decision — draft an ADR |
+| aikit | **Always** — AI Kit tool signatures, search, analysis |
+| lesson-learned | When analyzing past changes to extract engineering principles |
+| c4-architecture | When researching system architecture — produce C4 diagrams |
+| adr-skill | When the research involves a technical decision — draft an ADR |
 
 ## Flows
 

package/scaffold/general/agents/Researcher-Delta.agent.md

@@ -2,7 +2,7 @@
 description: 'Research variant — implementation feasibility and performance implications'
 argument-hint: Research question, problem statement, or subsystem to investigate
 tools: [execute/runInTerminal, read/problems, read/readFile, read/terminalLastCommand, agent/runSubagent, search/changes, search/codebase, search/usages, web/fetch, web/githubRepo, browser/openBrowserPage, browser/readPage, browser/screenshotPage, browser/navigatePage, browser/clickElement, browser/dragElement, browser/hoverElement, browser/typeInPage, browser/runPlaywrightCode, browser/handleDialog, aikit/*]
-model: Gemini 3.1 Pro (Preview) (copilot)
+model: [Gemini 3.1 Pro (Preview) (copilot), Auto (copilot)]
 ---
 
 # Researcher-Delta - The Context Gatherer
@@ -15,9 +15,10 @@ You are **Researcher-Delta**, a variant of the Researcher agent optimized for **
 
 | Skill | When to load |
 |-------|--------------|
-| `lesson-learned` | When analyzing past changes to extract engineering principles |
-| `c4-architecture` | When researching system architecture — produce C4 diagrams |
-| `adr-skill` | When the research involves a technical decision — draft an ADR |
+| aikit | **Always** — AI Kit tool signatures, search, analysis |
+| lesson-learned | When analyzing past changes to extract engineering principles |
+| c4-architecture | When researching system architecture — produce C4 diagrams |
+| adr-skill | When the research involves a technical decision — draft an ADR |
 
 ## Flows
 

package/scaffold/general/agents/Researcher-Gamma.agent.md

@@ -2,7 +2,7 @@
 description: 'Research variant — broad pattern matching across domains and technologies'
 argument-hint: Research question, problem statement, or subsystem to investigate
 tools: [execute/runInTerminal, read/problems, read/readFile, read/terminalLastCommand, agent/runSubagent, search/changes, search/codebase, search/usages, web/fetch, web/githubRepo, browser/openBrowserPage, browser/readPage, browser/screenshotPage, browser/navigatePage, browser/clickElement, browser/dragElement, browser/hoverElement, browser/typeInPage, browser/runPlaywrightCode, browser/handleDialog, aikit/*]
-model: GPT-5.4 (copilot)
+model: [GPT-5.4 (copilot), Auto (copilot)]
 ---
 
 # Researcher-Gamma - The Context Gatherer
@@ -15,9 +15,10 @@ You are **Researcher-Gamma**, a variant of the Researcher agent optimized for **
 
 | Skill | When to load |
 |-------|--------------|
-| `lesson-learned` | When analyzing past changes to extract engineering principles |
-| `c4-architecture` | When researching system architecture — produce C4 diagrams |
-| `adr-skill` | When the research involves a technical decision — draft an ADR |
+| aikit | **Always** — AI Kit tool signatures, search, analysis |
+| lesson-learned | When analyzing past changes to extract engineering principles |
+| c4-architecture | When researching system architecture — produce C4 diagrams |
+| adr-skill | When the research involves a technical decision — draft an ADR |
 
 ## Flows
 

package/scaffold/general/agents/Security.agent.md

@@ -2,7 +2,7 @@
 description: 'Security specialist that analyzes code for vulnerabilities and compliance'
 argument-hint: Code, feature, or component to security review
 tools: [execute/runInTerminal, read/problems, read/readFile, agent/runSubagent, search/changes, search/codebase, search/usages, web/fetch, web/githubRepo, browser/openBrowserPage, browser/readPage, browser/screenshotPage, browser/navigatePage, browser/clickElement, browser/dragElement, browser/hoverElement, browser/typeInPage, browser/runPlaywrightCode, browser/handleDialog, aikit/*]
-model: Claude Opus 4.6 (copilot)
+model: [Claude Opus 4.6 (copilot), GPT-5.4 (copilot), Auto (copilot)]
 ---
 
 # Security - The Vulnerability Hunter

package/scaffold/general/agents/_shared/code-agent-base.md

@@ -83,9 +83,11 @@ Your agent file lists domain-specific skills in the **Skills** section. Load the
 
 1. Check if the current task matches a listed skill trigger
 2. If yes → load the skill file before starting implementation
-3. The `aikit` skill is **always loaded** — do not re-load it
+3. The following skills are **foundational** — always loaded, do not re-load:
+   - **`aikit`** — AI Kit MCP tool reference, search strategies, compression workflows, session protocol. **Required for all tool usage.**
+   - **`present`** — Rich content rendering (dashboards, tables, charts, timelines). **Required when producing visual output for the user.**
 
-> If no skills are listed for your agent, rely on AI Kit tools and onboard artifacts.
+> If no additional skills are listed for your agent, rely on AI Kit tools and onboard artifacts.
 
 ---
 
@@ -127,12 +129,32 @@ list()                     // see all stored knowledge entries
 | `symbol({ name })` | Find symbol definition + references |
 | `trace({ symbol, direction })` | Follow call graph forward/backward |
 | `compact({ path, query })` | Read specific section of a file |
-| `read_file` | **Only** when you need exact lines for editing |
+| `read_file` | **ONLY** when you need exact lines for a pending edit |
 
 ### Step 4: Tool Discovery
 
 If unsure which AI Kit tool to use → run `guide({ topic: "what you need" })` for recommendations.
 
+---
+
+## PROHIBITED: Native File Reading Tools
+
+**`read_file` / `read_file_raw` MUST NOT be used to understand code.** They waste tokens and miss structural information that AI Kit tools provide.
+
+| ❌ NEVER do this | ✅ Do this instead | Why |
+|---|---|---|
+| `read_file` to understand a file | `file_summary({ path })` | Structure, exports, imports, call edges — **10x fewer tokens** |
+| `read_file` to find specific code | `compact({ path, query })` | Server-side read + semantic extract — **5-20x reduction** |
+| Multiple `read_file` calls | `digest({ sources })` | Compresses multiple files into token-budgeted summary |
+| `grep_search` / `textSearch` | `search({ query })` | Hybrid search across all indexed + curated content |
+| `grep_search` for a symbol | `symbol({ name })` | Definition + references with scope context |
+| Manual code tracing | `trace({ start, direction })` | AST call-graph traversal |
+| Line counting / `wc` | `measure({ path })` | Lines, functions, cognitive complexity |
+| `fetch_webpage` | `web_fetch({ urls })` | Readability extract + token budget |
+| Web research / browsing | `web_search({ queries })` | Structured web results without browser |
+
+**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.
+
 ## FORGE Protocol (Quality Gate)
 
 **Quick reference:**
@@ -231,10 +253,11 @@ For outdated AI Kit entries → `update(path, content, reason)`
 
 ## Context Efficiency
 
-Minimize token usage by choosing the right compression tool:
-- **`compact({ path, query })`** — Extract relevant sections from a single file (5-20x token reduction vs full read)
+**NEVER use `read_file` to understand code.** 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
-- **`stratum_card({ path })`** — Generate a reusable T1/T2 context card for files you'll reference repeatedly
+- **`stratum_card({ files, query })`** — Generate a reusable T1/T2 context card for files you'll reference repeatedly
 
 **Session phases** — structure your work to minimize context bloat:
 

package/scaffold/general/agents/_shared/researcher-base.md

@@ -94,8 +94,10 @@ When invoked for a decision analysis, you receive a specific question. You MUST:
 
 ## Context Efficiency
 
-- **Prefer `file_summary` over `read_file`** for understanding structure
-- **Prefer `compact` over full reads** when you need specific sections
-- **Use `digest`** when synthesizing from 3+ sources
-- **Use `stratum_card`** for files you'll reference repeatedly
+- **NEVER use `read_file` to understand code** — use AI Kit compression tools instead
+- **`file_summary`** for structure (exports, imports, call edges — 10x fewer tokens)
+- **`compact`** for specific sections (5-20x token reduction vs read_file)
+- **`digest`** when synthesizing from 3+ sources
+- **`stratum_card`** for files you'll reference repeatedly
+- **`read_file` is ONLY acceptable** when you need exact lines for a pending edit operation
 

package/scaffold/general/skills/aikit/SKILL.md

@@ -278,12 +278,18 @@ install: []
 
 ## CRITICAL: Use AI Kit Tools Instead of Native IDE Tools
 
-AI Kit tools provide **10x richer output** than native IDE tools — with AST-analyzed call graphs, scope context, import classification, and cognitive complexity. **Always prefer AI Kit tools.**
+AI Kit tools provide **10x richer output** than native IDE tools — with AST-analyzed call graphs, scope context, import classification, and cognitive complexity. **You MUST use AI Kit tools instead of native read/search tools.**
+
+### ⛔ PROHIBITED: Native File Reading
+
+**`read_file` / `read_file_raw` MUST NOT be used to understand code.** They waste tokens and miss structural information.
+
+The **ONLY** acceptable use of `read_file`: getting exact lines immediately before an edit (to verify the `old_str` for replacement). Even then, use `file_summary` first to identify which lines to read.
 
 ### Tool Replacement Table
 
-| Instead of... | Use AI Kit Tool | Why |
-|---------------|-------------|-----|
+| ❌ NEVER do this | ✅ Use AI Kit Tool | Why |
+|---|---|---|
 | `read_file` (full file) | `file_summary` | Exports, imports, call edges — **10x fewer tokens** |
 | `read_file` (specific section) | `compact({ path, query })` | Server-side read + extract — **5-20x reduction** |
 | `grep_search` / `textSearch` | `search` | Semantic + keyword hybrid across all indexed content |
@@ -301,11 +307,12 @@ AI Kit tools provide **10x richer output** than native IDE tools — with AST-an
 
 ```
 Need to understand a file?
-├─ Just structure? → file_summary (exports, imports, call edges — ~50 tokens)
-├─ Specific section? → compact({ path: "file.ts", query: "topic" }) — 5-20x reduction
-├─ Multiple files? → digest (multi-source compression — token-budgeted)
-├─ Repeated reference? → stratum_card (T1/T2 card — 10-100x reduction)
-└─ Full file needed? → ONLY as last resort, and compact it after reading
+├─ Just structure?        → file_summary (exports, imports, call edges — ~50 tokens)
+├─ Specific section?      → compact({ path, query }) — 5-20x reduction
+├─ Multiple files?        → digest (multi-source compression — token-budgeted)
+├─ Repeated reference?    → stratum_card (T1/T2 card — 10-100x reduction)
+├─ Need exact lines to EDIT? → read_file (the ONLY acceptable use)
+└─ "I want to read the whole file" → ⛔ STOP. Use file_summary or compact instead.
 ```
 
 ### What AI Kit Tools Return (AST-Enhanced)