@compilr-dev/sdk 0.5.8 → 0.6.0

package/dist/index.d.ts

@@ -61,10 +61,11 @@ export type { AskUserQuestion, AskUserInput, AskUserResult, AskUserHandler, AskU
 export { createPlatformTools, createProjectTools, createWorkItemTools, createDocumentTools, createPlanTools, createBacklogTools, createAnchorTools, createArtifactTools, createEpisodeTools, ProjectAnchorStore, } from './platform/index.js';
 export type { ProjectAnchorStoreConfig } from './platform/index.js';
 export { STEP_ORDER, GUIDED_STEP_CRITERIA, getNextStep, isValidTransition, getStepCriteria, formatStepDisplay, getStepNumber, } from './platform/index.js';
-export { platformSkills, designSkill, sketchSkill, prdSkill, refineSkill, refineItemSkill, architectureSkill, sessionNotesSkill, buildSkill, scaffoldSkill, outlineSkill, literatureReviewSkill, draftSectionSkill, peerReviewSkill, } from './skills/index.js';
+export { platformSkills, designSkill, sketchSkill, prdSkill, refineSkill, refineItemSkill, architectureSkill, sessionNotesSkill, buildSkill, scaffoldSkill, outlineSkill, literatureReviewSkill, draftSectionSkill, peerReviewSkill, researchScaffoldSkill, } 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, getProjectTypesByCategory, generalConfig, softwareConfig, researchConfig, businessPlanConfig, contentConfig, techDocsConfig, courseConfig, } from './project-types/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 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 type { Tool, HooksConfig, AgentEvent, Message, LLMProvider, AnchorInput, ToolExecutionResult, AgentRunResult, PermissionHandler, ToolPermission, AgentTypeConfig, GuardrailTriggeredHandler, BeforeLLMHookResult, BeforeToolHook, BeforeToolHookResult, AfterToolHook, AgentState, AgentConfig, SessionInfo, Anchor, AnchorScope, AnchorClearOptions, AnchorPriority, AnchorQueryOptions, FileAccessType, FileAccess, GuardrailResult, GuardrailContext, MCPClient, MCPToolDefinition, } from '@compilr-dev/agents';

package/dist/index.js

@@ -139,7 +139,7 @@ export { STEP_ORDER, GUIDED_STEP_CRITERIA, getNextStep, isValidTransition, getSt
 // =============================================================================
 // Platform Skills (platform-specific prompt expansions)
 // =============================================================================
-export { platformSkills, designSkill, sketchSkill, prdSkill, refineSkill, refineItemSkill, architectureSkill, sessionNotesSkill, buildSkill, scaffoldSkill, outlineSkill, literatureReviewSkill, draftSectionSkill, peerReviewSkill, } from './skills/index.js';
+export { platformSkills, designSkill, sketchSkill, prdSkill, refineSkill, refineItemSkill, architectureSkill, sessionNotesSkill, buildSkill, scaffoldSkill, outlineSkill, literatureReviewSkill, draftSectionSkill, peerReviewSkill, researchScaffoldSkill, } from './skills/index.js';
 // =============================================================================
 // Contextual Actions (skill invocations with context)
 // =============================================================================
@@ -147,7 +147,9 @@ export { ACTION_REGISTRY, getActionsForContext, getActionById, resolveActionProm
 // =============================================================================
 // Project Types
 // =============================================================================
-export { PROJECT_TYPES, getProjectTypeConfig, getProjectTypesByCategory, generalConfig, softwareConfig, researchConfig, businessPlanConfig, contentConfig, techDocsConfig, courseConfig, } from './project-types/index.js';
+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';
 // =============================================================================
 // Re-exports from @compilr-dev/agents (convenience — no need to install separately)
 // =============================================================================

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

@@ -0,0 +1,14 @@
+/**
+ * Action Metadata
+ *
+ * Defines UI metadata for project-level and work-item-level actions.
+ * Referenced by ProjectTypeConfig.projectActionsMeta / workItemActionsMeta.
+ */
+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.
+ */
+export declare function resolveActionMeta(actionIds: readonly string[]): ActionMeta[];

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

@@ -0,0 +1,34 @@
+/**
+ * Action Metadata
+ *
+ * Defines UI metadata for project-level and work-item-level actions.
+ * Referenced by ProjectTypeConfig.projectActionsMeta / workItemActionsMeta.
+ */
+/** 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' },
+    // ── 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' },
+};
+/**
+ * Resolve action IDs to ActionMeta objects.
+ * Unknown IDs are returned with a fallback label.
+ */
+export function resolveActionMeta(actionIds) {
+    return actionIds.map((id) => ACTION_META_REGISTRY[id] ?? { id, label: id, icon: 'Zap', description: id });
+}

package/dist/project-types/configs.js

@@ -154,7 +154,7 @@ export const researchConfig = {
         { type: 'bibliography', label: 'Bibliography', description: 'References and citations' },
         { type: 'session-notes', label: 'Session Notes', description: 'Summary of work done' },
     ],
-    projectActions: ['outline', 'literature-review', 'draft-section', 'peer-review', 'session-notes'],
+    projectActions: ['research-scaffold', 'outline', 'literature-review', 'draft-section', 'peer-review', 'session-notes'],
     workItemActions: ['draft-section', 'explain'],
     workItemLabels: {
         feature: { short: 'SC', full: 'Section' },

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

@@ -5,8 +5,10 @@
  * document templates, and skills. The underlying platform is the same
  * for all types.
  */
-export type { ProjectTypeConfig, ProjectPhase, SuggestedAgent, DocumentTemplate } from './types.js';
+export type { ProjectTypeConfig, ProjectPhase, SuggestedAgent, DocumentTemplate, ActionMeta, SkillMeta } from './types.js';
 export { generalConfig, softwareConfig, researchConfig, businessPlanConfig, contentConfig, techDocsConfig, courseConfig, } from './configs.js';
+export { SKILL_META_REGISTRY, getSkillMeta, getAllSkillMeta } from './skill-meta.js';
+export { ACTION_META_REGISTRY, resolveActionMeta } from './action-meta.js';
 import type { ProjectTypeConfig } from './types.js';
 /** All registered project types */
 export declare const PROJECT_TYPES: ProjectTypeConfig[];
@@ -14,3 +16,8 @@ export declare const PROJECT_TYPES: ProjectTypeConfig[];
 export declare function getProjectTypeConfig(typeId: string): ProjectTypeConfig;
 /** Get project types grouped by category. */
 export declare function getProjectTypesByCategory(): Map<string, ProjectTypeConfig[]>;
+/**
+ * Get a fully enriched project type config with resolved action metadata.
+ * This is the primary API for the desktop app — returns everything needed for UI rendering.
+ */
+export declare function getEnrichedProjectTypeConfig(typeId: string): ProjectTypeConfig;

package/dist/project-types/index.js

@@ -7,6 +7,10 @@
  */
 // Configs
 export { generalConfig, softwareConfig, researchConfig, businessPlanConfig, contentConfig, techDocsConfig, courseConfig, } 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';
+import { resolveActionMeta } from './action-meta.js';
 import { generalConfig, softwareConfig, researchConfig, businessPlanConfig, contentConfig, techDocsConfig, courseConfig, } from './configs.js';
 /** All registered project types */
 export const PROJECT_TYPES = [
@@ -32,3 +36,19 @@ export function getProjectTypesByCategory() {
     }
     return groups;
 }
+/**
+ * Get a fully enriched project type config with resolved action metadata.
+ * This is the primary API for the desktop app — returns everything needed for UI rendering.
+ */
+export function getEnrichedProjectTypeConfig(typeId) {
+    const config = getProjectTypeConfig(typeId);
+    // Auto-populate *Meta arrays from action IDs if not explicitly set
+    if (!config.projectActionsMeta) {
+        return {
+            ...config,
+            projectActionsMeta: resolveActionMeta(config.projectActions),
+            workItemActionsMeta: resolveActionMeta(config.workItemActions),
+        };
+    }
+    return config;
+}

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

@@ -0,0 +1,17 @@
+/**
+ * Skill Metadata Registry
+ *
+ * Maps skill IDs to UI metadata (label, icon, category).
+ * This is the single source of truth — the desktop reads this via IPC.
+ */
+import type { SkillMeta } from './types.js';
+/** All skill UI metadata — platform skills + builtin skills */
+export declare const SKILL_META_REGISTRY: Record<string, SkillMeta>;
+/**
+ * Get skill metadata by ID.
+ */
+export declare function getSkillMeta(skillId: string): SkillMeta | undefined;
+/**
+ * Get all skill metadata entries.
+ */
+export declare function getAllSkillMeta(): SkillMeta[];

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

@@ -0,0 +1,44 @@
+/**
+ * Skill Metadata Registry
+ *
+ * Maps skill IDs to UI metadata (label, icon, category).
+ * This is the single source of truth — the desktop reads this via IPC.
+ */
+/** All skill UI metadata — platform skills + builtin skills */
+export const SKILL_META_REGISTRY = {
+    // ── Platform Skills (SDK) ────────────────────────────────────────────────
+    'design': { id: 'design', label: 'Design App', description: 'Guide through project design', icon: 'Wand2', category: 'design' },
+    'sketch': { id: 'sketch', label: 'Quick Sketch', description: 'Quick project outline', icon: 'Pencil', category: 'design' },
+    'prd': { id: 'prd', label: 'Write PRD', description: 'Product requirements document', icon: 'FileText', category: 'planning' },
+    'refine': { id: 'refine', label: 'Refine Backlog', description: 'Expand and refine requirements', icon: 'RefreshCw', category: 'planning' },
+    'refine-item': { id: 'refine-item', label: 'Refine Item', description: 'Add detail to a work item', icon: 'RefreshCw', category: 'planning' },
+    'architecture': { id: 'architecture', label: 'Architecture', description: 'System architecture design', icon: 'Network', category: 'design' },
+    'session-notes': { id: 'session-notes', label: 'Session Notes', description: 'Summarize work done', icon: 'StickyNote', category: 'documentation' },
+    'build': { id: 'build', label: 'Build', description: 'Implement a feature', icon: 'Hammer', category: 'development' },
+    'scaffold': { id: 'scaffold', label: 'Scaffold', description: 'Generate project code', icon: 'Layers', category: 'development' },
+    // ── Research Skills ──────────────────────────────────────────────────────
+    'outline': { id: 'outline', label: 'Paper Outline', description: 'Build paper structure', icon: 'BookOpen', category: 'research' },
+    'literature-review': { id: 'literature-review', label: 'Lit Review', description: 'Analyze sources', icon: 'Search', category: 'research' },
+    'draft-section': { id: 'draft-section', label: 'Draft Section', description: 'Write a paper section', icon: 'PenTool', category: 'research' },
+    'peer-review': { id: 'peer-review', label: 'Peer Review', description: 'Validate argument structure', icon: 'ShieldCheck', category: 'research' },
+    'research-scaffold': { id: 'research-scaffold', label: 'New Paper', description: 'Set up from a template', icon: 'Layers', category: 'research' },
+    // ── Builtin Skills (agents library) ──────────────────────────────────────
+    'code-review': { id: 'code-review', label: 'Code Review', description: 'Review code quality', icon: 'Search', category: 'development' },
+    'debug': { id: 'debug', label: 'Debug', description: 'Find and fix bugs', icon: 'Bug', category: 'development' },
+    'explain': { id: 'explain', label: 'Explain', description: 'Explain code or concept', icon: 'BookOpen', category: 'documentation' },
+    'refactor': { id: 'refactor', label: 'Refactor', description: 'Improve code structure', icon: 'Scissors', category: 'development' },
+    'security-review': { id: 'security-review', label: 'Security Review', description: 'Check for vulnerabilities', icon: 'Shield', category: 'analysis' },
+    'planning': { id: 'planning', label: 'Planning', description: 'Plan implementation approach', icon: 'ListTodo', category: 'planning' },
+};
+/**
+ * Get skill metadata by ID.
+ */
+export function getSkillMeta(skillId) {
+    return SKILL_META_REGISTRY[skillId];
+}
+/**
+ * Get all skill metadata entries.
+ */
+export function getAllSkillMeta() {
+    return Object.values(SKILL_META_REGISTRY);
+}

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

@@ -39,6 +39,30 @@ export interface DocumentTemplate {
     /** Initial template content (markdown) */
     template?: string;
 }
+/**
+ * UI metadata for a project-level or work-item-level action.
+ */
+export interface ActionMeta {
+    id: string;
+    label: string;
+    /** Lucide icon name */
+    icon: string;
+    description: string;
+    category?: string;
+    /** Suggested agent role for this action (work item actions) */
+    suggestedRole?: string;
+}
+/**
+ * UI metadata for a skill.
+ */
+export interface SkillMeta {
+    id: string;
+    label: string;
+    description: string;
+    /** Lucide icon name */
+    icon: string;
+    category: 'design' | 'development' | 'planning' | 'documentation' | 'analysis' | 'research';
+}
 /**
  * Full project type configuration.
  */
@@ -68,6 +92,10 @@ export interface ProjectTypeConfig {
         short: string;
         full: string;
     }>>;
+    /** Project-level actions with full UI metadata (replaces projectActions for UI rendering) */
+    projectActionsMeta?: ActionMeta[];
+    /** Work item actions with full UI metadata (replaces workItemActions for UI rendering) */
+    workItemActionsMeta?: ActionMeta[];
     /** Context line injected into the system prompt (one-liner, deprecated — use systemPromptSection) */
     systemPromptContext: string;
     /** Rich multi-line system prompt section for the default agent. Takes precedence over systemPromptContext. */

package/dist/skills/index.d.ts

@@ -1,4 +1,4 @@
 /**
  * Platform Skills — barrel export
  */
-export { platformSkills, designSkill, sketchSkill, prdSkill, refineSkill, refineItemSkill, architectureSkill, sessionNotesSkill, buildSkill, scaffoldSkill, outlineSkill, literatureReviewSkill, draftSectionSkill, peerReviewSkill, } from './platform-skills.js';
+export { platformSkills, designSkill, sketchSkill, prdSkill, refineSkill, refineItemSkill, architectureSkill, sessionNotesSkill, buildSkill, scaffoldSkill, outlineSkill, literatureReviewSkill, draftSectionSkill, peerReviewSkill, researchScaffoldSkill, } from './platform-skills.js';

package/dist/skills/index.js

@@ -1,4 +1,4 @@
 /**
  * Platform Skills — barrel export
  */
-export { platformSkills, designSkill, sketchSkill, prdSkill, refineSkill, refineItemSkill, architectureSkill, sessionNotesSkill, buildSkill, scaffoldSkill, outlineSkill, literatureReviewSkill, draftSectionSkill, peerReviewSkill, } from './platform-skills.js';
+export { platformSkills, designSkill, sketchSkill, prdSkill, refineSkill, refineItemSkill, architectureSkill, sessionNotesSkill, buildSkill, scaffoldSkill, outlineSkill, literatureReviewSkill, draftSectionSkill, peerReviewSkill, researchScaffoldSkill, } from './platform-skills.js';

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

@@ -21,8 +21,9 @@ export declare const outlineSkill: Skill;
 export declare const literatureReviewSkill: Skill;
 export declare const draftSectionSkill: Skill;
 export declare const peerReviewSkill: Skill;
+export declare const researchScaffoldSkill: Skill;
 /**
- * All platform-specific skills (13 total).
+ * All platform-specific skills (14 total).
  * These skills reference platform tools (backlog, workitems, documents, projects)
  * and belong in the SDK rather than in generic agent/coding libraries.
  */

package/dist/skills/platform-skills.js

@@ -1355,11 +1355,65 @@ For issues that affect the Research Model:
 ✓ User has received the review summary`,
     tags: ['research', 'review', 'quality'],
 });
+export const researchScaffoldSkill = defineSkill({
+    name: 'research-scaffold',
+    description: 'Scaffold a research paper project from a template (APA, IEEE, Thesis, Literature Review, Lab Report)',
+    prompt: `You are in RESEARCH SCAFFOLD MODE. Your goal is to help the user set up a new research paper project using a template.
+
+## Available Templates
+
+| Template | ID | Best For |
+|----------|-----|----------|
+| APA Research Paper | \`apa-paper\` | Social sciences, psychology, education |
+| IEEE Conference Paper | \`ieee-paper\` | Engineering, computer science |
+| Thesis / Dissertation | \`thesis\` | Graduate work, multi-chapter |
+| Literature Review | \`literature-review\` | Standalone review papers |
+| Lab Report | \`lab-report\` | Scientific experiments |
+
+## Step 1: Gather Info
+
+Ask the user (if not already provided):
+1. What is the paper topic / title?
+2. Which template best fits their needs? (describe the options briefly)
+3. What citation style? (default depends on template — APA for most, IEEE for engineering)
+
+## Step 2: Scaffold
+
+Call the \`research_scaffold\` tool with:
+- \`template\`: the template ID
+- \`title\`: the paper title
+- \`citation_style\`: if different from template default
+- \`output_dir\`: the project path
+
+This creates:
+- A Research Model with pre-defined sections
+- Folder structure (sections/, figures/, references/, knowledge/)
+- Section stub files (one per section)
+- COMPILR.md with project context
+- Bibliography file (.bib)
+- Work items for each section (type: "Section")
+
+## Step 3: Confirm and Guide
+
+After scaffolding, tell the user:
+- What was created (sections, files, work items)
+- Suggested next steps:
+  1. "Add your source material to the Knowledge Base"
+  2. "Run /outline to customize the section structure"
+  3. "Run /literature-review to analyze your sources"
+  4. "Run /draft-section to start writing"
+
+## Rules
+- If a Research Model already exists, warn the user and don't overwrite
+- Use dry_run first if the user seems uncertain
+- The scaffold is a starting point — the user can customize everything after`,
+    tags: ['research', 'scaffold', 'setup'],
+});
 // =============================================================================
 // Aggregate export
 // =============================================================================
 /**
- * All platform-specific skills (13 total).
+ * All platform-specific skills (14 total).
  * These skills reference platform tools (backlog, workitems, documents, projects)
  * and belong in the SDK rather than in generic agent/coding libraries.
  */
@@ -1377,4 +1431,5 @@ export const platformSkills = [
     literatureReviewSkill,
     draftSectionSkill,
     peerReviewSkill,
+    researchScaffoldSkill,
 ];

package/package.json

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