@compilr-dev/sdk 0.27.0 → 0.28.0

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/skills/canvas-macros.js

@@ -31,7 +31,7 @@ export const canvasMacro = defineSkill({
 - **carousel** — multiple slide "sheets"; author each slide as a top-level \`<section data-sheet>…</section>\`.
 - **board** — an infinite 2D coordinate space of absolutely-positioned node cards + inline-SVG connectors (mind-map / diagram / UI sketch). Wrap in \`<div data-board style="position:relative;width:Wpx;height:Hpx">\`.
 
-**Once you've picked the type, consult its craft guide for the design rules that make it good** — the \`infographic\` skill (hierarchy, grid, stat tiles, restrained color, correct charts), the \`carousel\` skill (one idea per slide, narrative arc, consistent master layout, 16:9 discipline), or the \`board\` skill (declared coordinate space, absolutely-positioned node cards, inline-SVG connectors, clustering). This general skill covers the mechanics (tools, structure, theme, Tweaks); the per-type skill covers the craft.
+**Once you've picked the type, consult its craft guide for the design rules that make it good** — the \`infographic\` macro (hierarchy, grid, stat tiles, restrained color, correct charts), the \`carousel\` macro (one idea per slide, narrative arc, consistent master layout, 16:9 discipline), or the \`board\` macro (declared coordinate space, absolutely-positioned node cards, inline-SVG connectors, clustering). This general macro covers the mechanics (tools, structure, theme, Tweaks); the per-type macro covers the craft.
 
 ## STEPS
 
@@ -89,7 +89,7 @@ stored and what the markup actually uses.
    - Do NOT include \`<html>\`, \`<head>\`, \`<meta>\`, \`<!doctype>\`, or your own CSP — the host injects the sandbox and CSP. Just the body content + a \`<style>\` and optional \`<script>\`.
    - The sandbox is \`allow-scripts\` with NO same-origin and CSP \`default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; img-src data: blob:\`. So: inline \`<style>\`/\`<script>\` only, no external fonts/CSS/JS/network, no remote images (use inline SVG or data: URIs).
    - **Match the app theme by default.** The host injects its live theme palette as CSS variables you MUST use instead of hardcoded colors: \`var(--canvas-bg)\` (page background), \`var(--canvas-fg)\` (text), \`var(--canvas-accent)\` and \`var(--canvas-secondary)\` (highlights), \`var(--canvas-muted)\` (secondary text), \`var(--canvas-border)\` (lines), \`var(--canvas-card)\` (raised surfaces). Only hardcode specific colors when the user explicitly asks for a particular palette or brand.
-   - **Background — infographic & carousel: always set it EXPLICITLY to \`var(--canvas-bg)\`** on your outermost wrapper (and each \`<section data-sheet>\` for a carousel). Do NOT use \`background: transparent\` and do NOT hardcode a fixed color like \`#0a0a0a\`: transparent looks fine in-app but **exports to PDF/HTML on WHITE**, and a fixed color ignores the theme. **EXCEPTION — infinite board: do the OPPOSITE.** Keep the \`data-board\` root **transparent** (do not fill it) — the host paints a dot-grid backdrop that must show through, and filling it turns the infinite surface into a finite rectangle. On a board you style only the node cards; the space between them stays transparent. (See the \`board\` skill.)
+   - **Background — infographic & carousel: always set it EXPLICITLY to \`var(--canvas-bg)\`** on your outermost wrapper (and each \`<section data-sheet>\` for a carousel). Do NOT use \`background: transparent\` and do NOT hardcode a fixed color like \`#0a0a0a\`: transparent looks fine in-app but **exports to PDF/HTML on WHITE**, and a fixed color ignores the theme. **EXCEPTION — infinite board: do the OPPOSITE.** Keep the \`data-board\` root **transparent** (do not fill it) — the host paints a dot-grid backdrop that must show through, and filling it turns the infinite surface into a finite rectangle. On a board you style only the node cards; the space between them stays transparent. (See the \`board\` macro.)
    - Make it look intentional: a clear grid, strong type scale, generous spacing. Use \`var(--canvas-accent)\` sparingly for emphasis. Prefer inline SVG for shapes/charts/icons (fill/stroke with the theme vars).
    - For a **carousel**, wrap each slide in \`<section data-sheet>…</section>\` — a natural unit to add one per \`canvas_edit\` append.
 
@@ -201,7 +201,7 @@ export const infographicMacro = defineSkill({
 - Inline **SVG**, filled/stroked with the theme vars, a consistent stroke width. No emoji as primary iconography.
 
 ## Before you finish
-- Set the background explicitly to \`var(--canvas-bg)\` (see the canvas skill's export note).
+- Set the background explicitly to \`var(--canvas-bg)\` (see the canvas macro's export note).
 - Add 2–4 **bound** Tweaks (accent color, headline size, a section toggle) — declared AND referenced in the HTML.
 
 ## Anti-patterns (fix on sight)
@@ -242,7 +242,7 @@ Structure the sequence like a story, not a list:
 - The same card/grid system reused slide to slide.
 
 ## Before you finish
-- Set \`background: var(--canvas-bg)\` on EACH \`<section data-sheet>\` (see the canvas skill's export note — transparent slides export white).
+- Set \`background: var(--canvas-bg)\` on EACH \`<section data-sheet>\` (see the canvas macro's export note — transparent slides export white).
 - Add 2–4 **bound** Tweaks (accent color, title size, a toggle for footer/page numbers).
 
 ## Anti-patterns (fix on sight)
@@ -335,7 +335,7 @@ export const canvasStylesMacro = defineSkill({
     prompt: `The STYLE CATALOGUE for canvases — pick a coherent visual aesthetic instead of defaulting to the flat theme look. Design guidance; author with the canvas tools (see the \`canvas\` skill for mechanics). Applies to **infographic** and **carousel** (a board is a diagram surface — keep it theme-flat unless asked).
 
 ## How to use it
-- **Offer during the brief, don't over-ask.** In the canvas skill's Step 1, if the user hasn't named a style, include a SHORT aesthetic menu (2–4 fitting options from below) in the SAME \`propose_alternatives\`/\`ask_user\` round — never a separate interview. If they said "surprise me / your call", just pick the one that best fits the content and build.
+- **Offer during the brief, don't over-ask.** In the canvas macro's Step 1, if the user hasn't named a style, include a SHORT aesthetic menu (2–4 fitting options from below) in the SAME \`propose_alternatives\`/\`ask_user\` round — never a separate interview. If they said "surprise me / your call", just pick the one that best fits the content and build.
 - **A style is a SYSTEM, not a trick.** Surfaces, borders, shadows, type, spacing, and accent all move together. Apply the whole recipe — half a recipe reads as a mistake.
 
 ## Hard constraints (every style — the sandbox is strict)

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

@@ -1,44 +1,78 @@
 /**
  * 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 TWO HOSTS SENT DIFFERENT THINGS FOR THE SAME COMMAND. The CLI wrapped each of these
+ * macros in 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 names, same macros, 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.
+ * The prompts were always shared data; what surrounded them 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.
+ * ⚠️ THE TEXT IS TRANSCRIBED, NOT REWRITTEN. Every block below was generated from the CLI's own
+ * template and asserted byte-identical to what it sent before the move, because a single reworded
+ * line here is a silent behaviour change in both hosts at once.
  *
- * Spec: project-docs/00-requirements/compilr-dev-sdk/macros-rename.md
+ * This composes the MESSAGE only. The tool-gap preamble (`macroToolGap`) stays a separate,
+ * host-applied prepend: it depends on which AGENT is addressed, which only the host knows.
  */
-/** What the host knows about the project a macro is being invoked against. */
+/** What the host knows about the project a macro is invoked against. */
 export interface MacroProjectContext {
     id: string | number;
     name: string;
+    /** Absolute path on disk. `build` and `scaffold` write files and need it. */
+    path?: string;
+}
+/** A backlog item, for `build`. */
+export interface MacroWorkItem {
+    itemId: string;
+    type: string;
+    priority: string;
+    title: string;
+    description?: string;
 }
 export interface MacroInvocationContext {
-    /** Absent when no project is selected; the context block is then omitted. */
+    /** Absent when no project is selected; the context block is then omitted entirely. */
     project?: MacroProjectContext;
+    /** `prd` — the section the user named, if any. */
+    section?: string;
+    /** `session-notes` — the title the user gave, if any. */
+    noteTitle?: string;
+    /** `architecture` — the document type chosen, and how to name it back to the user. */
+    architecture?: {
+        docType: string;
+        displayType?: string;
+    };
+    /** `refine` — the item id, when refining one item rather than the whole backlog. */
+    refineItemId?: string;
+    /** `build` — the item to implement. Without it there is nothing to build. */
+    workItem?: MacroWorkItem;
+    /**
+     * `scaffold` — `factoryContext` is a pre-rendered block the host supplies because only it
+     * knows the Application Model's state; `isFactory` picks the closing instruction.
+     */
+    scaffold?: {
+        factoryContext?: string;
+        isFactory?: boolean;
+    };
 }
 export interface MacroInvocation {
     /** The text to send to the agent. */
     message: string;
-    /** The text to show the user in the transcript, in place of the full message. */
+    /** The short line to show the user in place of the full message. */
     displayMessage: string;
 }
 /**
  * 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.
+ * A macro with no wrapper sends its prompt unchanged — the common case, and the default, so
+ * adding a macro needs no edit here. A macro WITH a wrapper falls back to the bare prompt when
+ * the host cannot supply what the wrapper names: better a plain prompt than one asserting a
+ * project, an item or a path that is not there.
  *
  * @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
+ * @param ctx       what the host knows
  */
 export declare function buildMacroInvocation(macroName: string, prompt: string, ctx?: MacroInvocationContext): MacroInvocation;

package/dist/skills/macro-invocation.js

@@ -1,26 +1,21 @@
 /**
  * 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 TWO HOSTS SENT DIFFERENT THINGS FOR THE SAME COMMAND. The CLI wrapped each of these
+ * macros in 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 names, same macros, 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.
+ * The prompts were always shared data; what surrounded them 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.
+ * ⚠️ THE TEXT IS TRANSCRIBED, NOT REWRITTEN. Every block below was generated from the CLI's own
+ * template and asserted byte-identical to what it sent before the move, because a single reworded
+ * line here is a silent behaviour change in both hosts at once.
  *
- * 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.
+ * This composes the MESSAGE only. The tool-gap preamble (`macroToolGap`) stays a separate,
+ * host-applied prepend: it depends on which AGENT is addressed, which only the host knows.
  */
 function designContext(project) {
     return `I want to design my project and create the backlog.
@@ -42,22 +37,250 @@ Save all documents and backlog items using the database - do NOT write files dir
 }
 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.';
+function sketchMessage(p, prompt) {
+    return `I want to quickly outline my project.
+
+## PROJECT CONTEXT (IMPORTANT)
+- Project Name: ${p.name} (ID: ${String(p.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: "..." })\`
+- For documents: \`project_document_add({ doc_type: "prd", title: "...", content: "..." })\`
+- Do NOT use write_file or edit tools for documentation
+
+${prompt}
+
+Please start by asking me about the type of application I'm building using the ask_user_simple tool.`;
+}
+function refineMessage(p, prompt, userIntent, agentInstructions) {
+    return `${userIntent}
+
+## PROJECT CONTEXT (IMPORTANT)
+- Project Name: ${p.name} (ID: ${String(p.id)})
+- Do NOT scan the filesystem - the current directory is NOT the project
+- Do NOT use detect_project, glob, read_file, or ls tools
+- Use ONLY database tools to access project data
+
+## DOCUMENT STORAGE (CRITICAL)
+Use database tools for all updates - do NOT write files directly.
+- Use \`workitem_query\` to read items
+- Use \`workitem_update\` to modify items
+- Do NOT use write_file or edit tools
+
+${prompt}
+
+${agentInstructions}`;
+}
+function buildMessage(p, prompt, item) {
+    return `I want to implement backlog item ${item.itemId}: "${item.title}".
+
+## PROJECT CONTEXT (CRITICAL)
+- Project Name: ${p.name} (ID: ${String(p.id)})
+- **Project Directory: ${p.path ?? ''}**
+- ALL files MUST be created/modified in this directory
+
+## WORK ITEM DETAILS
+- Item ID: ${item.itemId}
+- Type: ${item.type}
+- Priority: ${item.priority}
+- Description: ${item.description ?? 'No description provided'}
+
+## TOOL RESTRICTIONS (CRITICAL)
+- Do NOT use detect_project or find_project_root
+- Do NOT scan filesystem to detect project type
+- The project path above is the ONLY source of truth for where to create/modify files
+- Use \`project_document_get\` to read PRD and architecture docs from the database
+- Use \`workitem_query\` to read related backlog items from the database
+- Use \`workitem_update\` to update the item status when done
+
+## FILE OPERATIONS (CRITICAL)
+When creating or modifying files:
+- Use absolute paths starting with: ${p.path ?? ''}/
+- Example: write_file({ path: "${p.path ?? ''}/src/index.ts", ... })
+- NEVER use relative paths
+- IGNORE the current working directory (cwd) - it may be different from the project!
+- The user may have started the CLI from a different folder
+
+${prompt}
+
+Please start by:
+1. Using todo_write to plan the implementation steps
+2. Reading project documents from the database (project_document_list, project_document_get)
+3. Updating the work item status to 'in_progress' using workitem_update
+4. Implementing the feature
+5. Updating the work item status to 'completed' when done`;
+}
+function sessionNotesMessage(p, prompt, titleInstruction) {
+    return `I want to create a session note capturing what we've done.
+
+## PROJECT CONTEXT
+- Project Name: ${p.name} (ID: ${String(p.id)})
+
+## DOCUMENT STORAGE (CRITICAL)
+Save session notes using the database - do NOT write files directly.
+- Tool: \`project_document_add({ doc_type: "session-note", title: "...", content: "..." })\`
+- The database is the source of truth for all project documents
+- Do NOT use write_file or edit tools for documentation
+
+${prompt}
+
+${titleInstruction}
+
+Review the conversation context to understand what was accomplished, then create the session note.`;
+}
+function prdMessage(p, prompt, sectionInstruction) {
+    return `I want to update the Product Requirements Document.
+
+## DOCUMENT STORAGE (CRITICAL)
+Save PRD updates using the database - do NOT write files directly.
+- Project: ${p.name} (ID: ${String(p.id)})
+- Tool: \`project_document_add({ doc_type: "prd", title: "Product Requirements Document", content: "..." })\`
+- The database is the source of truth for all project documents
+- Do NOT use write_file or edit tools for documentation
+
+${prompt}
+
+${sectionInstruction}
+
+Start by reading the existing PRD from the database using project_document_get({ doc_type: "prd" }). If no document exists yet, create a new one.`;
+}
+function architectureMessage(p, prompt, arch) {
+    return `I want to create architecture documentation.
+
+## DOCUMENT STORAGE (CRITICAL)
+Save architecture documentation using the database - do NOT write files directly.
+- Project: ${p.name} (ID: ${String(p.id)})
+- Tool: \`project_document_add({ doc_type: "architecture", title: "...", content: "..." })\`
+- The database is the source of truth for all project documents
+- Do NOT use write_file or edit tools for documentation
+
+${prompt}
+
+Please start by using project_document_list to find any existing PRD, and workitem_query to understand the project backlog. Then use ask_user to gather the information needed for this ${arch.docType} document.`;
+}
+function scaffoldMessage(p, prompt, factoryContext, closingInstruction) {
+    return `I want to create the project scaffold/foundation.
+
+## PROJECT CONTEXT (CRITICAL)
+- Project Name: ${p.name} (ID: ${String(p.id)})
+- **Project Directory: ${p.path ?? ''}**
+- ALL files MUST be created in this directory
+${factoryContext}
+## TOOL RESTRICTIONS (CRITICAL)
+- Do NOT use detect_project or find_project_root
+- Do NOT scan filesystem to detect project type
+- The project path above is the ONLY source of truth for where to create files
+- Use \`project_document_get\` to read PRD and architecture docs from the database
+- Use \`workitem_query\` to read backlog items from the database
+
+## FILE CREATION (CRITICAL)
+When creating files:
+- Use absolute paths starting with: ${p.path ?? ''}/
+- Example: write_file({ path: "${p.path ?? ''}/package.json", ... })
+- NEVER use relative paths
+- IGNORE the current working directory (cwd) - it may be different from the project!
+- The user may have started the CLI from a different folder
+
+${prompt}
+
+${closingInstruction}`;
+}
 /**
  * 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.
+ * A macro with no wrapper sends its prompt unchanged — the common case, and the default, so
+ * adding a macro needs no edit here. A macro WITH a wrapper falls back to the bare prompt when
+ * the host cannot supply what the wrapper names: better a plain prompt than one asserting a
+ * project, an item or a path that is not there.
  *
  * @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
+ * @param ctx       what the host knows
  */
 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.',
-        };
+    const p = ctx.project;
+    if (!p)
+        return { message: prompt, displayMessage: `/${macroName}` };
+    switch (macroName) {
+        case 'design':
+            return {
+                message: `${designContext(p)}\n${prompt}\n\n${DESIGN_CLOSER}`,
+                displayMessage: 'Start the design process for my project.',
+            };
+        case 'sketch':
+            return { message: sketchMessage(p, prompt), displayMessage: 'Quick project outline.' };
+        case 'refine':
+        case 'refine-item': {
+            // Bound to a local so the narrowing survives into the template literals.
+            const itemId = ctx.refineItemId;
+            const userIntent = itemId !== undefined
+                ? `I want to refine backlog item ${itemId}.`
+                : 'I want to refine my project requirements.';
+            const agentInstructions = itemId !== undefined
+                ? `Please use workitem_query to find item "${itemId}", then guide me through refining it using workitem_update.`
+                : "Please start by using workitem_query with limit:10 to get an overview, then ask me what I'd like to focus on using ask_user_simple.";
+            return {
+                message: refineMessage(p, prompt, userIntent, agentInstructions),
+                displayMessage: userIntent,
+            };
+        }
+        case 'build': {
+            // Nothing to build without an item, and the whole wrapper is about one.
+            if (!ctx.workItem)
+                return { message: prompt, displayMessage: `/${macroName}` };
+            return {
+                message: buildMessage(p, prompt, ctx.workItem),
+                displayMessage: `Build ${ctx.workItem.itemId}: ${ctx.workItem.title}`,
+            };
+        }
+        case 'session-notes': {
+            const titleInstruction = ctx.noteTitle
+                ? `The session title is: "${ctx.noteTitle}"`
+                : 'Please ask me for a title using ask_user_simple, or generate one from the session summary.';
+            return {
+                message: sessionNotesMessage(p, prompt, titleInstruction),
+                displayMessage: ctx.noteTitle
+                    ? `Create session note: "${ctx.noteTitle}"`
+                    : 'Create a session note for this session.',
+            };
+        }
+        case 'prd': {
+            const valid = ['vision', 'scope', 'technical', 'success'];
+            const section = ctx.section ?? '';
+            const sectionInstruction = valid.includes(section)
+                ? `The user wants to update the "${section}" section specifically.`
+                : 'Ask the user which section they want to update using ask_user_simple.';
+            return {
+                message: prdMessage(p, prompt, sectionInstruction),
+                displayMessage: section
+                    ? `Update PRD: ${section} section`
+                    : 'Update the Product Requirements Document',
+            };
+        }
+        case 'architecture': {
+            if (!ctx.architecture)
+                return { message: prompt, displayMessage: `/${macroName}` };
+            return {
+                message: architectureMessage(p, prompt, ctx.architecture),
+                displayMessage: `Create ${ctx.architecture.displayType ?? ctx.architecture.docType} documentation.`,
+            };
+        }
+        case 'scaffold':
+        case 'factory-scaffold': {
+            const closingInstruction = macroName === 'factory-scaffold' || ctx.scaffold?.isFactory
+                ? 'Start by checking the Application Model with app_model_get. If no model exists, read the PRD with project_document_get and build the model incrementally using app_model_update. Then generate with factory_scaffold.'
+                : 'Start by reading the project documents from the database using project_document_list and project_document_get. Then create a plan with todo_write before generating files.';
+            return {
+                message: scaffoldMessage(p, prompt, ctx.scaffold?.factoryContext ?? '', closingInstruction),
+                displayMessage: 'Create project scaffold.',
+            };
+        }
+        default:
+            return { message: prompt, displayMessage: `/${macroName}` };
     }
-    return { message: prompt, displayMessage: `/${macroName}` };
 }

package/dist/skills/software-macros.js

@@ -18,9 +18,9 @@ export const designMacro = defineSkill({
 - Need to create initial backlog
 
 ## When NOT to Use
-- Project already has requirements → use refine skill
-- Quick project outline needed → use sketch skill
-- Just need to update PRD → use prd skill
+- Project already has requirements → tell the user to run /refine
+- Quick project outline needed → tell the user to run /sketch
+- Just need to update PRD → tell the user to run /prd
 
 ## PHASES
 
@@ -104,9 +104,9 @@ export const refineMacro = defineSkill({
 - Adding missing items to backlog
 
 ## When NOT to Use
-- No backlog exists yet → use design skill
-- Quick outline needed → use sketch skill
-- Refining single item → use refine-item skill
+- No backlog exists yet → tell the user to run /design
+- Quick outline needed → tell the user to run /sketch
+- Refining single item → tell the user to run /refine-item
 
 ## STARTUP
 
@@ -182,9 +182,9 @@ export const sketchMacro = defineSkill({
 - Initial brainstorming session
 
 ## When NOT to Use
-- Detailed requirements needed → use design skill
-- Project already has backlog → use refine skill
-- Single item focus → use refine-item skill
+- Detailed requirements needed → tell the user to run /design
+- Project already has backlog → tell the user to run /refine
+- Single item focus → tell the user to run /refine-item
 
 STEPS:
 1. Use todo_write with 6 tasks (one per question)
@@ -221,9 +221,9 @@ export const refineItemMacro = defineSkill({
 - Changing priority of specific item
 
 ## When NOT to Use
-- Multiple items need refinement → use refine skill
-- No items exist yet → use design or sketch skill
-- Ready to implement → use build skill
+- Multiple items need refinement → tell the user to run /refine
+- No items exist yet → tell the user to run /design or /sketch
+- Ready to implement → tell the user to run /build
 
 ## STARTUP
 
@@ -290,9 +290,9 @@ export const architectureMacro = defineSkill({
 - Recording technical decisions
 
 ## When NOT to Use
-- Need product requirements → use design or prd skill
-- Need to implement features → use build skill
-- Just want to understand existing code → use explain skill
+- Need product requirements → tell the user to run /design or /prd
+- Need to implement features → tell the user to run /build
+- Just want to understand existing code → tell the user to run /explain
 
 ## DOCUMENT TYPE: {{doc_type}}
 {{#if custom_topic}}Custom Topic: {{custom_topic}}{{/if}}
@@ -434,9 +434,9 @@ export const prdMacro = defineSkill({
 - Refining vision or scope
 
 ## When NOT to Use
-- No PRD exists yet → use design skill first
-- Need architecture docs → use architecture skill
-- Need session summary → use session-notes skill
+- No PRD exists yet → tell the user to run /design first
+- Need architecture docs → tell the user to run /architecture
+- Need session summary → tell the user to run /session-notes
 
 ## STARTUP
 
@@ -519,8 +519,8 @@ export const sessionNotesMacro = defineSkill({
 - Need to capture decisions for future reference
 
 ## When NOT to Use
-- Need product requirements → use prd skill
-- Need architecture docs → use architecture skill
+- Need product requirements → tell the user to run /prd
+- Need architecture docs → tell the user to run /architecture
 - In the middle of active work
 
 ## STARTUP
@@ -614,10 +614,10 @@ export const buildMacro = defineSkill({
 - Ready to write code for a feature
 
 ## When NOT to Use
-- Item is too vague → use refine-item skill first
-- No backlog exists → use design or sketch skill
-- Just exploring code → use code-navigation skill
-- Need to fix a bug → use debug skill
+- Item is too vague → tell the user to run /refine-item first
+- No backlog exists → tell the user to run /design or /sketch
+- Just exploring code → tell the user to run /code-navigation
+- Need to fix a bug → tell the user to run /debug
 
 ## CRITICAL: PROJECT DIRECTORY
 
@@ -711,9 +711,9 @@ export const scaffoldMacro = defineSkill({
 - Need basic project structure
 
 ## When NOT to Use
-- Project already has structure → use build skill
-- Need requirements first → use design skill
-- Modifying existing project → use appropriate skill
+- Project already has structure → tell the user to run /build
+- Need requirements first → tell the user to run /design
+- Modifying existing project → tell the user to run /appropriate
 
 ## FACTORY CHECK (TRY THIS FIRST)
 

package/package.json

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