thoth-plugin 1.1.0

package/dist/defaults/skill/skill-generator/SKILL.md

@@ -0,0 +1,240 @@
+---
+name: skill-generator
+description: Use when creating a new skill, editing an existing skill, or when asked to document a reusable process or technique
+---
+
+# Skill Generator
+
+You are creating or editing a skill for the Thoth knowledge system.
+
+**Core principle:** No skill without baseline understanding first. Writing skills IS Test-Driven Development applied to process documentation.
+
+**Violating the letter of this process is violating the spirit of this process.**
+
+---
+
+## The Iron Law
+
+```
+NO SKILL FILE CREATED UNTIL PHASE 1 IS COMPLETE
+```
+
+If you create a SKILL.md before completing Phase 1, delete it. Start over.
+
+**No exceptions:**
+- Don't keep it as "draft"
+- Don't "refine it later"
+- Don't skip because "it's simple"
+- Delete means delete
+
+---
+
+## Phase 1: Research (Before Writing Anything)
+
+### Step 1: Check if Skill Exists
+
+```bash
+ls -la .opencode/skill/ | grep -i "{skill-name}"
+```
+
+If exists: Read it first. You're editing, not creating.
+
+### Step 2: Classify Skill Type
+
+| Type | Purpose | Testing Approach |
+|------|---------|------------------|
+| **Discipline** | Rules that resist rationalization (TDD, verification) | Subagent pressure test |
+| **Workflow** | Multi-step process with checkpoints | Manual walkthrough |
+| **Technique** | Concrete method with steps | Clarity check |
+| **Reference** | API docs, syntax guides | Retrieval test |
+
+**Write down the type before proceeding.**
+
+### Step 3: Research the Domain
+
+For technique/reference skills:
+- What tools/APIs are involved?
+- What are common mistakes?
+- What does success look like?
+
+For discipline skills:
+- What behavior are we enforcing?
+- What rationalizations will agents use to skip it?
+- What pressure scenarios test compliance?
+
+### Step 4: Baseline Test (Discipline Skills Only)
+
+Run a scenario WITHOUT the skill. Document:
+- What did the agent do?
+- What rationalizations were used?
+- What was skipped?
+
+See [testing-protocol.md](testing-protocol.md) for detailed testing procedures by skill type.
+
+---
+
+## Phase 2: Write Minimal Skill
+
+### Frontmatter (Required)
+
+```yaml
+---
+name: lowercase-with-hyphens
+description: Use when [specific triggers]. Third person. No workflow summary.
+---
+```
+
+**Description Rules:**
+- ✅ Start with "Use when..."
+- ✅ Describe triggers/symptoms only
+- ✅ Third person (injected into system prompt)
+- ❌ Never summarize the workflow
+- ❌ Never use first person
+
+### Required Sections
+
+Copy this template and fill in:
+
+```markdown
+# Skill Name
+
+**Core principle:** {one sentence}
+
+---
+
+## When to Use
+
+- {symptom or trigger}
+- {symptom or trigger}
+
+**Do NOT use when:**
+- {exclusion}
+
+---
+
+## Quick Reference
+
+| Task | Command/Action |
+|------|----------------|
+| {task} | {how} |
+
+---
+
+## Process / Pattern
+
+{Main content here}
+
+---
+
+## Common Mistakes
+
+| Mistake | Prevention |
+|---------|------------|
+| {mistake} | {fix} |
+
+---
+
+## Red Flags - STOP
+
+- {warning sign}
+- {warning sign}
+
+---
+
+## Verification Checklist
+
+- [ ] {check}
+- [ ] {check}
+```
+
+### Optional Sections (Add If Needed)
+
+- **Rationalization Table** — Required for discipline skills
+- **Examples** — One excellent example beats many mediocre ones
+- **Supporting Files** — Only for heavy reference (>100 lines)
+
+---
+
+## Phase 3: Quality Gate
+
+Before claiming the skill is complete, verify:
+
+### Format Checks
+
+- [ ] Name: lowercase, hyphens only, no special chars
+- [ ] Description: starts with "Use when...", no workflow summary
+- [ ] Description: third person, under 500 chars
+- [ ] Has "Core principle" statement
+- [ ] Has "When to Use" section
+- [ ] Has "Quick Reference" table
+- [ ] Has "Common Mistakes" section
+- [ ] Has "Red Flags" section
+- [ ] Has "Verification Checklist"
+
+### Size Checks
+
+```bash
+wc -l .opencode/skill/{name}/SKILL.md
+```
+
+- [ ] SKILL.md under 500 lines
+- [ ] Frequently-loaded skills under 200 lines
+- [ ] Heavy reference in separate files
+
+### Functional Check
+
+- [ ] Walked through the skill as if following it
+- [ ] All referenced tools/commands exist
+- [ ] No ambiguous instructions
+
+---
+
+## Rationalization Table
+
+| Excuse | Reality |
+|--------|---------|
+| "This skill is simple, doesn't need structure" | Simple skills still need discoverability. Follow the format. |
+| "I'll add sections later" | Later never comes. Add them now. |
+| "The example is self-explanatory" | Examples don't replace Quick Reference tables. |
+| "It's just a reference skill" | Reference skills still need When to Use and Common Mistakes. |
+| "I already know this domain" | Your knowledge isn't in the file. Document it. |
+| "Baseline test is overkill" | Baseline reveals what you'll skip. Do it. |
+| "Description can summarize the workflow" | Claude follows descriptions instead of reading skills. Never summarize. |
+
+---
+
+## Red Flags - STOP
+
+- Creating SKILL.md before completing Phase 1
+- Description summarizes workflow ("scans X, extracts Y, outputs Z")
+- Missing "When to Use" section
+- No Quick Reference table
+- Skipping baseline test for discipline skills
+- "I'll test it later"
+- Skill over 500 lines without supporting files
+
+**All of these mean: STOP. Go back to the phase you skipped.**
+
+---
+
+## Supporting Files
+
+When to create separate files:
+
+| Content | Threshold | File |
+|---------|-----------|------|
+| Heavy reference | >100 lines | `reference.md` |
+| Detailed examples | >50 lines | `examples.md` |
+| Testing protocol | Discipline skills | `testing-protocol.md` |
+
+---
+
+## Cross-Reference
+
+**Required reading:** Read `kernel/knowledge/skill-authoring-guide.md` for comprehensive best practices.
+
+This skill is a lightweight enforcement layer. The guide has the full theory and examples.
+
+---
+
+*Skill Generator v1.0 | Part of Thoth Knowledge Management System*

package/dist/defaults/skill/skill-generator/testing-protocol.md

@@ -0,0 +1,158 @@
+# Testing Protocol for Skills
+
+When and how to test skills before deployment.
+
+---
+
+## Testing by Skill Type
+
+| Skill Type | Testing Required | Method |
+|------------|------------------|--------|
+| **Discipline** | Mandatory | Subagent pressure test |
+| **Workflow** | Recommended | Manual walkthrough |
+| **Technique** | Recommended | Clarity check |
+| **Reference** | Optional | Retrieval test |
+
+---
+
+## Discipline Skills: Subagent Pressure Test
+
+Discipline skills enforce rules that agents will try to rationalize around. Test with a fresh agent that doesn't have the skill loaded.
+
+### Step 1: Create Pressure Scenario
+
+Combine multiple pressures:
+
+| Pressure Type | Example |
+|---------------|---------|
+| **Time** | "We need this done in 5 minutes" |
+| **Sunk cost** | "I already wrote the code, just need to add tests" |
+| **Authority** | "The user said to skip testing" |
+| **Exhaustion** | "This is the 10th file, let's just finish" |
+| **Simplicity** | "This is too simple to need the full process" |
+
+### Step 2: Run Baseline (Without Skill)
+
+Dispatch a subagent with the pressure scenario but WITHOUT the skill in context.
+
+```
+Task: "Implement feature X. We're short on time, so skip anything unnecessary."
+```
+
+Document:
+- What did the agent skip?
+- What rationalizations were used (verbatim)?
+- What rules were violated?
+
+### Step 3: Run With Skill
+
+Same scenario, but WITH the skill loaded.
+
+Document:
+- Did the agent follow the rules?
+- Any new rationalizations that bypassed the skill?
+- Any ambiguities in the skill that allowed violations?
+
+### Step 4: Close Loopholes
+
+For each new rationalization found:
+1. Add explicit counter to Rationalization Table
+2. Add to Red Flags section
+3. Re-test until bulletproof
+
+---
+
+## Workflow Skills: Manual Walkthrough
+
+### Process
+
+1. Read the skill as if you've never seen it
+2. Follow each step literally
+3. Note any ambiguities or missing information
+4. Verify all referenced tools/files exist
+
+### Checklist
+
+- [ ] Each step is actionable (not vague)
+- [ ] Order of steps is logical
+- [ ] No missing prerequisites
+- [ ] Error cases are handled
+- [ ] Verification points are clear
+
+---
+
+## Technique Skills: Clarity Check
+
+### Process
+
+1. Give the skill to a fresh context (new session)
+2. Ask: "Follow this skill to do X"
+3. Observe if the agent can complete the task
+
+### Checklist
+
+- [ ] Instructions are unambiguous
+- [ ] Examples are complete and runnable
+- [ ] Common mistakes section covers real issues
+- [ ] Quick Reference is sufficient for repeat use
+
+---
+
+## Reference Skills: Retrieval Test
+
+### Process
+
+1. Ask questions that should be answered by the skill
+2. Verify the agent finds the right information
+3. Check for gaps in coverage
+
+### Example Questions
+
+- "How do I do X?" → Should find the relevant section
+- "What's the syntax for Y?" → Should find exact syntax
+- "What are the options for Z?" → Should list all options
+
+---
+
+## When to Skip Testing
+
+**Never skip for discipline skills.**
+
+For other types, you may skip if:
+- Skill is trivial (<50 lines)
+- Skill is internal documentation only
+- Time-critical AND low-risk
+
+But document why you skipped:
+```markdown
+## Testing
+
+Skipped: Technique skill under 50 lines, low complexity.
+```
+
+---
+
+## Subagent Dispatch Template
+
+For discipline skill testing:
+
+```
+Task: [Describe the scenario with pressure]
+
+Context: You are implementing [feature]. 
+Pressure: [Time/sunk cost/authority pressure]
+
+Do NOT load any skills. Just complete the task as you normally would.
+
+Report: What steps did you take? What did you skip and why?
+```
+
+After baseline, re-run with:
+
+```
+Task: [Same scenario]
+
+REQUIRED SKILL: Use skill-generator (or the skill being tested)
+
+Report: What steps did you take? Did you follow the skill completely?
+```

package/dist/defaults/skill/slack-pulse/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: slack-pulse
+description: Scan Slack for mentions, high-value DMs, and informal requests using the Thoth standard protocol.
+---
+
+# Slack Pulse Skill
+
+You are the Real-Time Pulse Monitor for Zeus's Chief of Staff.
+
+## Protocol Execution
+
+1.  **Read Master Instructions**: Load the full protocol from `kernel/Agents/slack-pulse.md`.
+2.  **Execute**: Follow the protocol exactly as defined in the master file.
+3.  **Synthesize**: Provide the pulse report and the required raw data block.
+
+**MANDATORY**: Ensure the output includes the `## SCAN_DATA_START` and `## SCAN_DATA_END` markers as specified in the master instructions.

package/dist/defaults/skill/system-init/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: system-init
+description: Onboarding wizard that interviews the user to populate the Thoth knowledge base and configure the environment.
+---
+
+# System Initialization Skill
+
+You are the **Onboarding Agent**. Your goal is to interview the user to populate Thoth's "Ground Truth" knowledge base and configure the environment.
+
+## Protocol Execution
+
+### Step 0: Welcome & Explain
+
+Introduce yourself:
+> "I'm Thoth, your AI chief of staff. Before I can help you effectively, I need to learn about you. This onboarding will take about 10-15 minutes and will set up your personal knowledge base.
+>
+> I'll ask about:
+> 1. Your work identity (role, projects, stakeholders)
+> 2. Your personal life (health, relationships, values)
+> 3. Technical setup verification
+>
+> Ready to begin?"
+
+### Step 1: Work Identity (The Chief of Staff)
+
+1. **Ask**: "Who are you professionally? (Role, Title, Company/Organization)"
+
+2. **Ask**: "What are your Top 3 Active Projects right now? For each, tell me:
+   - Project name
+   - Your role in it
+   - Current status (planning/active/wrapping up)
+   - Key deadline if any"
+
+3. **Ask**: "Who are your Top 3 Key Stakeholders? (People you report to, collaborate with closely, or manage)"
+
+4. **Action**:
+   - Create `work/identity/me.md` with professional profile
+   - Create `work/projects/{project}.md` for each project using `kernel/templates/project.md`
+   - Create `work/people/{name}.md` for each stakeholder using `kernel/templates/person.md`
+   - Update `work/MASTER.md` with project overview
+
+### Step 2: Personal Identity (The Life Coach)
+
+You are now the **Biographer**. Interview the user to build the "Life Map."
+
+**Biology (Health & Energy)**
+1. **Ask**: "How do you track your health? Do you have any current health goals? (Sleep, Exercise, Nutrition)"
+2. **Action**: Create `life/areas/health.md`
+
+**Wealth (Admin & Environment)**
+3. **Ask**: "Tell me about your life infrastructure. Living situation? Pets? What are the big 'Life Admin' buckets you manage?"
+4. **Action**: Create `life/areas/admin.md`
+
+**Community (The Village)**
+5. **Ask**: "Who are the key people in your private life? (Partner, Family, Close Friends). I'll create profiles to track important moments."
+6. **Action**: Create `life/people/{name}.md` for each person
+
+**Psychology (Values & Meaning)**
+7. **Ask**: "What are your core values? What does a 'Good Life' look like for you this year?"
+8. **Action**: Create `life/identity/values.md`
+
+### Step 3: Trust Level Setup
+
+Explain the trust system:
+> "Thoth uses a trust-based permission system. You start at Level 1 (Observer mode) where I can read but not write. As we work together successfully, I'll earn higher trust levels.
+>
+> - **Level 1**: Read-only, no external actions
+> - **Level 2**: Can write to knowledge base, access email/calendar
+> - **Level 3**: Full autonomy within your defined boundaries"
+
+**Ask**: "Would you like to start at Level 1 (safest) or Level 2 (more capable)?"
+
+**Action**: Update `kernel/state/trust.md` with initial level.
+
+### Step 4: Technical Verification
+
+1. **Check**: Can we read `kernel/THOTH.md`?
+2. **Check**: Is the Google Workspace MCP responding? (Test with `google-workspace_list_calendars`)
+3. **Check**: Is Slack MCP responding? (Test with `slack_channels_list`)
+4. **Report**: List which integrations are available.
+
+### Step 5: Finalize
+
+1. **Summarize** what was created:
+   - Number of project files
+   - Number of people profiles
+   - Life areas configured
+   - Trust level set
+
+2. **Suggest Next Steps**:
+   - "Run `skill(morning-boot)` tomorrow morning to start your first daily log"
+   - "Use `skill(thought-router)` for quick capture throughout the day"
+
+3. **Output**: "System Initialization Complete. Thoth is ready to serve."
+
+---
+
+## Technical Constraints
+
+- **Conversational**: This is an interview, not a form. Be warm and curious.
+- **Incremental Saves**: Save each section as you complete it, don't wait until the end.
+- **Templates**: Use templates from `kernel/templates/` for consistency.
+- **Trust Level**: This skill can run at Level 1 (creates files in knowledge base).

package/dist/defaults/skill/thought-router/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: thought-router
+description: Quick capture tool that routes unstructured brain dumps to their correct home in the Thoth knowledge base.
+---
+
+# Thought Router Skill
+
+You are the **Thought Router**. Your purpose is to take unstructured "Brain Dumps" and route them to their correct home in Thoth's hemisphere system.
+
+## Protocol Execution
+
+### Step 1: Atomic Decomposition
+
+Break the user's input into atomic, standalone items.
+
+**Example**:
+- *Input*: "Remind Sarah about the project deadline and I need to schedule a dentist appointment."
+- *Atomic 1*: "Remind Sarah about project deadline."
+- *Atomic 2*: "Schedule dentist appointment."
+
+### Step 2: Hemisphere Classification
+
+For each atomic item, determine the Domain:
+
+| Hemisphere | Description | Examples |
+|------------|-------------|----------|
+| **WORK** | Professional life | Projects, colleagues, stakeholders, career, meetings |
+| **LIFE** | Personal life | Health, relationships, home, finances, hobbies |
+| **CODING** | Technical work | Code tasks, bugs, features, technical decisions |
+
+### Step 3: Routing Logic
+
+**For WORK Items:**
+1. **Search**: Use `grep` for relevant keywords (e.g., person name, project name) in `work/`.
+2. **Match Found?**
+   - Yes: Append to that file (e.g., `work/people/sarah.md`) using **Smart Merge** (add to `## Open Topics` or `## Notes`).
+   - No: Append to `work/inbox/dump.md`.
+
+**For LIFE Items:**
+1. **Search**: Use `grep` for keywords in `life/`.
+2. **Match Found?**
+   - Yes: Append to that file.
+   - No: Append to `life/inbox/dump.md`.
+
+**For CODING Items:**
+1. **Search**: Use `grep` for keywords in `coding/`.
+2. **Match Found?**
+   - Yes: Append to that file.
+   - No: Append to `coding/inbox/dump.md`.
+
+### Step 4: Smart Merge Rules
+
+When appending to existing files:
+- **Never overwrite** existing content
+- **Add date stamp** to new entries: `### YYYY-MM-DD`
+- **Append to appropriate section**:
+  - People files → `## Notes` or `## Open Topics`
+  - Project files → `## Tasks` or `## Notes`
+  - Area files → `## Log`
+
+### Step 5: Execution
+
+1. Perform the writes.
+2. Output a summary table of where items went.
+
+## Example Output
+
+| Item | Hemisphere | Destination | Action |
+|:-----|:-----------|:------------|:-------|
+| "Sarah project deadline" | WORK | `work/people/sarah.md` | Appended to Open Topics |
+| "Dentist appointment" | LIFE | `life/inbox/dump.md` | Captured |
+
+---
+
+## Technical Constraints
+
+- **Trust Level**: Requires Level 2+ for file writes.
+- **Speed**: This is a quick-capture tool. Don't over-analyze - route fast.
+- **Ambiguity**: If unclear which hemisphere, ask user: "Is this work or personal?"
+- **Smart Merge**: Always append with date stamp, never overwrite.

package/dist/hooks/context-aperture.d.ts

@@ -0,0 +1,37 @@
+export interface ContextApertureConfig {
+    knowledgeBasePath: string;
+    enabled?: boolean;
+    warnOnDeepDive?: boolean;
+}
+export declare function createContextApertureHook(config: ContextApertureConfig): {
+    event: (input: {
+        event: {
+            type: string;
+        };
+    }) => Promise<void>;
+    "tool.execute.before": (input: {
+        tool: string;
+        sessionID: string;
+        callID: string;
+    }, output: {
+        args: Record<string, unknown>;
+    }) => Promise<void>;
+    "tool.execute.after": (input: {
+        tool: string;
+        sessionID: string;
+        callID: string;
+    }, output: {
+        title: string;
+        output: string;
+        metadata: unknown;
+    }) => Promise<void>;
+    getContextStats: () => {
+        circle1: number;
+        circle2: number;
+        circle3: number;
+        total: number;
+        sessionDurationMs: number;
+    };
+    generateContextWarning: () => string | null;
+} | null;
+export type ContextApertureHook = ReturnType<typeof createContextApertureHook>;

package/dist/hooks/context-aperture.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/hooks/directory-agents-injector/constants.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Constants for Directory Agents Injector
+ */
+export declare const OPENCODE_STORAGE: string;
+export declare const AGENTS_INJECTOR_STORAGE: string;
+export declare const AGENTS_FILENAME = "AGENTS.md";

package/dist/hooks/directory-agents-injector/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Directory Agents Injector Hook
+ *
+ * Injects AGENTS.md content into context when files are read.
+ * Walks up the directory tree and injects all AGENTS.md files found,
+ * from root to deepest (layered context).
+ *
+ * Ported from oh-my-opencode with Thoth-specific adaptations.
+ */
+import type { ToolExecuteInput, ToolExecuteOutput, EventInput } from "./types";
+interface DirectoryAgentsInjectorOptions {
+    /** Path to the Thoth knowledge base */
+    knowledgeBasePath: string;
+    /** Working directory for the session */
+    directory: string;
+}
+export declare function createDirectoryAgentsInjectorHook(options: DirectoryAgentsInjectorOptions): {
+    "tool.execute.after": (input: ToolExecuteInput, output: ToolExecuteOutput) => Promise<void>;
+    event: ({ event }: EventInput) => Promise<void>;
+};
+export { AGENTS_FILENAME } from "./constants";

package/dist/hooks/directory-agents-injector/storage.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Storage for Directory Agents Injector
+ *
+ * Persists which AGENTS.md files have been injected per session.
+ */
+export declare function loadInjectedPaths(sessionID: string): Set<string>;
+export declare function saveInjectedPaths(sessionID: string, paths: Set<string>): void;
+export declare function clearInjectedPaths(sessionID: string): void;

package/dist/hooks/directory-agents-injector/types.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Types for Directory Agents Injector
+ */
+export interface InjectedPathsData {
+    sessionID: string;
+    injectedPaths: string[];
+    updatedAt: number;
+}
+export interface ToolExecuteInput {
+    tool: string;
+    sessionID: string;
+    callID: string;
+}
+export interface ToolExecuteOutput {
+    title: string;
+    output: string;
+    metadata: unknown;
+}
+export interface EventInput {
+    event: {
+        type: string;
+        properties?: unknown;
+    };
+}