studiograph 1.1.2 → 1.2.0-beta.1

package/dist/agent/skill-loader.js

@@ -0,0 +1,166 @@
+/**
+ * Skill Loader — prompt skills for the Studiograph agent.
+ *
+ * Skills are markdown files with YAML frontmatter that inject domain-specific
+ * knowledge into the agent's system prompt. Two formats supported:
+ *
+ *   Directory skill:
+ *     skills/create-deck/
+ *       skill.md        ← required entrypoint
+ *       slide-types.md  ← optional sub-files
+ *
+ *   Single-file skill:
+ *     skills/quick-tip.md
+ *
+ * Frontmatter fields:
+ *   name:        kebab-case identifier (defaults to directory/filename)
+ *   description: shown in skill index so agent knows when to load it
+ *   loading:     "on-demand" (default) | "eager" (inlined in system prompt)
+ */
+import { existsSync, readdirSync, readFileSync } from 'fs';
+import { join, extname, basename } from 'path';
+/**
+ * Minimal YAML frontmatter parser — handles the subset used by skills.
+ */
+function parseFrontmatter(content) {
+    const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+    if (!match) {
+        return { meta: {}, body: content };
+    }
+    const meta = {};
+    for (const line of match[1].split('\n')) {
+        const colon = line.indexOf(':');
+        if (colon === -1)
+            continue;
+        const key = line.slice(0, colon).trim();
+        const value = line.slice(colon + 1).trim();
+        if (key)
+            meta[key] = value;
+    }
+    return { meta, body: match[2] };
+}
+/**
+ * Scan one or more skill directories and return a de-duplicated skill index.
+ * Directories are processed in order — first occurrence of a name wins,
+ * so workspace-level skills override app-bundled skills.
+ */
+export function loadSkillIndex(skillsDirs) {
+    const skills = [];
+    const seen = new Set();
+    for (const dir of skillsDirs) {
+        if (!existsSync(dir))
+            continue;
+        let entries;
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (entry.startsWith('.'))
+                continue;
+            const entryPath = join(dir, entry);
+            // Directory skill: subdirectory containing skill.md
+            const skillMd = join(entryPath, 'skill.md');
+            if (existsSync(skillMd)) {
+                try {
+                    const content = readFileSync(skillMd, 'utf-8');
+                    const { meta } = parseFrontmatter(content);
+                    const name = meta.name || entry;
+                    if (!seen.has(name)) {
+                        seen.add(name);
+                        skills.push({
+                            name,
+                            description: meta.description || '',
+                            loading: meta.loading === 'eager' ? 'eager' : 'on-demand',
+                            dir: entryPath,
+                            entrypoint: skillMd,
+                            isDirectory: true,
+                        });
+                    }
+                }
+                catch {
+                    // skip malformed skill
+                }
+                continue;
+            }
+            // Single-file skill: top-level .md file with valid frontmatter
+            if (extname(entry) === '.md') {
+                try {
+                    const content = readFileSync(entryPath, 'utf-8');
+                    const { meta } = parseFrontmatter(content);
+                    // Must have at least name or description to be a skill
+                    if (!meta.name && !meta.description)
+                        continue;
+                    const name = meta.name || basename(entry, '.md');
+                    if (!seen.has(name)) {
+                        seen.add(name);
+                        skills.push({
+                            name,
+                            description: meta.description || '',
+                            loading: meta.loading === 'eager' ? 'eager' : 'on-demand',
+                            dir,
+                            entrypoint: entryPath,
+                            isDirectory: false,
+                        });
+                    }
+                }
+                catch {
+                    // skip
+                }
+            }
+        }
+    }
+    return skills;
+}
+/**
+ * Load the full content of a skill's entrypoint or a named sub-file.
+ * Sanitises the file parameter to prevent path traversal.
+ */
+export function loadSkillContent(meta, file) {
+    if (file) {
+        if (!meta.isDirectory) {
+            return `Error: skill "${meta.name}" is a single-file skill with no sub-files.`;
+        }
+        // Allow only simple filenames — no slashes, no dots at start
+        const safeName = file.replace(/[^a-zA-Z0-9._-]/g, '');
+        if (!safeName || safeName.startsWith('.')) {
+            return `Error: invalid sub-file name "${file}".`;
+        }
+        const filePath = join(meta.dir, safeName);
+        if (!existsSync(filePath)) {
+            return `Error: sub-file "${safeName}" not found in skill "${meta.name}".`;
+        }
+        return readFileSync(filePath, 'utf-8');
+    }
+    return readFileSync(meta.entrypoint, 'utf-8');
+}
+/**
+ * Build the skill index section to append to the system prompt.
+ * Eager skills are inlined separately; this lists only on-demand skills.
+ */
+export function buildSkillIndexPrompt(skills) {
+    const onDemand = skills.filter(s => s.loading === 'on-demand');
+    if (onDemand.length === 0)
+        return '';
+    const lines = [
+        '## Available Skills',
+        '',
+        'Call `load_skill` to load domain-specific guidance when it is relevant to the current task.',
+        '',
+        ...onDemand.map(s => `- **${s.name}** — ${s.description}`),
+    ];
+    return lines.join('\n');
+}
+/**
+ * Return the full content of all eager skills, to be injected directly
+ * into the system prompt at startup.
+ */
+export function loadEagerSkills(skills) {
+    return skills
+        .filter(s => s.loading === 'eager')
+        .map(s => loadSkillContent(s))
+        .join('\n\n---\n\n');
+}
+//# sourceMappingURL=skill-loader.js.map

package/dist/agent/skill-loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-loader.js","sourceRoot":"","sources":["../../src/agent/skill-loader.ts"],"names":[],"mappings":"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"}

package/dist/agent/skills/enrich-entities.md

@@ -0,0 +1,136 @@
+---
+name: enrich-entities
+description: Proactively suggest enrichment for incomplete entities using context
+loading: eager
+---
+
+# Entity Enrichment
+
+When you discover incomplete entities (missing recommended fields), proactively suggest enrichment using contextual inference.
+
+## Batch Enrichment (automated)
+
+For bulk enrichment of entities with low completeness scores, use the `enrich_run` tool:
+
+1. `enrich_run({ dryRun: true })` — preview what would be enriched
+2. Present summary to user, get confirmation
+3. `enrich_run()` — run enrichment (writes in-place, no git commit)
+4. "Review changes with `studiograph review`, then commit with `studiograph commit`"
+5. `workspace_commit({ messagePrefix: "enrich" })` — or let user commit via CLI
+
+Use `enrich_abort` to discard all changes if the results aren't satisfactory.
+
+## When to Enrich
+
+**Proactive discovery:**
+- User asks to "clean up" or "enrich" entities
+- You call `lint_entities` and find incomplete records
+- You fetch an entity and notice missing recommended fields
+
+**During normal work:**
+- User asks about a specific entity and you notice gaps
+- You're creating related entities and spot incomplete references
+
+## How to Enrich
+
+### 1. Discover gaps
+Use `lint_entities` to find incomplete entities:
+```
+lint_entities({ entityType: "project" })
+→ 12 projects missing client, start_date, or end_date
+```
+
+### 2. Gather context for each incomplete entity
+- **Fetch the entity:** `get_entity({ entityId: "..." })`
+- **Find related entities:** `get_backlinks({ entityId: "..." })`
+- **Search for references:** Look in meeting notes, proposals, briefs
+- **Check memory:** Review past conversations about this entity
+
+### 3. Infer missing values from context
+
+**Missing client:**
+- Search entity markdown body for `[[client-name]]` wikilinks
+- Check backlinks from meetings, proposals, deals
+- Look for client mentions in related artifacts
+
+**Missing dates:**
+- Extract from related meetings (kickoff = start_date)
+- Check proposal expected_start or contract signed_date
+- Look for date mentions in project description
+
+**Missing relationships:**
+- Scan for wikilinks in markdown body
+- Check what entities reference this one (backlinks)
+- Infer from entity type (artifact → deliverable → project)
+
+### 4. Suggest, don't assume
+Always confirm before updating:
+
+> "I notice this project is missing a client. I see Meridian Health mentioned in 3 related meetings and the project brief. Should I add `client: [[meridian-rebrand]]`?"
+
+Wait for user confirmation, then call `update_entity`.
+
+## Example Workflows
+
+**Batch enrichment:**
+```
+User: "Help me fill in missing clients for incomplete projects"
+
+You:
+1. lint_entities({ entityType: "project" }) → 8 missing client
+2. For each project:
+   - get_entity() → read markdown body
+   - get_backlinks() → find meetings, proposals
+   - Search for client wikilinks
+   - Suggest: "Add client: [[acme]]?" → confirm → update
+3. Report: "Enriched 6/8 projects. 2 need manual review (no clear client in context)."
+```
+
+**Focused enrichment:**
+```
+User: "Fill in missing deal values"
+
+You:
+1. lint_entities({ entityType: "deal" }) → 5 deals missing deal_value
+2. For each deal:
+   - get_backlinks() → find related proposal
+   - get_entity() on proposal → extract fees
+   - Suggest: "This deal's proposal shows $50k. Add deal_value: 50000?" → confirm → update
+```
+
+**Inline during work:**
+```
+User: "Show me the Acme project"
+
+You:
+1. get_entity({ entityId: "acme-rebrand" })
+2. Notice missing: client, start_date
+3. Get context: search for Acme client entity, check proposal
+4. Suggest inline: "This project is missing a client and start date. I found the Acme client entity and a proposal dated 2026-01-15. Should I add those?"
+```
+
+## Guidelines
+
+**Do:**
+- Use multiple context sources (backlinks, search, memory, markdown body)
+- Present evidence: "I see X mentioned in 3 meetings"
+- Batch similar fields: "Should I add client and start_date?"
+- Report progress: "Enriched 8/12, 4 need review"
+
+**Don't:**
+- Update without confirmation
+- Guess when evidence is weak ("I'm not sure which client this is")
+- Over-enrich — only fill recommended fields that are clearly missing
+- Make up data — if no context exists, say so: "I couldn't find a clear client reference. Would you like to specify it?"
+
+## Priority Fields
+
+Focus enrichment on high-value semantic fields:
+1. **Relationships** — client, project, deliverable (wikilinks)
+2. **Dates** — start_date, due_date, expected_close
+3. **People** — assignee, decision_makers, attendees
+4. **Values** — deal_value, fees, budget
+
+Low-priority (often intentionally omitted):
+- Tags, notes, optional descriptions
+- Status (user may want to set this themselves)