@vibescope/mcp-server 0.2.1 → 0.2.3

package/docs/TOOLS.md

@@ -0,0 +1,2053 @@
+# Vibescope MCP Tools Reference
+
+> Auto-generated from tool definitions. Do not edit manually.
+>
+> Generated: 2026-01-16
+>
+> Total tools: 132
+
+## Table of Contents
+
+- [session](#session) - Session lifecycle and monitoring (5 tools)
+- [project](#project) - Project CRUD and configuration (5 tools)
+- [tasks](#tasks) - Task management and tracking (10 tools)
+- [milestones](#milestones) - Task breakdown into steps (5 tools)
+- [progress](#progress) - Progress logging and activity (2 tools)
+- [blockers](#blockers) - Blocker management (4 tools)
+- [decisions](#decisions) - Architectural decisions (3 tools)
+- [ideas](#ideas) - Feature ideas tracking (5 tools)
+- [findings](#findings) - Audit findings/knowledge base (5 tools)
+- [validation](#validation) - Cross-agent task validation (3 tools)
+- [deployment](#deployment) - Deployment coordination (16 tools)
+- [fallback](#fallback) - Background activities when idle (4 tools)
+- [bodies_of_work](#bodies-of-work) - Group tasks into bodies of work (12 tools)
+- [sprints](#sprints) - Time-bounded sprints with velocity tracking (11 tools)
+- [requests](#requests) - User request handling (3 tools)
+- [organizations](#organizations) - Organization and team management (13 tools)
+- [cost](#cost) - Cost monitoring and alerts (6 tools)
+- [git_issues](#git-issues) - Git conflict and issue tracking (4 tools)
+- [knowledge](#knowledge) - Queryable knowledge base from project data (1 tools)
+- [discovery](#discovery) - Tool discovery and documentation (2 tools)
+- [subtasks](#subtasks) - Break tasks into smaller pieces (2 tools)
+- [worktrees](#worktrees) - Git worktree management (2 tools)
+- [roles](#roles) - Agent role management (4 tools)
+- [file_locks](#file-locks) - File checkout/locking for multi-agent (5 tools)
+
+## session
+
+*Session lifecycle and monitoring*
+
+### start_work_session
+
+CALL THIS FIRST when beginning work on a project.
+
+Returns session info, persona, role, and next_task. Start the next_task IMMEDIATELY without asking the user.
+
+Use mode:'full' for complete context, mode:'lite' (default) for minimal tokens.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | No | Project UUID |
+| `git_url` | `string` | No | Git repository URL. Used to find project if project_id not provided. |
+| `mode` | `"lite" | "full"` | No | Response mode: lite (default, minimal tokens) or full (complete context) |
+| `model` | `"opus" | "sonnet" | "haiku"` | No | Claude model being used (for accurate cost tracking). E.g., "opus", "sonnet", "haiku". |
+| `role` | `"developer" | "validator" | "deployer" | "reviewer" | "maintainer"` | No | Agent role: developer (general work, default), validator (task validation), deployer (deployments), reviewer (code review), maintainer (housekeeping) |
+
+---
+
+### get_help
+
+Get guidance on a specific topic. Use when unsure about workflows.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `topic` | `"getting_started" | "tasks" | "validation" | "deployment" | "git" | "blockers" | "milestones" | "fallback" | "session" | "tokens" | "roles" | "knowledge" | "topics"` | Yes | Help topic. Use "topics" to list all available. |
+
+---
+
+### get_token_usage
+
+Get token usage stats for this session. Monitor efficiency.
+
+**Parameters:** None
+
+---
+
+### heartbeat
+
+Send heartbeat to maintain 'active' status. Call every 30-60 seconds.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `session_id` | `string` | No | Session ID from start_work_session (optional, uses current session if not provided) |
+| `current_worktree_path` | `string,null` | No | Report your current git worktree path (e.g., "../project-task-abc123"). Set to null to clear. |
+
+---
+
+### end_work_session
+
+End session and release claimed tasks. Returns session summary.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `session_id` | `string` | No | Session ID to end (optional, uses current session if not provided) |
+
+---
+
+## project
+
+*Project CRUD and configuration*
+
+### get_project_context
+
+Get full project context: goals, instructions, tasks, blockers, decisions.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | No | Project UUID. If not provided, will list all projects. |
+| `git_url` | `string` | No | Git repository URL. Used to find project if project_id not provided. |
+
+---
+
+### get_git_workflow
+
+Get git workflow config and branching instructions for the project.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | Yes | Project UUID |
+| `task_id` | `string` | No | Optional task ID to include branch naming suggestion |
+
+---
+
+### create_project
+
+Create a new project to track in Vibescope.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `name` | `string` | Yes | Project display name |
+| `description` | `string` | No | Brief project description |
+| `goal` | `string` | No | What does "done" look like for this project? |
+| `git_url` | `string` | No | Git repository URL (if available) |
+| `tech_stack` | `string[]` | No | Technologies used (e.g., ["TypeScript", "React", "PostgreSQL"]) |
+
+---
+
+### update_project
+
+Update project details (name, description, goal, settings).
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | Yes | Project UUID |
+| `name` | `string` | No |  |
+| `description` | `string` | No |  |
+| `goal` | `string` | No |  |
+| `git_url` | `string` | No |  |
+| `tech_stack` | `string[]` | No |  |
+| `status` | `"active" | "paused" | "completed" | "archived"` | No |  |
+| `git_workflow` | `"none" | "trunk-based" | "github-flow" | "git-flow"` | No | Git workflow: none (no branching), trunk-based (commit to main), github-flow (feature branches + PR), git-flow (develop/release branches) |
+| `git_main_branch` | `string` | No | Main branch name (default: main) |
+| `git_develop_branch` | `string` | No | Development branch name (used with git-flow) |
+| `git_auto_branch` | `boolean` | No | Automatically create feature branches for new tasks |
+| `git_auto_tag` | `boolean` | No | Automatically tag deployments on main branch |
+| `git_auto_commit_on_complete` | `boolean` | No | Agents must commit changes after completing tasks |
+| `git_auto_pr_on_complete` | `boolean` | No | Agents must create PR after completing tasks |
+| `deployment_instructions` | `string` | No | Instructions for how to deploy (e.g., "Push to main for Vercel auto-deploy", "Run fly deploy") |
+
+---
+
+### update_project_readme
+
+Sync README content to the dashboard.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | Yes | Project UUID |
+| `readme_content` | `string` | Yes | README content in markdown format |
+
+---
+
+## tasks
+
+*Task management and tracking*
+
+### get_tasks
+
+Get tasks for a project, optionally filtered by status. By default returns only root tasks (not subtasks).
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | Yes | Project UUID |
+| `status` | `"backlog" | "pending" | "in_progress" | "completed" | "cancelled"` | No | Filter by status (optional) |
+| `limit` | `number` | No | Max number of tasks to return (default 50) |
+| `include_subtasks` | `boolean` | No | Include subtasks in results (default false). Use get_subtasks for subtasks of a specific task. |
+| `include_metadata` | `boolean` | No | When true, returns all task fields (description, progress, timestamps, etc.). When false (default), returns only id/title/priority/status to save tokens. |
+
+---
+
+### get_next_task
+
+Get highest priority pending task. Start it IMMEDIATELY by calling update_task(task_id, status: "in_progress").
+
+Do NOT ask the user for permission. Follow the directive in the response.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | Yes | Project UUID |
+
+---
+
+### add_task
+
+Add a new task. Priority 1=highest, 5=lowest. Include estimated_minutes. Use blocking=true for deployment finalization tasks that must complete before other work.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | Yes | Project UUID |
+| `title` | `string` | Yes | Task title |
+| `description` | `string` | No | Detailed description |
+| `priority` | `number` | No | Priority 1-5 (1 = highest) (min: 1, max: 5) |
+| `estimated_minutes` | `number` | No | Estimated time to complete in minutes (min: 1) |
+| `blocking` | `boolean` | No | When true, this task blocks all other work until complete (used for deployment finalization) |
+| `model_capability` | `"haiku" | "sonnet" | "opus"` | No | Recommended model capability: haiku (simple tasks), sonnet (standard), opus (complex reasoning) |
+
+---
+
+### update_task
+
+Update task status, progress, or details. Include progress_note with progress_percentage.
+
+IMPORTANT: When setting status to "in_progress", you MUST provide git_branch AND worktree_path to enable cleanup tracking.
+
+Create worktree first: git worktree add ../PROJECT-task-TASKID -b feature/TASKID-description BASE_BRANCH
+
+Then call: update_task(task_id, status: "in_progress", git_branch: "feature/TASKID-description", worktree_path: "../PROJECT-task-TASKID")
+
+For projects without git branching (trunk-based or none), use skip_worktree_requirement: true.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `task_id` | `string` | Yes | Task UUID |
+| `title` | `string` | No |  |
+| `description` | `string` | No |  |
+| `priority` | `number` | No | (min: 1, max: 5) |
+| `status` | `"backlog" | "pending" | "in_progress" | "completed" | "cancelled"` | No |  |
+| `progress_percentage` | `number` | No | 0-100 completion percentage (min: 0, max: 100) |
+| `progress_note` | `string` | No | Brief note (auto-logged) |
+| `estimated_minutes` | `number` | No | Revised time estimate (min: 1) |
+| `git_branch` | `string` | No | Git branch associated with this task. REQUIRED when status is "in_progress" (unless skip_worktree_requirement is true) |
+| `worktree_path` | `string` | No | Git worktree path for this task (e.g., "../project-task-abc123"). Store this for cleanup tracking across sessions. |
+| `model_capability` | `"haiku" | "sonnet" | "opus"` | No | Recommended model capability: haiku (simple tasks), sonnet (standard), opus (complex reasoning) |
+| `skip_worktree_requirement` | `boolean` | No | Skip git_branch requirement for projects without branching workflows (trunk-based or none). Default: false |
+
+---
+
+### complete_task
+
+Mark task done. Returns next_task which you MUST start immediately without asking the user.
+
+CRITICAL: After calling this tool, you must:
+
+1. If next_task is returned → Start it immediately by calling update_task(task_id, status: "in_progress")
+
+2. If no next_task → Call get_next_task() or start a fallback_activity
+
+3. NEVER ask the user "What should I do next?" or "Should I continue?"
+
+The auto_continue: true flag in the response means you are expected to continue working autonomously.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `task_id` | `string` | Yes | Task UUID |
+| `summary` | `string` | No | Brief summary of what was done |
+
+---
+
+### delete_task
+
+Delete a task.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `task_id` | `string` | Yes | Task UUID |
+
+---
+
+### batch_update_tasks
+
+Update multiple tasks at once. Include progress_note with progress_percentage.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `updates` | `object[]` | Yes | Array of task updates to apply |
+
+---
+
+### batch_complete_tasks
+
+Mark multiple tasks as completed at once.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `completions` | `object[]` | Yes | Array of task completions |
+
+---
+
+### add_task_reference
+
+Add a reference URL to a task (docs, PRs, issues).
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `task_id` | `string` | Yes | Task UUID |
+| `url` | `string` | Yes | URL to add as reference |
+| `label` | `string` | No | Optional label/title for the reference |
+
+---
+
+### remove_task_reference
+
+Remove a reference link from a task by URL.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `task_id` | `string` | Yes | Task UUID |
+| `url` | `string` | Yes | URL of the reference to remove |
+
+---
+
+## milestones
+
+*Task breakdown into steps*
+
+### add_milestone
+
+Add a milestone to a task.
+
+Milestones help break down large tasks into smaller trackable steps.
+
+Use this to show progress on complex tasks and help gauge completion.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `task_id` | `string` | Yes | Task UUID to add milestone to |
+| `title` | `string` | Yes | Milestone title (brief description of what needs to be done) |
+| `description` | `string` | No | Optional detailed description |
+| `order_index` | `number` | No | Order of this milestone (0-based, defaults to end of list) (min: 0) |
+
+---
+
+### update_milestone
+
+Update a milestone's title, description, status, or order.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `milestone_id` | `string` | Yes | Milestone UUID |
+| `title` | `string` | No | Updated title |
+| `description` | `string` | No | Updated description |
+| `status` | `"pending" | "in_progress" | "completed"` | No | Milestone status |
+| `order_index` | `number` | No | Updated order (min: 0) |
+
+---
+
+### complete_milestone
+
+Mark a milestone as completed. This is a convenience wrapper for update_milestone with status=completed.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `milestone_id` | `string` | Yes | Milestone UUID |
+
+---
+
+### delete_milestone
+
+Delete a milestone from a task.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `milestone_id` | `string` | Yes | Milestone UUID |
+
+---
+
+### get_milestones
+
+Get all milestones for a task, ordered by order_index.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `task_id` | `string` | Yes | Task UUID |
+
+---
+
+## progress
+
+*Progress logging and activity*
+
+### log_progress
+
+Log progress update. Record significant milestones or observations.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | Yes | Project UUID |
+| `task_id` | `string` | No | Task UUID (optional, links progress to specific task) |
+| `summary` | `string` | Yes | Brief summary of progress |
+| `details` | `string` | No | Detailed notes (optional) |
+
+---
+
+### get_activity_feed
+
+Get combined activity feed (tasks, progress, blockers, decisions) in chronological order.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | Yes | Project UUID |
+| `types` | `string[]` | No | Filter by activity types (default: all) |
+| `created_by` | `"agent" | "user"` | No | Filter by creator (default: all) |
+| `since` | `string` | No | ISO date string - only return activity after this time |
+| `limit` | `number` | No | Max number of items to return (default 50, max 200) |
+
+---
+
+## blockers
+
+*Blocker management*
+
+### add_blocker
+
+Record a blocker preventing progress.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | Yes | Project UUID |
+| `description` | `string` | Yes | What is blocking progress? |
+
+---
+
+### resolve_blocker
+
+Mark a blocker as resolved.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `blocker_id` | `string` | Yes | Blocker UUID |
+| `resolution_note` | `string` | No | How was it resolved? |
+
+---
+
+### get_blockers
+
+Get blockers for a project, optionally filtered by status.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | Yes | Project UUID |
+| `status` | `"open" | "resolved"` | No | Filter by status (default: open) |
+
+---
+
+### delete_blocker
+
+Delete a blocker.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `blocker_id` | `string` | Yes | Blocker UUID |
+
+---
+
+## decisions
+
+*Architectural decisions*
+
+### log_decision
+
+Record an architectural or technical decision with rationale.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | Yes | Project UUID |
+| `title` | `string` | Yes | Decision title (e.g., "Use PostgreSQL for database") |
+| `description` | `string` | Yes | What was decided |
+| `rationale` | `string` | No | Why this decision was made |
+| `alternatives_considered` | `string[]` | No | Other options that were considered |
+
+---
+
+### get_decisions
+
+Get recorded decisions for a project.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | Yes | Project UUID |
+
+---
+
+### delete_decision
+
+Delete a decision.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `decision_id` | `string` | Yes | Decision UUID |
+
+---
+
+## ideas
+
+*Feature ideas tracking*
+
+### add_idea
+
+Record an idea for improvements or features. Starts as 'raw', can progress to 'shipped'.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | Yes | Project UUID |
+| `title` | `string` | Yes | Idea title |
+| `description` | `string` | No | Detailed description |
+| `status` | `"raw" | "exploring" | "planned" | "in_development" | "shipped"` | No | Development stage (default: raw) |
+
+---
+
+### update_idea
+
+Update an idea's status or details.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `idea_id` | `string` | Yes | Idea UUID |
+| `title` | `string` | No | Updated title |
+| `description` | `string` | No | Updated description |
+| `status` | `"raw" | "exploring" | "planned" | "in_development" | "shipped"` | No | New development stage |
+| `doc_url` | `string` | No | URL to feature documentation/specification |
+
+---
+
+### get_ideas
+
+Get recorded ideas for a project, optionally filtered by status.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | Yes | Project UUID |
+| `status` | `"raw" | "exploring" | "planned" | "in_development" | "shipped"` | No | Filter by status (optional) |
+| `limit` | `number` | No | Max number of ideas to return (default 50, max 100) |
+| `offset` | `number` | No | Number of ideas to skip for pagination (default 0) |
+| `search_query` | `string` | No | Search ideas by title or description |
+
+---
+
+### delete_idea
+
+Delete an idea.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `idea_id` | `string` | Yes | Idea UUID |
+
+---
+
+### convert_idea_to_task
+
+Convert an idea to a task. Creates a task from the idea's title and description, links them, and optionally updates the idea status to 'in_development'. Useful for planned ideas that are ready for implementation.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `idea_id` | `string` | Yes | Idea UUID to convert |
+| `priority` | `number` | No | Task priority 1-5 (default: 3, 1 = highest) (min: 1, max: 5) |
+| `estimated_minutes` | `number` | No | Estimated time to complete in minutes (min: 1) |
+| `update_status` | `boolean` | No | Update idea status to 'in_development' (default: true) |
+
+---
+
+## findings
+
+*Audit findings/knowledge base*
+
+### add_finding
+
+Record a finding from an audit/review (performance, security, code quality, etc).
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | Yes | Project UUID |
+| `category` | `"performance" | "security" | "code_quality" | "accessibility" | "documentation" | "architecture" | "testing" | "other"` | No | Category of the finding (default: other) |
+| `title` | `string` | Yes | Brief title describing the finding |
+| `description` | `string` | No | Detailed description of the finding, including impact and suggested fix |
+| `severity` | `"info" | "low" | "medium" | "high" | "critical"` | No | Severity level (default: info) |
+| `file_path` | `string` | No | File path where the issue was found (optional) |
+| `line_number` | `number` | No | Line number in the file (optional) |
+| `related_task_id` | `string` | No | ID of related task if this finding came from a task (optional) |
+
+---
+
+### get_findings
+
+Get findings for a project, optionally filtered by category, severity, or status. Use summary_only=true to reduce token usage by returning only essential fields (id, title, category, severity, status). For just counts, use get_findings_stats instead.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | Yes | Project UUID |
+| `category` | `"performance" | "security" | "code_quality" | "accessibility" | "documentation" | "architecture" | "testing" | "other"` | No | Filter by category (optional) |
+| `severity` | `"info" | "low" | "medium" | "high" | "critical"` | No | Filter by severity (optional) |
+| `status` | `"open" | "addressed" | "dismissed" | "wontfix"` | No | Filter by status (default: open) |
+| `limit` | `number` | No | Max number of findings to return (default 50, max 200) |
+| `offset` | `number` | No | Number of findings to skip for pagination (default 0) |
+| `search_query` | `string` | No | Search findings by title |
+| `summary_only` | `boolean` | No | When true, returns only id, title, category, severity, status (reduces tokens by ~80%). Default: false |
+
+---
+
+### get_findings_stats
+
+Get aggregate statistics about findings for a project. Returns total count and breakdowns by status, severity, and category. Much more token-efficient than get_findings when you just need to understand the overall state.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | Yes | Project UUID |
+
+---
+
+### update_finding
+
+Update a finding's status or details. Use to mark findings as addressed or dismissed.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `finding_id` | `string` | Yes | Finding UUID |
+| `status` | `"open" | "addressed" | "dismissed" | "wontfix"` | No | New status |
+| `resolution_note` | `string` | No | Note explaining how the finding was addressed or why it was dismissed |
+| `title` | `string` | No | Updated title |
+| `description` | `string` | No | Updated description |
+| `severity` | `"info" | "low" | "medium" | "high" | "critical"` | No | Updated severity |
+
+---
+
+### delete_finding
+
+Delete a finding.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `finding_id` | `string` | Yes | Finding UUID |
+
+---
+
+## validation
+
+*Cross-agent task validation*
+
+### get_tasks_awaiting_validation
+
+Get completed tasks not yet validated.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | Yes | Project UUID |
+
+---
+
+### claim_validation
+
+Claim a completed task for review. Shows "being reviewed" on dashboard.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `task_id` | `string` | Yes | Task UUID to claim for review |
+
+---
+
+### validate_task
+
+Validate a completed task. Include test results in validation_notes. For github-flow/git-flow projects, a PR must exist before approval (add via add_task_reference).
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `task_id` | `string` | Yes | Task UUID to validate |
+| `validation_notes` | `string` | No | Notes about the validation (what was checked, any issues found) |
+| `approved` | `boolean` | Yes | Whether the task passes validation (true = approved, false = needs more work) |
+| `skip_pr_check` | `boolean` | No | Skip PR existence check (use only for tasks that legitimately do not need a PR) |
+
+---
+
+## deployment
+
+*Deployment coordination*
+
+### request_deployment
+
+Request a deployment. Requires validation first. One active deployment per project.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | Yes | Project UUID |
+| `environment` | `"development" | "staging" | "production"` | No | Target environment (default: production) |
+| `version_bump` | `"patch" | "minor" | "major"` | No | Version bump: major/minor/patch (default: patch) |
+| `notes` | `string` | No | Optional notes about this deployment |
+| `git_ref` | `string` | No | Git branch or commit being deployed |
+
+---
+
+### claim_deployment_validation
+
+Claim pending deployment for validation. Run build+tests, then call report_validation.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | Yes | Project UUID |
+
+---
+
+### report_validation
+
+Report build/test results. If passed, status->'ready'. If failed, creates investigation task.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | Yes | Project UUID |
+| `build_passed` | `boolean` | Yes | Whether the build succeeded |
+| `tests_passed` | `boolean` | Yes | Whether the tests passed |
+| `error_message` | `string` | No | Error details if validation failed |
+
+---
+
+### check_deployment_status
+
+Get active deployment status and details.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | Yes | Project UUID |
+
+---
+
+### start_deployment
+
+Start deployment (requires 'ready' status). Sets status to 'deploying'.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | Yes | Project UUID |
+
+---
+
+### complete_deployment
+
+Mark deployment as complete (success or failure).
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | Yes | Project UUID |
+| `success` | `boolean` | Yes | Whether the deployment succeeded |
+| `summary` | `string` | No | Summary of what was deployed or why it failed |
+
+---
+
+### cancel_deployment
+
+Cancel active deployment. Sets status to 'failed'.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | Yes | Project UUID |
+| `reason` | `string` | No | Reason for cancellation |
+
+---
+
+### add_deployment_requirement
+
+Add a pre-deployment requirement (migration, env var, config change). These are shown as a checklist before deployment.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | Yes | Project UUID |
+| `type` | `"migration" | "env_var" | "config" | "manual" | "breaking_change" | "agent_task"` | Yes | Type of requirement |
+| `title` | `string` | Yes | Brief description (e.g., "Run migration: 20250114_token_tracking.sql") |
+| `description` | `string` | No | Optional detailed instructions |
+| `file_path` | `string` | No | Optional file path reference |
+| `stage` | `"preparation" | "deployment" | "verification"` | No | Deployment stage: preparation (default), deployment, or verification |
+| `blocking` | `boolean` | No | When true, converted task blocks all other work until complete |
+| `recurring` | `boolean` | No | When true, requirement resets to pending when a new deployment is requested |
+
+---
+
+### complete_deployment_requirement
+
+Mark a deployment requirement as completed.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `requirement_id` | `string` | Yes | Requirement UUID |
+
+---
+
+### get_deployment_requirements
+
+Get pending deployment requirements for a project.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | Yes | Project UUID |
+| `status` | `"pending" | "completed" | "converted_to_task" | "all"` | No | Filter by status (default: pending) |
+| `stage` | `"preparation" | "deployment" | "verification" | "all"` | No | Filter by stage (optional) |
+
+---
+
+### schedule_deployment
+
+Schedule a deployment for a specific time. Supports one-time and recurring schedules with auto-trigger or manual trigger modes.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | Yes | Project UUID |
+| `scheduled_at` | `string` | Yes | ISO 8601 datetime for when the deployment should be triggered |
+| `schedule_type` | `"once" | "hourly" | "daily" | "weekly" | "monthly"` | No | Schedule type: once (one-time), hourly, daily, weekly, or monthly |
+| `hours_interval` | `number` | No | For hourly schedules, the number of hours between runs (1-24, default: 1) (min: 1, max: 24) |
+| `auto_trigger` | `boolean` | No | Whether agents should automatically trigger this deployment when due (default: true) |
+| `environment` | `"development" | "staging" | "production"` | No | Target environment (default: production) |
+| `version_bump` | `"patch" | "minor" | "major"` | No | Version bump: patch, minor, or major (default: patch) |
+| `notes` | `string` | No | Optional notes about this scheduled deployment |
+| `git_ref` | `string` | No | Optional git branch or commit to deploy |
+
+---
+
+### get_scheduled_deployments
+
+Get scheduled deployments for a project.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | Yes | Project UUID |
+| `include_disabled` | `boolean` | No | Include disabled schedules (default: false) |
+
+---
+
+### update_scheduled_deployment
+
+Update a scheduled deployment's configuration.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `schedule_id` | `string` | Yes | Schedule UUID |
+| `scheduled_at` | `string` | No | New scheduled time (ISO 8601) |
+| `schedule_type` | `"once" | "hourly" | "daily" | "weekly" | "monthly"` | No | New schedule type |
+| `hours_interval` | `number` | No | For hourly schedules, the number of hours between runs (1-24) (min: 1, max: 24) |
+| `auto_trigger` | `boolean` | No | Whether to auto-trigger |
+| `enabled` | `boolean` | No | Enable or disable the schedule |
+| `environment` | `"development" | "staging" | "production"` | No | Target environment |
+| `version_bump` | `"patch" | "minor" | "major"` | No | Version bump type |
+| `notes` | `string` | No | Notes about this deployment |
+| `git_ref` | `string` | No | Git branch or commit to deploy |
+
+---
+
+### delete_scheduled_deployment
+
+Delete a scheduled deployment.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `schedule_id` | `string` | Yes | Schedule UUID |
+
+---
+
+### trigger_scheduled_deployment
+
+Manually trigger a scheduled deployment. Creates a new deployment and updates the schedule.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `schedule_id` | `string` | Yes | Schedule UUID |
+
+---
+
+### check_due_deployments
+
+Check for scheduled deployments that are due. Returns schedules where: enabled AND auto_trigger AND scheduled_at <= NOW().
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | Yes | Project UUID |
+
+---
+
+## fallback
+
+*Background activities when idle*
+
+### start_fallback_activity
+
+Start a background activity when no tasks available.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | Yes | Project UUID |
+| `activity` | `"feature_ideation" | "code_review" | "performance_audit" | "ux_review" | "cost_analysis" | "security_review" | "test_coverage" | "documentation_review" | "dependency_audit" | "validate_completed_tasks"` | Yes | The fallback activity type (e.g., code_review, security_review) |
+
+---
+
+### stop_fallback_activity
+
+Stop current fallback activity. Auto-clears when starting a regular task.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | Yes | Project UUID |
+| `summary` | `string` | No | Optional summary of what was accomplished during this activity |
+
+---
+
+### get_activity_history
+
+Get background activity completion history.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | Yes | Project UUID |
+| `activity_type` | `string` | No | Optional: filter to a specific activity type |
+| `limit` | `number` | No | Max number of history entries to return (default 50) |
+
+---
+
+### get_activity_schedules
+
+Get background activity schedules.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | Yes | Project UUID |
+
+---
+
+## bodies_of_work
+
+*Group tasks into bodies of work*
+
+### create_body_of_work
+
+Create a new body of work to group tasks into phases (pre/core/post).
+
+Bodies of work allow organizing related tasks with optional auto-deployment on completion.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | Yes | Project UUID |
+| `title` | `string` | Yes | Title for the body of work |
+| `description` | `string` | No | Optional description |
+| `auto_deploy_on_completion` | `boolean` | No | Automatically request deployment when all tasks complete (default: false) |
+| `deploy_environment` | `"development" | "staging" | "production"` | No | Target environment for auto-deploy (default: production) |
+| `deploy_version_bump` | `"patch" | "minor" | "major"` | No | Version bump for auto-deploy (default: minor) |
+| `deploy_trigger` | `"all_completed" | "all_completed_validated"` | No | When to trigger auto-deploy: all_completed (immediate) or all_completed_validated (requires validation, default) |
+
+---
+
+### update_body_of_work
+
+Update a body of work's settings.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `body_of_work_id` | `string` | Yes | Body of work UUID |
+| `title` | `string` | No | Updated title |
+| `description` | `string` | No | Updated description |
+| `auto_deploy_on_completion` | `boolean` | No | Auto-deploy setting |
+| `deploy_environment` | `"development" | "staging" | "production"` | No | Target environment |
+| `deploy_version_bump` | `"patch" | "minor" | "major"` | No | Version bump type |
+| `deploy_trigger` | `"all_completed" | "all_completed_validated"` | No | When to trigger auto-deploy |
+
+---
+
+### get_body_of_work
+
+Get a body of work with all its tasks organized by phase.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `body_of_work_id` | `string` | Yes | Body of work UUID |
+
+---
+
+### get_bodies_of_work
+
+List bodies of work for a project with task counts per phase.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | Yes | Project UUID |
+| `status` | `"draft" | "active" | "completed" | "cancelled"` | No | Filter by status (optional) |
+
+---
+
+### delete_body_of_work
+
+Delete a body of work. Tasks are preserved but no longer grouped.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `body_of_work_id` | `string` | Yes | Body of work UUID |
+
+---
+
+### add_task_to_body_of_work
+
+Add a task to a body of work in a specific phase.
+
+Phases control execution order: pre tasks run first, then core, then post.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `body_of_work_id` | `string` | Yes | Body of work UUID |
+| `task_id` | `string` | Yes | Task UUID to add |
+| `phase` | `"pre" | "core" | "post"` | No | Task phase (default: core) |
+| `order_index` | `number` | No | Order within phase (auto-assigned if not specified) |
+
+---
+
+### remove_task_from_body_of_work
+
+Remove a task from its body of work. The task is preserved.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `task_id` | `string` | Yes | Task UUID to remove |
+
+---
+
+### activate_body_of_work
+
+Activate a draft body of work to start execution.
+
+Requires at least one task. Once active, tasks can be worked on following phase order.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `body_of_work_id` | `string` | Yes | Body of work UUID |
+
+---
+
+### add_task_dependency
+
+Add a dependency between tasks in a body of work.
+
+The dependent task cannot start until the dependency is completed. Prevents circular dependencies.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `body_of_work_id` | `string` | Yes | Body of work UUID |
+| `task_id` | `string` | Yes | Task that depends on another task |
+| `depends_on_task_id` | `string` | Yes | Task that must complete first |
+
+---
+
+### remove_task_dependency
+
+Remove a dependency between tasks.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `task_id` | `string` | Yes | Task UUID |
+| `depends_on_task_id` | `string` | Yes | Dependency task UUID |
+
+---
+
+### get_task_dependencies
+
+Get task dependencies for a body of work or specific task.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `body_of_work_id` | `string` | No | Body of work UUID (optional if task_id provided) |
+| `task_id` | `string` | No | Specific task UUID (optional if body_of_work_id provided) |
+
+---
+
+### get_next_body_of_work_task
+
+Get the next available task from a body of work.
+
+Considers phase order (pre → core → post) and task dependencies.
+
+Only returns tasks where all dependencies are completed.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `body_of_work_id` | `string` | Yes | Body of work UUID |
+
+---
+
+## sprints
+
+*Time-bounded sprints with velocity tracking*
+
+### create_sprint
+
+Create a new sprint. Sprints are time-bounded bodies of work with velocity tracking.
+
+Sprints start in 'planning' status where tasks can be added with story points.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | Yes | Project UUID |
+| `title` | `string` | Yes | Sprint title (e.g., "Sprint 5" or "Q1 Release") |
+| `goal` | `string` | No | Sprint goal statement |
+| `start_date` | `string` | Yes | Start date (YYYY-MM-DD) |
+| `end_date` | `string` | Yes | End date (YYYY-MM-DD) |
+| `auto_deploy_on_completion` | `boolean` | No | Automatically request deployment when sprint completes (default: false) |
+| `deploy_environment` | `"development" | "staging" | "production"` | No | Target environment for auto-deploy (default: production) |
+| `deploy_version_bump` | `"patch" | "minor" | "major"` | No | Version bump for auto-deploy (default: minor) |
+
+---
+
+### update_sprint
+
+Update a sprint's details. Can update title, goal, dates, and deployment settings.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `sprint_id` | `string` | Yes | Sprint UUID |
+| `title` | `string` | No | New sprint title |
+| `goal` | `string` | No | New sprint goal |
+| `start_date` | `string` | No | New start date (YYYY-MM-DD) |
+| `end_date` | `string` | No | New end date (YYYY-MM-DD) |
+| `auto_deploy_on_completion` | `boolean` | No | Auto-deploy setting |
+| `deploy_environment` | `"development" | "staging" | "production"` | No | Target environment |
+| `deploy_version_bump` | `"patch" | "minor" | "major"` | No | Version bump type |
+
+---
+
+### get_sprint
+
+Get a sprint with all its tasks organized by phase (pre/core/post).
+
+Includes progress percentage, velocity points, and committed points.
+
+Use summary_only: true to get task counts and next task instead of full task arrays (saves tokens).
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `sprint_id` | `string` | Yes | Sprint UUID |
+| `summary_only` | `boolean` | No | Return task counts and next task instead of full task arrays (default: false) |
+
+---
+
+### get_sprints
+
+List sprints for a project with velocity metrics.
+
+Returns sprints sorted by sprint_number descending (most recent first).
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | Yes | Project UUID |
+| `status` | `"planning" | "active" | "in_review" | "retrospective" | "completed" | "cancelled"` | No | Filter by sprint status (optional) |
+| `limit` | `number` | No | Max sprints to return (default: 20, max: 100) |
+
+---
+
+### delete_sprint
+
+Delete a sprint. Tasks are preserved but no longer grouped.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `sprint_id` | `string` | Yes | Sprint UUID |
+
+---
+
+### start_sprint
+
+Start a sprint. Transitions from 'planning' to 'active' status.
+
+Locks the committed_points at the current total story points.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `sprint_id` | `string` | Yes | Sprint UUID |
+
+---
+
+### complete_sprint
+
+Complete a sprint. Handles retrospective phase and auto-deployment if configured.
+
+Status flow: active → in_review → retrospective → completed
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `sprint_id` | `string` | Yes | Sprint UUID |
+| `retrospective_notes` | `string` | No | Sprint retrospective notes |
+| `skip_retrospective` | `boolean` | No | Skip retrospective phase and go directly to completed (default: false) |
+
+---
+
+### add_task_to_sprint
+
+Add a task to a sprint with optional story points.
+
+Tasks can be added during 'planning' status. Story points contribute to committed_points.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `sprint_id` | `string` | Yes | Sprint UUID |
+| `task_id` | `string` | Yes | Task UUID to add |
+| `story_points` | `number` | No | Story point estimate (optional, must be non-negative integer) |
+| `phase` | `"pre" | "core" | "post"` | No | Task phase (default: core) |
+
+---
+
+### remove_task_from_sprint
+
+Remove a task from a sprint. Task is preserved but returns to backlog.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `sprint_id` | `string` | Yes | Sprint UUID |
+| `task_id` | `string` | Yes | Task UUID to remove |
+
+---
+
+### get_sprint_backlog
+
+Get tasks from backlog/pending that can be added to a sprint.
+
+Returns tasks not already assigned to any body of work or sprint.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | Yes | Project UUID |
+| `sprint_id` | `string` | No | Sprint UUID to exclude already-added tasks (optional) |
+
+---
+
+### get_sprint_velocity
+
+Get velocity metrics for completed sprints.
+
+Returns committed vs completed points and average velocity.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | Yes | Project UUID |
+| `limit` | `number` | No | Number of sprints to analyze (default: 10, max: 50) |
+
+---
+
+## requests
+
+*User request handling*
+
+### get_pending_requests
+
+Get unacknowledged user requests for this agent/project.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | Yes | Project UUID |
+
+---
+
+### acknowledge_request
+
+Mark a user request as handled.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `request_id` | `string` | Yes | Request UUID to acknowledge |
+
+---
+
+### answer_question
+
+Answer a question from the user. Use this when the user has asked a question via the dashboard.
+
+The answer will be displayed to the user and the question marked as answered.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `request_id` | `string` | Yes | Request UUID of the question to answer |
+| `answer` | `string` | Yes | Your answer to the user's question |
+
+---
+
+## organizations
+
+*Organization and team management*
+
+### list_organizations
+
+List organizations the current user belongs to.
+
+**Parameters:** None
+
+---
+
+### create_organization
+
+Create a new organization. You become the owner.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `name` | `string` | Yes | Organization display name |
+| `description` | `string` | No | Brief description of the organization |
+| `slug` | `string` | No | URL-friendly identifier (auto-generated from name if not provided) |
+
+---
+
+### update_organization
+
+Update organization details. Requires admin role.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `organization_id` | `string` | Yes | Organization UUID |
+| `name` | `string` | No | New organization name |
+| `description` | `string` | No | New description |
+| `logo_url` | `string` | No | URL to organization logo |
+
+---
+
+### delete_organization
+
+Delete an organization. Requires owner role. Removes all shares.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `organization_id` | `string` | Yes | Organization UUID |
+
+---
+
+### list_org_members
+
+List members of an organization.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `organization_id` | `string` | Yes | Organization UUID |
+
+---
+
+### invite_member
+
+Invite a user to an organization by email. Requires admin role.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `organization_id` | `string` | Yes | Organization UUID |
+| `email` | `string` | Yes | Email address to invite |
+| `role` | `"admin" | "member" | "viewer"` | No | Role to assign (default: member) |
+
+---
+
+### update_member_role
+
+Change a member's role. Requires admin role. Cannot change owner.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `organization_id` | `string` | Yes | Organization UUID |
+| `user_id` | `string` | Yes | User UUID to update |
+| `role` | `"admin" | "member" | "viewer"` | Yes | New role to assign |
+
+---
+
+### remove_member
+
+Remove a member from an organization. Requires admin role.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `organization_id` | `string` | Yes | Organization UUID |
+| `user_id` | `string` | Yes | User UUID to remove |
+
+---
+
+### leave_organization
+
+Leave an organization. Owner cannot leave without transferring ownership.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `organization_id` | `string` | Yes | Organization UUID |
+
+---
+
+### share_project_with_org
+
+Share a project with an organization. You must own the project.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | Yes | Project UUID |
+| `organization_id` | `string` | Yes | Organization UUID to share with |
+| `permission` | `"read" | "write" | "admin"` | No | Permission level (default: read) |
+
+---
+
+### update_project_share
+
+Update the permission level for a project share.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | Yes | Project UUID |
+| `organization_id` | `string` | Yes | Organization UUID |
+| `permission` | `"read" | "write" | "admin"` | Yes | New permission level |
+
+---
+
+### unshare_project
+
+Remove a project share from an organization.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | Yes | Project UUID |
+| `organization_id` | `string` | Yes | Organization UUID |
+
+---
+
+### list_project_shares
+
+List all organizations a project is shared with.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | Yes | Project UUID |
+
+---
+
+## cost
+
+*Cost monitoring and alerts*
+
+### get_cost_summary
+
+Get cost summary (daily/weekly/monthly) for a project.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | Yes | Project UUID |
+| `period` | `"daily" | "weekly" | "monthly"` | No | Summary period (default: daily) |
+| `limit` | `number` | No | Max records to return (default: 30) |
+
+---
+
+### get_cost_alerts
+
+Get cost alerts for the current user.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | No | Filter by project (optional) |
+
+---
+
+### add_cost_alert
+
+Add a cost alert threshold.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | No | Project UUID (null for all projects) |
+| `threshold_amount` | `number` | Yes | Amount in USD that triggers the alert |
+| `threshold_period` | `"daily" | "weekly" | "monthly"` | Yes | Period for the threshold |
+| `alert_type` | `"warning" | "critical"` | No | Alert severity (default: warning) |
+
+---
+
+### update_cost_alert
+
+Update a cost alert.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `alert_id` | `string` | Yes | Alert UUID |
+| `threshold_amount` | `number` | No | New threshold amount in USD |
+| `threshold_period` | `"daily" | "weekly" | "monthly"` | No | New period |
+| `alert_type` | `"warning" | "critical"` | No | New alert type |
+| `enabled` | `boolean` | No | Enable or disable the alert |
+
+---
+
+### delete_cost_alert
+
+Delete a cost alert.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `alert_id` | `string` | Yes | Alert UUID to delete |
+
+---
+
+### get_task_costs
+
+Get cost breakdown by task for a project.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | Yes | Project UUID |
+| `limit` | `number` | No | Max tasks to return (default: 20) |
+
+---
+
+## git_issues
+
+*Git conflict and issue tracking*
+
+### add_git_issue
+
+Record a git-related issue (merge conflict, push failure, etc.). Auto-created by claim_validation when conflicts detected.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | Yes | Project UUID |
+| `issue_type` | `"merge_conflict" | "push_failed" | "rebase_needed" | "branch_diverged" | "pr_not_mergeable"` | Yes | Type of git issue |
+| `branch` | `string` | Yes | Branch where the issue occurred |
+| `target_branch` | `string` | No | Target branch for merge/rebase (optional) |
+| `pr_url` | `string` | No | Pull request URL if applicable (optional) |
+| `conflicting_files` | `string[]` | No | List of files with conflicts (optional) |
+| `error_message` | `string` | No | Error message from git operation (optional) |
+| `task_id` | `string` | No | Related task UUID (optional) |
+
+---
+
+### resolve_git_issue
+
+Mark a git issue as resolved.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `git_issue_id` | `string` | Yes | Git issue UUID |
+| `resolution_note` | `string` | No | How the issue was resolved (optional) |
+| `auto_resolved` | `boolean` | No | Whether this was auto-resolved (e.g., PR became mergeable) |
+
+---
+
+### get_git_issues
+
+Get git issues for a project, optionally filtered by status, type, or branch.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | Yes | Project UUID |
+| `status` | `"open" | "resolved"` | No | Filter by status (default: open) |
+| `issue_type` | `"merge_conflict" | "push_failed" | "rebase_needed" | "branch_diverged" | "pr_not_mergeable"` | No | Filter by issue type (optional) |
+| `branch` | `string` | No | Filter by branch (optional) |
+| `limit` | `number` | No | Max issues to return (default: 50) |
+
+---
+
+### delete_git_issue
+
+Delete a git issue.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `git_issue_id` | `string` | Yes | Git issue UUID |
+
+---
+
+## knowledge
+
+*Queryable knowledge base from project data*
+
+### query_knowledge_base
+
+Query aggregated project knowledge in a single call. Returns findings, Q&A, decisions, completed tasks, and resolved blockers. Use this instead of multiple separate tool calls to reduce token usage.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | Yes | Project UUID |
+| `scope` | `"summary" | "detailed"` | No | Response detail level: summary (default) or detailed (includes rationales) |
+| `categories` | `string[]` | No | Categories to include (default: all). Filter to reduce response size. |
+| `limit` | `number` | No | Max items per category (default: 5, max: 20) |
+| `search_query` | `string` | No | Optional text search across all knowledge |
+
+---
+
+## discovery
+
+*Tool discovery and documentation*
+
+### discover_tools
+
+List tools by category. Use get_tool_info for details.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `category` | `"session" | "project" | "tasks" | "milestones" | "progress" | "blockers" | "decisions" | "ideas" | "findings" | "validation" | "deployment" | "fallback" | "bodies_of_work" | "sprints" | "requests" | "organizations" | "cost" | "git_issues" | "knowledge" | "discovery" | "subtasks" | "worktrees" | "roles" | "file_locks"` | No | Category to list (omit for all categories) |
+
+---
+
+### get_tool_info
+
+Get detailed tool documentation.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `tool_name` | `string` | Yes | Tool name |
+
+---
+
+## subtasks
+
+*Break tasks into smaller pieces*
+
+### add_subtask
+
+Add a subtask to break down a larger task into smaller workable pieces.
+
+Subtasks can be claimed and worked on independently by any agent.
+
+Subtasks inherit the project from their parent task.
+
+Max depth is 1 (subtasks cannot have their own subtasks).
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `parent_task_id` | `string` | Yes | UUID of the parent task to add subtask to |
+| `title` | `string` | Yes | Subtask title |
+| `description` | `string` | No | Detailed description (optional) |
+| `priority` | `number` | No | Priority 1-5 (1 = highest). Defaults to parent task priority. (min: 1, max: 5) |
+| `estimated_minutes` | `number` | No | Estimated time to complete in minutes (min: 1) |
+
+---
+
+### get_subtasks
+
+Get subtasks for a parent task.
+
+Returns subtasks with aggregate completion stats.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `parent_task_id` | `string` | Yes | UUID of the parent task |
+| `status` | `"backlog" | "pending" | "in_progress" | "completed" | "cancelled"` | No | Filter by status (optional) |
+
+---
+
+## worktrees
+
+*Git worktree management*
+
+### get_stale_worktrees
+
+Get worktrees that need cleanup.
+
+Returns tasks with worktree_path set where:
+
+- Task is completed or cancelled (worktree should have been cleaned up)
+
+- Task has been abandoned (no activity for 24+ hours while in_progress)
+
+IMPORTANT: Call this on session start to clean up orphaned worktrees from previous sessions.
+
+For each stale worktree:
+
+1. Run: git worktree remove <worktree_path>
+
+2. Call: clear_worktree_path(task_id)
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | Yes | Project UUID |
+
+---
+
+### clear_worktree_path
+
+Clear the worktree_path from a task after cleanup.
+
+Call this AFTER removing the worktree with git worktree remove.
+
+This marks the task as cleaned up so it won't appear in get_stale_worktrees.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `task_id` | `string` | Yes | Task UUID |
+
+---
+
+## roles
+
+*Agent role management*
+
+### get_role_settings
+
+Get role configuration for a project. Shows available roles and their settings.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | Yes | Project UUID |
+
+---
+
+### update_role_settings
+
+Update role settings for a project. Configure which roles are enabled and their behavior.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | Yes | Project UUID |
+| `role` | `"developer" | "validator" | "deployer" | "reviewer" | "maintainer"` | Yes | Role to configure |
+| `enabled` | `boolean` | No | Enable or disable this role |
+| `display_name` | `string` | No | Custom display name for this role |
+| `description` | `string` | No | Description of what this role does |
+| `priority_filter` | `number[]` | No | Only show tasks with these priorities (1-5) |
+| `fallback_activities` | `string[]` | No | Preferred fallback activities for this role |
+| `auto_assign_validation` | `boolean` | No | Auto-assign validation tasks to agents with this role |
+| `auto_assign_deployment` | `boolean` | No | Auto-assign deployment tasks to agents with this role |
+
+---
+
+### set_session_role
+
+Set the role for your current session. Changes task filtering and fallback activity suggestions.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `role` | `"developer" | "validator" | "deployer" | "reviewer" | "maintainer"` | Yes | Role to assign to this session |
+| `role_config` | `object` | No | Custom configuration for specialist role (optional) |
+
+---
+
+### get_agents_by_role
+
+Get active agents grouped by their assigned roles. See who is working on what.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | Yes | Project UUID |
+
+---
+
+## file_locks
+
+*File checkout/locking for multi-agent*
+
+### checkout_file
+
+Check out a file for editing. Prevents other agents from editing the same file until checked in. ALWAYS checkout files before making changes to prevent conflicts.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | Yes | Project UUID |
+| `file_path` | `string` | Yes | Relative path to the file to checkout (e.g., "src/index.ts") |
+| `reason` | `string` | No | Optional reason for checkout (e.g., "Fixing bug in login flow") |
+
+---
+
+### checkin_file
+
+Check in a file after editing. Releases the file for other agents to edit. ALWAYS checkin files when done editing.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `checkout_id` | `string` | No | Checkout UUID (from checkout_file response) |
+| `project_id` | `string` | No | Project UUID (alternative to checkout_id) |
+| `file_path` | `string` | No | File path (use with project_id as alternative to checkout_id) |
+| `summary` | `string` | No | Optional summary of changes made |
+
+---
+
+### get_file_checkouts
+
+Get list of file checkouts for a project. Shows which files are currently checked out and by whom.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | Yes | Project UUID |
+| `status` | `"checked_out" | "checked_in" | "abandoned"` | No | Filter by status (default: checked_out) |
+| `include_completed` | `boolean` | No | Include checked_in and abandoned checkouts (default: false) |
+| `limit` | `number` | No | Max checkouts to return (default: 50) |
+
+---
+
+### abandon_checkout
+
+Force-release a checkout. Use when the original agent session died or is stuck.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `checkout_id` | `string` | Yes | Checkout UUID to abandon |
+| `reason` | `string` | No | Reason for abandoning (e.g., "Agent session died") |
+
+---
+
+### is_file_available
+
+Check if a file is available for checkout. Returns who has it checked out if not available.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | Yes | Project UUID |
+| `file_path` | `string` | Yes | Path to the file to check |
+
+---