@compilr-dev/sdk 0.25.1 → 0.27.0

package/dist/skills/{software-skills.js → software-macros.js}

@@ -1,5 +1,5 @@
 /**
- * Software Development Skills
+ * Software Development Macros
  *
  * design, sketch, prd, refine, refine-item, architecture, session-notes, build, scaffold
  */
@@ -7,7 +7,7 @@ import { defineSkill } from '@compilr-dev/agents';
 // =============================================================================
 // From @compilr-dev/agents (7 skills)
 // =============================================================================
-export const designSkill = defineSkill({
+export const designMacro = defineSkill({
     name: 'design',
     description: 'Interactive requirements gathering session that produces 5-15 actionable backlog items. Use when starting a new project from scratch or when the user has an idea but no clear requirements. Asks structured questions about goals, users, features, and constraints.',
     prompt: `You are in DESIGN MODE. Your goal is to gather enough information to populate the project backlog with 5-15 actionable items.
@@ -92,7 +92,7 @@ When you have enough information:
 ✓ User has approved the backlog`,
     tags: ['planning', 'requirements'],
 });
-export const refineSkill = defineSkill({
+export const refineMacro = defineSkill({
     name: 'refine',
     description: 'Iteratively refine and expand existing project requirements. Use when the project already has an initial design or backlog but needs deeper detail, edge cases, or new features explored. Walks through each area asking targeted follow-up questions.',
     prompt: `You are in REFINE MODE. Your goal is to deepen and expand existing requirements based on user feedback.
@@ -171,7 +171,7 @@ For complex features:
 ✓ No open questions remain`,
     tags: ['planning', 'requirements'],
 });
-export const sketchSkill = defineSkill({
+export const sketchMacro = defineSkill({
     name: 'sketch',
     description: 'Quick lightweight project outline using a few simple questions. Use for rapid brainstorming or when the user wants a fast first pass before committing to a full design session. Produces a high-level summary, not detailed backlog items.',
     prompt: `You are in SKETCH MODE. Ask 6 quick questions, then create backlog items.
@@ -210,7 +210,7 @@ RULES:
 - For fresh projects, ALWAYS add CHORE-001 scaffolding as first item`,
     tags: ['planning', 'requirements'],
 });
-export const refineItemSkill = defineSkill({
+export const refineItemMacro = defineSkill({
     name: 'refine-item',
     description: 'Deep-dive refinement of a single backlog work item. Use when an item needs more detail — acceptance criteria, implementation notes, subtask breakdown, or dependency analysis. Reads the item from the database and produces an updated version.',
     prompt: `You are in FOCUSED REFINE MODE. Your goal is to refine a specific backlog item.
@@ -278,7 +278,7 @@ Based on user's choice:
 ✓ Changes are summarized`,
     tags: ['planning', 'requirements'],
 });
-export const architectureSkill = defineSkill({
+export const architectureMacro = defineSkill({
     name: 'architecture',
     description: 'Create or update architecture documentation including ADRs, system diagrams, data models, and API designs. Use after requirements are defined. Reads the current backlog and project documents to produce architecture artifacts stored as project documents.',
     prompt: `You are in ARCHITECTURE MODE. Your goal is to create architecture documentation.
@@ -423,7 +423,7 @@ Generate appropriate documentation.
 ✓ User has reviewed the output`,
     tags: ['architecture', 'documentation'],
 });
-export const prdSkill = defineSkill({
+export const prdMacro = defineSkill({
     name: 'prd',
     description: 'Create, amend, or enhance the Product Requirements Document. Use when formalizing requirements into a structured PRD with sections for overview, user personas, functional requirements, non-functional requirements, and success metrics. Stored as a project document.',
     prompt: `You are in PRD MODE. Your goal is to update or enhance the existing Product Requirements Document.
@@ -508,7 +508,7 @@ Based on section selected:
 ✓ Related backlog updates are suggested if needed`,
     tags: ['planning', 'requirements'],
 });
-export const sessionNotesSkill = defineSkill({
+export const sessionNotesMacro = defineSkill({
     name: 'session-notes',
     description: 'Create structured session notes capturing work done, decisions made, and open questions. Use at the end of a work session to document progress. Reviews conversation history and produces a formatted summary stored as a project document.',
     prompt: `You are in SESSION NOTES MODE. Your goal is to create a structured summary of the current session.
@@ -602,7 +602,7 @@ CRITICAL: session notes are database documents. NEVER write a .md file (no write
 ✓ User has reviewed the note`,
     tags: ['documentation', 'session'],
 });
-export const buildSkill = defineSkill({
+export const buildMacro = defineSkill({
     name: 'build',
     description: 'Implement a backlog work item end-to-end — read requirements, write code, run tests, and update the item status. Use when an item is ready to build. Follows a structured workflow: understand → plan → implement → verify → mark complete.',
     tags: ['implementation', 'coding'],
@@ -699,7 +699,7 @@ Before implementing, read these files for context:
 - Always run tests before marking complete`,
     version: '1.0.0',
 });
-export const scaffoldSkill = defineSkill({
+export const scaffoldMacro = defineSkill({
     name: 'scaffold',
     description: 'Generate a complete project scaffold from the Application Model or tech stack selection. Use after the design phase to create the initial codebase — directory structure, configuration, boilerplate, and starter components. Supports multiple toolkits (React+Node, Next+Prisma, FastAPI, Go, static landing).',
     tags: ['setup', 'foundation', 'scaffolding'],

package/dist/skills/types.d.ts

@@ -86,5 +86,5 @@ export interface CustomSkill {
  * A second copy of a list is a list that will disagree with the first. Deriving it costs one
  * import and cannot go stale.
  */
-export declare const RESERVED_SKILL_NAMES: readonly string[];
-export declare function isReservedSkillName(name: string): boolean;
+export declare const RESERVED_MACRO_NAMES: readonly string[];
+export declare function isReservedMacroName(name: string): boolean;

package/dist/skills/types.js

@@ -9,7 +9,7 @@
  * extensions live under the optional `compilr:` block, which
  * Anthropic-compatible runtimes ignore.
  */
-import { platformSkills } from './platform-skills.js';
+import { platformMacros } from './platform-macros.js';
 /**
  * SDK skill names that are reserved — user/project skills cannot use these.
  *
@@ -27,7 +27,7 @@ import { platformSkills } from './platform-skills.js';
  * A second copy of a list is a list that will disagree with the first. Deriving it costs one
  * import and cannot go stale.
  */
-export const RESERVED_SKILL_NAMES = platformSkills.map((s) => s.name);
-export function isReservedSkillName(name) {
-    return RESERVED_SKILL_NAMES.includes(name);
+export const RESERVED_MACRO_NAMES = platformMacros.map((s) => s.name);
+export function isReservedMacroName(name) {
+    return RESERVED_MACRO_NAMES.includes(name);
 }

package/dist/team/agent-templates.d.ts

@@ -21,7 +21,6 @@ export interface AgentTemplate {
     personality?: string;
     systemPromptAddition?: string;
     toolProfile?: string;
-    enabledSkills?: string[];
     modelTier?: string;
 }
 /** List all saved templates */

package/dist/team/agent-templates.js

@@ -60,7 +60,6 @@ export function saveTemplate(name, agent, description) {
         personality: agent.personality,
         systemPromptAddition: agent.systemPromptAddition,
         toolProfile: agent.toolConfig?.profile,
-        enabledSkills: agent.enabledSkills,
         modelTier: agent.modelTier,
     };
     templates.push(template);
@@ -101,7 +100,6 @@ export function createAgentFromTemplate(template, agentId, existingAgents) {
         mascot: assignMascot(existingAgents),
         createdAt: new Date().toISOString(),
         toolConfig: template.toolProfile ? { profile: template.toolProfile } : undefined,
-        enabledSkills: template.enabledSkills,
         modelTier: template.modelTier,
     };
 }

package/dist/team/custom-agents.d.ts

@@ -17,7 +17,6 @@ export interface CustomAgentDefinition {
     mascot: string;
     createdAt: string;
     toolConfig?: ToolConfig;
-    enabledSkills?: string[];
     modelTier?: ModelTier;
     /** Custom instructions appended to the agent's system prompt (max 2000 chars) */
     systemPromptAddition?: string;
@@ -97,4 +96,4 @@ export declare function isAgentIdTaken(id: string, existingCustomAgents: CustomA
 /**
  * Create a new CustomAgentDefinition with auto-assigned mascot.
  */
-export declare function createCustomAgentDefinition(id: string, displayName: string, specialty: string, personality: string | undefined, existingAgents: CustomAgentDefinition[], toolConfig?: ToolConfig, enabledSkills?: string[], modelTier?: ModelTier, systemPromptAddition?: string): CustomAgentDefinition;
+export declare function createCustomAgentDefinition(id: string, displayName: string, specialty: string, personality: string | undefined, existingAgents: CustomAgentDefinition[], toolConfig?: ToolConfig, modelTier?: ModelTier, systemPromptAddition?: string): CustomAgentDefinition;

package/dist/team/custom-agents.js

@@ -191,7 +191,7 @@ export function isAgentIdTaken(id, existingCustomAgents, teamAgentIds, predefine
 /**
  * Create a new CustomAgentDefinition with auto-assigned mascot.
  */
-export function createCustomAgentDefinition(id, displayName, specialty, personality, existingAgents, toolConfig, enabledSkills, modelTier, systemPromptAddition) {
+export function createCustomAgentDefinition(id, displayName, specialty, personality, existingAgents, toolConfig, modelTier, systemPromptAddition) {
     return {
         id,
         displayName,
@@ -200,7 +200,6 @@ export function createCustomAgentDefinition(id, displayName, specialty, personal
         mascot: assignMascot(existingAgents),
         createdAt: new Date().toISOString(),
         toolConfig: toolConfig ?? createDefaultToolConfig(),
-        enabledSkills: enabledSkills ?? [], // Empty = all skills
         modelTier: modelTier ?? 'balanced', // Default tier
         systemPromptAddition: systemPromptAddition?.trim() || undefined,
     };

package/dist/team/index.d.ts

@@ -7,6 +7,8 @@
 export { AgentTeam } from './team.js';
 export type { AgentTeamConfig } from './team.js';
 export { TeamAgent, isNarrowing, lostWriteAccess } from './team-agent.js';
+export { macroToolGap, macroToolGapPreamble } from './macro-tool-gap.js';
+export type { MacroToolGap } from './macro-tool-gap.js';
 export { mcpServerOf, filterMcpToolsByGrant, MCP_TOOL_PREFIX } from './mcp-servers.js';
 export type { TeamAgentUpdate, AgentUpdateResult } from './team-agent.js';
 export { SharedContextManager } from './shared-context.js';
@@ -24,7 +26,7 @@ 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 type { AgentWorkshopData, WorkshopRoleDef, WorkshopToolProfile, WorkshopModelTier, WorkshopMacroDef, } 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';
@@ -37,8 +39,8 @@ export { wouldCreateLoop, recordAssignment, getAssignmentHistory, clearAssignmen
 export { DelegationTracker } from './delegation-tracker.js';
 export type { Delegation, DelegationStatus, DelegationResult, CompletionEvent, CreateDelegationOptions, DelegationStats, DelegationTrackerEvents, } from './delegation-tracker.js';
 export { setActiveSharedContext, getActiveSharedContext, recordTeamActivity } from './activity.js';
-export type { SkillToolRequirement } from './skill-requirements.js';
-export { SKILL_REQUIREMENTS, getDefinedSkillNames, getSkillRequirements, checkSkillCompatibility, getCompatibleSkills, getAllRequiredTools, getSkillsByCategory, } from './skill-requirements.js';
+export type { MacroToolRequirement } from './macro-requirements.js';
+export { MACRO_REQUIREMENTS, getDefinedMacroNames, getMacroRequirements, checkMacroCompatibility, getCompatibleMacros, getAllRequiredTools, getMacrosByCategory, } from './macro-requirements.js';
 export { resolveAgentIdCollision } from './collision-utils.js';
 export { createDelegationStatusTool, createHandoffTool, createDelegateTool, createDelegateBackgroundTool, } from './delegation-tools.js';
 export type { HandoffResult, HandoffToolConfig, DelegateResult, DelegateToolConfig, DelegateBackgroundResult, DelegateBackgroundToolConfig, } from './delegation-tools.js';

package/dist/team/index.js

@@ -7,6 +7,7 @@
 // Core classes
 export { AgentTeam } from './team.js';
 export { TeamAgent, isNarrowing, lostWriteAccess } from './team-agent.js';
+export { macroToolGap, macroToolGapPreamble } from './macro-tool-gap.js';
 export { mcpServerOf, filterMcpToolsByGrant, MCP_TOOL_PREFIX } from './mcp-servers.js';
 export { SharedContextManager } from './shared-context.js';
 export { ArtifactStore } from './artifacts.js';
@@ -29,7 +30,7 @@ export { wouldCreateLoop, recordAssignment, getAssignmentHistory, clearAssignmen
 export { DelegationTracker } from './delegation-tracker.js';
 // Activity recording
 export { setActiveSharedContext, getActiveSharedContext, recordTeamActivity } from './activity.js';
-export { SKILL_REQUIREMENTS, getDefinedSkillNames, getSkillRequirements, checkSkillCompatibility, getCompatibleSkills, getAllRequiredTools, getSkillsByCategory, } from './skill-requirements.js';
+export { MACRO_REQUIREMENTS, getDefinedMacroNames, getMacroRequirements, checkMacroCompatibility, getCompatibleMacros, getAllRequiredTools, getMacrosByCategory, } from './macro-requirements.js';
 // Collision utils
 export { resolveAgentIdCollision } from './collision-utils.js';
 // Delegation & Handoff tools (factory functions)

package/dist/team/{skill-requirements.d.ts → macro-requirements.d.ts}

@@ -1,14 +1,20 @@
 /**
- * Skill Requirements Mapping
+ * Macro tool requirements.
  *
- * Maps skills to the tools they require to function properly.
- * This enables automatic filtering of incompatible skills based
- * on an agent's tool configuration.
+ * Maps each MACRO to the tools its text assumes, so an agent can be told before it starts that
+ * it cannot carry one out. A macro is a named prompt the USER invokes — `/design`, `/code-review`
+ * — which expands into a message.
+ *
+ * ⚠️ THIS IS NOT ABOUT SKILLS, DESPITE ITS FORMER NAME. It was called `MACRO_REQUIREMENTS` and
+ * rendered by `buildAgentWorkshopData` as if it were a catalogue of skills, which is how the
+ * agent editor came to offer 13 items that were all Commands. Verified: every one of the 13
+ * entries is a macro and none is an installed skill. Skills — the Anthropic kind the model
+ * chooses — declare their own requirements in `SKILL.md` under `compilr.requires`.
  */
-export interface SkillToolRequirement {
-    /** Tools that MUST be available for this skill to work */
+export interface MacroToolRequirement {
+    /** Tools that MUST be available for this macro to work */
     required: string[];
-    /** Tools that enhance this skill but aren't strictly required */
+    /** Tools that enhance this macro but aren't strictly required */
     optional?: string[];
     /** Brief description of why these tools are needed */
     reason?: string;
@@ -20,23 +26,23 @@ export interface SkillToolRequirement {
  * - Required tools: The skill will fail without these
  * - Optional tools: The skill works better with these but can function without
  */
-export declare const SKILL_REQUIREMENTS: Record<string, SkillToolRequirement>;
+export declare const MACRO_REQUIREMENTS: Record<string, MacroToolRequirement>;
 /**
  * Get all skill names that have requirements defined.
  */
-export declare function getDefinedSkillNames(): string[];
+export declare function getDefinedMacroNames(): string[];
 /**
  * Get the tool requirements for a skill.
  */
-export declare function getSkillRequirements(skillName: string): SkillToolRequirement | undefined;
+export declare function getMacroRequirements(macroName: string): MacroToolRequirement | undefined;
 /**
  * Check if a skill is compatible with a set of available tools.
  *
- * @param skillName - Name of the skill to check
+ * @param macroName - Name of the macro to check
  * @param availableTools - Set of tool names available to the agent
  * @returns Object with compatibility status and missing tools
  */
-export declare function checkSkillCompatibility(skillName: string, availableTools: Set<string> | string[]): {
+export declare function checkMacroCompatibility(macroName: string, availableTools: Set<string> | string[]): {
     compatible: boolean;
     missingRequired: string[];
     missingOptional: string[];
@@ -48,7 +54,7 @@ export declare function checkSkillCompatibility(skillName: string, availableTool
  * @param allSkillNames - All skill names to check (default: defined skills)
  * @returns Object with compatible and incompatible skill names
  */
-export declare function getCompatibleSkills(availableTools: Set<string> | string[], allSkillNames?: string[]): {
+export declare function getCompatibleMacros(availableTools: Set<string> | string[], allMacroNames?: string[]): {
     compatible: string[];
     incompatible: Array<{
         name: string;
@@ -63,4 +69,4 @@ export declare function getAllRequiredTools(): string[];
 /**
  * Get skills grouped by their primary category.
  */
-export declare function getSkillsByCategory(): Record<string, string[]>;
+export declare function getMacrosByCategory(): Record<string, string[]>;

package/dist/team/{skill-requirements.js → macro-requirements.js}

@@ -1,12 +1,18 @@
 /**
- * Skill Requirements Mapping
+ * Macro tool requirements.
  *
- * Maps skills to the tools they require to function properly.
- * This enables automatic filtering of incompatible skills based
- * on an agent's tool configuration.
+ * Maps each MACRO to the tools its text assumes, so an agent can be told before it starts that
+ * it cannot carry one out. A macro is a named prompt the USER invokes — `/design`, `/code-review`
+ * — which expands into a message.
+ *
+ * ⚠️ THIS IS NOT ABOUT SKILLS, DESPITE ITS FORMER NAME. It was called `MACRO_REQUIREMENTS` and
+ * rendered by `buildAgentWorkshopData` as if it were a catalogue of skills, which is how the
+ * agent editor came to offer 13 items that were all Commands. Verified: every one of the 13
+ * entries is a macro and none is an installed skill. Skills — the Anthropic kind the model
+ * chooses — declare their own requirements in `SKILL.md` under `compilr.requires`.
  */
 // =============================================================================
-// Skill Requirements
+// Macro Requirements
 // =============================================================================
 /**
  * Maps skill names to their tool requirements.
@@ -15,7 +21,7 @@
  * - Required tools: The skill will fail without these
  * - Optional tools: The skill works better with these but can function without
  */
-export const SKILL_REQUIREMENTS = {
+export const MACRO_REQUIREMENTS = {
     // Development skills
     'code-review': {
         required: ['read_file', 'glob', 'grep'],
@@ -104,33 +110,33 @@ export const SKILL_REQUIREMENTS = {
 /**
  * Get all skill names that have requirements defined.
  */
-export function getDefinedSkillNames() {
-    return Object.keys(SKILL_REQUIREMENTS);
+export function getDefinedMacroNames() {
+    return Object.keys(MACRO_REQUIREMENTS);
 }
 /**
  * Get the tool requirements for a skill.
  */
-export function getSkillRequirements(skillName) {
-    return SKILL_REQUIREMENTS[skillName];
+export function getMacroRequirements(macroName) {
+    return MACRO_REQUIREMENTS[macroName];
 }
 /**
  * Check if a skill is compatible with a set of available tools.
  *
- * @param skillName - Name of the skill to check
+ * @param macroName - Name of the macro to check
  * @param availableTools - Set of tool names available to the agent
  * @returns Object with compatibility status and missing tools
  */
-export function checkSkillCompatibility(skillName, availableTools) {
+export function checkMacroCompatibility(macroName, availableTools) {
     const toolSet = availableTools instanceof Set ? availableTools : new Set(availableTools);
     // If no requirements defined, assume compatible
-    if (!(skillName in SKILL_REQUIREMENTS)) {
+    if (!(macroName in MACRO_REQUIREMENTS)) {
         return {
             compatible: true,
             missingRequired: [],
             missingOptional: [],
         };
     }
-    const requirement = SKILL_REQUIREMENTS[skillName];
+    const requirement = MACRO_REQUIREMENTS[macroName];
     const missingRequired = requirement.required.filter((t) => !toolSet.has(t));
     const missingOptional = (requirement.optional ?? []).filter((t) => !toolSet.has(t));
     return {
@@ -146,18 +152,18 @@ export function checkSkillCompatibility(skillName, availableTools) {
  * @param allSkillNames - All skill names to check (default: defined skills)
  * @returns Object with compatible and incompatible skill names
  */
-export function getCompatibleSkills(availableTools, allSkillNames) {
-    const skillNames = allSkillNames ?? getDefinedSkillNames();
+export function getCompatibleMacros(availableTools, allMacroNames) {
+    const macroNames = allMacroNames ?? getDefinedMacroNames();
     const compatible = [];
     const incompatible = [];
-    for (const skillName of skillNames) {
-        const result = checkSkillCompatibility(skillName, availableTools);
+    for (const macroName of macroNames) {
+        const result = checkMacroCompatibility(macroName, availableTools);
         if (result.compatible) {
-            compatible.push(skillName);
+            compatible.push(macroName);
         }
         else {
             incompatible.push({
-                name: skillName,
+                name: macroName,
                 missingTools: result.missingRequired,
             });
         }
@@ -170,7 +176,7 @@ export function getCompatibleSkills(availableTools, allSkillNames) {
  */
 export function getAllRequiredTools() {
     const allTools = new Set();
-    for (const requirement of Object.values(SKILL_REQUIREMENTS)) {
+    for (const requirement of Object.values(MACRO_REQUIREMENTS)) {
         for (const tool of requirement.required) {
             allTools.add(tool);
         }
@@ -180,7 +186,7 @@ export function getAllRequiredTools() {
 /**
  * Get skills grouped by their primary category.
  */
-export function getSkillsByCategory() {
+export function getMacrosByCategory() {
     return {
         development: ['code-review', 'debug', 'explain', 'refactor'],
         security: ['security-review'],

package/dist/team/macro-tool-gap.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Telling an agent, up front, that a macro needs tools it does not have.
+ *
+ * ⚠️ A MACRO'S TEXT ASSUMES TOOLS, AND NOTHING CHECKED. `/design` instructs the agent to use
+ * `ask_user` and `workitem_add`; sent to an agent that cannot reach those, it announces it is
+ * starting a requirements session and then fails partway, having already promised the user
+ * something it cannot deliver. The failure surfaces as the agent being broken rather than as a
+ * mismatch anyone can act on.
+ *
+ * The data for this has existed all along — `MACRO_REQUIREMENTS` carries `required`, `optional`
+ * and a written `reason` per macro, and `checkMacroCompatibility` does the comparison. Between
+ * them they had exactly one caller: a display hint in the CLI's agent wizard.
+ *
+ * ⚠️ THE WARNING GOES TO THE AGENT, NOT THE USER. A host-side dialog stops the user at a moment
+ * they cannot resolve — they do not know which tools `/design` needs or which teammate has them.
+ * The agent does know, once told, and is where the user is already looking: it can explain in one
+ * sentence and suggest the handoff.
+ */
+export interface MacroToolGap {
+    /** Tools the macro cannot work without. Non-empty whenever a gap is reported. */
+    missingRequired: string[];
+    /** Tools the macro uses when present. Reported so the agent can say what it will skip. */
+    missingOptional: string[];
+    /** The macro's own stated reason for needing them, from MACRO_REQUIREMENTS. */
+    reason: string;
+}
+/**
+ * What this macro needs and this agent lacks, or `null` when there is nothing to say.
+ *
+ * `null` for an unknown macro is deliberate: only 13 have declared requirements, so silence means
+ * "not described", never "verified fine". Warning on an undeclared macro would train people to
+ * ignore the warning.
+ */
+export declare function macroToolGap(macroName: string, availableTools: Set<string> | readonly string[]): MacroToolGap | null;
+/**
+ * A preamble to prepend to the macro's message, addressed to the agent.
+ *
+ * ⚠️ IT TELLS THE AGENT WHAT TO DO, NOT JUST WHAT IS WRONG. "You lack write_file" invites it to
+ * try anyway and fail at the first call. Naming the consequence and the recovery — say so, offer
+ * the handoff — is what turns a broken turn into a useful one.
+ */
+export declare function macroToolGapPreamble(macroName: string, gap: MacroToolGap): string;

package/dist/team/macro-tool-gap.js

@@ -0,0 +1,69 @@
+/**
+ * Telling an agent, up front, that a macro needs tools it does not have.
+ *
+ * ⚠️ A MACRO'S TEXT ASSUMES TOOLS, AND NOTHING CHECKED. `/design` instructs the agent to use
+ * `ask_user` and `workitem_add`; sent to an agent that cannot reach those, it announces it is
+ * starting a requirements session and then fails partway, having already promised the user
+ * something it cannot deliver. The failure surfaces as the agent being broken rather than as a
+ * mismatch anyone can act on.
+ *
+ * The data for this has existed all along — `MACRO_REQUIREMENTS` carries `required`, `optional`
+ * and a written `reason` per macro, and `checkMacroCompatibility` does the comparison. Between
+ * them they had exactly one caller: a display hint in the CLI's agent wizard.
+ *
+ * ⚠️ THE WARNING GOES TO THE AGENT, NOT THE USER. A host-side dialog stops the user at a moment
+ * they cannot resolve — they do not know which tools `/design` needs or which teammate has them.
+ * The agent does know, once told, and is where the user is already looking: it can explain in one
+ * sentence and suggest the handoff.
+ */
+import { MACRO_REQUIREMENTS, checkMacroCompatibility } from './macro-requirements.js';
+/**
+ * What this macro needs and this agent lacks, or `null` when there is nothing to say.
+ *
+ * `null` for an unknown macro is deliberate: only 13 have declared requirements, so silence means
+ * "not described", never "verified fine". Warning on an undeclared macro would train people to
+ * ignore the warning.
+ */
+export function macroToolGap(macroName, availableTools) {
+    if (!(macroName in MACRO_REQUIREMENTS))
+        return null;
+    const { missingRequired, missingOptional } = checkMacroCompatibility(macroName, [
+        ...availableTools,
+    ]);
+    // Optional tools alone are not worth interrupting for — the macro still works without them.
+    if (missingRequired.length === 0)
+        return null;
+    return {
+        missingRequired,
+        missingOptional,
+        // Every entry carries one; the fallback exists because the index signature cannot say so.
+        reason: MACRO_REQUIREMENTS[macroName].reason ?? 'carry out this workflow',
+    };
+}
+/**
+ * A preamble to prepend to the macro's message, addressed to the agent.
+ *
+ * ⚠️ IT TELLS THE AGENT WHAT TO DO, NOT JUST WHAT IS WRONG. "You lack write_file" invites it to
+ * try anyway and fail at the first call. Naming the consequence and the recovery — say so, offer
+ * the handoff — is what turns a broken turn into a useful one.
+ */
+export function macroToolGapPreamble(macroName, gap) {
+    const missing = gap.missingRequired.join(', ');
+    const alsoMissing = gap.missingOptional.length > 0
+        ? ` It also uses ${gap.missingOptional.join(', ')}, which you do not have.`
+        : '';
+    /*
+      The stored reasons are written as "Needs to gather requirements and create backlog", so
+      splicing one in after "needs them to" reads "needs them to: Needs to gather…". Strip the
+      lead-in rather than rewrite 13 table entries whose phrasing is fine on its own.
+    */
+    const purpose = gap.reason.replace(/^\s*needs?\s+to\s+/i, '').replace(/\.$/, '');
+    return [
+        `[System] The /${macroName} workflow below needs tools you do not have: ${missing}.`,
+        `It needs them to ${purpose}.${alsoMissing}`,
+        '',
+        'Do NOT start the workflow and fail partway. Tell the user in one or two sentences what you ' +
+            'cannot do and why, and if a teammate has those tools, suggest handing off to them. ' +
+            'If part of the workflow is still useful without those tools, say which part and offer it.',
+    ].join('\n');
+}

package/dist/team/team-agent.d.ts

@@ -67,9 +67,10 @@ export interface TeamAgentUpdate {
     personality?: string;
     toolProfile?: TeamAgentConfig['toolProfile'];
     toolFilter?: string[];
-    enabledSkills?: string[];
     /** Which MCP servers this agent may reach. See `TeamAgent.mcpServers`. */
     mcpServers?: string[];
+    /** Which Skills this agent may choose. See `TeamAgent.grantedSkills`. */
+    grantedSkills?: string[];
 }
 /** What an edit did, and whether anyone needs telling. */
 export interface AgentUpdateResult {
@@ -187,6 +188,19 @@ export declare class TeamAgent {
      * from the profile name alone.
      */
     customGroups?: string[];
+    /**
+     * Skills this agent may CHOOSE. `undefined` = never asked, reaches everything eligible;
+     * `[]` = granted nothing. Same contract as `mcpServers`.
+     *
+     * ⚠️ THERE USED TO BE A SECOND FIELD, `enabledSkills`, AND IT HELD SOMETHING ELSE ENTIRELY.
+     * MACRO ids — the 13 its picker offered were `code-review`, `debug`, `design`, `prd` and
+     * friends, all things a user types. 0.25.0 wired Skills enforcement onto it and produced a
+     * live hazard: ticking "Code Review" wrote a name no installed skill has, so the agent
+     * silently got zero skills. It is deleted now. The MCP-style reading is legitimate HERE
+     * only because this
+     * field is new and nothing has a prior meaning.
+     */
+    grantedSkills?: string[];
     /**
      * MCP servers this agent may reach. `undefined` = a pre-grants agent, which reaches all;
      * `[]` = granted nothing. See `TeamAgentConfig.mcpServers`.
@@ -199,7 +213,6 @@ export declare class TeamAgent {
     /**
      * Enabled skills (empty = all skills)
      */
-    enabledSkills?: string[];
     /**
      * How the agent should sound. Tone only — never capability.
      *