@vpxa/aikit 0.1.17 → 0.1.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vpxa/aikit",
-  "version": "0.1.17",
+  "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/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/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
 
@@ -228,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.

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/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

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

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

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
 

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.

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

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

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

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

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

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