thoth-plugin 1.2.4 → 1.2.6

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

@@ -0,0 +1,217 @@
+---
+name: skill-generator
+description: Use when creating a new skill, editing an existing skill, or when asked to document a reusable process or technique
+triggers: 
+created: 2026-01-07
+updated: 2026-01-10
+---
+
+<!--
+ARCHITECTURE REFERENCE: docs/concepts/skill-architecture.md
+AUTHORING GUIDE: docs/guides/skill-authoring-guide.md
+TEMPLATES: skill-template.md (in this folder)
+-->
+
+# Skill Generator
+
+**Core principle:** No skill without baseline failure first. TDD for process documentation.
+
+**Violating the letter of this process is violating the spirit of this process.**
+
+---
+
+## The Iron Law
+
+```
+NO SKILL FILE CREATED UNTIL RED PHASE SUBAGENT COMPLETES
+```
+
+If you create SKILL.md before documenting a baseline failure, delete it. Start over. No exceptions.
+
+---
+
+## Quick Reference: The Phases
+
+| Phase | Action | Gate |
+|-------|--------|------|
+| 0 | Check exists, classify type | — |
+| 1 RED | Subagent WITHOUT skill → document failure | Must have failure |
+| 2 GREEN | Write skill in thoth-core | — |
+| 3 GREEN | Subagent WITH skill → verify fix | Must pass |
+| 4 REFACTOR | Symlink, build, quality checks | All pass |
+
+---
+
+## Phase 0: Setup
+
+**Check exists:** `ls defaults/skill/ | grep -i {name}`
+
+**Classify type:**
+- **Discipline** — Rules resisting rationalization
+- **Workflow** — Multi-step with checkpoints  
+- **Technique** — Concrete method
+- **Reference** — API docs
+
+**Determine requirements:**
+- Structured output? → Create template file
+- Needs user email? → Add context discovery
+- Needs config? → Add `config:` frontmatter
+
+---
+
+## Phase 1: RED — Baseline Test (MANDATORY)
+
+Dispatch subagent WITHOUT the skill:
+
+```
+task(
+  subagent_type="general",
+  description="Baseline test for {skill-name}",
+  prompt="""
+You are testing baseline behavior WITHOUT a skill.
+
+**Task:** {Describe the task}
+**Context:** {Relevant context}
+
+Complete the task using your best judgment. Do NOT load any skills.
+
+**Report:** What approach? What output? What assumptions?
+"""
+)
+```
+
+**Document:** What went wrong? What rationalizations? What must skill teach?
+
+**GATE:** Do not proceed without documented failure.
+
+---
+
+## Phase 2: GREEN — Write Skill
+
+### Location: thoth-core (MANDATORY)
+
+```bash
+cd /path/to/thoth-core
+mkdir -p defaults/skill/{skill-name}
+```
+
+Never create directly in thoth-kb. Symlink comes in Phase 4.
+
+### Create SKILL.md
+
+See `skill-template.md` in this folder for the complete template.
+
+**Required frontmatter:**
+```yaml
+---
+name: skill-name
+description: Use when [triggers]. No workflow summary.
+triggers:
+  - "phrase that activates"
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+---
+```
+
+**Required sections:** Core principle, When to Use, Quick Reference, Process, Common Mistakes, Red Flags, Verification Checklist
+
+**If skill produces output:** Create `skill-name-template.md` with `{{PLACEHOLDER}}` syntax.
+
+---
+
+## Phase 3: GREEN — Verify (MANDATORY)
+
+Dispatch subagent WITH the skill:
+
+```
+task(
+  subagent_type="general",
+  description="Skill-guided test for {skill-name}",
+  prompt="""
+You are testing a skill.
+
+**REQUIRED SKILL:**
+---
+{Paste skill content}
+---
+
+**Task:** {Same as baseline}
+
+Follow the skill exactly. Report: What approach? Did you follow completely?
+"""
+)
+```
+
+**Verify:** Avoided baseline mistakes? New rationalizations? Ambiguities?
+
+**GATE:** Do not proceed until agent performs correctly.
+
+---
+
+## Phase 4: REFACTOR — Deploy
+
+### Symlink to thoth-kb
+
+```bash
+cd /path/to/thoth-kb/.opencode/skill
+ln -s ../../../thoth-core/defaults/skill/{skill-name} {skill-name}
+```
+
+### Build and verify
+
+```bash
+cd /path/to/thoth-core && bun run build
+```
+
+### Quality Checklist
+
+- [ ] Baseline failure documented (Phase 1)
+- [ ] Skill-guided test passed (Phase 3)
+- [ ] Name: lowercase, hyphens only
+- [ ] Description: "Use when...", no workflow summary
+- [ ] Triggers: list of activation phrases
+- [ ] Architecture comment after frontmatter
+- [ ] Template file if structured output
+- [ ] Under 500 lines (under 200 if frequent)
+- [ ] Symlink created and verified
+- [ ] Build succeeds
+
+---
+
+## Rationalization Table
+
+| Excuse | Reality |
+|--------|---------|
+| "Too simple for structure" | Simple skills need discoverability. Follow format. |
+| "I'll add sections later" | Later never comes. Add now. |
+| "Baseline is overkill" | Baseline reveals what you'll skip. Mandatory. |
+| "I already know what will fail" | You're guessing. Run the subagent. |
+| "I'll test after writing" | That's not TDD. RED before GREEN. |
+| "Description can summarize workflow" | Claude follows descriptions instead of reading. Never summarize. |
+
+---
+
+## Red Flags - STOP
+
+- Creating SKILL.md before RED phase completes
+- Skipping baseline for ANY skill type
+- Description summarizes workflow
+- Missing `triggers:` in frontmatter
+- Hardcoded user email (use context-discovery)
+- Skill created in thoth-kb instead of thoth-core
+- Proceeding to Phase 4 without Phase 3 verification
+
+**All mean: STOP. Go back.**
+
+---
+
+## Related
+
+- `skill-template.md` — SKILL.md and output templates
+- `testing-protocol.md` — Detailed testing by skill type
+- `docs/concepts/skill-architecture.md` — Architecture reference
+- `docs/guides/skill-authoring-guide.md` — Comprehensive guide
+
+---
+
+*Skill Generator v3.1 | Condensed TDD enforcement*

package/defaults/skill/skill-generator/skill-template.md

@@ -0,0 +1,163 @@
+---
+created: 2026-01-10
+updated: 2026-01-10
+---
+
+# Skill Templates
+
+Reference templates for creating new skills. Copy and customize.
+
+---
+
+## SKILL.md Template
+
+```markdown
+---
+name: skill-name
+description: Use when [triggers]. Third person. No workflow summary.
+triggers:
+  - "trigger phrase"
+  - "another phrase"
+template: skill-name-template.md    # If produces output
+config:                             # If needs external config
+  - path: work/operations/config.md
+    as: config_name
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+---
+
+<!--
+ARCHITECTURE REFERENCE: docs/concepts/skill-architecture.md
+This skill can be invoked standalone OR as a subagent context template.
+-->
+
+# Skill Name
+
+**Core principle:** {one sentence}
+
+---
+
+## Context Requirements (If Needed)
+
+**Step 0 — Get Identity:**
+
+1. **Check if passed in context**: If `context.identity.email` exists, use it.
+2. **If not passed**: Call `skill({ name: "context-discovery" })`.
+
+**If discovery fails**: Stop and report error.
+
+---
+
+## When to Use
+
+- {symptom or trigger}
+
+**Do NOT use when:**
+- {exclusion}
+
+---
+
+## Quick Reference
+
+| Task | Command/Action |
+|------|----------------|
+| {task} | {how} |
+
+---
+
+## Process
+
+{Main content — address failures from baseline test}
+
+---
+
+## Output Format (If Template)
+
+**Template:** `skill-name-template.md`
+**Output path:** `{path}`
+
+| Placeholder | Value |
+|-------------|-------|
+| `{{DATE}}` | Today's date |
+
+---
+
+## Common Mistakes
+
+| Mistake | Prevention |
+|---------|------------|
+| {from baseline} | {fix} |
+
+---
+
+## Red Flags - STOP
+
+- {warning sign}
+
+---
+
+## Verification Checklist
+
+- [ ] {check}
+```
+
+---
+
+## Output Template Example
+
+For skills that produce structured output:
+
+```markdown
+---
+type: {output-type}
+created: {{DATE}}
+updated: {{DATE}}
+tags: [{tags}]
+summary: "{Summary} — {{DATE}}"
+---
+
+# Title — {{DATE}}
+
+**Generated:** {{TIME}}
+
+---
+
+## Section
+
+{{CONTENT}}
+
+## Data
+
+| Column A | Column B |
+|----------|----------|
+{{DATA_TABLE}}
+
+---
+
+*Generated by {skill-name} skill*
+```
+
+---
+
+## Placeholder Conventions
+
+| Pattern | Purpose | Example |
+|---------|---------|---------|
+| `{{UPPER_SNAKE}}` | Simple value | `{{DATE}}`, `{{TIME}}` |
+| `{{*_TABLE}}` | Multi-row table | `{{ACTION_ITEMS_TABLE}}` |
+| `{{*_COUNT}}` | Numeric count | `{{EMAIL_COUNT}}` |
+| `{{#if COND}}...{{/if}}` | Conditional | `{{#if COUNT > 0}}` |
+
+---
+
+## Frontmatter Quick Reference
+
+| Field | Required | Rules |
+|-------|----------|-------|
+| `name` | Yes | lowercase, hyphens, max 64 chars |
+| `description` | Yes | "Use when...", third person, no workflow summary |
+| `triggers` | Yes | Phrases that auto-invoke skill |
+| `template` | If output | Filename in skill folder |
+| `config` | If external config | `path` + `as` |
+| `created` | Yes | YYYY-MM-DD (hook-enforced) |
+| `updated` | Yes | YYYY-MM-DD (hook-enforced) |

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

@@ -1,26 +1,223 @@
 ---
 name: slack-pulse
-version: 1.0.0
-description: Lookback window in hours
+description: Scan Slack for mentions, DMs, and high-value channel activity requiring attention.
 triggers: 
-inputs: 
-- name: hours
-type: markdown
-required: false
-default: 4
-output: 
+template: slack-pulse-template.md
+config: 
+- path: work/operations/slack-map.md
+as: slack_config
 created: 2026-01-09
 updated: 2026-01-09
 ---
 
+<!--
+ARCHITECTURE REFERENCE: docs/concepts/skill-architecture.md
+This skill can be invoked standalone OR as a subagent context template.
+-->
+
 # Slack Pulse Skill
 
-You are the Real-Time Pulse Monitor for Zeus's Chief of Staff.
+You are the Real-Time Pulse Monitor. Your mission is to scan Slack for messages requiring attention and surface what matters.
+
+---
+
+## Context Requirements (EXECUTE FIRST)
+
+This skill requires the user's identity AND Slack channel configuration.
+
+**Step 0 — Get Identity:**
+
+1. **Check if passed in context**: If you received `context.identity`, use it directly.
+
+2. **If not passed, invoke context-discovery skill**: Call `skill({ name: "context-discovery" })` and use the returned context.
+
+3. **Store `kb_root`** for loading Slack config in Step 1.
+
+**If discovery fails**: Stop and report the error from context-discovery.
+
+**Step 1 — Load Slack Configuration:**
+
+Read the Slack channel map:
+```
+Read: {kb_root}/work/operations/slack-map.md
+```
+
+Parse the configuration to extract:
+- **Priority Channels**: Channel IDs to always scan (e.g., `C09QGBFUR4G`)
+- **Tier 0 DMs**: Leadership chain usernames (scan 7 days)
+- **Team DM Anchors**: Team member usernames (scan 2 days)
+- **Stakeholder DM Anchors**: Key stakeholder usernames (scan 2 days)
+- **Exclusion Patterns**: Patterns to skip (e.g., `#in-*`, `#alerts-*`)
+
+**If slack-map.md not found**: Fall back to basic mention scanning only.
+
+---
+
+## When to Use
+
+- Morning boot Slack scan
+- "Check my Slack"
+- "Any messages I need to respond to?"
+- "What's happening on Slack?"
+
+---
+
+## Tools Required
+
+| Action | Tool | Parameters |
+|--------|------|------------|
+| List channels | slack_channels_list | `channel_types: "public_channel,private_channel,im,mpim"` |
+| Get channel history | slack_conversations_history | `channel_id`, `limit: "1d"` or `"7d"` |
+| Get thread replies | slack_conversations_replies | `channel_id`, `thread_ts` |
+| Search messages | slack_conversations_search_messages | `filter_date_during: "today"` |
+| Write output | write | `work/operations/daily-log/YYYY-MM-DD/slack-pulse.md` |
+
+---
+
+## Execution Protocol
+
+### Phase 1: Identify Channels to Scan
+
+Use the parsed `slack-map.md` configuration:
+
+| Source | Config Section | Lookback |
+|--------|----------------|----------|
+| Priority Channels | `Priority Channels` table | 1 day |
+| Leadership DMs | `Tier 0: Critical DMs` table | 7 days |
+| Team DMs | `Team DM Anchors` table | 2 days |
+| Stakeholder DMs | `Stakeholder DM Anchors` table | 2 days |
+| All mentions | Search | 1 day |
+
+**For Priority Channels** (those with Channel IDs):
+```
+slack_conversations_history(
+  channel_id={channel_id},  # e.g., "C09QGBFUR4G"
+  limit="1d"
+)
+```
+
+**For DMs** (use @username):
+```
+slack_conversations_history(
+  channel_id="@{username}",  # e.g., "@vasco.taveira"
+  limit="7d"  # or "2d" for team/stakeholder
+)
+```
+
+### Phase 2: Scan for Mentions
+
+Search for messages mentioning the user:
+```
+slack_conversations_search_messages(
+  filter_date_during="today",
+  filter_users_with="@me"
+)
+```
+
+### Phase 3: Scan Priority DMs
+
+For each Tier 0/1 DM or channel:
+```
+slack_conversations_history(
+  channel_id={channel_id},
+  limit="1d"
+)
+```
+
+### Phase 4: Fetch Thread Context
+
+For items needing response, get full thread:
+```
+slack_conversations_replies(
+  channel_id={channel_id},
+  thread_ts={thread_ts}
+)
+```
+
+### Phase 5: Classify Messages
+
+For each message, determine action needed:
+
+| Classification | Criteria | Action |
+|----------------|----------|--------|
+| **RESPOND** | Direct question, request, blocking issue | Needs reply |
+| **MONITOR** | FYI, discussion to track | Watch but no action |
+| **IGNORE** | Noise, already handled | Skip |
+
+**Priority Boosters:**
+
+| Signal | Boost |
+|--------|-------|
+| From manager or skip-level | +2 |
+| From direct report | +1 |
+| Contains "urgent", "blocker", "help" | +1 |
+| Unanswered >4 hours | +1 |
+| Thread with multiple replies | +1 |
+
+---
+
+## Output Format
+
+**Template:** Read `slack-pulse-template.md` from this skill folder.
+
+**Output path:** `work/operations/daily-log/YYYY-MM-DD/slack-pulse.md`
+
+Fill the template placeholders with scan results:
+
+| Placeholder | Value |
+|-------------|-------|
+| `{{DATE}}` | Today's date (YYYY-MM-DD) |
+| `{{TIME}}` | Scan completion time (HH:MM) |
+| `{{CHANNELS_SCANNED}}` | Number of channels scanned |
+| `{{DMS_CHECKED}}` | Number of DMs checked |
+| `{{RESPOND_COUNT}}` | Items needing response |
+| `{{MONITOR_COUNT}}` | Items to monitor |
+| `{{NOISE_COUNT}}` | Items filtered as noise |
+| `{{RESPOND_ITEMS_TABLE}}` | Table rows for RESPOND items |
+| `{{MONITOR_ITEMS_TABLE}}` | Table rows for MONITOR items |
+| `{{ANCHOR_CANDIDATES_TABLE}}` | Table rows for anchor candidates |
+| `{{PRIORITY_CHANNELS_TABLE}}` | Scan summary per priority channel |
+| `{{TIER0_DMS_TABLE}}` | Scan summary per leadership DM |
+| `{{TEAM_DMS_TABLE}}` | Scan summary per team DM |
+| `{{STAKEHOLDER_DMS_TABLE}}` | Scan summary per stakeholder DM |
+| `{{IMMEDIATE_ACTIONS}}` | Bulleted list of urgent responses |
+| `{{WATCH_LIST}}` | Bulleted list of items to monitor |
+| `{{CHANNEL_HEALTH_NOTES}}` | Any observations about channel usage |
+
+**Critical:** Output MUST include `## SCAN_DATA_START` and `## SCAN_DATA_END` markers for parsing.
+
+---
+
+## Completion Checklist
+
+- [ ] Context discovery completed
+- [ ] Channels listed and prioritized
+- [ ] Mentions scanned
+- [ ] Priority DMs checked
+- [ ] Thread context fetched for RESPOND items
+- [ ] Messages classified (RESPOND/MONITOR/IGNORE)
+- [ ] Output written to `work/operations/daily-log/YYYY-MM-DD/slack-pulse.md`
+- [ ] SCAN_DATA markers included
+
+---
+
+## Error Handling
+
+| Error | Action |
+|-------|--------|
+| No Slack access | Report OAuth/token needed, stop |
+| Rate limited | Wait and retry with smaller batch |
+| Channel not found | Skip and note in output |
+
+---
 
-## Protocol Execution
+## Channel Discovery
 
-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.
+If you encounter high-signal messages from unknown channels, flag them as "Anchor Candidates" for future Tier 1 monitoring:
 
-**MANDATORY**: Ensure the output includes the `## SCAN_DATA_START` and `## SCAN_DATA_END` markers as specified in the master instructions.
+```markdown
+### Anchor Candidates
+| Channel | Reason | Recommendation |
+|---------|--------|----------------|
+| #new-project | Multiple relevant discussions | Add to Tier 1 |
+```

package/defaults/skill/slack-pulse/slack-pulse-template.md

@@ -0,0 +1,98 @@
+---
+type: operations
+hemisphere: work
+created: {{DATE}}
+updated: 2026-01-09
+tags: [slack-pulse, daily-log]
+summary: Slack Pulse — {{DATE}}
+---
+
+# Slack Pulse — {{DATE}}
+
+**Scan Time:** {{TIME}}  
+**Channels Scanned:** {{CHANNELS_SCANNED}}  
+**DMs Checked:** {{DMS_CHECKED}}
+
+---
+
+## Summary
+
+| Metric | Count |
+|--------|-------|
+| **Needs Response** | {{RESPOND_COUNT}} |
+| **Monitor/Review** | {{MONITOR_COUNT}} |
+| **Noise Filtered** | {{NOISE_COUNT}} |
+
+---
+
+## SCAN_DATA_START
+
+### RESPOND_ITEMS
+
+| Priority | Source | From | Preview | Action Needed |
+|----------|--------|------|---------|---------------|
+{{RESPOND_ITEMS_TABLE}}
+
+### MONITOR_ITEMS
+
+| Source | From | Preview | Relevance |
+|--------|------|---------|-----------|
+{{MONITOR_ITEMS_TABLE}}
+
+### ANCHOR_CANDIDATES
+
+| Channel/Topic | Reason | Recommendation |
+|---------------|--------|----------------|
+{{ANCHOR_CANDIDATES_TABLE}}
+
+## SCAN_DATA_END
+
+---
+
+## Scan Coverage
+
+### Priority Channels
+
+| Channel | Messages | Items Found |
+|---------|----------|-------------|
+{{PRIORITY_CHANNELS_TABLE}}
+
+### Leadership DMs (Tier 0)
+
+| Person | Role | Messages | Status |
+|--------|------|----------|--------|
+{{TIER0_DMS_TABLE}}
+
+### Team DMs
+
+| Person | Domain | Messages | Status |
+|--------|--------|----------|--------|
+{{TEAM_DMS_TABLE}}
+
+### Stakeholder DMs
+
+| Person | Context | Messages | Status |
+|--------|---------|----------|--------|
+{{STAKEHOLDER_DMS_TABLE}}
+
+---
+
+## Action Items
+
+### Immediate Response Needed
+
+{{IMMEDIATE_ACTIONS}}
+
+### Watch List
+
+{{WATCH_LIST}}
+
+---
+
+## Channel Health
+
+{{CHANNEL_HEALTH_NOTES}}
+
+---
+
+*Generated by slack-pulse skill at {{TIME}}*