@feelingmindful/thinking-graph 1.10.0 → 1.11.0

package/dist/tools/skill-routing.d.ts

@@ -0,0 +1,63 @@
+import type { ThinkingGraph } from '../engine/graph.js';
+export interface SkillRoutingInput {
+    request: string;
+    platform?: 'ios' | 'android' | 'web' | 'all';
+    goalVerb?: string;
+    areas?: string[];
+    currentState?: 'new' | 'existing' | 'unknown';
+    detectedNeeds?: string[];
+    maxCandidates?: number;
+    selectedInvocation?: string;
+}
+export interface RoutedSkillCandidate {
+    id: string;
+    plugin: string;
+    skill: string;
+    invocation: string;
+    verb?: string;
+    platform?: string;
+    areas: string[];
+    detects: string[];
+    produces: string[];
+    invokes: string[];
+    score: number;
+    reasons: string[];
+}
+export interface SkillPlanStep {
+    stepNumber: number;
+    invocation: string;
+    plugin: string;
+    skill: string;
+    verb?: string;
+    purpose: string;
+    approvalGateIds: string[];
+}
+export interface ApprovalGate {
+    id: string;
+    title: string;
+    beforeStepNumber: number;
+    reason: string;
+    prompt: string;
+}
+export declare function buildPlanId(input: {
+    request?: string;
+    plan: SkillPlanStep[];
+    approvalGates: ApprovalGate[];
+}): string;
+export declare function routeSkills(graph: ThinkingGraph, input: SkillRoutingInput): Promise<{
+    desiredVerb?: string;
+    inferredAreas: string[];
+    heuristicNotes: string[];
+    candidates: RoutedSkillCandidate[];
+}>;
+export declare function buildSkillPlan(graph: ThinkingGraph, input: SkillRoutingInput & {
+    requireApproval?: boolean;
+}): Promise<{
+    desiredVerb?: string;
+    inferredAreas: string[];
+    heuristicNotes: string[];
+    route: RoutedSkillCandidate | null;
+    plan: SkillPlanStep[];
+    approvalGates: ApprovalGate[];
+    fallbacks: RoutedSkillCandidate[];
+}>;

package/dist/tools/skill-routing.js

@@ -0,0 +1,343 @@
+import { createHash } from 'node:crypto';
+export function buildPlanId(input) {
+    const payload = JSON.stringify({
+        request: input.request ?? null,
+        plan: input.plan.map(step => ({
+            stepNumber: step.stepNumber,
+            invocation: step.invocation,
+            plugin: step.plugin,
+            skill: step.skill,
+            verb: step.verb ?? null,
+            purpose: step.purpose,
+            approvalGateIds: [...step.approvalGateIds].sort(),
+        })),
+        approvalGates: input.approvalGates.map(gate => ({
+            id: gate.id,
+            title: gate.title,
+            beforeStepNumber: gate.beforeStepNumber,
+            reason: gate.reason,
+            prompt: gate.prompt,
+        })),
+    });
+    return `plan_${createHash('sha1').update(payload).digest('hex').slice(0, 12)}`;
+}
+const WORKFLOW_ORDER = ['research', 'init', 'configure', 'refactor', 'create', 'growth', 'humanize', 'audit'];
+const AREA_ALIASES = {
+    accessibility: ['accessibility'],
+    analytics: ['observability'],
+    api: ['api', 'backend', 'fullstack'],
+    auth: ['auth', 'security'],
+    backend: ['backend', 'api', 'fullstack', 'data'],
+    content: ['content-sites', 'seo'],
+    copy: ['copy'],
+    dashboard: ['frontend', 'architecture', 'routing'],
+    data: ['data', 'backend', 'fullstack'],
+    design: ['design-tokens', 'icons', 'typography', 'animations'],
+    form: ['frontend'],
+    infra: ['infra', 'observability'],
+    marketing: ['copy', 'seo'],
+    monetization: ['monetization', 'subscriptions', 'iap', 'receipts'],
+    observability: ['observability', 'performance'],
+    payment: ['monetization', 'receipts'],
+    performance: ['performance', 'observability'],
+    queue: ['jobs', 'queues', 'background-processing'],
+    realtime: ['realtime', 'websockets', 'sse', 'data'],
+    routing: ['routing', 'react-router', 'app-router'],
+    seo: ['seo', 'content-sites'],
+    state: ['architecture', 'routing', 'tanstack-query', 'zustand'],
+    tanstack: ['tanstack-query'],
+    ui: ['frontend', 'design-tokens', 'icons', 'typography', 'animations'],
+    upload: ['media', 'uploads', 'cdn'],
+    webhooks: ['webhooks', 'integrations'],
+    zustand: ['zustand', 'architecture'],
+};
+function tokenize(input) {
+    return input
+        .toLowerCase()
+        .split(/[^a-z0-9-]+/)
+        .filter(Boolean);
+}
+function inferGoalVerb(request, currentState, explicitGoal) {
+    if (explicitGoal)
+        return explicitGoal;
+    const tokens = tokenize(request);
+    if (tokens.some(t => ['audit', 'review', 'check', 'inspect'].includes(t)))
+        return 'audit';
+    if (tokens.some(t => ['research', 'explore', 'compare', 'investigate'].includes(t)))
+        return 'research';
+    if (tokens.some(t => ['configure', 'setup', 'integrate', 'wire'].includes(t)))
+        return 'configure';
+    if (tokens.some(t => ['refactor', 'fix', 'improve', 'clean'].includes(t)))
+        return 'refactor';
+    if (tokens.some(t => ['create', 'build', 'implement', 'ship'].includes(t)))
+        return currentState === 'new' ? 'full' : 'create';
+    if (tokens.some(t => ['init', 'scaffold', 'bootstrap'].includes(t)))
+        return 'init';
+    if (tokens.some(t => ['full', 'end-to-end', 'orchestrate', 'launch'].includes(t)))
+        return 'full';
+    return currentState === 'new' ? 'full' : undefined;
+}
+function inferAreas(request, explicitAreas, skills) {
+    const inferred = new Set((explicitAreas ?? []).map(a => a.toLowerCase()));
+    const tokens = tokenize(request);
+    for (const token of tokens) {
+        for (const area of AREA_ALIASES[token] ?? [])
+            inferred.add(area);
+    }
+    const allKnownAreas = new Set(skills.flatMap(skill => skill.areas.map(area => area.toLowerCase())));
+    for (const token of tokens) {
+        if (allKnownAreas.has(token))
+            inferred.add(token);
+    }
+    return [...inferred];
+}
+function containsText(haystack, terms) {
+    const lower = haystack.toLowerCase();
+    return terms.some(term => lower.includes(term));
+}
+function scoreSkill(skill, request, inferredAreas, desiredVerb, currentState, detectedNeeds, relatedNodes, requestedPlatform) {
+    let score = 0;
+    const reasons = [];
+    const requestTerms = tokenize(request);
+    const requestText = request.toLowerCase();
+    if (requestedPlatform && skill.platform === requestedPlatform) {
+        score += 30;
+        reasons.push(`exact ${requestedPlatform} platform match`);
+    }
+    else if (requestedPlatform && skill.platform === 'all') {
+        score += 12;
+        reasons.push('cross-platform workflow remains valid');
+    }
+    if (desiredVerb && skill.verb === desiredVerb) {
+        score += 28;
+        reasons.push(`verb matches requested outcome (${desiredVerb})`);
+    }
+    else if (desiredVerb === 'full' && skill.verb === 'full') {
+        score += 22;
+        reasons.push('orchestrator workflow fits end-to-end request');
+    }
+    const matchedAreas = inferredAreas.filter(area => skill.areas.map(a => a.toLowerCase()).includes(area));
+    if (matchedAreas.length > 0) {
+        score += matchedAreas.length * 9;
+        reasons.push(`covers requested areas: ${matchedAreas.join(', ')}`);
+    }
+    if (containsText(`${skill.invocation} ${skill.pluginName} ${skill.skillName}`, requestTerms)) {
+        score += 10;
+        reasons.push('name/invocation aligns with request wording');
+    }
+    const matchedNeeds = detectedNeeds.filter(need => skill.detects.includes(need));
+    if (matchedNeeds.length > 0) {
+        score += matchedNeeds.length * 10;
+        reasons.push(`detects requested state: ${matchedNeeds.join(', ')}`);
+    }
+    if (currentState === 'new' && skill.verb && ['full', 'research', 'init', 'create'].includes(skill.verb)) {
+        score += 8;
+        reasons.push('good fit for greenfield work');
+    }
+    if (currentState === 'existing' && skill.verb && ['full', 'audit', 'configure', 'refactor'].includes(skill.verb)) {
+        score += 8;
+        reasons.push('good fit for existing codebases');
+    }
+    if (skill.verb === 'full' && skill.invokes.length > 0) {
+        score += 4;
+        reasons.push('has an orchestrated skill chain');
+    }
+    if (relatedNodes.length > 0) {
+        const nodeText = relatedNodes.map(node => node.content.toLowerCase()).join(' ');
+        const priorAreaHits = skill.areas.filter(area => nodeText.includes(area.toLowerCase()));
+        if (priorAreaHits.length > 0) {
+            score += Math.min(priorAreaHits.length * 4, 12);
+            reasons.push(`prior graph context overlaps: ${priorAreaHits.slice(0, 3).join(', ')}`);
+        }
+        if (relatedNodes.some(node => ['detection', 'tech_debt'].includes(node.type)) && skill.detects.some(d => ['missing', 'needs-work'].includes(d))) {
+            score += 6;
+            reasons.push('prior detections/debt make remediation workflow relevant');
+        }
+        if (relatedNodes.some(node => node.type === 'decision') && skill.produces.includes('decision')) {
+            score += 3;
+            reasons.push('workflow commonly produces actionable decisions');
+        }
+    }
+    if (skill.areas.some(area => requestText.includes(area.toLowerCase()))) {
+        score += 6;
+        reasons.push('request directly mentions skill coverage');
+    }
+    return {
+        id: skill.id,
+        plugin: skill.pluginName,
+        skill: skill.skillName,
+        invocation: skill.invocation,
+        verb: skill.verb,
+        platform: skill.platform,
+        areas: skill.areas,
+        detects: skill.detects,
+        produces: skill.produces,
+        invokes: skill.invokes,
+        score,
+        reasons,
+    };
+}
+export async function routeSkills(graph, input) {
+    const desiredVerb = inferGoalVerb(input.request, input.currentState, input.goalVerb);
+    const skills = await graph.storage.querySkills(input.platform ? { platform: input.platform } : {});
+    const inferredAreas = inferAreas(input.request, input.areas, skills);
+    const relatedNodes = await graph.searchNodes(input.request, 12);
+    const detectedNeeds = input.detectedNeeds ?? [];
+    const candidates = skills
+        .map(skill => scoreSkill(skill, input.request, inferredAreas, desiredVerb, input.currentState, detectedNeeds, relatedNodes, input.platform))
+        .filter(candidate => candidate.score > 0)
+        .sort((a, b) => {
+        if (b.score !== a.score)
+            return b.score - a.score;
+        const aOrder = WORKFLOW_ORDER.indexOf(a.verb ?? 'audit');
+        const bOrder = WORKFLOW_ORDER.indexOf(b.verb ?? 'audit');
+        return aOrder - bOrder;
+    })
+        .slice(0, input.maxCandidates ?? 5);
+    const heuristicNotes = [
+        desiredVerb ? `desired verb inferred as \`${desiredVerb}\`` : 'no explicit verb inferred; ranking favors area/platform fit',
+        inferredAreas.length > 0 ? `areas inferred: ${inferredAreas.join(', ')}` : 'no strong area hints inferred from request',
+        relatedNodes.length > 0 ? `used ${relatedNodes.length} graph nodes as lightweight context` : 'no close graph context found for this request',
+    ];
+    return { desiredVerb, inferredAreas, heuristicNotes, candidates };
+}
+function buildPurpose(skill) {
+    if (skill.verb === 'research')
+        return 'gather context and sharpen the implementation direction';
+    if (skill.verb === 'init')
+        return 'establish missing foundation and initial scaffolding';
+    if (skill.verb === 'configure')
+        return 'wire infrastructure, auth, data, security, or observability';
+    if (skill.verb === 'refactor')
+        return 'reshape architecture or state ownership in-place';
+    if (skill.verb === 'create')
+        return 'build product/UI surface and deliver the requested experience';
+    if (skill.verb === 'audit')
+        return 'verify quality and surface issues before completion';
+    if (skill.verb === 'growth')
+        return 'improve growth loops and conversion strategy';
+    if (skill.verb === 'humanize')
+        return 'improve product copy and tone';
+    return 'execute the selected workflow';
+}
+function dedupeSkills(skills) {
+    const seen = new Set();
+    return skills.filter(skill => {
+        if (seen.has(skill.invocation))
+            return false;
+        seen.add(skill.invocation);
+        return true;
+    });
+}
+function selectWorkflowVerbs(currentState, desiredVerb, selected) {
+    if (desiredVerb && desiredVerb !== 'full')
+        return [desiredVerb];
+    if (selected.verb && ['research', 'init', 'configure', 'refactor', 'create', 'audit'].includes(selected.verb) && desiredVerb !== 'full') {
+        return [selected.verb];
+    }
+    return currentState === 'new'
+        ? ['research', 'init', 'configure', 'create', 'audit']
+        : ['research', 'configure', 'refactor', 'create', 'audit'];
+}
+function buildApprovalGates(steps, requireApproval) {
+    if (!requireApproval || steps.length === 0)
+        return [];
+    const gates = [{
+            id: 'approve-plan',
+            title: 'Approve selected route and plan',
+            beforeStepNumber: 1,
+            reason: 'Confirms the chosen skill family, execution order, and intended scope before any workflow runs.',
+            prompt: 'Approve this execution plan before step 1.',
+        }];
+    const firstInit = steps.find(step => step.verb === 'init');
+    if (firstInit) {
+        gates.push({
+            id: 'approve-foundation',
+            title: 'Approve foundation and scaffolding choices',
+            beforeStepNumber: firstInit.stepNumber,
+            reason: 'Init steps usually lock in framework, structure, and default service choices.',
+            prompt: `Approve foundation choices before step ${firstInit.stepNumber}.`,
+        });
+    }
+    const firstArchitecture = steps.find(step => ['configure', 'refactor'].includes(step.verb ?? ''));
+    if (firstArchitecture) {
+        gates.push({
+            id: 'approve-architecture',
+            title: 'Approve architecture and integration changes',
+            beforeStepNumber: firstArchitecture.stepNumber,
+            reason: 'Configure/refactor work can change auth ownership, data flow, state management, and infra boundaries.',
+            prompt: `Approve architecture/integration changes before step ${firstArchitecture.stepNumber}.`,
+        });
+    }
+    const firstMessaging = steps.find(step => ['growth', 'humanize'].includes(step.verb ?? ''));
+    if (firstMessaging) {
+        gates.push({
+            id: 'approve-messaging',
+            title: 'Approve messaging or growth changes',
+            beforeStepNumber: firstMessaging.stepNumber,
+            reason: 'Growth and copy steps change user-facing messaging and should be explicitly approved.',
+            prompt: `Approve messaging/growth changes before step ${firstMessaging.stepNumber}.`,
+        });
+    }
+    return gates;
+}
+export async function buildSkillPlan(graph, input) {
+    const routed = await routeSkills(graph, input);
+    const allSkills = await graph.storage.querySkills(input.platform ? { platform: input.platform } : {});
+    const byInvocation = new Map(allSkills.map(skill => [skill.invocation, skill]));
+    const selectedCandidate = input.selectedInvocation
+        ? routed.candidates.find(candidate => candidate.invocation === input.selectedInvocation) ?? null
+        : routed.candidates[0] ?? null;
+    if (!selectedCandidate) {
+        return {
+            desiredVerb: routed.desiredVerb,
+            inferredAreas: routed.inferredAreas,
+            heuristicNotes: routed.heuristicNotes,
+            route: null,
+            plan: [],
+            approvalGates: [],
+            fallbacks: [],
+        };
+    }
+    const selectedSkill = byInvocation.get(selectedCandidate.invocation);
+    const family = allSkills.filter(skill => skill.pluginName === selectedSkill.pluginName && skill.skillName === selectedSkill.skillName);
+    let orderedSkills = [];
+    if (selectedSkill.verb === 'full' && selectedSkill.invokes.length > 0) {
+        orderedSkills = selectedSkill.invokes.map(invocation => byInvocation.get(invocation)).filter(Boolean);
+    }
+    else if (family.length > 1) {
+        const wantedVerbs = selectWorkflowVerbs(input.currentState, routed.desiredVerb, selectedSkill);
+        const familyMap = new Map(family.map(skill => [skill.verb ?? '', skill]));
+        orderedSkills = wantedVerbs.map(verb => familyMap.get(verb)).filter(Boolean);
+        if (orderedSkills.length === 0)
+            orderedSkills = [selectedSkill];
+    }
+    else {
+        orderedSkills = [selectedSkill];
+    }
+    const dedupedSkills = dedupeSkills(orderedSkills);
+    const steps = dedupedSkills.map((skill, index) => ({
+        stepNumber: index + 1,
+        invocation: skill.invocation,
+        plugin: skill.pluginName,
+        skill: skill.skillName,
+        verb: skill.verb,
+        purpose: buildPurpose(skill),
+        approvalGateIds: [],
+    }));
+    const approvalGates = buildApprovalGates(steps, input.requireApproval ?? true);
+    for (const gate of approvalGates) {
+        const step = steps.find(candidate => candidate.stepNumber === gate.beforeStepNumber);
+        if (step)
+            step.approvalGateIds.push(gate.id);
+    }
+    return {
+        desiredVerb: routed.desiredVerb,
+        inferredAreas: routed.inferredAreas,
+        heuristicNotes: routed.heuristicNotes,
+        route: selectedCandidate,
+        plan: steps,
+        approvalGates,
+        fallbacks: routed.candidates.filter(candidate => candidate.invocation !== selectedCandidate.invocation).slice(0, 2),
+    };
+}

package/dist/tools/think.js

@@ -82,7 +82,7 @@ function buildSuggestions(type, thoughtNumber, relatedCount, stats, matchedSkill
         suggestions.push({
             tool: 'skill',
             when: 'Load the reasoning skill for structured thinking: recall → think → relate → research → decide → learn',
-            example: { skill: 'premium-core:reasoning' },
+            example: { skill: 'reasoning' },
         });
     }
     // Append matched skills from the registry
@@ -155,8 +155,8 @@ export async function thinkHandler(graph, input) {
         if (matches.length > 0) {
             matchedSkills = matches.slice(0, 2).map(s => ({
                 tool: 'skill',
-                when: `${s.verb ?? 'Run'} with ${s.pluginName}:${s.skillName} (covers: ${s.areas.join(', ')})`,
-                example: { skill: `${s.pluginName}:${s.skillName}` },
+                when: `Run \`${s.invocation}\`${s.areas.length > 0 ? ` (covers: ${s.areas.join(', ')})` : ''}`,
+                example: { skill: `${s.pluginName}:${s.skillName}`, invocation: s.invocation },
             }));
         }
     }

package/dist/vault/bridge.d.ts

@@ -29,6 +29,11 @@ export interface VaultWriteOpts {
     projectSlug: string;
     metadata?: Record<string, unknown>;
 }
+/**
+ * Derive a short, meaningful title from freeform content.
+ * Takes the first sentence (or first N words) and sanitizes it.
+ */
+export declare function deriveTitle(content: string, fallback: string): string;
 export declare class VaultBridge {
     private vaultRoot;
     constructor(vaultPath: string);

package/dist/vault/bridge.js

@@ -33,12 +33,37 @@ function expandHome(p) {
         return join(homedir(), p.slice(2));
     return p;
 }
+// Obsidian titles should stay under 60 chars for clean sidebar display.
+// macOS allows 255 bytes but long titles break Obsidian search and links.
+const MAX_TITLE_LENGTH = 60;
 function sanitizeFilename(name) {
     return name
-        .replace(/[<>:"/\\|?*]/g, '')
+        .replace(/[<>:"/\\|?*#^\[\]]/g, '') // filesystem + Obsidian-reserved chars
         .replace(/\s+/g, ' ')
         .trim()
-        .slice(0, 120);
+        .slice(0, MAX_TITLE_LENGTH);
+}
+/**
+ * Derive a short, meaningful title from freeform content.
+ * Takes the first sentence (or first N words) and sanitizes it.
+ */
+export function deriveTitle(content, fallback) {
+    // Strip leading markdown headings/bullets
+    const cleaned = content.replace(/^[#\-*>\s]+/, '').trim();
+    if (!cleaned)
+        return sanitizeFilename(fallback);
+    // Take first sentence (up to period, newline, or em-dash)
+    const firstSentence = cleaned.split(/[.\n—]/, 1)[0].trim();
+    // If the sentence is short enough, use it
+    if (firstSentence.length > 0 && firstSentence.length <= MAX_TITLE_LENGTH) {
+        const title = firstSentence.replace(/[^a-zA-Z0-9 \-_]/g, '').trim();
+        if (title.length >= 5)
+            return sanitizeFilename(title);
+    }
+    // Otherwise take first ~8 words
+    const words = cleaned.replace(/[^a-zA-Z0-9 \-_]/g, '').split(/\s+/).filter(Boolean);
+    const shortTitle = words.slice(0, 8).join(' ');
+    return sanitizeFilename(shortTitle || fallback);
 }
 /**
  * Walk a directory tree and yield .md files.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feelingmindful/thinking-graph",
-  "version": "1.10.0",
+  "version": "1.11.0",
   "description": "Persistent graph-based MCP thinking server for the feeling-mindful plugin marketplace",
   "type": "module",
   "main": "dist/index.js",