gkt-node 3.3.0

package/assets/.agent/skills/skill-developer/TROUBLESHOOTING.md

@@ -0,0 +1,514 @@
+# Troubleshooting - Skill Activation Issues
+
+Complete debugging guide for skill activation problems.
+
+## Table of Contents
+
+- [Skill Not Triggering](#skill-not-triggering)
+  - [UserPromptSubmit Not Suggesting](#userpromptsubmit-not-suggesting)
+  - [PreToolUse Not Blocking](#pretooluse-not-blocking)
+- [False Positives](#false-positives)
+- [Hook Not Executing](#hook-not-executing)
+- [Performance Issues](#performance-issues)
+
+---
+
+## Skill Not Triggering
+
+### UserPromptSubmit Not Suggesting
+
+**Symptoms:** Ask a question, but no skill suggestion appears in output.
+
+**Common Causes:**
+
+####  1. Keywords Don't Match
+
+**Check:**
+- Look at `promptTriggers.keywords` in skill-rules.json
+- Are the keywords actually in your prompt?
+- Remember: case-insensitive substring matching
+
+**Example:**
+```json
+"keywords": ["layout", "grid"]
+```
+- "how does the layout work?" → ✅ Matches "layout"
+- "how does the grid system work?" → ✅ Matches "grid"
+- "how do layouts work?" → ✅ Matches "layout"
+- "how does it work?" → ❌ No match
+
+**Fix:** Add more keyword variations to skill-rules.json
+
+#### 2. Intent Patterns Too Specific
+
+**Check:**
+- Look at `promptTriggers.intentPatterns`
+- Test regex at https://regex101.com/
+- May need broader patterns
+
+**Example:**
+```json
+"intentPatterns": [
+  "(create|add).*?(database.*?table)"  // Too specific
+]
+```
+- "create a database table" → ✅ Matches
+- "add new table" → ❌ Doesn't match (missing "database")
+
+**Fix:** Broaden the pattern:
+```json
+"intentPatterns": [
+  "(create|add).*?(table|database)"  // Better
+]
+```
+
+#### 3. Typo in Skill Name
+
+**Check:**
+- Skill name in SKILL.md frontmatter
+- Skill name in skill-rules.json
+- Must match exactly
+
+**Example:**
+```yaml
+# SKILL.md
+name: project-catalog-developer
+```
+```json
+// skill-rules.json
+"project-catalogue-developer": {  // ❌ Typo: catalogue vs catalog
+  ...
+}
+```
+
+**Fix:** Make names match exactly
+
+#### 4. JSON Syntax Error
+
+**Check:**
+```bash
+cat .claude/skills/skill-rules.json | jq .
+```
+
+If invalid JSON, jq will show the error.
+
+**Common errors:**
+- Trailing commas
+- Missing quotes
+- Single quotes instead of double
+- Unescaped characters in strings
+
+**Fix:** Correct JSON syntax, validate with jq
+
+#### Debug Command
+
+Test the hook manually:
+
+```bash
+echo '{"session_id":"debug","prompt":"your test prompt here"}' | \
+  npx tsx .claude/hooks/skill-activation-prompt.ts
+```
+
+Expected: Your skill should appear in the output.
+
+---
+
+### PreToolUse Not Blocking
+
+**Symptoms:** Edit a file that should trigger a guardrail, but no block occurs.
+
+**Common Causes:**
+
+#### 1. File Path Doesn't Match Patterns
+
+**Check:**
+- File path being edited
+- `fileTriggers.pathPatterns` in skill-rules.json
+- Glob pattern syntax
+
+**Example:**
+```json
+"pathPatterns": [
+  "frontend/src/**/*.tsx"
+]
+```
+- Editing: `frontend/src/components/Dashboard.tsx` → ✅ Matches
+- Editing: `frontend/tests/Dashboard.test.tsx` → ✅ Matches (add exclusion!)
+- Editing: `backend/src/app.ts` → ❌ Doesn't match
+
+**Fix:** Adjust glob patterns or add the missing path
+
+#### 2. Excluded by pathExclusions
+
+**Check:**
+- Are you editing a test file?
+- Look at `fileTriggers.pathExclusions`
+
+**Example:**
+```json
+"pathExclusions": [
+  "**/*.test.ts",
+  "**/*.spec.ts"
+]
+```
+- Editing: `services/user.test.ts` → ❌ Excluded
+- Editing: `services/user.ts` → ✅ Not excluded
+
+**Fix:** If test exclusion too broad, narrow it or remove
+
+#### 3. Content Pattern Not Found
+
+**Check:**
+- Does the file actually contain the pattern?
+- Look at `fileTriggers.contentPatterns`
+- Is the regex correct?
+
+**Example:**
+```json
+"contentPatterns": [
+  "import.*[Pp]risma"
+]
+```
+- File has: `import { PrismaService } from './prisma'` → ✅ Matches
+- File has: `import { Database } from './db'` → ❌ Doesn't match
+
+**Debug:**
+```bash
+# Check if pattern exists in file
+grep -i "prisma" path/to/file.ts
+```
+
+**Fix:** Adjust content patterns or add missing imports
+
+#### 4. Session Already Used Skill
+
+**Check session state:**
+```bash
+ls .claude/hooks/state/
+cat .claude/hooks/state/skills-used-{session-id}.json
+```
+
+**Example:**
+```json
+{
+  "skills_used": ["database-verification"],
+  "files_verified": []
+}
+```
+
+If the skill is in `skills_used`, it won't block again in this session.
+
+**Fix:** Delete the state file to reset:
+```bash
+rm .claude/hooks/state/skills-used-{session-id}.json
+```
+
+#### 5. File Marker Present
+
+**Check file for skip marker:**
+```bash
+grep "@skip-validation" path/to/file.ts
+```
+
+If found, the file is permanently skipped.
+
+**Fix:** Remove the marker if verification is needed again
+
+#### 6. Environment Variable Override
+
+**Check:**
+```bash
+echo $SKIP_DB_VERIFICATION
+echo $SKIP_SKILL_GUARDRAILS
+```
+
+If set, the skill is disabled.
+
+**Fix:** Unset the environment variable:
+```bash
+unset SKIP_DB_VERIFICATION
+```
+
+#### Debug Command
+
+Test the hook manually:
+
+```bash
+cat <<'EOF' | npx tsx .claude/hooks/skill-verification-guard.ts 2>&1
+{
+  "session_id": "debug",
+  "tool_name": "Edit",
+  "tool_input": {"file_path": "/root/git/your-project/form/src/services/user.ts"}
+}
+EOF
+echo "Exit code: $?"
+```
+
+Expected:
+- Exit code 2 + stderr message if should block
+- Exit code 0 + no output if should allow
+
+---
+
+## False Positives
+
+**Symptoms:** Skill triggers when it shouldn't.
+
+**Common Causes & Solutions:**
+
+### 1. Keywords Too Generic
+
+**Problem:**
+```json
+"keywords": ["user", "system", "create"]  // Too broad
+```
+- Triggers on: "user manual", "file system", "create directory"
+
+**Solution:** Make keywords more specific
+```json
+"keywords": [
+  "user authentication",
+  "user tracking",
+  "create feature"
+]
+```
+
+### 2. Intent Patterns Too Broad
+
+**Problem:**
+```json
+"intentPatterns": [
+  "(create)"  // Matches everything with "create"
+]
+```
+- Triggers on: "create file", "create folder", "create account"
+
+**Solution:** Add context to patterns
+```json
+"intentPatterns": [
+  "(create|add).*?(database|table|feature)"  // More specific
+]
+```
+
+**Advanced:** Use negative lookaheads to exclude
+```regex
+(create)(?!.*test).*?(feature)  // Don't match if "test" appears
+```
+
+### 3. File Paths Too Generic
+
+**Problem:**
+```json
+"pathPatterns": [
+  "form/**"  // Matches everything in form/
+]
+```
+- Triggers on: test files, config files, everything
+
+**Solution:** Use narrower patterns
+```json
+"pathPatterns": [
+  "form/src/services/**/*.ts",  // Only service files
+  "form/src/controllers/**/*.ts"
+]
+```
+
+### 4. Content Patterns Catching Unrelated Code
+
+**Problem:**
+```json
+"contentPatterns": [
+  "Prisma"  // Matches in comments, strings, etc.
+]
+```
+- Triggers on: `// Don't use Prisma here`
+- Triggers on: `const note = "Prisma is cool"`
+
+**Solution:** Make patterns more specific
+```json
+"contentPatterns": [
+  "import.*[Pp]risma",        // Only imports
+  "PrismaService\\.",         // Only actual usage
+  "prisma\\.(findMany|create)" // Specific methods
+]
+```
+
+### 5. Adjust Enforcement Level
+
+**Last resort:** If false positives are frequent:
+
+```json
+{
+  "enforcement": "block"  // Change to "suggest"
+}
+```
+
+This makes it advisory instead of blocking.
+
+---
+
+## Hook Not Executing
+
+**Symptoms:** Hook doesn't run at all - no suggestion, no block.
+
+**Common Causes:**
+
+### 1. Hook Not Registered
+
+**Check `.claude/settings.json`:**
+```bash
+cat .claude/settings.json | jq '.hooks.UserPromptSubmit'
+cat .claude/settings.json | jq '.hooks.PreToolUse'
+```
+
+Expected: Hook entries present
+
+**Fix:** Add missing hook registration:
+```json
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/skill-activation-prompt.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### 2. Bash Wrapper Not Executable
+
+**Check:**
+```bash
+ls -l .claude/hooks/*.sh
+```
+
+Expected: `-rwxr-xr-x` (executable)
+
+**Fix:**
+```bash
+chmod +x .claude/hooks/*.sh
+```
+
+### 3. Incorrect Shebang
+
+**Check:**
+```bash
+head -1 .claude/hooks/skill-activation-prompt.sh
+```
+
+Expected: `#!/bin/bash`
+
+**Fix:** Add correct shebang to first line
+
+### 4. npx/tsx Not Available
+
+**Check:**
+```bash
+npx tsx --version
+```
+
+Expected: Version number
+
+**Fix:** Install dependencies:
+```bash
+cd .claude/hooks
+npm install
+```
+
+### 5. TypeScript Compilation Error
+
+**Check:**
+```bash
+cd .claude/hooks
+npx tsc --noEmit skill-activation-prompt.ts
+```
+
+Expected: No output (no errors)
+
+**Fix:** Correct TypeScript syntax errors
+
+---
+
+## Performance Issues
+
+**Symptoms:** Hooks are slow, noticeable delay before prompt/edit.
+
+**Common Causes:**
+
+### 1. Too Many Patterns
+
+**Check:**
+- Count patterns in skill-rules.json
+- Each pattern = regex compilation + matching
+
+**Solution:** Reduce patterns
+- Combine similar patterns
+- Remove redundant patterns
+- Use more specific patterns (faster matching)
+
+### 2. Complex Regex
+
+**Problem:**
+```regex
+(create|add|modify|update|implement|build).*?(feature|endpoint|route|service|controller|component|UI|page)
+```
+- Long alternations = slow
+
+**Solution:** Simplify
+```regex
+(create|add).*?(feature|endpoint)  // Fewer alternatives
+```
+
+### 3. Too Many Files Checked
+
+**Problem:**
+```json
+"pathPatterns": [
+  "**/*.ts"  // Checks ALL TypeScript files
+]
+```
+
+**Solution:** Be more specific
+```json
+"pathPatterns": [
+  "form/src/services/**/*.ts",  // Only specific directory
+  "form/src/controllers/**/*.ts"
+]
+```
+
+### 4. Large Files
+
+Content pattern matching reads entire file - slow for large files.
+
+**Solution:**
+- Only use content patterns when necessary
+- Consider file size limits (future enhancement)
+
+### Measure Performance
+
+```bash
+# UserPromptSubmit
+time echo '{"prompt":"test"}' | npx tsx .claude/hooks/skill-activation-prompt.ts
+
+# PreToolUse
+time cat <<'EOF' | npx tsx .claude/hooks/skill-verification-guard.ts
+{"tool_name":"Edit","tool_input":{"file_path":"test.ts"}}
+EOF
+```
+
+**Target metrics:**
+- UserPromptSubmit: < 100ms
+- PreToolUse: < 200ms
+
+---
+
+**Related Files:**
+- [SKILL.md](SKILL.md) - Main skill guide
+- [HOOK_MECHANISMS.md](HOOK_MECHANISMS.md) - How hooks work
+- [SKILL_RULES_REFERENCE.md](SKILL_RULES_REFERENCE.md) - Configuration reference

package/assets/.agent/skills/slack-automation/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: slack-automation
+description: "Automate Slack messaging, channel management, search, reactions, and threads via Rube MCP (Composio). Send messages, search conversations, manage channels/users, and react to messages programmatically."
+requires:
+  mcp: [rube]
+---
+
+# Slack Automation via Rube MCP
+
+Automate Slack workspace operations including messaging, search, channel management, and reaction workflows through Composio's Slack toolkit.
+
+## Prerequisites
+
+- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
+- Active Slack connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `slack`
+- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
+
+## Setup
+
+**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
+
+
+1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
+2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `slack`
+3. If connection is not ACTIVE, follow the returned auth link to complete Slack OAuth
+4. Confirm connection status shows ACTIVE before running any workflows
+
+## Core Workflows
+
+### 1. Send Messages to Channels
+
+**When to use**: User wants to post a message to a Slack channel or DM
+
+**Tool sequence**:
+1. `SLACK_FIND_CHANNELS` - Resolve channel name to channel ID [Prerequisite]
+2. `SLACK_LIST_ALL_CHANNELS` - Fallback if FIND_CHANNELS returns empty/ambiguous results [Fallback]
+3. `SLACK_FIND_USERS` - Resolve user for DMs or @mentions [Optional]
+4. `SLACK_OPEN_DM` - Open/reuse a DM channel if messaging a user directly [Optional]
+5. `SLACK_SEND_MESSAGE` - Post the message with resolved channel ID [Required]
+6. `SLACK_UPDATES_A_SLACK_MESSAGE` - Edit the posted message if corrections needed [Optional]
+
+**Key parameters**:
+- `channel`: Channel ID or name (without '#' prefix)
+- `markdown_text`: Preferred field for formatted messages (supports headers, bold, italic, code blocks)
+- `text`: Raw text fallback (deprecated in favor of markdown_text)
+- `thread_ts`: Timestamp of parent message to reply in a thread
+- `blocks`: Block Kit layout blocks (deprecated, use markdown_text)
+
+**Pitfalls**:
+- `SLACK_FIND_CHANNELS` requires `query` param; missing it errors with "Invalid request data provided"
+- `SLACK_SEND_MESSAGE` requires valid channel plus one of markdown_text/text/blocks/attachments
+- Invalid block payloads return error=invalid_blocks (max 50 blocks)
+- Replies become top-level posts if `thread_ts` is omitted
+- Persist `response.data.channel` and `response.data.message.ts` from SEND_MESSAGE for edit/thread operations
+
+### 2. Search Messages and Conversations
+
+**When to use**: User wants to find specific messages across the workspace
+
+**Tool sequence**:
+1. `SLACK_FIND_CHANNELS` - Resolve channel for scoped search with `in:#channel` [Optional]
+2. `SLACK_FIND_USERS` - Resolve user for author filter with `from:@user` [Optional]
+3. `SLACK_SEARCH_MESSAGES` - Run keyword search across accessible conversations [Required]
+4. `SLACK_FETCH_MESSAGE_THREAD_FROM_A_CONVERSATION` - Expand threads for relevant hits [Required]
+
+**Key parameters**:
+- `query`: Search string supporting modifiers (`in:#channel`, `from:@user`, `before:YYYY-MM-DD`, `after:YYYY-MM-DD`, `has:link`, `has:file`)
+- `count`: Results per page (max 100), or total with auto_paginate=true
+- `sort`: 'score' (relevance) or 'timestamp' (chronological)
+- `sort_dir`: 'asc' or 'desc'
+
+**Pitfalls**:
+- Validation fails if `query` is missing/empty
+- `ok=true` can still mean no hits (`response.data.messages.total=0`)
+- Matches are under `response.data.messages.matches` (sometimes also `response.data_preview.messages.matches`)
+- `match.text` may be empty/truncated; key info can appear in `matches[].attachments[]`
+- Thread expansion via FETCH_MESSAGE_THREAD can truncate when `response.data.has_more=true`; paginate via `response_metadata.next_cursor`
+
+### 3. Manage Channels and Users
+
+**When to use**: User wants to list channels, users, or workspace info
+
+**Tool sequence**:
+1. `SLACK_FETCH_TEAM_INFO` - Validate connectivity and get workspace identity [Required]
+2. `SLACK_LIST_ALL_CHANNELS` - Enumerate public channels [Required]
+3. `SLACK_LIST_CONVERSATIONS` - Include private channels and DMs [Optional]
+4. `SLACK_LIST_ALL_USERS` - List workspace members [Required]
+5. `SLACK_RETRIEVE_CONVERSATION_INFORMATION` - Get detailed channel metadata [Optional]
+6. `SLACK_LIST_USER_GROUPS_FOR_TEAM_WITH_OPTIONS` - List user groups [Optional]
+
+**Key parameters**:
+- `cursor`: Pagination cursor from `response_metadata.next_cursor`
+- `limit`: Results per page (default varies; set explicitly for large workspaces)
+- `types`: Channel types filter ('public_channel', 'private_channel', 'im', 'mpim')
+
+**Pitfalls**:
+- Workspace metadata is nested under `response.data.team`, not top-level
+- `SLACK_LIST_ALL_CHANNELS` returns public channels only; use `SLACK_LIST_CONVERSATIONS` for private/IM coverage
+- `SLACK_LIST_ALL_USERS` can hit HTTP 429 rate limits; honor Retry-After header
+- Always paginate via `response_metadata.next_cursor` until empty; de-duplicate by `id`
+
+### 4. React to and Thread Messages
+
+**When to use**: User wants to add reactions or manage threaded conversations
+
+**Tool sequence**:
+1. `SLACK_SEARCH_MESSAGES` or `SLACK_FETCH_CONVERSATION_HISTORY` - Find the target message [Prerequisite]
+2. `SLACK_ADD_REACTION_TO_AN_ITEM` - Add an emoji reaction [Required]
+3. `SLACK_FETCH_ITEM_REACTIONS` - List reactions on a message [Optional]
+4. `SLACK_REMOVE_REACTION_FROM_ITEM` - Remove a reaction [Optional]
+5. `SLACK_SEND_MESSAGE` - Reply in thread using `thread_ts` [Optional]
+6. `SLACK_FETCH_MESSAGE_THREAD_FROM_A_CONVERSATION` - Read full thread [Optional]
+
+**Key parameters**:
+- `channel`: Channel ID where the message lives
+- `timestamp` / `ts`: Message timestamp (unique identifier like '1234567890.123456')
+- `name`: Emoji name without colons (e.g., 'thumbsup', 'wave::skin-tone-3')
+- `thread_ts`: Parent message timestamp for threaded replies
+
+**Pitfalls**:
+- Reactions require exact channel ID + message timestamp pair
+- Emoji names use Slack's naming convention without colons
+- `SLACK_FETCH_CONVERSATION_HISTORY` only returns main channel timeline, NOT threaded replies
+- Use `SLACK_FETCH_MESSAGE_THREAD_FROM_A_CONVERSATION` with parent's `thread_ts` to get thread replies
+
+### 5. Schedule Messages
+
+**When to use**: User wants to schedule a message for future delivery
+
+**Tool sequence**:
+1. `SLACK_FIND_CHANNELS` - Resolve channel ID [Prerequisite]
+2. `SLACK_SCHEDULE_MESSAGE` - Schedule the message with `post_at` timestamp [Required]
+
+**Key parameters**:
+- `channel`: Resolved channel ID
+- `post_at`: Unix timestamp for delivery (up to 120 days in advance)
+- `text` / `blocks`: Message content
+
+**Pitfalls**:
+- Scheduling is limited to 120 days in advance
+- `post_at` must be a Unix timestamp, not ISO 8601
+
+## Common Patterns
+
+### ID Resolution
+Always resolve display names to IDs before operations:
+- **Channel name -> Channel ID**: `SLACK_FIND_CHANNELS` with `query` param
+- **User name -> User ID**: `SLACK_FIND_USERS` with `search_query` or `email`
+- **DM channel**: `SLACK_OPEN_DM` with resolved user IDs
+
+### Pagination
+Most list endpoints use cursor-based pagination:
+- Follow `response_metadata.next_cursor` until empty
+- Set explicit `limit` values (e.g., 100-200) for reliable paging
+- De-duplicate results by `id` across pages
+
+### Message Formatting
+- Prefer `markdown_text` over `text` or `blocks` for formatted messages
+- Use `<@USER_ID>` format to mention users (not @username)
+- Use `\n` for line breaks in markdown_text
+
+## Known Pitfalls
+
+- **Channel resolution**: `SLACK_FIND_CHANNELS` can return empty results if channel is private and bot hasn't been invited
+- **Rate limits**: `SLACK_LIST_ALL_USERS` and other list endpoints can hit HTTP 429; honor Retry-After header
+- **Nested responses**: Results may be nested under `response.data.results[0].response.data` in wrapped executions
+- **Thread vs channel**: `SLACK_FETCH_CONVERSATION_HISTORY` returns main timeline only; use `SLACK_FETCH_MESSAGE_THREAD_FROM_A_CONVERSATION` for thread replies
+- **Message editing**: Requires both `channel` and original message `ts`; persist these from SEND_MESSAGE response
+- **Search delays**: Recently posted messages may not appear in search results immediately
+- **Scope limitations**: Missing OAuth scopes can cause 403 errors; check with `SLACK_GET_APP_PERMISSION_SCOPES`
+
+## Quick Reference
+
+| Task | Tool Slug | Key Params |
+|------|-----------|------------|
+| Find channels | `SLACK_FIND_CHANNELS` | `query` |
+| List all channels | `SLACK_LIST_ALL_CHANNELS` | `limit`, `cursor`, `types` |
+| Send message | `SLACK_SEND_MESSAGE` | `channel`, `markdown_text` |
+| Edit message | `SLACK_UPDATES_A_SLACK_MESSAGE` | `channel`, `ts`, `markdown_text` |
+| Search messages | `SLACK_SEARCH_MESSAGES` | `query`, `count`, `sort` |
+| Get thread | `SLACK_FETCH_MESSAGE_THREAD_FROM_A_CONVERSATION` | `channel`, `ts` |
+| Add reaction | `SLACK_ADD_REACTION_TO_AN_ITEM` | `channel`, `name`, `timestamp` |
+| Find users | `SLACK_FIND_USERS` | `search_query` or `email` |
+| List users | `SLACK_LIST_ALL_USERS` | `limit`, `cursor` |
+| Open DM | `SLACK_OPEN_DM` | user IDs |
+| Schedule message | `SLACK_SCHEDULE_MESSAGE` | `channel`, `post_at`, `text` |
+| Get channel info | `SLACK_RETRIEVE_CONVERSATION_INFORMATION` | channel ID |
+| Channel history | `SLACK_FETCH_CONVERSATION_HISTORY` | `channel`, `oldest`, `latest` |
+| Workspace info | `SLACK_FETCH_TEAM_INFO` | (none) |