@compilr-dev/sdk 0.7.7 → 0.7.9

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

@@ -0,0 +1,10 @@
+/**
+ * Research Paper Skills
+ *
+ * outline, literature-review, draft-section, peer-review, research-scaffold
+ */
+export declare const outlineSkill: import("@compilr-dev/agents").Skill;
+export declare const literatureReviewSkill: import("@compilr-dev/agents").Skill;
+export declare const draftSectionSkill: import("@compilr-dev/agents").Skill;
+export declare const peerReviewSkill: import("@compilr-dev/agents").Skill;
+export declare const researchScaffoldSkill: import("@compilr-dev/agents").Skill;

package/dist/skills/research-skills.js

@@ -0,0 +1,569 @@
+/**
+ * Research Paper Skills
+ *
+ * outline, literature-review, draft-section, peer-review, research-scaffold
+ */
+import { defineSkill } from '@compilr-dev/agents';
+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'],
+});
+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'],
+});
+export const draftSectionSkill = defineSkill({
+    name: 'draft-section',
+    description: 'Draft a paper section using the outline, claims, and linked sources',
+    prompt: `You are in DRAFT SECTION MODE. Your goal is to write or revise a section of the research paper, guided by the Research Model's outline, claims, and linked sources.
+
+## When to Use
+- A section has status "outlined" and needs its first draft
+- A section needs revision based on reviewer feedback
+- The user wants to expand a section with more detail
+
+## Step 1: Select the Section
+
+1. Use \`research_model_get\` with scope: "sections" to see all sections and their status
+2. If the user didn't specify which section, suggest the next logical one:
+   - Methodology first (grounds the paper)
+   - Literature Review (needed early)
+   - Results / Findings (core content)
+   - Discussion (interpretation)
+   - Introduction and Conclusion last (summaries)
+3. Confirm the section choice with the user
+
+## Step 2: Gather Section Context
+
+For the chosen section:
+1. Use \`research_model_get\` with sectionId to get the section's purpose, claims, and notes
+2. Read any existing draft file (if the section has been drafted before)
+3. For each claim with linked sources, read the source content from KB to understand the evidence
+4. Check the citation style from the model: \`research_model_get\` with scope: "overview"
+
+Summarize to the user:
+- "Section: {title}"
+- "Purpose: {purpose}"
+- "Claims to address: {list}"
+- "Sources available: {list with citeKeys}"
+
+## Step 3: Draft the Section
+
+Write the section following these guidelines:
+
+**Structure:**
+- Start with a topic sentence that states the section's purpose
+- Address each claim in the section in a logical order
+- Use transitions between paragraphs
+- End with a connection to the next section (or summary for final sections)
+
+**Citations:**
+- Use the project's citation style for in-text citations
+- APA: (Author, Year) or Author (Year)
+- MLA: (Author Page) or Author (Page)
+- IEEE: [citeKey] or [N]
+- Chicago: (Author Year) or Author (Year)
+- Harvard: (Author Year) or Author (Year)
+- Cite sources for every non-original claim
+- When multiple sources support a claim, cite them together
+
+**Academic Tone:**
+- Formal but clear — avoid jargon without definition
+- Use hedging language where appropriate ("suggests", "indicates", "appears to")
+- Distinguish between established facts and interpretations
+- Use active voice for the author's contributions, passive for general findings
+
+**Length:**
+- Respect the section's targetWordCount if set
+- If not set, aim for appropriate length based on scope:
+  - Journal article section: 500-1500 words
+  - Thesis chapter: 2000-5000 words
+  - Literature review section: 800-2000 words
+
+## Step 4: Write the File
+
+1. Determine the file path: \`{project_path}/sections/{section_order}-{section_slug}.md\`
+   - e.g., \`sections/01-introduction.md\`, \`sections/03-methodology.md\`
+2. Write the draft using \`write_file\` or \`edit_file\` (if revising)
+3. Include a header comment: \`<!-- Section: {title} | Status: drafted | Rev: {model revision} -->\`
+
+## Step 5: Update the Model
+
+After writing:
+1. Update section status: \`research_model_update\` with op: "section_update", sectionId, updates: { status: "drafted", actualWordCount: N }
+2. If new claims emerged during writing, add them: \`research_model_update\` with op: "claim_add"
+3. If evidence strength changed based on closer reading, update claims
+
+## Step 6: Generate Bibliography (if needed)
+
+If this is the first section being drafted or the user requests it:
+1. Use \`bibliography_generate\` with format: "markdown" to produce the references list
+2. Write it to \`{project_path}/sections/references.md\`
+
+## Step 7: Summary
+
+Report to the user:
+- Section drafted: title, word count, file path
+- Claims addressed: list with evidence strength
+- Citations used: list of citeKeys
+- Suggestions: any gaps noticed, claims that need more support
+
+## Rules
+- NEVER fabricate citations — only cite sources that exist in the Research Model
+- If a claim lacks source support, note it explicitly rather than inventing a reference
+- Maintain consistency with previously drafted sections (terminology, tense, voice)
+- If the section has subsections in the model, draft them as ## subheadings
+- Read existing drafted sections first to maintain consistent style
+- Ask the user about tone preferences if this is the first section being drafted
+
+## Completion Criteria
+✓ Section file written with proper citations
+✓ Model updated (status: drafted, actualWordCount)
+✓ All claims in the section are addressed in the text
+✓ In-text citations match the project's citation style
+✓ User has reviewed the draft`,
+    tags: ['research', 'writing', 'drafting'],
+});
+export const peerReviewSkill = defineSkill({
+    name: 'peer-review',
+    description: 'Validate argument structure, find logical gaps, check consistency across sections',
+    prompt: `You are in PEER REVIEW MODE. Your goal is to critically evaluate the research paper's argument structure, identify gaps, and check consistency — like an academic peer reviewer.
+
+## When to Use
+- One or more sections have been drafted
+- The user wants feedback before submitting/finalizing
+- After significant revisions to check nothing was broken
+- To identify areas that need more work
+
+## Step 1: Assess What's Available
+
+1. Use \`research_model_get\` with scope: "overview" for the big picture
+2. Use \`research_model_get\` with scope: "sections" to see status of each section
+3. Run \`research_model_validate\` for structural issues and warnings
+
+Report to the user:
+- "X sections drafted, Y still outlined, Z sources linked"
+- Any structural errors from validation
+- Which sections are ready for review
+
+If no sections are drafted yet, tell the user: "There's nothing to review yet — run /draft-section first."
+
+## Step 2: Argument Structure Review
+
+Read each drafted section (use \`read_file\` on the section files) and evaluate:
+
+**Thesis & Research Questions:**
+- Is the main thesis clearly stated in the Introduction?
+- Does each section contribute to answering the research questions?
+- Are the research questions actually addressed by the paper's content?
+
+**Logical Flow:**
+- Does the argument progress logically from Introduction → Literature Review → Methodology → Results → Discussion → Conclusion?
+- Does each section build on what came before?
+- Are there logical jumps or non-sequiturs between sections?
+
+**Claim Validation:**
+For each claim in the Research Model:
+- Is it actually stated in the draft text?
+- Is it supported by the cited sources?
+- Is the evidence strength rating accurate given the sources?
+- Are there unsupported assertions presented as established facts?
+
+Rate each issue found:
+- **Critical** — breaks the argument (e.g., unsupported central claim, circular reasoning)
+- **Major** — weakens the argument significantly (e.g., missing counter-arguments, logical gap)
+- **Minor** — should be fixed but doesn't break the argument (e.g., vague language, minor inconsistency)
+
+## Step 3: Gap Detection
+
+Check for missing elements:
+
+**Source Gaps:**
+- Claims that should have citations but don't
+- Sections that rely on very few sources
+- Important counter-arguments not addressed
+- Methodology claims without justification
+
+**Structural Gaps:**
+- Research questions not addressed by any section
+- Sections that don't connect to the overall argument
+- Missing limitations discussion
+- Missing future work section (if appropriate)
+
+**Content Gaps:**
+- Definitions used but never introduced
+- Acronyms used without expansion
+- Figures/tables referenced but not present
+- Promises made in the Introduction but not delivered
+
+## Step 4: Consistency Check
+
+Across all drafted sections, check:
+
+**Terminology:**
+- Is the same concept referred to consistently? (e.g., not "users" in one place and "participants" in another without reason)
+- Are technical terms used with consistent meaning?
+
+**Tense:**
+- Literature review: past tense for completed studies
+- Methodology: past tense for what was done, present for general statements
+- Results: past tense for findings
+- Discussion: present tense for interpretations
+
+**Voice & Tone:**
+- Is the level of formality consistent?
+- Is the author's voice consistent (not shifting between confident and hedging without reason)?
+
+**Numbers & Data:**
+- Do statistics match between text and any tables/figures?
+- Are numbers formatted consistently?
+
+## Step 5: Cross-Reference Check
+
+- "As discussed in Section X" — does Section X actually discuss that?
+- "See Table N" / "See Figure N" — do they exist?
+- Citations in text match sources in the Research Model
+- Consistent use of citation style throughout
+
+## Step 6: Generate Review Report
+
+Structure the report as:
+
+### Strengths
+- What the paper does well (2-3 points)
+
+### Critical Issues
+- Issues that must be addressed (with specific locations)
+
+### Major Issues
+- Significant improvements needed
+
+### Minor Issues
+- Small fixes and suggestions
+
+### Recommendations
+- Prioritized list of what to fix first
+- Suggested order of revisions
+
+Write the report to \`{project_path}/reviews/peer-review-{date}.md\`
+
+## Step 7: Update Model
+
+For issues that affect the Research Model:
+1. Update claim evidence strength if ratings were inaccurate
+2. Add new claims if the review identified missing arguments
+3. Create work items (type: "bug" / displayed as "Revision") for each critical and major issue:
+   - \`workitem_create\` with type: "bug", title: "Review: {brief issue}", description: detailed issue + suggested fix
+
+## Rules
+- Be constructive, not destructive — every critique should include a suggestion for improvement
+- Reference specific sections, claims, and sources by ID/citeKey
+- Don't rewrite the paper — point out issues and let the author fix them
+- Distinguish between opinion ("I would suggest...") and errors ("This claim is unsupported")
+- If the argument is sound, say so — don't manufacture problems
+- Focus on the argument, not the writing style (that's the Editor's job)
+
+## Completion Criteria
+✓ All drafted sections reviewed
+✓ Argument structure evaluated (thesis, logical flow, claim support)
+✓ Gaps identified (source, structural, content)
+✓ Consistency checked (terminology, tense, cross-references)
+✓ Review report written to file
+✓ Revision work items created for critical/major issues
+✓ 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'],
+});

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

@@ -0,0 +1,14 @@
+/**
+ * Software Development Skills
+ *
+ * design, sketch, prd, refine, refine-item, architecture, session-notes, build, scaffold
+ */
+export declare const designSkill: import("@compilr-dev/agents").Skill;
+export declare const refineSkill: import("@compilr-dev/agents").Skill;
+export declare const sketchSkill: import("@compilr-dev/agents").Skill;
+export declare const refineItemSkill: import("@compilr-dev/agents").Skill;
+export declare const architectureSkill: import("@compilr-dev/agents").Skill;
+export declare const prdSkill: import("@compilr-dev/agents").Skill;
+export declare const sessionNotesSkill: import("@compilr-dev/agents").Skill;
+export declare const buildSkill: import("@compilr-dev/agents").Skill;
+export declare const scaffoldSkill: import("@compilr-dev/agents").Skill;