From 4b307b55b9c06ac457516e45ec17612bd0f477ef Mon Sep 17 00:00:00 2001 From: Riz Ashraf Date: Mon, 5 Oct 2026 11:22:55 +0100 Subject: [PATCH] docs: update human and LLM docs and enhance tool/list schemas with actionable next steps --- EFFECTIVE_DISCOURSE.md | 2 +- README.md | 27 +++- agent-rules/mcp_memory_workflow.md | 4 +- instructions.md | 225 ++++++++++------------------- server/src/handlers/env.rs | 4 +- server/src/handlers/meta.rs | 8 +- server/src/handlers/notes.rs | 8 +- server/src/handlers/tasks.rs | 20 +-- server/src/handlers/workspaces.rs | 22 +-- server/src/instructions.md | 203 ++++++++++---------------- server/src/models.rs | 1 - server/src/tools.rs | 119 +++++++++++---- 12 files changed, 307 insertions(+), 336 deletions(-) diff --git a/EFFECTIVE_DISCOURSE.md b/EFFECTIVE_DISCOURSE.md index c2daff6..76de67e 100644 --- a/EFFECTIVE_DISCOURSE.md +++ b/EFFECTIVE_DISCOURSE.md @@ -89,7 +89,7 @@ Actively instruct the LLM to maintain its memory constraints and use canonical c * **Do say:** "Log this architectural decision in the knowledge graph using PascalCase for entity types." * **Do say:** "Add a sticky note with the test database credentials for this session with a 1-hour TTL." * **Do say:** "Create a milestone for the 'Rich Clipboard' feature and break it down into active tasks." -* **Tools Triggered:** `create_entities`, `log_decision`, `add_sticky_note`, `add_milestone`, `add_task` +* **Tools Triggered:** `create_entities`, `decisions` (log), `sticky_notes` (add), `milestones` (add), `tasks` (add) --- diff --git a/README.md b/README.md index 8169651..b3d25d6 100644 --- a/README.md +++ b/README.md @@ -25,6 +25,27 @@ To prevent graph fragmentation and ensure optimal LLM tokenization and retrieval --- +--- + +## πŸ› οΈ Consolidated Smart MCP Tools + +The server consolidates granular single-purpose tools into 12 concise, action-oriented smart domain handlers with zero prefix clutter: + +* **`tasks`**: Complete task lifecycle management (`add`, `update`, `delete`, `list`, `set_criteria`, `verify`). +* **`milestones`**: Milestone tracking (`add`, `update`, `list`). +* **`sticky_notes`**: Ephemeral scratchpad notes with TTL (`add`, `read`, `delete`, `clear`). +* **`handoff_memos`**: Cross-session handoff notes (`leave`, `read`, `clear`). +* **`pinned_files`**: Working set file focus management (`pin`, `unpin`, `list`). +* **`context_workspaces`**: Workspace context state snapshots (`save`, `load`, `list`, `delete`, `diff`). +* **`pr_checklist`**: Pre-commit and PR checklist management (`add`, `get`, `clear`). +* **`snippets`**: Reusable code snippet vault with BM25+Vector search (`store`, `search`, `delete`, `tag`). +* **`decisions`**: Architectural Decision Records (ADRs) (`log`, `query`, `delete`). +* **`tech_debt`**: Engineering technical debt backlog (`log`, `resolve`, `list`). +* **`environment`**: Infrastructure & tool fingerprints tracking (`update_fingerprint`, `read_fingerprint`, `log_requirement`, `register`, `get_details`). +* **`clipboard`**: Cross-OS clipboard management (`read`, `write`, `toggle_watch`). + +--- + ## Key Features & Capabilities ### πŸ•ΈοΈ Multi-Hop Subgraph Expansion (`get_subgraph`) @@ -37,11 +58,11 @@ Compares build and test stack traces against historical error resolutions using Saves point-in-time snapshots of graph entities, active tasks, and tech debt backlogs before risky operations, enabling seamless state restoration. ### πŸ“Š Token Budgeting & RRF Search -* **Token Budgeting**: Supports `summary_level` (`compact` | `detailed` | `full`) and `max_tokens` parameters on `list_active_tasks` and `list_tech_debt`. +* **Token Budgeting**: Supports `summary_level` (`compact` | `detailed` | `full`) and `max_tokens` parameters on `tasks` (list) and `tech_debt` (list). * **Hybrid RRF Search**: `omni_search` combines Tantivy BM25 keyword matching with Dense Vector embeddings using Reciprocal Rank Fusion. * **Session Delta Resource (`memory://session/delta`)**: Delivers recent session changes in a compact context resource. -### 🏷️ Domain Tagging for Code Snippets (`tag_snippet`) +### 🏷️ Domain Tagging for Code Snippets (`snippets`) Supports categorization tags (`tags: Vec`) on code snippets for category-filtered searches and domain organization. ### 🧹 Self-Healing Graph Sweeper (`sweep_graph_health`) @@ -56,7 +77,7 @@ Evaluates task dependency graphs and returns unblocked, ready-to-run tasks for s ### 🧠 Chain-of-Thought & Diagnostic Hypothesis Memory (`log_hypothesis` / `query_hypotheses`) Records structured diagnostic hypotheses, test evidence, and verification statuses to preserve reasoning across sessions. -### πŸ”€ Context Workspace Diffing (`diff_context_workspaces`) +### πŸ”€ Context Workspace Diffing (`context_workspaces`) Computes structured diffs of pinned files and active task IDs between two saved context workspaces. ### πŸ“‘ Real-time WebSocket Memory Sync (`ws://127.0.0.1:3000/ws`) diff --git a/agent-rules/mcp_memory_workflow.md b/agent-rules/mcp_memory_workflow.md index d784b46..3a5804f 100644 --- a/agent-rules/mcp_memory_workflow.md +++ b/agent-rules/mcp_memory_workflow.md @@ -11,8 +11,8 @@ description: Strict guidelines for interacting with the mcp-memory server, ensur ## 2. Proactive "Central Brain" Usage The MCP Memory server is the central brain. You must be PROACTIVE, not reactive, in using it: -- **Session Starts & Context Drops**: Always begin by checking `list_active_tasks`, `list_pinned_files`, and `read_sticky_notes`. -- **Sticky Notes**: Use sticky notes for transient, session-scoped operational constraints (e.g., "Do not touch file X until Y is done"). +- **Session Starts & Context Drops**: Always begin by calling `tasks` (action: "list"), `pinned_files` (action: "list"), and `sticky_notes` (action: "read"). +- **Sticky Notes**: Use `sticky_notes` (action: "add") for transient, session-scoped operational constraints (e.g., "Do not touch file X until Y is done"). - **Error Fixes**: The moment a tricky, undocumented, or environment-specific bug is resolved (e.g., Bitbucket markdown rendering quirks, nuanced framework bugs), IMMEDIATELY call `log_error_fix`. Do not wait for the user to ask. - **Tech Debt**: If you notice an anti-pattern (e.g., nested `if` statements, arrow anti-pattern) but deliberately skip fixing it to focus on a feature, IMMEDIATELY call `log_tech_debt`. diff --git a/instructions.md b/instructions.md index 6ab2a17..fc12a2a 100644 --- a/instructions.md +++ b/instructions.md @@ -17,184 +17,117 @@ To prevent graph fragmentation and ensure seamless LLM context retrieval: --- -## 2. LLM Token Budgeting & RRF Search Optimization +## 2. Consolidated Smart Tools Architecture -* **Token Budgeting (`summary_level` & `max_tokens`)**: - When calling `list_active_tasks` or `list_tech_debt`, pass `summary_level: "compact"` or `"detailed"` and `max_tokens: 500` to constrain output size when token context budget is tight. -* **Reciprocal Rank Fusion (RRF) Omni-Search**: - `omni_search` uses Hybrid RRF (BM25 keyword search + Dense Vector Embeddings) to rank results semantically. You do not need exact keyword matches; query conceptually (e.g. "database lock issues"). -* **Delta Session Context (`memory://session/delta`)**: - Passively read `memory://session/delta` to get a succinct delta of code changes, tasks, and tech debt recorded during the current working session. -* **Context Warmup (`context_warmup`)**: - Trigger the `context_warmup` prompt at session start to automatically synthesize delta changes, active tasks, tech debt, and pinned files in a single pass. +The server consolidates granular single-purpose tools into domain-named smart tools. Always prefer the consolidated tools over legacy aliases: + +* **`tasks`**: Complete task lifecycle management. + - `action: "add"`: Create a new task (requires `title`, optional `description`, `git_branch`, `parent_id`, `dependencies`). + - `action: "update"`: Update task status (requires `id`, `status: "pending" | "completed" | "cancelled"`). + - `action: "delete"`: Delete task and child tasks (requires `id`). + - `action: "list"`: List active tasks (optional `git_branch`, `summary_level: "compact" | "detailed" | "full"`, `max_tokens`). + - `action: "set_criteria"`: Set acceptance criteria (requires `id`, `criteria: Vec`). + - `action: "verify"`: Verify criteria met (requires `id`). + +* **`milestones`**: Milestone tracking. + - `action: "add"`: Create milestone (requires `title`). + - `action: "update"`: Update milestone status (requires `id`, `status`). + - `action: "list"`: List milestones. + +* **`sticky_notes`**: Ephemeral scratchpad notes with TTL. + - `action: "add"`: Add note (requires `content`, optional `ttl_seconds`, `session_only`). + - `action: "read"`: Read all active notes. + - `action: "delete"`: Delete note by index (requires 1-based `index`). + - `action: "clear"`: Clear all sticky notes. + +* **`handoff_memos`**: Session handoff notes for future agents. + - `action: "leave"`: Leave a memo (requires `content`). + - `action: "read"`: Read active handoff memos. + - `action: "clear"`: Clear memos. + +* **`pinned_files`**: Focus file working set. + - `action: "pin"`: Pin file to focus set (requires `path`). + - `action: "unpin"`: Unpin file from focus set (requires `path`). + - `action: "list"`: List pinned files. + +* **`context_workspaces`**: Workspace context state snapshots. + - `action: "save"`: Save context workspace (requires `name`). + - `action: "load"`: Restore saved context workspace (requires `name`). + - `action: "list"`: List saved context workspaces. + - `action: "delete"`: Delete saved context workspace (requires `name`). + - `action: "diff"`: Compare two saved context workspaces (requires `name`, `other_name`). + +* **`pr_checklist`**: Pre-commit and PR checklist. + - `action: "add"`: Add checklist item (requires `description`). + - `action: "get"`: Get PR checklist items. + - `action: "clear"`: Clear PR checklist. + +* **`snippets`**: Reusable code snippet vault. + - `action: "store"`: Store snippet (requires `query` as name, optional `language`, `code`, `description`, `tags`). + - `action: "search"`: Search snippet vault (optional `query`, `tags`, `hybrid: true`). + - `action: "delete"`: Delete snippet (requires `id`). + - `action: "tag"`: Attach classification tags (requires `id`, `tags: Vec`). + +* **`decisions`**: Architectural Decision Records (ADRs). + - `action: "log"`: Log ADR (requires `title`, optional `status`, `context`, `decision`, `consequences`). + - `action: "query"`: Query ADRs (optional `query`). + - `action: "delete"`: Delete ADR (requires `id`). + +* **`tech_debt`**: Engineering debt backlog. + - `action: "log"`: Log debt item (requires `description`, optional `ideal_solution`, `git_commit`, `git_branch`, `symbol_references`, `line_range`). + - `action: "resolve"`: Resolve debt item (requires `id`). + - `action: "list"`: List debt items (optional `include_resolved`). + +* **`environment`**: Infrastructure and requirements tracking. + - `action: "update_fingerprint"`: Update tool versions. + - `action: "read_fingerprint"`: Read tool versions fingerprint. + - `action: "log_requirement"`: Log environment variable requirement (requires `key`). + - `action: "register"`: Register target environment (requires `name`). + - `action: "get_details"`: Read full environment details. + +* **`clipboard`**: OS Clipboard management. + - `action: "read"`: Read OS clipboard. + - `action: "write"`: Write text/html/files/image to clipboard. + - `action: "toggle_watch"`: Toggle auto-clipboard watcher. --- ## 3. Subgraph Expansion & Multi-Hop Navigation - **Tool:** `get_subgraph` - **When to use:** When you need to understand the complete architectural neighborhood surrounding a specific component, module, or database table. -- **Behavior:** Performs a multi-hop Breadth-First Search (BFS) around a `root_node` up to a requested `depth` (e.g. 1 to 3 hops) and returns all connected entities and relations in a single call. +- **Behavior:** Performs a multi-hop Breadth-First Search (BFS) around a `root_node` (or `root_entity`) up to a requested `depth` (e.g. 1 to 3 hops) and returns all connected entities and relations. Pass `format: "markdown_tree"` to generate a compact, token-budgeted Markdown topology tree capped within a requested `max_tokens` budget. --- ## 4. Automated Error Fix Auto-Matcher -- **Tools:** `log_error_fix`, `suggest_error_fix`, `search_error_fixes` -- **When to use:** When encountering a build error, test failure, or stack trace. Call `suggest_error_fix` with the error trace before attempting a fix from scratch. -- **Behavior:** Computes cosine similarity between error trace embeddings and past resolution logs to return top matched solutions, modified files, and git commits. +- **Tools:** `log_error_fix`, `search_error_fixes` (and alias `suggest_error_fix`) +- **When to use:** When encountering a build error, test failure, or stack trace. Call `search_error_fixes` with either a text `query` or `stack_trace` before attempting a fix from scratch. +- **Behavior:** Computes cosine similarity between error trace embeddings and past resolution logs when `stack_trace` is provided, or keyword filtering when `query` is provided, returning top matched solutions, modified files, and git commits. --- ## 5. Memory State Checkpointing & Rollbacks -- **Tools:** `checkpoint_state`, `restore_state` +- **Tool:** `checkpoint_state`, `restore_state` (or `create_snapshot`, `restore_snapshot`) - **When to use:** Before initiating a large refactor, running experimental subagent tasks, or executing destructive batch operations. - **Behavior:** Saves or restores a point-in-time snapshot of graph entities, active tasks, and tech debt backlogs. --- -## 6. Symbol Reference Backlinks -- **Tools:** `log_code_change`, `log_error_fix`, `log_tech_debt` -- **When to use:** When logging changes or debt tied to specific code symbols or line boundaries. -- **Behavior:** Accept `symbol_references` (e.g., `["MemoryState::new", "CreateEntitiesTool"]`) and `line_range` (e.g., `"L45-L90"`), automatically indexing code references for quick symbol backlink searches. - ---- - -## 7. Ephemeral Sticky Notes with TTL -- **Tools:** `add_sticky_note`, `read_sticky_notes`, `delete_sticky_note`, `clear_sticky_notes` -- **When to use:** For temporary scratchpad items, temporary ports, task IDs, or transient notes. -- **Behavior:** Supports `ttl_seconds` for auto-expiration and `session_only: true` for automatic purging when the session ends. - ---- - -## 8. Snippet Vault & Domain Tagging -- **Tools:** `store_snippet`, `search_snippets`, `delete_snippet`, `tag_snippet` -- **When to use:** Store exact multi-line code snippets, Nushell pipelines, or frequently used CLI commands. -- **Behavior:** Guarantees precise syntactic preservation. Use `tag_snippet` to attach domain tags (e.g., `["rust", "axum", "mcp"]`) for category-filtered searches. - ---- - -## 9. Context Namespaces (Project Scopes) -- **Feature:** `namespace` optional parameter -- **When to use:** Isolate graph queries, tasks, and tech debt to specific project scopes (e.g. "mcp-memory"). -- **Behavior:** Pass `namespace` to `read_graph`, `search_nodes`, `create_entities`, or `create_relations` to isolate items from global scope. - ---- - -## 10. Architectural Decision Records (ADRs) -- **Tools:** `log_decision`, `query_decisions`, `delete_decision` -- **When to use:** Whenever making a non-trivial architectural, environmental, or design decision. -- **Behavior:** Permanently stores context, decision, and consequences to prevent future agents from second-guessing choices. - ---- - -## 11. Graph Refactoring & Algorithms -- **Tools:** `merge_entities`, `find_orphans`, `query_graph_path`, `condense_entity` -- **When to use:** Run `find_orphans` periodically to clean unused nodes. Use `merge_entities` to combine duplicate concepts. Use `query_graph_path` to find shortest relational connections between components. Use `condense_entity` when entity observation counts grow large. - ---- - -## 12. Dynamic Learned Preferences -- **Tools:** `learn_preference`, `read_preferences` -- **When to use:** When the user specifies personal or repository-specific preferences. -- **Behavior:** Stores key-value behavioral preferences that persist across agent invocations. - ---- - -## 13. Pinned Workspaces & Hot Files -- **Tools:** `pin_file`, `unpin_file`, `list_pinned_files` -- **When to use:** Pin 3–5 active working set files to maintain focus in large codebases. - ---- - -## 14. Agent Handoffs & Memos -- **Tools:** `leave_handoff_memo`, `read_handoff_memos`, `clear_handoff_memos` -- **When to use:** Leave messages for future agent sessions or inspect pending handoff notes upon waking. - ---- - -## 15. Real-time WebSocket Memory Sync -- **Endpoint:** `ws://127.0.0.1:3000/ws` -- **Behavior:** Broadcasts live state updates and activity notifications to the Brain Monitor UI in real time. - ---- - -## 16. Self-Healing Graph Health Sweeper +## 6. Self-Healing Graph Health Sweeper - **Tool:** `sweep_graph_health` - **When to use:** Periodically or before committing major graph changes to audit entity consistency. - **Behavior:** Detects orphaned nodes (0 relations), computes name similarity to identify near-duplicates (e.g., `APIGateway` vs `ApiGateway`), and provides structured `merge_entities` recommendations or auto-prunes orphans. --- -## 17. Causal Lineage & Provenance Tracker +## 7. Causal Lineage & Provenance Tracker - **Tool:** `query_lineage` - **When to use:** When asking *"Why was this component modified?"* or *"What task or ADR led to this code change?"* - **Behavior:** Searches across tasks, ADRs, audit ledger entries, and error fixes to assemble a unified chronological timeline explaining the provenance behind any file, symbol, or commit. --- -## 18. Topological Unblocked Task Resolver -- **Tool:** `get_next_actionable_tasks` -- **When to use:** When orchestrating subagent execution or selecting the next task to work on. -- **Behavior:** Evaluates task dependency DAGs and filters out any blocked tasks, returning only unblocked, actionable tasks ready for immediate execution. - ---- - -## 19. Chain-of-Thought & Diagnostic Hypothesis Memory -- **Tools:** `log_hypothesis`, `query_hypotheses` -- **When to use:** During complex debugging or root cause analysis. -- **Behavior:** Records hypotheses alongside tested evidence and status (`unverified`, `verified`, `rejected`). Allows subagents to query past diagnostic paths and avoid re-testing disproven hypotheses. - ---- - -## 20. Workspace Context Diffing -- **Tool:** `diff_context_workspaces` -- **When to use:** When switching branches or comparing two saved context workspaces. -- **Behavior:** Returns a structured delta highlighting added, removed, and shared pinned files and active task IDs between two context workspaces. - ---- - -## 21. Universal Token Guardrails -- **Behavior:** Automatically caps large MCP resource reads (e.g. `memory://graph/entities`) and list responses, adding summary headers (`"_meta": "Showing 100 of N items"`) to guarantee output stays within context window limits. - ---- - -## 22. LLM Pre-Flight Context Bundle +## 8. LLM Pre-Flight Context Bundle - **Tool:** `get_preflight_context` - **When to use:** At the start of a turn or subagent task to gain total situational awareness in 1 call. - **Behavior:** Aggregates current active branch, in-progress tasks with acceptance criteria, pinned files, top open tech debts, and active unverified hypotheses into a consolidated executive context bundle. - ---- - -## 23. Self-Healing Symbol & Line Range Resolver -- **Tool:** `resolve_stale_symbols` -- **When to use:** When files have been deleted, moved, or heavily refactored. -- **Behavior:** Verifies graph entities and tech debt symbol references against disk and AST, flagging and auto-healing stale pointers or broken file paths. - ---- - -## 24. Subgraph Topology Summarizer -- **Tool:** `summarize_subgraph` -- **When to use:** When needing a high-density, token-budgeted architectural summary of a module or component neighborhood. -- **Behavior:** Generates a compact Markdown topology tree centered on a `root_entity` up to `depth` hops, capped strictly within a requested `max_tokens` budget. - ---- - -## 25. Inter-Agent Signal Bus -- **Tools:** `broadcast_agent_signal`, `query_agent_signals` -- **When to use:** For real-time coordination and event-driven communication between concurrent subagents (e.g., `PrePushAuditor` signaling `AUDIT_PASSED` to parent agent). -- **Behavior:** Ephemeral TTL-backed signal bus storing structured agent events, payloads, and artifact URIs. - ---- - -## 26. Automated Session Checkpoint on Shutdown -- **Tool:** `auto_session_checkpoint` -- **When to use:** Executed automatically on `/shutdown` or manually when pausing a session. -- **Behavior:** Captures active tasks, unverified hypotheses, recent commit ledgers, and workspace state into a permanent `HandoffMemo` for seamless turn-taking and recovery. - ---- - -## 27. Hybrid Vector & BM25 Code Search -- **Tool:** `search_snippets_hybrid` -- **When to use:** When searching the snippet vault for reusable code patterns or Nushell pipelines. -- **Behavior:** Combines BM25 term frequency keyword matching with semantic tag scoring to rank code snippets by relevance. - - diff --git a/server/src/handlers/env.rs b/server/src/handlers/env.rs index 1235cdd..c880d9c 100644 --- a/server/src/handlers/env.rs +++ b/server/src/handlers/env.rs @@ -190,7 +190,7 @@ impl McpTool for EnvironmentHandler { } EnvAction::LogRequirement => { let key = req.key.ok_or_else(|| { - crate::error::AppError::Internal("key is required for 'log_requirement' action".to_string()) + crate::error::AppError::Internal("Missing required parameter 'key' for action 'log_requirement'. Next step: Provide environment variable 'key' string in request and retry.".to_string()) })?; let desc = req.description.unwrap_or_default(); let secret = req.is_secret.unwrap_or(false); @@ -198,7 +198,7 @@ impl McpTool for EnvironmentHandler { } EnvAction::Register => { let name = req.name.ok_or_else(|| { - crate::error::AppError::Internal("name is required for 'register' action".to_string()) + crate::error::AppError::Internal("Missing required parameter 'name' for action 'register'. Next step: Provide environment 'name' string in request and retry.".to_string()) })?; let url = req.url.unwrap_or_default(); let desc = req.description.unwrap_or_default(); diff --git a/server/src/handlers/meta.rs b/server/src/handlers/meta.rs index 36b574b..6930d7f 100644 --- a/server/src/handlers/meta.rs +++ b/server/src/handlers/meta.rs @@ -545,7 +545,7 @@ impl McpTool for DecisionsHandler { match req.action { DecisionAction::Log => { let title = req.title.ok_or_else(|| { - crate::error::AppError::Internal("title is required for 'log' action".to_string()) + crate::error::AppError::Internal("Missing required parameter 'title' for action 'log'. Next step: Provide ADR 'title' string in request and retry.".to_string()) })?; let status = req.status.unwrap_or_else(|| "accepted".to_string()); let context = req.context.unwrap_or_default(); @@ -568,7 +568,7 @@ impl McpTool for DecisionsHandler { } DecisionAction::Delete => { let id = req.id.ok_or_else(|| { - crate::error::AppError::Internal("id is required for 'delete' action".to_string()) + crate::error::AppError::Internal("Missing required parameter 'id' for action 'delete'. Next step: Provide ADR 'id' string in request and retry.".to_string()) })?; DeleteDecisionHandler.execute(serde_json::json!({"id": id}), state).await } @@ -597,7 +597,7 @@ impl McpTool for TechDebtHandler { match req.action { TechDebtAction::Log => { let desc = req.description.ok_or_else(|| { - crate::error::AppError::Internal("description is required for 'log' action".to_string()) + crate::error::AppError::Internal("Missing required parameter 'description' for action 'log'. Next step: Provide tech debt 'description' in request and retry.".to_string()) })?; let ideal = req.ideal_solution.unwrap_or_default(); LogTechDebtHandler.execute( @@ -615,7 +615,7 @@ impl McpTool for TechDebtHandler { } TechDebtAction::Resolve => { let id = req.id.ok_or_else(|| { - crate::error::AppError::Internal("id is required for 'resolve' action".to_string()) + crate::error::AppError::Internal("Missing required parameter 'id' for action 'resolve'. Next step: Provide tech debt 'id' string in request and retry.".to_string()) })?; ResolveTechDebtHandler.execute(serde_json::json!({"id": id}), state).await } diff --git a/server/src/handlers/notes.rs b/server/src/handlers/notes.rs index 3c0c0a1..0b73692 100644 --- a/server/src/handlers/notes.rs +++ b/server/src/handlers/notes.rs @@ -27,7 +27,7 @@ impl McpTool for StickyNotesHandler { match req.action { StickyNoteAction::Add => { let content = req.content.ok_or_else(|| { - crate::error::AppError::Internal("content is required for 'add' action".to_string()) + crate::error::AppError::Internal("Missing required parameter 'content' for action 'add'. Next step: Provide non-empty 'content' string in request and retry.".to_string()) })?; let now = crate::handlers::utils::now_secs(); let expires_at = if let Some(ttl) = req.ttl_seconds { @@ -64,7 +64,7 @@ impl McpTool for StickyNotesHandler { } StickyNoteAction::Delete => { let idx = req.index.ok_or_else(|| { - crate::error::AppError::Internal("index is required for 'delete' action".to_string()) + crate::error::AppError::Internal("Missing required parameter 'index' for action 'delete'. Next step: Provide 1-based sticky note 'index' integer in request and retry.".to_string()) })?; let mut success = false; state.code.sticky.modify(|notes| { @@ -77,7 +77,7 @@ impl McpTool for StickyNotesHandler { Ok("Sticky note deleted.".to_string()) } else { Err(crate::error::AppError::Internal( - "Invalid sticky note index.".to_string(), + "Invalid sticky note index. Next step: Call sticky_notes with action='read' to view active notes and valid 1-based indices, then retry.".to_string(), )) } } @@ -236,7 +236,7 @@ impl McpTool for HandoffMemosHandler { match req.action { HandoffMemoAction::Leave => { let content = req.content.ok_or_else(|| { - crate::error::AppError::Internal("content is required for 'leave' action".to_string()) + crate::error::AppError::Internal("Missing required parameter 'content' for action 'leave'. Next step: Provide non-empty 'content' string in request and retry.".to_string()) })?; let ns = req.namespace.unwrap_or_else(|| crate::models::default_namespace()); state.telemetry.handoff_memos.modify(|memos| { diff --git a/server/src/handlers/tasks.rs b/server/src/handlers/tasks.rs index ceb9962..1488443 100644 --- a/server/src/handlers/tasks.rs +++ b/server/src/handlers/tasks.rs @@ -532,7 +532,7 @@ impl McpTool for TasksHandler { match req.action { TaskAction::Add => { let title = req.title.ok_or_else(|| { - crate::error::AppError::Internal("title is required for 'add' action".to_string()) + crate::error::AppError::Internal("Missing required parameter 'title' for action 'add'. Next step: Provide non-empty 'title' string in request and retry.".to_string()) })?; let description = req.description.unwrap_or_default(); let add_args = serde_json::json!({ @@ -546,10 +546,10 @@ impl McpTool for TasksHandler { } TaskAction::Update => { let id = req.id.ok_or_else(|| { - crate::error::AppError::Internal("id is required for 'update' action".to_string()) + crate::error::AppError::Internal("Missing required parameter 'id' for action 'update'. Next step: Provide task 'id' string in request and retry.".to_string()) })?; let status = req.status.ok_or_else(|| { - crate::error::AppError::Internal("status is required for 'update' action".to_string()) + crate::error::AppError::Internal("Missing required parameter 'status' for action 'update'. Next step: Provide valid 'status' ('pending', 'completed', or 'cancelled') in request and retry.".to_string()) })?; let update_args = serde_json::json!({ "id": id, @@ -559,7 +559,7 @@ impl McpTool for TasksHandler { } TaskAction::Delete => { let id = req.id.ok_or_else(|| { - crate::error::AppError::Internal("id is required for 'delete' action".to_string()) + crate::error::AppError::Internal("Missing required parameter 'id' for action 'delete'. Next step: Provide task 'id' string in request and retry.".to_string()) })?; let del_args = serde_json::json!({ "id": id, @@ -576,10 +576,10 @@ impl McpTool for TasksHandler { } TaskAction::SetCriteria => { let id = req.id.ok_or_else(|| { - crate::error::AppError::Internal("id is required for 'set_criteria' action".to_string()) + crate::error::AppError::Internal("Missing required parameter 'id' for action 'set_criteria'. Next step: Provide task 'id' string in request and retry.".to_string()) })?; let criteria = req.criteria.ok_or_else(|| { - crate::error::AppError::Internal("criteria array is required for 'set_criteria' action".to_string()) + crate::error::AppError::Internal("Missing required parameter 'criteria' for action 'set_criteria'. Next step: Provide array of acceptance criteria descriptions in request and retry.".to_string()) })?; let set_args = serde_json::json!({ "id": id, @@ -589,7 +589,7 @@ impl McpTool for TasksHandler { } TaskAction::Verify => { let id = req.id.ok_or_else(|| { - crate::error::AppError::Internal("id is required for 'verify' action".to_string()) + crate::error::AppError::Internal("Missing required parameter 'id' for action 'verify'. Next step: Provide task 'id' string in request and retry.".to_string()) })?; let verify_args = serde_json::json!({ "id": id, @@ -620,7 +620,7 @@ impl McpTool for MilestonesHandler { match req.action { MilestoneAction::Add => { let title = req.title.ok_or_else(|| { - crate::error::AppError::Internal("title is required for 'add' action".to_string()) + crate::error::AppError::Internal("Missing required parameter 'title' for action 'add'. Next step: Provide non-empty 'title' string in request and retry.".to_string()) })?; let add_args = serde_json::json!({ "title": title, @@ -630,10 +630,10 @@ impl McpTool for MilestonesHandler { } MilestoneAction::Update => { let id = req.id.ok_or_else(|| { - crate::error::AppError::Internal("id is required for 'update' action".to_string()) + crate::error::AppError::Internal("Missing required parameter 'id' for action 'update'. Next step: Provide milestone 'id' string in request and retry.".to_string()) })?; let status = req.status.ok_or_else(|| { - crate::error::AppError::Internal("status is required for 'update' action".to_string()) + crate::error::AppError::Internal("Missing required parameter 'status' for action 'update'. Next step: Provide milestone 'status' in request and retry.".to_string()) })?; let update_args = serde_json::json!({ "id": id, diff --git a/server/src/handlers/workspaces.rs b/server/src/handlers/workspaces.rs index 5c08aee..e79691a 100644 --- a/server/src/handlers/workspaces.rs +++ b/server/src/handlers/workspaces.rs @@ -496,13 +496,13 @@ impl McpTool for PinnedFilesHandler { match req.action { PinnedFileAction::Pin => { let path = req.path.ok_or_else(|| { - crate::error::AppError::Internal("path is required for 'pin' action".to_string()) + crate::error::AppError::Internal("Missing required parameter 'path' for action 'pin'. Next step: Provide absolute or relative file 'path' in request and retry.".to_string()) })?; PinFileHandler.execute(serde_json::json!({"file_path": path, "namespace": ns}), state).await } PinnedFileAction::Unpin => { let path = req.path.ok_or_else(|| { - crate::error::AppError::Internal("path is required for 'unpin' action".to_string()) + crate::error::AppError::Internal("Missing required parameter 'path' for action 'unpin'. Next step: Provide file 'path' in request and retry.".to_string()) })?; UnpinFileHandler.execute(serde_json::json!({"file_path": path, "namespace": ns}), state).await } @@ -534,7 +534,7 @@ impl McpTool for ContextWorkspacesHandler { match req.action { ContextWorkspaceAction::Save => { let name = req.name.ok_or_else(|| { - crate::error::AppError::Internal("name is required for 'save' action".to_string()) + crate::error::AppError::Internal("Missing required parameter 'name' for action 'save'. Next step: Provide workspace 'name' string in request and retry.".to_string()) })?; let pinned_files = req.pinned_files.unwrap_or_default(); let active_task_ids = req.active_task_ids.unwrap_or_default(); @@ -550,7 +550,7 @@ impl McpTool for ContextWorkspacesHandler { } ContextWorkspaceAction::Load => { let name = req.name.ok_or_else(|| { - crate::error::AppError::Internal("name is required for 'load' action".to_string()) + crate::error::AppError::Internal("Missing required parameter 'name' for action 'load'. Next step: Provide workspace 'name' string in request and retry.".to_string()) })?; LoadContextWorkspaceHandler.execute(serde_json::json!({"name": name, "namespace": ns}), state).await } @@ -559,16 +559,16 @@ impl McpTool for ContextWorkspacesHandler { } ContextWorkspaceAction::Delete => { let name = req.name.ok_or_else(|| { - crate::error::AppError::Internal("name is required for 'delete' action".to_string()) + crate::error::AppError::Internal("Missing required parameter 'name' for action 'delete'. Next step: Provide workspace 'name' string in request and retry.".to_string()) })?; DeleteContextWorkspaceHandler.execute(serde_json::json!({"name": name, "namespace": ns}), state).await } ContextWorkspaceAction::Diff => { let name = req.name.ok_or_else(|| { - crate::error::AppError::Internal("name is required for 'diff' action".to_string()) + crate::error::AppError::Internal("Missing required parameter 'name' for action 'diff'. Next step: Provide primary workspace 'name' in request and retry.".to_string()) })?; let other = req.other_name.ok_or_else(|| { - crate::error::AppError::Internal("other_name is required for 'diff' action".to_string()) + crate::error::AppError::Internal("Missing required parameter 'other_name' for action 'diff'. Next step: Provide secondary workspace 'other_name' in request and retry.".to_string()) })?; DiffContextWorkspacesHandler.execute(serde_json::json!({"workspace_a": name, "workspace_b": other, "namespace": ns}), state).await } @@ -597,7 +597,7 @@ impl McpTool for PrChecklistHandler { match req.action { PrChecklistAction::Add => { let desc = req.description.ok_or_else(|| { - crate::error::AppError::Internal("description is required for 'add' action".to_string()) + crate::error::AppError::Internal("Missing required parameter 'description' for action 'add'. Next step: Provide checklist item 'description' string in request and retry.".to_string()) })?; AddPrChecklistItemHandler.execute(serde_json::json!({"description": desc, "namespace": ns}), state).await } @@ -631,7 +631,7 @@ impl McpTool for SnippetsHandler { match req.action { SnippetAction::Store => { let name = req.query.or(req.id).ok_or_else(|| { - crate::error::AppError::Internal("name is required for 'store' action".to_string()) + crate::error::AppError::Internal("Missing required parameter 'query' or 'id' as snippet name for action 'store'. Next step: Provide snippet name in 'query' field and retry.".to_string()) })?; let lang = req.language.unwrap_or_else(|| "text".to_string()); let code = req.code.unwrap_or_default(); @@ -657,13 +657,13 @@ impl McpTool for SnippetsHandler { } SnippetAction::Delete => { let id = req.id.or(req.query).ok_or_else(|| { - crate::error::AppError::Internal("id/name is required for 'delete' action".to_string()) + crate::error::AppError::Internal("Missing required parameter 'id' or 'query' for action 'delete'. Next step: Provide snippet ID/name in request and retry.".to_string()) })?; DeleteSnippetHandler.execute(serde_json::json!({"name": id}), state).await } SnippetAction::Tag => { let id = req.id.or(req.query).ok_or_else(|| { - crate::error::AppError::Internal("id/name is required for 'tag' action".to_string()) + crate::error::AppError::Internal("Missing required parameter 'id' or 'query' for action 'tag'. Next step: Provide snippet ID/name and 'tags' array in request and retry.".to_string()) })?; let tags = req.tags.unwrap_or_default(); TagSnippetHandler.execute(serde_json::json!({"name": id, "tags": tags}), state).await diff --git a/server/src/instructions.md b/server/src/instructions.md index 102c2b2..fc12a2a 100644 --- a/server/src/instructions.md +++ b/server/src/instructions.md @@ -17,16 +17,78 @@ To prevent graph fragmentation and ensure seamless LLM context retrieval: --- -## 2. LLM Token Budgeting & RRF Search Optimization +## 2. Consolidated Smart Tools Architecture -* **Token Budgeting (`summary_level` & `max_tokens`)**: - When calling `list_active_tasks` or `list_tech_debt`, pass `summary_level: "compact"` or `"detailed"` and `max_tokens: 500` to constrain output size when token context budget is tight. -* **Reciprocal Rank Fusion (RRF) Omni-Search**: - `omni_search` uses Hybrid RRF (BM25 keyword search + Dense Vector Embeddings) to rank results semantically. You do not need exact keyword matches; query conceptually (e.g. "database lock issues"). -* **Delta Session Context (`memory://session/delta`)**: - Passively read `memory://session/delta` to get a succinct delta of code changes, tasks, and tech debt recorded during the current working session. -* **Context Warmup (`context_warmup`)**: - Trigger the `context_warmup` prompt at session start to automatically synthesize delta changes, active tasks, tech debt, and pinned files in a single pass. +The server consolidates granular single-purpose tools into domain-named smart tools. Always prefer the consolidated tools over legacy aliases: + +* **`tasks`**: Complete task lifecycle management. + - `action: "add"`: Create a new task (requires `title`, optional `description`, `git_branch`, `parent_id`, `dependencies`). + - `action: "update"`: Update task status (requires `id`, `status: "pending" | "completed" | "cancelled"`). + - `action: "delete"`: Delete task and child tasks (requires `id`). + - `action: "list"`: List active tasks (optional `git_branch`, `summary_level: "compact" | "detailed" | "full"`, `max_tokens`). + - `action: "set_criteria"`: Set acceptance criteria (requires `id`, `criteria: Vec`). + - `action: "verify"`: Verify criteria met (requires `id`). + +* **`milestones`**: Milestone tracking. + - `action: "add"`: Create milestone (requires `title`). + - `action: "update"`: Update milestone status (requires `id`, `status`). + - `action: "list"`: List milestones. + +* **`sticky_notes`**: Ephemeral scratchpad notes with TTL. + - `action: "add"`: Add note (requires `content`, optional `ttl_seconds`, `session_only`). + - `action: "read"`: Read all active notes. + - `action: "delete"`: Delete note by index (requires 1-based `index`). + - `action: "clear"`: Clear all sticky notes. + +* **`handoff_memos`**: Session handoff notes for future agents. + - `action: "leave"`: Leave a memo (requires `content`). + - `action: "read"`: Read active handoff memos. + - `action: "clear"`: Clear memos. + +* **`pinned_files`**: Focus file working set. + - `action: "pin"`: Pin file to focus set (requires `path`). + - `action: "unpin"`: Unpin file from focus set (requires `path`). + - `action: "list"`: List pinned files. + +* **`context_workspaces`**: Workspace context state snapshots. + - `action: "save"`: Save context workspace (requires `name`). + - `action: "load"`: Restore saved context workspace (requires `name`). + - `action: "list"`: List saved context workspaces. + - `action: "delete"`: Delete saved context workspace (requires `name`). + - `action: "diff"`: Compare two saved context workspaces (requires `name`, `other_name`). + +* **`pr_checklist`**: Pre-commit and PR checklist. + - `action: "add"`: Add checklist item (requires `description`). + - `action: "get"`: Get PR checklist items. + - `action: "clear"`: Clear PR checklist. + +* **`snippets`**: Reusable code snippet vault. + - `action: "store"`: Store snippet (requires `query` as name, optional `language`, `code`, `description`, `tags`). + - `action: "search"`: Search snippet vault (optional `query`, `tags`, `hybrid: true`). + - `action: "delete"`: Delete snippet (requires `id`). + - `action: "tag"`: Attach classification tags (requires `id`, `tags: Vec`). + +* **`decisions`**: Architectural Decision Records (ADRs). + - `action: "log"`: Log ADR (requires `title`, optional `status`, `context`, `decision`, `consequences`). + - `action: "query"`: Query ADRs (optional `query`). + - `action: "delete"`: Delete ADR (requires `id`). + +* **`tech_debt`**: Engineering debt backlog. + - `action: "log"`: Log debt item (requires `description`, optional `ideal_solution`, `git_commit`, `git_branch`, `symbol_references`, `line_range`). + - `action: "resolve"`: Resolve debt item (requires `id`). + - `action: "list"`: List debt items (optional `include_resolved`). + +* **`environment`**: Infrastructure and requirements tracking. + - `action: "update_fingerprint"`: Update tool versions. + - `action: "read_fingerprint"`: Read tool versions fingerprint. + - `action: "log_requirement"`: Log environment variable requirement (requires `key`). + - `action: "register"`: Register target environment (requires `name`). + - `action: "get_details"`: Read full environment details. + +* **`clipboard`**: OS Clipboard management. + - `action: "read"`: Read OS clipboard. + - `action: "write"`: Write text/html/files/image to clipboard. + - `action: "toggle_watch"`: Toggle auto-clipboard watcher. --- @@ -45,140 +107,27 @@ To prevent graph fragmentation and ensure seamless LLM context retrieval: --- ## 5. Memory State Checkpointing & Rollbacks -- **Tool:** `manage_checkpoint` (unifying `checkpoint_state`, `restore_state`, `create_snapshot`, `restore_snapshot`) +- **Tool:** `checkpoint_state`, `restore_state` (or `create_snapshot`, `restore_snapshot`) - **When to use:** Before initiating a large refactor, running experimental subagent tasks, or executing destructive batch operations. -- **Behavior:** Consolidates state snapshots and point-in-time checkpointers. Use `action: "create"`, `"restore"`, `"list"`, or `"delete"`. +- **Behavior:** Saves or restores a point-in-time snapshot of graph entities, active tasks, and tech debt backlogs. --- -## 6. Symbol Reference Backlinks -- **Tools:** `log_code_change`, `log_error_fix`, `log_tech_debt` -- **When to use:** When logging changes or debt tied to specific code symbols or line boundaries. -- **Behavior:** Accept `symbol_references` (e.g., `["MemoryState::new", "CreateEntitiesTool"]`) and `line_range` (e.g., `"L45-L90"`), automatically indexing code references for quick symbol backlink searches. - ---- - -## 7. Ephemeral Sticky Notes with TTL -- **Tool:** `manage_sticky_notes` (or granular `add_sticky_note`, `read_sticky_notes`, `delete_sticky_note`, `clear_sticky_notes`) -- **When to use:** For temporary scratchpad items, temporary ports, task IDs, or transient notes. -- **Behavior:** Supports `action: "add" | "read" | "delete" | "clear"`. Supports `ttl_seconds` for auto-expiration and `session_only: true` for automatic purging when the session ends. - ---- - -## 8. Snippet Vault & Domain Tagging -- **Tools:** `store_snippet`, `search_snippets`, `delete_snippet`, `tag_snippet` -- **When to use:** Store exact multi-line code snippets, Nushell pipelines, or frequently used CLI commands. -- **Behavior:** `search_snippets` supports `mode: "hybrid" | "keyword" | "semantic"` combining BM25 term frequency keyword matching with semantic tag scoring. Guarantees precise syntactic preservation. Use `tag_snippet` to attach domain tags (e.g., `["rust", "axum", "mcp"]`) for category-filtered searches. - ---- - -## 9. Context & Subagent Namespaces -- **Tools:** `manage_subagent_namespace` (unifying `create_subagent_namespace`, `condense_subagent_namespace`, `purge_subagent_namespace`) -- **When to use:** Isolate graph queries, tasks, and tech debt to specific project or subagent scopes. -- **Behavior:** `manage_subagent_namespace` manages subagent memory lifecycles (`action: "create" | "condense" | "purge"`). Condensing auto-promotes subagent entities/relations to the global Knowledge Graph. - ---- - -## 10. Architectural Decision Records (ADRs) -- **Tools:** `log_decision`, `query_decisions`, `delete_decision` -- **When to use:** Whenever making a non-trivial architectural, environmental, or design decision. -- **Behavior:** Permanently stores context, decision, and consequences to prevent future agents from second-guessing choices. - ---- - -## 11. Graph Refactoring & Algorithms -- **Tools:** `merge_entities`, `find_orphans`, `query_graph_path`, `condense_entity` -- **When to use:** Run `find_orphans` periodically to clean unused nodes. Use `merge_entities` to combine duplicate concepts. Use `query_graph_path` to find shortest relational connections between components. Use `condense_entity` when entity observation counts grow large. - ---- - -## 12. Dynamic Learned Preferences -- **Tools:** `learn_preference`, `read_preferences` -- **When to use:** When the user specifies personal or repository-specific preferences. -- **Behavior:** Stores key-value behavioral preferences that persist across agent invocations. - ---- - -## 13. Pinned Workspaces & Hot Files -- **Tools:** `pin_file`, `unpin_file`, `list_pinned_files` -- **When to use:** Pin 3–5 active working set files to maintain focus in large codebases. - ---- - -## 14. Agent Handoffs & Memos -- **Tools:** `leave_handoff_memo`, `read_handoff_memos`, `clear_handoff_memos` -- **When to use:** Leave messages for future agent sessions or inspect pending handoff notes upon waking. - ---- - -## 15. Real-time WebSocket Memory Sync -- **Endpoint:** `ws://127.0.0.1:3000/ws` -- **Behavior:** Broadcasts live state updates and activity notifications to the Brain Monitor UI in real time. - ---- - -## 16. Self-Healing Graph Health Sweeper +## 6. Self-Healing Graph Health Sweeper - **Tool:** `sweep_graph_health` - **When to use:** Periodically or before committing major graph changes to audit entity consistency. - **Behavior:** Detects orphaned nodes (0 relations), computes name similarity to identify near-duplicates (e.g., `APIGateway` vs `ApiGateway`), and provides structured `merge_entities` recommendations or auto-prunes orphans. --- -## 17. Causal Lineage & Provenance Tracker +## 7. Causal Lineage & Provenance Tracker - **Tool:** `query_lineage` - **When to use:** When asking *"Why was this component modified?"* or *"What task or ADR led to this code change?"* - **Behavior:** Searches across tasks, ADRs, audit ledger entries, and error fixes to assemble a unified chronological timeline explaining the provenance behind any file, symbol, or commit. --- -## 18. Topological Unblocked Task Resolver -- **Tool:** `get_next_actionable_tasks` -- **When to use:** When orchestrating subagent execution or selecting the next task to work on. -- **Behavior:** Evaluates task dependency DAGs and filters out any blocked tasks, returning only unblocked, actionable tasks ready for immediate execution. - ---- - -## 19. Chain-of-Thought & Diagnostic Hypothesis Memory -- **Tools:** `log_hypothesis`, `query_hypotheses` -- **When to use:** During complex debugging or root cause analysis. -- **Behavior:** Records hypotheses alongside tested evidence and status (`unverified`, `verified`, `rejected`). Allows subagents to query past diagnostic paths and avoid re-testing disproven hypotheses. - ---- - -## 20. Workspace Context Diffing -- **Tool:** `diff_context_workspaces` -- **When to use:** When switching branches or comparing two saved context workspaces. -- **Behavior:** Returns a structured delta highlighting added, removed, and shared pinned files and active task IDs between two context workspaces. - ---- - -## 21. Universal Token Guardrails -- **Behavior:** Automatically caps large MCP resource reads (e.g. `memory://graph/entities`) and list responses, adding summary headers (`"_meta": "Showing 100 of N items"`) to guarantee output stays within context window limits. - ---- - -## 22. LLM Pre-Flight Context Bundle +## 8. LLM Pre-Flight Context Bundle - **Tool:** `get_preflight_context` - **When to use:** At the start of a turn or subagent task to gain total situational awareness in 1 call. - **Behavior:** Aggregates current active branch, in-progress tasks with acceptance criteria, pinned files, top open tech debts, and active unverified hypotheses into a consolidated executive context bundle. - ---- - -## 23. Self-Healing Symbol & Line Range Resolver -- **Tool:** `resolve_stale_symbols` -- **When to use:** When files have been deleted, moved, or heavily refactored. -- **Behavior:** Verifies graph entities and tech debt symbol references against disk and AST, flagging and auto-healing stale pointers or broken file paths. - ---- - -## 24. Inter-Agent Signal Bus -- **Tools:** `broadcast_agent_signal`, `query_agent_signals` -- **When to use:** For real-time coordination and event-driven communication between concurrent subagents (e.g., `PrePushAuditor` signaling `AUDIT_PASSED` to parent agent). -- **Behavior:** Ephemeral TTL-backed signal bus storing structured agent events, payloads, and artifact URIs. - ---- - -## 25. Automated Session Checkpoint on Shutdown -- **Tool:** `auto_session_checkpoint` -- **When to use:** Executed automatically on `/shutdown` or manually when pausing a session. -- **Behavior:** Captures active tasks, unverified hypotheses, recent commit ledgers, and workspace state into a permanent `HandoffMemo` for seamless turn-taking and recovery. diff --git a/server/src/models.rs b/server/src/models.rs index 5f53ae2..51fdcaf 100644 --- a/server/src/models.rs +++ b/server/src/models.rs @@ -311,7 +311,6 @@ pub struct AgentSignal { #[cfg(test)] mod tests { - use super::*; use axum::http::StatusCode; use axum::response::IntoResponse; use crate::error::AppError; diff --git a/server/src/tools.rs b/server/src/tools.rs index c0874ef..1f7895d 100644 --- a/server/src/tools.rs +++ b/server/src/tools.rs @@ -140,7 +140,13 @@ pub enum StickyNoteAction { Clear, } -/// Ephemeral sticky notes with TTL (add, read, delete, clear). +/// Ephemeral sticky notes with TTL for scratchpad items, ports, and transient notes. +/// Actions: +/// - 'add': Add note. Required: content. Optional: ttl_seconds, session_only. +/// - 'read': Read all active notes. +/// - 'delete': Delete note. Required: index (1-based integer). +/// - 'clear': Clear all active notes. +/// Next steps on error: Ensure required fields for the specific action are supplied. #[derive(Debug, Deserialize, Serialize, JsonSchema)] pub struct StickyNotesTool { /// Action to perform: 'add', 'read', 'delete', or 'clear'. @@ -1093,7 +1099,12 @@ pub enum HandoffMemoAction { Clear, } -/// Manage handoff memos across sessions (leave, read, clear). +/// Persistent handoff memos for passing session context to future agents. +/// Actions: +/// - 'leave': Post a handoff memo. Required: content. Optional: namespace. +/// - 'read': Inspect active memos. Optional: namespace. +/// - 'clear': Clear memos. Optional: namespace, ids. +/// Next steps on error: Check parameter requirements for 'leave' or 'clear' actions. #[derive(Debug, Deserialize, Serialize, JsonSchema)] pub struct HandoffMemosTool { /// Action to perform: 'leave', 'read', or 'clear'. @@ -1117,7 +1128,15 @@ pub enum TaskAction { Verify, } -/// Consolidated task management (add, update, delete, list, set_criteria, verify). +/// Action-oriented task tracking system (add, update, delete, list, set_criteria, verify). +/// Actions: +/// - 'add': Create task. Required: title. Optional: description, git_branch, parent_id, dependencies. +/// - 'update': Update task status. Required: id, status ('pending'|'completed'|'cancelled'). +/// - 'delete': Delete task & subtasks. Required: id. +/// - 'list': List active tasks. Optional: git_branch, summary_level ('compact'|'detailed'|'full'), max_tokens. +/// - 'set_criteria': Set acceptance criteria. Required: id, criteria (array of strings). +/// - 'verify': Verify criteria met. Required: id. +/// Next steps on error: Check required parameters or call list to verify task IDs. #[derive(Debug, Deserialize, Serialize, JsonSchema)] pub struct TasksTool { /// Action to perform: 'add', 'update', 'delete', 'list', 'set_criteria', or 'verify'. @@ -1126,7 +1145,7 @@ pub struct TasksTool { pub id: Option, /// Task title (required for 'add'). pub title: Option, - /// Task description (required for 'add'). + /// Task description (optional for 'add'). pub description: Option, /// New status: 'pending', 'completed', or 'cancelled' (for 'update'). pub status: Option, @@ -1152,7 +1171,12 @@ pub enum MilestoneAction { List, } -/// Consolidated milestone management (add, update, list). +/// Project milestone management (add, update, list). +/// Actions: +/// - 'add': Create milestone. Required: title. Optional: namespace. +/// - 'update': Update milestone status. Required: id, status. +/// - 'list': List milestones. Optional: namespace. +/// Next steps on error: Provide required title for 'add' or id/status for 'update'. #[derive(Debug, Deserialize, Serialize, JsonSchema)] pub struct MilestonesTool { /// Action to perform: 'add', 'update', or 'list'. @@ -1175,7 +1199,12 @@ pub enum PinnedFileAction { List, } -/// Consolidated pinned files focus management (pin, unpin, list). +/// Pinned working set files management (pin, unpin, list). +/// Actions: +/// - 'pin': Pin file to active focus set. Required: path. Optional: namespace. +/// - 'unpin': Unpin file from focus set. Required: path. Optional: namespace. +/// - 'list': List pinned files. Optional: namespace. +/// Next steps on error: Provide exact file path for pin/unpin operations. #[derive(Debug, Deserialize, Serialize, JsonSchema)] pub struct PinnedFilesTool { /// Action to perform: 'pin', 'unpin', or 'list'. @@ -1196,14 +1225,21 @@ pub enum ContextWorkspaceAction { Diff, } -/// Consolidated context workspace state management (save, load, list, delete, diff). +/// Context workspace snapshots management (save, load, list, delete, diff). +/// Actions: +/// - 'save': Save current pinned files & task IDs. Required: name. Optional: pinned_files, active_task_ids, namespace. +/// - 'load': Restore saved workspace state. Required: name. Optional: namespace. +/// - 'list': List saved context workspaces. Optional: namespace. +/// - 'delete': Delete saved workspace. Required: name. Optional: namespace. +/// - 'diff': Compare two context workspaces. Required: name, other_name. Optional: namespace. +/// Next steps on error: Check workspace name or list existing workspaces first. #[derive(Debug, Deserialize, Serialize, JsonSchema)] pub struct ContextWorkspacesTool { /// Action to perform: 'save', 'load', 'list', 'delete', or 'diff'. pub action: ContextWorkspaceAction, - /// Workspace name. + /// Workspace name (required for 'save', 'load', 'delete', 'diff'). pub name: Option, - /// Second workspace name (for 'diff'). + /// Second workspace name (required for 'diff'). pub other_name: Option, /// Pinned file paths (for 'save'). pub pinned_files: Option>, @@ -1221,7 +1257,12 @@ pub enum PrChecklistAction { Clear, } -/// Consolidated PR checklist management (add, get, clear). +/// Pre-commit and Pull Request checklist management (add, get, clear). +/// Actions: +/// - 'add': Add PR checklist item. Required: description. Optional: namespace. +/// - 'get': Get PR checklist items. Optional: namespace. +/// - 'clear': Clear PR checklist. Optional: namespace. +/// Next steps on error: Provide description for 'add' action. #[derive(Debug, Deserialize, Serialize, JsonSchema)] pub struct PrChecklistTool { /// Action to perform: 'add', 'get', or 'clear'. @@ -1241,14 +1282,20 @@ pub enum SnippetAction { Tag, } -/// Consolidated reusable code snippets management (store, search, delete, tag). +/// Syntactically preserved reusable code snippets vault (store, search, delete, tag). +/// Actions: +/// - 'store': Store snippet. Required: query (or id) as snippet name. Optional: language, code, description, tags. +/// - 'search': Search snippets. Optional: query, tags, hybrid (boolean for BM25+vector search). +/// - 'delete': Delete snippet. Required: id (or query) as snippet name. +/// - 'tag': Tag snippet. Required: id (or query), tags (array of strings). +/// Next steps on error: Ensure snippet name/query or id is provided. #[derive(Debug, Deserialize, Serialize, JsonSchema)] pub struct SnippetsTool { /// Action to perform: 'store', 'search', 'delete', or 'tag'. pub action: SnippetAction, - /// Snippet ID (required for 'delete', 'tag'). + /// Snippet ID or name (required for 'delete', 'tag'). pub id: Option, - /// Search query or snippet name. + /// Search query or snippet name (required for 'store'). pub query: Option, /// Snippet language (for 'store'). pub language: Option, @@ -1270,7 +1317,12 @@ pub enum DecisionAction { Delete, } -/// Consolidated Architectural Decision Records (ADRs) management (log, query, delete). +/// Architectural Decision Records (ADRs) log (log, query, delete). +/// Actions: +/// - 'log': Record ADR. Required: title. Optional: status, context, decision, consequences, namespace. +/// - 'query': Search ADRs. Optional: query, namespace. +/// - 'delete': Remove ADR. Required: id. +/// Next steps on error: Provide title for 'log' or id for 'delete'. #[derive(Debug, Deserialize, Serialize, JsonSchema)] pub struct DecisionsTool { /// Action to perform: 'log', 'query', or 'delete'. @@ -1279,13 +1331,13 @@ pub struct DecisionsTool { pub id: Option, /// ADR title (required for 'log'). pub title: Option, - /// ADR status (required for 'log'). + /// ADR status (for 'log'). pub status: Option, - /// Context & problem statement (required for 'log'). + /// Context & problem statement (for 'log'). pub context: Option, - /// Decision made (required for 'log'). + /// Decision made (for 'log'). pub decision: Option, - /// Consequences & tradeoffs (required for 'log'). + /// Consequences & tradeoffs (for 'log'). pub consequences: Option, /// Search query string (for 'query'). pub query: Option, @@ -1301,7 +1353,12 @@ pub enum TechDebtAction { List, } -/// Consolidated technical debt management (log, resolve, list). +/// Technical debt backlog management (log, resolve, list). +/// Actions: +/// - 'log': Record technical debt. Required: description. Optional: ideal_solution, git_commit, git_branch, symbol_references, line_range, namespace. +/// - 'resolve': Mark tech debt resolved. Required: id. +/// - 'list': List tech debt items. Optional: include_resolved, namespace. +/// Next steps on error: Provide description for 'log' or valid ID for 'resolve'. #[derive(Debug, Deserialize, Serialize, JsonSchema)] pub struct TechDebtTool { /// Action to perform: 'log', 'resolve', or 'list'. @@ -1310,7 +1367,7 @@ pub struct TechDebtTool { pub id: Option, /// Tech debt description (required for 'log'). pub description: Option, - /// Ideal solution (required for 'log'). + /// Ideal solution (optional for 'log'). pub ideal_solution: Option, /// Include resolved tech debt items (for 'list'). pub include_resolved: Option, @@ -1336,20 +1393,27 @@ pub enum EnvAction { GetDetails, } -/// Consolidated environment & infrastructure management (update_fingerprint, read_fingerprint, log_requirement, register, get_details). +/// Environment requirements, tool fingerprints & infrastructure management. +/// Actions: +/// - 'update_fingerprint': Update tool versions. Optional: tool_versions map, namespace. +/// - 'read_fingerprint': Read current environment fingerprint. Optional: namespace. +/// - 'log_requirement': Log environment variable requirement. Required: key. Optional: description, is_secret, namespace. +/// - 'register': Register remote target environment. Required: name. Optional: url, description, requires_vpn, namespace. +/// - 'get_details': Get full environment details. Optional: namespace. +/// Next steps on error: Provide key for 'log_requirement' or name for 'register'. #[derive(Debug, Deserialize, Serialize, JsonSchema)] pub struct EnvironmentTool { - /// Action to perform. + /// Action to perform: 'update_fingerprint', 'read_fingerprint', 'log_requirement', 'register', or 'get_details'. pub action: EnvAction, /// Map of tool names to versions (for 'update_fingerprint'). pub tool_versions: Option>, - /// Env variable key (for 'log_requirement'). + /// Env variable key (required for 'log_requirement'). pub key: Option, /// Description (for 'log_requirement', 'register'). pub description: Option, /// Secret flag (for 'log_requirement'). pub is_secret: Option, - /// Environment name (for 'register'). + /// Environment name (required for 'register'). pub name: Option, /// Environment URL (for 'register'). pub url: Option, @@ -1367,7 +1431,12 @@ pub enum ClipboardAction { ToggleWatch, } -/// Consolidated OS clipboard management (read, write, toggle_watch). +/// OS Clipboard management (read, write, toggle_watch). +/// Actions: +/// - 'read': Read current clipboard contents. +/// - 'write': Write content to OS clipboard. Optional: text, html, files, image_path. +/// - 'toggle_watch': Enable or disable auto-clipboard ingestion. Optional: enabled (bool). +/// Next steps on error: Provide text/html/files/image_path when calling 'write'. #[derive(Debug, Deserialize, Serialize, JsonSchema)] pub struct ClipboardTool { /// Action to perform: 'read', 'write', or 'toggle_watch'.