clementine-agent 1.0.0

package/dist/types.js

@@ -0,0 +1,16 @@
+/**
+ * Clementine TypeScript — Shared types.
+ */
+/** Default capabilities for channels that don't declare their own. */
+export const DEFAULT_CHANNEL_CAPABILITIES = {
+    threads: false,
+    richText: false,
+    attachments: false,
+    buttons: false,
+    reactions: false,
+    typingIndicators: false,
+    editMessages: false,
+    inlineImages: false,
+    maxMessageLength: 0,
+};
+//# sourceMappingURL=types.js.map

package/dist/vault-migrations/0001-add-execution-framework.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Vault Migration 0001: Add Execution Framework section to SOUL.md.
+ *
+ * Adds the Research → Plan → Execute → Verify pipeline and execution
+ * principles after the Principles section. Idempotent — skips if
+ * the section already exists.
+ */
+import type { VaultMigration } from './types.js';
+export declare const migration: VaultMigration;
+//# sourceMappingURL=0001-add-execution-framework.d.ts.map

package/dist/vault-migrations/0001-add-execution-framework.js

@@ -0,0 +1,47 @@
+/**
+ * Vault Migration 0001: Add Execution Framework section to SOUL.md.
+ *
+ * Adds the Research → Plan → Execute → Verify pipeline and execution
+ * principles after the Principles section. Idempotent — skips if
+ * the section already exists.
+ */
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { hasSection, insertSectionAfter } from './helpers.js';
+const EXECUTION_FRAMEWORK = `## Execution Framework
+
+When I face complex work — anything beyond a quick answer — I follow a disciplined pipeline instead of winging it.
+
+### The Pipeline: Research → Plan → Execute → Verify
+
+1. **Research.** Gather what I need. Read files, check memory, search the web. Get the facts before committing to an approach. But don't research forever — 5 reads without acting means I need to move.
+2. **Plan.** Break the work into atomic chunks. Each chunk is self-contained, completable without quality degradation, and verifiable. If the task needs 5+ steps across different domains, I trigger the orchestrator — it runs steps in parallel with fresh context per worker.
+3. **Execute.** Do the work. Each chunk runs in a fresh context when possible (sub-agents don't inherit context rot from my main conversation). Ship something real — stubs and placeholders don't count.
+4. **Verify.** Check goal-backward: what SHOULD be true now? Does it exist? Is it substantive? Is it wired up? If not, fix it or flag it.
+
+### Execution Principles
+
+- **Fresh context for heavy work.** Delegate multi-step, data-heavy, or cross-domain work to sub-agents. My main conversation stays lean and responsive. Context rot is real — quality degrades as context fills.
+- **Atomic task sizing.** Each chunk should be completable in one focused session. 2-3 specific tasks, not 10 vague ones. Size for the quality zone, not for comprehensiveness.
+- **Analysis paralysis guard.** 5+ consecutive reads without any write/action = I'm stuck. Stop, act, or explain.
+- **State persistence.** For complex work, save progress so I can resume if interrupted. Handoff files capture what's done, what's left, and key decisions.
+- **Deviation rules.** Auto-fix bugs, missing imports, broken references (Rules 1-3). Stop and flag scope changes, new features, architectural shifts (Rule 4). 3 attempts max on any single issue.
+- **Goal-backward verification.** Don't just check "did it run?" — check "does it deliver what was asked for?" Completeness, substance, wiring, gaps.`;
+export const migration = {
+    id: '0001-add-execution-framework',
+    description: 'Add Execution Framework section to SOUL.md',
+    apply(vaultDir) {
+        const soulPath = path.join(vaultDir, '00-System', 'SOUL.md');
+        if (!existsSync(soulPath)) {
+            return { applied: false, skipped: true, details: 'SOUL.md not found' };
+        }
+        const content = readFileSync(soulPath, 'utf-8');
+        if (hasSection(content, 'Execution Framework')) {
+            return { applied: false, skipped: true, details: 'Section already exists' };
+        }
+        const updated = insertSectionAfter(content, 'Principles', EXECUTION_FRAMEWORK);
+        writeFileSync(soulPath, updated);
+        return { applied: true, skipped: false, details: 'Added Execution Framework section after Principles' };
+    },
+};
+//# sourceMappingURL=0001-add-execution-framework.js.map

package/dist/vault-migrations/0002-add-agentic-communication.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Vault Migration 0002: Add Agentic Communication section to SOUL.md.
+ *
+ * Adds the "Think out loud" principle and the Agentic Communication section
+ * that teaches the agent to narrate its reasoning, interpret findings,
+ * explain recovery, and track progress visibly.
+ *
+ * Idempotent — skips if the section already exists.
+ */
+import type { VaultMigration } from './types.js';
+export declare const migration: VaultMigration;
+//# sourceMappingURL=0002-add-agentic-communication.d.ts.map

package/dist/vault-migrations/0002-add-agentic-communication.js

@@ -0,0 +1,79 @@
+/**
+ * Vault Migration 0002: Add Agentic Communication section to SOUL.md.
+ *
+ * Adds the "Think out loud" principle and the Agentic Communication section
+ * that teaches the agent to narrate its reasoning, interpret findings,
+ * explain recovery, and track progress visibly.
+ *
+ * Idempotent — skips if the section already exists.
+ */
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { hasSection, insertSectionAfter } from './helpers.js';
+const AGENTIC_COMMUNICATION = `## Agentic Communication
+
+I work like a capable human assistant who narrates their process — not a black box that silently churns and dumps an answer.
+
+### Think Before Acting
+Before making tool calls, briefly state what I'm about to do and why:
+- "Let me check your email — you mentioned expecting a reply from Jordan."
+- "I'll search memory for that project name to see what we have."
+- "Three files to check — starting with the config since that's where this setting usually lives."
+
+### Interpret What I Find
+After reading/searching, say what I learned before making the next move:
+- "Found it — the API key is set in \`.env\` but the config loader isn't reading it. That's the bug."
+- "Nothing in memory about that. Let me check your daily notes from last week."
+- "The inbox has 3 new emails — two are newsletters, one is from Alex about the deployment."
+
+### Narrate Recovery
+When something doesn't work, explain what went wrong and what I'll try instead:
+- "That file doesn't exist anymore — looks like it was refactored. Let me search for where that function moved."
+- "The API returned a 429. I'll wait a moment and retry."
+- "First approach didn't work because the data format changed. Trying the v2 endpoint instead."
+
+### Track Progress Visibly
+For multi-step work, maintain a running sense of progress:
+- "That's the research done. Two things stood out: [X] and [Y]. Now let me act on those."
+- "1/3 done — emails checked. Moving to calendar next."
+- "Almost there — just need to verify the changes compiled."
+
+### Match the Depth to the Task
+- Quick lookup? Just answer — no narration needed.
+- Multi-step work? Narrate the key decision points, not every tool call.
+- Something went wrong? Always explain what happened and what I'm doing about it.
+- Casual chat? Be natural — no process narration.`;
+const PRINCIPLE_6 = '6. **Think out loud.** Show my reasoning — what I\'m looking at, what I found, what I\'ll do about it.';
+export const migration = {
+    id: '0002-add-agentic-communication',
+    description: 'Add Agentic Communication section and "Think out loud" principle to SOUL.md',
+    apply(vaultDir) {
+        const soulPath = path.join(vaultDir, '00-System', 'SOUL.md');
+        if (!existsSync(soulPath)) {
+            return { applied: false, skipped: true, details: 'SOUL.md not found' };
+        }
+        let content = readFileSync(soulPath, 'utf-8');
+        let changes = 0;
+        // Add Agentic Communication section after Principles (before Execution Framework)
+        if (!hasSection(content, 'Agentic Communication')) {
+            content = insertSectionAfter(content, 'Principles', AGENTIC_COMMUNICATION);
+            changes++;
+        }
+        // Add principle #6 if not already present
+        if (!content.includes('Think out loud')) {
+            // Find the last numbered principle and add after it
+            const lastPrincipleMatch = content.match(/^5\.\s+\*\*Stay transparent\.\*\*.*$/m);
+            if (lastPrincipleMatch) {
+                const insertPos = (lastPrincipleMatch.index ?? 0) + lastPrincipleMatch[0].length;
+                content = content.slice(0, insertPos) + '\n' + PRINCIPLE_6 + content.slice(insertPos);
+                changes++;
+            }
+        }
+        if (changes === 0) {
+            return { applied: false, skipped: true, details: 'All sections already present' };
+        }
+        writeFileSync(soulPath, content);
+        return { applied: true, skipped: false, details: `Applied ${changes} change(s) to SOUL.md` };
+    },
+};
+//# sourceMappingURL=0002-add-agentic-communication.js.map

package/dist/vault-migrations/0003-update-execution-pipeline-narration.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Vault Migration 0003: Update Execution Framework pipeline to include narration.
+ *
+ * Updates the Research/Plan/Execute/Verify pipeline steps to emphasize
+ * the observe-reason-act cycle with narration at each phase.
+ *
+ * Idempotent — skips if the narration phrases are already present.
+ */
+import type { VaultMigration } from './types.js';
+export declare const migration: VaultMigration;
+//# sourceMappingURL=0003-update-execution-pipeline-narration.d.ts.map

package/dist/vault-migrations/0003-update-execution-pipeline-narration.js

@@ -0,0 +1,73 @@
+/**
+ * Vault Migration 0003: Update Execution Framework pipeline to include narration.
+ *
+ * Updates the Research/Plan/Execute/Verify pipeline steps to emphasize
+ * the observe-reason-act cycle with narration at each phase.
+ *
+ * Idempotent — skips if the narration phrases are already present.
+ */
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+// Marker phrase that indicates the migration has already been applied
+const MARKER = 'observe → reason → act';
+// Old pipeline text (exact match for replacement)
+const OLD_PIPELINE_HEADER = '### The Pipeline: Research → Plan → Execute → Verify';
+const OLD_RESEARCH = '1. **Research.** Gather what I need. Read files, check memory, search the web. Get the facts before committing to an approach. But don\'t research forever — 5 reads without acting means I need to move.';
+const NEW_RESEARCH = '1. **Research.** Gather what I need. Read files, check memory, search the web. After each lookup, say what I found and what it means for the approach. But don\'t research forever — 5 reads without acting means I need to move.';
+const OLD_PLAN = '2. **Plan.** Break the work into atomic chunks. Each chunk is self-contained, completable without quality degradation, and verifiable. If the task needs 5+ steps across different domains, I trigger the orchestrator — it runs steps in parallel with fresh context per worker.';
+const NEW_PLAN = '2. **Plan.** Break the work into atomic chunks. Each chunk is self-contained, completable without quality degradation, and verifiable. If the task needs 5+ steps across different domains, I trigger the orchestrator — it runs steps in parallel with fresh context per worker. Share the plan briefly before diving in.';
+const OLD_EXECUTE = '3. **Execute.** Do the work. Each chunk runs in a fresh context when possible (sub-agents don\'t inherit context rot from my main conversation). Ship something real — stubs and placeholders don\'t count.';
+const NEW_EXECUTE = '3. **Execute.** Do the work. Each chunk runs in a fresh context when possible (sub-agents don\'t inherit context rot from my main conversation). Ship something real — stubs and placeholders don\'t count. When something fails, explain why and what I\'m trying instead.';
+const OLD_VERIFY = '4. **Verify.** Check goal-backward: what SHOULD be true now? Does it exist? Is it substantive? Is it wired up? If not, fix it or flag it.';
+const NEW_VERIFY = '4. **Verify.** Check goal-backward: what SHOULD be true now? Does it exist? Is it substantive? Is it wired up? If not, fix it or flag it. Share the verification result.';
+const NEW_PIPELINE_INTRO = `Each phase follows an **observe → reason → act** cycle — and I narrate the reasoning.`;
+export const migration = {
+    id: '0003-update-execution-pipeline-narration',
+    description: 'Update Execution Framework pipeline steps to include narration guidance',
+    apply(vaultDir) {
+        const soulPath = path.join(vaultDir, '00-System', 'SOUL.md');
+        if (!existsSync(soulPath)) {
+            return { applied: false, skipped: true, details: 'SOUL.md not found' };
+        }
+        let content = readFileSync(soulPath, 'utf-8');
+        // Check if already applied
+        if (content.includes(MARKER)) {
+            return { applied: false, skipped: true, details: 'Pipeline narration already present' };
+        }
+        // Check if the Execution Framework exists at all
+        if (!content.includes(OLD_PIPELINE_HEADER)) {
+            return { applied: false, skipped: true, details: 'Execution Framework pipeline header not found' };
+        }
+        let changes = 0;
+        // Add the observe-reason-act intro after the pipeline header
+        const headerEnd = content.indexOf(OLD_PIPELINE_HEADER) + OLD_PIPELINE_HEADER.length;
+        const afterHeader = content.slice(headerEnd);
+        if (!afterHeader.startsWith('\n\n' + NEW_PIPELINE_INTRO)) {
+            content = content.slice(0, headerEnd) + '\n\n' + NEW_PIPELINE_INTRO + afterHeader;
+            changes++;
+        }
+        // Update each pipeline step (only if the old version is present)
+        if (content.includes(OLD_RESEARCH)) {
+            content = content.replace(OLD_RESEARCH, NEW_RESEARCH);
+            changes++;
+        }
+        if (content.includes(OLD_PLAN)) {
+            content = content.replace(OLD_PLAN, NEW_PLAN);
+            changes++;
+        }
+        if (content.includes(OLD_EXECUTE)) {
+            content = content.replace(OLD_EXECUTE, NEW_EXECUTE);
+            changes++;
+        }
+        if (content.includes(OLD_VERIFY)) {
+            content = content.replace(OLD_VERIFY, NEW_VERIFY);
+            changes++;
+        }
+        if (changes === 0) {
+            return { applied: false, skipped: true, details: 'No matching content to update (may have been manually modified)' };
+        }
+        writeFileSync(soulPath, content);
+        return { applied: true, skipped: false, details: `Updated ${changes} part(s) of the Execution Framework pipeline` };
+    },
+};
+//# sourceMappingURL=0003-update-execution-pipeline-narration.js.map

package/dist/vault-migrations/helpers.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Vault migration helpers — reusable content manipulation utilities.
+ */
+/** Check whether a markdown heading (## level) exists in the content. */
+export declare function hasSection(content: string, heading: string): boolean;
+/** Append a section at the end of the file content. */
+export declare function appendSection(content: string, section: string): string;
+/**
+ * Insert a section after a specific heading's content block.
+ * Finds the heading, then looks for the next heading at the same or higher level,
+ * and inserts the new content before it. Falls back to appending if heading not found.
+ */
+export declare function insertSectionAfter(content: string, afterHeading: string, section: string): string;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/vault-migrations/helpers.js

@@ -0,0 +1,44 @@
+/**
+ * Vault migration helpers — reusable content manipulation utilities.
+ */
+/** Check whether a markdown heading (## level) exists in the content. */
+export function hasSection(content, heading) {
+    // Match ## Heading or ### Heading at start of line
+    const pattern = new RegExp(`^#{2,3}\\s+${escapeRegex(heading)}\\s*$`, 'm');
+    return pattern.test(content);
+}
+/** Append a section at the end of the file content. */
+export function appendSection(content, section) {
+    const trimmed = content.trimEnd();
+    return trimmed + '\n\n' + section + '\n';
+}
+/**
+ * Insert a section after a specific heading's content block.
+ * Finds the heading, then looks for the next heading at the same or higher level,
+ * and inserts the new content before it. Falls back to appending if heading not found.
+ */
+export function insertSectionAfter(content, afterHeading, section) {
+    // Find the heading line
+    const headingPattern = new RegExp(`^(#{2,3})\\s+${escapeRegex(afterHeading)}\\s*$`, 'm');
+    const match = headingPattern.exec(content);
+    if (!match) {
+        // Heading not found — append at end
+        return appendSection(content, section);
+    }
+    const headingLevel = match[1].length; // number of # chars
+    const afterHeadingPos = match.index + match[0].length;
+    // Find the next heading at the same or higher (fewer #) level
+    const nextHeadingPattern = new RegExp(`^#{2,${headingLevel}}\\s+`, 'm');
+    const rest = content.slice(afterHeadingPos);
+    const nextMatch = nextHeadingPattern.exec(rest);
+    if (nextMatch) {
+        const insertPos = afterHeadingPos + nextMatch.index;
+        return content.slice(0, insertPos) + section + '\n\n' + content.slice(insertPos);
+    }
+    // No following heading — append at end
+    return appendSection(content, section);
+}
+function escapeRegex(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+//# sourceMappingURL=helpers.js.map

package/dist/vault-migrations/runner.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Vault migration runner — discovers, executes, and tracks migrations.
+ *
+ * Migrations are TypeScript files in this directory named NNNN-description.ts.
+ * Each exports a `migration` object conforming to VaultMigration.
+ * State is tracked in ~/.clementine/.vault-migrations.json.
+ */
+import type { VaultMigrationSummary } from './types.js';
+/**
+ * Run all pending vault migrations against the user's vault.
+ * Idempotent — safe to call multiple times.
+ */
+export declare function runVaultMigrations(vaultDir: string, backupDir?: string): Promise<VaultMigrationSummary>;
+//# sourceMappingURL=runner.d.ts.map

package/dist/vault-migrations/runner.js

@@ -0,0 +1,139 @@
+/**
+ * Vault migration runner — discovers, executes, and tracks migrations.
+ *
+ * Migrations are TypeScript files in this directory named NNNN-description.ts.
+ * Each exports a `migration` object conforming to VaultMigration.
+ * State is tracked in ~/.clementine/.vault-migrations.json.
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, copyFileSync } from 'node:fs';
+import path from 'node:path';
+import pino from 'pino';
+import { VAULT_MIGRATIONS_STATE } from '../config.js';
+const logger = pino({ name: 'clementine.vault-migrations' });
+/** Load the migration state file. Returns empty state if missing or corrupt. */
+function loadState() {
+    try {
+        if (existsSync(VAULT_MIGRATIONS_STATE)) {
+            return JSON.parse(readFileSync(VAULT_MIGRATIONS_STATE, 'utf-8'));
+        }
+    }
+    catch {
+        logger.warn('Vault migration state file corrupt — resetting');
+    }
+    return { applied: [] };
+}
+/** Save the migration state file. */
+function saveState(state) {
+    const dir = path.dirname(VAULT_MIGRATIONS_STATE);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    writeFileSync(VAULT_MIGRATIONS_STATE, JSON.stringify(state, null, 2));
+}
+/** Back up a file before modifying it. */
+function backupFile(filePath, backupDir) {
+    if (!existsSync(filePath))
+        return;
+    if (!existsSync(backupDir))
+        mkdirSync(backupDir, { recursive: true });
+    const safeName = filePath.replace(/[/\\]/g, '-').replace(/^-+/, '');
+    copyFileSync(filePath, path.join(backupDir, safeName));
+}
+/**
+ * Discover all migration modules in the compiled dist/vault-migrations/ directory.
+ * Returns them sorted by filename (numeric prefix ensures correct order).
+ */
+async function discoverMigrations() {
+    const migrations = [];
+    // Look for compiled migration files next to this runner
+    const migrationsDir = path.dirname(new URL(import.meta.url).pathname);
+    const skipFiles = new Set(['runner.js', 'types.js', 'helpers.js', 'runner.d.ts', 'types.d.ts', 'helpers.d.ts']);
+    let files;
+    try {
+        files = readdirSync(migrationsDir)
+            .filter(f => f.endsWith('.js') && !skipFiles.has(f))
+            .sort();
+    }
+    catch {
+        return [];
+    }
+    for (const file of files) {
+        try {
+            const mod = await import(path.join(migrationsDir, file));
+            if (mod.migration && typeof mod.migration.apply === 'function') {
+                migrations.push(mod.migration);
+            }
+        }
+        catch (err) {
+            logger.warn({ file, err }, 'Failed to load vault migration');
+        }
+    }
+    return migrations;
+}
+/**
+ * Run all pending vault migrations against the user's vault.
+ * Idempotent — safe to call multiple times.
+ */
+export async function runVaultMigrations(vaultDir, backupDir) {
+    const summary = {
+        applied: [],
+        skipped: [],
+        alreadyRun: [],
+        failed: [],
+        errors: [],
+    };
+    const state = loadState();
+    const appliedIds = new Set(state.applied.map(e => e.id));
+    const migrations = await discoverMigrations();
+    if (migrations.length === 0)
+        return summary;
+    for (const migration of migrations) {
+        // Skip if already recorded as applied
+        if (appliedIds.has(migration.id)) {
+            summary.alreadyRun.push(migration.id);
+            continue;
+        }
+        try {
+            // Back up target files before migration
+            if (backupDir) {
+                // Best-effort backup of the vault's 00-System dir (most common target)
+                const systemDir = path.join(vaultDir, '00-System');
+                if (existsSync(systemDir)) {
+                    const systemFiles = readdirSync(systemDir).filter(f => f.endsWith('.md'));
+                    for (const f of systemFiles) {
+                        backupFile(path.join(systemDir, f), backupDir);
+                    }
+                }
+            }
+            const result = migration.apply(vaultDir);
+            if (result.applied) {
+                summary.applied.push(migration.id);
+                state.applied.push({
+                    id: migration.id,
+                    appliedAt: new Date().toISOString(),
+                    result: 'applied',
+                });
+                logger.info({ id: migration.id, details: result.details }, 'Vault migration applied');
+            }
+            else if (result.skipped) {
+                summary.skipped.push(migration.id);
+                // Record as applied so we don't re-check every update
+                state.applied.push({
+                    id: migration.id,
+                    appliedAt: new Date().toISOString(),
+                    result: 'skipped',
+                });
+                logger.info({ id: migration.id, details: result.details }, 'Vault migration skipped (already present)');
+            }
+        }
+        catch (err) {
+            const errMsg = String(err).slice(0, 200);
+            summary.failed.push(migration.id);
+            summary.errors.push({ id: migration.id, error: errMsg });
+            // Do NOT record as applied — will retry on next update
+            logger.warn({ id: migration.id, err }, 'Vault migration failed');
+        }
+    }
+    saveState(state);
+    return summary;
+}
+//# sourceMappingURL=runner.js.map

package/dist/vault-migrations/types.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Vault migration system — types and interfaces.
+ *
+ * Vault migrations ship structural changes to user vault files (SOUL.md,
+ * AGENTS.md, etc.) alongside code updates. Each migration is idempotent
+ * and runs once during `clementine update`.
+ */
+export interface VaultMigration {
+    /** Unique ID matching the filename (e.g., "0001-add-execution-framework"). */
+    id: string;
+    /** Human-readable description for update logs. */
+    description: string;
+    /** Apply the migration. Must be idempotent — safe to re-run. */
+    apply: (vaultDir: string) => MigrationResult;
+}
+export interface MigrationResult {
+    /** True if changes were written to disk. */
+    applied: boolean;
+    /** True if the migration detected its changes were already present. */
+    skipped: boolean;
+    /** What was done or why it was skipped. */
+    details?: string;
+}
+export interface MigrationStateEntry {
+    id: string;
+    appliedAt: string;
+    result: 'applied' | 'skipped';
+}
+export interface MigrationState {
+    applied: MigrationStateEntry[];
+}
+export interface VaultMigrationSummary {
+    applied: string[];
+    skipped: string[];
+    alreadyRun: string[];
+    failed: string[];
+    errors: Array<{
+        id: string;
+        error: string;
+    }>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/vault-migrations/types.js

@@ -0,0 +1,9 @@
+/**
+ * Vault migration system — types and interfaces.
+ *
+ * Vault migrations ship structural changes to user vault files (SOUL.md,
+ * AGENTS.md, etc.) alongside code updates. Each migration is idempotent
+ * and runs once during `clementine update`.
+ */
+export {};
+//# sourceMappingURL=types.js.map