thoth-plugin 1.2.4 → 1.2.5

package/defaults/skill/context-onboarding/SKILL.md

@@ -0,0 +1,370 @@
+---
+name: context-onboarding
+description: Use when context-discovery fails and user needs to set up their Thoth KB. Guides user through creating identity files and basic KB structure. Triggered automatically when morning-boot can't find required context.
+triggers: 
+created: 2026-01-09
+updated: 2026-01-10
+---
+
+<!--
+ARCHITECTURE REFERENCE: docs/concepts/skill-architecture.md
+This skill is typically invoked when context-discovery fails.
+-->
+
+# Context Onboarding
+
+**Core principle:** Get the user from zero to working morning-boot in under 2 minutes with the minimum viable configuration.
+
+---
+
+## When to Use
+
+- context-discovery returned `ready: false`
+- User has no thoth-kb set up
+- User asks to "set up thoth" or "initialize knowledge base"
+- First-time user trying to run a context-dependent skill
+
+**Do NOT use when:**
+- context-discovery succeeded (ready: true)
+- User just needs to add a single file (guide them directly)
+- User explicitly wants manual setup
+
+---
+
+## Quick Reference
+
+| Task | Action |
+|------|--------|
+| Determine KB location | Ask user OR use `~/.thoth-kb/` default |
+| Get work email | Ask user (required for morning-boot) |
+| Get timezone | Ask user OR detect from system |
+| Create structure | kernel/, work/, life/ directories |
+| Create config | `~/.config/opencode/thoth.json` + `.opencode/thoth.json` |
+| Create identity | `work/AGENTS.md` with MCP config table |
+
+---
+
+## Onboarding Flow
+
+### Phase 1: Assess Current State
+
+Read the discovery results (passed as context) to understand what's missing:
+
+```
+Missing KB root → Need to create KB structure
+Missing identity → Need email address
+Missing stakeholders → Optional, can add later
+```
+
+### Phase 2: Minimal Questions (Max 3)
+
+Ask ONLY what's required. Don't over-ask.
+
+**Question 1: KB Location** (if no KB found)
+```
+Where would you like your Thoth knowledge base?
+
+Options:
+1. ~/.thoth-kb/ (recommended - works from anywhere)
+2. Current directory: /path/to/cwd
+3. Custom path
+
+[Default: ~/.thoth-kb/]
+```
+
+**Question 2: Work Email** (required)
+```
+What's your work email address?
+(Used for Gmail/Calendar API calls)
+
+Example: you@company.com
+```
+
+**Question 3: Timezone** (optional, can detect)
+```
+What's your timezone?
+
+[Detected: America/Los_Angeles]
+Press Enter to accept, or type a different timezone.
+```
+
+### Phase 3: Create Files
+
+#### 3.1: Global Config (`~/.config/opencode/thoth.json`)
+
+```json
+{
+  "kb_root": "/Users/username/.thoth-kb",
+  "default_hemisphere": "work",
+  "created": "2026-01-09",
+  "version": "1.0"
+}
+```
+
+#### 3.2: Project Marker (`{kb_root}/.opencode/thoth.json`)
+
+```json
+{
+  "type": "thoth-kb",
+  "version": "1.0",
+  "hemispheres": ["kernel", "work", "life"]
+}
+```
+
+#### 3.3: Directory Structure
+
+```
+{kb_root}/
+├── .opencode/
+│   └── thoth.json         # Project marker
+├── kernel/
+│   └── AGENTS.md          # System context
+├── work/
+│   ├── AGENTS.md          # Work context with MCP config
+│   └── Stakeholders/      # Empty, to be populated
+└── life/
+    └── AGENTS.md          # Life context
+```
+
+#### 3.4: Root AGENTS.md
+
+```markdown
+---
+hemisphere: null
+depth: 0
+---
+
+# Thoth Knowledge Base
+
+Your personal knowledge management system organized into hemispheres.
+
+## Hemispheres
+
+| Hemisphere | Purpose |
+|------------|---------|
+| kernel/ | System configuration and preferences |
+| work/ | Professional life - email, calendar, projects, colleagues |
+| life/ | Personal life - health, relationships, home, finance |
+
+## Getting Started
+
+Run `morning-boot` to start your day with email triage and calendar review.
+```
+
+#### 3.5: Work AGENTS.md (Critical - Contains Identity)
+
+```markdown
+---
+hemisphere: work
+depth: 1
+---
+
+# Work Hemisphere
+
+Professional life domain.
+
+## MCP Tool Configuration (CRITICAL)
+
+| MCP Server | Required Parameter | Value |
+|------------|-------------------|-------|
+| google-workspace | user_google_email | {USER_EMAIL} |
+| drive-synapsis | user_google_email | {USER_EMAIL} |
+
+**Rules:**
+- Always include `user_google_email` parameter in Google Workspace calls
+- Never guess or hardcode email addresses
+
+## Skill Triggers
+
+| Trigger Phrases | Skill |
+|----------------|-------|
+| "start my day", "morning boot" | morning-boot |
+| "check email", "email triage" | mail-triage |
+| "check slack" | slack-pulse |
+
+## Structure
+
+| Directory | Purpose |
+|-----------|---------|
+| Stakeholders/ | Key people you work with |
+| projects/ | Active work initiatives |
+| Team/ | Direct reports (if applicable) |
+```
+
+#### 3.6: Life AGENTS.md
+
+```markdown
+---
+hemisphere: life
+depth: 1
+---
+
+# Life Hemisphere
+
+Personal life domain.
+
+## MCP Tool Configuration
+
+| MCP Server | Required Parameter | Value |
+|------------|-------------------|-------|
+| google-workspace | user_google_email | {PERSONAL_EMAIL_OR_SAME} |
+
+## Structure
+
+| Directory | Purpose |
+|-----------|---------|
+| people/ | Family, friends, relationships |
+| health/ | Fitness, medical, wellness |
+| home/ | Household, maintenance |
+| finance/ | Budget, investments |
+```
+
+#### 3.7: Kernel AGENTS.md
+
+```markdown
+---
+hemisphere: kernel
+depth: 1
+---
+
+# Kernel
+
+System configuration and Thoth self-improvement.
+
+## Purpose
+
+- Store preferences and settings
+- Track decisions and learnings
+- Configure Thoth behavior
+
+## Structure
+
+| Directory | Purpose |
+|-----------|---------|
+| config/ | User preferences |
+| memory/ | Decisions log |
+| state/ | Runtime state |
+```
+
+### Phase 4: Verify Setup
+
+After creating files:
+
+1. Read back the created `work/AGENTS.md`
+2. Verify email is correctly embedded
+3. Confirm directory structure exists
+4. Update global config with kb_root
+
+### Phase 5: Handoff
+
+```
+✅ Thoth KB created at ~/.thoth-kb/
+
+What was set up:
+- Global config: ~/.config/opencode/thoth.json
+- KB structure: kernel/, work/, life/
+- Work identity: work/AGENTS.md (email: you@company.com)
+
+Next steps:
+1. Run `morning-boot` - it should work now!
+2. First run will prompt for Google OAuth
+3. Add stakeholders to work/Stakeholders/ over time
+
+Optional:
+- Add personal email to life/AGENTS.md
+- Create project files in work/projects/
+```
+
+---
+
+## Templates
+
+### Minimal Work AGENTS.md
+
+Use this template, replacing `{EMAIL}`:
+
+```markdown
+---
+hemisphere: work
+depth: 1
+---
+
+# Work Hemisphere
+
+## MCP Tool Configuration (CRITICAL)
+
+| MCP Server | Required Parameter | Value |
+|------------|-------------------|-------|
+| google-workspace | user_google_email | {EMAIL} |
+| drive-synapsis | user_google_email | {EMAIL} |
+
+## Skill Triggers
+
+| Trigger | Skill |
+|---------|-------|
+| "morning boot" | morning-boot |
+| "check email" | mail-triage |
+```
+
+---
+
+## Common Mistakes
+
+| Mistake | Prevention |
+|---------|------------|
+| Asking too many questions | Max 3 questions. Email is the only truly required one. |
+| Creating complex structure | Minimal viable: just work/AGENTS.md with email is enough |
+| Not creating global config | Always create `~/.config/opencode/thoth.json` for cross-directory access |
+| Forgetting MCP table format | Must be exact format with headers: MCP Server, Required Parameter, Value |
+| Not verifying creation | Always read back critical files to confirm |
+
+---
+
+## Red Flags - STOP
+
+- Asking more than 3 questions
+- Creating files without confirming location with user
+- Skipping the global config file
+- Not embedding email in MCP table format
+- Leaving placeholders like `{EMAIL}` in final files
+- Not providing clear next steps
+
+---
+
+## Verification Checklist
+
+- [ ] Asked ≤3 questions
+- [ ] Created `~/.config/opencode/thoth.json` with kb_root
+- [ ] Created `.opencode/thoth.json` in KB root
+- [ ] Created work/AGENTS.md with MCP config table
+- [ ] Email is correctly embedded (not placeholder)
+- [ ] Provided clear next steps to user
+- [ ] User can now run morning-boot successfully
+
+---
+
+## Integration with Discovery
+
+After onboarding completes, discovery should be re-run:
+
+```prose
+# In calling skill (e.g., morning-boot)
+
+let context = do context-discovery
+
+if **context.ready is false**:
+  do context-onboarding
+    context: context  # Pass discovery results
+  
+  # Retry discovery
+  let context = do context-discovery
+  
+  if **still not ready**:
+    throw "Setup incomplete. Please check the error messages above."
+
+# Proceed with context
+```
+
+---
+
+*Context Onboarding v1.0 | Part of Thoth Skill System*

package/{dist/defaults/skill/_legacy/email-draft/skill.md → defaults/skill/email-draft/SKILL.md}

@@ -1,23 +1,38 @@
 ---
 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
+triggers: 
+created: 2026-01-09
+updated: 2026-01-10
 ---
 
+<!--
+ARCHITECTURE REFERENCE: docs/concepts/skill-architecture.md
+This skill can be invoked standalone OR as a subagent context template.
+-->
+
 # Email Draft
 
 **Core principle:** Gmail does not support Markdown. Always use HTML formatting with `body_format="html"`.
 
 ---
 
+## Context Requirements (EXECUTE FIRST)
+
+This skill requires the user's email address for API calls.
+
+**Step 0 — Get Identity:**
+
+1. **Check if passed in context**: If you received `context.identity.email`, use it directly.
+
+2. **If not passed, invoke context-discovery skill**: Call `skill({ name: "context-discovery" })` and use the returned `email` value.
+
+3. **Store as `EMAIL`** for use in all API calls below.
+
+**If discovery fails**: Stop and report the error from context-discovery.
+
+---
+
 ## When to Use
 
 - Drafting a reply to an email
@@ -72,31 +87,18 @@ Format with HTML:
 - `<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?
-```
+### 3. Present Final Payload for Approval
+**CRITICAL:** Show Zeus the *exact* final HTML string that will be saved.
+- If HTML conversion changes the wording, you MUST get re-approval.
+- Use a code block to show the verbatim HTML payload.
 
 ### 4. Save Draft
-
 ```python
 google-workspace_draft_gmail_message(
-  user_google_email="david.helmus@hellofresh.com",
+  user_google_email={EMAIL},
   to="recipient@example.com",
   subject="Re: Subject",
-  body="<p>HTML content</p>",
+  body="<p>Approved HTML payload</p>",
   body_format="html",           # CRITICAL
   thread_id="...",              # For replies
   in_reply_to="<message-id>"    # For replies
@@ -110,10 +112,11 @@ google-workspace_draft_gmail_message(
 | Mistake | Prevention |
 |---------|------------|
 | Using Markdown `**bold**` | Use HTML `<b>bold</b>` — Gmail renders Markdown literally |
-| Forgetting `body_format="html"` | Always include — defaults to plain text |
+| Forgetting `body_format="html"` | Always include — plain text drafts have a **known bug** where they open empty in Gmail |
 | 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` |
+| Using wrong email | Use `{EMAIL}` from Context Discovery |
+| Calling MCP tool without invoking skill | Always use this skill for email drafts — ensures correct formatting |
 
 ---
 

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

@@ -1,97 +1,129 @@
 ---
 name: evening-close
-version: 1.0.0
 description: Summarize the day, extract incomplete tasks into tomorrow's overflow, and persist daily learnings to the Knowledge Base.
 triggers: 
-output: 
-type: markdown
+template: evening-close-template.md
 created: 2026-01-09
-updated: 2026-01-09
+updated: 2026-01-10
 ---
 
+<!--
+ARCHITECTURE REFERENCE: docs/concepts/skill-architecture.md
+This skill can be invoked standalone OR as a subagent context template.
+-->
+
 # Evening Close Skill
 
-You are the **Integrity & Persistence Lead**. Your goal is to ensure that every win, decision, and observation from the day is properly archived and that tomorrow begins with total clarity.
+**Core principle:** Every win, decision, and observation must be archived. Tomorrow begins with total clarity.
+
+---
+
+## Context Requirements (EXECUTE FIRST)
+
+**Step 0 — Get Identity:**
+
+1. **Check if passed in context**: If `context.identity.kb_root` exists, use it.
+2. **If not passed**: Call `skill({ name: "context-discovery" })`.
+3. **Store `KB_ROOT`** for all file paths below.
 
-## Protocol Execution
+**If discovery fails**: Stop and report error.
+
+---
+
+## Quick Reference
+
+| Task | Path |
+|------|------|
+| Today's log | `{KB_ROOT}/work/operations/daily-log/YYYY-MM-DD/daily-log.md` |
+| Overflow file | `{KB_ROOT}/work/inbox/overflow-YYYY-MM-DD.md` |
+| Chronicle | `{KB_ROOT}/work/chronicle.md` |
+| People files | `{KB_ROOT}/work/people/{person}.md` |
+| Project files | `{KB_ROOT}/work/projects/{project}.md` |
+
+---
+
+## Protocol
 
 ### Step 1: Audit
 
-1. **Read Daily Log**: Load today's `work/logs/YYYY-MM-DD-daily-log.md`.
-2. **Verify Progress**:
-   - Compare **Top 3 Priorities** against the **Action Log**.
-   - Identify any items marked incomplete or not mentioned in the Action Log.
+1. **Read Daily Log**: `{KB_ROOT}/work/operations/daily-log/YYYY-MM-DD/daily-log.md`
+2. **Verify Progress**: Compare Top 3 Priorities against Action Log
+3. **Identify incomplete items** (not mentioned or marked incomplete)
 
 ### Step 2: Summarize
 
-1. **Generate Executive Recap**:
-   - **Completed**: Count of actions taken.
-   - **Key Wins**: 2-3 most impactful accomplishments.
-   - **Blockers Surfaced**: Any items preventing progress.
-   - **Decisions Logged**: Summary of strategic choices.
+Fill in `## Evening Summary` section of daily-log.md:
 
-2. **Update Log**: Fill in the `## Evening Summary` section of the `daily-log.md`:
-   - Completed items
-   - Blocked items
-   - Deferred items
-   - Key Wins
-   - Key Decisions
-   - Observations
+| Field | Content |
+|-------|---------|
+| Completed | Count + list |
+| Blocked | Items with blockers |
+| Deferred | Moved to tomorrow |
+| Key Wins | 2-3 most impactful |
+| Key Decisions | Strategic choices made |
+| Observations | Learnings, patterns |
 
 ### Step 3: Extract Overflow
 
-1. **Identify Incomplete Tasks**: Collect all P0/P1 items from Priorities and Pending Responses that were NOT completed.
+Create overflow file using template: `evening-close-template.md`
 
-2. **Create Overflow File**: Write to `work/inbox/overflow-YYYY-MM-DD.md`:
-   ```yaml
-   ---
-   type: overflow
-   from_date: YYYY-MM-DD
-   for_date: YYYY-MM-DD (tomorrow)
-   ---
-   
-   # Overflow Tasks
-   
-   ## From [Date]
-   
-   - [ ] [P0] Task description - Reason: [why not completed]
-   - [ ] [P1] Task description - Reason: [why not completed]
-   ```
+**Output path**: `{KB_ROOT}/work/inbox/overflow-YYYY-MM-DD.md`
 
-### Step 4: Knowledge Persistence (The Save)
+Collect all P0/P1 items NOT completed from:
+- Top 3 Priorities
+- Pending Responses
+- Action items from meetings
 
-Using **Smart Merge** (append-only, never overwrite), update the permanent Knowledge base:
+### Step 4: Knowledge Persistence
 
-1. **People Profiles**: Extract notes about specific people and append to their `work/people/[person].md` in the `## Interaction Log` section with date stamp.
+**Smart Merge** (append-only, never overwrite):
 
-2. **Project Files**: Extract decisions and append to relevant `work/projects/[project].md` in the `## Decisions` section with date stamp.
+| Source | Destination | Section |
+|--------|-------------|---------|
+| People notes | `work/people/{person}.md` | `## Interaction Log` |
+| Project decisions | `work/projects/{project}.md` | `## Decisions` |
+| Day summary | `work/chronicle.md` | `## YYYY-MM-DD` |
 
-3. **Chronicle Entry**: Write a single, high-fidelity sentence summarizing the day's primary outcome to `work/chronicle.md`:
-   ```
-   ## YYYY-MM-DD
-   [One sentence summary of day's state and primary outcome]
-   ```
+Format: `> YYYY-MM-DD: [content]`
 
 ### Step 5: Weekly Maintenance (Friday Only)
 
-1. **Check Date**: Calculate `DayOfWeek` from `<omo-env>`.
-2. **If Friday**:
-   - Run system hygiene checks
-   - Review week's chronicle entries
-   - Identify patterns or recurring blockers
-   - Suggest focus areas for next week
+If Friday:
+- Run system hygiene checks
+- Review week's chronicle entries
+- Identify patterns or recurring blockers
+- Suggest focus areas for next week
 
 ### Step 6: Finalize
 
-1. Verify all file writes were successful.
-2. Present the summary and overflow list to user in chat for final sign-off.
-3. Suggest any preparation needed for tomorrow.
+1. Verify all file writes succeeded
+2. Present summary + overflow list to user
+3. Suggest preparation for tomorrow
+
+---
+
+## Common Mistakes
+
+| Mistake | Prevention |
+|---------|------------|
+| Overwriting existing content | Use append-only Smart Merge |
+| Hallucinating outcomes | Mark unclear items as "UNCLEAR", ask user |
+| Missing incomplete tasks | Cross-check ALL priority lists |
+
+---
+
+## Red Flags - STOP
+
+- About to overwrite existing section content
+- Item status is unclear (ask user first)
+- Daily log doesn't exist (run morning-boot first)
 
 ---
 
-## Technical Constraints
+## Verification Checklist
 
-- **Smart Merge**: NEVER overwrite existing context. Only append to specific sections with a date stamp.
-- **Accuracy**: Do not hallucinate outcomes. If an item status is unclear, mark it as "UNCLEAR" and ask user.
-- **Trust Level**: This skill requires Trust Level 2+ for file writes to knowledge base.
-- **Privacy**: Summarize sensitive information, don't copy verbatim.
+- [ ] Daily log updated with Evening Summary
+- [ ] Overflow file created with all incomplete P0/P1
+- [ ] Chronicle entry added
+- [ ] People/project files updated if notes exist
+- [ ] User presented with summary

package/defaults/skill/evening-close/evening-close-template.md

@@ -0,0 +1,42 @@
+---
+created: 2026-01-10
+updated: 2026-01-10
+---
+
+# Overflow — {{DATE}}
+
+> Incomplete items from {{DATE}} requiring attention tomorrow.
+
+## P0 — Must Complete Tomorrow
+
+| Item | Source | Context |
+|------|--------|---------|
+| {{P0_ITEMS}} |
+
+## P1 — Should Complete Tomorrow
+
+| Item | Source | Context |
+|------|--------|---------|
+| {{P1_ITEMS}} |
+
+## Pending Responses
+
+| Person | Topic | Days Waiting | Original Date |
+|--------|-------|--------------|---------------|
+| {{PENDING_RESPONSES}} |
+
+## Blocked Items
+
+| Item | Blocker | Unblock Action |
+|------|---------|----------------|
+| {{BLOCKED_ITEMS}} |
+
+---
+
+## Notes for Tomorrow
+
+{{NOTES}}
+
+---
+
+*Generated by evening-close skill on {{GENERATED_AT}}*