EricGrill · github-actions · May 31, 2026
@@ -39,7 +39,7 @@ ls -la package.json pyproject.toml Cargo.toml go.mod pom.xml 2>/dev/null
 cat package.json 2>/dev/null | head -50
 
 # Check dependencies for MCP server recommendations
-cat package.json 2>/dev/null | grep -E '"(react|vue|angular|next|express|fastapi|django|prisma|supabase|stripe)"'
+cat package.json 2>/dev/null | grep -E '"(react|vue|angular|next|express|fastapi|django|prisma|supabase|convex|stripe)"'
 
 # Check for existing Claude Code config
 ls -la .claude/ CLAUDE.md 2>/dev/null
@@ -55,7 +55,7 @@ ls -la src/ app/ lib/ tests/ components/ pages/ api/ 2>/dev/null
 | Language/Framework | package.json, pyproject.toml, import patterns | Hooks, MCP servers |
 | Frontend stack | React, Vue, Angular, Next.js | Playwright MCP, frontend skills |
 | Backend stack | Express, FastAPI, Django | API documentation tools |
-| Database | Prisma, Supabase, raw SQL | Database MCP servers |
+| Database | Prisma, Supabase, Convex, raw SQL | Database / backend MCP servers |
 | External APIs | Stripe, OpenAI, AWS SDKs | context7 MCP for docs |
 | Testing | Jest, pytest, Playwright configs | Testing hooks, subagents |
 | CI/CD | GitHub Actions, CircleCI | GitHub MCP server |
@@ -75,6 +75,7 @@ See [references/mcp-servers.md](references/mcp-servers.md) for detailed patterns
 | Uses popular libraries (React, Express, etc.) | **context7** - Live documentation lookup |
 | Frontend with UI testing needs | **Playwright** - Browser automation/testing |
 | Uses Supabase | **Supabase MCP** - Direct database operations |
+| Uses Convex | **Convex MCP** - Live deployment introspection, run queries/mutations, manage env vars and logs |
 | PostgreSQL/MySQL database | **Database MCP** - Query and schema tools |
 | GitHub repository | **GitHub MCP** - Issues, PRs, actions |
 | Uses Linear for issues | **Linear MCP** - Issue management |

@@ -72,6 +72,18 @@ MCP (Model Context Protocol) servers extend Claude's capabilities by connecting
 
 **Value**: Claude can query tables, manage auth, and interact with Supabase storage directly.
 
+### Convex MCP
+**Best for**: Projects using Convex as the backend (reactive database + server functions + auth + storage + scheduling, all on one platform)
+
+| Recommend When | Examples |
+|----------------|----------|
+| Convex project detected | `convex` in deps, `convex/` directory present, `convex.json` at repo root |
+| Real-time / reactive UI | `useQuery` / `useMutation` / `useAction` from `convex/react` |
+| Mobile + Convex | `convex/react-native` in deps |
+| AI / chat / agent features on Convex | `@convex-dev/agent` in deps |
+
+**Value**: Claude can introspect the live deployment (tables, function specs, env vars, logs) and execute queries/mutations against it via tools like `tables`, `function-spec`, `data`, `run-once-query`, `logs`, `env list/set/get`. Run via `npx convex mcp start`.
+
 ### PostgreSQL MCP
 **Best for**: Direct PostgreSQL database access
 
@@ -253,6 +265,7 @@ MCP (Model Context Protocol) servers extend Claude's capabilities by connecting
 | Popular npm packages | context7 |
 | React/Vue/Next.js | Playwright MCP |
 | `@supabase/supabase-js` | Supabase MCP |
+| `convex` in deps, `convex/` directory, or `convex.json` | Convex MCP |
 | `pg` or `postgres` | PostgreSQL MCP |
 | GitHub remote | GitHub MCP |
 | `.linear` or Linear refs | Linear MCP |

@@ -1,13 +1,22 @@
 ---
 name: conversation-analyzer
-description: Use this agent when analyzing conversation transcripts to find behaviors worth preventing with hooks. Examples: <example>Context: User is running /hookify command without arguments\nuser: "/hookify"\nassistant: "I'll analyze the conversation to find behaviors you want to prevent"\n<commentary>The /hookify command without arguments triggers conversation analysis to find unwanted behaviors.</commentary></example><example>Context: User wants to create hooks from recent frustrations\nuser: "Can you look back at this conversation and help me create hooks for the mistakes you made?"\nassistant: "I'll use the conversation-analyzer agent to identify the issues and suggest hooks."\n<commentary>User explicitly asks to analyze conversation for mistakes that should be prevented.</commentary></example>
+description: Use this agent when analyzing conversation transcripts to find behaviors worth preventing with hooks. Typical triggers include the /hookify command being invoked without arguments, or the user explicitly asking to look back at the current conversation and surface mistakes that should be prevented in the future. See "When to invoke" in the agent body for worked scenarios.
 model: inherit
 color: yellow
 tools: ["Read", "Grep"]
 ---
 
 You are a conversation analysis specialist that identifies problematic behaviors in Claude Code sessions that could be prevented with hooks.
 
+## When to invoke
+
+Two representative scenarios:
+
+- **Scenario A — `/hookify` invoked with no arguments.** Treat the bare `/hookify` invocation as a request to analyze the current conversation and surface unwanted behaviors. Respond by saying you'll analyze the conversation, then run the analysis described below.
+- **Scenario B — User asks to learn from recent frustrations.** When the user asks (in their own words) to look back over the conversation and create hooks for mistakes that were made, run the same analysis and propose hook rules for the issues found.
+
+
+
 **Your Core Responsibilities:**
 1. Read and analyze user messages to find frustration signals
 2. Identify specific tool usage patterns that caused issues

@@ -6,7 +6,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/pretooluse.py",
+            "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/hooks/pretooluse.py\"",
             "timeout": 10
           }
         ]
@@ -17,7 +17,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/posttooluse.py",
+            "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/hooks/posttooluse.py\"",
             "timeout": 10
           }
         ]
@@ -28,7 +28,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/stop.py",
+            "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/hooks/stop.py\"",
             "timeout": 10
           }
         ]
@@ -39,7 +39,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/userpromptsubmit.py",
+            "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/hooks/userpromptsubmit.py\"",
             "timeout": 10
           }
         ]

@@ -24,28 +24,20 @@ Agents are autonomous subprocesses that handle complex, multi-step tasks indepen
 ```markdown
 ---
 name: agent-identifier
-description: Use this agent when [triggering conditions]. Examples:
-
-<example>
-Context: [Situation description]
-user: "[User request]"
-assistant: "[How assistant should respond and use this agent]"
-<commentary>
-[Why this agent should be triggered]
-</commentary>
-</example>
-
-<example>
-[Additional example...]
-</example>
-
+description: Use this agent when [triggering conditions]. Typical triggers include [scenario 1 in prose], [scenario 2 in prose], and [scenario 3 in prose]. See "When to invoke" in the agent body for worked scenarios.
 model: inherit
 color: blue
 tools: ["Read", "Write", "Grep"]
 ---
 
 You are [agent role description]...
 
+## When to invoke
+
+[Two to four representative scenarios written as prose, e.g.:]
+- **[Scenario name].** [What the situation looks like and what the agent should do.]
+- **[Scenario name].** [Same.]
+
 **Your Core Responsibilities:**
 1. [Responsibility 1]
 2. [Responsibility 2]
@@ -81,36 +73,24 @@ Agent identifier used for namespacing and invocation.
 
 ### description (required)
 
-Defines when Claude should trigger this agent. **This is the most critical field.**
+Defines when Claude should trigger this agent. **This is the most critical field** — it is loaded into context whenever the agent is registered, so the harness can decide when to dispatch.
 
 **Must include:**
 1. Triggering conditions ("Use this agent when...")
-2. Multiple `<example>` blocks showing usage
-3. Context, user request, and assistant response in each example
-4. `<commentary>` explaining why agent triggers
+2. A short prose summary of the typical trigger scenarios
+3. A pointer to a "When to invoke" section in the agent body for the detailed worked scenarios
 
 **Format:**
 ```
-Use this agent when [conditions]. Examples:
-
-<example>
-Context: [Scenario description]
-user: "[What user says]"
-assistant: "[How Claude should respond]"
-<commentary>
-[Why this agent is appropriate]
-</commentary>
-</example>
-
-[More examples...]
+Use this agent when [conditions]. Typical triggers include [scenario 1 in prose], [scenario 2 in prose], and [scenario 3 in prose]. See "When to invoke" in the agent body for worked scenarios.
 ```
 
 **Best practices:**
-- Include 2-4 concrete examples
-- Show proactive and reactive triggering
-- Cover different phrasings of same intent
-- Explain reasoning in commentary
+- Name 2-4 trigger scenarios in the prose summary
+- Cover both proactive (assistant invokes itself) and reactive (user requests) triggering
+- Cover different phrasings of the same intent
 - Be specific about when NOT to use the agent
+- Put detailed scenarios in the body under "When to invoke" as a bullet list of prose descriptions
 
 ### model (required)
 
@@ -231,14 +211,14 @@ Requirements:
    - Specific methodologies
    - Edge case handling
    - Output format
+   - A "When to invoke" section listing 2-4 trigger scenarios as prose bullets
 4. Create identifier (lowercase, hyphens, 3-50 chars)
-5. Write description with triggering conditions
-6. Include 2-3 <example> blocks showing when to use
+5. Write description with triggering conditions and a short prose summary of trigger scenarios
 
 Return JSON with:
 {
   "identifier": "agent-name",
-  "whenToUse": "Use this agent when... Examples: <example>...</example>",
+  "whenToUse": "Use this agent when... Typical triggers include [...]. See \"When to invoke\" in the agent body.",
   "systemPrompt": "You are..."
 }
 ```
@@ -332,13 +312,18 @@ Ensure system prompt is complete:
 ```markdown
 ---
 name: simple-agent
-description: Use this agent when... Examples: <example>...</example>
+description: Use this agent when [condition]. Typical triggers include [trigger 1] and [trigger 2]. See "When to invoke" in the agent body.
 model: inherit
 color: blue
 ---
 
 You are an agent that [does X].
 
+## When to invoke
+
+- **[Scenario A].** [Description.]
+- **[Scenario B].** [Description.]
+
 Process:
 1. [Step 1]
 2. [Step 2]
@@ -351,23 +336,24 @@ Output: [What to provide]
 | Field | Required | Format | Example |
 |-------|----------|--------|---------|
 | name | Yes | lowercase-hyphens | code-reviewer |
-| description | Yes | Text + examples | Use when... <example>... |
+| description | Yes | Prose triggers | Use when... Typical triggers include... |
 | model | Yes | inherit/sonnet/opus/haiku | inherit |
 | color | Yes | Color name | blue |
 | tools | No | Array of tool names | ["Read", "Grep"] |
 
 ### Best Practices
 
 **DO:**
-- ✅ Include 2-4 concrete examples in description
+- ✅ Name 2-4 trigger scenarios in the description (as prose)
+- ✅ Put detailed worked scenarios in a "When to invoke" body section, as prose bullets
 - ✅ Write specific triggering conditions
 - ✅ Use `inherit` for model unless specific need
 - ✅ Choose appropriate tools (least privilege)
 - ✅ Write clear, structured system prompts
 - ✅ Test agent triggering thoroughly
 
 **DON'T:**
-- ❌ Use generic descriptions without examples
+- ❌ Use generic descriptions without trigger scenarios
 - ❌ Omit triggering conditions
 - ❌ Give all agents same color
 - ❌ Grant unnecessary tool access
@@ -407,7 +393,7 @@ To create an agent for a plugin:
 3. Create `agents/agent-name.md` file
 4. Write frontmatter with all required fields
 5. Write system prompt following best practices
-6. Include 2-4 triggering examples in description
+6. Name 2-4 trigger scenarios in description (prose) and detail them in a "When to invoke" body section
 7. Validate with `scripts/validate-agent.sh`
 8. Test triggering with real scenarios
 9. Document agent in plugin README