thoth-plugin 1.1.1 → 1.1.2

package/README.md

@@ -4,6 +4,96 @@
 
 Thoth is a knowledge-based life operating system that acts as your chief of staff. Unlike traditional coding assistants, Thoth is designed to **support, guide, and mentor** — not just write code.
 
+## Installation
+
+### Via npm (Recommended)
+
+```bash
+npm install -g thoth-plugin
+```
+
+Then add to your OpenCode config (`~/.config/opencode/opencode.json`):
+
+```json
+{
+  "plugin": [
+    "thoth-plugin"
+  ]
+}
+```
+
+### Initialize Your Knowledge Base
+
+```bash
+# Create a new knowledge base with default structure
+npx thoth-plugin init
+
+# Or initialize in a specific directory
+npx thoth-plugin init ./my-thoth-kb
+```
+
+### Configure Knowledge Base Path
+
+Create `~/.config/opencode/thoth-plugin.json`:
+
+```json
+{
+  "enabled": true,
+  "knowledge_base": "/path/to/your/thoth-kb"
+}
+```
+
+---
+
+## LLM Installation Instructions
+
+<!-- 
+INSTRUCTIONS FOR AI ASSISTANTS:
+
+When a user asks you to "install Thoth plugin" or provides a link to this repository,
+follow these steps:
+
+1. Install the plugin globally:
+   npm install -g thoth-plugin
+
+2. Add to OpenCode config (~/.config/opencode/opencode.json):
+   - Read the existing config file
+   - Add "thoth-plugin" to the "plugin" array
+   - If "plugin" array doesn't exist, create it
+
+3. Initialize the knowledge base:
+   npx thoth-plugin init ~/thoth-kb
+
+4. Configure the knowledge base path (~/.config/opencode/thoth-plugin.json):
+   {
+     "enabled": true,
+     "knowledge_base": "/Users/<username>/thoth-kb"
+   }
+
+5. Restart OpenCode to load the plugin
+
+EXAMPLE COMMANDS:
+```bash
+# Install
+npm install -g thoth-plugin
+
+# Add to OpenCode config
+# Edit ~/.config/opencode/opencode.json and add "thoth-plugin" to plugin array
+
+# Initialize knowledge base
+npx thoth-plugin init ~/thoth-kb
+
+# Create thoth config
+echo '{"enabled": true, "knowledge_base": "'$HOME'/thoth-kb"}' > ~/.config/opencode/thoth-plugin.json
+
+# Restart OpenCode
+```
+-->
+
+If you're an AI assistant helping a user install Thoth, see the HTML comment above for step-by-step instructions.
+
+---
+
 ## Features
 
 - **Four Hemispheres**: Organized knowledge across work, life, coding, and system (kernel)
@@ -11,6 +101,7 @@ Thoth is a knowledge-based life operating system that acts as your chief of staf
 - **Smart Delegation**: Routes tasks to specialized sub-agents (Work Master, Life Master, Code Master)
 - **Permission System**: Critical actions require explicit approval
 - **Knowledge Persistence**: Learns and remembers across sessions
+- **Skill System**: Automatic skill triggers for common workflows (morning boot, email triage, etc.)
 
 ## Depth-Based Specialization
 
@@ -18,56 +109,166 @@ Thoth's personality and expertise change based on your current directory:
 
 | Depth | Example | Persona |
 |-------|---------|---------|
-| 0 | `/thoth/` | Pure Chief of Staff |
-| 1 | `/thoth/work/` | Executive COS (crisp, P0-focused) |
-| 1 | `/thoth/life/` | Personal Consultant (warm, Socratic) |
-| 2 | `/thoth/work/projects/` | Project Portfolio Manager |
-| 3 | `/thoth/work/projects/x/` | Deep Expert on Project X |
-
-See [Persona Building Guide](kernel/knowledge/persona-building.md) for details.
+| 0 | `/thoth-kb/` | Pure Chief of Staff |
+| 1 | `/thoth-kb/work/` | Executive COS (crisp, P0-focused) |
+| 1 | `/thoth-kb/life/` | Personal Consultant (warm, Socratic) |
+| 2 | `/thoth-kb/work/projects/` | Project Portfolio Manager |
+| 3 | `/thoth-kb/work/projects/x/` | Deep Expert on Project X |
 
 ## Structure
 
 ```
-thoth/
-├── kernel/          # System config, memory, standards
-├── work/            # Professional life
-├── life/            # Personal life  
-├── coding/          # Technical projects
-└── src/             # OpenCode plugin source
+thoth-kb/                    # Your knowledge base
+├── kernel/                  # System config, memory, standards
+├── work/                    # Professional life
+├── life/                    # Personal life  
+├── coding/                  # Technical projects
+└── .opencode/skill/         # Custom skills
 ```
 
-## As an OpenCode Plugin
+## Skills
 
-Thoth is also an [OpenCode](https://github.com/nichochar/opencode) plugin that provides:
+Thoth includes built-in skills that trigger automatically based on your intent:
 
-- **Thoth Agent**: Primary orchestrator with depth-based specialization
-- **Sub-Agents**: Work Master, Life Master, Code Master, Coach, Sentinel, Diplomat, Chronicler
-- **Hooks**: Permission enforcement, trust tracking, context management
-- **Skills**: Morning boot, evening close, thought routing, meeting processing
+| Trigger Phrases | Skill |
+|-----------------|-------|
+| "start my day", "morning routine", "prepare me for the day" | morning-boot |
+| "end of day", "wrap up", "evening summary" | evening-close |
+| "check my email", "email triage" | mail-triage |
+| "check slack", "slack mentions" | slack-pulse |
+| "brain dump", "capture this" | thought-router |
 
-### Installation
+### Managing Skills
 
 ```bash
-# In your opencode config
+# List all available skills
+npx thoth-plugin skill list
+
+# Update skills to latest version (interactive)
+npx thoth-plugin skill update
+```
+
+The `skill update` command:
+- Compares your local skills with the latest package
+- Shows what's new, updated, or locally modified
+- Prompts for confirmation before each update
+- Offers to help you contribute back if your local version is more advanced
+
+### Skill Distribution Architecture
+
+```
+thoth-core (this repo)              thoth-kb (your knowledge base)
+├── defaults/skill/        ──────>  ├── .opencode/skill/
+│   ├── skill-generator/    copy    │   ├── skill-generator/
+│   ├── email-draft/        on      │   ├── email-draft/
+│   ├── morning-boot/       init    │   ├── morning-boot/
+│   └── ...                 or      │   └── my-local-skill/
+└── src/cli.ts              update  └── ...
+```
+
+**Key principles:**
+- **Source of truth**: `thoth-core/defaults/skill/` is canonical
+- **All skills are public**: Personalization via knowledge base files, not skill forks
+- **Distribution via npm**: Skills ship with the package
+- **Contribute back**: Local improvements can be PR'd to thoth-core
+
+### Creating Skills
+
+Skills follow a TDD-inspired process (RED-GREEN-REFACTOR):
+
+1. **RED**: Test baseline behavior without the skill (using subagent)
+2. **GREEN**: Write minimal skill that fixes the failure
+3. **REFACTOR**: Close loopholes, add to rationalization table
+
+Use the `skill-generator` skill:
+```
+/skill-generator
+```
+
+Skills are defined in `.opencode/skill/` with YAML frontmatter:
+
+```yaml
+---
+name: my-skill
+description: Use when [specific triggers]. Third person.
+triggers:
+  - phrase that activates this skill
+  - another trigger phrase
+---
+
+# My Skill
+
+**Core principle:** One sentence summary.
+
+## When to Use
+- Trigger condition 1
+- Trigger condition 2
+
+## Quick Reference
+| Task | Action |
+|------|--------|
+
+## Common Mistakes
+| Mistake | Prevention |
+|---------|------------|
+```
+
+The `triggers` field enables automatic skill invocation when the user's message matches.
+
+## Sub-Agents
+
+Thoth delegates to specialized agents:
+
+| Agent | Role |
+|-------|------|
+| Work Master | Professional life orchestrator |
+| Life Master | Personal life orchestrator |
+| Code Master | Technical projects (Sisyphus-quality code) |
+| Coach | Reflection and thinking partner |
+| Sentinel | Proactive monitoring |
+| Diplomat | Communication drafting |
+| Chronicler | Meeting and event processing |
+
+## Configuration
+
+### Global Config
+
+`~/.config/opencode/thoth-plugin.json`:
+
+```json
 {
-  "plugins": ["path/to/thoth"]
+  "enabled": true,
+  "knowledge_base": "/path/to/your/thoth-kb"
 }
 ```
 
-### Building
+### Local Override
+
+`.opencode/thoth-plugin.json` in any workspace:
+
+```json
+{
+  "knowledge_base": "./relative/path/to/kb"
+}
+```
+
+## Development
+
+### Building from Source
 
 ```bash
-npm install
-npm run build
+git clone https://github.com/Skeptomenos/thoth-core.git
+cd thoth-core
+bun install
+bun run build
 ```
 
-## Documentation
+### Development Workflow
 
-- [**Thoth User Guide**](kernel/knowledge/thoth-user-guide.md) - Comprehensive guide to capabilities, usage, and configuration
-- [Vision](kernel/knowledge/vision.md) - Chief of Staff philosophy
-- [Persona Building](kernel/knowledge/persona-building.md) - How depth-based specialization works
-- [Plugin Architecture](kernel/knowledge/plugin-architecture.md) - Technical architecture
+1. Edit source in `src/`
+2. Build: `bun run build`
+3. Test locally: Add absolute path to OpenCode config
+4. Publish: `npm version patch && npm publish`
 
 ## Philosophy
 
@@ -79,6 +280,11 @@ Thoth operates on these principles:
 4. **Cross-domain synthesis** — Can connect insights across hemispheres
 5. **Continuous learning** — Persists learnings to the knowledge base
 
+## Links
+
+- **npm**: https://www.npmjs.com/package/thoth-plugin
+- **GitHub**: https://github.com/Skeptomenos/thoth-core
+
 ## License
 
-Private repository.
+MIT

package/dist/cli.d.ts

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
 /**
- * Thoth CLI - Knowledge Base Initialization
+ * Thoth CLI - Knowledge Base Management
  *
  * Usage:
  *   npx thoth-plugin init [path]
- *   thoth init [path]
+ *   npx thoth-plugin skill update [path]
+ *   npx thoth-plugin skill list
  */
 export {};

package/dist/cli.js

@@ -2,13 +2,46 @@
 // @bun
 
 // src/cli.ts
-import { existsSync, mkdirSync, cpSync, writeFileSync, readdirSync } from "fs";
+import {
+  existsSync,
+  mkdirSync,
+  cpSync,
+  writeFileSync,
+  readFileSync,
+  readdirSync
+} from "fs";
 import { join, dirname } from "path";
 import { homedir } from "os";
 import { fileURLToPath } from "url";
+import { createInterface } from "readline";
+import { createHash } from "crypto";
 var __filename2 = fileURLToPath(import.meta.url);
 var __dirname2 = dirname(__filename2);
 var NPM_DEFAULTS_PATH = join(__dirname2, "defaults");
+function prompt(question) {
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim().toLowerCase());
+    });
+  });
+}
+function hashFile(filePath) {
+  if (!existsSync(filePath))
+    return "";
+  const content = readFileSync(filePath, "utf-8");
+  return createHash("md5").update(content).digest("hex");
+}
+function countLines(filePath) {
+  if (!existsSync(filePath))
+    return 0;
+  return readFileSync(filePath, "utf-8").split(`
+`).length;
+}
 var README_TEMPLATE = `# Thoth Knowledge Base
 
 Welcome to your personal Thoth knowledge base - your AI chief of staff for life orchestration.
@@ -182,6 +215,196 @@ Index of all knowledge in the ${hemi} hemisphere.
   console.log(`  3. Ask: "Help me onboard"
 `);
 }
+function findKbPath(startPath) {
+  const searchPaths = [
+    startPath,
+    process.cwd(),
+    join(process.cwd(), ".."),
+    join(homedir(), "thoth")
+  ].filter(Boolean);
+  for (const basePath of searchPaths) {
+    const skillPath = join(basePath, ".opencode", "skill");
+    if (existsSync(skillPath)) {
+      return basePath;
+    }
+  }
+  return null;
+}
+function compareSkills(localSkillDir) {
+  const packageSkillDir = join(NPM_DEFAULTS_PATH, "skill");
+  const results = [];
+  if (!existsSync(packageSkillDir)) {
+    console.log("Error: No skills found in package");
+    return results;
+  }
+  const packageSkills = existsSync(packageSkillDir) ? readdirSync(packageSkillDir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name) : [];
+  const localSkills = existsSync(localSkillDir) ? readdirSync(localSkillDir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name) : [];
+  const allSkills = [...new Set([...packageSkills, ...localSkills])].sort();
+  for (const skill of allSkills) {
+    const localPath = join(localSkillDir, skill);
+    const packagePath = join(packageSkillDir, skill);
+    const localExists = existsSync(localPath);
+    const packageExists = existsSync(packagePath);
+    const localFile = localExists ? existsSync(join(localPath, "SKILL.md")) ? join(localPath, "SKILL.md") : join(localPath, "skill.md") : "";
+    const packageFile = packageExists ? existsSync(join(packagePath, "SKILL.md")) ? join(packagePath, "SKILL.md") : join(packagePath, "skill.md") : "";
+    const localHash = localFile ? hashFile(localFile) : "";
+    const packageHash = packageFile ? hashFile(packageFile) : "";
+    const localLines = localFile ? countLines(localFile) : 0;
+    const packageLines = packageFile ? countLines(packageFile) : 0;
+    let status;
+    if (!localExists && packageExists) {
+      status = "package-only";
+    } else if (localExists && !packageExists) {
+      status = "local-only";
+    } else if (localHash === packageHash) {
+      status = "identical";
+    } else if (localLines > packageLines) {
+      status = "local-newer";
+    } else {
+      status = "package-newer";
+    }
+    results.push({
+      name: skill,
+      status,
+      localLines: localLines || undefined,
+      packageLines: packageLines || undefined,
+      localHash: localHash || undefined,
+      packageHash: packageHash || undefined
+    });
+  }
+  return results;
+}
+async function skillUpdate(kbPath) {
+  const basePath = findKbPath(kbPath);
+  if (!basePath) {
+    console.log(`
+Error: Could not find Thoth knowledge base.`);
+    console.log("Run this command from your knowledge base directory, or specify the path:");
+    console.log(`  npx thoth-plugin skill update ~/thoth
+`);
+    process.exit(1);
+  }
+  const localSkillDir = join(basePath, ".opencode", "skill");
+  const packageSkillDir = join(NPM_DEFAULTS_PATH, "skill");
+  console.log(`
+Comparing skills in: ${localSkillDir}
+`);
+  const comparisons = compareSkills(localSkillDir);
+  const identical = comparisons.filter((c) => c.status === "identical");
+  const packageNewer = comparisons.filter((c) => c.status === "package-newer");
+  const localNewer = comparisons.filter((c) => c.status === "local-newer");
+  const packageOnly = comparisons.filter((c) => c.status === "package-only");
+  const localOnly = comparisons.filter((c) => c.status === "local-only");
+  console.log("Skill Status Summary:");
+  console.log("\u2500".repeat(60));
+  if (identical.length > 0) {
+    console.log(`
+\u2713 Up to date (${identical.length}):`);
+    identical.forEach((s) => console.log(`  ${s.name}`));
+  }
+  if (packageNewer.length > 0) {
+    console.log(`
+\u2193 Updates available (${packageNewer.length}):`);
+    packageNewer.forEach((s) => console.log(`  ${s.name} (local: ${s.localLines} lines \u2192 package: ${s.packageLines} lines)`));
+  }
+  if (localNewer.length > 0) {
+    console.log(`
+\u2191 Local is more advanced (${localNewer.length}):`);
+    localNewer.forEach((s) => console.log(`  ${s.name} (local: ${s.localLines} lines vs package: ${s.packageLines} lines)`));
+  }
+  if (packageOnly.length > 0) {
+    console.log(`
++ New skills available (${packageOnly.length}):`);
+    packageOnly.forEach((s) => console.log(`  ${s.name}`));
+  }
+  if (localOnly.length > 0) {
+    console.log(`
+\u25CB Local only (${localOnly.length}):`);
+    localOnly.forEach((s) => console.log(`  ${s.name}`));
+  }
+  console.log(`
+` + "\u2500".repeat(60));
+  const toUpdate = [...packageNewer, ...packageOnly];
+  if (toUpdate.length === 0) {
+    console.log(`
+\u2713 All skills are up to date!
+`);
+    return;
+  }
+  console.log(`
+${toUpdate.length} skill(s) can be updated.
+`);
+  for (const skill of toUpdate) {
+    const action = skill.status === "package-only" ? "install" : "update";
+    const answer = await prompt(`${action === "install" ? "Install" : "Update"} ${skill.name}? [y/N/q] `);
+    if (answer === "q") {
+      console.log(`
+Aborted.
+`);
+      return;
+    }
+    if (answer === "y" || answer === "yes") {
+      const source = join(packageSkillDir, skill.name);
+      const target = join(localSkillDir, skill.name);
+      cpSync(source, target, { recursive: true });
+      console.log(`  \u2713 ${skill.name} ${action}d`);
+    } else {
+      console.log(`  \u25CB ${skill.name} skipped`);
+    }
+  }
+  if (localNewer.length > 0) {
+    console.log(`
+` + "\u2500".repeat(60));
+    console.log(`
+You have skills that are more advanced than the package.`);
+    console.log(`Consider contributing them back to Thoth!
+`);
+    for (const skill of localNewer) {
+      const answer = await prompt(`Would you like to contribute ${skill.name} back to Thoth? [y/N] `);
+      if (answer === "y" || answer === "yes") {
+        console.log(`
+  To contribute ${skill.name}:`);
+        console.log(`  1. Fork https://github.com/davidhelmus/thoth-core`);
+        console.log(`  2. Copy your skill to defaults/skill/${skill.name}/`);
+        console.log(`  3. Open a Pull Request
+`);
+      }
+    }
+  }
+  console.log(`
+\u2713 Done!
+`);
+}
+function skillList(kbPath) {
+  const basePath = findKbPath(kbPath);
+  if (!basePath) {
+    console.log(`
+Showing skills from package only (no knowledge base found).
+`);
+  }
+  const packageSkillDir = join(NPM_DEFAULTS_PATH, "skill");
+  const localSkillDir = basePath ? join(basePath, ".opencode", "skill") : null;
+  const packageSkills = existsSync(packageSkillDir) ? readdirSync(packageSkillDir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name) : [];
+  const localSkills = localSkillDir && existsSync(localSkillDir) ? readdirSync(localSkillDir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name) : [];
+  const allSkills = [...new Set([...packageSkills, ...localSkills])].sort();
+  console.log(`
+Available Skills:`);
+  console.log("\u2500".repeat(40));
+  for (const skill of allSkills) {
+    const inPackage = packageSkills.includes(skill);
+    const inLocal = localSkills.includes(skill);
+    let status = "";
+    if (inPackage && inLocal)
+      status = "\u2713";
+    else if (inLocal)
+      status = "\u25CB (local only)";
+    else
+      status = "+ (available)";
+    console.log(`  ${status} ${skill}`);
+  }
+  console.log(`
+`);
+}
 function showHelp() {
   console.log(`
 Thoth - Life Orchestrator for OpenCode
@@ -190,21 +413,41 @@ Usage:
   npx thoth-plugin <command> [options]
 
 Commands:
-  init [path]    Create a new knowledge base (default: ~/thoth)
+  init [path]           Create a new knowledge base (default: ~/thoth)
+  skill update [path]   Update skills from the latest package
+  skill list            List available skills
 
 Examples:
-  npx thoth-plugin init              # Create at ~/thoth
-  npx thoth-plugin init ~/my-thoth   # Create at custom path
-  npx thoth-plugin init ./kb         # Create in current directory
+  npx thoth-plugin init                # Create at ~/thoth
+  npx thoth-plugin init ~/my-thoth     # Create at custom path
+  npx thoth-plugin skill update        # Update skills in current KB
+  npx thoth-plugin skill list          # List all available skills
 
 Learn more: https://github.com/davidhelmus/thoth-core
 `);
 }
 var command = process.argv[2];
+var subcommand = process.argv[3];
 switch (command) {
   case "init":
     init(process.argv[3]);
     break;
+  case "skill":
+    switch (subcommand) {
+      case "update":
+        skillUpdate(process.argv[4]);
+        break;
+      case "list":
+        skillList(process.argv[4]);
+        break;
+      default:
+        console.log(`
+Unknown skill command: ${subcommand}`);
+        console.log(`Available: skill update, skill list
+`);
+        process.exit(1);
+    }
+    break;
   case "help":
   case "--help":
   case "-h":

package/dist/config/schema.d.ts

@@ -12,6 +12,7 @@ declare const HooksConfigSchema: z.ZodObject<{
     "temporal-awareness": z.ZodOptional<z.ZodBoolean>;
     "knowledge-persistence": z.ZodOptional<z.ZodBoolean>;
     "directory-agents-injector": z.ZodOptional<z.ZodBoolean>;
+    "frontmatter-enforcer": z.ZodOptional<z.ZodBoolean>;
     "todo-continuation": z.ZodOptional<z.ZodBoolean>;
     "session-recovery": z.ZodOptional<z.ZodBoolean>;
     "context-window-monitor": z.ZodOptional<z.ZodBoolean>;
@@ -65,6 +66,7 @@ export declare const ThothPluginConfigSchema: z.ZodObject<{
         "temporal-awareness": z.ZodOptional<z.ZodBoolean>;
         "knowledge-persistence": z.ZodOptional<z.ZodBoolean>;
         "directory-agents-injector": z.ZodOptional<z.ZodBoolean>;
+        "frontmatter-enforcer": z.ZodOptional<z.ZodBoolean>;
         "todo-continuation": z.ZodOptional<z.ZodBoolean>;
         "session-recovery": z.ZodOptional<z.ZodBoolean>;
         "context-window-monitor": z.ZodOptional<z.ZodBoolean>;