@compilr-dev/sdk 0.26.0 → 0.28.0

package/dist/actions/registry.d.ts

@@ -1,7 +1,7 @@
 /**
  * Action Registry — Defines which actions are available and where.
  *
- * Each action maps to a skill (from platformSkills/builtinSkills)
+ * Each action maps to a skill (from platformMacros/builtinSkills)
  * but adds UI metadata: icon, label, category, applicable contexts,
  * and suggested agent role.
  */

package/dist/actions/registry.js

@@ -1,7 +1,7 @@
 /**
  * Action Registry — Defines which actions are available and where.
  *
- * Each action maps to a skill (from platformSkills/builtinSkills)
+ * Each action maps to a skill (from platformMacros/builtinSkills)
  * but adds UI metadata: icon, label, category, applicable contexts,
  * and suggested agent role.
  */

package/dist/guide/shared-content.js

@@ -115,20 +115,53 @@ The delegated agent runs independently and returns results to the coordinator.`,
     },
     // ── Skills ──────────────────────────────────────────────────────────────
     {
-        id: 'skills-overview',
-        title: 'Skills Overview',
-        keywords: ['skills', 'slash', 'command', '/'],
-        content: `Skills are pre-built prompts that guide the agent through specific workflows.
+        id: 'macros-overview',
+        title: 'Macros Overview',
+        keywords: ['macros', 'macro', 'skills', 'slash', 'command', '/'],
+        content: `Macros are pre-built prompts that guide the agent through specific workflows. You
+invoke one; it expands into a message.
 
-Use them by typing / followed by the skill name (e.g., /design, /build).
+Use them by typing / followed by the macro name (e.g., /design, /build).
 
-Skills vary by project type. Software projects have: /design, /sketch, /prd, /architecture, /scaffold, /build, /refine, /session-notes.
+Macros vary by project type. Software projects have: /design, /sketch, /prd, /architecture, /scaffold, /build, /refine, /session-notes.
 
 Research projects have: /research-scaffold, /outline, /literature-review, /draft-section, /peer-review.
 
 Business projects have: /business-vision, /market-analysis, /competitor-analysis, /financial-model, /pitch-outline, /business-review.
 
-Skills can be combined with your own instructions: type /design then add context.`,
+Macros can be combined with your own instructions: type /design then add context.
+
+**Macros are not Skills.** A macro is text YOU trigger. A Skill is a capability the MODEL
+chooses from a catalogue and loads when it decides it is relevant — see "Skills". They were
+called the same thing until recently, which is why older notes use "skill" for both.`,
+    },
+    {
+        id: 'skills',
+        title: 'Skills — Capabilities the Model Chooses',
+        keywords: ['skill', 'skills', 'SKILL.md', 'anthropic', 'agent skills', 'catalogue', 'grant'],
+        content: `A Skill is a capability the MODEL picks up when it decides the work calls for it —
+not something you type.
+
+Each agent is shown a CATALOGUE: one line per skill, name and description only. When the agent
+judges a skill relevant it loads the body then, and not before, so an unused skill costs a line
+of context rather than a document.
+
+**Where they live**
+- User scope: ~/.compilr-dev/skills/<name>/SKILL.md — personal, every project
+- Project scope: <project>/.compilr/skills/<name>/SKILL.md — shared via version control
+
+The format is Anthropic's Agent Skills format: YAML frontmatter (name, description) and a
+markdown body. We read the frontmatter and the body; bundled references/, scripts/, templates/
+and assets/ are not read yet.
+
+**Granting them per agent**
+In the agent editor's Skills section, tick the skills an agent may choose from. An agent you have
+never restricted may choose any installed skill; once you save a selection it is limited to
+exactly what is ticked, and an empty selection grants none.
+
+**Skills are not macros.** A macro (/design, /build) is text YOU trigger. A skill is something
+the model reaches for on its own. A skill you install is also typeable as a slash command, so one
+folder can serve both purposes — see "Custom Skills".`,
     },
     {
         id: 'custom-skills',
@@ -157,8 +190,8 @@ A folder with a SKILL.md file containing YAML frontmatter (name, description) an
 
 **Desktop:** The Agents panel has a Skills section showing custom skills. Click the maximize button to open the SkillsView tab with full management (create, fork, bind/unbind, enable/disable, delete). Click a skill name to view/edit in the code editor.
 
-**Forking SDK skills:**
-You cannot override built-in skills directly. Instead, fork them: this creates a copy with your changes. Then bind a slash command to your fork (e.g., /design → design-acme). The capability bundle still loads based on the command name.
+**Forking shipped macros:**
+You cannot override a shipped macro directly — its name is reserved, so creating one is refused. Fork it instead: that copies it, and you edit the copy. Then bind a slash command to your fork (e.g., /design → design-acme).
 
 **Bindings:**
 Bindings remap slash commands to custom skills. Example: bind /design to your forked design-acme skill. When you type /design, it uses your custom prompt instead of the SDK version. Use the Bindings tab/section to manage them.

package/dist/index.d.ts

@@ -36,10 +36,10 @@
 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, createDelegationStatusTool, createHandoffTool, createDelegateTool, createDelegateBackgroundTool, buildHandoffTaskMessage, validateHandoffIntent, HandoffStash, createConsultTool, buildConsultQuestionMessage, ROLE_NAME_ALIASES, normalizeRoleName, isNarrowing, lostWriteAccess, } from './team/index.js';
-export type { AgentTeamConfig, TeamAgentConfig, TeamAgentUpdate, AgentUpdateResult, 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, HandoffResult, HandoffToolConfig, HandoffIntent, HandoffValidationResult, DelegateResult, DelegateToolConfig, DelegateBackgroundResult, DelegateBackgroundToolConfig, ConsultInput, ConsultResult, ConsultToolConfig, NormalizedRole, SkillToolRequirement, } 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, mcpServerOf, filterMcpToolsByGrant, MCP_TOOL_PREFIX, 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, macroToolGap, macroToolGapPreamble, getCompatibleSkills, getAllRequiredTools, getSkillsByCategory, } from './team/index.js';
+export type { AgentTeamConfig, TeamAgentConfig, TeamAgentUpdate, AgentUpdateResult, ITeamPersistence, IArtifactStorage, ISessionRegistry, CustomAgentDefinition, AgentTemplate, AgentWorkshopData, WorkshopRoleDef, WorkshopToolProfile, WorkshopModelTier, WorkshopMacroDef, 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, HandoffResult, HandoffToolConfig, HandoffIntent, HandoffValidationResult, DelegateResult, DelegateToolConfig, DelegateBackgroundResult, DelegateBackgroundToolConfig, ConsultInput, ConsultResult, ConsultToolConfig, NormalizedRole, } from './team/index.js';
+export { ROLE_METADATA, ROLE_EXPERTISE, ROLE_GROUPS, PREDEFINED_ROLE_IDS, TOOL_GROUPS, TOOL_PROFILES, PROFILE_INFO, MACRO_REQUIREMENTS, getDefinedMacroNames, getMacroRequirements, getCompatibleMacros, getMacrosByCategory, 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, mcpServerOf, filterMcpToolsByGrant, MCP_TOOL_PREFIX, 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, checkMacroCompatibility, macroToolGap, macroToolGapPreamble, getAllRequiredTools, } from './team/index.js';
 export { codingPreset, readOnlyPreset, resolvePreset } from './presets/index.js';
 export type { Preset } from './presets/index.js';
 export type { AnyTool } from './presets/types.js';
@@ -68,16 +68,20 @@ export { createPlatformTools, createProjectTools, createWorkItemTools, createDoc
 export type { ProjectAnchorStoreConfig, FileArtifactServiceConfig, ImageToolsConfig, ImageResizer, } from './platform/index.js';
 export { STEP_ORDER, GUIDED_STEP_CRITERIA, getNextStep, isValidTransition, getStepCriteria, formatStepDisplay, getStepNumber, } from './platform/index.js';
 export type { CustomSkill, CompilrSkillExtension, ForkedFromMarker, SkillEligibilityContext, SkillCollision, SkillDiffLine, SkillValidationIssue, ScopeConfig, SkillResolution, } from './skills/index.js';
-export { RESERVED_SKILL_NAMES, isReservedSkillName, parseSkillMarkdown, loadSkillsFromDir, loadInstalledSkills, resolveLayeredSkills, resolveSkillsForAgent, resolveSkillsForTeamAgent, detectCollisions, formatCollisionWarnings, diffForkVsUpstream, buildForkContent, buildNewSkillContent, validateSkill as validateSkillQuality, getSkillsDir, getSkillFolder, getSkillFile, ensureSkillsDir, isValidSkillName, getScopeConfigPath, readSkillScopeConfig, readSkillScopeConfigSync, writeSkillScopeConfig, getSkillBindings, resolveSkillBinding, } from './skills/index.js';
+export { RESERVED_MACRO_NAMES, isReservedMacroName, parseSkillMarkdown, loadSkillsFromDir, loadInstalledSkills, resolveLayeredSkills, resolveSkillsForAgent, resolveSkillsForTeamAgent, detectCollisions, formatCollisionWarnings, diffForkVsUpstream, buildForkContent, buildNewSkillContent, validateSkill as validateSkillQuality, getSkillsDir, getSkillFolder, getSkillFile, ensureSkillsDir, isValidSkillName, getScopeConfigPath, readSkillScopeConfig, readSkillScopeConfigSync, writeSkillScopeConfig, getSkillBindings, resolveSkillBinding, } from './skills/index.js';
 export type { SkillScope, SkillPromptResolution, AvailableSkillEntry, SkillSources, } from './skills/index.js';
 export { resolveSkillPrompt, getAllAvailableSkills } from './skills/index.js';
+export { buildMacroList } from './skills/index.js';
+export { buildMacroInvocation } from './skills/index.js';
+export type { MacroInvocation, MacroInvocationContext, MacroProjectContext, } from './skills/index.js';
+export type { MacroListEntry, BuildMacroListOptions } from './skills/index.js';
 export { generateSkillCatalog, toCatalogEntry, createLoadSkillTool } from './skills/index.js';
 export type { SkillCatalogEntry, SkillSource } from './skills/index.js';
-export { platformSkills, designSkill, sketchSkill, prdSkill, refineSkill, refineItemSkill, architectureSkill, sessionNotesSkill, buildSkill, scaffoldSkill, outlineSkill, literatureReviewSkill, draftSectionSkill, peerReviewSkill, researchScaffoldSkill, businessVisionSkill, marketAnalysisSkill, competitorAnalysisSkill, financialModelSkill, pitchOutlineSkill, businessReviewSkill, brandSetupSkill, contentStrategySkill, contentCalendarSkill, createContentSkill, contentReviewSkill, curriculumDesignSkill, lessonPlanSkill, assessmentDesignSkill, courseReviewSkill, bookOutlineSkill, characterDesignSkill, plotThreadsSkill, sceneBreakdownSkill, bookReviewSkill, } from './skills/index.js';
+export { platformMacros, designMacro, sketchMacro, prdMacro, refineMacro, refineItemMacro, architectureMacro, sessionNotesMacro, buildMacro, scaffoldMacro, outlineMacro, literatureReviewMacro, draftSectionMacro, peerReviewMacro, researchScaffoldMacro, businessVisionMacro, marketAnalysisMacro, competitorAnalysisMacro, financialModelMacro, pitchOutlineMacro, businessReviewMacro, brandSetupMacro, contentStrategyMacro, contentCalendarMacro, createContentMacro, contentReviewMacro, curriculumDesignMacro, lessonPlanMacro, assessmentDesignMacro, courseReviewMacro, bookOutlineMacro, characterDesignMacro, plotThreadsMacro, sceneBreakdownMacro, bookReviewMacro, } from './skills/index.js';
 export { ACTION_REGISTRY, getActionsForContext, getActionById, resolveActionPrompt, buildContextSummary, getSuggestedRole, } from './actions/index.js';
 export type { ActionContext, ActionDefinition } from './actions/index.js';
-export { PROJECT_TYPES, getProjectTypeConfig, getEnrichedProjectTypeConfig, getProjectTypesByCategory, generalConfig, softwareConfig, researchConfig, businessPlanConfig, contentConfig, techDocsConfig, courseConfig, ACTION_META_REGISTRY, SKILL_META_REGISTRY, resolveActionMeta, getSkillMeta, getAllSkillMeta, } from './project-types/index.js';
-export type { ActionMeta, SkillMeta } from './project-types/index.js';
+export { PROJECT_TYPES, getProjectTypeConfig, getEnrichedProjectTypeConfig, getProjectTypesByCategory, generalConfig, softwareConfig, researchConfig, businessPlanConfig, contentConfig, techDocsConfig, courseConfig, MACRO_META_REGISTRY, resolveActionMeta, getRelevantMacros, getMacroMeta, getAllMacroMeta, } from './project-types/index.js';
+export type { ActionMeta, MacroMeta, MacroCategory, MacroCapabilities, } from './project-types/index.js';
 export type { ProjectTypeConfig, ProjectPhase, SuggestedAgent, DocumentTemplate, } from './project-types/index.js';
 export { defineTool, createSuccessResult, createErrorResult, mergeHooks, createLoggingHooks, createClaudeProvider, createOpenAIProvider, createGeminiNativeProvider, createOllamaProvider, createTogetherProvider, createGroqProvider, createFireworksProvider, createPerplexityProvider, createOpenRouterProvider, createMockProvider, MockProvider, Agent, ContextManager, DEFAULT_CONTEXT_CONFIG, createTaskTool, createSuggestTool, defaultAgentTypes, TOOL_SETS, BUILTIN_GUARDRAILS, TOOL_NAMES, getDefaultShellManager, builtinSkills, AnchorManager, MCPManager, AgentError, ProviderError, ToolError, ToolTimeoutError, MaxIterationsError, AbortError, } from '@compilr-dev/agents';
 export { classifyAgentError, isApiKeyError } from './errors/classify.js';

package/dist/index.js

@@ -43,7 +43,7 @@ export { createCompilrAgent } from './agent.js';
 // Core classes
 export { AgentTeam, TeamAgent, SharedContextManager, ArtifactStore, DelegationTracker, ContextResolver, createDelegationStatusTool, createHandoffTool, createDelegateTool, createDelegateBackgroundTool, buildHandoffTaskMessage, validateHandoffIntent, HandoffStash, createConsultTool, buildConsultQuestionMessage, ROLE_NAME_ALIASES, normalizeRoleName, isNarrowing, lostWriteAccess, } from './team/index.js';
 // Constants
-export { ROLE_METADATA, ROLE_EXPERTISE, ROLE_GROUPS, PREDEFINED_ROLE_IDS, TOOL_GROUPS, TOOL_PROFILES, PROFILE_INFO, SKILL_REQUIREMENTS, CUSTOM_MASCOTS, buildAgentWorkshopData, buildSuggestedRolesMap, 
+export { ROLE_METADATA, ROLE_EXPERTISE, ROLE_GROUPS, PREDEFINED_ROLE_IDS, TOOL_GROUPS, TOOL_PROFILES, PROFILE_INFO, MACRO_REQUIREMENTS, getDefinedMacroNames, getMacroRequirements, getCompatibleMacros, getMacrosByCategory, 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
@@ -67,7 +67,7 @@ resolveAgentIdCollision,
 // Activity
 setActiveSharedContext, getActiveSharedContext, recordTeamActivity, 
 // Skills
-getDefinedSkillNames, getSkillRequirements, checkSkillCompatibility, macroToolGap, macroToolGapPreamble, getCompatibleSkills, getAllRequiredTools, getSkillsByCategory, } from './team/index.js';
+checkMacroCompatibility, macroToolGap, macroToolGapPreamble, getAllRequiredTools, } from './team/index.js';
 // =============================================================================
 // Presets
 // =============================================================================
@@ -152,10 +152,12 @@ export { createPlatformTools, createProjectTools, createWorkItemTools, createDoc
 // Platform Workflow (pure step-criteria logic)
 // =============================================================================
 export { STEP_ORDER, GUIDED_STEP_CRITERIA, getNextStep, isValidTransition, getStepCriteria, formatStepDisplay, getStepNumber, } from './platform/index.js';
-export { RESERVED_SKILL_NAMES, isReservedSkillName, parseSkillMarkdown, loadSkillsFromDir, loadInstalledSkills, resolveLayeredSkills, resolveSkillsForAgent, resolveSkillsForTeamAgent, detectCollisions, formatCollisionWarnings, diffForkVsUpstream, buildForkContent, buildNewSkillContent, validateSkill as validateSkillQuality, getSkillsDir, getSkillFolder, getSkillFile, ensureSkillsDir, isValidSkillName, getScopeConfigPath, readSkillScopeConfig, readSkillScopeConfigSync, writeSkillScopeConfig, getSkillBindings, resolveSkillBinding, } from './skills/index.js';
+export { RESERVED_MACRO_NAMES, isReservedMacroName, parseSkillMarkdown, loadSkillsFromDir, loadInstalledSkills, resolveLayeredSkills, resolveSkillsForAgent, resolveSkillsForTeamAgent, detectCollisions, formatCollisionWarnings, diffForkVsUpstream, buildForkContent, buildNewSkillContent, validateSkill as validateSkillQuality, getSkillsDir, getSkillFolder, getSkillFile, ensureSkillsDir, isValidSkillName, getScopeConfigPath, readSkillScopeConfig, readSkillScopeConfigSync, writeSkillScopeConfig, getSkillBindings, resolveSkillBinding, } from './skills/index.js';
 export { resolveSkillPrompt, getAllAvailableSkills } from './skills/index.js';
+export { buildMacroList } from './skills/index.js';
+export { buildMacroInvocation } from './skills/index.js';
 export { generateSkillCatalog, toCatalogEntry, createLoadSkillTool } from './skills/index.js';
-export { platformSkills, designSkill, sketchSkill, prdSkill, refineSkill, refineItemSkill, architectureSkill, sessionNotesSkill, buildSkill, scaffoldSkill, outlineSkill, literatureReviewSkill, draftSectionSkill, peerReviewSkill, researchScaffoldSkill, businessVisionSkill, marketAnalysisSkill, competitorAnalysisSkill, financialModelSkill, pitchOutlineSkill, businessReviewSkill, brandSetupSkill, contentStrategySkill, contentCalendarSkill, createContentSkill, contentReviewSkill, curriculumDesignSkill, lessonPlanSkill, assessmentDesignSkill, courseReviewSkill, bookOutlineSkill, characterDesignSkill, plotThreadsSkill, sceneBreakdownSkill, bookReviewSkill, } from './skills/index.js';
+export { platformMacros, designMacro, sketchMacro, prdMacro, refineMacro, refineItemMacro, architectureMacro, sessionNotesMacro, buildMacro, scaffoldMacro, outlineMacro, literatureReviewMacro, draftSectionMacro, peerReviewMacro, researchScaffoldMacro, businessVisionMacro, marketAnalysisMacro, competitorAnalysisMacro, financialModelMacro, pitchOutlineMacro, businessReviewMacro, brandSetupMacro, contentStrategyMacro, contentCalendarMacro, createContentMacro, contentReviewMacro, curriculumDesignMacro, lessonPlanMacro, assessmentDesignMacro, courseReviewMacro, bookOutlineMacro, characterDesignMacro, plotThreadsMacro, sceneBreakdownMacro, bookReviewMacro, } from './skills/index.js';
 // =============================================================================
 // Contextual Actions (skill invocations with context)
 // =============================================================================
@@ -165,7 +167,7 @@ export { ACTION_REGISTRY, getActionsForContext, getActionById, resolveActionProm
 // =============================================================================
 export { PROJECT_TYPES, getProjectTypeConfig, getEnrichedProjectTypeConfig, getProjectTypesByCategory, generalConfig, softwareConfig, researchConfig, businessPlanConfig, contentConfig, techDocsConfig, courseConfig, 
 // Action & skill metadata
-ACTION_META_REGISTRY, SKILL_META_REGISTRY, resolveActionMeta, getSkillMeta, getAllSkillMeta, } from './project-types/index.js';
+MACRO_META_REGISTRY, resolveActionMeta, getRelevantMacros, getMacroMeta, getAllMacroMeta, } from './project-types/index.js';
 // =============================================================================
 // Re-exports from @compilr-dev/agents (convenience — no need to install separately)
 // =============================================================================

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

@@ -20,9 +20,9 @@ import * as pathNode from 'node:path';
 const PAGE_SIZES = ['16:9', '4:3', '1:1', '4:5', '9:16'];
 import { seedValues } from '../../canvas/types.js';
 import { validateControlManifest } from '../../canvas/validate.js';
-import { canvasSkill, infographicSkill, carouselSkill, boardSkill, canvasStylesSkill, } from '../../skills/canvas-skills.js';
-import { canvasExemplarInfographicSkill, canvasExemplarAppScreenSkill, } from '../../skills/canvas-exemplars.js';
-import { canvasIconsSkill } from '../../skills/canvas-icons.js';
+import { canvasMacro, infographicMacro, carouselMacro, boardMacro, canvasStylesMacro, } from '../../skills/canvas-macros.js';
+import { canvasExemplarInfographicMacro, canvasExemplarAppScreenMacro, } from '../../skills/canvas-exemplars.js';
+import { canvasIconsMacro } from '../../skills/canvas-icons.js';
 const CANVAS_TYPES = ['infographic', 'carousel', 'board'];
 /** Render content as numbered lines (1-based), optionally a slice. */
 function numberedLines(content, startLine, maxLines) {
@@ -743,14 +743,14 @@ export function createCanvasTools(config, imageConfig) {
               tests). The type was lying, not the guard.
             */
             const guides = {
-                canvas: canvasSkill,
-                infographic: infographicSkill,
-                carousel: carouselSkill,
-                board: boardSkill,
-                styles: canvasStylesSkill,
-                'exemplar-infographic': canvasExemplarInfographicSkill,
-                'exemplar-app-screen': canvasExemplarAppScreenSkill,
-                icons: canvasIconsSkill,
+                canvas: canvasMacro,
+                infographic: infographicMacro,
+                carousel: carouselMacro,
+                board: boardMacro,
+                styles: canvasStylesMacro,
+                'exemplar-infographic': canvasExemplarInfographicMacro,
+                'exemplar-app-screen': canvasExemplarAppScreenMacro,
+                icons: canvasIconsMacro,
             };
             const guide = guides[input.topic];
             if (!guide) {

package/dist/project-types/action-meta.d.ts

@@ -1,14 +1,28 @@
 /**
- * Action Metadata
+ * Action metadata — the action-button VIEW of a macro.
  *
- * Defines UI metadata for project-level and work-item-level actions.
- * Referenced by ProjectTypeConfig.projectActionsMeta / workItemActionsMeta.
+ * ⚠️ THIS FILE USED TO HOLD A SECOND REGISTRY. `ACTION_META_REGISTRY` keyed the same 35 macro
+ * ids as MACRO_META_REGISTRY with its own labels, descriptions and icons, and the two drifted
+ * apart in both directions. It is gone; this now derives from the one registry.
+ *
+ * What it does NOT do is flatten the difference. The action view was deliberately terser —
+ * 26 of 35 labels and 33 of 35 descriptions were shorter, because a button in a row of six
+ * cannot say "Competitor Analysis" and a work-item action says "Implement this item" rather
+ * than "Implement a feature". Those live on MacroMeta as `shortLabel` / `shortDescription`
+ * and are preferred here, so every label and description this function returns is byte-for-byte
+ * what the old registry returned. That is asserted in tests/project-types/action-meta.test.ts,
+ * against a snapshot taken before the merge.
+ *
+ * Spec: project-docs/00-requirements/compilr-dev-sdk/macro-metadata-consolidation.md
  */
 import type { ActionMeta } from './types.js';
-/** All known action metadata, keyed by action/skill ID */
-export declare const ACTION_META_REGISTRY: Record<string, ActionMeta>;
 /**
- * Resolve action IDs to ActionMeta objects.
- * Unknown IDs are returned with a fallback label.
+ * Resolve action ids to their button metadata.
+ *
+ * An unknown id still yields a usable entry rather than throwing — but it is a hole, not a
+ * feature: it renders as the raw id with a generic icon, which is exactly how twenty macros
+ * came to be displayed as `business-vision`, `market-analysis`, … The coverage guard in
+ * tests/skills/macro-meta-coverage.test.ts is what keeps this branch unreachable for anything
+ * we ship.
  */
 export declare function resolveActionMeta(actionIds: readonly string[]): ActionMeta[];

package/dist/project-types/action-meta.js

@@ -1,220 +1,51 @@
 /**
- * Action Metadata
+ * Action metadata — the action-button VIEW of a macro.
  *
- * Defines UI metadata for project-level and work-item-level actions.
- * Referenced by ProjectTypeConfig.projectActionsMeta / workItemActionsMeta.
+ * ⚠️ THIS FILE USED TO HOLD A SECOND REGISTRY. `ACTION_META_REGISTRY` keyed the same 35 macro
+ * ids as MACRO_META_REGISTRY with its own labels, descriptions and icons, and the two drifted
+ * apart in both directions. It is gone; this now derives from the one registry.
+ *
+ * What it does NOT do is flatten the difference. The action view was deliberately terser —
+ * 26 of 35 labels and 33 of 35 descriptions were shorter, because a button in a row of six
+ * cannot say "Competitor Analysis" and a work-item action says "Implement this item" rather
+ * than "Implement a feature". Those live on MacroMeta as `shortLabel` / `shortDescription`
+ * and are preferred here, so every label and description this function returns is byte-for-byte
+ * what the old registry returned. That is asserted in tests/project-types/action-meta.test.ts,
+ * against a snapshot taken before the merge.
+ *
+ * Spec: project-docs/00-requirements/compilr-dev-sdk/macro-metadata-consolidation.md
  */
-/** All known action metadata, keyed by action/skill ID */
-export const ACTION_META_REGISTRY = {
-    // ── Software project actions ─────────────────────────────────────────────
-    design: { id: 'design', label: 'Design', icon: 'Wand2', description: 'Design the app' },
-    prd: { id: 'prd', label: 'PRD', icon: 'FileText', description: 'Write requirements' },
-    architecture: {
-        id: 'architecture',
-        label: 'Architecture',
-        icon: 'Network',
-        description: 'System architecture',
-    },
-    refine: { id: 'refine', label: 'Refine', icon: 'RefreshCw', description: 'Refine backlog' },
-    scaffold: { id: 'scaffold', label: 'Scaffold', icon: 'Layers', description: 'Generate code' },
-    'session-notes': {
-        id: 'session-notes',
-        label: 'Notes',
-        icon: 'StickyNote',
-        description: 'Session summary',
-    },
-    // ── Research project actions ─────────────────────────────────────────────
-    'research-scaffold': {
-        id: 'research-scaffold',
-        label: 'New Paper',
-        icon: 'Layers',
-        description: 'Set up from a template',
-    },
-    outline: {
-        id: 'outline',
-        label: 'Outline',
-        icon: 'BookOpen',
-        description: 'Build paper outline',
-    },
-    'literature-review': {
-        id: 'literature-review',
-        label: 'Lit Review',
-        icon: 'Search',
-        description: 'Analyze sources',
-    },
-    'draft-section': {
-        id: 'draft-section',
-        label: 'Draft',
-        icon: 'PenTool',
-        description: 'Write a section',
-    },
-    'peer-review': {
-        id: 'peer-review',
-        label: 'Review',
-        icon: 'ShieldCheck',
-        description: 'Review the paper',
-    },
-    // ── Business Plan project actions ──────────────────────────────────────────
-    'business-vision': {
-        id: 'business-vision',
-        label: 'Vision',
-        icon: 'Target',
-        description: 'Define your business',
-    },
-    'market-analysis': {
-        id: 'market-analysis',
-        label: 'Market',
-        icon: 'TrendingUp',
-        description: 'Analyze the market',
-    },
-    'competitor-analysis': {
-        id: 'competitor-analysis',
-        label: 'Competitors',
-        icon: 'Swords',
-        description: 'Map competition',
-    },
-    // ── Content & Marketing actions ───────────────────────────────────────────
-    'brand-setup': {
-        id: 'brand-setup',
-        label: 'Brand',
-        icon: 'Palette',
-        description: 'Set up brand identity',
-    },
-    'content-strategy': {
-        id: 'content-strategy',
-        label: 'Strategy',
-        icon: 'Target',
-        description: 'Define pillars',
-    },
-    'content-calendar': {
-        id: 'content-calendar',
-        label: 'Calendar',
-        icon: 'Calendar',
-        description: 'Plan content',
-    },
-    'create-content': {
-        id: 'create-content',
-        label: 'Create',
-        icon: 'PenTool',
-        description: 'Write content',
-    },
-    'content-review': {
-        id: 'content-review',
-        label: 'Review',
-        icon: 'CheckCircle',
-        description: 'Check quality',
-    },
-    // ── Book actions ─────────────────────────────────────────────────────────
-    'book-outline': {
-        id: 'book-outline',
-        label: 'Outline',
-        icon: 'BookOpen',
-        description: 'Plan structure',
-    },
-    'character-design': {
-        id: 'character-design',
-        label: 'Characters',
-        icon: 'Users',
-        description: 'Build cast',
-    },
-    'plot-threads': {
-        id: 'plot-threads',
-        label: 'Threads',
-        icon: 'GitBranch',
-        description: 'Map plot lines',
-    },
-    'scene-breakdown': {
-        id: 'scene-breakdown',
-        label: 'Scenes',
-        icon: 'Layers',
-        description: 'Detail scenes',
-    },
-    'book-review': {
-        id: 'book-review',
-        label: 'Review',
-        icon: 'CheckCircle',
-        description: 'Structure check',
-    },
-    // ── Course / Training actions ─────────────────────────────────────────────
-    'curriculum-design': {
-        id: 'curriculum-design',
-        label: 'Curriculum',
-        icon: 'School',
-        description: 'Define structure',
-    },
-    'lesson-plan': {
-        id: 'lesson-plan',
-        label: 'Lessons',
-        icon: 'BookOpen',
-        description: 'Plan lessons',
-    },
-    'assessment-design': {
-        id: 'assessment-design',
-        label: 'Assess',
-        icon: 'ClipboardCheck',
-        description: 'Create assessments',
-    },
-    'course-review': {
-        id: 'course-review',
-        label: 'Review',
-        icon: 'CheckCircle',
-        description: 'Quality check',
-    },
-    'financial-model': {
-        id: 'financial-model',
-        label: 'Financials',
-        icon: 'DollarSign',
-        description: 'Build projections',
-    },
-    'pitch-outline': {
-        id: 'pitch-outline',
-        label: 'Pitch',
-        icon: 'Rocket',
-        description: 'Structure a pitch',
-    },
-    'business-review': {
-        id: 'business-review',
-        label: 'Review',
-        icon: 'ShieldCheck',
-        description: 'Validate the plan',
-    },
-    // ── Work item actions ────────────────────────────────────────────────────
-    build: {
-        id: 'build',
-        label: 'Build',
-        icon: 'Hammer',
-        description: 'Implement this item',
-        category: 'development',
-        suggestedRole: 'developer',
-    },
-    'refine-item': {
-        id: 'refine-item',
-        label: 'Refine',
-        icon: 'RefreshCw',
-        description: 'Add detail to this item',
-        category: 'planning',
-        suggestedRole: 'pm',
-    },
-    'code-review': {
-        id: 'code-review',
-        label: 'Review',
-        icon: 'Search',
-        description: 'Review code for this item',
-        category: 'development',
-        suggestedRole: 'qa',
-    },
-    explain: {
-        id: 'explain',
-        label: 'Explain',
-        icon: 'BookOpen',
-        description: 'Explain this item',
-        category: 'documentation',
-    },
-};
+import { MACRO_META_REGISTRY } from './macro-meta.js';
 /**
- * Resolve action IDs to ActionMeta objects.
- * Unknown IDs are returned with a fallback label.
+ * Resolve action ids to their button metadata.
+ *
+ * An unknown id still yields a usable entry rather than throwing — but it is a hole, not a
+ * feature: it renders as the raw id with a generic icon, which is exactly how twenty macros
+ * came to be displayed as `business-vision`, `market-analysis`, … The coverage guard in
+ * tests/skills/macro-meta-coverage.test.ts is what keeps this branch unreachable for anything
+ * we ship.
  */
 export function resolveActionMeta(actionIds) {
-    return actionIds.map((id) => ACTION_META_REGISTRY[id] ?? { id, label: id, icon: 'Zap', description: id });
+    return actionIds.map((id) => {
+        // `in`, not a falsy check on the lookup. `Record<string, MacroMeta>` claims every key
+        // resolves, so `if (!meta)` reads as dead code to eslint and it asks for the guard to be
+        // deleted — but `id` comes from a project type's data, not from the type, and an unknown id
+        // is exactly what this branch is for. `checkMacroCompatibility` guards the same way.
+        if (!(id in MACRO_META_REGISTRY))
+            return { id, label: id, icon: 'Zap', description: id };
+        const meta = MACRO_META_REGISTRY[id];
+        const action = {
+            id: meta.id,
+            label: meta.shortLabel ?? meta.label,
+            icon: meta.icon,
+            description: meta.shortDescription ?? meta.description,
+            // Populated for every action now. The old registry carried it on 4 of 35 entries, which
+            // was an artifact of who edited it last rather than a distinction — nothing reads it, and
+            // ActionBar already groups by category elsewhere.
+            category: meta.category,
+        };
+        if (meta.suggestedRole !== undefined)
+            action.suggestedRole = meta.suggestedRole;
+        return action;
+    });
 }

package/dist/project-types/index.d.ts

@@ -5,10 +5,12 @@
  * document templates, and skills. The underlying platform is the same
  * for all types.
  */
-export type { ProjectTypeConfig, ProjectPhase, SuggestedAgent, DocumentTemplate, ActionMeta, SkillMeta, } from './types.js';
+export type { ProjectTypeConfig, ProjectPhase, SuggestedAgent, DocumentTemplate, ActionMeta, MacroMeta, MacroCategory, } from './types.js';
 export { generalConfig, softwareConfig, researchConfig, businessPlanConfig, contentConfig, techDocsConfig, courseConfig, bookConfig, } from './configs.js';
-export { SKILL_META_REGISTRY, getSkillMeta, getAllSkillMeta } from './skill-meta.js';
-export { ACTION_META_REGISTRY, resolveActionMeta } from './action-meta.js';
+export { MACRO_META_REGISTRY, getMacroMeta, getAllMacroMeta } from './macro-meta.js';
+export { resolveActionMeta } from './action-meta.js';
+export { getRelevantMacros } from './macro-relevance.js';
+export type { MacroCapabilities } from './macro-relevance.js';
 import type { ProjectTypeConfig } from './types.js';
 /** All registered project types */
 export declare const PROJECT_TYPES: ProjectTypeConfig[];

package/dist/project-types/index.js

@@ -8,8 +8,9 @@
 // Configs
 export { generalConfig, softwareConfig, researchConfig, businessPlanConfig, contentConfig, techDocsConfig, courseConfig, bookConfig, } from './configs.js';
 // Action & Skill metadata
-export { SKILL_META_REGISTRY, getSkillMeta, getAllSkillMeta } from './skill-meta.js';
-export { ACTION_META_REGISTRY, resolveActionMeta } from './action-meta.js';
+export { MACRO_META_REGISTRY, getMacroMeta, getAllMacroMeta } from './macro-meta.js';
+export { resolveActionMeta } from './action-meta.js';
+export { getRelevantMacros } from './macro-relevance.js';
 import { resolveActionMeta } from './action-meta.js';
 import { generalConfig, softwareConfig, researchConfig, businessPlanConfig, contentConfig, techDocsConfig, courseConfig, bookConfig, } from './configs.js';
 /** All registered project types */

package/dist/project-types/macro-meta.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Macro Metadata Registry — the single registry for every macro we ship.
+ *
+ * 55 entries: 42 platform macros, the 6 agents-library builtins they do not shadow, and the 7
+ * from agents-coding. Every id here is a MACRO — a named prompt the user invokes — never an
+ * installed Skill, which carries its own description in its SKILL.md.
+ *
+ * ⚠️ THERE USED TO BE THREE OF THESE. This one (unread, reachable only through an IPC channel
+ * nothing called), ACTION_META_REGISTRY (live, shorter labels), and a third inside Desktop
+ * (live, the slash menu). Each was missing what the others had: this one lacked all 8 canvas
+ * and 7 agents-coding macros, Desktop's lacked all 20 business/content/course/book ones. The
+ * failure mode was never an error — a macro with no entry renders as its raw id with a generic
+ * icon, so a business-plan project listed `business-vision`, `market-analysis`, … verbatim.
+ *
+ * `shortLabel` is why the merge is not lossy: ACTION_META's labels were shorter ON PURPOSE
+ * (a button in a row of six cannot say "Competitor Analysis"), so both survive here. Every one
+ * of its 35 labels is reproducible as `shortLabel ?? label`, asserted before it was deleted.
+ *
+ * Coverage is enforced, in both directions, by tests/skills/macro-meta-coverage.test.ts —
+ * derived from the macro sources themselves, never a hand-written list, because a hand-written
+ * list is precisely what produced three maps.
+ *
+ * Spec: project-docs/00-requirements/compilr-dev-sdk/macro-metadata-consolidation.md
+ */
+import type { MacroMeta } from './types.js';
+/** All macro UI metadata — platform macros + the agents library's builtins. */
+export declare const MACRO_META_REGISTRY: Record<string, MacroMeta>;
+/**
+ * Get macro metadata by ID.
+ *
+ * No internal caller: `buildMacroList` and `resolveActionMeta` read the registry directly.
+ * Kept as public API of a published package — but do not read its existence as evidence that
+ * something depends on it. The IPC channel that used to was deleted for being dead.
+ */
+export declare function getMacroMeta(macroId: string): MacroMeta | undefined;
+/**
+ * Get all macro metadata entries.
+ */
+export declare function getAllMacroMeta(): MacroMeta[];