@pcircle/memesh 2.6.3

package/dist/mcp/resources/ccb-complete-guide.md

@@ -0,0 +1,382 @@
+# Claude Code Buddy (CCB) - Complete Tool Guide
+
+**For LLMs**: This guide helps you actively use CCB's 17 tools. Use tools proactively based on triggers, not just when explicitly requested.
+
+## Quick Reference: When to Use Each Tool
+
+| User Says | Use Tool | Why |
+|-----------|----------|-----|
+| "remember when we..." | `buddy-remember` | Search project memory |
+| "what did we decide..." | `buddy-remember` | Recall past decisions |
+| "why did we choose..." | `buddy-remember` | Find architecture choices |
+| "do this task..." | `buddy-do` | Execute with smart routing |
+| "implement X..." | `buddy-do` | Task execution |
+| "generate tests..." | `generate-tests` | Create test cases |
+| "save this API key..." | `buddy-secret-store` | Store secrets securely |
+| "get my token..." | `buddy-secret-get` | Retrieve secrets |
+| "another session should..." | `a2a-send-task` | Multi-session collaboration |
+| "what's my progress..." | `get-session-health` | Check token usage |
+
+---
+
+## Core Tools (Daily Use)
+
+### buddy-remember: Project Memory Search
+**Triggers**: remember, recall, past, decision, why, when, bug, pattern, architecture
+
+**When to use**:
+- User asks "why did we..."
+- User asks "remember when..."
+- Starting work on existing feature (check past decisions)
+- Before making architectural changes (review previous choices)
+- Debugging (check if similar bug was fixed before)
+
+**Examples**:
+```typescript
+// User: "Why did we use JWT instead of sessions?"
+buddy-remember({ query: "JWT authentication decision" })
+
+// User: "Has this bug happened before?"
+buddy-remember({ query: "login timeout bug" })
+
+// Proactive: Starting auth work
+buddy-remember({ query: "authentication patterns" })
+```
+
+**Best practices**:
+- Search BEFORE implementing (check existing patterns)
+- Use specific keywords from domain (not generic terms)
+- Query when user mentions "we did this before"
+
+---
+
+### buddy-do: Smart Task Execution
+**Triggers**: implement, create, build, fix, refactor, add, update
+
+**When to use**:
+- User requests implementation work
+- Task requires routing to appropriate capability
+- Want automatic task metadata capture
+
+**Examples**:
+```typescript
+// User: "Add rate limiting to the API"
+buddy-do({
+  task: "Add rate limiting to API endpoints because we're getting too many requests so that server stays responsive under load"
+})
+
+// Include: what (rate limiting) + why (too many requests) + outcome (stay responsive)
+```
+
+**Best practices**:
+- Include goal + reason + expected outcome
+- Let buddy-do handle routing (don't manually route)
+- Task metadata auto-saved to knowledge graph
+
+---
+
+### create-entities: Store Knowledge
+**Triggers**: Completed major work, made important decision, learned lesson, fixed bug
+
+**When to use** (PROACTIVE):
+- After implementing new feature (store decision rationale)
+- After fixing bug (record root cause)
+- After making architectural choice (document why)
+- User explicitly corrects you (record mistake pattern)
+
+**Examples**:
+```typescript
+// After implementing OAuth
+create-entities({
+  entities: [{
+    name: "OAuth2 Implementation Decision",
+    entityType: "decision",
+    observations: [
+      "Chose OAuth2 over JWT for better revocation control",
+      "Used authorization code flow for web clients",
+      "Implemented PKCE for mobile apps"
+    ],
+    tags: ["authentication", "oauth", "security"]
+  }]
+})
+
+// After fixing bug
+create-entities({
+  entities: [{
+    name: "Login Timeout Bug Fix",
+    entityType: "bug_fix",
+    observations: [
+      "Root cause: Redis connection pooling exhaustion",
+      "Solution: Increased pool size to 20 connections",
+      "Prevention: Added connection pool monitoring"
+    ],
+    tags: ["bug", "redis", "timeout"]
+  }]
+})
+```
+
+**Best practices**:
+- Store AFTER completing significant work (not during)
+- Include specific details (not vague summaries)
+- Add relevant tags for future searchability
+
+---
+
+## Workflow Tools (Automatic Guidance)
+
+### get-workflow-guidance: Next Steps
+**Triggers**: Automatically triggered after Write/Edit/Bash (via hooks)
+
+**Manual use cases**:
+- User asks "what should I do next?"
+- Starting new phase (idle → code-written → test → commit)
+- Unsure about workflow rules
+
+**Phases**:
+- `idle`: Starting fresh work
+- `code-written`: Just finished coding
+- `test-complete`: Tests just ran
+- `commit-ready`: About to commit
+- `committed`: Just committed
+
+**Note**: Usually auto-triggered by `hook-tool-use`, rarely called manually.
+
+---
+
+### get-session-health: Token Monitoring
+**Triggers**: Long session, complex task, user asks about progress
+
+**When to use**:
+- Session feels slow or degraded
+- User asks "how much context left?"
+- Before starting memory-intensive work
+- When considering session cleanup
+
+**Example**:
+```typescript
+get-session-health()
+// Returns: { tokenUsage, contextQuality, recommendations }
+```
+
+---
+
+## Learning Tools (Improvement)
+
+### buddy-record-mistake: Error Learning
+**Triggers**: User corrects you, says "you should have...", "why didn't you..."
+
+**When to use** (IMMEDIATE):
+- User explicitly corrects your behavior
+- You violated documented procedure
+- You made assumption instead of asking
+- You skipped validation step
+- User frustrated with repeated mistake
+
+**Examples**:
+```typescript
+// User: "Why did you edit the file without reading it first?"
+buddy-record-mistake({
+  action: "Edited config.ts without reading first",
+  errorType: "procedure-violation",
+  userCorrection: "Must read file before editing",
+  correctMethod: "Use Read tool first, then Edit with exact content",
+  impact: "Broke file formatting, wasted time",
+  preventionMethod: "ALWAYS Read before Edit - no exceptions"
+})
+```
+
+**Best practices**:
+- Record IMMEDIATELY when corrected (don't wait)
+- Be specific about what you did wrong
+- Include concrete prevention method
+
+---
+
+## Secret Management (Security)
+
+### buddy-secret-store/get/list/delete
+**Triggers**: API key, token, password, credential, secret
+
+**When to use**:
+- User provides API key/token (offer to store securely)
+- Need API key for integration (retrieve from storage)
+- User asks "what secrets do I have?" (list)
+- Rotating credentials (delete old, store new)
+
+**Examples**:
+```typescript
+// User shares: "Here's the OpenAI API key: sk-..."
+buddy-secret-store({
+  name: "openai-api-key",
+  value: "sk-...",
+  type: "api_key",
+  description: "OpenAI API key for GPT-4 integration"
+})
+
+// Later, when needed:
+const key = buddy-secret-get({ name: "openai-api-key" })
+```
+
+**Best practices**:
+- ALWAYS offer to store when user shares secret
+- Use descriptive names (not "key1", "key2")
+- Never log secret values (use masked output)
+
+---
+
+## Test Generation
+
+### generate-tests: AI Test Creation
+**Triggers**: "write tests", "need tests", "generate tests", finished feature without tests
+
+**When to use**:
+- Completed feature implementation (no tests yet)
+- User explicitly requests test generation
+- Following TDD (specification → tests → implementation)
+
+**Examples**:
+```typescript
+// After implementing function
+generate-tests({
+  code: `
+    function validateEmail(email: string): boolean {
+      const regex = /^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/;
+      return regex.test(email);
+    }
+  `
+})
+
+// From specification
+generate-tests({
+  specification: "Email validator should: accept valid emails, reject invalid formats, handle edge cases (empty, null, special chars)"
+})
+```
+
+---
+
+## Multi-Session Collaboration (A2A Protocol)
+
+### a2a-send-task: Delegate to Other Session
+**Triggers**: "another session", "parallel", "split work", "specialized session"
+
+**When to use**:
+- User mentions working with multiple sessions
+- Task can be parallelized across sessions
+- Need specialized session (frontend/backend/testing)
+
+**Example**:
+```typescript
+// User: "Have another session work on the frontend while I do backend"
+a2a-send-task({
+  targetAgentId: "frontend-session-123",
+  taskDescription: "Implement React components for user dashboard with charts and tables",
+  priority: "normal"
+})
+```
+
+---
+
+### a2a-get-task / list-tasks / list-agents
+**Use together**:
+1. `a2a-list-agents()` - Find available sessions
+2. `a2a-send-task()` - Send work to session
+3. `a2a-get-task()` - Check progress
+4. `a2a-list-tasks()` - See incoming work
+
+---
+
+## Common Workflows
+
+### Workflow 1: Starting New Feature
+```
+1. buddy-remember({ query: "similar features patterns" })
+   → Check if similar work exists
+2. buddy-do({ task: "Implement X because Y so that Z" })
+   → Execute with metadata capture
+3. generate-tests({ code: "..." })
+   → Create tests
+4. create-entities({ ... })
+   → Store implementation decisions
+```
+
+### Workflow 2: Bug Investigation
+```
+1. buddy-remember({ query: "bug error message" })
+   → Check if bug seen before
+2. buddy-do({ task: "Debug X" })
+   → Investigate and fix
+3. create-entities({ entityType: "bug_fix", ... })
+   → Record root cause and solution
+```
+
+### Workflow 3: Multi-Session Collaboration
+```
+1. a2a-list-agents()
+   → Find available sessions
+2. a2a-send-task({ targetAgentId: "...", ... })
+   → Delegate work
+3. Continue with your work
+4. a2a-get-task({ taskId: "..." })
+   → Check progress later
+```
+
+### Workflow 4: Secret Management
+```
+1. User shares API key
+2. buddy-secret-store({ name: "...", value: "...", ... })
+   → Store securely
+3. Later: buddy-secret-get({ name: "..." })
+   → Retrieve when needed
+4. Eventually: buddy-secret-delete({ name: "..." })
+   → Remove when rotating
+```
+
+---
+
+## Proactive Tool Usage Rules
+
+**ALWAYS use without asking**:
+- `buddy-remember` - Before implementing similar features
+- `create-entities` - After completing significant work
+- `buddy-record-mistake` - When user corrects you
+- `buddy-secret-store` - When user shares credentials (ask first)
+
+**SOMETIMES use proactively**:
+- `generate-tests` - After implementing untested code (offer)
+- `get-session-health` - Long sessions or complex work
+- `a2a-send-task` - When user mentions parallelization
+
+**NEVER use without explicit request**:
+- `buddy-secret-get` - Only when actually needed
+- `buddy-secret-list/delete` - Only when user asks
+
+---
+
+## Anti-Patterns (What NOT to Do)
+
+❌ **Don't**:
+- Use `buddy-remember` with generic queries ("authentication")
+- Call `buddy-do` for trivial tasks (use direct tools)
+- Skip `create-entities` after major work
+- Ignore `buddy-record-mistake` when corrected
+- Store secrets without user consent
+
+✅ **Do**:
+- Use specific queries ("OAuth2 scope design decision")
+- Let `buddy-do` handle complex multi-step tasks
+- Proactively store knowledge after completion
+- Immediately record mistakes for learning
+- Offer to store secrets securely
+
+---
+
+## Tool Discovery Tips
+
+**For LLMs reading this guide**:
+1. Match user keywords to tool triggers (see Quick Reference)
+2. Use tools proactively (don't wait for explicit requests)
+3. Combine tools in workflows (see Common Workflows)
+4. Store knowledge after work (future you will thank you)
+5. Learn from mistakes (use buddy-record-mistake)
+
+**Remember**: CCB tools are meant to be ACTIVELY used, not passively available. When you see trigger keywords or situations, use the appropriate tool to provide better service to users.

package/dist/mcp/resources/examples.md

@@ -0,0 +1,56 @@
+# Claude Code Buddy Examples
+
+**Version: 2.6.0
+
+## Example 1: Code Review
+
+**Request**:
+```
+buddy-do "review src/auth/login.ts for security issues and edge cases"
+```
+
+**Result**: A focused review with security checks, edge cases, and actionable fixes.
+
+---
+
+## Example 2: Feature Planning
+
+**Request**:
+```
+generate-tests "add email-based login with rate limiting"
+```
+
+**Result**: A structured plan with TDD-friendly steps and estimated durations.
+
+---
+
+## Example 3: Debugging a Failure
+
+**Request**:
+```
+buddy-do "debug why login requests return 500s in production"
+```
+
+**Result**: Root-cause analysis with likely failure paths and verification steps.
+
+---
+
+## Example 4: Memory Recall
+
+**Request**:
+```
+buddy-remember "why we chose SQLite for local storage"
+```
+
+**Result**: A concise summary of the decision and its tradeoffs.
+
+---
+
+## Example 5: Workflow Guidance
+
+**Request**:
+```
+get-workflow-guidance {"phase":"test-complete"}
+```
+
+**Result**: Next-step recommendations for code review and commit readiness.

package/dist/mcp/resources/handlers/AgentStatusHandler.d.ts

@@ -0,0 +1,7 @@
+import { ResourceContent } from '../ResourceRegistry.js';
+import { URITemplateParams } from '../URITemplateHandler.js';
+export declare class AgentStatusHandler {
+    handle(params: URITemplateParams): Promise<ResourceContent>;
+    private getAgentCapabilities;
+}
+//# sourceMappingURL=AgentStatusHandler.d.ts.map

package/dist/mcp/resources/handlers/AgentStatusHandler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentStatusHandler.d.ts","sourceRoot":"","sources":["../../../../src/mcp/resources/handlers/AgentStatusHandler.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAyB7D,qBAAa,kBAAkB;IAOvB,MAAM,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,eAAe,CAAC;IAqCjE,OAAO,CAAC,oBAAoB;CAW7B"}

package/dist/mcp/resources/handlers/AgentStatusHandler.js

@@ -0,0 +1,41 @@
+import { NotFoundError } from '../../../errors/index.js';
+const VALID_AGENT_TYPES = [
+    'code-reviewer',
+    'test-writer',
+    'development-butler',
+    'e2e-healing',
+    'knowledge-graph',
+];
+export class AgentStatusHandler {
+    async handle(params) {
+        const agentType = params.agentType;
+        if (!agentType) {
+            throw new Error('Missing required parameter: agentType');
+        }
+        if (!VALID_AGENT_TYPES.includes(agentType)) {
+            throw new NotFoundError(`Unknown agent type: ${agentType}`, 'agent', agentType, { validTypes: VALID_AGENT_TYPES });
+        }
+        const status = {
+            agentType,
+            status: 'active',
+            capabilities: this.getAgentCapabilities(agentType),
+            lastActive: new Date().toISOString(),
+        };
+        return {
+            uri: `ccb://agent/${agentType}/status`,
+            mimeType: 'application/json',
+            text: JSON.stringify(status, null, 2),
+        };
+    }
+    getAgentCapabilities(agentType) {
+        const capabilities = {
+            'code-reviewer': ['review', 'analyze', 'suggest'],
+            'test-writer': ['generate-tests', 'test-analysis'],
+            'development-butler': ['project-setup', 'dependency-management'],
+            'e2e-healing': ['test-healing', 'failure-analysis'],
+            'knowledge-graph': ['memory', 'learning', 'recall'],
+        };
+        return capabilities[agentType] || [];
+    }
+}
+//# sourceMappingURL=AgentStatusHandler.js.map

package/dist/mcp/resources/handlers/AgentStatusHandler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentStatusHandler.js","sourceRoot":"","sources":["../../../../src/mcp/resources/handlers/AgentStatusHandler.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AASzD,MAAM,iBAAiB,GAAG;IACxB,eAAe;IACf,aAAa;IACb,oBAAoB;IACpB,aAAa;IACb,iBAAiB;CACT,CAAC;AASX,MAAM,OAAO,kBAAkB;IAO7B,KAAK,CAAC,MAAM,CAAC,MAAyB;QACpC,MAAM,SAAS,GAAG,MAAM,CAAC,SAAS,CAAC;QAEnC,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC;QAC3D,CAAC;QAED,IAAI,CAAC,iBAAiB,CAAC,QAAQ,CAAC,SAAgB,CAAC,EAAE,CAAC;YAClD,MAAM,IAAI,aAAa,CACrB,uBAAuB,SAAS,EAAE,EAClC,OAAO,EACP,SAAS,EACT,EAAE,UAAU,EAAE,iBAAiB,EAAE,CAClC,CAAC;QACJ,CAAC;QAGD,MAAM,MAAM,GAAgB;YAC1B,SAAS;YACT,MAAM,EAAE,QAAQ;YAChB,YAAY,EAAE,IAAI,CAAC,oBAAoB,CAAC,SAAS,CAAC;YAClD,UAAU,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACrC,CAAC;QAEF,OAAO;YACL,GAAG,EAAE,eAAe,SAAS,SAAS;YACtC,QAAQ,EAAE,kBAAkB;YAC5B,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;SACtC,CAAC;IACJ,CAAC;IAQO,oBAAoB,CAAC,SAAiB;QAC5C,MAAM,YAAY,GAA6B;YAC7C,eAAe,EAAE,CAAC,QAAQ,EAAE,SAAS,EAAE,SAAS,CAAC;YACjD,aAAa,EAAE,CAAC,gBAAgB,EAAE,eAAe,CAAC;YAClD,oBAAoB,EAAE,CAAC,eAAe,EAAE,uBAAuB,CAAC;YAChE,aAAa,EAAE,CAAC,cAAc,EAAE,kBAAkB,CAAC;YACnD,iBAAiB,EAAE,CAAC,QAAQ,EAAE,UAAU,EAAE,QAAQ,CAAC;SACpD,CAAC;QAEF,OAAO,YAAY,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC;IACvC,CAAC;CACF"}

package/dist/mcp/resources/handlers/TaskLogsHandler.d.ts

@@ -0,0 +1,7 @@
+import { ResourceContent } from '../ResourceRegistry.js';
+import { URITemplateParams } from '../URITemplateHandler.js';
+export declare class TaskLogsHandler {
+    handle(params: URITemplateParams): Promise<ResourceContent>;
+    private fetchTaskLogs;
+}
+//# sourceMappingURL=TaskLogsHandler.d.ts.map

package/dist/mcp/resources/handlers/TaskLogsHandler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TaskLogsHandler.d.ts","sourceRoot":"","sources":["../../../../src/mcp/resources/handlers/TaskLogsHandler.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAS7D,qBAAa,eAAe;IAOpB,MAAM,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,eAAe,CAAC;YA+BnD,aAAa;CAqB5B"}

package/dist/mcp/resources/handlers/TaskLogsHandler.js

@@ -0,0 +1,36 @@
+export class TaskLogsHandler {
+    async handle(params) {
+        const taskId = params.taskId;
+        if (!taskId) {
+            throw new Error('Missing required parameter: taskId');
+        }
+        const logs = await this.fetchTaskLogs(taskId);
+        return {
+            uri: `ccb://task/${taskId}/logs`,
+            mimeType: 'text/plain',
+            text: logs,
+        };
+    }
+    async fetchTaskLogs(taskId) {
+        return `Task Logs - Feature Not Yet Available
+=====================================
+
+Task ID: ${taskId}
+
+Detailed task execution logs are not yet available in this version.
+
+This feature requires:
+- Log capture in BackgroundExecutor
+- Log storage in EvolutionStore
+- Integration with task lifecycle tracking
+
+Current workaround:
+- Check task status via BackgroundExecutor.getProgress()
+- Monitor console logs during task execution
+- Use UIEventBus for progress events
+
+Status: Planned for future release
+`;
+    }
+}
+//# sourceMappingURL=TaskLogsHandler.js.map

package/dist/mcp/resources/handlers/TaskLogsHandler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TaskLogsHandler.js","sourceRoot":"","sources":["../../../../src/mcp/resources/handlers/TaskLogsHandler.ts"],"names":[],"mappings":"AAWA,MAAM,OAAO,eAAe;IAO1B,KAAK,CAAC,MAAM,CAAC,MAAyB;QACpC,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;QAE7B,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAC;QACxD,CAAC;QAGD,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC;QAE9C,OAAO;YACL,GAAG,EAAE,cAAc,MAAM,OAAO;YAChC,QAAQ,EAAE,YAAY;YACtB,IAAI,EAAE,IAAI;SACX,CAAC;IACJ,CAAC;IAgBO,KAAK,CAAC,aAAa,CAAC,MAAc;QACxC,OAAO;;;WAGA,MAAM;;;;;;;;;;;;;;;CAehB,CAAC;IACA,CAAC;CACF"}

package/dist/mcp/resources/quick-reference.md

@@ -0,0 +1,73 @@
+# Claude Code Buddy Quick Reference
+
+**Version: 2.6.0
+
+## 🚀 Quick Commands
+
+```bash
+buddy-do "<task description>"         # Smart routing (recommended)
+buddy-remember "<query>"             # Recall project memory
+buddy-help                             # Command help
+get-session-health                     # Session health snapshot
+get-workflow-guidance '{"phase":"code-written"}'
+generate-tests '{"featureDescription":"..."}'
+```
+
+Note: `hook-tool-use` is internal and used by Claude Code hooks.
+
+## 🧭 Capability Keywords
+
+| Capability | Keywords | Use For |
+|---|---|---|
+| Code Review | review, audit, quality | Security checks, best practices |
+| Testing | test, coverage, TDD | Unit, integration, E2E testing |
+| Debugging | debug, bug, error | Root-cause analysis |
+| Refactoring | refactor, cleanup | Structural improvements |
+| API/Backend | api, endpoint, backend | API design and backend logic |
+| Frontend/UI | ui, component, frontend | UI, accessibility, UX |
+| Architecture | architecture, design, scalability | System design, tradeoffs |
+| Data/Database | database, query, schema | Query tuning, schema design |
+| Documentation | docs, guide, readme | Technical writing |
+
+## 🎯 Common Workflows
+
+### Feature Development
+```
+1. generate-tests "<feature>"
+2. buddy-do "implement <feature>"
+3. buddy-do "write tests for <feature>"
+4. buddy-do "review <feature> for quality"
+```
+
+### Bug Fixing
+```
+1. buddy-do "debug <issue> and find root cause"
+2. buddy-do "fix <issue> and add regression test"
+```
+
+### Performance Review
+```
+1. buddy-do "profile performance for <area>"
+2. buddy-do "optimize slow path in <area>"
+```
+
+## 💡 Quick Tips
+
+✅ **DO**:
+- Use clear, specific task descriptions
+- Mention files, constraints, or target behaviors
+- Use `buddy-remember` before large changes
+
+❌ **DON'T**:
+- Use vague descriptions ("fix bug")
+- Skip context when it matters
+
+## 📚 Full Documentation
+
+- **Complete Guide**: `@claude-code-buddy://usage-guide`
+- **Examples**: `@claude-code-buddy://examples`
+- **Best Practices**: `@claude-code-buddy://best-practices`
+
+---
+
+**Remember**: The smart router learns from your patterns - the more you use it, the better it gets!