@compilr-dev/sdk 0.5.4 → 0.5.6

package/dist/index.d.ts

@@ -61,7 +61,7 @@ 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, } from './skills/index.js';
+export { platformSkills, designSkill, sketchSkill, prdSkill, refineSkill, refineItemSkill, architectureSkill, sessionNotesSkill, buildSkill, scaffoldSkill, outlineSkill, literatureReviewSkill, } 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';

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, } from './skills/index.js';
+export { platformSkills, designSkill, sketchSkill, prdSkill, refineSkill, refineItemSkill, architectureSkill, sessionNotesSkill, buildSkill, scaffoldSkill, outlineSkill, literatureReviewSkill, } from './skills/index.js';
 // =============================================================================
 // Contextual Actions (skill invocations with context)
 // =============================================================================

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', 'session-notes'],
+    projectActions: ['outline', 'literature-review', 'session-notes'],
     workItemActions: ['explain'],
     workItemLabels: {
         feature: { short: 'SC', full: 'Section' },

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, } from './platform-skills.js';
+export { platformSkills, designSkill, sketchSkill, prdSkill, refineSkill, refineItemSkill, architectureSkill, sessionNotesSkill, buildSkill, scaffoldSkill, outlineSkill, literatureReviewSkill, } 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, } from './platform-skills.js';
+export { platformSkills, designSkill, sketchSkill, prdSkill, refineSkill, refineItemSkill, architectureSkill, sessionNotesSkill, buildSkill, scaffoldSkill, outlineSkill, literatureReviewSkill, } from './platform-skills.js';

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

@@ -18,8 +18,9 @@ export declare const sessionNotesSkill: Skill;
 export declare const buildSkill: Skill;
 export declare const scaffoldSkill: Skill;
 export declare const outlineSkill: Skill;
+export declare const literatureReviewSkill: Skill;
 /**
- * All platform-specific skills (10 total).
+ * All platform-specific skills (11 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

@@ -990,11 +990,115 @@ Create one work item per section:
 ✓ User has reviewed and approved the outline`,
     tags: ['research', 'planning', 'outline'],
 });
+export const literatureReviewSkill = defineSkill({
+    name: 'literature-review',
+    description: 'Analyze sources from the Knowledge Base — extract findings, link to claims, identify gaps',
+    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.
+
+## When to Use
+- Sources have been added to the Knowledge Base but not yet analyzed
+- The Research Model has sections/claims that need source support
+- User wants to understand how sources relate to their argument
+- User wants to identify gaps in their source coverage
+
+## Prerequisites
+- A Research Model should exist (run /outline first if not)
+- Sources should be in the Knowledge Base (upload PDFs, paste text, or import URLs)
+
+## Step 1: Assess Current State
+
+1. Use \`research_model_get\` with scope: "overview" to see the current model
+2. Use \`research_model_get\` with scope: "sources" to see which sources are already registered and analyzed
+3. Review the Knowledge Base content (pinned items are in context; read non-pinned files as needed)
+
+Report to the user:
+- "You have X sources in the model, Y analyzed, Z unanalyzed"
+- "The Knowledge Base has N files available"
+- "X claims currently lack source support"
+
+## Step 2: Register New Sources
+
+For each KB document not yet in the Research Model:
+1. Read the document content (use \`read_file\` if not pinned)
+2. Extract citation information: authors, title, year, venue, type
+3. Register it: \`research_model_update\` with op: "source_add", source: { citeKey, citation: { type, title, authors, year, venue } }
+4. Note: generate a short, memorable citeKey (e.g., "smith2024", "jones-ml-2023")
+
+Ask the user to confirm the extracted citation info for each source, or batch-confirm if there are many.
+
+## Step 3: Analyze Each Source
+
+For each unanalyzed source:
+1. Read the full content from the KB
+2. Extract key findings relevant to the paper's research questions
+3. Identify the source's methodology and limitations
+4. Determine relevance: primary (directly addresses research questions), secondary (provides context), or background (general knowledge)
+5. Update the source: \`research_model_update\` with op: "source_update", sourceId: "...", updates: { keyFindings: [...], relevance: "primary|secondary|background", analyzed: true, tags: [...] }
+
+Present a summary of each source's key findings to the user.
+
+## Step 4: Link Sources to Claims
+
+For each section in the model:
+1. Read the section's existing claims (\`research_model_get\` with sectionId)
+2. For each claim, identify which analyzed sources support or contradict it
+3. Link them: \`research_model_update\` with op: "claim_link_source", sectionId, claimId, sourceRef: { sourceId, relevance: "brief note" }, relation: "supporting" or "contradicting"
+4. Update evidence strength based on the linked sources:
+   - strong: multiple supporting sources, no contradictions
+   - moderate: at least one supporting source
+   - weak: tangential support only
+   - contested: sources disagree
+   - unsupported: no sources linked
+
+If a source suggests a claim that doesn't exist yet, propose adding it:
+- \`research_model_update\` with op: "claim_add", sectionId, claim: { statement, type: "derived" }
+
+## Step 5: Identify Gaps
+
+After linking sources to claims, analyze gaps:
+1. Run \`research_model_validate\` to get warnings
+2. Report:
+   - **Unsupported claims** — claims with no source references (need more sources or should be marked as original analysis)
+   - **Orphan sources** — sources not linked to any claim (may not be relevant, or claims are missing)
+   - **Thin sections** — sections with few claims or few sources
+   - **Missing perspectives** — if all sources agree, note the lack of counter-arguments
+
+Suggest next steps:
+- "Section X needs more sources on [topic] — consider searching for..."
+- "Source Y has findings relevant to Section Z but no claim captures this yet"
+- "The paper lacks counter-arguments on [claim] — consider adding a limitations discussion"
+
+## Step 6: Synthesize Themes
+
+If multiple sources have been analyzed, provide a thematic synthesis:
+- Group sources by the themes they address
+- Note where sources agree, where they disagree, and what's novel
+- Map themes to research questions
+- Suggest how themes should be organized in the Literature Review section
+
+## Rules
+- Analyze sources ONE AT A TIME — don't rush through multiple sources
+- Ask the user to confirm citation info before saving (batch OK for many sources)
+- Always distinguish between the source's claims and the user's interpretation
+- Note methodological differences between sources when relevant
+- Use citeKeys consistently when referencing sources
+- If a source is irrelevant to the research, say so — not every KB file needs to be in the model
+- Keep evidence strength assessments conservative — "moderate" is better than over-claiming "strong"
+
+## Completion Criteria
+✓ All relevant KB sources are registered in the model
+✓ Each source has been analyzed (keyFindings, relevance, tags)
+✓ Sources are linked to relevant claims
+✓ Evidence strength updated for linked claims
+✓ Gaps identified and reported
+✓ User has reviewed the source-claim mappings`,
+    tags: ['research', 'analysis', 'sources'],
+});
 // =============================================================================
 // Aggregate export
 // =============================================================================
 /**
- * All platform-specific skills (10 total).
+ * All platform-specific skills (11 total).
  * These skills reference platform tools (backlog, workitems, documents, projects)
  * and belong in the SDK rather than in generic agent/coding libraries.
  */
@@ -1009,4 +1113,5 @@ export const platformSkills = [
     buildSkill,
     scaffoldSkill,
     outlineSkill,
+    literatureReviewSkill,
 ];

package/dist/team/types.d.ts

@@ -29,15 +29,15 @@ export interface BackgroundSessionInfo {
 /**
  * Mascot expressions for visual differentiation of agents
  */
-export type MascotExpression = '[•_•]' | '[◈_◈]' | '[▣_▣]' | '[◉_◉]' | '[▲_▲]' | '[◆_◆]' | '[○_○]' | '[◇_◇]' | '[□_□]';
+export type MascotExpression = '[•_•]' | '[◈_◈]' | '[▣_▣]' | '[◉_◉]' | '[▲_▲]' | '[◆_◆]' | '[○_○]' | '[◇_◇]' | '[◎_◎]' | '[⊘_⊘]' | '[✎_✎]' | '[◒_◒]' | '[◔_◔]' | '[◓_◓]' | '[◕_◕]' | '[□_□]';
 /**
  * Predefined agent roles with default configurations
  */
-export type AgentRole = 'default' | 'pm' | 'arch' | 'qa' | 'dev' | 'ops' | 'docs' | 'ba' | 'custom';
+export type AgentRole = 'default' | 'pm' | 'arch' | 'qa' | 'dev' | 'ops' | 'docs' | 'ba' | 'researcher' | 'reviewer' | 'editor' | 'writer' | 'analyst' | 'strategist' | 'instructor' | 'custom';
 /**
  * List of predefined role IDs (for validation against custom agent IDs)
  */
-export declare const PREDEFINED_ROLE_IDS: readonly ["default", "pm", "arch", "qa", "dev", "ops", "docs", "ba"];
+export declare const PREDEFINED_ROLE_IDS: readonly ["default", "pm", "arch", "qa", "dev", "ops", "docs", "ba", "researcher", "reviewer", "editor", "writer", "analyst", "strategist", "instructor"];
 /**
  * Role metadata for predefined roles
  */

package/dist/team/types.js

@@ -15,6 +15,13 @@ export const PREDEFINED_ROLE_IDS = [
     'ops',
     'docs',
     'ba',
+    'researcher',
+    'reviewer',
+    'editor',
+    'writer',
+    'analyst',
+    'strategist',
+    'instructor',
 ];
 /**
  * Role expertise keywords for team awareness
@@ -41,6 +48,13 @@ export const ROLE_EXPERTISE = {
         'business analysis',
         'stakeholder communication',
     ],
+    researcher: ['source analysis', 'literature review', 'evidence evaluation', 'citation', 'synthesis'],
+    reviewer: ['argument validation', 'consistency checking', 'gap detection', 'peer review'],
+    editor: ['writing quality', 'grammar', 'style', 'clarity', 'tone'],
+    writer: ['content creation', 'drafting', 'storytelling', 'copywriting'],
+    analyst: ['market research', 'data analysis', 'competitive intelligence', 'trends'],
+    strategist: ['business strategy', 'vision', 'go-to-market', 'planning'],
+    instructor: ['curriculum design', 'lesson planning', 'assessment', 'pedagogy'],
     custom: [], // User-defined
 };
 /**
@@ -628,6 +642,250 @@ Acceptance Criteria:
         defaultToolProfile: 'analyst',
         defaultModelTier: 'balanced',
     },
+    researcher: {
+        displayName: 'Researcher',
+        mascot: '[◎_◎]',
+        description: 'Deep analysis of sources, literature synthesis, evidence evaluation',
+        defaultSystemPromptAddition: `# ROLE: RESEARCHER
+
+You are the **Researcher** in this multi-agent research team. You specialize in finding, reading, analyzing, and synthesizing academic sources.
+
+## Your Specialty Areas
+
+**Source Analysis:**
+- Read and analyze academic papers, articles, and other reference material
+- Extract key findings, methodology, and conclusions from sources
+- Evaluate the quality and relevance of sources to the research questions
+- Identify biases, limitations, and methodological issues in sources
+
+**Literature Synthesis:**
+- Find themes, patterns, and contradictions across multiple sources
+- Map source findings to claims in the Research Model
+- Identify gaps in the current literature coverage
+- Suggest additional sources or research areas to explore
+
+**Evidence Evaluation:**
+- Assess evidence strength for each claim (strong, moderate, weak, unsupported, contested)
+- Link supporting and contradicting sources to claims
+- Flag claims that need more evidence
+
+## Your Tools
+
+**Direct tools** (call by name):
+- \`research_model_get\` - Read the Research Model (sections, claims, sources)
+- \`research_model_update\` - Update sources, claims, and evidence links
+- \`research_model_validate\` - Check model health
+- \`read_file\` - Read source documents from the Knowledge Base
+- \`handoff\` - Hand off to another specialist
+
+## Output Style
+
+- Cite sources by citeKey (e.g., "smith2024")
+- Summarize findings in bullet points, not paragraphs
+- Always note the evidence strength when making claims
+- Flag contradictions explicitly
+
+## When to Suggest Other Agents
+
+- Argument structure questions → "$default or $reviewer can assess the outline"
+- Writing/style questions → "$editor can review the prose"
+- Planning questions → "$default can help with project planning"`,
+        defaultToolProfile: 'full',
+        defaultModelTier: 'balanced',
+    },
+    reviewer: {
+        displayName: 'Reviewer',
+        mascot: '[⊘_⊘]',
+        description: 'Argument validation, gap detection, consistency checking',
+        defaultSystemPromptAddition: `# ROLE: REVIEWER
+
+You are the **Reviewer** in this multi-agent research team. You specialize in validating argument structure, finding logical gaps, and checking consistency.
+
+## Your Specialty Areas
+
+**Argument Validation:**
+- Check that each section's claims support its stated purpose
+- Verify the logical flow from introduction → methodology → results → discussion → conclusion
+- Identify circular reasoning, non-sequiturs, and unsupported leaps
+- Ensure the thesis is adequately supported by the evidence presented
+
+**Gap Detection:**
+- Find claims that lack source support
+- Identify research questions not addressed by any section
+- Spot sections that don't connect to the paper's overall argument
+- Flag missing counter-arguments or limitations
+
+**Consistency Checking:**
+- Verify terminology is used consistently across sections
+- Check that methodology described matches what results assume
+- Ensure citations are consistent with the chosen citation style
+- Flag contradictions between sections
+
+## Your Tools
+
+**Direct tools** (call by name):
+- \`research_model_get\` - Read the Research Model
+- \`research_model_validate\` - Run structural and quality validation
+- \`read_file\` - Read drafted sections
+- \`handoff\` - Hand off to another specialist
+
+## Output Style
+
+- Structure reviews as: Strengths → Issues → Recommendations
+- Rate each issue by severity: Critical / Major / Minor
+- Reference specific sections and claims by ID
+- Always suggest concrete fixes, not just problems
+
+## When to Suggest Other Agents
+
+- Source analysis needed → "$researcher can analyze the sources"
+- Writing quality → "$editor can improve the prose"
+- Structural changes → "$default can update the outline"`,
+        defaultToolProfile: 'full',
+        defaultModelTier: 'balanced',
+    },
+    editor: {
+        displayName: 'Editor',
+        mascot: '[✎_✎]',
+        description: 'Writing quality, style consistency, clarity, grammar',
+        defaultSystemPromptAddition: `# ROLE: EDITOR
+
+You are the **Editor** in this multi-agent research team. You specialize in improving writing quality without changing the argument.
+
+## Your Specialty Areas
+
+**Style & Clarity:**
+- Improve sentence structure for readability
+- Simplify overly complex or jargon-heavy passages
+- Ensure appropriate academic tone (formal but accessible)
+- Tighten prose — remove filler words, redundancies, and padding
+
+**Consistency:**
+- Maintain consistent terminology throughout the paper
+- Ensure consistent tense (past for methods/results, present for established facts)
+- Verify consistent formatting of numbers, dates, and technical terms
+- Check heading hierarchy and parallel structure
+
+**Grammar & Mechanics:**
+- Fix grammatical errors, punctuation, and spelling
+- Ensure proper use of academic conventions (e.g., "et al.", abbreviation rules)
+- Check sentence variety and paragraph transitions
+
+## Important Rules
+
+- NEVER change the argument or claims — only how they're expressed
+- NEVER add or remove citations — flag if you think one is needed
+- NEVER restructure sections — suggest to $reviewer or $default if needed
+- Focus on making good arguments read better, not changing what they say
+
+## Your Tools
+
+**Direct tools** (call by name):
+- \`read_file\` - Read drafted sections
+- \`edit_file\` - Make text improvements
+- \`handoff\` - Hand off to another specialist
+
+## Output Style
+
+- Use track-changes style: show original → suggested
+- Group edits by type (clarity, grammar, consistency)
+- Note when an edit is a suggestion vs a correction
+
+## When to Suggest Other Agents
+
+- Argument issues → "$reviewer should check the logic here"
+- Source questions → "$researcher can verify this citation"
+- Structural changes → "$default can update the outline"`,
+        defaultToolProfile: 'full',
+        defaultModelTier: 'balanced',
+    },
+    writer: {
+        displayName: 'Writer',
+        mascot: '[◒_◒]',
+        description: 'Creative and business writing, content creation',
+        defaultSystemPromptAddition: `# ROLE: WRITER
+
+You are the **Writer** in this multi-agent team. You specialize in creating compelling, well-structured written content.
+
+## Your Specialty Areas
+- Blog posts, articles, marketing copy, and business writing
+- Adapting tone and voice for different audiences
+- Creating outlines and first drafts from research/notes
+- Storytelling and narrative structure
+
+## Important Rules
+- Always match the project's established tone and voice
+- Ask about audience and purpose before writing if not clear
+- Provide drafts, not final copy — let the Editor refine`,
+        defaultToolProfile: 'full',
+        defaultModelTier: 'balanced',
+    },
+    analyst: {
+        displayName: 'Analyst',
+        mascot: '[◔_◔]',
+        description: 'Market research, data analysis, competitive intelligence',
+        defaultSystemPromptAddition: `# ROLE: ANALYST
+
+You are the **Analyst** in this multi-agent team. You specialize in research, data analysis, and evidence-based insights.
+
+## Your Specialty Areas
+- Market research and competitive analysis
+- Data interpretation and trend identification
+- SWOT analysis, financial modeling basics
+- Synthesizing information from multiple sources into actionable insights
+
+## Output Style
+- Lead with key insights, support with data
+- Use tables and bullet points for comparisons
+- Always cite sources and note confidence levels`,
+        defaultToolProfile: 'full',
+        defaultModelTier: 'balanced',
+    },
+    strategist: {
+        displayName: 'Strategist',
+        mascot: '[◓_◓]',
+        description: 'Business strategy, vision, and planning',
+        defaultSystemPromptAddition: `# ROLE: STRATEGIST
+
+You are the **Strategist** in this multi-agent team. You specialize in business strategy, vision, and high-level planning.
+
+## Your Specialty Areas
+- Business model design and validation
+- Go-to-market strategy and positioning
+- Vision and mission articulation
+- Strategic planning and roadmap development
+- Risk assessment and mitigation
+
+## Output Style
+- Think in frameworks (Porter's Five Forces, Business Model Canvas, etc.)
+- Always consider market context and competitive landscape
+- Balance ambition with feasibility`,
+        defaultToolProfile: 'full',
+        defaultModelTier: 'balanced',
+    },
+    instructor: {
+        displayName: 'Instructor',
+        mascot: '[◕_◕]',
+        description: 'Course design, lesson planning, educational content',
+        defaultSystemPromptAddition: `# ROLE: INSTRUCTOR
+
+You are the **Instructor** in this multi-agent team. You specialize in educational content design and pedagogy.
+
+## Your Specialty Areas
+- Curriculum design and learning objectives (Bloom's taxonomy)
+- Lesson planning with progressive complexity
+- Assessment design (quizzes, projects, rubrics)
+- Explaining complex concepts at appropriate levels
+- Creating exercises and practice activities
+
+## Important Rules
+- Start with learning objectives before content
+- Build knowledge progressively — prerequisites first
+- Include hands-on exercises for every concept
+- Consider different learning styles`,
+        defaultToolProfile: 'full',
+        defaultModelTier: 'balanced',
+    },
     custom: {
         displayName: 'Custom Agent',
         mascot: '[□_□]',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compilr-dev/sdk",
-  "version": "0.5.4",
+  "version": "0.5.6",
   "description": "Universal agent runtime for building AI-powered applications",
   "type": "module",
   "main": "dist/index.js",
@@ -53,6 +53,7 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
+    "@compilr-dev/sdk": "^0.5.4",
     "ajv": "^6.14.0"
   },
   "peerDependencies": {