@vibescope/mcp-server 0.2.9 → 0.3.1

package/docs/TOOLS.md

@@ -1,2053 +1,2407 @@
-# 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 |
-
----
+# Vibescope MCP Tools Reference
+
+> Auto-generated from tool definitions. Do not edit manually.
+>
+> Generated: 2026-01-30
+>
+> Total tools: 152
+
+## Table of Contents
+
+- [session](#session) - Session lifecycle and monitoring (8 tools)
+- [project](#project) - Project CRUD and configuration (6 tools)
+- [tasks](#tasks) - Task management and tracking (16 tools)
+- [milestones](#milestones) - Task breakdown into steps (5 tools)
+- [progress](#progress) - Progress logging and activity (2 tools)
+- [blockers](#blockers) - Blocker management (6 tools)
+- [decisions](#decisions) - Architectural decisions (5 tools)
+- [ideas](#ideas) - Feature ideas tracking (6 tools)
+- [findings](#findings) - Audit findings/knowledge base (6 tools)
+- [validation](#validation) - Cross-agent task validation (3 tools)
+- [deployment](#deployment) - Deployment coordination (17 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 (10 tools)
+- [cost](#cost) - Cost monitoring and alerts (4 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 (6 tools)
+- [connectors](#connectors) - External integration connectors (7 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.
+
+IMPORTANT: If the user gives you direct work that isn't tracked as a task (e.g., "add feature X", "fix bug Y"), you MUST call add_task() first to create a task before starting work. This ensures all work is tracked and visible on the dashboard.
+
+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` | `string` | No | Model being used for cost tracking. E.g., "opus", "sonnet", "haiku" for Claude, "gemini" for Gemini, "gpt-4o" for OpenAI. |
+| `role` | `string` | No | Agent role (e.g., "developer", "validator", "deployer", "reviewer", "maintainer"). Custom roles accepted. |
+| `hostname` | `string` | No | Machine hostname for worktree tracking. Pass os.hostname() to filter stale worktrees to only those created on this machine. |
+| `agent_type` | `string` | No | Agent type (e.g., "claude", "gemini", "cursor", "windsurf"). Custom agent types accepted. |
+
+---
+
+### 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
+
+---
+
+### report_token_usage
+
+Report actual Claude API token usage for accurate cost tracking.
+
+IMPORTANT: MCP can only estimate tokens from tool I/O (~1-5% of actual usage). Call this tool after each API response to report actual usage from the Claude API response headers.
+
+The Claude API response includes 'usage.input_tokens' and 'usage.output_tokens' - pass those values here for accurate cost attribution.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `input_tokens` | `number` | Yes | Input tokens from Claude API response (usage.input_tokens) |
+| `output_tokens` | `number` | Yes | Output tokens from Claude API response (usage.output_tokens) |
+| `model` | `string` | No | Model used for this API call (optional, uses session model if not provided) |
+
+---
+
+### 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. |
+| `hostname` | `string` | No | Machine hostname (os.hostname()). Updates session hostname for worktree tracking. |
+
+---
+
+### signal_idle
+
+Signal that agent is idle (no more tasks). Call this when complete_task returns no next_task or when there's no work available. This provides real-time visibility on the dashboard instead of waiting for heartbeat timeout.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `session_id` | `string` | No | Session ID (optional, uses current session if not provided) |
+
+---
+
+### 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) |
+
+---
+
+### confirm_agent_setup
+
+Confirm that agent setup is complete for this project. Call this after creating your agent's configuration file (e.g., .claude/CLAUDE.md, .gemini/GEMINI.md).
+
+This marks your agent type as fully onboarded to the project, so you won't receive setup instructions again.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | Yes | Project UUID |
+| `agent_type` | `string` | Yes | Agent type that completed setup (e.g., "claude", "gemini", "cursor"). Custom agent types accepted. |
+
+---
+
+## 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_project_summary
+
+Get a unified project overview with aggregated stats. Token-efficient way to get task counts, blockers, findings, active agents, and more in a single call.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | Yes | Project UUID |
+
+---
+
+### 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 | Project name |
+| `description` | `string` | No | Project description |
+| `goal` | `string` | No | Project goal or objective |
+| `git_url` | `string` | No | Git repository URL |
+| `tech_stack` | `string[]` | No | List of technologies used in the project |
+| `status` | `"active" | "paused" | "completed" | "archived"` | No | Project status |
+| `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 |
+| `deployment_instructions` | `string` | No | Instructions for how to deploy (e.g., "Push to main for Vercel auto-deploy", "Run fly deploy") |
+| `git_delete_branch_on_merge` | `boolean` | No | Delete feature branch after PR merge (default: true) |
+| `require_pr_for_validation` | `boolean` | No | Require PR exists before task validation can be approved (default: true for github-flow/git-flow) |
+| `auto_merge_on_approval` | `boolean` | No | Automatically merge PR when validator approves (default: true) |
+| `validation_required` | `boolean` | No | Completed tasks require validation before being considered done (default: true) |
+| `default_task_priority` | `integer` | No | Default priority for new tasks when not specified (1=highest, 5=lowest, default: 3) (min: 1, max: 5) |
+| `require_time_estimates` | `boolean` | No | Require estimated_minutes when creating tasks (default: false) |
+| `fallback_activities_enabled` | `boolean` | No | Allow agents to perform background activities when no tasks available (default: true) |
+| `preferred_fallback_activities` | `string[]` | No | Array of preferred fallback activities (e.g., ["code_review", "security_review"]). Null means all allowed. |
+
+---
+
+### 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_task
+
+Get a single task by ID with optional subtasks and milestones.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `task_id` | `string` | Yes | Task UUID |
+| `include_subtasks` | `boolean` | No | Include subtasks array (default: false) |
+| `include_milestones` | `boolean` | No | Include milestones array (default: false) |
+
+---
+
+### search_tasks
+
+Search tasks by text query. Supports pagination with offset. Use for finding specific tasks by title or description.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | Yes | Project UUID |
+| `query` | `string` | Yes | Search query (min 2 chars). Searches title and description. |
+| `status` | `string[]` | No | Filter by status (optional, array) |
+| `limit` | `number` | No | Max results per page (1-20, default: 10) |
+| `offset` | `number` | No | Number of results to skip for pagination (default: 0) |
+
+---
+
+### get_tasks_by_priority
+
+Get tasks filtered by priority. Supports pagination with offset. Use for finding high-priority or low-priority tasks.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | Yes | Project UUID |
+| `priority` | `number` | No | Exact priority to match (1=highest, 5=lowest) (min: 1, max: 5) |
+| `priority_max` | `number` | No | Max priority (for range, e.g., priority=1, priority_max=2 gets P1 and P2) (min: 1, max: 5) |
+| `status` | `"backlog" | "pending" | "in_progress" | "completed" | "cancelled"` | No | Filter by status (default: pending) |
+| `limit` | `number` | No | Max results per page (1-20, default: 10) |
+| `offset` | `number` | No | Number of results to skip for pagination (default: 0) |
+
+---
+
+### get_recent_tasks
+
+Get tasks ordered by creation date. Supports pagination with offset. Use to find oldest pending tasks or newest additions.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | Yes | Project UUID |
+| `order` | `"newest" | "oldest"` | No | Sort order (default: newest) |
+| `status` | `"backlog" | "pending" | "in_progress" | "completed" | "cancelled"` | No | Filter by status (optional) |
+| `limit` | `number` | No | Max results per page (1-20, default: 10) |
+| `offset` | `number` | No | Number of results to skip for pagination (default: 0) |
+
+---
+
+### get_task_stats
+
+Get aggregate task statistics for a project. Returns counts by status and priority, no task data. Most token-efficient way to understand project state.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | Yes | Project UUID |
+
+---
+
+### 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.
+
+WHEN TO USE: If the user gives you work directly (e.g., "implement feature X", "fix this bug") that isn't already tracked as a task in Vibescope, you MUST create a task first using this tool. This ensures:
+
+- The work is visible on the dashboard
+
+- Progress can be tracked
+
+- Other agents won't duplicate the work
+
+- The human can see what you're working on
+
+**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.
+
+CRITICAL - WORKTREE REQUIRED: For projects using github-flow or git-flow, you MUST use a git worktree to isolate your work. This prevents conflicts with other agents working on the same repository.
+
+When setting status to "in_progress":
+
+1. Create worktree FIRST: git worktree add ../PROJECT-PERSONA-task-desc -b feature/TASKID-description BASE_BRANCH
+
+2. cd into the worktree directory
+
+3. THEN call update_task with git_branch AND worktree_path
+
+Example: update_task(task_id, status: "in_progress", git_branch: "feature/abc123-add-login", worktree_path: "../MyProject-Edge-add-login")
+
+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 | New task title |
+| `description` | `string` | No | New task description |
+| `priority` | `number` | No | Task priority (1=highest, 5=lowest) (min: 1, max: 5) |
+| `status` | `"backlog" | "pending" | "in_progress" | "completed" | "cancelled"` | No | Task status |
+| `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. |
+| `worktree_hostname` | `string` | No | Machine hostname where worktree was created (os.hostname()). Required with worktree_path to enable machine-aware cleanup. |
+| `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: Before calling complete_task on branching workflows (github-flow, git-flow):
+
+1. Create your PR targeting the correct branch (develop for git-flow, main for github-flow)
+
+2. Call add_task_reference(task_id, pr_url) to link the PR to your task
+
+3. THEN call complete_task - validators CANNOT approve tasks without a PR reference
+
+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. This is stored on the task as completion_summary and displayed when reviewing completed tasks. |
+
+---
+
+### delete_task
+
+Delete a task.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `task_id` | `string` | Yes | Task UUID |
+
+---
+
+### cancel_task
+
+Cancel a task with an optional reason. Use this when a task should be marked as cancelled rather than deleted (e.g., PR was closed, work was superseded). The task remains visible with a cancelled status for historical tracking.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `task_id` | `string` | Yes | Task UUID |
+| `cancelled_reason` | `"pr_closed" | "superseded" | "user_cancelled" | "validation_failed" | "obsolete" | "blocked"` | No | Reason for cancellation |
+| `cancellation_note` | `string` | No | Optional note explaining the cancellation (logged to progress) |
+
+---
+
+### release_task
+
+Release a claimed task back to pending status. Use when you need to give up a task you've started but cannot complete (e.g., context limits reached, conflicts with other work, user requested different approach). The task becomes available for other agents to claim.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `task_id` | `string` | Yes | Task UUID |
+| `reason` | `string` | No | Optional reason for releasing the task (logged to progress) |
+
+---
+
+### 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 10, 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_blocker
+
+Get a single blocker by ID. More token-efficient than get_blockers when you need details for a specific blocker.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `blocker_id` | `string` | Yes | Blocker UUID |
+
+---
+
+### 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) |
+| `limit` | `number` | No | Max number of blockers to return (default 10, max 200) |
+| `offset` | `number` | No | Number of blockers to skip for pagination (default 0) |
+| `search_query` | `string` | No | Search blockers by description |
+
+---
+
+### get_blockers_stats
+
+Get aggregate statistics about blockers for a project. Returns total count and breakdown by status. Much more token-efficient than get_blockers when you just need to understand the overall state.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | Yes | Project UUID |
+
+---
+
+### 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_decision
+
+Get a single decision by ID. More token-efficient than get_decisions when you need details for a specific decision.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `decision_id` | `string` | Yes | Decision UUID |
+
+---
+
+### get_decisions
+
+Get recorded decisions for a project.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | Yes | Project UUID |
+| `limit` | `number` | No | Max number of decisions to return (default 10, max 200) |
+| `offset` | `number` | No | Number of decisions to skip for pagination (default 0) |
+| `search_query` | `string` | No | Search decisions by title |
+
+---
+
+### get_decisions_stats
+
+Get aggregate statistics about decisions for a project. Returns total count. More token-efficient than get_decisions when you just need to know how many decisions exist.
+
+**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_idea
+
+Get a single idea by ID. More token-efficient than get_ideas when you need details for a specific idea.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `idea_id` | `string` | Yes | Idea UUID |
+
+---
+
+### 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 10, 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_finding
+
+Get a single finding by ID. More token-efficient than get_findings when you need details for a specific finding.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `finding_id` | `string` | Yes | Finding UUID |
+
+---
+
+### get_findings
+
+Get findings for a project, optionally filtered by category, severity, or status. Returns summary fields by default (id, title, category, severity, status). Set summary_only=false for full details. 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 10, 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 (default), returns only id, title, category, severity, status. Set to false for full details. |
+
+---
+
+### 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 and checks must pass before approval.
+
+**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) |
+| `pr_checks_passing` | `boolean` | No | REQUIRED when approving tasks with PRs. Confirm you verified PR checks are passing via `gh pr view <PR_NUMBER> --json statusCheckRollup`. Set to true only if all required checks pass. |
+| `skip_pr_check` | `boolean` | No | Skip PR existence check (use only for tasks that legitimately do not need a PR) |
+| `create_fix_task` | `boolean` | No | When rejecting (approved: false), create a new fix task linked to the original. The fix task will contain the rejection reason and be assigned the same git branch. |
+
+---
+
+## 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) |
+| `limit` | `number` | No | Max number of requirements to return (default 50, max 200) |
+| `offset` | `number` | No | Number of requirements to skip for pagination (default 0) |
+
+---
+
+### get_deployment_requirements_stats
+
+Get aggregate statistics about deployment requirements for a project. Returns total count and breakdowns by status, stage, and type. More token-efficient than get_deployment_requirements when you just need to understand the overall state.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | Yes | Project UUID |
+
+---
+
+### 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) |
+| `limit` | `number` | No | Max schedules to return (default: 50) |
+| `offset` | `number` | No | Number of schedules to skip for pagination (default: 0) |
+
+---
+
+### 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" | "worktree_cleanup"` | 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) |
+| `offset` | `number` | No | Number of entries to skip for pagination (default 0) |
+
+---
+
+### get_activity_schedules
+
+Get background activity schedules.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | Yes | Project UUID |
+| `limit` | `number` | No | Max schedules to return (default: 50) |
+| `offset` | `number` | No | Number of schedules to skip for pagination (default: 0) |
+
+---
+
+## 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 with pagination.
+
+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) |
+| `limit` | `number` | No | Max tasks to return (default: 20, max: 50) |
+| `offset` | `number` | No | Number of tasks to skip (default: 0) |
+
+---
+
+### 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 |
+| `limit` | `number` | No | Max number of requests to return (default 50, max 200) |
+| `offset` | `number` | No | Number of requests to skip for pagination (default 0) |
+
+---
+
+### 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*
+
+### 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 |
+
+---
+
+### 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 |
+
+---
+
+## 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) |
+
+---
+
+### 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 |
+
+---
+
+## 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) |
+| `offset` | `number` | No | Number of issues to skip for pagination (default 0) |
+
+---
+
+### 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 with pagination.
+
+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) |
+| `limit` | `number` | No | Max subtasks to return (default: 20, max: 50) |
+| `offset` | `number` | No | Number of subtasks to skip (default: 0) |
+
+---
+
+## 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: Pass hostname (os.hostname()) to only see worktrees created on THIS machine.
+
+Worktrees created on other machines cannot be removed locally.
+
+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 |
+| `hostname` | `string` | No | Machine hostname (os.hostname()). Only returns worktrees created on this machine, preventing attempts to clean up worktrees on other machines. |
+| `limit` | `number` | No | Max worktrees to return (default: 50) |
+| `offset` | `number` | No | Number of worktrees to skip for pagination (default: 0) |
+
+---
+
+### 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` | `string` | Yes | Role to configure (e.g., "developer", "validator", "deployer"). Custom roles accepted. |
+| `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` | `string` | Yes | Role to assign to this session (e.g., "developer", "validator", "deployer"). Custom roles accepted. |
+| `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 |
+| `counts_only` | `boolean` | No | When true (default), returns only counts per role to save tokens. Set to false for full agent details. |
+
+---
+
+## 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) |
+| `offset` | `number` | No | Number of checkouts to skip for pagination (default 0) |
+
+---
+
+### get_file_checkouts_stats
+
+Get aggregate statistics about file checkouts for a project. Returns counts by status without the actual checkout data. This is much more token-efficient than get_file_checkouts for understanding the overall state.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | Yes | Project UUID |
+
+---
+
+### 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 |
+
+---
+
+## connectors
+
+*External integration connectors*
+
+### get_connectors
+
+List connectors for a project. Connectors enable sending events to external services (Slack, Discord, webhooks, etc.).
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | Yes | Project UUID |
+| `type` | `"webhook" | "slack" | "discord" | "github" | "custom"` | No | Filter by connector type (optional) |
+| `status` | `"active" | "disabled"` | No | Filter by status (optional) |
+| `limit` | `number` | No | Max connectors to return (default: 50) |
+| `offset` | `number` | No | Pagination offset (default: 0) |
+
+---
+
+### get_connector
+
+Get a single connector with full details including configuration (sensitive fields are masked).
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `connector_id` | `string` | Yes | Connector UUID |
+
+---
+
+### add_connector
+
+Add a new connector for external integrations. Supports webhook, Slack, Discord, GitHub, and custom connectors.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | Yes | Project UUID |
+| `name` | `string` | Yes | Connector name (e.g., "Slack Notifications") |
+| `type` | `"webhook" | "slack" | "discord" | "github" | "custom"` | Yes | Connector type |
+| `description` | `string` | No | Optional description |
+| `config` | `object` | No | Type-specific configuration (e.g., { webhook_url: "..." } for Slack) |
+| `events` | `object` | No | Event subscriptions (e.g., { task_completed: true, blocker_added: true }) |
+
+---
+
+### update_connector
+
+Update a connector's configuration, events, or status.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `connector_id` | `string` | Yes | Connector UUID |
+| `name` | `string` | No | Updated name |
+| `description` | `string` | No | Updated description |
+| `config` | `object` | No | Updated configuration (merged with existing) |
+| `events` | `object` | No | Updated event subscriptions |
+| `status` | `"active" | "disabled"` | No | Enable or disable the connector |
+
+---
+
+### delete_connector
+
+Delete a connector.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `connector_id` | `string` | Yes | Connector UUID |
+
+---
+
+### test_connector
+
+Test a connector by sending a test event. Returns success/failure status.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `connector_id` | `string` | Yes | Connector UUID to test |
+
+---
+
+### get_connector_events
+
+Get event history for a connector or project. Shows delivery status and errors.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `connector_id` | `string` | No | Connector UUID (optional if project_id provided) |
+| `project_id` | `string` | No | Project UUID (optional if connector_id provided) |
+| `status` | `"pending" | "sent" | "failed" | "retrying"` | No | Filter by delivery status (optional) |
+| `limit` | `number` | No | Max events to return (default: 50) |
+| `offset` | `number` | No | Pagination offset (default: 0) |
+
+---