@ikarmic/forge-core 5.1.0 → 5.2.0

package/dist/journey/trigger.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Tier 1 of the journey trigger: does this message deserve a read-only Survey?
+ *
+ * It decides whether to *look*, not whether to show a card. A false positive
+ * costs a few auto-approved, token-capped reads; a false positive on the card
+ * is the nagging that kills the feature (spec anti-goal 1). So this is
+ * deliberately generous and the vetoes carry the weight.
+ *
+ * Signals are noun-driven, not verb-driven: a change verb on its own trips on
+ * everything ("add a button"), so it only counts beside a noun that implies
+ * many files.
+ */
+import type { TriggerVerdict } from './types.js';
+/**
+ * `typed` is what the person wrote, `sent` what goes to the model. They differ
+ * when a slash command, skill or `@agent` mention expanded into a long body;
+ * judging that text would offer a journey for a one-line request (RB-16).
+ */
+export declare function shouldSurvey(typed: string, sent: string): TriggerVerdict;

package/dist/journey/trigger.js

@@ -0,0 +1,79 @@
+const BUILD_VERBS = /\b(?:build|create|make|develop|scaffold|set up|generate|write me)\b/i;
+const CHANGE_VERBS = /\b(?:add|extend|integrate|migrate|refactor|support|introduce|replace|rework|wire up|hook up|implement)\b/i;
+const SYSTEM_NOUNS = /\b(?:app|application|system|platform|crm|erp|cms|web ?site|api|backend|frontend|dashboard|portal|saas|marketplace|game)\b/i;
+/** Nouns that imply many files rather than one element. */
+const SCALE_NOUNS = /\b(?:module|subsystem|service|integration|pipeline|workflow|migration|multi-?tenancy|auth|authentication|authorisation|authorization|sso|oauth|billing|payments|notifications|search|reporting|analytics|audit log|admin panel|permissions|rbac|onboarding|checkout)\b/i;
+/** Hard vetoes: the person has already told us the scope is small. */
+const SMALL_VERBS = /\b(?:fix|typo|rename|bump|tweak|format|indent|lint|spelling|revert)\b/i;
+const UI_ATOM = /\b(?:button|label|icon|tooltip|placeholder|colour|color|margin|padding|border|font)\b/i;
+const CROSS_CUTTING = /\b(?:across|everywhere|all our|end-to-end|throughout|every (?:page|screen|endpoint))\b/i;
+const PLURAL_DELIVERABLE = /\b(?:pages|endpoints|models|screens|tables|services|roles|reports)\b/i;
+const REQUIREMENT_INTENT = /\b(?:need|want|should|must|would like|let (?:people|users|them|me))\b/i;
+const LONGISH_WORDS = 25;
+const MIN_LIST_SEPARATORS = 3;
+/** Cap before any regex runs, so a pathological message cannot stall the editor. */
+const MAX_INPUT = 4000;
+/**
+ * Technology names that are shaped exactly like filenames. Without this,
+ * "Build me a Next.js SaaS platform" — close to the canonical phrasing of the
+ * flagship scenario — is vetoed as naming a file and silently gets nothing.
+ */
+const TECH_TOKENS = /\b(?:next|node|nuxt|vue|three|d3|express|react|nest|ember|backbone|socket|chart|moment|day)\.(?:js|io|ts)\b/gi;
+/**
+ * A file path or extension means a scoped change, however big the noun beside it.
+ *
+ * Two narrowings against the version in `vscode/src/chat/large-request.ts`:
+ * technology names are removed first, and the extension must be letters, so a
+ * version number ("the 2.0 release") is not a filename.
+ */
+function namesAFile(text) {
+    const withoutTech = text.replace(TECH_TOKENS, ' ');
+    return /[\\/]|\.[a-z]{1,5}\b/i.test(withoutTech.replace(/[.!?]+(?=\s|$)/g, ''));
+}
+function listSeparators(text) {
+    const commasAndAnds = (text.match(/,|\band\b/gi) ?? []).length;
+    const bullets = (text.match(/^\s*(?:[-*•]|\d+[.)])\s/gm) ?? []).length;
+    return commasAndAnds + bullets;
+}
+/**
+ * `typed` is what the person wrote, `sent` what goes to the model. They differ
+ * when a slash command, skill or `@agent` mention expanded into a long body;
+ * judging that text would offer a journey for a one-line request (RB-16).
+ */
+export function shouldSurvey(typed, sent) {
+    const full = typed.trim();
+    if (!full)
+        return { survey: false, reasons: ['empty'] };
+    if (full !== sent.trim())
+        return { survey: false, reasons: ['expanded command'] };
+    if (/^\/\w/.test(full))
+        return { survey: false, reasons: ['slash command'] };
+    if (/(?:^|\s)@\S/.test(full))
+        return { survey: false, reasons: ['@agent mention'] };
+    const t = full.slice(0, MAX_INPUT);
+    if (namesAFile(t))
+        return { survey: false, reasons: ['veto: names a file or path'] };
+    if (SMALL_VERBS.test(t))
+        return { survey: false, reasons: ['veto: small-change verb'] };
+    const reasons = [];
+    const change = CHANGE_VERBS.test(t);
+    if (BUILD_VERBS.test(t) && SYSTEM_NOUNS.test(t))
+        reasons.push('build verb + system noun');
+    if (change && SCALE_NOUNS.test(t))
+        reasons.push('change verb + scale noun');
+    if (change && SYSTEM_NOUNS.test(t))
+        reasons.push('change verb + system noun');
+    if (CROSS_CUTTING.test(t))
+        reasons.push('cross-cutting scope');
+    if (change && PLURAL_DELIVERABLE.test(t))
+        reasons.push('plural deliverables');
+    if (t.split(/\s+/).length >= LONGISH_WORDS && REQUIREMENT_INTENT.test(t) && listSeparators(t) >= MIN_LIST_SEPARATORS) {
+        reasons.push('long multi-requirement message');
+    }
+    if (reasons.length === 0)
+        return { survey: false, reasons: ['no scope signal'] };
+    // One UI element with a single weak signal is a scoped edit, not a subsystem.
+    if (UI_ATOM.test(t) && reasons.length < 2)
+        return { survey: false, reasons: ['veto: single UI element'] };
+    return { survey: true, reasons };
+}

package/dist/journey/types.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Shared types for the guided journey. Types only, no logic, so every other
+ * file in `journey/` can import this one without a cycle.
+ *
+ * Design: docs/superpowers/specs/2026-10-23-guided-journey-design.md (rev 3)
+ */
+import type { DetectedCheck } from '../verify/detect.js';
+/** Tier-1 verdict: whether a read-only Survey is worth running, and why. */
+export interface TriggerVerdict {
+    survey: boolean;
+    /** Human-readable signals or vetoes; the offer card shows these. */
+    reasons: string[];
+}
+/**
+ * What the Survey read. Every field is absent or empty when it was not read —
+ * never guessed. There is deliberately no greenfield/brownfield flag: a
+ * workspace that is half-scaffolded is neither, and a label would have to lie
+ * about it. `journey-questions.test.ts` forbids that identifier anywhere under
+ * `src/`, prose included, which is why this note spells it out in words.
+ */
+export interface SurveyFacts {
+    manifest?: {
+        path: string;
+        packageManager?: string;
+    };
+    checks: DetectedCheck[];
+    isGitRepo: boolean;
+    hasCommits: boolean;
+    sourceFileCount: number;
+    conventionFiles: string[];
+    relatedSymbols: string[];
+    priorSpecIds: string[];
+}
+/** Tier-2 decision, with the evidence that earns the card. */
+export interface JourneyOffer {
+    offer: boolean;
+    evidence: string[];
+}
+/**
+ * One interview question. `answeredBy` is the precondition: when it returns a
+ * value, the Survey already answered this and the question is never asked.
+ */
+export interface InterviewQuestion {
+    id: string;
+    question: string;
+    options?: string[];
+    multiSelect?: boolean;
+    answeredBy: (facts: SurveyFacts) => string | undefined;
+}
+/** A question the person answered, carried into the system prompt. */
+export interface Answer {
+    id: string;
+    question: string;
+    answer: string;
+}
+export type StageId = 'survey' | 'interview' | 'plan' | 'spec' | 'implPlan' | 'build';
+export interface Stage {
+    id: StageId;
+    /** Survey and Interview are host-driven and run no model at all. */
+    usesModel: boolean;
+    promptSuffix: string;
+    allowTools: readonly string[];
+    artefact: string;
+    gateOptions: readonly string[];
+}
+export interface JourneyState {
+    /** `'done'` once the journey is over, including when a saved stage id is unknown. */
+    current: StageId | 'done';
+    answers: Answer[];
+    /** Index into the approved `tasks.md` during the Build stage. */
+    taskCursor: number;
+}

package/dist/journey/types.js

@@ -0,0 +1 @@
+export {};

package/dist/mcp/json-schema-to-zod.js

@@ -55,7 +55,18 @@ export function jsonSchemaToZod(schema) {
                     const propZod = jsonSchemaToZod(propSchema);
                     shape[key] = required.has(key) ? propZod : propZod.optional();
                 }
-                inner = z.object(shape).passthrough();
+                const objectZod = z.object(shape).passthrough();
+                // Zod 4 reads a missing `__proto__` key off the prototype chain and skips the property, so a required one is checked on the raw input first.
+                inner =
+                    required.has('__proto__') && Object.prototype.hasOwnProperty.call(s.properties, '__proto__')
+                        ? z
+                            .any()
+                            .refine((v) => typeof v === 'object' && v !== null && Object.prototype.hasOwnProperty.call(v, '__proto__'), {
+                            message: 'Invalid input: required property "__proto__" is missing',
+                            path: ['__proto__'],
+                        })
+                            .pipe(objectZod)
+                        : objectZod;
             }
             else if (s.additionalProperties === true) {
                 inner = z.record(z.string(), z.any());

package/dist/orchestrator/index.d.ts

@@ -7,7 +7,7 @@
  */
 export { BUILTIN_SPECIALISTS, getSpecialist, effectiveToolsFor } from './specialists.js';
 export { parseRouterOutput, ROUTER_SYSTEM_PROMPT } from './router.js';
-export { runOrchestrator, runRouter, groupStepsByParallel, resolveEffectiveModel, _dispatchGroup, type OrchestratorOptions, type OrchestratorProgressEvent, type OrchestratorWorktreeMode, } from './orchestrator.js';
+export { runOrchestrator, runRouter, groupStepsByParallel, resolveEffectiveModel, specialistAgentConfig, handoffBlock, MAX_HANDOFF_CHARS, _dispatchGroup, type OrchestratorOptions, type StepLimits, type OrchestratorProgressEvent, type OrchestratorWorktreeMode, } from './orchestrator.js';
 export { MessageBoard, DEFAULT_BOARD_CAP, type BoardMessage } from './board.js';
 export { createBoardTools, BOARD_TOOL_NAMES } from './board-tools.js';
 export { registerSpecialist, unregisterSpecialist, listSpecialists, getRegisteredSpecialist, loadSpecialistsFromConfig, saveSpecialistsToConfig, validateSpecialistConfig, defaultConfigPath, _resetSpecialistsForTests, _customSpecialistCount, type CustomSpecialistConfig, type SpecialistsConfigFile, type LoadSpecialistsResult, } from './specialists-registry.js';

package/dist/orchestrator/index.js

@@ -7,7 +7,7 @@
  */
 export { BUILTIN_SPECIALISTS, getSpecialist, effectiveToolsFor } from './specialists.js';
 export { parseRouterOutput, ROUTER_SYSTEM_PROMPT } from './router.js';
-export { runOrchestrator, runRouter, groupStepsByParallel, resolveEffectiveModel, _dispatchGroup, } from './orchestrator.js';
+export { runOrchestrator, runRouter, groupStepsByParallel, resolveEffectiveModel, specialistAgentConfig, handoffBlock, MAX_HANDOFF_CHARS, _dispatchGroup, } from './orchestrator.js';
 export { MessageBoard, DEFAULT_BOARD_CAP } from './board.js';
 export { createBoardTools, BOARD_TOOL_NAMES } from './board-tools.js';
 export { registerSpecialist, unregisterSpecialist, listSpecialists, getRegisteredSpecialist, loadSpecialistsFromConfig, saveSpecialistsToConfig, validateSpecialistConfig, defaultConfigPath, _resetSpecialistsForTests, _customSpecialistCount, } from './specialists-registry.js';

package/dist/orchestrator/orchestrator.d.ts

@@ -29,7 +29,8 @@
  *     AND the step is part of a parallel group. Solo steps never get
  *     a worktree (it's wasted overhead).
  */
-import type { AgentConfig, AgentRunResult, ModelConfig } from '../types.js';
+import type { PermissionConfig } from '../tools/permission-rules.js';
+import type { AgentConfig, AgentRunResult, ModelConfig, ToolSandbox } from '../types.js';
 import { MessageBoard, type BoardMessage } from './board.js';
 import type { OrchestratorPlan, OrchestratorRunResult, OrchestratorStep, OrchestratorStepResult, SpecialistConfig } from './types.js';
 /**
@@ -63,6 +64,12 @@ export interface OrchestratorOptions {
     maxParallelism?: number;
     /** Approval callback for the router (specialists don't ask the user: they're scoped). */
     approve?: AgentConfig['approve'];
+    /** Tools a step runs without asking (the person's `autoApproveTools`); default: the read-only tools. */
+    autoApproveTools?: readonly string[];
+    /** The person's permission rules, kept by every step. */
+    permissionRules?: PermissionConfig;
+    /** The person's tool sandbox; a step's tools are narrowed to its `allowTools`. */
+    toolSandbox?: ToolSandbox;
     /** Optional modelFactory override (for tests). */
     modelFactory?: AgentConfig['modelFactory'];
     /**
@@ -180,11 +187,7 @@ export declare function runOrchestrator(options: OrchestratorOptions): Promise<O
  * git worktree. When `always`, every step gets a worktree regardless
  * of group size. `never` disables the feature.
  */
-export declare function _dispatchGroup(group: OrchestratorStep[], base: {
-    model: ModelConfig;
-    cwd?: string;
-    modelFactory?: AgentConfig['modelFactory'];
-}, dispatchOpts: {
+export declare function _dispatchGroup(group: OrchestratorStep[], base: StepBase, dispatchOpts: {
     worktrees: OrchestratorWorktreeMode;
     cleanupBranches?: boolean;
     commitChanges?: boolean;
@@ -195,6 +198,8 @@ export declare function _dispatchGroup(group: OrchestratorStep[], base: {
     }) => void;
     onWorktreeEvent?: OrchestratorOptions['onWorktreeEvent'];
     board?: MessageBoard;
+    /** Results of the groups that ran before this one, handed to every step of this group. */
+    prior?: readonly OrchestratorStepResult[];
 }, maxParallelism: number): Promise<OrchestratorStepResult[]>;
 /**
  * Run the router agent. Exposed for testing + for the
@@ -233,3 +238,37 @@ export declare function runRouter(args: {
  * without going through `Agent.run()`.
  */
 export declare function resolveEffectiveModel(spec: SpecialistConfig, baseModel: ModelConfig): ModelConfig;
+/** The most of one earlier step's reply handed to a later step. */
+export declare const MAX_HANDOFF_CHARS = 6000;
+/**
+ * What the earlier steps of an orchestrator run produced, for a later step. Without it each step saw only the
+ * line the router wrote before any step ran, so in "plan, then code" Code never saw Plan's plan.
+ */
+export declare function handoffBlock(prior: readonly OrchestratorStepResult[]): string;
+/** What a step inherits from the run: the model, where it works, and the limits the person set. */
+interface StepBase {
+    model: ModelConfig;
+    cwd?: string;
+    modelFactory?: AgentConfig['modelFactory'];
+    limits?: StepLimits;
+}
+/** The person's limits a step must keep: a step has no one to ask, so these decide what it may do (RB-14, RB-39). */
+export interface StepLimits {
+    autoApproveTools?: readonly string[];
+    permissionRules?: PermissionConfig;
+    toolSandbox?: ToolSandbox;
+}
+/**
+ * The Agent configuration for one orchestrator step. The step sees exactly its agent's effective tools
+ * (builtins off, the sandbox narrowed to that list), and runs its read-only tools without asking, as a
+ * `sub_agent` child does: there is no one to ask, so without the list every such call is refused.
+ */
+export declare function specialistAgentConfig(args: {
+    spec: SpecialistConfig;
+    model: ModelConfig;
+    cwd?: string;
+    modelFactory?: AgentConfig['modelFactory'];
+    board?: MessageBoard;
+    limits: StepLimits;
+}): AgentConfig;
+export {};

package/dist/orchestrator/orchestrator.js

@@ -31,12 +31,14 @@
  */
 import { randomBytes } from 'node:crypto';
 import { Agent } from '../agent/agent.js';
+import { NO_TOOLS_SENTINEL } from '../journey/stages.js';
 import { BUILTIN_TOOLS } from '../tools/index.js';
+import { READ_ONLY_TOOLS } from '../tools/read-only.js';
 import { commitAllInWorktree } from '../worktree/branch-ops.js';
 import { WorktreeError, WorktreeManager } from '../worktree/index.js';
 import { MessageBoard } from './board.js';
 import { createBoardTools } from './board-tools.js';
-import { getSpecialist, effectiveToolsFor } from './specialists.js';
+import { BUILTIN_SPECIALISTS, getSpecialist, effectiveToolsFor } from './specialists.js';
 import { parseRouterOutput, ROUTER_SYSTEM_PROMPT } from './router.js';
 /** Default cap on how many specialists can run at once within a group. */
 const DEFAULT_MAX_PARALLELISM = 5;
@@ -134,6 +136,11 @@ export async function runOrchestrator(options) {
         model: options.model,
         cwd: options.cwd,
         modelFactory: options.modelFactory,
+        limits: {
+            ...(options.autoApproveTools ? { autoApproveTools: options.autoApproveTools } : {}),
+            ...(options.permissionRules ? { permissionRules: options.permissionRules } : {}),
+            ...(options.toolSandbox ? { toolSandbox: options.toolSandbox } : {}),
+        },
     };
     const board = new MessageBoard();
     if (options.onBoardEvent)
@@ -158,7 +165,8 @@ export async function runOrchestrator(options) {
     };
     const groups = groupStepsByParallel(plan.steps);
     for (const group of groups) {
-        const groupResults = await _dispatchGroup(group, base, dispatchOpts, maxParallelism);
+        // Steps in one group run in parallel and do not see each other; they see every group before them.
+        const groupResults = await _dispatchGroup(group, base, { ...dispatchOpts, prior: [...stepResults] }, maxParallelism);
         for (const result of groupResults) {
             stepResults.push(result);
             totalIn += result.inputTokens;
@@ -362,7 +370,7 @@ async function runSpecialistStepInner(step, base, dispatchOpts, isParallelGroup,
             inputTokens: 0,
             outputTokens: 0,
             costUsd: 0,
-            error: `unknown specialist "${step.specialist}": known: plan, code, debug, ask, review`,
+            error: `unknown specialist "${step.specialist}": known: ${BUILTIN_SPECIALISTS.map((s) => s.id).join(', ')}`,
         };
     }
     // Worktree setup: same fallback pattern as `subAgentTool`:
@@ -408,12 +416,14 @@ async function runSpecialistStepInner(step, base, dispatchOpts, isParallelGroup,
     const effectiveCwd = worktree ? worktree.path : base.cwd;
     const effectiveModel = resolveEffectiveModel(spec, base.model);
     try {
+        const handoff = handoffBlock(dispatchOpts.prior ?? []);
         const result = await runSpecialist({
             spec,
-            task: step.task,
+            task: handoff ? `${step.task}\n\n${handoff}` : step.task,
             model: effectiveModel,
             cwd: effectiveCwd,
             modelFactory: base.modelFactory,
+            limits: base.limits ?? {},
             ...(dispatchOpts.board ? { board: dispatchOpts.board } : {}),
         });
         if (dispatchOpts.commitChanges && worktree) {
@@ -474,23 +484,63 @@ async function runSpecialistStepInner(step, base, dispatchOpts, isParallelGroup,
         }
     }
 }
-/** Construct + run a specialist sub-agent. */
-async function runSpecialist(args) {
-    const allowedSet = new Set(effectiveToolsFor(args.spec));
+/** The most of one earlier step's reply handed to a later step. */
+export const MAX_HANDOFF_CHARS = 6000;
+/** Remove the block's closing tag until none is left, so a reply cannot end the block early (RB-35). */
+function stripHandoffTag(text) {
+    let out = text;
+    for (let prev = ''; prev !== out;) {
+        prev = out;
+        out = out.replace(/<\/previous-steps>/gi, '');
+    }
+    return out;
+}
+/**
+ * What the earlier steps of an orchestrator run produced, for a later step. Without it each step saw only the
+ * line the router wrote before any step ran, so in "plan, then code" Code never saw Plan's plan.
+ */
+export function handoffBlock(prior) {
+    if (prior.length === 0)
+        return '';
+    const parts = prior.map((r, i) => {
+        const reply = stripHandoffTag(r.finalText.trim());
+        const capped = reply.length > MAX_HANDOFF_CHARS ? `${reply.slice(0, MAX_HANDOFF_CHARS)}\n[cut: ${reply.length - MAX_HANDOFF_CHARS} characters left out]` : reply;
+        const status = r.error ? `failed: ${stripHandoffTag(r.error)}` : r.reason;
+        return `## Step ${i + 1}: ${r.step.specialist} (${status})\nTask: ${stripHandoffTag(r.step.task)}\n\n${capped || '(no reply)'}`;
+    });
+    return ['<previous-steps>', 'Earlier steps of this task, in order. Build on their results; do not redo their work.', '', ...parts, '</previous-steps>'].join('\n');
+}
+/**
+ * The Agent configuration for one orchestrator step. The step sees exactly its agent's effective tools
+ * (builtins off, the sandbox narrowed to that list), and runs its read-only tools without asking, as a
+ * `sub_agent` child does: there is no one to ask, so without the list every such call is refused.
+ */
+export function specialistAgentConfig(args) {
+    const effective = effectiveToolsFor(args.spec);
+    const offered = new Set(effective);
     const tools = [
-        ...BUILTIN_TOOLS.filter((t) => allowedSet.has(t.name)),
-        ...(args.board ? createBoardTools(args.board, args.spec.id).filter((t) => allowedSet.has(t.name)) : []),
+        ...BUILTIN_TOOLS.filter((t) => offered.has(t.name)),
+        ...(args.board ? createBoardTools(args.board, args.spec.id).filter((t) => offered.has(t.name)) : []),
     ];
-    const config = {
+    const parentAllow = args.limits.toolSandbox?.allowTools;
+    const narrowed = parentAllow ? effective.filter((t) => parentAllow.includes(t)) : effective;
+    return {
         model: args.model,
         systemPrompt: args.spec.systemPrompt,
         ...(args.cwd ? { cwd: args.cwd } : {}),
         auto: args.spec.auto ?? false,
         maxIterations: args.spec.maxIterations ?? 10,
         extraTools: tools,
-        disableBuiltins: false,
+        disableBuiltins: true,
+        autoApproveTools: args.limits.autoApproveTools ? [...args.limits.autoApproveTools] : [...READ_ONLY_TOOLS],
+        ...(args.limits.permissionRules ? { permissionRules: args.limits.permissionRules } : {}),
+        // An empty allowTools means "no whitelist" to the sandbox, so "nothing left" is the sentinel (RB-29).
+        toolSandbox: { ...(args.limits.toolSandbox ?? {}), allowTools: narrowed.length > 0 ? narrowed : [NO_TOOLS_SENTINEL] },
         ...(args.modelFactory ? { modelFactory: args.modelFactory } : {}),
     };
-    const agent = new Agent(config);
+}
+/** Construct + run a specialist sub-agent. */
+async function runSpecialist(args) {
+    const agent = new Agent(specialistAgentConfig(args));
     return agent.run({ task: args.task });
 }

package/dist/orchestrator/router.d.ts

@@ -13,7 +13,7 @@
  */
 import type { OrchestratorPlan } from './types.js';
 /** System prompt used by the router agent. */
-export declare const ROUTER_SYSTEM_PROMPT = "You are the IKarmic Forge ORCHESTRATOR. Your job is to read the user's task and decide which specialist(s) to dispatch to.\n\nAvailable specialists:\n- **plan**   \u2014 read-only investigation, produces a structured plan as text\n- **code**   \u2014 focused file edits, runs tests\n- **debug**  \u2014 investigates failures and identifies the root cause\n- **ask**    \u2014 pure Q&A, no file mutations\n- **review** \u2014 read-only code review, identifies issues + suggests fixes\n\nYour output MUST be a single JSON object (no prose around it) with this exact shape:\n\n```json\n{\n  \"rationale\": \"One-sentence reason for this routing decision.\",\n  \"steps\": [\n    { \"specialist\": \"<id>\", \"task\": \"<focused task for the specialist>\", \"parallelGroup\": \"<optional tag>\" }\n  ]\n}\n```\n\nRouting heuristics:\n- A clear bug report \u2192 1 step: debug\n- \"What does X do?\" or \"How does Y work?\" \u2192 1 step: ask\n- \"Implement X\" / \"Add feature Y\" \u2192 2 steps in order: plan, code (sequential, parallelGroup unset)\n- \"Review PR / diff / file\" \u2192 1 step: review\n- \"Refactor X\" \u2192 2 steps: plan, code\n- Multi-area research (e.g. \"compare X and Y\") \u2192 2+ ask steps with the SAME parallelGroup so they run concurrently\n- \"Fix and add tests for X\" \u2192 2 steps: debug, code\n- If you're unsure, default to: plan, then code. Never dispatch the same specialist twice unless the user asks for revisions.\n\nAbout parallelGroup:\n- Set it ONLY when you want two or more consecutive steps to run concurrently.\n- Consecutive steps with the same parallelGroup run in parallel. A different (or missing) label between them breaks the group, so a later step with the same label will start a new group.\n- Examples:\n    - [{\"ask\",\"how does auth work?\",\"parallelGroup\":\"research\"}, {\"ask\",\"how does billing work?\",\"parallelGroup\":\"research\"}] \u2192 both run concurrently.\n    - [{\"ask\",\"q1\",\"parallelGroup\":\"x\"}, {\"ask\",\"q2\",\"parallelGroup\":\"x\"}, {\"ask\",\"q3\"}] \u2192 q1 and q2 run together, then q3 runs alone after them.\n- Do NOT use parallelGroup for steps with side effects on the same files (e.g. two 'code' specialists editing the same module) \u2014 they would race.\n\nConstraints:\n- All specialist ids must be one of: plan, code, debug, ask, review.\n- Tasks must be focused (1-3 sentences each).\n- Don't dispatch more than 5 steps \u2014 decompose is the user's job, not yours.";
+export declare const ROUTER_SYSTEM_PROMPT: string;
 /**
  * Parse the router agent's final text into an {@link OrchestratorPlan}.
  * Tolerant of:

package/dist/orchestrator/router.js

@@ -11,6 +11,7 @@
  * from a free-form model response. We strip ```json fences, try
  * JSON.parse, and accept the first object that has a steps array.
  */
+import { BUILTIN_SPECIALISTS } from './specialists.js';
 /** System prompt used by the router agent. */
 export const ROUTER_SYSTEM_PROMPT = `You are the IKarmic Forge ORCHESTRATOR. Your job is to read the user's task and decide which specialist(s) to dispatch to.
 
@@ -20,6 +21,7 @@ Available specialists:
 - **debug**  — investigates failures and identifies the root cause
 - **ask**    — pure Q&A, no file mutations
 - **review** — read-only code review, identifies issues + suggests fixes
+- **security** — finds exploitable security problems and vulnerable dependencies; changes files only for findings the user named
 
 Your output MUST be a single JSON object (no prose around it) with this exact shape:
 
@@ -37,6 +39,7 @@ Routing heuristics:
 - "What does X do?" or "How does Y work?" → 1 step: ask
 - "Implement X" / "Add feature Y" → 2 steps in order: plan, code (sequential, parallelGroup unset)
 - "Review PR / diff / file" → 1 step: review
+- "Check for security problems / vulnerabilities / audit" → 1 step: security
 - "Refactor X" → 2 steps: plan, code
 - Multi-area research (e.g. "compare X and Y") → 2+ ask steps with the SAME parallelGroup so they run concurrently
 - "Fix and add tests for X" → 2 steps: debug, code
@@ -51,7 +54,7 @@ About parallelGroup:
 - Do NOT use parallelGroup for steps with side effects on the same files (e.g. two 'code' specialists editing the same module) — they would race.
 
 Constraints:
-- All specialist ids must be one of: plan, code, debug, ask, review.
+- All specialist ids must be one of: ${BUILTIN_SPECIALISTS.map((s) => s.id).join(', ')}.
 - Tasks must be focused (1-3 sentences each).
 - Don't dispatch more than 5 steps — decompose is the user's job, not yours.`;
 /**

package/dist/orchestrator/specialists.d.ts

@@ -16,7 +16,12 @@
  * `~/.forge/specialists.json` (loaded automatically on startup).
  */
 import type { SpecialistConfig, SpecialistId } from './types.js';
-/** The five built-in specialists. Order is the order shown in `forge orchestrator list`. */
+/**
+ * The built-in specialists. Order is the order shown in `forge orchestrator list` and in the chat's mode menu.
+ * Each prompt works both as a chat mode and as an orchestrator step: nothing in it assumes another agent.
+ * Prompt rules (RB-27): a tool named in the text is a built-in, in backticks, and never one that is only
+ * registered when a feature is on. `core/tests/specialist-profiles.test.ts` pins tools, limits and size.
+ */
 export declare const BUILTIN_SPECIALISTS: readonly SpecialistConfig[];
 /**
  * Look up a specialist by id. Checks custom registrations first