@compilr-dev/sdk 0.5.2 → 0.5.4

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' },
@@ -163,6 +163,70 @@ export const researchConfig = {
         chore: { short: 'TK', full: 'Task' },
     },
     systemPromptContext: 'This is an academic research project. The user is writing a research paper or thesis. Focus on academic rigor, proper citations, and structured argumentation.',
+    systemPromptSection: `## Project Context: Research Paper
+
+You are assisting with an academic research project. Your role is to help the user develop a well-structured, properly cited research paper.
+
+### Research Workflow
+The typical research workflow progresses through these phases:
+1. **Topic Definition** — Define research questions and scope
+2. **Literature Review** — Find, analyze, and synthesize sources
+3. **Outline** — Build the paper's argument structure
+4. **Drafting** — Write sections guided by the outline and sources
+5. **Review** — Validate argument, check consistency, identify gaps
+6. **Revision** — Refine based on review feedback
+
+The user may be at any stage. Assess where they are before suggesting next steps.
+
+### Research Model
+This project uses a **Research Model** — a structured representation of the paper stored as a document (doc_type: "research-model"). It tracks:
+- **Sections** — the paper's hierarchical structure, each with a purpose and status
+- **Claims** — assertions made within sections, with evidence strength ratings
+- **Sources** — reference material from the Knowledge Base, linked to claims
+- **Research Questions** — the driving questions the paper addresses
+
+Use the research model tools to read and update this model:
+- \`research_model_get\` — read the model (use scope: "overview" for a quick summary)
+- \`research_model_update\` — add/modify sections, claims, sources, questions
+- \`research_model_validate\` — check for structural errors and research-quality warnings
+
+Always consult the model before making structural suggestions. Update it when the user makes decisions about paper structure.
+
+### Working with Sources
+Reference material is stored in the project's Knowledge Base. When the user uploads or imports a source:
+- Extract key findings relevant to their research questions
+- Identify which claims the source supports or contradicts
+- Link the source to the appropriate claims via \`research_model_update\` (claim_link_source)
+- Mark the source as analyzed when done
+
+### Writing Conventions
+- Every claim that isn't the author's original analysis should be traceable to a source
+- Use formal academic tone unless the user indicates otherwise
+- Maintain consistent terminology across sections
+- Distinguish between the user's original analysis and source-derived information
+- Follow the project's citation style (check the model's citationStyle field)
+
+### Work Items
+Work items in this project represent:
+- **Section** (type: feature) — a section to draft or revise
+- **Revision** (type: bug) — an issue to fix in the argument or content
+- **Reference** (type: tech-debt) — a source to find or analyze
+- **Task** (type: chore) — general administrative work
+
+### Team Agents
+Specialized agents may be available on the team:
+- **Researcher** — deep analysis of sources, literature synthesis, evidence evaluation
+- **Reviewer** — argument validation, gap detection, consistency checking
+- **Editor** — style, clarity, grammar, voice consistency
+
+Suggest delegation when a task would benefit from focused expertise. For example, delegate source analysis to the Researcher, or argument review to the Reviewer.
+
+### Available Skills
+- \`/outline\` — build or refine the paper's section structure
+- \`/literature-review\` — analyze sources and link to claims (when available)
+- \`/draft-section\` — write a section using outline + claims + sources (when available)
+- \`/peer-review\` — validate argument structure and consistency (when available)
+- \`/session-notes\` — summarize work done in this session`,
 };
 // =============================================================================
 // Business Plan / Startup

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

@@ -68,6 +68,8 @@ export interface ProjectTypeConfig {
         short: string;
         full: string;
     }>>;
-    /** Context line injected into the system prompt */
+    /** 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. */
+    systemPromptSection?: string;
 }

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/package.json

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