CLAUDE.md

1* Use the `bd` tool instead of markdown to coordinate all work and tasks.
2* NEVER commit changes unless the user explicitly asks you to.
3 
4# Using bv as an AI sidecar
5 
6bv is a fast terminal UI for Beads projects (.beads/beads.jsonl). It renders lists/details and precomputes dependency metrics (PageRank, critical path, cycles, etc.) so you instantly see blockers and execution order. For agents, it’s a graph sidecar: instead of parsing JSONL or risking hallucinated traversal, call the robot flags to get deterministic, dependency-aware outputs.
7 
8*IMPORTANT: As an agent, you must ONLY use bv with the robot flags, otherwise you'll get stuck in the interactive TUI that's intended for human usage only!*
9 
10- bv --robot-help — shows all AI-facing commands.
11- bv --robot-insights — JSON graph metrics (PageRank, betweenness, HITS, critical path, cycles) with top-N summaries for quick triage.
12- bv --robot-plan — JSON execution plan: parallel tracks, items per track, and unblocks lists showing what each item frees up.
13- bv --robot-priority — JSON priority recommendations with reasoning and confidence.
14- bv --robot-recipes — list recipes (default, actionable, blocked, etc.); apply via bv --recipe <name> to pre-filter/sort before other flags.
15- bv --robot-diff --diff-since <commit|date> — JSON diff of issue changes, new/closed items, and cycles introduced/resolved.
16 
17Use these commands instead of hand-rolling graph logic; bv already computes the hard parts so agents can act safely and quickly.
18 
19## MCP Agent Mail: coordination for multi-agent workflows
20 
21What it is
22- A mail-like layer that lets coding agents coordinate asynchronously via MCP tools and resources.
23- Provides identities, inbox/outbox, searchable threads, and advisory file reservations, with human-auditable artifacts in Git.
24 
25Why it's useful
26- Prevents agents from stepping on each other with explicit file reservations (leases) for files/globs.
27- Keeps communication out of your token budget by storing messages in a per-project archive.
28- Offers quick reads (`resource://inbox/...`, `resource://thread/...`) and macros that bundle common flows.
29 
30How to use effectively
311) Same repository
32   - Register an identity: call `ensure_project`, then `register_agent` using this repo's absolute path as `project_key`.
33   - Reserve files before you edit: `file_reservation_paths(project_key, agent_name, ["src/**"], ttl_seconds=3600, exclusive=true)` to signal intent and avoid conflict.
34   - Communicate with threads: use `send_message(..., thread_id="FEAT-123")`; check inbox with `fetch_inbox` and acknowledge with `acknowledge_message`.
35   - Read fast: `resource://inbox/{Agent}?project=<abs-path>&limit=20` or `resource://thread/{id}?project=<abs-path>&include_bodies=true`.
36   - Tip: set `AGENT_NAME` in your environment so the pre-commit guard can block commits that conflict with others' active exclusive file reservations.
37 
382) Across different repos in one project (e.g., Next.js frontend + FastAPI backend)
39   - Option A (single project bus): register both sides under the same `project_key` (shared key/path). Keep reservation patterns specific (e.g., `frontend/**` vs `backend/**`).
40   - Option B (separate projects): each repo has its own `project_key`; use `macro_contact_handshake` or `request_contact`/`respond_contact` to link agents, then message directly. Keep a shared `thread_id` (e.g., ticket key) across repos for clean summaries/audits.
41 
42Macros vs granular tools
43- Prefer macros when you want speed or are on a smaller model: `macro_start_session`, `macro_prepare_thread`, `macro_file_reservation_cycle`, `macro_contact_handshake`.
44- Use granular tools when you need control: `register_agent`, `file_reservation_paths`, `send_message`, `fetch_inbox`, `acknowledge_message`.
45 
46Common pitfalls
47- "from_agent not registered": always `register_agent` in the correct `project_key` first.
48- "FILE_RESERVATION_CONFLICT": adjust patterns, wait for expiry, or use a non-exclusive reservation when appropriate.
49- Auth errors: if JWT+JWKS is enabled, include a bearer token with a `kid` that matches server JWKS; static bearer is used only when JWT is disabled.
50 
51 
52## Integrating with Beads (dependency-aware task planning)
53 
54Beads provides a lightweight, dependency-aware issue database and a CLI (`bd`) for selecting "ready work," setting priorities, and tracking status. It complements MCP Agent Mail's messaging, audit trail, and file-reservation signals. Project: [steveyegge/beads](https://github.com/steveyegge/beads)
55 
56Recommended conventions
57- **Single source of truth**: Use **Beads** for task status/priority/dependencies; use **Agent Mail** for conversation, decisions, and attachments (audit).
58- **Shared identifiers**: Use the Beads issue id (e.g., `bd-123`) as the Mail `thread_id` and prefix message subjects with `[bd-123]`.
59- **Reservations**: When starting a `bd-###` task, call `file_reservation_paths(...)` for the affected paths; include the issue id in the `reason` and release on completion.
60 
61Typical flow (agents)
621) **Pick ready work** (Beads)
63   - `bd ready --json` → choose one item (highest priority, no blockers)
642) **Reserve edit surface** (Mail)
65   - `file_reservation_paths(project_key, agent_name, ["src/**"], ttl_seconds=3600, exclusive=true, reason="bd-123")`
663) **Announce start** (Mail)
67   - `send_message(..., thread_id="bd-123", subject="[bd-123] Start: <short title>", ack_required=true)`
684) **Work and update**
69   - Reply in-thread with progress and attach artifacts/images; keep the discussion in one thread per issue id
705) **Complete and release**
71   - `bd close bd-123 --reason "Completed"` (Beads is status authority)
72   - `release_file_reservations(project_key, agent_name, paths=["src/**"])`
73   - Final Mail reply: `[bd-123] Completed` with summary and links
74 
75Mapping cheat-sheet
76- **Mail `thread_id`** ↔ `bd-###`
77- **Mail subject**: `[bd-###] …`
78- **File reservation `reason`**: `bd-###`
79- **Commit messages (optional)**: include `bd-###` for traceability
80 
81Event mirroring (optional automation)
82- On `bd update --status blocked`, send a high-importance Mail message in thread `bd-###` describing the blocker.
83- On Mail "ACK overdue" for a critical decision, add a Beads label (e.g., `needs-ack`) or bump priority to surface it in `bd ready`.
84 
85Pitfalls to avoid
86- Don't create or manage tasks in Mail; treat Beads as the single task queue.
87- Always include `bd-###` in message `thread_id` to avoid ID drift across tools.
88 
89# 🔎 cass — Search All Your Agent History
90 
91What: cass indexes conversations from Claude Code, Codex, Cursor, Gemini, Aider, ChatGPT, and more into a unified, searchable index. Before solving a problem from scratch, check if any agent already solved something similar.
92 
93⚠️ NEVER run bare cass — it launches an interactive TUI. Always use --robot or --json.
94 
95Quick Start
96 
97# Check if index is healthy (exit 0=ok, 1=run index first)
98cass health
99 
100# Search across all agent histories
101cass search "authentication error" --robot --limit 5
102 
103# View a specific result (from search output)
104cass view /path/to/session.jsonl -n 42 --json
105 
106# Expand context around a line
107cass expand /path/to/session.jsonl -n 42 -C 3 --json
108 
109# Learn the full API
110cass capabilities --json # Feature discovery
111cass robot-docs guide # LLM-optimized docs
112 
113Why Use It
114 
115- Cross-agent knowledge: Find solutions from Codex when using Claude, or vice versa
116- Forgiving syntax: Typos and wrong flags are auto-corrected with teaching notes
117- Token-efficient: --fields minimal returns only essential data
118 
119Key Flags
120 
121| Flag | Purpose |
122|------------------|--------------------------------------------------------|
123| --robot / --json | Machine-readable JSON output (required!) |
124| --fields minimal | Reduce payload: source_path, line_number, agent only |
125| --limit N | Cap result count |
126| --agent NAME | Filter to specific agent (claude, codex, cursor, etc.) |
127| --days N | Limit to recent N days |
128 
129stdout = data only, stderr = diagnostics. Exit 0 = success.
130 
131<skills_system priority="1">
132 
133## Available Skills
134 
135<!-- SKILLS_TABLE_START -->
136<usage>
137When users ask you to perform tasks, check if any of the available skills below can help complete the task more effectively. Skills provide specialized capabilities and domain knowledge.
138 
139How to use skills:
140- Invoke: Bash("npx openskills read <skill-name>")
141- The skill content will load with detailed instructions on how to complete the task
142- Base directory provided in output for resolving bundled resources (references/, scripts/, assets/)
143 
144Usage notes:
145- Only use skills listed in <available_skills> below
146- Do not invoke a skill that is already loaded in your context
147- Each skill invocation is stateless
148</usage>
149 
150<available_skills>
151 
152<skill>
153<name>agent-builder</name>
154<description>Use when creating, improving, or troubleshooting Claude Code subagents. Expert guidance on agent design, system prompts, tool access, model selection, and best practices for building specialized AI assistants.</description>
155<location>project</location>
156</skill>
157 
158<skill>
159<name>aws-beanstalk-expert</name>
160<description>Expert knowledge for deploying, managing, and troubleshooting AWS Elastic Beanstalk applications with production best practices</description>
161<location>project</location>
162</skill>
163 
164<skill>
165<name>beanstalk-deploy</name>
166<description>"Robust deployment patterns for Elastic Beanstalk with GitHub Actions, Pulumi, and edge case handling"</description>
167<location>project</location>
168</skill>
169 
170<skill>
171<name>claude-hook-writer</name>
172<description>Expert guidance for writing secure, reliable, and performant Claude Code hooks - validates design decisions, enforces best practices, and prevents common pitfalls</description>
173<location>project</location>
174</skill>
175 
176<skill>
177<name>creating-agents-md</name>
178<description>Use when creating agents.md files - provides plain markdown format with NO frontmatter, free-form structure, and project context guidelines for AI coding assistants</description>
179<location>project</location>
180</skill>
181 
182<skill>
183<name>creating-claude-agents</name>
184<description>Use when creating or improving Claude Code agents. Expert guidance on agent file structure, frontmatter, persona definition, tool access, model selection, and validation against schema.</description>
185<location>project</location>
186</skill>
187 
188<skill>
189<name>creating-claude-commands</name>
190<description>Expert guidance for creating Claude Code slash commands with correct frontmatter, structure, and best practices</description>
191<location>project</location>
192</skill>
193 
194<skill>
195<name>creating-claude-hooks</name>
196<description>Use when creating or publishing Claude Code hooks - covers executable format, event types, JSON I/O, exit codes, security requirements, and PRPM package structure</description>
197<location>project</location>
198</skill>
199 
200<skill>
201<name>creating-continue-packages</name>
202<description>Use when creating Continue rules - provides required name field, alwaysApply semantics, glob/regex patterns, and markdown format with optional frontmatter</description>
203<location>project</location>
204</skill>
205 
206<skill>
207<name>creating-copilot-packages</name>
208<description>Use when creating GitHub Copilot instructions - provides repository-wide and path-specific formats, applyTo patterns, excludeAgent options, and natural language markdown style</description>
209<location>project</location>
210</skill>
211 
212<skill>
213<name>creating-cursor-commands</name>
214<description>Expert guidance for creating effective Cursor slash commands with best practices, format requirements, and schema validation</description>
215<location>project</location>
216</skill>
217 
218<skill>
219<name>creating-cursor-rules-skill</name>
220<description>Expert guidance for creating effective Cursor IDE rules with best practices, patterns, and examples</description>
221<location>project</location>
222</skill>
223 
224<skill>
225<name>creating-kiro-agents</name>
226<description>Use when building custom Kiro AI agents or when user asks for agent configurations - provides JSON structure, tool configuration, prompt patterns, and security best practices for specialized development assistants</description>
227<location>project</location>
228</skill>
229 
230<skill>
231<name>creating-kiro-packages</name>
232<description>Use when creating Kiro steering files or hooks - provides inclusion modes (always/fileMatch/manual), foundational files (product.md/tech.md/structure.md), and JSON hook configuration with event triggers</description>
233<location>project</location>
234</skill>
235 
236<skill>
237<name>creating-skills</name>
238<description>Use when creating new Claude Code skills or improving existing ones - ensures skills are discoverable, scannable, and effective through proper structure, CSO optimization, and real examples</description>
239<location>project</location>
240</skill>
241 
242<skill>
243<name>creating-windsurf-packages</name>
244<description>Use when creating Windsurf rules - provides plain markdown format with NO frontmatter, 12,000 character limit, and single-file structure requirements</description>
245<location>project</location>
246</skill>
247 
248<skill>
249<name>documentation-standards</name>
250<description>Standards and guidelines for organizing, structuring, and maintaining documentation in the PRPM repository - ensures consistency across user docs, development docs, and internal references</description>
251<location>project</location>
252</skill>
253 
254<skill>
255<name>elastic-beanstalk-deployment</name>
256<description>Use when deploying Node.js applications to AWS Elastic Beanstalk or troubleshooting deployment issues - provides dependency installation strategies, monorepo handling, and deployment best practices</description>
257<location>project</location>
258</skill>
259 
260<skill>
261<name>github-actions-testing</name>
262<description>Expert guidance for testing and validating GitHub Actions workflows before deployment - catches cache errors, path issues, monorepo dependencies, and service container problems that local testing misses</description>
263<location>project</location>
264</skill>
265 
266<skill>
267<name>human-writing</name>
268<description>Write content that sounds natural, conversational, and authentically human - avoiding AI-generated patterns, corporate speak, and generic phrasing</description>
269<location>project</location>
270</skill>
271 
272<skill>
273<name>integrating-stripe-webhooks</name>
274<description>Use when implementing Stripe webhook endpoints and getting 'Raw body not available' or signature verification errors - provides raw body parsing solutions and subscription period field fixes across frameworks</description>
275<location>project</location>
276</skill>
277 
278<skill>
279<name>karen-repo-reviewer</name>
280<description>Use when the user requests a repository review, code assessment, or honest evaluation of their codebase. Provides brutally honest AI-powered reviews with market-aware Karen Scores (0-100) analyzing over-engineering, completion honesty, and practical value. Available as GitHub Action or IDE tool.</description>
281<location>project</location>
282</skill>
283 
284<skill>
285<name>postgres-migrations</name>
286<description>Comprehensive guide to PostgreSQL migrations - common errors, generated columns, full-text search, indexes, idempotent migrations, and best practices for database schema changes</description>
287<location>project</location>
288</skill>
289 
290<skill>
291<name>prpm-development</name>
292<description>Use when developing PRPM (Prompt Package Manager) - comprehensive knowledge base covering architecture, format conversion, package types, collections, quality standards, testing, and deployment</description>
293<location>project</location>
294</skill>
295 
296<skill>
297<name>prpm-json-best-practices</name>
298<description>Best practices for structuring prpm.json package manifests with required fields, tags, organization, multi-package management, enhanced file format, and conversion hints</description>
299<location>project</location>
300</skill>
301 
302<skill>
303<name>pulumi-troubleshooting</name>
304<description>Comprehensive guide to troubleshooting Pulumi TypeScript errors, infrastructure issues, and best practices - covers common errors, Outputs handling, AWS Beanstalk deployment, and cost optimization</description>
305<location>project</location>
306</skill>
307 
308<skill>
309<name>self-improving</name>
310<description>Use when starting infrastructure, testing, deployment, or framework-specific tasks - automatically searches PRPM registry for relevant expertise packages and suggests installation to enhance capabilities for the current task</description>
311<location>project</location>
312</skill>
313 
314<skill>
315<name>slash-command-builder</name>
316<description>Use when creating, improving, or troubleshooting Claude Code slash commands. Expert guidance on command structure, arguments, frontmatter, tool permissions, and best practices for building effective custom commands.</description>
317<location>project</location>
318</skill>
319 
320<skill>
321<name>thoroughness</name>
322<description>Use when implementing complex multi-step tasks, fixing critical bugs, or when quality and completeness matter more than speed - ensures comprehensive implementation without shortcuts through systematic analysis, implementation, and verification phases</description>
323<location>project</location>
324</skill>
325 
326<skill>
327<name>typescript-hook-writer</name>
328<description>Expert guidance for developing Claude Code hooks in TypeScript with shared utilities, esbuild compilation, and Vitest testing - distributes compiled JS while maintaining TypeScript development experience</description>
329<location>project</location>
330</skill>
331 
332<skill>
333<name>typescript-type-safety</name>
334<description>Use when encountering TypeScript any types, type errors, or lax type checking - eliminates type holes and enforces strict type safety through proper interfaces, type guards, and module augmentation</description>
335<location>project</location>
336</skill>
337 
338</available_skills>
339<!-- SKILLS_TABLE_END -->
340 
341</skills_system>
342 
343<!-- prpm:snippet:start @agent-relay/agent-relay-snippet@1.0.2 -->
344# Agent Relay
345 
346Real-time agent-to-agent messaging. Output `->relay:` patterns to communicate.
347 
348## Sending Messages
349 
350**Always use the fenced format** for reliable message delivery:
351 
352```
353->relay:AgentName <<<
354Your message here.>>>
355```
356 
357```
358->relay:* <<<
359Broadcast to all agents.>>>
360```
361 
362**CRITICAL:** Always close multi-line messages with `>>>` on its own line!
363 
364## Communication Protocol
365 
366**ACK immediately** - When you receive a task, acknowledge it before starting work:
367 
368```
369->relay:Sender <<<
370ACK: Brief description of task received>>>
371```
372 
373Then proceed with your work. This confirms message delivery and lets the sender know you're on it.
374 
375**Report completion** - When done, send a completion message:
376 
377```
378->relay:Sender <<<
379DONE: Brief summary of what was completed>>>
380```
381 
382## Receiving Messages
383 
384Messages appear as:
385```
386Relay message from Alice [abc123]: Message content here
387```
388 
389### Channel Routing (Important!)
390 
391Messages from #general (broadcast channel) include a `[#general]` indicator:
392```
393Relay message from Alice [abc123] [#general]: Hello everyone!
394```
395 
396**When you see `[#general]`**: Reply to `*` (broadcast), NOT to the sender directly.
397 
398```
399# Correct - responds to #general channel
400->relay:* <<<
401Response to the group message.>>>
402 
403# Wrong - sends as DM to sender instead of to the channel
404->relay:Alice <<<
405Response to the group message.>>>
406```
407 
408This ensures your response appears in the same channel as the original message.
409 
410If truncated, read full message:
411```bash
412agent-relay read abc123
413```
414 
415## Spawning Agents
416 
417Spawn workers to delegate tasks:
418 
419```
420->relay:spawn WorkerName claude "task description"
421->relay:release WorkerName
422```
423 
424## Threads
425 
426Use threads to group related messages together. Thread syntax:
427 
428```
429->relay:AgentName [thread:topic-name] <<<
430Your message here.>>>
431```
432 
433**When to use threads:**
434- Working on a specific issue (e.g., `[thread:agent-relay-299]`)
435- Back-and-forth discussions with another agent
436- Code review conversations
437- Any multi-message topic you want grouped
438 
439**Examples:**
440 
441```
442->relay:Protocol [thread:auth-feature] <<<
443How should we handle token refresh?>>>
444 
445->relay:Frontend [thread:auth-feature] <<<
446Use a 401 interceptor that auto-refreshes.>>>
447 
448->relay:Reviewer [thread:pr-123] <<<
449Please review src/auth/*.ts>>>
450 
451->relay:Developer [thread:pr-123] <<<
452LGTM, approved!>>>
453```
454 
455Thread messages appear grouped in the dashboard with reply counts.
456 
457## Common Patterns
458 
459```
460->relay:Lead <<<
461ACK: Starting /api/register implementation>>>
462 
463->relay:* <<<
464STATUS: Working on auth module>>>
465 
466->relay:Lead <<<
467DONE: Auth module complete>>>
468 
469->relay:Developer <<<
470TASK: Implement /api/register>>>
471 
472->relay:Reviewer [thread:code-review-auth] <<<
473REVIEW: Please check src/auth/*.ts>>>
474 
475->relay:Architect <<<
476QUESTION: JWT or sessions?>>>
477```
478 
479## Rules
480 
481- Pattern must be at line start (whitespace OK)
482- Escape with `\->relay:` to output literally
483- Check daemon status: `agent-relay status`
484<!-- prpm:snippet:end @agent-relay/agent-relay-snippet@1.0.2 -->
485