thoth-plugin 1.1.1 → 1.2.0

package/dist/defaults/skill/email-draft/skill.md

@@ -0,0 +1,134 @@
+---
+name: email-draft
+description: Use when drafting emails, composing replies, or writing professional messages that will be sent via Gmail.
+triggers:
+  - draft email
+  - draft a reply
+  - write an email
+  - respond to email
+  - compose email
+  - reply to this email
+  - help me write an email
+  - email response
+---
+
+# Email Draft
+
+**Core principle:** Gmail does not support Markdown. Always use HTML formatting with `body_format="html"`.
+
+---
+
+## When to Use
+
+- Drafting a reply to an email
+- Composing a new email
+- Writing professional messages via Gmail
+
+**Do NOT use when:**
+- Sending Slack messages (different formatting)
+- Writing internal KB notes (Markdown is fine)
+
+---
+
+## Quick Reference
+
+| Task | Command/Action |
+|------|----------------|
+| Bold text | `<b>text</b>` |
+| Italic text | `<i>text</i>` |
+| Line break | `<br>` |
+| Paragraph | `<p>text</p>` |
+| Bullet list | `<ul><li>item</li></ul>` |
+| Numbered list | `<ol><li>item</li></ol>` |
+| Create draft | `google-workspace_draft_gmail_message` with `body_format="html"` |
+| Send email | `google-workspace_send_gmail_message` with `body_format="html"` |
+
+---
+
+## Process
+
+### 1. Gather Context
+
+**For replies:**
+- Retrieve thread with `get_gmail_thread_content(thread_id, user_google_email)`
+- Extract `thread_id` and `in_reply_to` (Message-ID header)
+- Note key points requiring response
+
+**For new emails:**
+- Confirm recipient and purpose
+- Check stakeholder file if available (`work/Stakeholders/` or `work/Team/`)
+
+### 2. Draft Content
+
+Structure:
+1. **Opening** — Acknowledge their message (replies) or state purpose (new)
+2. **Body** — Key points with `<b>headers</b>` for multiple topics
+3. **Closing** — Next steps or call to action
+4. **Sign-off** — "Best, David"
+
+Format with HTML:
+- `<b>` for section headers
+- `<ul><li>` for lists of 3+ items  
+- `<p>` for paragraph separation
+- `<i>` sparingly for emphasis
+
+### 3. Present for Approval
+
+Show full email in chat before saving:
+
+```
+**Draft ready for review:**
+
+---
+[Email content]
+---
+
+**To:** recipient
+**CC:** if applicable
+
+Shall I save as draft?
+```
+
+### 4. Save Draft
+
+```python
+google-workspace_draft_gmail_message(
+  user_google_email="david.helmus@hellofresh.com",
+  to="recipient@example.com",
+  subject="Re: Subject",
+  body="<p>HTML content</p>",
+  body_format="html",           # CRITICAL
+  thread_id="...",              # For replies
+  in_reply_to="<message-id>"    # For replies
+)
+```
+
+---
+
+## Common Mistakes
+
+| Mistake | Prevention |
+|---------|------------|
+| Using Markdown `**bold**` | Use HTML `<b>bold</b>` — Gmail renders Markdown literally |
+| Forgetting `body_format="html"` | Always include — defaults to plain text |
+| Missing `thread_id` on replies | Retrieve from original message first |
+| Sending without approval | Always draft first, ask Zeus to confirm |
+| Using personal email for work | Work context = `david.helmus@hellofresh.com` |
+
+---
+
+## Red Flags - STOP
+
+- About to use `**` or `__` for formatting — STOP, use HTML
+- About to send without Zeus approval — STOP, save as draft
+- Can't find thread_id for a reply — STOP, retrieve original thread first
+
+---
+
+## Verification Checklist
+
+- [ ] Used HTML tags, not Markdown
+- [ ] Included `body_format="html"` parameter
+- [ ] For replies: included `thread_id` and `in_reply_to`
+- [ ] Presented draft to Zeus before saving
+- [ ] Used correct email (work vs personal context)

package/dist/defaults/skill/evening-close/SKILL.md

@@ -1,6 +1,13 @@
 ---
 name: evening-close
 description: Summarize the day, extract incomplete tasks into tomorrow's overflow, and persist daily learnings to the Knowledge Base.
+triggers:
+  - end of day
+  - close out
+  - wrap up the day
+  - evening summary
+  - what did I accomplish
+  - end my day
 ---
 
 # Evening Close Skill

package/dist/defaults/skill/gardener/SKILL.md

@@ -7,7 +7,42 @@ description: Use when knowledge base health needs checking, broken links need fi
 
 You are the **Knowledge Base Gardener**. Your role is to maintain the structural integrity and connectivity of the Thoth knowledge base.
 
-**Core principle:** A healthy knowledge base has no broken links, no orphan files, and rich cross-references between related content.
+**Core principle:** A healthy knowledge base has no broken links, no orphan files, consistent frontmatter, and rich cross-references between related content.
+
+---
+
+## Frontmatter Schema Reference
+
+The canonical frontmatter schema is defined in `kernel/config/frontmatter-schemas.yaml`. Key points:
+
+### Base Fields (ALL files)
+
+| Field | Required | Auto-managed |
+|-------|----------|--------------|
+| `type` | Yes | No - agent sets |
+| `hemisphere` | Yes | Inferred from path |
+| `created` | Yes | **Hook auto-sets** |
+| `updated` | Yes | **Hook auto-updates** |
+| `tags` | No | Agent sets |
+| `summary` | No | Agent sets |
+
+### Type-Specific Fields
+
+| Type | Extra Required | Extra Optional |
+|------|----------------|----------------|
+| `person` | `relationship` | `email`, `slack` |
+| `project` | `status` | `priority`, `health`, `due`, `stakeholders` |
+| `task` | `status`, `priority` | `due`, `project` |
+| All others | (none) | (none) |
+
+### Valid Values
+
+- **hemisphere**: `kernel`, `work`, `life`, `coding`
+- **relationship**: `manager`, `peer`, `report`, `stakeholder`, `friend`, `family`
+- **status** (project): `planning`, `active`, `on-hold`, `completed`, `cancelled`
+- **status** (task): `pending`, `in-progress`, `done`, `cancelled`, `blocked`
+- **priority**: `P0`, `P1`, `P2`, `P3`
+- **health**: `green`, `yellow`, `red`
 
 ---
 

package/dist/defaults/skill/leadership-coach/SKILL.md

@@ -1,6 +1,13 @@
 ---
 name: leadership-coach
 description: IC-to-Manager coaching for new leaders. Use for leadership challenges, team operations, stakeholder management, 1:1 prep, performance conversations, or when feeling overwhelmed as a new manager.
+triggers:
+  - help me with leadership
+  - manager coaching
+  - prep for 1:1
+  - performance conversation
+  - feeling overwhelmed as manager
+  - team challenge
 ---
 
 ## Role

package/dist/defaults/skill/mail-triage/SKILL.md

@@ -1,6 +1,13 @@
 ---
 name: mail-triage
 description: Exhaustive Gmail inbox triage using the Thoth standard protocol. Drains ALL inbox items and returns an executive dashboard.
+triggers:
+  - check my email
+  - email triage
+  - process inbox
+  - what's in my inbox
+  - scan my email
+  - any important emails
 ---
 
 # Mail Triage Skill

package/dist/defaults/skill/morning-boot/SKILL.md

@@ -1,6 +1,14 @@
 ---
 name: morning-boot
 description: The master orchestrator for your morning routine. Parallelizes scans and synthesizes the Daily Log.
+triggers:
+  - start my day
+  - morning routine
+  - prepare me for the day
+  - what do I need to do today
+  - boot up
+  - daily briefing
+  - morning boot
 ---
 
 # Morning Boot Skill

package/dist/defaults/skill/post-meeting-drill/SKILL.md

@@ -1,6 +1,12 @@
 ---
 name: post-meeting-drill
 description: Deep processing of meeting notes with context hydration, entity resolution, thought-routing, urgency assessment, and knowledge persistence.
+triggers:
+  - process meeting notes
+  - meeting follow-up
+  - extract action items from meeting
+  - drill meeting
+  - post meeting
 ---
 
 # Post-Meeting Drill Skill

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

@@ -7,7 +7,7 @@ description: Use when creating a new skill, editing an existing skill, or when a
 
 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.
+**Core principle:** No skill without baseline failure first. Writing skills IS Test-Driven Development applied to process documentation.
 
 **Violating the letter of this process is violating the spirit of this process.**
 
@@ -16,20 +16,21 @@ You are creating or editing a skill for the Thoth knowledge system.
 ## The Iron Law
 
 ```
-NO SKILL FILE CREATED UNTIL PHASE 1 IS COMPLETE
+NO SKILL FILE CREATED UNTIL RED PHASE SUBAGENT COMPLETES
 ```
 
-If you create a SKILL.md before completing Phase 1, delete it. Start over.
+If you create a SKILL.md before the RED phase subagent documents a failure, delete it. Start over.
 
 **No exceptions:**
 - Don't keep it as "draft"
-- Don't "refine it later"
+- Don't "refine it later"  
 - Don't skip because "it's simple"
+- Don't skip because "it's just a technique skill"
 - Delete means delete
 
 ---
 
-## Phase 1: Research (Before Writing Anything)
+## Phase 0: Setup
 
 ### Step 1: Check if Skill Exists
 
@@ -41,39 +42,72 @@ 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 |
+| Type | Purpose |
+|------|---------|
+| **Discipline** | Rules that resist rationalization (TDD, verification) |
+| **Workflow** | Multi-step process with checkpoints |
+| **Technique** | Concrete method with steps |
+| **Reference** | API docs, syntax guides |
 
 **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?
+For discipline skills, also identify:
 - What rationalizations will agents use to skip it?
 - What pressure scenarios test compliance?
 
-### Step 4: Baseline Test (Discipline Skills Only)
+---
+
+## Phase 1: RED — Baseline Test (MANDATORY)
+
+**You MUST dispatch a subagent to attempt the task WITHOUT the skill.**
+
+### Dispatch Baseline Subagent
+
+```
+task(
+  subagent_type="general",
+  description="Baseline test for {skill-name}",
+  prompt="""
+You are testing baseline behavior WITHOUT a skill.
+
+**Task:** {Describe the task the skill will teach}
+
+**Context:** {Relevant context}
+
+**Instructions:** Complete the task using your best judgment. 
+Do NOT load any skills. Just complete the task as you normally would.
+
+**Report back:**
+1. What approach did you take?
+2. What formatting/tools/methods did you use?
+3. Show the exact output you produced.
+4. What assumptions did you make?
+"""
+)
+```
+
+### Document the Failure
 
-Run a scenario WITHOUT the skill. Document:
-- What did the agent do?
-- What rationalizations were used?
-- What was skipped?
+Before proceeding, write down:
+- **What the agent did wrong** (or suboptimally)
+- **What rationalizations were used** (verbatim if possible)
+- **What the skill must teach** to prevent this
 
-See [testing-protocol.md](testing-protocol.md) for detailed testing procedures by skill type.
+**GATE: Do not proceed to Phase 2 until you have documented at least one failure or suboptimal behavior.**
+
+If the baseline agent does everything perfectly, you may not need this skill.
 
 ---
 
-## Phase 2: Write Minimal Skill
+## Phase 2: GREEN — Write Minimal Skill
+
+Address the specific failures documented in Phase 1.
 
 ### Frontmatter (Required)
 
@@ -81,9 +115,26 @@ See [testing-protocol.md](testing-protocol.md) for detailed testing procedures b
 ---
 name: lowercase-with-hyphens
 description: Use when [specific triggers]. Third person. No workflow summary.
+triggers:
+  - phrase that activates this skill
+  - another trigger phrase
+  - variations users might say
 ---
 ```
 
+**Frontmatter Rules:**
+
+| Field | Purpose | Rules |
+|-------|---------|-------|
+| `name` | Skill identifier | lowercase, hyphens only |
+| `description` | Injected into system prompt for skill discovery | Start with "Use when...", third person, no workflow summary |
+| `triggers` | **Automatic skill invocation** | Phrases users say that should activate this skill |
+
+**Triggers are critical** — they teach Thoth when to use the skill automatically. Include:
+- Direct commands ("check my email")
+- Natural phrases ("what's in my inbox")
+- Variations ("email triage", "process inbox")
+
 **Description Rules:**
 - ✅ Start with "Use when..."
 - ✅ Describe triggers/symptoms only
@@ -155,15 +206,67 @@ Copy this template and fill in:
 
 ---
 
-## Phase 3: Quality Gate
+## Phase 3: GREEN — Verify With Skill (MANDATORY)
+
+**You MUST dispatch a subagent to attempt the same task WITH the skill.**
+
+### Dispatch Skill-Guided Subagent
+
+```
+task(
+  subagent_type="general",
+  description="Skill-guided test for {skill-name}",
+  prompt="""
+You are testing a skill.
+
+**REQUIRED SKILL — Read and follow this exactly:**
+
+---
+{Paste the full skill content here}
+---
+
+**Task:** {Same task as baseline}
+
+**Context:** {Same context as baseline}
+
+**Instructions:** Follow the skill above. Complete the task.
+
+**Report back:**
+1. What approach did you take?
+2. Did you follow the skill completely?
+3. Show the exact output you produced.
+"""
+)
+```
+
+### Verify the Fix
+
+Compare baseline vs skill-guided:
+- Did the agent avoid the mistakes from Phase 1?
+- Any NEW rationalizations that bypassed the skill?
+- Any ambiguities in the skill that allowed violations?
+
+**GATE: Do not proceed until the skill-guided agent performs correctly.**
 
-Before claiming the skill is complete, verify:
+If the agent still fails, revise the skill and re-test.
+
+---
+
+## Phase 4: REFACTOR — Quality Gate
+
+### Close Loopholes
+
+For each new rationalization found in Phase 3:
+1. Add explicit counter to Common Mistakes or Rationalization Table
+2. Add to Red Flags section
+3. Re-run Phase 3 if significant changes made
 
 ### Format Checks
 
 - [ ] Name: lowercase, hyphens only, no special chars
 - [ ] Description: starts with "Use when...", no workflow summary
 - [ ] Description: third person, under 500 chars
+- [ ] **Triggers: list of phrases that activate this skill**
 - [ ] Has "Core principle" statement
 - [ ] Has "When to Use" section
 - [ ] Has "Quick Reference" table
@@ -183,7 +286,8 @@ wc -l .opencode/skill/{name}/SKILL.md
 
 ### Functional Check
 
-- [ ] Walked through the skill as if following it
+- [ ] Baseline subagent documented failure (Phase 1)
+- [ ] Skill-guided subagent performed correctly (Phase 3)
 - [ ] All referenced tools/commands exist
 - [ ] No ambiguous instructions
 
@@ -198,20 +302,26 @@ wc -l .opencode/skill/{name}/SKILL.md
 | "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. |
+| "Baseline test is overkill" | Baseline reveals what you'll skip. Do it. Subagent is mandatory. |
+| "It's just a technique skill, doesn't need baseline" | Technique skills fail too. We learned this with email-draft. Test everything. |
+| "I already know what will fail" | You're guessing. Run the subagent. Document actual behavior. |
+| "I'll test after writing" | That's not TDD. RED comes before GREEN. Delete and start over. |
 | "Description can summarize the workflow" | Claude follows descriptions instead of reading skills. Never summarize. |
 
 ---
 
 ## Red Flags - STOP
 
-- Creating SKILL.md before completing Phase 1
+- Creating SKILL.md before RED phase subagent completes
+- Skipping baseline test for ANY skill type
+- "I already know what will fail" without running subagent
 - Description summarizes workflow ("scans X, extracts Y, outputs Z")
+- **Missing `triggers:` in frontmatter** — skill won't be auto-invoked
 - 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
+- Proceeding to Phase 4 without Phase 3 subagent verification
 
 **All of these mean: STOP. Go back to the phase you skipped.**
 
@@ -237,4 +347,16 @@ This skill is a lightweight enforcement layer. The guide has the full theory and
 
 ---
 
-*Skill Generator v1.0 | Part of Thoth Knowledge Management System*
+*Skill Generator v2.0 | Part of Thoth Knowledge Management System*
+
+---
+
+## Quick Reference: The Phases
+
+| Phase | Name | Action | Gate |
+|-------|------|--------|------|
+| 0 | Setup | Check exists, classify type, research domain | — |
+| 1 | RED | Dispatch subagent WITHOUT skill, document failure | Must have documented failure |
+| 2 | GREEN | Write minimal skill addressing failures | — |
+| 3 | GREEN | Dispatch subagent WITH skill, verify fix | Must pass |
+| 4 | REFACTOR | Close loopholes, quality checks | All checks pass |

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

@@ -1,6 +1,12 @@
 ---
 name: slack-pulse
 description: Scan Slack for mentions, high-value DMs, and informal requests using the Thoth standard protocol.
+triggers:
+  - check slack
+  - slack mentions
+  - what's happening on slack
+  - any slack messages
+  - scan slack
 ---
 
 # Slack Pulse Skill

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

@@ -1,6 +1,13 @@
 ---
 name: thought-router
 description: Quick capture tool that routes unstructured brain dumps to their correct home in the Thoth knowledge base.
+triggers:
+  - quick thought
+  - capture this
+  - brain dump
+  - remember this
+  - note this down
+  - dump
 ---
 
 # Thought Router Skill

package/dist/hooks/frontmatter-enforcer.d.ts

@@ -0,0 +1,24 @@
+export interface FrontmatterEnforcerConfig {
+    knowledgeBasePath: string;
+    enabled?: boolean;
+}
+export declare function createFrontmatterEnforcerHook(config: FrontmatterEnforcerConfig): {
+    "tool.execute.before": (input: {
+        tool: string;
+        callID?: string;
+    }, output: {
+        args: Record<string, unknown>;
+        abort?: {
+            reason: string;
+        };
+    }) => Promise<void>;
+    "tool.execute.after": (input: {
+        tool: string;
+        callID: string;
+    }, _output: {
+        title: string;
+        output: string;
+        metadata: unknown;
+    }) => Promise<void>;
+} | null;
+export type FrontmatterEnforcerHook = ReturnType<typeof createFrontmatterEnforcerHook>;

package/dist/hooks/index.d.ts

@@ -2,3 +2,6 @@ export { createPermissionEnforcerHook, type PermissionEnforcerHook, type Permiss
 export { createTrustLevelTrackerHook, type TrustLevelTrackerHook, type TrustLevelTrackerConfig, type TrustLevel, type TrustState, } from "./trust-level-tracker";
 export { createContextApertureHook, type ContextApertureHook, type ContextApertureConfig, } from "./context-aperture";
 export { createTemporalAwarenessHook, type TemporalAwarenessHook, type TemporalAwarenessConfig, } from "./temporal-awareness";
+export { createFrontmatterEnforcerHook, type FrontmatterEnforcerHook, type FrontmatterEnforcerConfig, } from "./frontmatter-enforcer";
+export { createReadConfirmationHook, type ReadConfirmationHook, type ReadConfirmationConfig, } from "./read-confirmation";
+export { createWriteConfirmationHook, type WriteConfirmationHook, type WriteConfirmationConfig, } from "./write-confirmation";

package/dist/hooks/read-confirmation.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Read Confirmation Hook
+ *
+ * After file reads, injects a confirmation message into the conversation.
+ * This creates an audit trail and prevents hallucination about what was read.
+ *
+ * Value:
+ * - Prevents "I read file X" when it wasn't actually read
+ * - Creates audit trail of file access
+ * - Helps with context management
+ */
+export interface ReadConfirmationConfig {
+    knowledgeBasePath: string;
+    enabled?: boolean;
+    /** Only confirm reads within the knowledge base (default: true) */
+    kbOnly?: boolean;
+}
+export declare function createReadConfirmationHook(config: ReadConfirmationConfig): {
+    "tool.execute.before": (input: {
+        tool: string;
+        callID: string;
+    }, output: {
+        args: Record<string, unknown>;
+    }) => Promise<void>;
+    "tool.execute.after": (input: {
+        tool: string;
+        callID: string;
+    }, output: {
+        title: string;
+        output: string;
+        metadata: unknown;
+    }) => Promise<void>;
+} | null;
+export type ReadConfirmationHook = ReturnType<typeof createReadConfirmationHook>;

package/dist/hooks/write-confirmation.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Write Confirmation Hook
+ *
+ * After file writes/edits, injects a confirmation message with reminders.
+ * This creates an audit trail and reinforces the Smart Merge protocol.
+ *
+ * Value:
+ * - Reminds about _index.md updates for new files
+ * - Creates audit trail of file modifications
+ * - Reinforces Smart Merge protocol
+ */
+export interface WriteConfirmationConfig {
+    knowledgeBasePath: string;
+    enabled?: boolean;
+    /** Only confirm writes within the knowledge base (default: true) */
+    kbOnly?: boolean;
+}
+export declare function createWriteConfirmationHook(config: WriteConfirmationConfig): {
+    "tool.execute.before": (input: {
+        tool: string;
+        callID: string;
+    }, output: {
+        args: Record<string, unknown>;
+    }) => Promise<void>;
+    "tool.execute.after": (input: {
+        tool: string;
+        callID: string;
+    }, output: {
+        title: string;
+        output: string;
+        metadata: unknown;
+    }) => Promise<void>;
+} | null;
+export type WriteConfirmationHook = ReturnType<typeof createWriteConfirmationHook>;