@compilr-dev/sdk 0.9.12 → 0.9.14

package/dist/index.d.ts

@@ -36,9 +36,9 @@
 export { createCompilrAgent } from './agent.js';
 export type { CompilrAgentConfig, CompilrAgent, RunOptions, RunResult, ToolCallRecord, ToolConfig, UsageInfo, ProviderType, PermissionCallback, GuardrailConfig, ContextConfig, CapabilitiesConfig, } from './config.js';
 export { AgentTeam, TeamAgent, SharedContextManager, ArtifactStore, DelegationTracker, ContextResolver, } from './team/index.js';
-export type { AgentTeamConfig, TeamAgentConfig, ITeamPersistence, IArtifactStorage, ISessionRegistry, CustomAgentDefinition, AgentTemplate, ToolConfig as TeamToolConfig, ToolTier, ToolGroup, ProfileInfo, } from './team/index.js';
+export type { AgentTeamConfig, TeamAgentConfig, ITeamPersistence, IArtifactStorage, ISessionRegistry, CustomAgentDefinition, AgentTemplate, AgentWorkshopData, WorkshopRoleDef, WorkshopToolProfile, WorkshopModelTier, WorkshopSkillDef, PlanSubmitInfo, PlanSubmitResult, PlanModeExitInfo, PlanModeCallbacks, ToolConfig as TeamToolConfig, ToolTier, ToolGroup, ProfileInfo, } from './team/index.js';
 export type { AgentRole, RoleMetadata, ToolProfile, MascotExpression, BackgroundSessionInfo, SerializedTeam, SerializedTeamAgent, TeamMetadata, TeamEvent, TeamEventType, TeamEventHandler, Artifact, ArtifactType as TeamArtifactType, ArtifactSummary as TeamArtifactSummary, CreateArtifactOptions, UpdateArtifactOptions, SerializedArtifact, SharedContext, SharedProjectInfo, SharedTeamInfo, TeamRosterEntry, TeamActivity, TeamActivityType, SharedDecision, TokenBudget, SerializedSharedContext, ParsedMention, ParsedInput, ResolvedMention, ResolveOptions, ResolutionSource, Delegation, DelegationStatus, DelegationResult, CompletionEvent, CreateDelegationOptions, DelegationStats, DelegationTrackerEvents, SkillToolRequirement, } from './team/index.js';
-export { ROLE_METADATA, ROLE_EXPERTISE, PREDEFINED_ROLE_IDS, TOOL_GROUPS, TOOL_PROFILES, PROFILE_INFO, SKILL_REQUIREMENTS, CUSTOM_MASCOTS, } from './team/index.js';
+export { ROLE_METADATA, ROLE_EXPERTISE, ROLE_GROUPS, PREDEFINED_ROLE_IDS, TOOL_GROUPS, TOOL_PROFILES, PROFILE_INFO, SKILL_REQUIREMENTS, CUSTOM_MASCOTS, buildAgentWorkshopData, buildSuggestedRolesMap, PLAN_MODE_BLOCKED_TOOLS, PLAN_MODE_DENIAL_MESSAGE, PLAN_MODE_PROMPT, isToolAllowedInPlanMode, getPlanModePrompt, } from './team/index.js';
 export { getToolsForProfile, detectProfileFromTools, isProfileReadOnly, generateToolAwarenessPrompt, generateCoordinatorGuidance, generateSpecialistGuidance, createDefaultToolConfig, validateToolConfig, getAllGroupIds, getGroupInfo, getGroupsByTier, getGroupsForProfile, assignMascot, generateCustomAgentSystemPrompt, getCustomAgentToolFilter, getCustomAgentProfileLabel, validateAgentId, isAgentIdTaken, createCustomAgentDefinition, listTemplates, getTemplate, saveTemplate, updateTemplate, deleteTemplate, createAgentFromTemplate, parseInputForMentions, getReferencedAgents, hasReferences, buildMessageWithContext, buildContextMap, findAgentForRole, findAgentById, getAvailableSpecialists, getSpecialistsSummary, hasSpecialists, suggestOwner, suggestOwners, matchesAgentExpertise, wouldCreateLoop, recordAssignment, getAssignmentHistory, clearAssignmentHistory, clearAllAssignmentHistory, canReassign, resolveAgentIdCollision, setActiveSharedContext, getActiveSharedContext, recordTeamActivity, getDefinedSkillNames, getSkillRequirements, checkSkillCompatibility, getCompatibleSkills, getAllRequiredTools, getSkillsByCategory, } from './team/index.js';
 export { codingPreset, readOnlyPreset, resolvePreset } from './presets/index.js';
 export type { Preset } from './presets/index.js';

package/dist/index.js

@@ -43,7 +43,9 @@ export { createCompilrAgent } from './agent.js';
 // Core classes
 export { AgentTeam, TeamAgent, SharedContextManager, ArtifactStore, DelegationTracker, ContextResolver, } from './team/index.js';
 // Constants
-export { ROLE_METADATA, ROLE_EXPERTISE, PREDEFINED_ROLE_IDS, TOOL_GROUPS, TOOL_PROFILES, PROFILE_INFO, SKILL_REQUIREMENTS, CUSTOM_MASCOTS, } from './team/index.js';
+export { ROLE_METADATA, ROLE_EXPERTISE, ROLE_GROUPS, PREDEFINED_ROLE_IDS, TOOL_GROUPS, TOOL_PROFILES, PROFILE_INFO, SKILL_REQUIREMENTS, CUSTOM_MASCOTS, buildAgentWorkshopData, buildSuggestedRolesMap, 
+// Plan mode
+PLAN_MODE_BLOCKED_TOOLS, PLAN_MODE_DENIAL_MESSAGE, PLAN_MODE_PROMPT, isToolAllowedInPlanMode, getPlanModePrompt, } from './team/index.js';
 // Utility functions
 export { 
 // Tool config

package/dist/platform/tools/index.d.ts

@@ -11,12 +11,18 @@
 import type { Tool } from '@compilr-dev/agents';
 import type { PlatformToolsConfig } from '../context.js';
 import type { ImageToolsConfig } from './image-tools.js';
+import type { PlanModeCallbacks } from '../../team/plan-mode.js';
+export interface PlatformToolsOptions {
+    imageConfig?: ImageToolsConfig;
+    planModeCallbacks?: PlanModeCallbacks;
+}
 /**
  * Create all platform tools operating against the given context.
- * Returns 25 DB tools + 1 image tool unconditionally, plus up to 8 service-based
+ * Returns 25+ DB tools + 1 image tool unconditionally, plus up to 8 service-based
  * tools if the optional anchors/artifacts/episodes services are provided.
+ * If planModeCallbacks are provided, plan_submit and plan_mode_exit tools are included.
  */
-export declare function createPlatformTools(config: PlatformToolsConfig, imageConfig?: ImageToolsConfig): Tool<never>[];
+export declare function createPlatformTools(config: PlatformToolsConfig, options?: ImageToolsConfig | PlatformToolsOptions): Tool<never>[];
 export { createProjectTools } from './project-tools.js';
 export { createWorkItemTools } from './workitem-tools.js';
 export { createDocumentTools } from './document-tools.js';

package/dist/platform/tools/index.js

@@ -19,18 +19,29 @@ import { createEpisodeTools } from './episode-tools.js';
 import { createImageTools } from './image-tools.js';
 /**
  * Create all platform tools operating against the given context.
- * Returns 25 DB tools + 1 image tool unconditionally, plus up to 8 service-based
+ * Returns 25+ DB tools + 1 image tool unconditionally, plus up to 8 service-based
  * tools if the optional anchors/artifacts/episodes services are provided.
+ * If planModeCallbacks are provided, plan_submit and plan_mode_exit tools are included.
  */
 // eslint-disable-next-line @typescript-eslint/explicit-function-return-type
-export function createPlatformTools(config, imageConfig) {
+export function createPlatformTools(config, options) {
+    // Backwards compat: options can be ImageToolsConfig (old) or PlatformToolsOptions (new)
+    let imageConfig;
+    let planCallbacks;
+    if (options && 'planModeCallbacks' in options) {
+        imageConfig = options.imageConfig;
+        planCallbacks = options.planModeCallbacks;
+    }
+    else if (options) {
+        imageConfig = options;
+    }
     // Use Tool<never>[] to accept any Tool<T> — the generic parameter is only
     // relevant to execute() callers, not to the registry that stores them.
     const tools = [
         ...createProjectTools(config),
         ...createWorkItemTools(config),
         ...createDocumentTools(config),
-        ...createPlanTools(config),
+        ...createPlanTools(config, planCallbacks),
         ...createBacklogTools(config),
         ...createImageTools({ cwd: config.cwd, ...imageConfig }),
     ];

package/dist/platform/tools/plan-tools.d.ts

@@ -5,26 +5,12 @@
  *
  * Ported from CLI's src/tools/plan-tools.ts.
  */
+import { type Tool } from '@compilr-dev/agents';
 import type { PlatformToolsConfig } from '../context.js';
-export declare function createPlanTools(config: PlatformToolsConfig): (import("@compilr-dev/agents").Tool<{
-    name: string;
-    content: string;
-    work_item_id?: number;
-    project_id?: number;
-}> | import("@compilr-dev/agents").Tool<{
-    plan_id: number;
-    content?: string;
-    status?: string;
-    work_item_id?: number | null;
-}> | import("@compilr-dev/agents").Tool<{
-    plan_id?: number;
-    name?: string;
-    summary_only?: boolean;
-    project_id?: number;
-}> | import("@compilr-dev/agents").Tool<{
-    project_id?: number;
-    status?: string;
-    work_item_id?: number;
-    limit?: number;
-    order_by?: string;
-}>)[];
+import type { PlanModeCallbacks } from '../../team/plan-mode.js';
+export interface PlanToolsConfig {
+    platform: PlatformToolsConfig;
+    /** Optional plan mode callbacks (for plan_submit and plan_mode_exit) */
+    planModeCallbacks?: PlanModeCallbacks;
+}
+export declare function createPlanTools(config: PlatformToolsConfig, planModeCallbacks?: PlanModeCallbacks): Tool<never>[];

package/dist/platform/tools/plan-tools.js

@@ -8,7 +8,7 @@
 import { defineTool, createSuccessResult, createErrorResult } from '@compilr-dev/agents';
 import { truncateContent } from './truncate.js';
 // eslint-disable-next-line @typescript-eslint/explicit-function-return-type
-export function createPlanTools(config) {
+export function createPlanTools(config, planModeCallbacks) {
     const { context: ctx } = config;
     // ---------------------------------------------------------------------------
     // plan_create
@@ -360,5 +360,94 @@ export function createPlanTools(config) {
             }
         },
     });
-    return [planCreateTool, planUpdateTool, planGetTool, planListTool, planDeleteTool];
+    // ---------------------------------------------------------------------------
+    // plan_submit (requires callback from host app)
+    // ---------------------------------------------------------------------------
+    const planSubmitTool = planModeCallbacks
+        ? defineTool({
+            name: 'plan_submit',
+            description: 'Submit a plan for user approval. Call this when your plan is ready for review. ' +
+                'The user will see the plan and choose to approve, revise, or reject it. ' +
+                'On approval, write tools are unlocked and you can implement the plan.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    plan_id: {
+                        type: 'number',
+                        description: 'ID of the plan to submit for approval',
+                    },
+                    summary: {
+                        type: 'string',
+                        description: 'One-line summary of what the plan does',
+                    },
+                },
+                required: ['plan_id'],
+            },
+            execute: async (input) => {
+                // Verify plan exists
+                const plan = await ctx.plans.getById(input.plan_id);
+                if (!plan) {
+                    return createErrorResult(`Plan ${String(input.plan_id)} not found`);
+                }
+                // Call host app's approval UI
+                const result = await planModeCallbacks.onPlanSubmit({
+                    planId: input.plan_id,
+                    summary: input.summary,
+                });
+                // Update plan status based on user decision
+                if (result.action === 'approve-auto' || result.action === 'approve') {
+                    await ctx.plans.update(input.plan_id, { status: 'approved' });
+                }
+                else if (result.action === 'reject') {
+                    await ctx.plans.update(input.plan_id, { status: 'abandoned' });
+                }
+                const messages = {
+                    'approve-auto': 'Plan approved. Auto-accept mode enabled. Proceed with implementation.',
+                    approve: 'Plan approved. Proceed with implementation (tools will require approval).',
+                    revise: `Plan needs revision. Feedback: ${result.feedback ?? 'No specific feedback'}`,
+                    reject: 'Plan rejected. Create a new plan or exit plan mode.',
+                };
+                return createSuccessResult({ action: result.action, message: messages[result.action] });
+            },
+        })
+        : null;
+    // ---------------------------------------------------------------------------
+    // plan_mode_exit (requires callback from host app)
+    // ---------------------------------------------------------------------------
+    const planModeExitTool = planModeCallbacks
+        ? defineTool({
+            name: 'plan_mode_exit',
+            description: 'Exit plan mode without submitting a plan. Use this when the task is simple enough ' +
+                'to implement directly without a formal plan.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    reason: {
+                        type: 'string',
+                        description: 'Brief reason for exiting plan mode (e.g., "Simple one-line fix")',
+                    },
+                },
+                required: ['reason'],
+            },
+            execute: async (input) => {
+                await planModeCallbacks.onPlanModeExit({ reason: input.reason });
+                return createSuccessResult({
+                    message: `Exited plan mode: ${input.reason}. Full tools now available.`,
+                });
+            },
+        })
+        : null;
+    // Build tools array — include plan_submit and plan_mode_exit only if callbacks provided
+    const tools = [
+        planCreateTool,
+        planUpdateTool,
+        planGetTool,
+        planListTool,
+        planDeleteTool,
+    ];
+    if (planSubmitTool)
+        tools.push(planSubmitTool);
+    if (planModeExitTool)
+        tools.push(planModeExitTool);
+    return tools;
 }

package/dist/team/index.d.ts

@@ -12,7 +12,7 @@ export type { SharedContext, SharedProjectInfo, SharedTeamInfo, TeamRosterEntry,
 export { ArtifactStore } from './artifacts.js';
 export type { Artifact, ArtifactType, ArtifactSummary, CreateArtifactOptions, UpdateArtifactOptions, SerializedArtifact, } from './artifacts.js';
 export type { TeamAgentConfig, SerializedTeamAgent, TeamMetadata, SerializedTeam, TeamEvent, TeamEventType, TeamEventHandler, AgentRole, RoleMetadata, MascotExpression, ToolProfile, BackgroundSessionInfo, } from './types.js';
-export { ROLE_METADATA, ROLE_EXPERTISE, PREDEFINED_ROLE_IDS } from './types.js';
+export { ROLE_METADATA, ROLE_EXPERTISE, ROLE_GROUPS, PREDEFINED_ROLE_IDS } from './types.js';
 export { TOOL_GROUPS, TOOL_PROFILES, PROFILE_INFO, getToolsForProfile, detectProfileFromTools, isProfileReadOnly, generateToolAwarenessPrompt, generateCoordinatorGuidance, generateSpecialistGuidance, } from './tool-config.js';
 export type { ToolConfig, ToolTier, ToolGroup, ProfileInfo } from './tool-config.js';
 export { createDefaultToolConfig, validateToolConfig, getAllGroupIds, getGroupInfo, getGroupsByTier, getGroupsForProfile, } from './tool-config.js';
@@ -20,6 +20,10 @@ export type { CustomAgentDefinition } from './custom-agents.js';
 export { CUSTOM_MASCOTS, assignMascot, generateCustomAgentSystemPrompt, getCustomAgentToolFilter, getCustomAgentProfileLabel, validateAgentId, isAgentIdTaken, createCustomAgentDefinition, } from './custom-agents.js';
 export type { AgentTemplate } from './agent-templates.js';
 export { listTemplates, getTemplate, saveTemplate, updateTemplate, deleteTemplate, createAgentFromTemplate, } from './agent-templates.js';
+export type { PlanSubmitInfo, PlanSubmitResult, PlanModeExitInfo, PlanModeCallbacks, } from './plan-mode.js';
+export { PLAN_MODE_BLOCKED_TOOLS, PLAN_MODE_DENIAL_MESSAGE, PLAN_MODE_PROMPT, isToolAllowedInPlanMode, getPlanModePrompt, } from './plan-mode.js';
+export type { AgentWorkshopData, WorkshopRoleDef, WorkshopToolProfile, WorkshopModelTier, WorkshopSkillDef, } from './workshop-data.js';
+export { buildAgentWorkshopData, buildSuggestedRolesMap } from './workshop-data.js';
 export type { ITeamPersistence, IArtifactStorage, ISessionRegistry } from './interfaces.js';
 export type { ParsedMention, ParsedInput } from './mention-parser.js';
 export { parseInputForMentions, getReferencedAgents, hasReferences, buildMessageWithContext, } from './mention-parser.js';

package/dist/team/index.js

@@ -9,12 +9,14 @@ export { AgentTeam } from './team.js';
 export { TeamAgent } from './team-agent.js';
 export { SharedContextManager } from './shared-context.js';
 export { ArtifactStore } from './artifacts.js';
-export { ROLE_METADATA, ROLE_EXPERTISE, PREDEFINED_ROLE_IDS } from './types.js';
+export { ROLE_METADATA, ROLE_EXPERTISE, ROLE_GROUPS, PREDEFINED_ROLE_IDS } from './types.js';
 // Tool configuration
 export { TOOL_GROUPS, TOOL_PROFILES, PROFILE_INFO, getToolsForProfile, detectProfileFromTools, isProfileReadOnly, generateToolAwarenessPrompt, generateCoordinatorGuidance, generateSpecialistGuidance, } from './tool-config.js';
 export { createDefaultToolConfig, validateToolConfig, getAllGroupIds, getGroupInfo, getGroupsByTier, getGroupsForProfile, } from './tool-config.js';
 export { CUSTOM_MASCOTS, assignMascot, generateCustomAgentSystemPrompt, getCustomAgentToolFilter, getCustomAgentProfileLabel, validateAgentId, isAgentIdTaken, createCustomAgentDefinition, } from './custom-agents.js';
 export { listTemplates, getTemplate, saveTemplate, updateTemplate, deleteTemplate, createAgentFromTemplate, } from './agent-templates.js';
+export { PLAN_MODE_BLOCKED_TOOLS, PLAN_MODE_DENIAL_MESSAGE, PLAN_MODE_PROMPT, isToolAllowedInPlanMode, getPlanModePrompt, } from './plan-mode.js';
+export { buildAgentWorkshopData, buildSuggestedRolesMap } from './workshop-data.js';
 export { parseInputForMentions, getReferencedAgents, hasReferences, buildMessageWithContext, } from './mention-parser.js';
 export { ContextResolver, buildContextMap } from './context-resolver.js';
 // Agent selection

package/dist/team/plan-mode.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Plan Mode — Tool blocking and callbacks for plan-before-act workflow.
+ *
+ * During plan mode, write/execute tools are blocked at the permission layer.
+ * The agent can only read, search, and create plans. When ready, it calls
+ * plan_submit to trigger the host app's approval UI.
+ */
+/**
+ * Tools that are blocked during plan mode.
+ * The agent still "sees" these tools in its schema but any call
+ * is denied with a message explaining plan mode restrictions.
+ */
+export declare const PLAN_MODE_BLOCKED_TOOLS: Set<string>;
+/**
+ * Check if a tool is allowed during plan mode.
+ */
+export declare function isToolAllowedInPlanMode(toolName: string): boolean;
+/**
+ * Message returned to the agent when a blocked tool is called in plan mode.
+ */
+export declare const PLAN_MODE_DENIAL_MESSAGE: string;
+export interface PlanSubmitInfo {
+    planId: number;
+    summary?: string;
+}
+export interface PlanSubmitResult {
+    /** User's decision */
+    action: 'approve-auto' | 'approve' | 'revise' | 'reject';
+    /** User's feedback (for revise/reject) */
+    feedback?: string;
+}
+export interface PlanModeExitInfo {
+    reason: string;
+}
+/**
+ * Callbacks that the host app (CLI/Desktop) must provide for plan mode tools.
+ * Same pattern as ask_user — SDK defines the tool, host provides the UI.
+ */
+export interface PlanModeCallbacks {
+    /** Called when agent submits a plan for approval (shows approval UI) */
+    onPlanSubmit: (info: PlanSubmitInfo) => Promise<PlanSubmitResult>;
+    /** Called when agent wants to exit plan mode without a plan */
+    onPlanModeExit: (info: PlanModeExitInfo) => Promise<void>;
+}
+/**
+ * System prompt section injected when plan mode is active.
+ * Appended to the agent's system prompt by the host app.
+ */
+export declare const PLAN_MODE_PROMPT = "## Plan Mode (Active)\n\nYou are in plan mode. Your write and execute tools are temporarily blocked.\n\n**What you CAN do:**\n- Read files, search code, analyze the codebase\n- Create and update plans with plan_create and plan_update\n- Ask the user clarifying questions\n- Submit your plan for approval with plan_submit\n\n**What you CANNOT do (until plan is approved):**\n- Edit, create, or delete files\n- Run shell commands\n- Execute tests or builds\n- Make git commits\n\n**Your workflow:**\n1. Understand the request \u2014 read relevant files, check the backlog, review existing code\n2. Create a plan \u2014 use plan_create with a clear name and structured content\n3. Submit for approval \u2014 call plan_submit when your plan is ready\n4. Wait for user decision \u2014 they may approve, ask for revisions, or reject\n\n**Plan format:**\n- Context: What problem are we solving? What exists today?\n- Approach: High-level strategy\n- Steps: Numbered list of specific changes (file, what to change, why)\n- Verification: How to confirm the changes work\n\nIf the task is too simple for a plan, call plan_mode_exit with a reason.";
+/**
+ * Get the plan mode prompt, optionally with active plan context.
+ */
+export declare function getPlanModePrompt(activePlan?: {
+    id: number;
+    name: string;
+}): string;

package/dist/team/plan-mode.js

@@ -0,0 +1,97 @@
+/**
+ * Plan Mode — Tool blocking and callbacks for plan-before-act workflow.
+ *
+ * During plan mode, write/execute tools are blocked at the permission layer.
+ * The agent can only read, search, and create plans. When ready, it calls
+ * plan_submit to trigger the host app's approval UI.
+ */
+// =============================================================================
+// Blocked Tools
+// =============================================================================
+/**
+ * Tools that are blocked during plan mode.
+ * The agent still "sees" these tools in its schema but any call
+ * is denied with a message explaining plan mode restrictions.
+ */
+export const PLAN_MODE_BLOCKED_TOOLS = new Set([
+    // Shell / execution
+    'bash',
+    'bash_output',
+    'kill_shell',
+    // File writes
+    'edit',
+    'write_file',
+    'create_file',
+    'delete_file',
+    'rename_file',
+    'move_file',
+    // Git writes
+    'git_commit',
+    'git_branch',
+    'git_checkout',
+    'git_push',
+    // Runners (execute code)
+    'run_tests',
+    'run_lint',
+    'run_build',
+]);
+/**
+ * Check if a tool is allowed during plan mode.
+ */
+export function isToolAllowedInPlanMode(toolName) {
+    return !PLAN_MODE_BLOCKED_TOOLS.has(toolName);
+}
+/**
+ * Message returned to the agent when a blocked tool is called in plan mode.
+ */
+export const PLAN_MODE_DENIAL_MESSAGE = 'Plan mode: write/execute tools are blocked during planning. ' +
+    'Read and analyze first, create your plan with plan_create, ' +
+    'then call plan_submit to request approval.';
+// =============================================================================
+// System Prompt
+// =============================================================================
+/**
+ * System prompt section injected when plan mode is active.
+ * Appended to the agent's system prompt by the host app.
+ */
+export const PLAN_MODE_PROMPT = `## Plan Mode (Active)
+
+You are in plan mode. Your write and execute tools are temporarily blocked.
+
+**What you CAN do:**
+- Read files, search code, analyze the codebase
+- Create and update plans with plan_create and plan_update
+- Ask the user clarifying questions
+- Submit your plan for approval with plan_submit
+
+**What you CANNOT do (until plan is approved):**
+- Edit, create, or delete files
+- Run shell commands
+- Execute tests or builds
+- Make git commits
+
+**Your workflow:**
+1. Understand the request — read relevant files, check the backlog, review existing code
+2. Create a plan — use plan_create with a clear name and structured content
+3. Submit for approval — call plan_submit when your plan is ready
+4. Wait for user decision — they may approve, ask for revisions, or reject
+
+**Plan format:**
+- Context: What problem are we solving? What exists today?
+- Approach: High-level strategy
+- Steps: Numbered list of specific changes (file, what to change, why)
+- Verification: How to confirm the changes work
+
+If the task is too simple for a plan, call plan_mode_exit with a reason.`;
+/**
+ * Get the plan mode prompt, optionally with active plan context.
+ */
+export function getPlanModePrompt(activePlan) {
+    let prompt = PLAN_MODE_PROMPT;
+    if (activePlan) {
+        prompt +=
+            `\n\n**Active Plan:** "${activePlan.name}" (ID: ${String(activePlan.id)}). ` +
+                'Use plan_get to review it, plan_update to modify it, or plan_submit to submit for approval.';
+    }
+    return prompt;
+}

package/dist/team/types.d.ts

@@ -34,6 +34,11 @@ export type MascotExpression = '[•_•]' | '[◈_◈]' | '[▣_▣]' | '[◉_
  * Predefined agent roles with default configurations
  */
 export type AgentRole = 'default' | 'pm' | 'arch' | 'qa' | 'dev' | 'ops' | 'docs' | 'ba' | 'researcher' | 'reviewer' | 'editor' | 'writer' | 'analyst' | 'strategist' | 'instructor' | 'custom';
+/**
+ * Role groups for UI display (Workshop, team overlay).
+ * Groups roles by domain — used for visual categorization.
+ */
+export declare const ROLE_GROUPS: Record<string, AgentRole[]>;
 /**
  * List of predefined role IDs (for validation against custom agent IDs)
  */

package/dist/team/types.js

@@ -3,6 +3,15 @@
  *
  * Type definitions for the multi-agent team system.
  */
+/**
+ * Role groups for UI display (Workshop, team overlay).
+ * Groups roles by domain — used for visual categorization.
+ */
+export const ROLE_GROUPS = {
+    Software: ['dev', 'arch', 'qa', 'pm', 'ops'],
+    'Writing & Analysis': ['writer', 'editor', 'reviewer', 'researcher', 'analyst', 'docs', 'ba'],
+    'Business & Education': ['strategist', 'instructor'],
+};
 /**
  * List of predefined role IDs (for validation against custom agent IDs)
  */

package/dist/team/workshop-data.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Workshop Data Builder — Assembles all agent/skill/tool metadata
+ * into a single UI-friendly structure for the Agent Workshop.
+ *
+ * Used by both Desktop (via IPC) and CLI (direct import).
+ * Single source of truth — no hardcoded data in UI components.
+ */
+export interface WorkshopRoleDef {
+    id: string;
+    displayName: string;
+    mascot: string;
+    description: string;
+    group: string;
+    expertise: string[];
+    defaultToolProfile: string;
+    defaultModelTier: string;
+}
+export interface WorkshopToolProfile {
+    id: string;
+    label: string;
+    description: string;
+    isReadOnly: boolean;
+}
+export interface WorkshopModelTier {
+    id: string;
+    label: string;
+    description: string;
+}
+export interface WorkshopSkillDef {
+    id: string;
+    label: string;
+    category: string;
+    requiredTools: string[];
+    optionalTools: string[];
+}
+export interface AgentWorkshopData {
+    /** Predefined roles with metadata */
+    roles: WorkshopRoleDef[];
+    /** Role group names in display order */
+    roleGroupOrder: string[];
+    /** Suggested role IDs per project type */
+    suggestedRoles: Record<string, string[]>;
+    /** Available tool profiles */
+    toolProfiles: WorkshopToolProfile[];
+    /** Model tiers */
+    modelTiers: WorkshopModelTier[];
+    /** Skills with tool requirements */
+    skills: WorkshopSkillDef[];
+    /** Skill category names in display order */
+    skillCategories: string[];
+}
+/**
+ * Build the complete workshop data from SDK constants.
+ * This is a pure function — no side effects, fully testable.
+ */
+export declare function buildAgentWorkshopData(suggestedRolesMap?: Record<string, string[]>): AgentWorkshopData;
+/**
+ * Build the suggested roles map from project type configs.
+ * Call this from the host app (needs access to PROJECT_TYPES).
+ */
+export declare function buildSuggestedRolesMap(projectTypes: Array<{
+    id: string;
+    suggestedAgents?: Array<{
+        role: string;
+    }>;
+}>): Record<string, string[]>;

package/dist/team/workshop-data.js

@@ -0,0 +1,119 @@
+/**
+ * Workshop Data Builder — Assembles all agent/skill/tool metadata
+ * into a single UI-friendly structure for the Agent Workshop.
+ *
+ * Used by both Desktop (via IPC) and CLI (direct import).
+ * Single source of truth — no hardcoded data in UI components.
+ */
+import { PREDEFINED_ROLE_IDS, ROLE_METADATA, ROLE_EXPERTISE, ROLE_GROUPS, } from './types.js';
+import { PROFILE_INFO } from './tool-config.js';
+import { SKILL_REQUIREMENTS, getSkillsByCategory } from './skill-requirements.js';
+// =============================================================================
+// Builder
+// =============================================================================
+/**
+ * Find which group a role belongs to.
+ */
+function getRoleGroup(roleId) {
+    for (const [group, roles] of Object.entries(ROLE_GROUPS)) {
+        if (roles.includes(roleId))
+            return group;
+    }
+    return 'Other';
+}
+/**
+ * Prettify a skill ID into a human-readable label.
+ * "code-review" → "Code Review", "prd" → "PRD"
+ */
+function skillLabel(id) {
+    // Special cases
+    const special = { prd: 'PRD' };
+    if (special[id])
+        return special[id];
+    return id.replace(/-/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
+}
+/**
+ * Find which category a skill belongs to.
+ */
+function getSkillCategory(skillId, categories) {
+    for (const [cat, skills] of Object.entries(categories)) {
+        if (skills.includes(skillId)) {
+            // Capitalize category name
+            return cat.charAt(0).toUpperCase() + cat.slice(1);
+        }
+    }
+    return 'Other';
+}
+/**
+ * Build the complete workshop data from SDK constants.
+ * This is a pure function — no side effects, fully testable.
+ */
+export function buildAgentWorkshopData(suggestedRolesMap) {
+    // Roles (exclude 'default' — it's the coordinator, not selectable)
+    const roles = PREDEFINED_ROLE_IDS.filter((id) => id !== 'default').map((id) => {
+        const meta = ROLE_METADATA[id];
+        return {
+            id,
+            displayName: meta.displayName,
+            mascot: meta.mascot,
+            description: meta.description,
+            group: getRoleGroup(id),
+            expertise: ROLE_EXPERTISE[id],
+            defaultToolProfile: meta.defaultToolProfile ?? 'full',
+            defaultModelTier: meta.defaultModelTier ?? 'balanced',
+        };
+    });
+    // Role groups in display order
+    const roleGroupOrder = Object.keys(ROLE_GROUPS);
+    // Tool profiles
+    const toolProfiles = Object.entries(PROFILE_INFO)
+        .filter(([id]) => id !== 'custom') // Custom is handled separately in UI
+        .map(([id, info]) => ({
+        id,
+        label: info.label,
+        description: info.description,
+        isReadOnly: info.isReadOnly,
+    }));
+    // Model tiers
+    const modelTiers = [
+        { id: 'fast', label: 'Fast', description: 'Quick responses, lower cost' },
+        {
+            id: 'balanced',
+            label: 'Balanced',
+            description: 'Best mix of speed and capability (default)',
+        },
+        { id: 'powerful', label: 'Powerful', description: 'Best reasoning for complex tasks' },
+    ];
+    // Skills
+    const categories = getSkillsByCategory();
+    const skills = Object.entries(SKILL_REQUIREMENTS).map(([id, req]) => ({
+        id,
+        label: skillLabel(id),
+        category: getSkillCategory(id, categories),
+        requiredTools: req.required,
+        optionalTools: req.optional ?? [],
+    }));
+    const skillCategories = Object.keys(categories).map((c) => c.charAt(0).toUpperCase() + c.slice(1));
+    return {
+        roles,
+        roleGroupOrder,
+        suggestedRoles: suggestedRolesMap ?? {},
+        toolProfiles,
+        modelTiers,
+        skills,
+        skillCategories,
+    };
+}
+/**
+ * Build the suggested roles map from project type configs.
+ * Call this from the host app (needs access to PROJECT_TYPES).
+ */
+export function buildSuggestedRolesMap(projectTypes) {
+    const map = {};
+    for (const pt of projectTypes) {
+        if (pt.suggestedAgents) {
+            map[pt.id] = pt.suggestedAgents.map((a) => a.role);
+        }
+    }
+    return map;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compilr-dev/sdk",
-  "version": "0.9.12",
+  "version": "0.9.14",
   "description": "Universal agent runtime for building AI-powered applications",
   "type": "module",
   "main": "dist/index.js",