@compilr-dev/sdk 0.5.3 → 0.5.5

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, } from './skills/index.js';
+export { platformSkills, designSkill, sketchSkill, prdSkill, refineSkill, refineItemSkill, architectureSkill, sessionNotesSkill, buildSkill, scaffoldSkill, outlineSkill, } 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, } from './skills/index.js';
+export { platformSkills, designSkill, sketchSkill, prdSkill, refineSkill, refineItemSkill, architectureSkill, sessionNotesSkill, buildSkill, scaffoldSkill, outlineSkill, } 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: ['session-notes'],
+    projectActions: ['outline', '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, } from './platform-skills.js';
+export { platformSkills, designSkill, sketchSkill, prdSkill, refineSkill, refineItemSkill, architectureSkill, sessionNotesSkill, buildSkill, scaffoldSkill, outlineSkill, } 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, } from './platform-skills.js';
+export { platformSkills, designSkill, sketchSkill, prdSkill, refineSkill, refineItemSkill, architectureSkill, sessionNotesSkill, buildSkill, scaffoldSkill, outlineSkill, } from './platform-skills.js';

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

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

@@ -844,10 +844,157 @@ Create both frontend and backend structures:
     version: '1.0.0',
 });
 // =============================================================================
+// Research Skills
+// =============================================================================
+export const outlineSkill = defineSkill({
+    name: 'outline',
+    description: 'Build or refine the research paper structure — sections, claims, source mapping',
+    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.
+
+## When to Use
+- Starting a new research paper — no outline exists yet
+- Restructuring an existing paper — user wants to reorganize sections
+- Evolving a paper — new sources or insights change the direction
+- Importing structure — user has an existing paper and wants to model it
+
+## Step 1: Assess Current State
+
+Start by reading the current state:
+1. Use \`research_model_get\` with scope: "overview" to check if a model exists
+2. If it exists, review sections, questions, and sources already defined
+3. Check the Knowledge Base (read pinned content) for available sources
+4. Check existing work items with \`workitem_query\`
+
+Tell the user what you found:
+- "You have X sections, Y sources, Z research questions defined" (if model exists)
+- "No research model found yet — let's build one from scratch" (if new)
+
+## Step 2: Gather Context (only ask what you don't already know)
+
+Ask in batches of 2-3 questions:
+- **Research topic:** What is the main topic or research question?
+- **Scope:** What type of paper? (journal article, thesis chapter, full thesis, literature review, lab report)
+- **Citation style:** APA, MLA, Chicago, IEEE, Harvard?
+- **Audience:** Who is this for? (academic journal, conference, class assignment)
+- **Constraints:** Any required sections or structure mandated by the target venue?
+
+If the model already has a title and citation style set, skip those questions.
+
+After gathering answers, save the metadata:
+- \`research_model_update\` with op: "set_title"
+- \`research_model_update\` with op: "set_citation_style"
+- \`research_model_update\` with op: "set_authors" (if provided)
+- \`research_model_update\` with op: "set_keywords" (if provided)
+
+## Step 3: Propose Research Questions
+
+Based on the topic and available sources, propose:
+- One main research question
+- 2-4 sub-questions the paper will address
+
+Present them to the user for review. After confirmation, save each:
+- \`research_model_update\` with op: "question_add", question: { question: "..." }
+
+## Step 4: Propose Section Structure
+
+Based on the questions, scope, and sources, propose an outline. Adapt to the paper type:
+
+**Journal article (5-7 sections):**
+1. Introduction — state the problem, thesis, and contribution
+2. Literature Review / Related Work — what's known, what's the gap
+3. Methodology — research approach
+4. Results / Findings — present the evidence
+5. Discussion — interpret results, implications, limitations
+6. Conclusion — summarize contributions, future work
+
+**Thesis (chapters with subsections):**
+- Chapters as top-level sections, subsections as children
+- Include: Abstract, Acknowledgments if appropriate
+
+**Literature review (thematic):**
+- Organized by themes, not methodology/results
+- Each theme is a section with sub-themes as subsections
+
+**Lab report:**
+- Hypothesis, Method, Results, Discussion, Conclusion
+
+Present the outline to the user. For each section include:
+- Title
+- Purpose (what this section argues or establishes — not just "discusses X" but "argues that X because Y")
+- Estimated word count (if appropriate for the scope)
+
+After user confirms/adjusts, save each section:
+- \`research_model_update\` with op: "section_add", section: { title, purpose, order, parentId, targetWordCount }
+
+For subsections, use parentId referencing the parent section's ID.
+
+## Step 5: Map Sources to Sections (if sources exist in KB)
+
+If the Knowledge Base has sources:
+1. Review available source descriptions/pinned content
+2. For each section, suggest which sources might be relevant
+3. Create initial claim sketches for key arguments
+4. Link sources to claims
+
+For each claim:
+- \`research_model_update\` with op: "claim_add", sectionId: "...", claim: { statement: "..." }
+
+For each source link (only if source is already in the model):
+- \`research_model_update\` with op: "claim_link_source", sectionId: "...", claimId: "...", sourceRef: { sourceId: "..." }, relation: "supporting"
+
+If no sources exist yet, skip this step and note: "Add sources to the Knowledge Base and run /literature-review to link them."
+
+## Step 6: Generate Work Items
+
+Create one work item per section:
+- Use \`workitem_create\` for each section
+- Type: "feature" (displayed as "Section" in research projects)
+- Title: "Draft: {section title}"
+- Description: Include section purpose, key claims to address, relevant sources
+- Priority based on writing order:
+  - Methodology → high (write first, grounds the paper)
+  - Literature Review → high (needed early)
+  - Results / Findings → medium
+  - Discussion → medium
+  - Introduction → low (easier to write once you know what you're introducing)
+  - Conclusion → low (summary of everything else)
+
+## Step 7: Validate and Summarize
+
+1. Run \`research_model_validate\` to check for issues
+2. Present a summary:
+   - Paper title and scope
+   - Research questions
+   - Section outline with purposes
+   - Source mapping (if any)
+   - Work items created
+   - Any warnings from validation (unsupported claims, empty sections — expected at this stage)
+
+## Rules
+- This is INTERACTIVE. Ask questions, propose, get feedback, iterate. Do NOT generate the entire outline in one shot.
+- Respect existing model state. If sections already exist, propose modifications rather than replacing everything.
+- Each section's purpose should clearly state what it argues or establishes.
+- Claims are hypotheses at this stage — mark them as unsupported until sources are linked.
+- Use the ask_user tool to present options when choices are needed.
+- If the user says "skip" or "later", move to the next step.
+- Total interaction should be 8-15 questions max.
+
+## Completion Criteria
+✓ Paper title and citation style are set
+✓ Research questions are defined
+✓ Section structure matches the paper scope
+✓ Each section has a clear purpose
+✓ Sources mapped to sections (if available)
+✓ Work items created for each section
+✓ Model validates without structural errors
+✓ User has reviewed and approved the outline`,
+    tags: ['research', 'planning', 'outline'],
+});
+// =============================================================================
 // Aggregate export
 // =============================================================================
 /**
- * All platform-specific skills (9 total).
+ * All platform-specific skills (10 total).
  * These skills reference platform tools (backlog, workitems, documents, projects)
  * and belong in the SDK rather than in generic agent/coding libraries.
  */
@@ -861,4 +1008,5 @@ export const platformSkills = [
     sessionNotesSkill,
     buildSkill,
     scaffoldSkill,
+    outlineSkill,
 ];

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.3",
+  "version": "0.5.5",
   "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": {