@compilr-dev/sdk 0.25.1 → 0.27.0

package/dist/skills/macro-invocation.js

@@ -0,0 +1,63 @@
+/**
+ * What a host actually SENDS when a user invokes a macro.
+ *
+ * ⚠️ THE TWO HOSTS SENT DIFFERENT THINGS FOR THE SAME COMMAND. `/design` in the CLI wrapped the
+ * macro's prompt in ~20 lines of project context — do not scan the filesystem, the cwd is not the
+ * project, save work items with `workitem_add` and documents with `project_document_add` rather
+ * than writing files — while Desktop sent the prompt alone. Same name, same macro, materially
+ * different instructions, so the same request produced an agent that interviewed you and filled
+ * the backlog in one host and an agent that went looking for source files in the other.
+ *
+ * The prompt is shared data; what surrounds it was not. It is now.
+ *
+ * This composes the MESSAGE only. The tool-gap preamble (`macroToolGap`) stays a separate,
+ * host-applied prepend because it depends on which AGENT is being addressed, which is a thing
+ * only the host knows.
+ *
+ * Spec: project-docs/00-requirements/compilr-dev-sdk/macros-rename.md
+ */
+/**
+ * ⚠️ "A NEW PROJECT" IS ASSERTED, NOT DETECTED, AND THAT IS DELIBERATE. `/design` is the
+ * from-scratch macro — `/refine` is the one for a backlog that already exists — so invoking it
+ * states the intent. Deriving it instead (counting work items, say) would make the prompt depend
+ * on database state at send time, and be wrong the moment someone re-runs /design to redesign.
+ */
+function designContext(project) {
+    return `I want to design my project and create the backlog.
+
+## PROJECT CONTEXT (IMPORTANT)
+- Project Name: ${project.name} (ID: ${String(project.id)})
+- This is a NEW project being designed from scratch
+- Do NOT scan the filesystem - the current directory is NOT the project
+- Do NOT use detect_project, glob, read_file, or ls tools
+- Focus ONLY on gathering requirements via ask_user questions
+
+## DOCUMENT STORAGE (CRITICAL)
+Save all documents and backlog items using the database - do NOT write files directly.
+- For backlog items: \`workitem_add({ type: "feature", title: "...", description: "...", priority: "high" })\`
+- For documents: \`project_document_add({ doc_type: "prd", title: "...", content: "..." })\`
+- The database is the source of truth for all project documents
+- Do NOT use write_file or edit tools for documentation
+`;
+}
+const DESIGN_CLOSER = 'Please start by using todo_write to track the design phases, then begin with Phase 1: Vision. ' +
+    'Use the ask_user tool to gather information efficiently.';
+/**
+ * Compose the message for a macro invocation.
+ *
+ * A macro with no wrapper sends its prompt unchanged — that is the common case and stays the
+ * default, so adding a macro does not require touching this file.
+ *
+ * @param macroName the macro being invoked, e.g. `design`
+ * @param prompt    the macro's resolved prompt text
+ * @param ctx       what the host knows; an absent project omits the context block
+ */
+export function buildMacroInvocation(macroName, prompt, ctx = {}) {
+    if (macroName === 'design' && ctx.project) {
+        return {
+            message: `${designContext(ctx.project)}\n${prompt}\n\n${DESIGN_CLOSER}`,
+            displayMessage: 'Start the design process for my project.',
+        };
+    }
+    return { message: prompt, displayMessage: `/${macroName}` };
+}

package/dist/skills/macro-list.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The list of macros a host presents — built once, here, for both hosts.
+ *
+ * ⚠️ THIS LIVED IN DESKTOP, AND THE CLI SIMPLY DID WITHOUT. Desktop decided what each entry was
+ * called, which category it belonged to and which ones came first; the terminal listed raw names
+ * in resolver order. That is not a presentation difference, it is the same question answered in
+ * one place and not asked in the other — so the two disagreed about the name of every macro.
+ *
+ * What legitimately differs per host is capability: a terminal cannot render a canvas. That is a
+ * parameter (`capabilities`), so neither host re-decides anything else.
+ *
+ * Spec: project-docs/00-requirements/compilr-dev-sdk/macro-metadata-consolidation.md
+ */
+import { type SkillSources } from './prompt-resolver.js';
+import { type MacroCapabilities } from '../project-types/macro-relevance.js';
+import type { MacroCategory, MacroMeta } from '../project-types/types.js';
+/** One row in a slash menu, command palette or picker. */
+export interface MacroListEntry {
+    id: string;
+    label: string;
+    description: string;
+    category: MacroCategory;
+    icon: string;
+}
+export interface BuildMacroListOptions {
+    /** Project directory, for project-scoped skills and bindings. */
+    projectPath?: string;
+    /** Project type id. Absent means no relevance ordering is applied. */
+    projectType?: string;
+    /** Extra prompt sources the host injects (factory, agents-coding). */
+    sources?: SkillSources;
+    /**
+     * Metadata for macros the SDK does not ship and therefore cannot describe.
+     *
+     * The SDK is the source of truth for ITS macros; a package that injects its own prompts is
+     * the source of truth for those. `factorySkills` is the case in point — factory depends on
+     * the SDK, not the reverse, so no registry here could ever cover it, and `factory-scaffold`
+     * rendered as a raw id. Supplying it through this channel keeps the hole visible and owned
+     * rather than hardcoded somewhere.
+     *
+     * Properly, each such package should export this alongside its prompts; until then the host
+     * that injects the source supplies it and asserts its own coverage.
+     */
+    extraMeta?: Record<string, Omit<MacroMeta, 'id'>>;
+    /** What this host can render. */
+    capabilities?: MacroCapabilities;
+}
+/**
+ * Everything typeable after a slash, labelled, and ordered by relevance to the project type.
+ *
+ * Disabled entries are filtered out — an entry offered and then refused as "Unknown command" is
+ * worse than one never offered.
+ */
+export declare function buildMacroList(options?: BuildMacroListOptions): MacroListEntry[];

package/dist/skills/macro-list.js

@@ -0,0 +1,84 @@
+/**
+ * The list of macros a host presents — built once, here, for both hosts.
+ *
+ * ⚠️ THIS LIVED IN DESKTOP, AND THE CLI SIMPLY DID WITHOUT. Desktop decided what each entry was
+ * called, which category it belonged to and which ones came first; the terminal listed raw names
+ * in resolver order. That is not a presentation difference, it is the same question answered in
+ * one place and not asked in the other — so the two disagreed about the name of every macro.
+ *
+ * What legitimately differs per host is capability: a terminal cannot render a canvas. That is a
+ * parameter (`capabilities`), so neither host re-decides anything else.
+ *
+ * Spec: project-docs/00-requirements/compilr-dev-sdk/macro-metadata-consolidation.md
+ */
+import { getAllAvailableSkills } from './prompt-resolver.js';
+import { MACRO_META_REGISTRY } from '../project-types/macro-meta.js';
+import { getRelevantMacros } from '../project-types/macro-relevance.js';
+import { platformMacros } from './platform-macros.js';
+/** Derived from the tag, never a name list — a stale name list is how `canvas-styles` leaked. */
+function isCanvasMacro(name) {
+    return platformMacros.some((m) => m.name === name && (m.tags ?? []).includes('canvas'));
+}
+/**
+ * Everything typeable after a slash, labelled, and ordered by relevance to the project type.
+ *
+ * Disabled entries are filtered out — an entry offered and then refused as "Unknown command" is
+ * worse than one never offered.
+ */
+export function buildMacroList(options = {}) {
+    const { projectPath, projectType, sources, capabilities, extraMeta } = options;
+    const entries = getAllAvailableSkills(projectPath, sources)
+        .filter((entry) => entry.enabled !== false)
+        // A host that cannot render a canvas must not be OFFERED one. Only ours are withheld: a
+        // user's own SKILL.md that happens to be called `canvas` is theirs and still works, which
+        // is the same line the CLI's resolver already draws.
+        .filter((entry) => !(capabilities?.canvas === false && entry.source === 'sdk' && isCanvasMacro(entry.name)))
+        .map((entry) => {
+        // A bound command is named for the binding, not for what it resolves to.
+        if (entry.source === 'binding') {
+            return {
+                id: entry.name,
+                label: `/${entry.name}`,
+                description: entry.description,
+                category: 'development',
+                icon: 'link',
+            };
+        }
+        // A user's or project's own SKILL.md. Its scope is part of how it reads, because two of
+        // them can share a name and the project's wins.
+        if (entry.scope) {
+            return {
+                id: entry.name,
+                label: `/${entry.name}`,
+                description: `[${entry.scope}] ${entry.description}`,
+                category: 'development',
+                icon: 'wand',
+            };
+        }
+        // Something we ship. The fallbacks below are a hole, not a feature — they are what made
+        // twenty macros render as `business-vision`, `market-analysis`, … and they are kept
+        // unreachable by tests/skills/macro-meta-coverage.test.ts.
+        const meta = (entry.name in MACRO_META_REGISTRY ? MACRO_META_REGISTRY[entry.name] : undefined) ??
+            extraMeta?.[entry.name];
+        return {
+            id: entry.name,
+            label: meta?.label ?? entry.name,
+            description: entry.description,
+            category: meta?.category ?? 'development',
+            icon: meta?.icon ?? 'Zap',
+        };
+    });
+    const relevant = getRelevantMacros(projectType, capabilities);
+    if (relevant.length === 0)
+        return entries;
+    // Promoted entries come back in RELEVANCE order — a business plan leads with its business
+    // macros — rather than in whatever order the resolver happened to return them. Everything
+    // else keeps its original order behind them.
+    const rank = new Map(relevant.map((id, i) => [id, i]));
+    const rankOf = (id) => rank.get(id) ?? Number.MAX_SAFE_INTEGER;
+    const promoted = entries
+        .filter((e) => rank.has(e.id))
+        .sort((a, b) => rankOf(a.id) - rankOf(b.id));
+    const rest = entries.filter((e) => !rank.has(e.id));
+    return [...promoted, ...rest];
+}

package/dist/skills/operations.js

@@ -7,8 +7,8 @@
  * - Validation (quality checks beyond parseSkillMarkdown)
  * - Binding resolution (config.json slash command remapping)
  */
-import { RESERVED_SKILL_NAMES } from './types.js';
-import { platformSkills } from './platform-skills.js';
+import { RESERVED_MACRO_NAMES } from './types.js';
+import { platformMacros } from './platform-macros.js';
 /**
  * Detect user/project skills that shadow SDK reserved names.
  * Called at startup to warn users about collisions introduced by SDK updates.
@@ -18,7 +18,7 @@ import { platformSkills } from './platform-skills.js';
  * already has a skill with that name.
  */
 export function detectCollisions(userSkills) {
-    const reserved = new Set(RESERVED_SKILL_NAMES);
+    const reserved = new Set(RESERVED_MACRO_NAMES);
     const collisions = [];
     for (const skill of userSkills) {
         if (reserved.has(skill.name)) {
@@ -54,7 +54,7 @@ export function formatCollisionWarnings(collisions) {
 export function diffForkVsUpstream(forkPrompt, upstreamSkillName) {
     // Find the upstream SDK skill
     // Check all platform skills + builtins
-    const allSdk = [...platformSkills];
+    const allSdk = [...platformMacros];
     const upstream = allSdk.find((s) => s.name === upstreamSkillName);
     if (!upstream)
         return null;

package/dist/skills/platform-macros.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Platform Macros — Aggregate
+ *
+ * The prompts we ship. A macro is a named prompt the USER invokes (`/design`, `/prd`); it
+ * expands into a message. That is not what a SKILL is — a skill is a capability the MODEL
+ * chooses from a catalogue, installed as `SKILL.md` and loaded on demand. These 42 are macros
+ * and have always been; they were named "skills" before the two were told apart.
+ *
+ * They are still built with `defineSkill()` from @compilr-dev/agents, deliberately: that is the
+ * shared primitive for "a named prompt with a description", and installed skills extend the same
+ * shape. The primitive is not being renamed — the population is.
+ *
+ * Per-domain files: software-macros.ts, research-macros.ts, business-macros.ts, content-macros.ts,
+ * course-macros.ts, book-macros.ts, canvas-macros.ts (+ canvas-exemplars.ts, canvas-icons.ts).
+ */
+import type { Skill } from '@compilr-dev/agents';
+export { designMacro, sketchMacro, prdMacro, refineMacro, refineItemMacro, architectureMacro, sessionNotesMacro, buildMacro, scaffoldMacro, } from './software-macros.js';
+export { outlineMacro, literatureReviewMacro, draftSectionMacro, peerReviewMacro, researchScaffoldMacro, } from './research-macros.js';
+export { businessVisionMacro, marketAnalysisMacro, competitorAnalysisMacro, financialModelMacro, pitchOutlineMacro, businessReviewMacro, } from './business-macros.js';
+export { brandSetupMacro, contentStrategyMacro, contentCalendarMacro, createContentMacro, contentReviewMacro, } from './content-macros.js';
+export { curriculumDesignMacro, lessonPlanMacro, assessmentDesignMacro, courseReviewMacro, } from './course-macros.js';
+export { bookOutlineMacro, characterDesignMacro, plotThreadsMacro, sceneBreakdownMacro, bookReviewMacro, } from './book-macros.js';
+export { canvasMacro, infographicMacro, carouselMacro, boardMacro, canvasStylesMacro, } from './canvas-macros.js';
+export { canvasExemplarInfographicMacro, canvasExemplarAppScreenMacro, } from './canvas-exemplars.js';
+export { canvasIconsMacro } from './canvas-icons.js';
+/** Every macro we ship. Count is asserted in tests/skills/platform-macros.test.ts. */
+export declare const platformMacros: Skill[];

package/dist/skills/platform-macros.js

@@ -0,0 +1,94 @@
+/**
+ * Platform Macros — Aggregate
+ *
+ * The prompts we ship. A macro is a named prompt the USER invokes (`/design`, `/prd`); it
+ * expands into a message. That is not what a SKILL is — a skill is a capability the MODEL
+ * chooses from a catalogue, installed as `SKILL.md` and loaded on demand. These 42 are macros
+ * and have always been; they were named "skills" before the two were told apart.
+ *
+ * They are still built with `defineSkill()` from @compilr-dev/agents, deliberately: that is the
+ * shared primitive for "a named prompt with a description", and installed skills extend the same
+ * shape. The primitive is not being renamed — the population is.
+ *
+ * Per-domain files: software-macros.ts, research-macros.ts, business-macros.ts, content-macros.ts,
+ * course-macros.ts, book-macros.ts, canvas-macros.ts (+ canvas-exemplars.ts, canvas-icons.ts).
+ */
+// Software Development
+export { designMacro, sketchMacro, prdMacro, refineMacro, refineItemMacro, architectureMacro, sessionNotesMacro, buildMacro, scaffoldMacro, } from './software-macros.js';
+// Research Paper
+export { outlineMacro, literatureReviewMacro, draftSectionMacro, peerReviewMacro, researchScaffoldMacro, } from './research-macros.js';
+// Business Plan
+export { businessVisionMacro, marketAnalysisMacro, competitorAnalysisMacro, financialModelMacro, pitchOutlineMacro, businessReviewMacro, } from './business-macros.js';
+// Content & Marketing
+export { brandSetupMacro, contentStrategyMacro, contentCalendarMacro, createContentMacro, contentReviewMacro, } from './content-macros.js';
+// Course / Training
+export { curriculumDesignMacro, lessonPlanMacro, assessmentDesignMacro, courseReviewMacro, } from './course-macros.js';
+// Book
+export { bookOutlineMacro, characterDesignMacro, plotThreadsMacro, sceneBreakdownMacro, bookReviewMacro, } from './book-macros.js';
+// Canvas (visual)
+export { canvasMacro, infographicMacro, carouselMacro, boardMacro, canvasStylesMacro, } from './canvas-macros.js';
+// Canvas exemplars — generated from the design handoff; see canvas-exemplars.ts.
+export { canvasExemplarInfographicMacro, canvasExemplarAppScreenMacro, } from './canvas-exemplars.js';
+export { canvasIconsMacro } from './canvas-icons.js';
+// Import all for the aggregate array
+import { designMacro, sketchMacro, prdMacro, refineMacro, refineItemMacro, architectureMacro, sessionNotesMacro, buildMacro, scaffoldMacro, } from './software-macros.js';
+import { outlineMacro, literatureReviewMacro, draftSectionMacro, peerReviewMacro, researchScaffoldMacro, } from './research-macros.js';
+import { businessVisionMacro, marketAnalysisMacro, competitorAnalysisMacro, financialModelMacro, pitchOutlineMacro, businessReviewMacro, } from './business-macros.js';
+import { brandSetupMacro, contentStrategyMacro, contentCalendarMacro, createContentMacro, contentReviewMacro, } from './content-macros.js';
+import { curriculumDesignMacro, lessonPlanMacro, assessmentDesignMacro, courseReviewMacro, } from './course-macros.js';
+import { bookOutlineMacro, characterDesignMacro, plotThreadsMacro, sceneBreakdownMacro, bookReviewMacro, } from './book-macros.js';
+import { canvasMacro, infographicMacro, carouselMacro, boardMacro, canvasStylesMacro, } from './canvas-macros.js';
+import { canvasExemplarInfographicMacro, canvasExemplarAppScreenMacro, } from './canvas-exemplars.js';
+import { canvasIconsMacro } from './canvas-icons.js';
+/** Every macro we ship. Count is asserted in tests/skills/platform-macros.test.ts. */
+export const platformMacros = [
+    // Software (9)
+    designMacro,
+    sketchMacro,
+    prdMacro,
+    refineMacro,
+    refineItemMacro,
+    architectureMacro,
+    sessionNotesMacro,
+    buildMacro,
+    scaffoldMacro,
+    // Research (5)
+    outlineMacro,
+    literatureReviewMacro,
+    draftSectionMacro,
+    peerReviewMacro,
+    researchScaffoldMacro,
+    // Business (6)
+    businessVisionMacro,
+    marketAnalysisMacro,
+    competitorAnalysisMacro,
+    financialModelMacro,
+    pitchOutlineMacro,
+    businessReviewMacro,
+    // Content (5)
+    brandSetupMacro,
+    contentStrategyMacro,
+    contentCalendarMacro,
+    createContentMacro,
+    contentReviewMacro,
+    // Course (4)
+    curriculumDesignMacro,
+    lessonPlanMacro,
+    assessmentDesignMacro,
+    courseReviewMacro,
+    // Book (5)
+    bookOutlineMacro,
+    characterDesignMacro,
+    plotThreadsMacro,
+    sceneBreakdownMacro,
+    bookReviewMacro,
+    // Canvas (4)
+    canvasMacro,
+    infographicMacro,
+    carouselMacro,
+    boardMacro,
+    canvasStylesMacro,
+    canvasExemplarInfographicMacro,
+    canvasExemplarAppScreenMacro,
+    canvasIconsMacro,
+];

package/dist/skills/prompt-resolver.d.ts

@@ -1,11 +1,17 @@
 /**
- * Unified skill prompt resolver — used by both CLI and Desktop.
+ * Unified slash-command prompt resolver — used by both CLI and Desktop.
  *
- * Resolves a slash command name to a skill prompt using:
+ * Resolves a slash command name to a prompt using:
  * 1. Binding resolution (config.json slashCommands)
  * 2. 5-layer priority: project → user → SDK platform → agents builtin → agents-coding
  *
  * Also provides getAllAvailableSkills() for autocomplete/picker display.
+ *
+ * ⚠️ DELIBERATELY NOT RENAMED YET. This module spans BOTH populations: layer 4 is platform
+ * macros, but layers 2–3 read the user's and project's `SKILL.md` directories, so today an
+ * installed skill is also reachable by typing its name. That conflation is what M5 removes, by
+ * moving user-authored macros to `commands/` and leaving `skills/` to skills alone. Naming this
+ * module before that split would name the wrong shape; the rename follows M5, not this group.
  */
 import type { ForkedFromMarker } from './types.js';
 /** Result of resolving a skill prompt */

package/dist/skills/prompt-resolver.js

@@ -1,17 +1,23 @@
 /**
- * Unified skill prompt resolver — used by both CLI and Desktop.
+ * Unified slash-command prompt resolver — used by both CLI and Desktop.
  *
- * Resolves a slash command name to a skill prompt using:
+ * Resolves a slash command name to a prompt using:
  * 1. Binding resolution (config.json slashCommands)
  * 2. 5-layer priority: project → user → SDK platform → agents builtin → agents-coding
  *
  * Also provides getAllAvailableSkills() for autocomplete/picker display.
+ *
+ * ⚠️ DELIBERATELY NOT RENAMED YET. This module spans BOTH populations: layer 4 is platform
+ * macros, but layers 2–3 read the user's and project's `SKILL.md` directories, so today an
+ * installed skill is also reachable by typing its name. That conflation is what M5 removes, by
+ * moving user-authored macros to `commands/` and leaving `skills/` to skills alone. Naming this
+ * module before that split would name the wrong shape; the rename follows M5, not this group.
  */
 import { readFileSync, existsSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { parseSkillMarkdown } from './loader.js';
 import { resolveBinding, getSkillsDir, readScopeConfigSync } from './paths.js';
-import { platformSkills } from './platform-skills.js';
+import { platformMacros } from './platform-macros.js';
 // Re-export builtinSkills from agents (available via SDK re-export)
 // The SDK re-exports builtinSkills from @compilr-dev/agents
 import { builtinSkills } from '@compilr-dev/agents';
@@ -99,10 +105,10 @@ export function resolveSkillPrompt(name, projectDir, sources) {
             return { prompt, skillName: name, isBound: false, source: 'user' };
         }
     }
-    // 4. SDK platform skills
-    const sdkSkill = platformSkills.find((s) => s.name === name);
-    if (sdkSkill) {
-        return { prompt: sdkSkill.prompt, skillName: name, isBound: false, source: 'sdk' };
+    // 4. SDK platform macros
+    const sdkMacro = platformMacros.find((s) => s.name === name);
+    if (sdkMacro) {
+        return { prompt: sdkMacro.prompt, skillName: name, isBound: false, source: 'sdk' };
     }
     // 5. Additional sources
     if (sources?.factorySkills) {
@@ -178,7 +184,7 @@ export function getAllAvailableSkills(projectDir, sources) {
         }
     }
     // 2. SDK platform skills
-    for (const skill of platformSkills) {
+    for (const skill of platformMacros) {
         if (!seen.has(skill.name)) {
             seen.add(skill.name);
             entries.push({ name: skill.name, description: skill.description, source: 'sdk' });

package/dist/skills/research-macros.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Research Paper Macros
+ *
+ * outline, literature-review, draft-section, peer-review, research-scaffold
+ */
+export declare const outlineMacro: import("@compilr-dev/agents").Skill;
+export declare const literatureReviewMacro: import("@compilr-dev/agents").Skill;
+export declare const draftSectionMacro: import("@compilr-dev/agents").Skill;
+export declare const peerReviewMacro: import("@compilr-dev/agents").Skill;
+export declare const researchScaffoldMacro: import("@compilr-dev/agents").Skill;

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

@@ -1,10 +1,10 @@
 /**
- * Research Paper Skills
+ * Research Paper Macros
  *
  * outline, literature-review, draft-section, peer-review, research-scaffold
  */
 import { defineSkill } from '@compilr-dev/agents';
-export const outlineSkill = defineSkill({
+export const outlineMacro = defineSkill({
     name: 'outline',
     description: 'Build or refine the research paper structure — define sections, formulate claims with evidence requirements, and map sources to claims. Use when starting a new paper or restructuring an existing one. Produces a ResearchModel outline stored in the project database.',
     prompt: `You are in OUTLINE MODE. Your goal is to help the user build or refine a structured outline for their research paper using the Research Model.
@@ -148,7 +148,7 @@ Create one work item per section:
 ✓ User has reviewed and approved the outline`,
     tags: ['research', 'planning', 'outline'],
 });
-export const literatureReviewSkill = defineSkill({
+export const literatureReviewMacro = defineSkill({
     name: 'literature-review',
     description: 'Systematically analyze sources from the Knowledge Base — extract key findings, link evidence to claims in the outline, assess source quality, and identify coverage gaps. Use after the outline exists and sources have been added to the Knowledge Base.',
     prompt: `You are in LITERATURE REVIEW MODE. Your goal is to systematically analyze the sources in the Knowledge Base and connect them to the Research Model's sections and claims.
@@ -252,7 +252,7 @@ If multiple sources have been analyzed, provide a thematic synthesis:
 ✓ User has reviewed the source-claim mappings`,
     tags: ['research', 'analysis', 'sources'],
 });
-export const draftSectionSkill = defineSkill({
+export const draftSectionMacro = defineSkill({
     name: 'draft-section',
     description: 'Draft a specific paper section using the outline structure, claims, and linked sources. Use when the outline and literature review are complete for the target section. Produces academic prose with inline citations following the selected citation style.',
     prompt: `You are in DRAFT SECTION MODE. Your goal is to write or revise a section of the research paper, guided by the Research Model's outline, claims, and linked sources.
@@ -364,7 +364,7 @@ Report to the user:
 ✓ User has reviewed the draft`,
     tags: ['research', 'writing', 'drafting'],
 });
-export const peerReviewSkill = defineSkill({
+export const peerReviewMacro = defineSkill({
     name: 'peer-review',
     description: 'Peer review the research paper — validate argument structure, find logical gaps, check claim-evidence consistency, assess citation coverage, and verify cross-section coherence. Use before submission to identify weaknesses. Produces a structured review report with actionable issues.',
     prompt: `You are in PEER REVIEW MODE. Your goal is to critically evaluate the research paper's argument structure, identify gaps, and check consistency — like an academic peer reviewer.
@@ -513,7 +513,7 @@ For issues that affect the Research Model:
 ✓ User has received the review summary`,
     tags: ['research', 'review', 'quality'],
 });
-export const researchScaffoldSkill = defineSkill({
+export const researchScaffoldMacro = defineSkill({
     name: 'research-scaffold',
     description: 'Scaffold a new research paper project from a template — APA journal article, IEEE conference paper, thesis/dissertation, literature review, or lab report. Use when starting a fresh research project. Creates the ResearchModel with template-appropriate sections, citation style, and document structure.',
     prompt: `You are in RESEARCH SCAFFOLD MODE. Your goal is to help the user set up a new research paper project using a template.

package/dist/skills/resolver.d.ts

@@ -6,7 +6,7 @@
  * 5-layer priority (first match by name wins):
  *   1. project (<projectDir>/.compilr/skills/)
  *   2. user    (~/.compilr-dev/skills/)
- *   3. sdk     (platformSkills)
+ *   3. sdk     (platformMacros)
  *   4. agents  (builtinSkills)
  *   5. agents-coding (codingSkills)
  *
@@ -28,8 +28,14 @@ export interface SkillEligibilityContext {
     agentId?: string;
     /** Tool names this agent has access to. */
     toolNames?: ReadonlySet<string> | readonly string[];
-    /** Explicit skill allowlist on the agent (legacy enabledSkills). */
-    enabledSkills?: readonly string[];
+    /**
+     * Skills this agent may choose. `undefined` = no allowlist, `[]` = none.
+     *
+     * ⚠️ NAMED FOR WHAT IT HOLDS. This was called `enabledSkills` and documented "legacy", while
+     * every caller fed it `grantedSkills` — the exact field-name reuse that inverted the contract
+     * and stripped every custom agent's skills in 0.25.0, preserved in the type that caused it.
+     */
+    grantedSkills?: readonly string[];
     /** Active project category ('software', 'research', 'business', ...). */
     projectType?: string;
 }
@@ -62,11 +68,15 @@ export declare function resolveSkillsForAgent(skills: CustomSkill[], context: Sk
  * than once. Every judgement lives here: which fields of the agent matter, and what an absent
  * allowlist means.
  *
- * ⚠️ `enabledSkills` DOES NOT FOLLOW THE MCP GRANT CONTRACT, and must not be made to. There,
- * `[]` means "granted nothing" because the field was new. Here both `undefined` and `[]` mean
- * "unrestricted": the field predates choosable skills, `createCustomAgentDefinition` normalises
- * `undefined` to `[]`, and every UI that collects it says empty means all. Only a NON-EMPTY list
- * filters.
+ * ⚠️ READS `grantedSkills`. There used to be a second field, `enabledSkills`, holding MACRO ids —
+ * the 13 its picker offered were `code-review`, `debug`, `design`, `prd` and friends, all things
+ * a user types — and 0.25.0 wired Skills enforcement onto it, so ticking "Code Review" wrote a
+ * name no installed skill has and the agent silently got zero skills. That field is deleted, and
+ * the reason it must never come back in another guise is the whole point of this comment.
+ *
+ * `grantedSkills` follows the MCP contract: `undefined` = never asked, reaches everything
+ * eligible; `[]` = granted nothing. That reading is legitimate here precisely because the field
+ * is new and nothing has a prior meaning.
  *
  * @param pool  every skill installed for this machine/project, unfiltered
  * @param agent the agent being built — role, id and its allowlist come from here
@@ -75,7 +85,8 @@ export declare function resolveSkillsForAgent(skills: CustomSkill[], context: Sk
 export declare function resolveSkillsForTeamAgent(pool: CustomSkill[], agent: {
     id: string;
     role?: string;
-    enabledSkills?: readonly string[];
+    /** Skills this agent may choose. undefined = never asked, [] = none. */
+    grantedSkills?: readonly string[];
 }, opts?: {
     projectType?: string;
     toolNames?: readonly string[];

package/dist/skills/resolver.js

@@ -6,7 +6,7 @@
  * 5-layer priority (first match by name wins):
  *   1. project (<projectDir>/.compilr/skills/)
  *   2. user    (~/.compilr-dev/skills/)
- *   3. sdk     (platformSkills)
+ *   3. sdk     (platformMacros)
  *   4. agents  (builtinSkills)
  *   5. agents-coding (codingSkills)
  *
@@ -47,20 +47,13 @@ export function resolveLayeredSkills(layers) {
 export function resolveSkillsForAgent(skills, context) {
     const toolSet = context.toolNames instanceof Set ? context.toolNames : new Set(context.toolNames ?? []);
     /*
-      ⚠️ AN EMPTY ALLOWLIST MEANS "UNRESTRICTED", NOT "NOTHING" — the opposite of the MCP grant
-      contract, and deliberately so. `enabledSkills` predates model-choosable skills and already had
-      a meaning, stated in three places: `CustomAgentDefinition.enabledSkills` is documented "Empty =
-      all skills, non-empty = filtered", `createCustomAgentDefinition` normalises `undefined` to `[]`
-      with the same comment, and Desktop's spawn dialog tells the user "Empty = all skills enabled".
-  
-      0.25.0 copied the MCP reading (`[]` = granted nothing) onto this field and inverted it. Because
-      the definition normalises to `[]`, EVERY custom agent ever created carries one — so every one
-      of them silently got no skills at all, having been told empty meant everything.
-  
-      MCP grants could afford the stricter reading because they were new and nothing had a prior
-      meaning. This field is not new. Honour what the UI has been promising.
+      ⚠️ THIS SET COMES FROM `grantedSkills`, WHICH IS NEW — so `[]` correctly means "granted
+      nothing", the MCP contract. It must NEVER be fed `enabledSkills`, which holds MACRO ids and
+      has always documented empty as "all"; 0.25.0 conflated the two and every custom agent
+      silently lost its skills. The field is now named `grantedSkills` on both sides, so the two
+      cannot be mixed up by a caller that does not read this comment.
     */
-    const allowlist = context.enabledSkills?.length ? new Set(context.enabledSkills) : null;
+    const allowlist = context.grantedSkills ? new Set(context.grantedSkills) : null;
     return skills.filter((skill) => {
         if (skill.enabled === false)
             return false;
@@ -86,7 +79,7 @@ export function resolveSkillsForAgent(skills, context) {
                     return false;
             }
         }
-        // Stage 1.4 — Agent's explicit enabledSkills allowlist (legacy mechanism).
+        // Stage 1.4 — the agent's explicit grant.
         if (allowlist && !allowlist.has(skill.name))
             return false;
         return true;
@@ -101,11 +94,15 @@ export function resolveSkillsForAgent(skills, context) {
  * than once. Every judgement lives here: which fields of the agent matter, and what an absent
  * allowlist means.
  *
- * ⚠️ `enabledSkills` DOES NOT FOLLOW THE MCP GRANT CONTRACT, and must not be made to. There,
- * `[]` means "granted nothing" because the field was new. Here both `undefined` and `[]` mean
- * "unrestricted": the field predates choosable skills, `createCustomAgentDefinition` normalises
- * `undefined` to `[]`, and every UI that collects it says empty means all. Only a NON-EMPTY list
- * filters.
+ * ⚠️ READS `grantedSkills`. There used to be a second field, `enabledSkills`, holding MACRO ids —
+ * the 13 its picker offered were `code-review`, `debug`, `design`, `prd` and friends, all things
+ * a user types — and 0.25.0 wired Skills enforcement onto it, so ticking "Code Review" wrote a
+ * name no installed skill has and the agent silently got zero skills. That field is deleted, and
+ * the reason it must never come back in another guise is the whole point of this comment.
+ *
+ * `grantedSkills` follows the MCP contract: `undefined` = never asked, reaches everything
+ * eligible; `[]` = granted nothing. That reading is legitimate here precisely because the field
+ * is new and nothing has a prior meaning.
  *
  * @param pool  every skill installed for this machine/project, unfiltered
  * @param agent the agent being built — role, id and its allowlist come from here
@@ -115,7 +112,7 @@ export function resolveSkillsForTeamAgent(pool, agent, opts = {}) {
     return resolveSkillsForAgent(pool, {
         role: agent.role,
         agentId: agent.id,
-        enabledSkills: agent.enabledSkills,
+        grantedSkills: agent.grantedSkills,
         projectType: opts.projectType,
         toolNames: opts.toolNames,
     });

package/dist/skills/software-macros.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Software Development Macros
+ *
+ * design, sketch, prd, refine, refine-item, architecture, session-notes, build, scaffold
+ */
+export declare const designMacro: import("@compilr-dev/agents").Skill;
+export declare const refineMacro: import("@compilr-dev/agents").Skill;
+export declare const sketchMacro: import("@compilr-dev/agents").Skill;
+export declare const refineItemMacro: import("@compilr-dev/agents").Skill;
+export declare const architectureMacro: import("@compilr-dev/agents").Skill;
+export declare const prdMacro: import("@compilr-dev/agents").Skill;
+export declare const sessionNotesMacro: import("@compilr-dev/agents").Skill;
+export declare const buildMacro: import("@compilr-dev/agents").Skill;
+export declare const scaffoldMacro: import("@compilr-dev/agents").Skill;