Skip to main content
Glama
╔════════════════════════════════════════════════════════════╗
║                                                            ║
║   ███╗   ███╗ ██████╗██████╗     ██╗     ██╗     ███╗   ███╗║
║   ████╗ ████║██╔════╝██╔══██╗    ██║     ██║     ████╗ ████║║
║   ██╔████╔██║██║     ██████╔╝    ██║     ██║     ██╔████╔██║║
║   ██║╚██╔╝██║██║     ██╔═══╝     ██║     ██║     ██║╚██╔╝██║║
║   ██║ ╚═╝ ██║╚██████╗██║         ███████╗███████╗██║ ╚═╝ ██║║
║   ╚═╝     ╚═╝ ╚═════╝╚═╝         ╚══════╝╚══════╝╚═╝     ╚═╝║
║                                                            ║
║                    L L M   R O U T E R                     ║
║                                                            ║
╚════════════════════════════════════════════════════════════╝

MCP LLM Router

A Model Context Protocol (MCP) server for routing LLM requests across multiple providers and connecting to other MCP servers. Designed with an "all-local except the brain" architecture for privacy and control.

Features (Unified Router + Judge)

  • One server, two roles: mcp_llm_router.server now ships Judge tools in-process—no separate mcp-as-a-judge server required.

  • Multi-Provider LLM Routing: Route requests to OpenAI, OpenRouter, DeepInfra, and other OpenAI-compatible APIs.

  • Configurable "Brain" Model: Choose DeepSeek reasoning or any OpenAI-compatible model as the router brain.

  • Session Management: Track agent sessions with goals, constraints, and event logging.

  • Quality Gating (Judge): Plan → code → test → completion validation using the embedded Judge toolset.

  • MCP-Native Context: Embedded judge resources expose current task state, history, rubric, and workflow state snapshots.

  • Local-First Memory: Default: Local embeddings via Ollama with optional ChromaDB vector store for efficient semantic search. OpenAI-compatible endpoints supported as fallback.

  • Local Cross-Encoder Reranking: Optional privacy-focused reranking using Qwen3-Reranker-0.6B for improved search relevance without external API calls.

  • MCP Server Orchestration: Connect to and orchestrate multiple MCP servers.

  • Cross-Server Tool Calling: Call tools across different MCP servers.

  • Universal MCP Compatibility: Works with any MCP-compatible client (not tied to specific IDEs).

Related MCP server: MCP Server Copilot

Architecture: All-Local Except the Brain

This project follows an "all-local except the brain" design philosophy:

  • ✅ Embeddings: Run locally via Ollama (default: qwen3-embedding:0.6b)

  • ✅ Vector Storage: SQLite (default) or ChromaDB with HNSW indexing (optional RAG package)

  • ✅ Document Chunking: Token-based chunking with overlap (optional RAG package)

  • ✅ Semantic Search: Local cosine similarity with L2-normalized vectors

  • ✅ Reranking: Optional local cross-encoder reranking with Qwen3-Reranker-0.6B

  • 🌐 LLM "Brain": Configurable external API (DeepSeek, OpenAI, etc.) for reasoning and generation

Why? This architecture keeps your data and semantic search private and fast, while leveraging powerful external LLMs only for high-level reasoning tasks.

Installation

This project is tested on Python 3.12 and 3.13.

One-command automated installation:

./install.sh

This script will:

  • ✅ Create a Python virtual environment

  • ✅ Install all dependencies from pyproject.toml

  • ✅ Check for Ollama installation

  • ✅ Verify the setup

  • ✅ Display next steps with your specific paths

Manual Installation

If you prefer manual installation or need a Conda environment:

# Clone the repository
git clone https://github.com/groxaxo/mcp-llm-router.git
cd mcp-llm-router

# Option 1: Using venv (recommended)
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -U pip
pip install -e .

# Option 2: Using Conda
conda create -n mcp-router python=3.13 -y
conda activate mcp-router
pip install -U pip
pip install -e .

Ollama Setup (Required for Local Embeddings)

Install Ollama for local, privacy-focused embeddings:

# Linux/macOS
curl -fsSL https://ollama.ai/install.sh | sh

# Or download from https://ollama.ai

Pull the embedding model:

ollama pull qwen3-embedding:0.6b

Verify Ollama is running:

curl http://localhost:11434/api/version

Alternative Embedding Models:

  • nomic-embed-text - General-purpose embeddings

  • mxbai-embed-large - Larger model for better quality

Set via environment variable:

export EMBEDDINGS_MODEL="nomic-embed-text"

Project Structure

mcp-llm-router/
├── install.sh              # Automated installation script
├── README.md               # This file
├── pyproject.toml          # Python package configuration
│
├── mcp_llm_router/         # Main package
│   ├── server.py           # MCP server entry point
│   ├── brain.py            # LLM routing logic
│   ├── memory.py           # Memory management (embeddings, search, rerank)
│   ├── codex.py            # MCP server orchestration
│   └── judge/              # Embedded judge tools for quality gating
│
├── rag/                    # Optional RAG package (ChromaDB, chunking)
│   ├── main.py             # CLI for indexing and queries
│   ├── indexer.py          # Document indexing
│   ├── retriever.py        # Vector search
│   └── reranker.py         # Local cross-encoder reranking
│
├── scripts/                # Utility scripts
│   ├── verify_server.py    # Installation verification
│   ├── opencode            # CLI tool for direct LLM requests
│   ├── mcp_client.py       # MCP client for testing
│   └── mcp_manager.py      # MCP server management
│
├── examples/               # Example configurations and demos
│   ├── demo_judge_gating.py          # End-to-end judge workflow demo
│   ├── local_reranker_example.py     # Local reranking example
│   ├── mcp-config.deepseek-ollama.json
│   └── mcp-config.local-reranker.json
│
└── tests/                  # Test suite
    ├── test_server.py
    ├── test_mcp.py
    └── test_local_reranker.py

Configuration

MCP Server Configuration (mcp-config.json)

Canonical minimal config

{
  "mcpServers": {
    "llm-router": {
      "command": "python",
      "args": ["-m", "mcp_llm_router.server"],
      "env": {
        "DEEPSEEK_API_KEY": "your-deepseek-key",
        "ROUTER_BRAIN_PROVIDER": "deepseek",
        "ROUTER_BRAIN_MODEL": "deepseek-reasoner",
        "ROUTER_BRAIN_API_KEY_ENV": "DEEPSEEK_API_KEY",
        "EMBEDDINGS_PROVIDER": "ollama",
        "EMBEDDINGS_BASE_URL": "http://localhost:11434",
        "EMBEDDINGS_MODEL": "qwen3-embedding:0.6b"
      }
    }
  }
}

Provider override example

{
  "mcpServers": {
    "llm-router": {
      "command": "python",
      "args": ["-m", "mcp_llm_router.server"],
      "env": {
        "OPENROUTER_API_KEY": "sk-or-...",
        "ROUTER_BRAIN_PROVIDER": "openrouter",
        "ROUTER_BRAIN_MODEL": "anthropic/claude-3.7-sonnet",
        "ROUTER_BRAIN_API_KEY_ENV": "OPENROUTER_API_KEY",
        "ROUTER_BRAIN_BASE_URL": "https://openrouter.ai/api/v1",
        "EMBEDDINGS_PROVIDER": "ollama",
        "EMBEDDINGS_BASE_URL": "http://localhost:11434",
        "EMBEDDINGS_MODEL": "qwen3-embedding:0.6b"
      }
    }
  }
}

Example Config + Demo

  • examples/mcp-config.deepseek-ollama.json - DeepSeek brain + Ollama embeddings + judge history persistence.

  • examples/mcp-config.local-reranker.json - DeepSeek brain + Ollama embeddings + local cross-encoder reranking.

  • examples/demo_judge_gating.py - End-to-end demo that indexes memory and walks a task through judge gating via router_chat.

  • examples/local_reranker_example.py - Example of using local cross-encoder reranking to improve search relevance.

Run the demo:

python examples/demo_judge_gating.py --config examples/mcp-config.deepseek-ollama.json

Run the local reranker example:

python examples/local_reranker_example.py

Note: the demo skips request_plan_approval because it requires user elicitation. Ensure DEEPSEEK_API_KEY (or LLM_API_KEY) is set and Ollama is running for embeddings.

Embedded judge resources + prompts

The embedded judge now exposes additive MCP resources and prompts alongside the existing tools:

  • Resources:

    • judge://current-task

    • judge://task/{task_id}

    • judge://task/{task_id}/history

    • judge://policy/rubric

    • judge://workflow/states

  • Prompts:

    • start_judged_coding_task

    • submit_implementation_for_review

    • prepare_testing_evidence

When an MCP client exposes roots, judge review/testing tools validate submitted paths against those roots. When roots are unavailable, the server preserves the existing stdio-first behavior.

Environment Variables

Set API keys in your environment or in the config:

export OPENAI_API_KEY="sk-proj-..."
export DEEPINFRA_API_KEY="..."
export OPENROUTER_API_KEY="sk-or-..."
export DEEPSEEK_API_KEY="..."

Brain Configuration (Router LLM)

The canonical examples in this README use a DeepSeek brain + local Ollama embeddings baseline. Provider overrides only need to change the ROUTER_BRAIN_* variables and API key.

# Core brain settings
export ROUTER_BRAIN_MODEL="deepseek-reasoner"
export ROUTER_BRAIN_PROVIDER="deepseek"
export ROUTER_BRAIN_API_KEY_ENV="DEEPSEEK_API_KEY"

# Optional overrides
export ROUTER_BRAIN_BASE_URL="https://api.deepseek.com"
export ROUTER_BRAIN_MAX_TOKENS="4000"
export ROUTER_BRAIN_TEMPERATURE="0.2"

You can also set the brain per session using the configure_brain tool.

Memory Configuration (Embeddings + Rerank)

No API keys required! The default configuration uses local Ollama embeddings:

# Storage paths
export MCP_ROUTER_DATA_DIR="./.mcp-llm-router"
export MCP_ROUTER_MEMORY_DB="./.mcp-llm-router/memory.db"

# Local embeddings via Ollama (DEFAULT - no API key needed)
export EMBEDDINGS_PROVIDER="ollama"
export EMBEDDINGS_BASE_URL="http://localhost:11434"
export EMBEDDINGS_MODEL="qwen3-embedding:0.6b"
export EMBEDDINGS_PATH="/api/embed"
# No EMBEDDINGS_API_KEY_ENV needed for local Ollama!

Alternative: OpenAI-Compatible Embeddings

If you prefer cloud-based embeddings:

# Embeddings via OpenAI
export EMBEDDINGS_PROVIDER="openai"
export EMBEDDINGS_BASE_URL="https://api.openai.com/v1"
export EMBEDDINGS_MODEL="text-embedding-3-small"
export EMBEDDINGS_API_KEY_ENV="OPENAI_API_KEY"
export EMBEDDINGS_PATH="/embeddings"

Reranking (Optional)

Reranking is optional and defaults to "none". Three modes are available:

Uses the local Qwen3-Reranker-0.6B model for reranking without external API calls:

# Local cross-encoder reranking (requires transformers and torch)
export RERANK_PROVIDER="local"
export RERANK_MODE="local"
export RERANK_MODEL="tomaarsen/Qwen3-Reranker-0.6B-seq-cls"  # Default model

Requirements:

  • Install PyTorch: pip install torch

  • Install Transformers: pip install transformers

  • The model will be automatically downloaded on first use (~1.2GB)

2. LLM-Based Reranking

Uses an external LLM API for reranking:

# Rerank using OpenAI-compatible LLM (optional)
export RERANK_PROVIDER="openai"
export RERANK_BASE_URL="https://api.openai.com/v1"
export RERANK_MODEL="gpt-4o-mini"
export RERANK_API_KEY_ENV="OPENAI_API_KEY"
export RERANK_PATH="/chat/completions"
export RERANK_MODE="llm"
3. Disable Reranking
# Or disable reranking entirely (default)
export RERANK_PROVIDER="none"

Judge Persistence (embedded Judge)

# Persist judge conversation history + task metadata
export MCP_JUDGE_DATABASE_URL="sqlite:///./.mcp-llm-router/judge_history.db"

Advanced: ChromaDB + Token Chunking (RAG Package)

For enhanced semantic search with vector indexing and intelligent chunking, this repository includes an optional rag package that provides:

  • Token-based chunking with overlap for consistent semantic granularity

  • ChromaDB vector store with HNSW indexing for fast similarity search

  • L2-normalized embeddings for consistent cosine similarity

  • Batch embedding and efficient upserts

Using the RAG Package

  1. Install additional dependencies (already included in pyproject.toml):

    pip install -e .  # chromadb, transformers are now included
  2. Index your codebase:

    python -m rag.main --path . --exts .py,.md --interactive

    This will:

    • Scan the current directory for .py and .md files

    • Chunk them into 400-token segments with 80-token overlap

    • Embed using Ollama (qwen3-embedding:0.6b)

    • Store in ChromaDB at data/chroma/

    • Enter interactive mode for testing queries

  3. Use in your code:

    from rag.retriever import retrieve
    from rag.indexer import index_path
    
    # Index documents
    stats = index_path("/path/to/docs", exts=[".py", ".md"])
    print(f"Indexed {stats['files_indexed']} files")
    
    # Retrieve relevant chunks
    results = retrieve("How does authentication work?", top_k=5)
    for hit in results:
        print(f"Score: {hit['distance']:.4f}")
        print(f"File: {hit['meta']['path']}")
        print(f"Content: {hit['doc']}\n")

RAG Package Components:

  • rag/embedding_config.py - Configuration constants

  • rag/chunker.py - Token-based text chunking

  • rag/ollama_embedder.py - Ollama embedding with normalization

  • rag/chroma_store.py - ChromaDB initialization and management

  • rag/indexer.py - Document indexing pipeline

  • rag/retriever.py - Vector search and retrieval

  • rag/main.py - CLI for indexing and queries

Note: The RAG package is a self-contained enhancement. The core MCP server works with its built-in SQLite memory store without requiring ChromaDB.

Usage

Running MCP Servers

Using the Server Runner

# List configured servers
python scripts/mcp_server_runner.py list

# Run a specific server
python scripts/mcp_server_runner.py run llm-router

Using the Server Manager

# Add a new server
python scripts/mcp_manager.py add my-server python -m my_mcp_server

# List servers
python scripts/mcp_manager.py list

# Test server connection
python scripts/mcp_manager.py test llm-router

# Remove a server
python scripts/mcp_manager.py remove my-server

Connecting to MCP Servers

Using the MCP Client

# List tools on a server
python scripts/mcp_client.py list-tools llm-router

# Call a tool on a server
python scripts/mcp_client.py call-tool llm-router start_session '{"goal": "Test session"}'

Using the Server Manager for Cross-Server Operations

# Call a tool across all configured servers
python scripts/mcp_manager.py call start_session '{"goal": "Test all servers"}'

MCP Tools Available

Session Management

  • start_session(goal, constraints, context, metadata) - Start a new agent session

  • log_event(session_id, kind, message, details) - Log events to a session

  • get_session_context(session_id) - Retrieve full session data

LLM Routing

  • agent_llm_request(session_id, prompt, model, base_url, api_key_env, ...) - Route to LLM providers

  • configure_brain(...) - Set the global or per-session brain model/settings

  • get_brain_config(session_id) - Read the active brain configuration

  • router_chat(session_id, message, ...) - Main brain chat (memory + workflow guidance)

Memory (Embeddings + Rerank)

  • configure_memory(...) - Set embedding/rerank configuration globally or per-session

  • memory_index(namespace, texts, metadatas, doc_ids) - Index texts into memory

  • memory_search(namespace, query, top_k, rerank) - Retrieve relevant memory hits

  • memory_delete(namespace, doc_id) - Delete one doc or a whole namespace

  • memory_list_namespaces() - List namespaces

  • memory_stats() - Show memory counts

MCP Server Orchestration

  • connect_mcp_server(server_name, command, args, env) - Configure connection to another MCP server

  • list_mcp_servers() - List configured MCP server connections

  • call_mcp_tool(server_name, tool_name, arguments) - Call tools on other MCP servers

  • list_mcp_tools(server_name) - List tools available on another MCP server

Judge Tools (built-in)

  • set_coding_task(...)

  • get_current_coding_task()

  • request_plan_approval(...)

  • judge_coding_plan(...)

  • judge_code_change(...)

  • judge_testing_implementation(...)

  • judge_coding_task_completion(...)

  • raise_obstacle(...)

  • raise_missing_requirements(...)

Integration with MCP Clients

Any MCP-Compatible Client

The server works with any client that supports the MCP protocol:

{
  "mcpServers": {
    "llm-router": {
      "command": "python",
      "args": ["-m", "mcp_llm_router.server"],
      "env": {
        "OPENAI_API_KEY": "your-key"
      }
    }
  }
}

Example: Claude Desktop

Add to your Claude Desktop MCP configuration:

{
  "mcpServers": {
    "llm-router": {
      "command": "python",
      "args": ["-m", "mcp_llm_router.server"],
      "env": {
        "OPENAI_API_KEY": "sk-...",
        "DEEPINFRA_API_KEY": "..."
      }
    }
  }
}

Example: Custom MCP Client

import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def main():
    server_params = StdioServerParameters(
        command="python",
        args=["-m", "mcp_llm_router.server"],
        env={"OPENAI_API_KEY": "your-key"}
    )

    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()

            # Start a session
            result = await session.call_tool("start_session", {
                "goal": "Test the MCP server"
            })
            print("Session started:", result)

if __name__ == "__main__":
    asyncio.run(main())

Provider Configuration

OpenAI

{
  "base_url": null,  # Uses default
  "api_key_env": "OPENAI_API_KEY"
}

OpenRouter

{
  "base_url": "https://openrouter.ai/api/v1",
  "api_key_env": "OPENROUTER_API_KEY"
}

DeepInfra

{
  "base_url": "https://api.deepinfra.com/v1/openai",
  "api_key_env": "DEEPINFRA_API_KEY"
}

CLI Tool

The opencode command provides direct CLI access:

# Basic usage
scripts/opencode run "What is Python"

# Use specific provider
scripts/opencode run "Explain Docker" --provider deepinfra --model meta-llama/Meta-Llama-3.1-70B-Instruct

Development

Running the Server Directly

cd ~/mcp-llm-router
conda activate mcp-router
python -m mcp_llm_router.server

Testing

# Test server startup
timeout 5 python -m mcp_llm_router.server

# Test CLI
scripts/opencode run "Hello world"

# Test MCP client
python scripts/mcp_client.py list-tools llm-router

Architecture

┌─────────────────┐    ┌──────────────────────────────────────┐
│   MCP Client    │◄──►│     LLM Router MCP Server            │
│ (Claude, etc.)  │    │  ┌────────────────────────────────┐  │
└─────────────────┘    │  │  Session & Memory Management   │  │
                       │  │  • SQLite/ChromaDB (local)     │  │
                       │  │  • Ollama Embeddings (local)   │  │
                       │  │  • L2-normalized vectors       │  │
                       │  └────────────────────────────────┘  │
                       │                │                     │
                       │                ▼                     │
                       │  ┌────────────────────────────────┐  │
                       │  │  Brain (External LLM API)      │  │
                       │  │  • DeepSeek / OpenAI / etc.    │  │
                       │  │  • Reasoning & Generation      │  │
                       │  └────────────────────────────────┘  │
                       └──────────────────────────────────────┘
                                         │
                                         ▼
                              ┌──────────────────┐
                              │ Other MCP Servers│
                              │ • File system    │
                              │ • Database       │
                              │ • APIs           │
                              └──────────────────┘

All-Local Except the Brain:
  ✅ Embeddings: Ollama (local, no API key)
  ✅ Vector Store: SQLite or ChromaDB (local)
  ✅ Semantic Search: Local cosine similarity
  🌐 LLM Brain: External API (configurable)

License

MIT License - see LICENSE file for details.

# Basic usage with OpenAI (default)
scripts/opencode run "Explain quantum computing"

# Use a specific provider
scripts/opencode run "Write a Python function" --provider openrouter --model anthropic/claude-3-opus

# Use DeepInfra
scripts/opencode run "Summarize this text" --provider deepinfra --model meta-llama/Llama-3.1-70B-Instruct

Available providers:

  • openai (default) - Uses OPENAI_API_KEY

  • openrouter - Uses OPENROUTER_API_KEY

  • deepinfra - Uses DEEPINFRA_API_KEY

MCP Tools

When used as an MCP server in Antigravity, the following tools are available:

start_session

Start a new agent session with a goal and constraints.

{
  "goal": "Implement user authentication",
  "constraints": "Use JWT tokens, no external dependencies",
  "context": "FastAPI application"
}

log_event

Log events during an agent session (info, error, warning, success).

{
  "session_id": "uuid-here",
  "kind": "error",
  "message": "Build failed",
  "details": {"exit_code": 1}
}

agent_llm_request

Make a request to an LLM provider within a session.

{
  "session_id": "uuid-here",
  "prompt": "How do I fix this error?",
  "model": "gpt-4",
  "base_url": "https://openrouter.ai/api/v1",  # optional
  "api_key_env": "OPENROUTER_API_KEY"
}

get_session_context

Retrieve full session history and events.

{
  "session_id": "uuid-here"
}

Example Agent Workflow in Antigravity

  1. Start session:

    Call start_session with goal="Build a REST API for task management"
  2. Work on task:

    Create files, run commands, etc.
  3. Log progress:

    Call log_event with kind="info", message="Created database schema"
  4. When stuck:

    Call agent_llm_request with prompt="How do I handle authentication?"
  5. Review context:

    Call get_session_context to see full history

Development

Run the MCP server directly:

cd ~/mcp-llm-router
conda activate mcp-router
python -m mcp_llm_router.server

Or use the packaged CLI entrypoint after installation:

mcp-llm-router

Inspector-style capability smoke check:

python scripts/inspector_smoke.py

Architecture and contributor guides:

  • docs/architecture.md

  • docs/how-to-add-a-judge-tool.md

Environment Variables

Set these in your ~/.bashrc or Antigravity config:

export OPENAI_API_KEY="sk-..."
export OPENROUTER_API_KEY="sk-or-..."
export DEEPINFRA_API_KEY="..."

Available Tools

28 tools
agent_llm_requestC

Make a request to an OpenAI-compatible LLM provider.

Inputs: model (required), prompt (required), session_id (required), base_url, +5 more. Returns: result

call_mcp_toolC

Call a tool on a connected MCP server.

Inputs: tool_name (required), server_name (required), arguments. Returns: result

configure_brainC

Configure the default or session-specific brain model.

Inputs: model, base_url, provider, timeout_s, +8 more. Returns: result

configure_memoryB

Configure memory embedding/rerank settings (global or per-session).

Inputs: rerank, embedding, session_id. Returns: result

connect_mcp_serverC

Connect to another MCP server.

Inputs: command (required), server_name (required), env, args. Returns: result

get_brain_configD

Inputs: session_id. Returns: result

get_current_coding_taskA

Get Current Coding Task

Description

Retrieve the most recently active coding task UUID (task_id) and metadata from conversation history. Use when the task_id is missing from context.

Critical Tool Warning

  • Skipping this tool causes severe token inefficiency and wasted iterations.

  • Always invoke this tool at the appropriate stage to avoid extreme token loss and redundant processing.

  • Do not rely on assistant memory for identifiers. Always pass the exact task_id and recover it via get_current_coding_task if missing.

When to use

  • Need the task_id for follow-up tool calls

  • Want to resume the last active coding task

Args

  • None

Returns

  • found: boolean — whether a recent task was found

  • task_id: string — task UUID (present when found)

  • last_activity: integer — last-activity timestamp for the session

  • current_task_metadata: object — TaskMetadata (when available)

  • workflow_guidance: object — WorkflowGuidance with next_tool, preparation, and guidance

Notes

  • After recovery, always use the exact task_id UUID in all subsequent tool calls. Do not invent or transform the value.

Inputs: no named parameters.

get_session_contextC

Retrieve the full context of a session.

Inputs: session_id (required). Returns: result

judge_code_changeA

Judge Code Change

Description

Review implementation code changes (not tests) strictly based on a unified Git diff patch. Tests are validated separately by judge_testing_implementation. Called when workflow_guidance.next_tool == "judge_code_change".

Critical Tool Warning

  • Skipping this tool causes severe token inefficiency and wasted iterations.

  • Always invoke this tool at the appropriate stage to avoid extreme token loss and redundant processing.

  • Do not rely on assistant memory for identifiers. Always pass the exact task_id and recover it via get_current_coding_task if missing.

When to use

  • After creating or modifying implementation code and a review is needed. Provide a unified Git diff of the changes. Tests may be written before or after review; they are validated via judge_testing_implementation.

Human-in-the-Loop (HITL) checks

  • If foundational choices are unclear or need confirmation (e.g., framework/library, UI vs CLI, web vs desktop, API style, auth, hosting), first call raise_missing_requirements to elicit the user’s intent

  • If the implementation proposes changing a previously described/understood fundamental choice, call raise_obstacle to involve the user in selecting the new direction

  • These HITL tools do not return next_tool; follow workflow guidance for the next step after elicitation

Args

  • task_id: string — Task UUID (required)

  • code_change: string — Unified Git diff patch representing the changes (REQUIRED)

  • file_path: string — Path to the primary created/modified file (optional; use when diff covers a single file)

  • change_description: string — What the change accomplishes

Returns

  • Response JSON schema (JudgeResponse):

{
  "$defs": {
    "FileReview": {
      "properties": {
        "path": {
          "description": "File path reviewed",
          "title": "Path",
          "type": "string"
        },
        "feedback": {
          "description": "Per-file feedback summary",
          "title": "Feedback",
          "type": "string"
        },
        "approved": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Optional per-file approval or risk flag",
          "title": "Approved"
        }
      },
      "required": [
        "path",
        "feedback"
      ],
      "title": "FileReview",
      "type": "object"
    },
    "LibraryPlanItem": {
      "properties": {
        "purpose": {
          "description": "Non-domain concern or integration point this library addresses",
          "title": "Purpose",
          "type": "string"
        },
        "selection": {
          "description": "Chosen library or internal utility (name and optional version)",
          "title": "Selection",
          "type": "string"
        },
        "source": {
          "description": "Source of solution: 'internal' for repo utility, 'external' for well-known library, 'custom' for in-house code",
          "title": "Source",
          "type": "string"
        },
        "justification": {
          "default": "",
          "description": "One-line rationale for the selection and any trade-offs",
          "title": "Justification",
          "type": "string"
        }
      },
      "required": [
        "purpose",
        "selection",
        "source"
      ],
      "title": "LibraryPlanItem",
      "type": "object"
    },
    "PlanRequiredField": {
      "description": "Specification for a required field in judge_coding_plan.",
      "properties": {
        "name": {
          "description": "Field name in the judge_coding_plan tool",
          "title": "Name",
          "type": "string"
        },
        "type": {
          "description": "Expected data type (string, list[str], list[dict], etc.)",
          "title": "Type",
          "type": "string"
        },
        "description": {
          "description": "What this field should contain",
          "title": "Description",
          "type": "string"
        },
        "required": {
          "description": "Whether this field is required",
          "title": "Required",
          "type": "boolean"
        },
        "conditional_on": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Task metadata field this requirement depends on (e.g., 'design_patterns_enforcement')",
          "title": "Conditional On"
        },
        "example_value": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Example of what this field should contain",
          "title": "Example Value"
        }
      },
      "required": [
        "name",
        "type",
        "description",
        "required"
      ],
      "title": "PlanRequiredField",
      "type": "object"
    },
    "RequirementsVersion": {
      "description": "A version of user requirements with timestamp and source.",
      "properties": {
        "content": {
          "title": "Content",
          "type": "string"
        },
        "source": {
          "title": "Source",
          "type": "string"
        },
        "timestamp": {
          "title": "Timestamp",
          "type": "integer"
        }
      },
      "required": [
        "content",
        "source"
      ],
      "title": "RequirementsVersion",
      "type": "object"
    },
    "ResearchScope": {
      "description": "Research scope enum for workflow-driven research validation.\n\nDetermines the depth and requirements for research validation:\n- NONE: No research required for this task complexity\n- LIGHT: Light research required (1+ authoritative domain source)\n- DEEP: Deep research required (2+ authoritative domain sources)",
      "enum": [
        "none",
        "light",
        "deep"
      ],
      "title": "ResearchScope",
      "type": "string"
    },
    "ReuseComponent": {
      "properties": {
        "path": {
          "description": "Repository path to the reusable component",
          "title": "Path",
          "type": "string"
        },
        "purpose": {
          "default": "",
          "description": "What part of the task this component will support",
          "title": "Purpose",
          "type": "string"
        },
        "notes": {
          "default": "",
          "description": "Any integration notes or caveats",
          "title": "Notes",
          "type": "string"
        }
      },
      "required": [
        "path"
      ],
      "title": "ReuseComponent",
      "type": "object"
    },
    "TaskMetadata": {
      "description": "Lightweight metadata for coding tasks that flows with memory layer.\n\nThis model serves as the foundation for the enhanced workflow v3 system,\nreplacing session-based tracking with task-centric approach.",
      "properties": {
        "task_id": {
          "description": "IMMUTABLE: Auto-generated UUID, primary key for memory storage",
          "title": "Task Id",
          "type": "string"
        },
        "created_at": {
          "description": "IMMUTABLE: Task creation timestamp (epoch seconds)",
          "title": "Created At",
          "type": "integer"
        },
        "title": {
          "description": "Display title for coding task (updatable)",
          "title": "Title",
          "type": "string"
        },
        "description": {
          "description": "Detailed coding task description (updatable)",
          "title": "Description",
          "type": "string"
        },
        "user_requirements": {
          "default": "",
          "description": "Current coding requirements (updatable)",
          "title": "User Requirements",
          "type": "string"
        },
        "state": {
          "$ref": "#/$defs/TaskState",
          "default": "created",
          "description": "Current task state (updatable, follows TaskState transitions)"
        },
        "task_size": {
          "$ref": "#/$defs/TaskSize",
          "description": "Task size classification for workflow optimization (XS=simple fixes, S=minor features, M=standard, L=complex, XL=major changes)"
        },
        "user_requirements_history": {
          "description": "History of requirements changes",
          "items": {
            "$ref": "#/$defs/RequirementsVersion"
          },
          "title": "User Requirements History",
          "type": "array"
        },
        "accumulated_diff": {
          "additionalProperties": true,
          "description": "Code changes accumulated over time",
          "title": "Accumulated Diff",
          "type": "object"
        },
        "modified_files": {
          "description": "List of file paths that were created or modified during task implementation",
          "items": {
            "type": "string"
          },
          "title": "Modified Files",
          "type": "array"
        },
        "test_files": {
          "description": "List of test file paths that were created during testing phase",
          "items": {
            "type": "string"
          },
          "title": "Test Files",
          "type": "array"
        },
        "test_status": {
          "additionalProperties": {
            "type": "string"
          },
          "description": "Status of different test types (unit, integration, e2e, etc.)",
          "title": "Test Status",
          "type": "object"
        },
        "updated_at": {
          "description": "Last update timestamp (epoch seconds)",
          "title": "Updated At",
          "type": "integer"
        },
        "tags": {
          "description": "Coding-related tags",
          "items": {
            "type": "string"
          },
          "title": "Tags",
          "type": "array"
        },
        "problem_domain": {
          "default": "",
          "description": "Concise statement of the problem domain and scope for this task",
          "title": "Problem Domain",
          "type": "string"
        },
        "problem_non_goals": {
          "description": "Explicit non-goals/boundaries to prevent scope creep and re-solving commodity concerns",
          "items": {
            "type": "string"
          },
          "title": "Problem Non Goals",
          "type": "array"
        },
        "library_plan": {
          "description": "Planned libraries/utilities per purpose; prefer internal reuse and well-known libraries; custom code only with justification",
          "items": {
            "$ref": "#/$defs/LibraryPlanItem"
          },
          "title": "Library Plan",
          "type": "array"
        },
        "internal_reuse_components": {
          "description": "Existing repository components/utilities to reuse with paths and purposes",
          "items": {
            "$ref": "#/$defs/ReuseComponent"
          },
          "title": "Internal Reuse Components",
          "type": "array"
        },
        "research_required": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Whether research is required by workflow guidance (None=undetermined, True=required, False=optional)",
          "title": "Research Required"
        },
        "research_scope": {
          "$ref": "#/$defs/ResearchScope",
          "default": "none",
          "description": "Research scope determined by workflow: none|light|deep"
        },
        "research_completed": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Epoch seconds when research validation passed",
          "title": "Research Completed"
        },
        "research_rationale": {
          "default": "",
          "description": "Explanation of why research was required and how the scope was determined",
          "title": "Research Rationale",
          "type": "string"
        },
        "expected_url_count": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "LLM-determined expected number of research URLs based on task complexity",
          "title": "Expected Url Count"
        },
        "minimum_url_count": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "LLM-determined minimum acceptable URL count for adequate research",
          "title": "Minimum Url Count"
        },
        "url_requirement_reasoning": {
          "default": "",
          "description": "LLM-generated explanation of why specific URL count is needed for this task",
          "title": "Url Requirement Reasoning",
          "type": "string"
        },
        "research_complexity_analysis": {
          "anyOf": [
            {
              "additionalProperties": true,
              "type": "object"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Detailed complexity analysis factors from LLM (domain, tech maturity, integration scope, etc.)",
          "title": "Research Complexity Analysis"
        },
        "internal_research_required": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Whether internal codebase research is needed (None=undetermined, True=required, False=not needed)",
          "title": "Internal Research Required"
        },
        "related_code_snippets": {
          "description": "Related code snippets from the codebase that are relevant to this task",
          "items": {
            "type": "string"
          },
          "title": "Related Code Snippets",
          "type": "array"
        },
        "risk_assessment_required": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Whether risk assessment is needed (None=undetermined, True=required, False=not needed)",
          "title": "Risk Assessment Required"
        },
        "identified_risks": {
          "description": "Areas that could be harmed by the proposed changes",
          "items": {
            "type": "string"
          },
          "title": "Identified Risks",
          "type": "array"
        },
        "risk_mitigation_strategies": {
          "description": "Strategies to mitigate identified risks",
          "items": {
            "type": "string"
          },
          "title": "Risk Mitigation Strategies",
          "type": "array"
        },
        "design_patterns_enforcement": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Whether design patterns are required for this task (None=undetermined, True=required, False=not needed)",
          "title": "Design Patterns Enforcement"
        },
        "plan_approved_at": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Timestamp when plan was approved by judge_coding_plan (None=not approved)",
          "title": "Plan Approved At"
        },
        "plan_rejection_count": {
          "default": 0,
          "description": "Number of times the plan has been rejected (max 1 allowed)",
          "title": "Plan Rejection Count",
          "type": "integer"
        },
        "code_approved_files": {
          "additionalProperties": {
            "type": "integer"
          },
          "description": "Dictionary mapping file paths to approval timestamps from judge_code_change",
          "title": "Code Approved Files",
          "type": "object"
        },
        "testing_approved_at": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Timestamp when testing was approved by judge_testing_implementation (None=not approved)",
          "title": "Testing Approved At"
        },
        "all_approvals_validated": {
          "default": false,
          "description": "Whether all required approvals (plan, code, testing) have been validated",
          "title": "All Approvals Validated",
          "type": "boolean"
        }
      },
      "required": [
        "title",
        "description",
        "task_size"
      ],
      "title": "TaskMetadata",
      "type": "object"
    },
    "TaskSize": {
      "description": "Task size classification for workflow optimization.\n\nSizes are based on estimated complexity and time requirements:\n- XS: Extra Small - Simple fixes, typos, minor config changes (< 30 minutes)\n- S: Small - Minor features, simple refactoring (30 minutes - 2 hours)\n- M: Medium - Standard features, moderate complexity (2-8 hours) - DEFAULT\n- L: Large - Complex features, multiple components (1-3 days)\n- XL: Extra Large - Major system changes, architectural updates (3+ days)\n\nThis classification determines planning complexity and validation depth:\n- XS/S: Basic planning requirements, streamlined validation\n- M: Standard planning and validation\n- L/XL: Comprehensive planning with enhanced validation (library plans, risk assessment, design patterns)\n\nAll tasks follow the unified workflow: CREATED \u2192 PLANNING \u2192 PLAN_APPROVED \u2192 IMPLEMENTING \u2192 REVIEW_READY \u2192 TESTING \u2192 COMPLETED",
      "enum": [
        "xs",
        "s",
        "m",
        "l",
        "xl"
      ],
      "title": "TaskSize",
      "type": "string"
    },
    "TaskState": {
      "description": "Coding task state enum with well-documented transitions.\n\nState Transitions:\n- CREATED \u2192 PLANNING: Task created, ready for planning phase (XS/S may skip to IMPLEMENTING)\n- PLANNING \u2192 PLAN_PENDING_APPROVAL: Plan created, awaiting user approval\n- PLAN_PENDING_APPROVAL \u2192 PLANNING: User requests plan changes\n- PLAN_PENDING_APPROVAL \u2192 PLAN_APPROVED: User approves plan\n- PLAN_APPROVED \u2192 IMPLEMENTING: Implementation phase started\n- IMPLEMENTING \u2192 IMPLEMENTING: Multiple code changes during implementation\n- IMPLEMENTING \u2192 REVIEW_READY: Implementation complete, ready for code review\n- REVIEW_READY \u2192 TESTING: Code review approved, ready for testing validation\n- TESTING \u2192 TESTING: Multiple test iterations\n- TESTING \u2192 COMPLETED: All tests validated; task completed successfully\n- Any state \u2192 BLOCKED: Task blocked by external dependencies\n- Any state \u2192 CANCELLED: Task cancelled\n- BLOCKED \u2192 Previous state: Unblocked, return to previous state\n\nUsage:\n- CREATED: Default state for new tasks, all tasks proceed to planning (unified workflow)\n- PLANNING: Planning phase in progress (set when planning starts)\n- PLAN_PENDING_APPROVAL: Plan created, awaiting user approval and potential iteration\n- PLAN_APPROVED: Plan validated and approved (set by judge_coding_plan)\n- IMPLEMENTING: Implementation phase in progress (set when coding starts)\n- REVIEW_READY: Implementation complete and ready for code review\n- TESTING: Testing/validation phase after code review approval\n- COMPLETED: Task completed successfully (set by judge_coding_task_completion)\n- BLOCKED: Task blocked by external dependencies (manual override)\n- CANCELLED: Task cancelled (manual override)",
      "enum": [
        "created",
        "planning",
        "plan_pending_approval",
        "plan_approved",
        "implementing",
        "testing",
        "review_ready",
        "completed",
        "blocked",
        "cancelled"
      ],
      "title": "TaskState",
      "type": "string"
    },
    "WorkflowGuidance": {
      "description": "Canonical workflow guidance model used across the system.\n\nReturned by tools to provide consistent next steps and instructions for\nthe coding assistant. This is the single source of truth for the\nWorkflowGuidance schema.",
      "properties": {
        "next_tool": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Next tool to call, or None if workflow complete",
          "title": "Next Tool"
        },
        "reasoning": {
          "default": "",
          "description": "Clear explanation of why this tool should be used next",
          "title": "Reasoning",
          "type": "string"
        },
        "preparation_needed": {
          "description": "List of things that need to be prepared before calling the recommended tool",
          "items": {
            "type": "string"
          },
          "title": "Preparation Needed",
          "type": "array"
        },
        "guidance": {
          "default": "",
          "description": "Detailed step-by-step guidance for the AI assistant",
          "title": "Guidance",
          "type": "string"
        },
        "research_required": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Whether research is required for this task (only determined for new CREATED tasks)",
          "title": "Research Required"
        },
        "research_scope": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Research scope: 'none', 'light', or 'deep' (only determined for new CREATED tasks)",
          "title": "Research Scope"
        },
        "research_rationale": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Explanation of research requirements (only determined for new CREATED tasks)",
          "title": "Research Rationale"
        },
        "internal_research_required": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Whether internal codebase analysis is needed (only determined for new CREATED tasks)",
          "title": "Internal Research Required"
        },
        "risk_assessment_required": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Whether risk assessment is needed (only determined for new CREATED tasks)",
          "title": "Risk Assessment Required"
        },
        "design_patterns_enforcement": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Whether design patterns are required (only determined for new CREATED tasks)",
          "title": "Design Patterns Enforcement"
        },
        "plan_required_fields": {
          "description": "Structured specification of required fields for judge_coding_plan tool",
          "items": {
            "$ref": "#/$defs/PlanRequiredField"
          },
          "title": "Plan Required Fields",
          "type": "array"
        }
      },
      "title": "WorkflowGuidance",
      "type": "object"
    }
  },
  "properties": {
    "approved": {
      "description": "Whether the validation passed",
      "title": "Approved",
      "type": "boolean"
    },
    "required_improvements": {
      "description": "List of required improvements if not approved",
      "items": {
        "type": "string"
      },
      "title": "Required Improvements",
      "type": "array"
    },
    "feedback": {
      "description": "Detailed feedback about the validation",
      "title": "Feedback",
      "type": "string"
    },
    "suggested_diff": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Unified Git diff patch with suggested changes (optional). Provide when rejecting with concrete fixes or when proposing minor refinements.",
      "title": "Suggested Diff"
    },
    "reviewed_files": {
      "description": "Per-file reviews. Must include an entry for every file changed in the diff.",
      "items": {
        "$ref": "#/$defs/FileReview"
      },
      "title": "Reviewed Files",
      "type": "array"
    },
    "current_task_metadata": {
      "$ref": "#/$defs/TaskMetadata",
      "description": "ALWAYS current state of task metadata after operation"
    },
    "workflow_guidance": {
      "anyOf": [
        {
          "$ref": "#/$defs/WorkflowGuidance"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "LLM-generated next steps and instructions from shared method"
    }
  },
  "required": [
    "approved",
    "feedback"
  ],
  "title": "JudgeResponse",
  "type": "object"
}
  • Review only implementation code here; tests are validated via judge_testing_implementation.

  • The code_change MUST be a unified Git diff (e.g., contains diff --git, ---, +++, @@). If a diff is not provided, this tool will return approved: false and request a proper diff.

  • Always use the exact task_id; recover it via get_current_coding_task if missing.

  • If HITL was performed, update the task description/requirements via set_coding_task if text needs to be clarified for future steps

  • Implementations that re-solve commodity concerns will be rejected unless a strong justification is provided. Prefer existing repo utilities or well-known libraries over custom code.

  • Provide per-file coverage: include a reviewed_files array with one entry per changed file path in the diff, each with a brief per-file summary and any specific issues.

Inputs: code_change (required), task_id, file_path, user_requirements, +1 more. Returns: approved, feedback, reviewed_files, suggested_diff, +3 more

judge_coding_planA

Judge Coding Plan

Description

Validate a proposed plan and design against requirements, research needs, and risks. Called when workflow_guidance.next_tool == "judge_coding_plan".

Critical Tool Warning

  • Skipping this tool causes severe token inefficiency and wasted iterations.

  • Always invoke this tool at the appropriate stage to avoid extreme token loss and redundant processing.

  • Do not rely on assistant memory for identifiers. Always pass the exact task_id and recover it via get_current_coding_task if missing.

Prerequisites

  • Thoroughly analyze requirements, propose a concrete plan, and produce a system design

  • Include a Problem Domain Statement, a Library Selection Map (well-known libraries by purpose, with justifications), and an Internal Reuse Map (existing repo components with paths)

Human-in-the-Loop (HITL) checks

  • If foundational choices are ambiguous or missing (e.g., framework/library, UI vs CLI, web vs desktop, API style, auth, hosting), first call raise_missing_requirements to elicit user preferences

  • If the plan proposes changing an already understood fundamental choice, call raise_obstacle to involve the user’s decision

  • These HITL tools do not return next_tool; rely on workflow guidance to determine the next tool after elicitation

Args

  • task_id: string — Task UUID (required)

  • plan: string — Detailed implementation plan (required)

  • design: string — Architecture, components, data flow, key decisions (required)

  • research: string — Findings and rationale (provide if available)

  • research_urls: list[string] — URLs for external research (if required)

  • context: string — Additional project context

  • problem_domain: string — Concise problem domain statement (optional but recommended)

  • problem_non_goals: list[string] — Non-goals/out-of-scope items (optional)

  • library_plan: list[object] — Library Selection Map entries: {purpose, selection, source: internal|external|custom, justification}

  • internal_reuse_components: list[object] — Internal Reuse Map entries: {path, purpose, notes}

  • design_patterns: list[object] — Design patterns to be applied: {name, area} (required when current_task_metadata.design_patterns_enforcement=true)

  • identified_risks: list[string] — Enumerated risks; required when current_task_metadata.risk_assessment_required=true (the server will auto-seed sensible defaults if omitted)

  • risk_mitigation_strategies: list[string] — Mitigations aligned one-to-one with identified_risks

Returns

  • Response JSON schema (JudgeResponse):

{
  "$defs": {
    "FileReview": {
      "properties": {
        "path": {
          "description": "File path reviewed",
          "title": "Path",
          "type": "string"
        },
        "feedback": {
          "description": "Per-file feedback summary",
          "title": "Feedback",
          "type": "string"
        },
        "approved": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Optional per-file approval or risk flag",
          "title": "Approved"
        }
      },
      "required": [
        "path",
        "feedback"
      ],
      "title": "FileReview",
      "type": "object"
    },
    "LibraryPlanItem": {
      "properties": {
        "purpose": {
          "description": "Non-domain concern or integration point this library addresses",
          "title": "Purpose",
          "type": "string"
        },
        "selection": {
          "description": "Chosen library or internal utility (name and optional version)",
          "title": "Selection",
          "type": "string"
        },
        "source": {
          "description": "Source of solution: 'internal' for repo utility, 'external' for well-known library, 'custom' for in-house code",
          "title": "Source",
          "type": "string"
        },
        "justification": {
          "default": "",
          "description": "One-line rationale for the selection and any trade-offs",
          "title": "Justification",
          "type": "string"
        }
      },
      "required": [
        "purpose",
        "selection",
        "source"
      ],
      "title": "LibraryPlanItem",
      "type": "object"
    },
    "PlanRequiredField": {
      "description": "Specification for a required field in judge_coding_plan.",
      "properties": {
        "name": {
          "description": "Field name in the judge_coding_plan tool",
          "title": "Name",
          "type": "string"
        },
        "type": {
          "description": "Expected data type (string, list[str], list[dict], etc.)",
          "title": "Type",
          "type": "string"
        },
        "description": {
          "description": "What this field should contain",
          "title": "Description",
          "type": "string"
        },
        "required": {
          "description": "Whether this field is required",
          "title": "Required",
          "type": "boolean"
        },
        "conditional_on": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Task metadata field this requirement depends on (e.g., 'design_patterns_enforcement')",
          "title": "Conditional On"
        },
        "example_value": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Example of what this field should contain",
          "title": "Example Value"
        }
      },
      "required": [
        "name",
        "type",
        "description",
        "required"
      ],
      "title": "PlanRequiredField",
      "type": "object"
    },
    "RequirementsVersion": {
      "description": "A version of user requirements with timestamp and source.",
      "properties": {
        "content": {
          "title": "Content",
          "type": "string"
        },
        "source": {
          "title": "Source",
          "type": "string"
        },
        "timestamp": {
          "title": "Timestamp",
          "type": "integer"
        }
      },
      "required": [
        "content",
        "source"
      ],
      "title": "RequirementsVersion",
      "type": "object"
    },
    "ResearchScope": {
      "description": "Research scope enum for workflow-driven research validation.\n\nDetermines the depth and requirements for research validation:\n- NONE: No research required for this task complexity\n- LIGHT: Light research required (1+ authoritative domain source)\n- DEEP: Deep research required (2+ authoritative domain sources)",
      "enum": [
        "none",
        "light",
        "deep"
      ],
      "title": "ResearchScope",
      "type": "string"
    },
    "ReuseComponent": {
      "properties": {
        "path": {
          "description": "Repository path to the reusable component",
          "title": "Path",
          "type": "string"
        },
        "purpose": {
          "default": "",
          "description": "What part of the task this component will support",
          "title": "Purpose",
          "type": "string"
        },
        "notes": {
          "default": "",
          "description": "Any integration notes or caveats",
          "title": "Notes",
          "type": "string"
        }
      },
      "required": [
        "path"
      ],
      "title": "ReuseComponent",
      "type": "object"
    },
    "TaskMetadata": {
      "description": "Lightweight metadata for coding tasks that flows with memory layer.\n\nThis model serves as the foundation for the enhanced workflow v3 system,\nreplacing session-based tracking with task-centric approach.",
      "properties": {
        "task_id": {
          "description": "IMMUTABLE: Auto-generated UUID, primary key for memory storage",
          "title": "Task Id",
          "type": "string"
        },
        "created_at": {
          "description": "IMMUTABLE: Task creation timestamp (epoch seconds)",
          "title": "Created At",
          "type": "integer"
        },
        "title": {
          "description": "Display title for coding task (updatable)",
          "title": "Title",
          "type": "string"
        },
        "description": {
          "description": "Detailed coding task description (updatable)",
          "title": "Description",
          "type": "string"
        },
        "user_requirements": {
          "default": "",
          "description": "Current coding requirements (updatable)",
          "title": "User Requirements",
          "type": "string"
        },
        "state": {
          "$ref": "#/$defs/TaskState",
          "default": "created",
          "description": "Current task state (updatable, follows TaskState transitions)"
        },
        "task_size": {
          "$ref": "#/$defs/TaskSize",
          "description": "Task size classification for workflow optimization (XS=simple fixes, S=minor features, M=standard, L=complex, XL=major changes)"
        },
        "user_requirements_history": {
          "description": "History of requirements changes",
          "items": {
            "$ref": "#/$defs/RequirementsVersion"
          },
          "title": "User Requirements History",
          "type": "array"
        },
        "accumulated_diff": {
          "additionalProperties": true,
          "description": "Code changes accumulated over time",
          "title": "Accumulated Diff",
          "type": "object"
        },
        "modified_files": {
          "description": "List of file paths that were created or modified during task implementation",
          "items": {
            "type": "string"
          },
          "title": "Modified Files",
          "type": "array"
        },
        "test_files": {
          "description": "List of test file paths that were created during testing phase",
          "items": {
            "type": "string"
          },
          "title": "Test Files",
          "type": "array"
        },
        "test_status": {
          "additionalProperties": {
            "type": "string"
          },
          "description": "Status of different test types (unit, integration, e2e, etc.)",
          "title": "Test Status",
          "type": "object"
        },
        "updated_at": {
          "description": "Last update timestamp (epoch seconds)",
          "title": "Updated At",
          "type": "integer"
        },
        "tags": {
          "description": "Coding-related tags",
          "items": {
            "type": "string"
          },
          "title": "Tags",
          "type": "array"
        },
        "problem_domain": {
          "default": "",
          "description": "Concise statement of the problem domain and scope for this task",
          "title": "Problem Domain",
          "type": "string"
        },
        "problem_non_goals": {
          "description": "Explicit non-goals/boundaries to prevent scope creep and re-solving commodity concerns",
          "items": {
            "type": "string"
          },
          "title": "Problem Non Goals",
          "type": "array"
        },
        "library_plan": {
          "description": "Planned libraries/utilities per purpose; prefer internal reuse and well-known libraries; custom code only with justification",
          "items": {
            "$ref": "#/$defs/LibraryPlanItem"
          },
          "title": "Library Plan",
          "type": "array"
        },
        "internal_reuse_components": {
          "description": "Existing repository components/utilities to reuse with paths and purposes",
          "items": {
            "$ref": "#/$defs/ReuseComponent"
          },
          "title": "Internal Reuse Components",
          "type": "array"
        },
        "research_required": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Whether research is required by workflow guidance (None=undetermined, True=required, False=optional)",
          "title": "Research Required"
        },
        "research_scope": {
          "$ref": "#/$defs/ResearchScope",
          "default": "none",
          "description": "Research scope determined by workflow: none|light|deep"
        },
        "research_completed": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Epoch seconds when research validation passed",
          "title": "Research Completed"
        },
        "research_rationale": {
          "default": "",
          "description": "Explanation of why research was required and how the scope was determined",
          "title": "Research Rationale",
          "type": "string"
        },
        "expected_url_count": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "LLM-determined expected number of research URLs based on task complexity",
          "title": "Expected Url Count"
        },
        "minimum_url_count": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "LLM-determined minimum acceptable URL count for adequate research",
          "title": "Minimum Url Count"
        },
        "url_requirement_reasoning": {
          "default": "",
          "description": "LLM-generated explanation of why specific URL count is needed for this task",
          "title": "Url Requirement Reasoning",
          "type": "string"
        },
        "research_complexity_analysis": {
          "anyOf": [
            {
              "additionalProperties": true,
              "type": "object"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Detailed complexity analysis factors from LLM (domain, tech maturity, integration scope, etc.)",
          "title": "Research Complexity Analysis"
        },
        "internal_research_required": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Whether internal codebase research is needed (None=undetermined, True=required, False=not needed)",
          "title": "Internal Research Required"
        },
        "related_code_snippets": {
          "description": "Related code snippets from the codebase that are relevant to this task",
          "items": {
            "type": "string"
          },
          "title": "Related Code Snippets",
          "type": "array"
        },
        "risk_assessment_required": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Whether risk assessment is needed (None=undetermined, True=required, False=not needed)",
          "title": "Risk Assessment Required"
        },
        "identified_risks": {
          "description": "Areas that could be harmed by the proposed changes",
          "items": {
            "type": "string"
          },
          "title": "Identified Risks",
          "type": "array"
        },
        "risk_mitigation_strategies": {
          "description": "Strategies to mitigate identified risks",
          "items": {
            "type": "string"
          },
          "title": "Risk Mitigation Strategies",
          "type": "array"
        },
        "design_patterns_enforcement": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Whether design patterns are required for this task (None=undetermined, True=required, False=not needed)",
          "title": "Design Patterns Enforcement"
        },
        "plan_approved_at": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Timestamp when plan was approved by judge_coding_plan (None=not approved)",
          "title": "Plan Approved At"
        },
        "plan_rejection_count": {
          "default": 0,
          "description": "Number of times the plan has been rejected (max 1 allowed)",
          "title": "Plan Rejection Count",
          "type": "integer"
        },
        "code_approved_files": {
          "additionalProperties": {
            "type": "integer"
          },
          "description": "Dictionary mapping file paths to approval timestamps from judge_code_change",
          "title": "Code Approved Files",
          "type": "object"
        },
        "testing_approved_at": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Timestamp when testing was approved by judge_testing_implementation (None=not approved)",
          "title": "Testing Approved At"
        },
        "all_approvals_validated": {
          "default": false,
          "description": "Whether all required approvals (plan, code, testing) have been validated",
          "title": "All Approvals Validated",
          "type": "boolean"
        }
      },
      "required": [
        "title",
        "description",
        "task_size"
      ],
      "title": "TaskMetadata",
      "type": "object"
    },
    "TaskSize": {
      "description": "Task size classification for workflow optimization.\n\nSizes are based on estimated complexity and time requirements:\n- XS: Extra Small - Simple fixes, typos, minor config changes (< 30 minutes)\n- S: Small - Minor features, simple refactoring (30 minutes - 2 hours)\n- M: Medium - Standard features, moderate complexity (2-8 hours) - DEFAULT\n- L: Large - Complex features, multiple components (1-3 days)\n- XL: Extra Large - Major system changes, architectural updates (3+ days)\n\nThis classification determines planning complexity and validation depth:\n- XS/S: Basic planning requirements, streamlined validation\n- M: Standard planning and validation\n- L/XL: Comprehensive planning with enhanced validation (library plans, risk assessment, design patterns)\n\nAll tasks follow the unified workflow: CREATED \u2192 PLANNING \u2192 PLAN_APPROVED \u2192 IMPLEMENTING \u2192 REVIEW_READY \u2192 TESTING \u2192 COMPLETED",
      "enum": [
        "xs",
        "s",
        "m",
        "l",
        "xl"
      ],
      "title": "TaskSize",
      "type": "string"
    },
    "TaskState": {
      "description": "Coding task state enum with well-documented transitions.\n\nState Transitions:\n- CREATED \u2192 PLANNING: Task created, ready for planning phase (XS/S may skip to IMPLEMENTING)\n- PLANNING \u2192 PLAN_PENDING_APPROVAL: Plan created, awaiting user approval\n- PLAN_PENDING_APPROVAL \u2192 PLANNING: User requests plan changes\n- PLAN_PENDING_APPROVAL \u2192 PLAN_APPROVED: User approves plan\n- PLAN_APPROVED \u2192 IMPLEMENTING: Implementation phase started\n- IMPLEMENTING \u2192 IMPLEMENTING: Multiple code changes during implementation\n- IMPLEMENTING \u2192 REVIEW_READY: Implementation complete, ready for code review\n- REVIEW_READY \u2192 TESTING: Code review approved, ready for testing validation\n- TESTING \u2192 TESTING: Multiple test iterations\n- TESTING \u2192 COMPLETED: All tests validated; task completed successfully\n- Any state \u2192 BLOCKED: Task blocked by external dependencies\n- Any state \u2192 CANCELLED: Task cancelled\n- BLOCKED \u2192 Previous state: Unblocked, return to previous state\n\nUsage:\n- CREATED: Default state for new tasks, all tasks proceed to planning (unified workflow)\n- PLANNING: Planning phase in progress (set when planning starts)\n- PLAN_PENDING_APPROVAL: Plan created, awaiting user approval and potential iteration\n- PLAN_APPROVED: Plan validated and approved (set by judge_coding_plan)\n- IMPLEMENTING: Implementation phase in progress (set when coding starts)\n- REVIEW_READY: Implementation complete and ready for code review\n- TESTING: Testing/validation phase after code review approval\n- COMPLETED: Task completed successfully (set by judge_coding_task_completion)\n- BLOCKED: Task blocked by external dependencies (manual override)\n- CANCELLED: Task cancelled (manual override)",
      "enum": [
        "created",
        "planning",
        "plan_pending_approval",
        "plan_approved",
        "implementing",
        "testing",
        "review_ready",
        "completed",
        "blocked",
        "cancelled"
      ],
      "title": "TaskState",
      "type": "string"
    },
    "WorkflowGuidance": {
      "description": "Canonical workflow guidance model used across the system.\n\nReturned by tools to provide consistent next steps and instructions for\nthe coding assistant. This is the single source of truth for the\nWorkflowGuidance schema.",
      "properties": {
        "next_tool": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Next tool to call, or None if workflow complete",
          "title": "Next Tool"
        },
        "reasoning": {
          "default": "",
          "description": "Clear explanation of why this tool should be used next",
          "title": "Reasoning",
          "type": "string"
        },
        "preparation_needed": {
          "description": "List of things that need to be prepared before calling the recommended tool",
          "items": {
            "type": "string"
          },
          "title": "Preparation Needed",
          "type": "array"
        },
        "guidance": {
          "default": "",
          "description": "Detailed step-by-step guidance for the AI assistant",
          "title": "Guidance",
          "type": "string"
        },
        "research_required": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Whether research is required for this task (only determined for new CREATED tasks)",
          "title": "Research Required"
        },
        "research_scope": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Research scope: 'none', 'light', or 'deep' (only determined for new CREATED tasks)",
          "title": "Research Scope"
        },
        "research_rationale": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Explanation of research requirements (only determined for new CREATED tasks)",
          "title": "Research Rationale"
        },
        "internal_research_required": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Whether internal codebase analysis is needed (only determined for new CREATED tasks)",
          "title": "Internal Research Required"
        },
        "risk_assessment_required": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Whether risk assessment is needed (only determined for new CREATED tasks)",
          "title": "Risk Assessment Required"
        },
        "design_patterns_enforcement": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Whether design patterns are required (only determined for new CREATED tasks)",
          "title": "Design Patterns Enforcement"
        },
        "plan_required_fields": {
          "description": "Structured specification of required fields for judge_coding_plan tool",
          "items": {
            "$ref": "#/$defs/PlanRequiredField"
          },
          "title": "Plan Required Fields",
          "type": "array"
        }
      },
      "title": "WorkflowGuidance",
      "type": "object"
    }
  },
  "properties": {
    "approved": {
      "description": "Whether the validation passed",
      "title": "Approved",
      "type": "boolean"
    },
    "required_improvements": {
      "description": "List of required improvements if not approved",
      "items": {
        "type": "string"
      },
      "title": "Required Improvements",
      "type": "array"
    },
    "feedback": {
      "description": "Detailed feedback about the validation",
      "title": "Feedback",
      "type": "string"
    },
    "suggested_diff": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Unified Git diff patch with suggested changes (optional). Provide when rejecting with concrete fixes or when proposing minor refinements.",
      "title": "Suggested Diff"
    },
    "reviewed_files": {
      "description": "Per-file reviews. Must include an entry for every file changed in the diff.",
      "items": {
        "$ref": "#/$defs/FileReview"
      },
      "title": "Reviewed Files",
      "type": "array"
    },
    "current_task_metadata": {
      "$ref": "#/$defs/TaskMetadata",
      "description": "ALWAYS current state of task metadata after operation"
    },
    "workflow_guidance": {
      "anyOf": [
        {
          "$ref": "#/$defs/WorkflowGuidance"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "LLM-generated next steps and instructions from shared method"
    }
  },
  "required": [
    "approved",
    "feedback"
  ],
  "title": "JudgeResponse",
  "type": "object"
}

Notes

  • Follow workflow_guidance.next_tool for the next step. Use the exact task_id from set_coding_task; recover via get_current_coding_task if missing.

  • Plans missing a library selection map and internal reuse map will be rejected.

Inputs: plan (required), design (required), research (required), research_urls (required), +10 more. Returns: approved, feedback, reviewed_files, suggested_diff, +3 more

judge_coding_task_completionA

Judge Coding Task Completion

Description

Final validation gate before declaring a task complete. Called when workflow_guidance.next_tool == "judge_coding_task_completion".

Critical Tool Warning

  • Skipping this tool causes severe token inefficiency and wasted iterations.

  • Always invoke this tool at the appropriate stage to avoid extreme token loss and redundant processing.

  • Do not rely on assistant memory for identifiers. Always pass the exact task_id and recover it via get_current_coding_task if missing.

Prerequisites

  • Plan approved via judge_coding_plan, code approved via judge_code_change, tests approved via judge_testing_implementation

Args

  • task_id: string — Task UUID (required)

  • completion_summary: string — Summary of implemented work (required)

  • requirements_met: list[string] — Requirements satisfied (required)

  • implementation_details: string — Key implementation details (required)

  • remaining_work: list[string] — Open items if any (optional)

  • quality_notes: string — Quality/standards notes (optional)

  • testing_status: string — Testing status summary (optional)

Returns

  • Response JSON schema (TaskCompletionResult):

{
  "$defs": {
    "LibraryPlanItem": {
      "properties": {
        "purpose": {
          "description": "Non-domain concern or integration point this library addresses",
          "title": "Purpose",
          "type": "string"
        },
        "selection": {
          "description": "Chosen library or internal utility (name and optional version)",
          "title": "Selection",
          "type": "string"
        },
        "source": {
          "description": "Source of solution: 'internal' for repo utility, 'external' for well-known library, 'custom' for in-house code",
          "title": "Source",
          "type": "string"
        },
        "justification": {
          "default": "",
          "description": "One-line rationale for the selection and any trade-offs",
          "title": "Justification",
          "type": "string"
        }
      },
      "required": [
        "purpose",
        "selection",
        "source"
      ],
      "title": "LibraryPlanItem",
      "type": "object"
    },
    "PlanRequiredField": {
      "description": "Specification for a required field in judge_coding_plan.",
      "properties": {
        "name": {
          "description": "Field name in the judge_coding_plan tool",
          "title": "Name",
          "type": "string"
        },
        "type": {
          "description": "Expected data type (string, list[str], list[dict], etc.)",
          "title": "Type",
          "type": "string"
        },
        "description": {
          "description": "What this field should contain",
          "title": "Description",
          "type": "string"
        },
        "required": {
          "description": "Whether this field is required",
          "title": "Required",
          "type": "boolean"
        },
        "conditional_on": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Task metadata field this requirement depends on (e.g., 'design_patterns_enforcement')",
          "title": "Conditional On"
        },
        "example_value": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Example of what this field should contain",
          "title": "Example Value"
        }
      },
      "required": [
        "name",
        "type",
        "description",
        "required"
      ],
      "title": "PlanRequiredField",
      "type": "object"
    },
    "RequirementsVersion": {
      "description": "A version of user requirements with timestamp and source.",
      "properties": {
        "content": {
          "title": "Content",
          "type": "string"
        },
        "source": {
          "title": "Source",
          "type": "string"
        },
        "timestamp": {
          "title": "Timestamp",
          "type": "integer"
        }
      },
      "required": [
        "content",
        "source"
      ],
      "title": "RequirementsVersion",
      "type": "object"
    },
    "ResearchScope": {
      "description": "Research scope enum for workflow-driven research validation.\n\nDetermines the depth and requirements for research validation:\n- NONE: No research required for this task complexity\n- LIGHT: Light research required (1+ authoritative domain source)\n- DEEP: Deep research required (2+ authoritative domain sources)",
      "enum": [
        "none",
        "light",
        "deep"
      ],
      "title": "ResearchScope",
      "type": "string"
    },
    "ReuseComponent": {
      "properties": {
        "path": {
          "description": "Repository path to the reusable component",
          "title": "Path",
          "type": "string"
        },
        "purpose": {
          "default": "",
          "description": "What part of the task this component will support",
          "title": "Purpose",
          "type": "string"
        },
        "notes": {
          "default": "",
          "description": "Any integration notes or caveats",
          "title": "Notes",
          "type": "string"
        }
      },
      "required": [
        "path"
      ],
      "title": "ReuseComponent",
      "type": "object"
    },
    "TaskMetadata": {
      "description": "Lightweight metadata for coding tasks that flows with memory layer.\n\nThis model serves as the foundation for the enhanced workflow v3 system,\nreplacing session-based tracking with task-centric approach.",
      "properties": {
        "task_id": {
          "description": "IMMUTABLE: Auto-generated UUID, primary key for memory storage",
          "title": "Task Id",
          "type": "string"
        },
        "created_at": {
          "description": "IMMUTABLE: Task creation timestamp (epoch seconds)",
          "title": "Created At",
          "type": "integer"
        },
        "title": {
          "description": "Display title for coding task (updatable)",
          "title": "Title",
          "type": "string"
        },
        "description": {
          "description": "Detailed coding task description (updatable)",
          "title": "Description",
          "type": "string"
        },
        "user_requirements": {
          "default": "",
          "description": "Current coding requirements (updatable)",
          "title": "User Requirements",
          "type": "string"
        },
        "state": {
          "$ref": "#/$defs/TaskState",
          "default": "created",
          "description": "Current task state (updatable, follows TaskState transitions)"
        },
        "task_size": {
          "$ref": "#/$defs/TaskSize",
          "description": "Task size classification for workflow optimization (XS=simple fixes, S=minor features, M=standard, L=complex, XL=major changes)"
        },
        "user_requirements_history": {
          "description": "History of requirements changes",
          "items": {
            "$ref": "#/$defs/RequirementsVersion"
          },
          "title": "User Requirements History",
          "type": "array"
        },
        "accumulated_diff": {
          "additionalProperties": true,
          "description": "Code changes accumulated over time",
          "title": "Accumulated Diff",
          "type": "object"
        },
        "modified_files": {
          "description": "List of file paths that were created or modified during task implementation",
          "items": {
            "type": "string"
          },
          "title": "Modified Files",
          "type": "array"
        },
        "test_files": {
          "description": "List of test file paths that were created during testing phase",
          "items": {
            "type": "string"
          },
          "title": "Test Files",
          "type": "array"
        },
        "test_status": {
          "additionalProperties": {
            "type": "string"
          },
          "description": "Status of different test types (unit, integration, e2e, etc.)",
          "title": "Test Status",
          "type": "object"
        },
        "updated_at": {
          "description": "Last update timestamp (epoch seconds)",
          "title": "Updated At",
          "type": "integer"
        },
        "tags": {
          "description": "Coding-related tags",
          "items": {
            "type": "string"
          },
          "title": "Tags",
          "type": "array"
        },
        "problem_domain": {
          "default": "",
          "description": "Concise statement of the problem domain and scope for this task",
          "title": "Problem Domain",
          "type": "string"
        },
        "problem_non_goals": {
          "description": "Explicit non-goals/boundaries to prevent scope creep and re-solving commodity concerns",
          "items": {
            "type": "string"
          },
          "title": "Problem Non Goals",
          "type": "array"
        },
        "library_plan": {
          "description": "Planned libraries/utilities per purpose; prefer internal reuse and well-known libraries; custom code only with justification",
          "items": {
            "$ref": "#/$defs/LibraryPlanItem"
          },
          "title": "Library Plan",
          "type": "array"
        },
        "internal_reuse_components": {
          "description": "Existing repository components/utilities to reuse with paths and purposes",
          "items": {
            "$ref": "#/$defs/ReuseComponent"
          },
          "title": "Internal Reuse Components",
          "type": "array"
        },
        "research_required": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Whether research is required by workflow guidance (None=undetermined, True=required, False=optional)",
          "title": "Research Required"
        },
        "research_scope": {
          "$ref": "#/$defs/ResearchScope",
          "default": "none",
          "description": "Research scope determined by workflow: none|light|deep"
        },
        "research_completed": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Epoch seconds when research validation passed",
          "title": "Research Completed"
        },
        "research_rationale": {
          "default": "",
          "description": "Explanation of why research was required and how the scope was determined",
          "title": "Research Rationale",
          "type": "string"
        },
        "expected_url_count": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "LLM-determined expected number of research URLs based on task complexity",
          "title": "Expected Url Count"
        },
        "minimum_url_count": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "LLM-determined minimum acceptable URL count for adequate research",
          "title": "Minimum Url Count"
        },
        "url_requirement_reasoning": {
          "default": "",
          "description": "LLM-generated explanation of why specific URL count is needed for this task",
          "title": "Url Requirement Reasoning",
          "type": "string"
        },
        "research_complexity_analysis": {
          "anyOf": [
            {
              "additionalProperties": true,
              "type": "object"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Detailed complexity analysis factors from LLM (domain, tech maturity, integration scope, etc.)",
          "title": "Research Complexity Analysis"
        },
        "internal_research_required": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Whether internal codebase research is needed (None=undetermined, True=required, False=not needed)",
          "title": "Internal Research Required"
        },
        "related_code_snippets": {
          "description": "Related code snippets from the codebase that are relevant to this task",
          "items": {
            "type": "string"
          },
          "title": "Related Code Snippets",
          "type": "array"
        },
        "risk_assessment_required": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Whether risk assessment is needed (None=undetermined, True=required, False=not needed)",
          "title": "Risk Assessment Required"
        },
        "identified_risks": {
          "description": "Areas that could be harmed by the proposed changes",
          "items": {
            "type": "string"
          },
          "title": "Identified Risks",
          "type": "array"
        },
        "risk_mitigation_strategies": {
          "description": "Strategies to mitigate identified risks",
          "items": {
            "type": "string"
          },
          "title": "Risk Mitigation Strategies",
          "type": "array"
        },
        "design_patterns_enforcement": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Whether design patterns are required for this task (None=undetermined, True=required, False=not needed)",
          "title": "Design Patterns Enforcement"
        },
        "plan_approved_at": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Timestamp when plan was approved by judge_coding_plan (None=not approved)",
          "title": "Plan Approved At"
        },
        "plan_rejection_count": {
          "default": 0,
          "description": "Number of times the plan has been rejected (max 1 allowed)",
          "title": "Plan Rejection Count",
          "type": "integer"
        },
        "code_approved_files": {
          "additionalProperties": {
            "type": "integer"
          },
          "description": "Dictionary mapping file paths to approval timestamps from judge_code_change",
          "title": "Code Approved Files",
          "type": "object"
        },
        "testing_approved_at": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Timestamp when testing was approved by judge_testing_implementation (None=not approved)",
          "title": "Testing Approved At"
        },
        "all_approvals_validated": {
          "default": false,
          "description": "Whether all required approvals (plan, code, testing) have been validated",
          "title": "All Approvals Validated",
          "type": "boolean"
        }
      },
      "required": [
        "title",
        "description",
        "task_size"
      ],
      "title": "TaskMetadata",
      "type": "object"
    },
    "TaskSize": {
      "description": "Task size classification for workflow optimization.\n\nSizes are based on estimated complexity and time requirements:\n- XS: Extra Small - Simple fixes, typos, minor config changes (< 30 minutes)\n- S: Small - Minor features, simple refactoring (30 minutes - 2 hours)\n- M: Medium - Standard features, moderate complexity (2-8 hours) - DEFAULT\n- L: Large - Complex features, multiple components (1-3 days)\n- XL: Extra Large - Major system changes, architectural updates (3+ days)\n\nThis classification determines planning complexity and validation depth:\n- XS/S: Basic planning requirements, streamlined validation\n- M: Standard planning and validation\n- L/XL: Comprehensive planning with enhanced validation (library plans, risk assessment, design patterns)\n\nAll tasks follow the unified workflow: CREATED \u2192 PLANNING \u2192 PLAN_APPROVED \u2192 IMPLEMENTING \u2192 REVIEW_READY \u2192 TESTING \u2192 COMPLETED",
      "enum": [
        "xs",
        "s",
        "m",
        "l",
        "xl"
      ],
      "title": "TaskSize",
      "type": "string"
    },
    "TaskState": {
      "description": "Coding task state enum with well-documented transitions.\n\nState Transitions:\n- CREATED \u2192 PLANNING: Task created, ready for planning phase (XS/S may skip to IMPLEMENTING)\n- PLANNING \u2192 PLAN_PENDING_APPROVAL: Plan created, awaiting user approval\n- PLAN_PENDING_APPROVAL \u2192 PLANNING: User requests plan changes\n- PLAN_PENDING_APPROVAL \u2192 PLAN_APPROVED: User approves plan\n- PLAN_APPROVED \u2192 IMPLEMENTING: Implementation phase started\n- IMPLEMENTING \u2192 IMPLEMENTING: Multiple code changes during implementation\n- IMPLEMENTING \u2192 REVIEW_READY: Implementation complete, ready for code review\n- REVIEW_READY \u2192 TESTING: Code review approved, ready for testing validation\n- TESTING \u2192 TESTING: Multiple test iterations\n- TESTING \u2192 COMPLETED: All tests validated; task completed successfully\n- Any state \u2192 BLOCKED: Task blocked by external dependencies\n- Any state \u2192 CANCELLED: Task cancelled\n- BLOCKED \u2192 Previous state: Unblocked, return to previous state\n\nUsage:\n- CREATED: Default state for new tasks, all tasks proceed to planning (unified workflow)\n- PLANNING: Planning phase in progress (set when planning starts)\n- PLAN_PENDING_APPROVAL: Plan created, awaiting user approval and potential iteration\n- PLAN_APPROVED: Plan validated and approved (set by judge_coding_plan)\n- IMPLEMENTING: Implementation phase in progress (set when coding starts)\n- REVIEW_READY: Implementation complete and ready for code review\n- TESTING: Testing/validation phase after code review approval\n- COMPLETED: Task completed successfully (set by judge_coding_task_completion)\n- BLOCKED: Task blocked by external dependencies (manual override)\n- CANCELLED: Task cancelled (manual override)",
      "enum": [
        "created",
        "planning",
        "plan_pending_approval",
        "plan_approved",
        "implementing",
        "testing",
        "review_ready",
        "completed",
        "blocked",
        "cancelled"
      ],
      "title": "TaskState",
      "type": "string"
    },
    "WorkflowGuidance": {
      "description": "Canonical workflow guidance model used across the system.\n\nReturned by tools to provide consistent next steps and instructions for\nthe coding assistant. This is the single source of truth for the\nWorkflowGuidance schema.",
      "properties": {
        "next_tool": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Next tool to call, or None if workflow complete",
          "title": "Next Tool"
        },
        "reasoning": {
          "default": "",
          "description": "Clear explanation of why this tool should be used next",
          "title": "Reasoning",
          "type": "string"
        },
        "preparation_needed": {
          "description": "List of things that need to be prepared before calling the recommended tool",
          "items": {
            "type": "string"
          },
          "title": "Preparation Needed",
          "type": "array"
        },
        "guidance": {
          "default": "",
          "description": "Detailed step-by-step guidance for the AI assistant",
          "title": "Guidance",
          "type": "string"
        },
        "research_required": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Whether research is required for this task (only determined for new CREATED tasks)",
          "title": "Research Required"
        },
        "research_scope": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Research scope: 'none', 'light', or 'deep' (only determined for new CREATED tasks)",
          "title": "Research Scope"
        },
        "research_rationale": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Explanation of research requirements (only determined for new CREATED tasks)",
          "title": "Research Rationale"
        },
        "internal_research_required": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Whether internal codebase analysis is needed (only determined for new CREATED tasks)",
          "title": "Internal Research Required"
        },
        "risk_assessment_required": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Whether risk assessment is needed (only determined for new CREATED tasks)",
          "title": "Risk Assessment Required"
        },
        "design_patterns_enforcement": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Whether design patterns are required (only determined for new CREATED tasks)",
          "title": "Design Patterns Enforcement"
        },
        "plan_required_fields": {
          "description": "Structured specification of required fields for judge_coding_plan tool",
          "items": {
            "$ref": "#/$defs/PlanRequiredField"
          },
          "title": "Plan Required Fields",
          "type": "array"
        }
      },
      "title": "WorkflowGuidance",
      "type": "object"
    }
  },
  "properties": {
    "approved": {
      "description": "Whether the task completion is approved",
      "title": "Approved",
      "type": "boolean"
    },
    "feedback": {
      "description": "Detailed feedback about the completion validation",
      "title": "Feedback",
      "type": "string"
    },
    "required_improvements": {
      "description": "List of required improvements if not approved",
      "items": {
        "type": "string"
      },
      "title": "Required Improvements",
      "type": "array"
    },
    "current_task_metadata": {
      "$ref": "#/$defs/TaskMetadata",
      "description": "ALWAYS current state of task metadata after operation"
    },
    "workflow_guidance": {
      "$ref": "#/$defs/WorkflowGuidance",
      "description": "LLM-generated next steps and instructions (or workflow complete)"
    }
  },
  "required": [
    "approved",
    "feedback",
    "current_task_metadata",
    "workflow_guidance"
  ],
  "title": "TaskCompletionResult",
  "type": "object"
}

Notes

  • The AI coding assistant MUST NOT present or claim task completion, or provide a final completion summary to the user, without successfully calling this tool and receiving approval.

  • Always use the exact task_id; if missing due to memory limits, recover it via get_current_coding_task.

Inputs: task_id (required), requirements_met (required), completion_summary (required), implementation_details (required), +3 mor… Returns: approved, feedback, workflow_guidance, current_task_metadata, +1 more

judge_testing_implementationA

Judge Testing Implementation

Description

Validate test quality, coverage, and execution results after code review is approved. The input MUST include real test evidence (raw test runner output and list of test files). Called when workflow_guidance.next_tool == "judge_testing_implementation".

Critical Tool Warning

  • Skipping this tool causes severe token inefficiency and wasted iterations.

  • Always invoke this tool at the appropriate stage to avoid extreme token loss and redundant processing.

  • Do not rely on assistant memory for identifiers. Always pass the exact task_id and recover it via get_current_coding_task if missing.

Args

  • task_id: string — Task UUID (required)

  • test_summary: string — Summary of the implemented tests (required)

  • test_files: list[string] — Paths to created/modified test files (required)

  • test_execution_results: string — Raw test runner output (required). For example, pytest/jest/mocha/go test/JUnit logs including pass/fail counts.

  • test_coverage_report: string — Coverage details (optional)

  • test_types_implemented: list[string] — e.g., unit, integration, e2e (optional)

  • testing_framework: string — e.g., pytest, jest (optional)

  • performance_test_results: string — Performance results (optional)

  • manual_test_notes: string — Manual testing notes (optional)

Returns

  • Response JSON schema (JudgeResponse):

{
  "$defs": {
    "FileReview": {
      "properties": {
        "path": {
          "description": "File path reviewed",
          "title": "Path",
          "type": "string"
        },
        "feedback": {
          "description": "Per-file feedback summary",
          "title": "Feedback",
          "type": "string"
        },
        "approved": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Optional per-file approval or risk flag",
          "title": "Approved"
        }
      },
      "required": [
        "path",
        "feedback"
      ],
      "title": "FileReview",
      "type": "object"
    },
    "LibraryPlanItem": {
      "properties": {
        "purpose": {
          "description": "Non-domain concern or integration point this library addresses",
          "title": "Purpose",
          "type": "string"
        },
        "selection": {
          "description": "Chosen library or internal utility (name and optional version)",
          "title": "Selection",
          "type": "string"
        },
        "source": {
          "description": "Source of solution: 'internal' for repo utility, 'external' for well-known library, 'custom' for in-house code",
          "title": "Source",
          "type": "string"
        },
        "justification": {
          "default": "",
          "description": "One-line rationale for the selection and any trade-offs",
          "title": "Justification",
          "type": "string"
        }
      },
      "required": [
        "purpose",
        "selection",
        "source"
      ],
      "title": "LibraryPlanItem",
      "type": "object"
    },
    "PlanRequiredField": {
      "description": "Specification for a required field in judge_coding_plan.",
      "properties": {
        "name": {
          "description": "Field name in the judge_coding_plan tool",
          "title": "Name",
          "type": "string"
        },
        "type": {
          "description": "Expected data type (string, list[str], list[dict], etc.)",
          "title": "Type",
          "type": "string"
        },
        "description": {
          "description": "What this field should contain",
          "title": "Description",
          "type": "string"
        },
        "required": {
          "description": "Whether this field is required",
          "title": "Required",
          "type": "boolean"
        },
        "conditional_on": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Task metadata field this requirement depends on (e.g., 'design_patterns_enforcement')",
          "title": "Conditional On"
        },
        "example_value": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Example of what this field should contain",
          "title": "Example Value"
        }
      },
      "required": [
        "name",
        "type",
        "description",
        "required"
      ],
      "title": "PlanRequiredField",
      "type": "object"
    },
    "RequirementsVersion": {
      "description": "A version of user requirements with timestamp and source.",
      "properties": {
        "content": {
          "title": "Content",
          "type": "string"
        },
        "source": {
          "title": "Source",
          "type": "string"
        },
        "timestamp": {
          "title": "Timestamp",
          "type": "integer"
        }
      },
      "required": [
        "content",
        "source"
      ],
      "title": "RequirementsVersion",
      "type": "object"
    },
    "ResearchScope": {
      "description": "Research scope enum for workflow-driven research validation.\n\nDetermines the depth and requirements for research validation:\n- NONE: No research required for this task complexity\n- LIGHT: Light research required (1+ authoritative domain source)\n- DEEP: Deep research required (2+ authoritative domain sources)",
      "enum": [
        "none",
        "light",
        "deep"
      ],
      "title": "ResearchScope",
      "type": "string"
    },
    "ReuseComponent": {
      "properties": {
        "path": {
          "description": "Repository path to the reusable component",
          "title": "Path",
          "type": "string"
        },
        "purpose": {
          "default": "",
          "description": "What part of the task this component will support",
          "title": "Purpose",
          "type": "string"
        },
        "notes": {
          "default": "",
          "description": "Any integration notes or caveats",
          "title": "Notes",
          "type": "string"
        }
      },
      "required": [
        "path"
      ],
      "title": "ReuseComponent",
      "type": "object"
    },
    "TaskMetadata": {
      "description": "Lightweight metadata for coding tasks that flows with memory layer.\n\nThis model serves as the foundation for the enhanced workflow v3 system,\nreplacing session-based tracking with task-centric approach.",
      "properties": {
        "task_id": {
          "description": "IMMUTABLE: Auto-generated UUID, primary key for memory storage",
          "title": "Task Id",
          "type": "string"
        },
        "created_at": {
          "description": "IMMUTABLE: Task creation timestamp (epoch seconds)",
          "title": "Created At",
          "type": "integer"
        },
        "title": {
          "description": "Display title for coding task (updatable)",
          "title": "Title",
          "type": "string"
        },
        "description": {
          "description": "Detailed coding task description (updatable)",
          "title": "Description",
          "type": "string"
        },
        "user_requirements": {
          "default": "",
          "description": "Current coding requirements (updatable)",
          "title": "User Requirements",
          "type": "string"
        },
        "state": {
          "$ref": "#/$defs/TaskState",
          "default": "created",
          "description": "Current task state (updatable, follows TaskState transitions)"
        },
        "task_size": {
          "$ref": "#/$defs/TaskSize",
          "description": "Task size classification for workflow optimization (XS=simple fixes, S=minor features, M=standard, L=complex, XL=major changes)"
        },
        "user_requirements_history": {
          "description": "History of requirements changes",
          "items": {
            "$ref": "#/$defs/RequirementsVersion"
          },
          "title": "User Requirements History",
          "type": "array"
        },
        "accumulated_diff": {
          "additionalProperties": true,
          "description": "Code changes accumulated over time",
          "title": "Accumulated Diff",
          "type": "object"
        },
        "modified_files": {
          "description": "List of file paths that were created or modified during task implementation",
          "items": {
            "type": "string"
          },
          "title": "Modified Files",
          "type": "array"
        },
        "test_files": {
          "description": "List of test file paths that were created during testing phase",
          "items": {
            "type": "string"
          },
          "title": "Test Files",
          "type": "array"
        },
        "test_status": {
          "additionalProperties": {
            "type": "string"
          },
          "description": "Status of different test types (unit, integration, e2e, etc.)",
          "title": "Test Status",
          "type": "object"
        },
        "updated_at": {
          "description": "Last update timestamp (epoch seconds)",
          "title": "Updated At",
          "type": "integer"
        },
        "tags": {
          "description": "Coding-related tags",
          "items": {
            "type": "string"
          },
          "title": "Tags",
          "type": "array"
        },
        "problem_domain": {
          "default": "",
          "description": "Concise statement of the problem domain and scope for this task",
          "title": "Problem Domain",
          "type": "string"
        },
        "problem_non_goals": {
          "description": "Explicit non-goals/boundaries to prevent scope creep and re-solving commodity concerns",
          "items": {
            "type": "string"
          },
          "title": "Problem Non Goals",
          "type": "array"
        },
        "library_plan": {
          "description": "Planned libraries/utilities per purpose; prefer internal reuse and well-known libraries; custom code only with justification",
          "items": {
            "$ref": "#/$defs/LibraryPlanItem"
          },
          "title": "Library Plan",
          "type": "array"
        },
        "internal_reuse_components": {
          "description": "Existing repository components/utilities to reuse with paths and purposes",
          "items": {
            "$ref": "#/$defs/ReuseComponent"
          },
          "title": "Internal Reuse Components",
          "type": "array"
        },
        "research_required": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Whether research is required by workflow guidance (None=undetermined, True=required, False=optional)",
          "title": "Research Required"
        },
        "research_scope": {
          "$ref": "#/$defs/ResearchScope",
          "default": "none",
          "description": "Research scope determined by workflow: none|light|deep"
        },
        "research_completed": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Epoch seconds when research validation passed",
          "title": "Research Completed"
        },
        "research_rationale": {
          "default": "",
          "description": "Explanation of why research was required and how the scope was determined",
          "title": "Research Rationale",
          "type": "string"
        },
        "expected_url_count": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "LLM-determined expected number of research URLs based on task complexity",
          "title": "Expected Url Count"
        },
        "minimum_url_count": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "LLM-determined minimum acceptable URL count for adequate research",
          "title": "Minimum Url Count"
        },
        "url_requirement_reasoning": {
          "default": "",
          "description": "LLM-generated explanation of why specific URL count is needed for this task",
          "title": "Url Requirement Reasoning",
          "type": "string"
        },
        "research_complexity_analysis": {
          "anyOf": [
            {
              "additionalProperties": true,
              "type": "object"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Detailed complexity analysis factors from LLM (domain, tech maturity, integration scope, etc.)",
          "title": "Research Complexity Analysis"
        },
        "internal_research_required": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Whether internal codebase research is needed (None=undetermined, True=required, False=not needed)",
          "title": "Internal Research Required"
        },
        "related_code_snippets": {
          "description": "Related code snippets from the codebase that are relevant to this task",
          "items": {
            "type": "string"
          },
          "title": "Related Code Snippets",
          "type": "array"
        },
        "risk_assessment_required": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Whether risk assessment is needed (None=undetermined, True=required, False=not needed)",
          "title": "Risk Assessment Required"
        },
        "identified_risks": {
          "description": "Areas that could be harmed by the proposed changes",
          "items": {
            "type": "string"
          },
          "title": "Identified Risks",
          "type": "array"
        },
        "risk_mitigation_strategies": {
          "description": "Strategies to mitigate identified risks",
          "items": {
            "type": "string"
          },
          "title": "Risk Mitigation Strategies",
          "type": "array"
        },
        "design_patterns_enforcement": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Whether design patterns are required for this task (None=undetermined, True=required, False=not needed)",
          "title": "Design Patterns Enforcement"
        },
        "plan_approved_at": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Timestamp when plan was approved by judge_coding_plan (None=not approved)",
          "title": "Plan Approved At"
        },
        "plan_rejection_count": {
          "default": 0,
          "description": "Number of times the plan has been rejected (max 1 allowed)",
          "title": "Plan Rejection Count",
          "type": "integer"
        },
        "code_approved_files": {
          "additionalProperties": {
            "type": "integer"
          },
          "description": "Dictionary mapping file paths to approval timestamps from judge_code_change",
          "title": "Code Approved Files",
          "type": "object"
        },
        "testing_approved_at": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Timestamp when testing was approved by judge_testing_implementation (None=not approved)",
          "title": "Testing Approved At"
        },
        "all_approvals_validated": {
          "default": false,
          "description": "Whether all required approvals (plan, code, testing) have been validated",
          "title": "All Approvals Validated",
          "type": "boolean"
        }
      },
      "required": [
        "title",
        "description",
        "task_size"
      ],
      "title": "TaskMetadata",
      "type": "object"
    },
    "TaskSize": {
      "description": "Task size classification for workflow optimization.\n\nSizes are based on estimated complexity and time requirements:\n- XS: Extra Small - Simple fixes, typos, minor config changes (< 30 minutes)\n- S: Small - Minor features, simple refactoring (30 minutes - 2 hours)\n- M: Medium - Standard features, moderate complexity (2-8 hours) - DEFAULT\n- L: Large - Complex features, multiple components (1-3 days)\n- XL: Extra Large - Major system changes, architectural updates (3+ days)\n\nThis classification determines planning complexity and validation depth:\n- XS/S: Basic planning requirements, streamlined validation\n- M: Standard planning and validation\n- L/XL: Comprehensive planning with enhanced validation (library plans, risk assessment, design patterns)\n\nAll tasks follow the unified workflow: CREATED \u2192 PLANNING \u2192 PLAN_APPROVED \u2192 IMPLEMENTING \u2192 REVIEW_READY \u2192 TESTING \u2192 COMPLETED",
      "enum": [
        "xs",
        "s",
        "m",
        "l",
        "xl"
      ],
      "title": "TaskSize",
      "type": "string"
    },
    "TaskState": {
      "description": "Coding task state enum with well-documented transitions.\n\nState Transitions:\n- CREATED \u2192 PLANNING: Task created, ready for planning phase (XS/S may skip to IMPLEMENTING)\n- PLANNING \u2192 PLAN_PENDING_APPROVAL: Plan created, awaiting user approval\n- PLAN_PENDING_APPROVAL \u2192 PLANNING: User requests plan changes\n- PLAN_PENDING_APPROVAL \u2192 PLAN_APPROVED: User approves plan\n- PLAN_APPROVED \u2192 IMPLEMENTING: Implementation phase started\n- IMPLEMENTING \u2192 IMPLEMENTING: Multiple code changes during implementation\n- IMPLEMENTING \u2192 REVIEW_READY: Implementation complete, ready for code review\n- REVIEW_READY \u2192 TESTING: Code review approved, ready for testing validation\n- TESTING \u2192 TESTING: Multiple test iterations\n- TESTING \u2192 COMPLETED: All tests validated; task completed successfully\n- Any state \u2192 BLOCKED: Task blocked by external dependencies\n- Any state \u2192 CANCELLED: Task cancelled\n- BLOCKED \u2192 Previous state: Unblocked, return to previous state\n\nUsage:\n- CREATED: Default state for new tasks, all tasks proceed to planning (unified workflow)\n- PLANNING: Planning phase in progress (set when planning starts)\n- PLAN_PENDING_APPROVAL: Plan created, awaiting user approval and potential iteration\n- PLAN_APPROVED: Plan validated and approved (set by judge_coding_plan)\n- IMPLEMENTING: Implementation phase in progress (set when coding starts)\n- REVIEW_READY: Implementation complete and ready for code review\n- TESTING: Testing/validation phase after code review approval\n- COMPLETED: Task completed successfully (set by judge_coding_task_completion)\n- BLOCKED: Task blocked by external dependencies (manual override)\n- CANCELLED: Task cancelled (manual override)",
      "enum": [
        "created",
        "planning",
        "plan_pending_approval",
        "plan_approved",
        "implementing",
        "testing",
        "review_ready",
        "completed",
        "blocked",
        "cancelled"
      ],
      "title": "TaskState",
      "type": "string"
    },
    "WorkflowGuidance": {
      "description": "Canonical workflow guidance model used across the system.\n\nReturned by tools to provide consistent next steps and instructions for\nthe coding assistant. This is the single source of truth for the\nWorkflowGuidance schema.",
      "properties": {
        "next_tool": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Next tool to call, or None if workflow complete",
          "title": "Next Tool"
        },
        "reasoning": {
          "default": "",
          "description": "Clear explanation of why this tool should be used next",
          "title": "Reasoning",
          "type": "string"
        },
        "preparation_needed": {
          "description": "List of things that need to be prepared before calling the recommended tool",
          "items": {
            "type": "string"
          },
          "title": "Preparation Needed",
          "type": "array"
        },
        "guidance": {
          "default": "",
          "description": "Detailed step-by-step guidance for the AI assistant",
          "title": "Guidance",
          "type": "string"
        },
        "research_required": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Whether research is required for this task (only determined for new CREATED tasks)",
          "title": "Research Required"
        },
        "research_scope": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Research scope: 'none', 'light', or 'deep' (only determined for new CREATED tasks)",
          "title": "Research Scope"
        },
        "research_rationale": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Explanation of research requirements (only determined for new CREATED tasks)",
          "title": "Research Rationale"
        },
        "internal_research_required": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Whether internal codebase analysis is needed (only determined for new CREATED tasks)",
          "title": "Internal Research Required"
        },
        "risk_assessment_required": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Whether risk assessment is needed (only determined for new CREATED tasks)",
          "title": "Risk Assessment Required"
        },
        "design_patterns_enforcement": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Whether design patterns are required (only determined for new CREATED tasks)",
          "title": "Design Patterns Enforcement"
        },
        "plan_required_fields": {
          "description": "Structured specification of required fields for judge_coding_plan tool",
          "items": {
            "$ref": "#/$defs/PlanRequiredField"
          },
          "title": "Plan Required Fields",
          "type": "array"
        }
      },
      "title": "WorkflowGuidance",
      "type": "object"
    }
  },
  "properties": {
    "approved": {
      "description": "Whether the validation passed",
      "title": "Approved",
      "type": "boolean"
    },
    "required_improvements": {
      "description": "List of required improvements if not approved",
      "items": {
        "type": "string"
      },
      "title": "Required Improvements",
      "type": "array"
    },
    "feedback": {
      "description": "Detailed feedback about the validation",
      "title": "Feedback",
      "type": "string"
    },
    "suggested_diff": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Unified Git diff patch with suggested changes (optional). Provide when rejecting with concrete fixes or when proposing minor refinements.",
      "title": "Suggested Diff"
    },
    "reviewed_files": {
      "description": "Per-file reviews. Must include an entry for every file changed in the diff.",
      "items": {
        "$ref": "#/$defs/FileReview"
      },
      "title": "Reviewed Files",
      "type": "array"
    },
    "current_task_metadata": {
      "$ref": "#/$defs/TaskMetadata",
      "description": "ALWAYS current state of task metadata after operation"
    },
    "workflow_guidance": {
      "anyOf": [
        {
          "$ref": "#/$defs/WorkflowGuidance"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "LLM-generated next steps and instructions from shared method"
    }
  },
  "required": [
    "approved",
    "feedback"
  ],
  "title": "JudgeResponse",
  "type": "object"
}

Notes

  • Use after judge_code_change is approved. Follow workflow_guidance.next_tool for the next step.

  • Always use the exact task_id; recover it via get_current_coding_task if missing.

  • If test_files is empty or test_execution_results does not look like raw runner output, this tool will return approved: false and request real evidence (copy/paste the test run output and list the test files).

Inputs: task_id (required), test_files (required), test_summary (required), test_execution_results (required), +5 more. Returns: approved, feedback, reviewed_files, suggested_diff, +3 more

list_mcp_serversA

List all configured MCP server connections.

Inputs: no named parameters. Returns: result

list_mcp_toolsB

List available tools on a connected MCP server.

Inputs: server_name (required). Returns: result

log_eventC

Log an event to a session.

Inputs: kind (required), message (required), session_id (required), details. Returns: result

memory_deleteA

Delete a document or entire namespace from memory.

Inputs: namespace (required), doc_id. Returns: result

memory_indexC

Index texts into the local memory store using embeddings.

Inputs: texts (required), namespace (required), doc_ids, metadatas, +1 more. Returns: result

memory_list_namespacesD

Inputs: no named parameters. Returns: result

memory_statsD

Inputs: no named parameters. Returns: result

raise_missing_requirementsA

Raise Missing Requirements

Description

Elicit missing requirements and clarifications from the user when details are insufficient for implementation.

Args

  • current_request: string — Current understanding of the user’s request

  • identified_gaps: list[string] — Missing requirement gaps

  • specific_questions: list[string] — Targeted questions to clarify gaps

  • decision_areas (optional): list[string] — Fundamental decisions to confirm (e.g., database, framework, ui_type, app_type, api_style, auth, hosting)

  • options (optional): list[string] — Candidate options to present with pros/cons

  • constraints (optional): list[string] — Known constraints or non-negotiables

Returns

  • string: summary text of clarified requirements and context from the user

Inputs: task_id (required), current_request (required), identified_gaps (required), specific_questions (required), +3 more. Returns: result

raise_obstacleA

Raise Obstacle

Description

Involve the user to resolve blockers or conflicts by presenting options and context.

Args

  • problem: string — Clear description of the obstacle

  • research: string — What has been investigated (alternatives, prior art)

  • options: list[string] — Possible approaches or next steps

  • decision_area (optional): string — Name of the decision area involved (e.g., database, framework)

  • constraints (optional): list[string] — Known constraints or non-negotiables

Returns

  • string: user's decision and any additional context for proceeding

Inputs: options (required), problem (required), research (required), task_id, +2 more. Returns: result

refresh_codexC

Scan and index local codebase.

Inputs: path_pattern. Returns: result

request_plan_approvalA

Request Plan Approval

Description

Present a completed plan to the user for approval before proceeding to AI judge validation. This tool enables human-in-the-loop plan review and iterative refinement based on user feedback.

When to use

  • After creating a detailed implementation plan but before calling judge_coding_plan

  • When the task is in PLANNING state and a complete plan has been prepared

  • To enable user review and approval of plans before AI validation

Prerequisites

  • Task must be in PLANNING state

  • Complete plan, design, and research must be prepared

  • Task metadata must exist (call set_coding_task first if needed)

Args

  • plan: string — Detailed implementation plan with step-by-step approach (required)

  • design: string — Technical design and architecture decisions (required)

  • research: string — Research summary and findings (required)

  • task_id: string — Task UUID (required)

  • research_urls: list[string] — URLs from external research sources (optional)

  • problem_domain: string — Problem domain statement (optional)

  • problem_non_goals: list[string] — Non-goals and scope boundaries (optional)

  • library_plan: list[dict] — Library selection map with purpose, selection, source (optional)

  • internal_reuse_components: list[dict] — Internal components to reuse with paths (optional)

Returns

  • approved: boolean — Whether the user approved the plan

  • user_feedback: string — User's feedback or modification requests

  • next_action: string — Recommended next step based on user decision

User Options

The tool presents three options to the user:

  1. Approve — Proceed with the plan as-is (transitions to PLAN_APPROVED state)

  2. Modify — Request changes to the plan (returns to PLANNING state with feedback)

  3. Reject — Start over with a different approach (returns to PLANNING state)

Workflow Integration

  • On Approval: Task remains in PLAN_PENDING_APPROVAL state, ready for judge_coding_plan AI validation

  • On Modification: Task returns to PLANNING state with user feedback integrated

  • On Rejection: Task returns to PLANNING state for complete plan revision

Notes

  • This tool uses the MCP elicitation system to present plans in a user-friendly format

  • User feedback is automatically integrated into task requirements for plan iteration

  • The tool maintains full audit trails of user decisions and feedback

  • Always use the exact task_id; recover it via get_current_coding_task if missing

Inputs: plan (required), design (required), task_id (required), research (required), +5 more. Returns: Result model for plan approval tool.

router_chatB

Main brain chat tool with optional memory + workflow guidance.

Inputs: message (required), session_id (required), top_k, rerank, +5 more. Returns: result

set_coding_taskA

Set Coding Task

Description

Create or update coding task metadata and receive dynamic workflow guidance. This is the mandatory entry point for any coding work.

Critical Tool Warning

  • Skipping this tool causes severe token inefficiency and wasted iterations.

  • Always invoke this tool at the appropriate stage to avoid extreme token loss and redundant processing.

  • Do not rely on assistant memory for identifiers. Always pass the exact task_id and recover it via get_current_coding_task if missing.

When to use

  • Any user request requiring logical code changes or creation of new files (new apps, features, refactors, bug fixes)

Args

  • user_request: string — Original user request (required for new tasks)

  • task_title: string — Task title (required for new tasks)

  • task_description: string — Detailed description (required for new tasks)

  • task_size: enum — One of xs|s|m|l|xl (default m)

  • task_id: string — Task UUID when updating an existing task (optional)

  • user_requirements: string — Updated requirements (optional)

  • state: enum — Optional state transition when updating an existing task. Valid transitions are enforced (e.g., plan_approved → implementing).

  • tags: list[string] — Task tags (optional)

Returns

  • Response JSON schema (TaskAnalysisResult):

{
  "$defs": {
    "LibraryPlanItem": {
      "properties": {
        "purpose": {
          "description": "Non-domain concern or integration point this library addresses",
          "title": "Purpose",
          "type": "string"
        },
        "selection": {
          "description": "Chosen library or internal utility (name and optional version)",
          "title": "Selection",
          "type": "string"
        },
        "source": {
          "description": "Source of solution: 'internal' for repo utility, 'external' for well-known library, 'custom' for in-house code",
          "title": "Source",
          "type": "string"
        },
        "justification": {
          "default": "",
          "description": "One-line rationale for the selection and any trade-offs",
          "title": "Justification",
          "type": "string"
        }
      },
      "required": [
        "purpose",
        "selection",
        "source"
      ],
      "title": "LibraryPlanItem",
      "type": "object"
    },
    "PlanRequiredField": {
      "description": "Specification for a required field in judge_coding_plan.",
      "properties": {
        "name": {
          "description": "Field name in the judge_coding_plan tool",
          "title": "Name",
          "type": "string"
        },
        "type": {
          "description": "Expected data type (string, list[str], list[dict], etc.)",
          "title": "Type",
          "type": "string"
        },
        "description": {
          "description": "What this field should contain",
          "title": "Description",
          "type": "string"
        },
        "required": {
          "description": "Whether this field is required",
          "title": "Required",
          "type": "boolean"
        },
        "conditional_on": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Task metadata field this requirement depends on (e.g., 'design_patterns_enforcement')",
          "title": "Conditional On"
        },
        "example_value": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Example of what this field should contain",
          "title": "Example Value"
        }
      },
      "required": [
        "name",
        "type",
        "description",
        "required"
      ],
      "title": "PlanRequiredField",
      "type": "object"
    },
    "RequirementsVersion": {
      "description": "A version of user requirements with timestamp and source.",
      "properties": {
        "content": {
          "title": "Content",
          "type": "string"
        },
        "source": {
          "title": "Source",
          "type": "string"
        },
        "timestamp": {
          "title": "Timestamp",
          "type": "integer"
        }
      },
      "required": [
        "content",
        "source"
      ],
      "title": "RequirementsVersion",
      "type": "object"
    },
    "ResearchScope": {
      "description": "Research scope enum for workflow-driven research validation.\n\nDetermines the depth and requirements for research validation:\n- NONE: No research required for this task complexity\n- LIGHT: Light research required (1+ authoritative domain source)\n- DEEP: Deep research required (2+ authoritative domain sources)",
      "enum": [
        "none",
        "light",
        "deep"
      ],
      "title": "ResearchScope",
      "type": "string"
    },
    "ReuseComponent": {
      "properties": {
        "path": {
          "description": "Repository path to the reusable component",
          "title": "Path",
          "type": "string"
        },
        "purpose": {
          "default": "",
          "description": "What part of the task this component will support",
          "title": "Purpose",
          "type": "string"
        },
        "notes": {
          "default": "",
          "description": "Any integration notes or caveats",
          "title": "Notes",
          "type": "string"
        }
      },
      "required": [
        "path"
      ],
      "title": "ReuseComponent",
      "type": "object"
    },
    "TaskMetadata": {
      "description": "Lightweight metadata for coding tasks that flows with memory layer.\n\nThis model serves as the foundation for the enhanced workflow v3 system,\nreplacing session-based tracking with task-centric approach.",
      "properties": {
        "task_id": {
          "description": "IMMUTABLE: Auto-generated UUID, primary key for memory storage",
          "title": "Task Id",
          "type": "string"
        },
        "created_at": {
          "description": "IMMUTABLE: Task creation timestamp (epoch seconds)",
          "title": "Created At",
          "type": "integer"
        },
        "title": {
          "description": "Display title for coding task (updatable)",
          "title": "Title",
          "type": "string"
        },
        "description": {
          "description": "Detailed coding task description (updatable)",
          "title": "Description",
          "type": "string"
        },
        "user_requirements": {
          "default": "",
          "description": "Current coding requirements (updatable)",
          "title": "User Requirements",
          "type": "string"
        },
        "state": {
          "$ref": "#/$defs/TaskState",
          "default": "created",
          "description": "Current task state (updatable, follows TaskState transitions)"
        },
        "task_size": {
          "$ref": "#/$defs/TaskSize",
          "description": "Task size classification for workflow optimization (XS=simple fixes, S=minor features, M=standard, L=complex, XL=major changes)"
        },
        "user_requirements_history": {
          "description": "History of requirements changes",
          "items": {
            "$ref": "#/$defs/RequirementsVersion"
          },
          "title": "User Requirements History",
          "type": "array"
        },
        "accumulated_diff": {
          "additionalProperties": true,
          "description": "Code changes accumulated over time",
          "title": "Accumulated Diff",
          "type": "object"
        },
        "modified_files": {
          "description": "List of file paths that were created or modified during task implementation",
          "items": {
            "type": "string"
          },
          "title": "Modified Files",
          "type": "array"
        },
        "test_files": {
          "description": "List of test file paths that were created during testing phase",
          "items": {
            "type": "string"
          },
          "title": "Test Files",
          "type": "array"
        },
        "test_status": {
          "additionalProperties": {
            "type": "string"
          },
          "description": "Status of different test types (unit, integration, e2e, etc.)",
          "title": "Test Status",
          "type": "object"
        },
        "updated_at": {
          "description": "Last update timestamp (epoch seconds)",
          "title": "Updated At",
          "type": "integer"
        },
        "tags": {
          "description": "Coding-related tags",
          "items": {
            "type": "string"
          },
          "title": "Tags",
          "type": "array"
        },
        "problem_domain": {
          "default": "",
          "description": "Concise statement of the problem domain and scope for this task",
          "title": "Problem Domain",
          "type": "string"
        },
        "problem_non_goals": {
          "description": "Explicit non-goals/boundaries to prevent scope creep and re-solving commodity concerns",
          "items": {
            "type": "string"
          },
          "title": "Problem Non Goals",
          "type": "array"
        },
        "library_plan": {
          "description": "Planned libraries/utilities per purpose; prefer internal reuse and well-known libraries; custom code only with justification",
          "items": {
            "$ref": "#/$defs/LibraryPlanItem"
          },
          "title": "Library Plan",
          "type": "array"
        },
        "internal_reuse_components": {
          "description": "Existing repository components/utilities to reuse with paths and purposes",
          "items": {
            "$ref": "#/$defs/ReuseComponent"
          },
          "title": "Internal Reuse Components",
          "type": "array"
        },
        "research_required": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Whether research is required by workflow guidance (None=undetermined, True=required, False=optional)",
          "title": "Research Required"
        },
        "research_scope": {
          "$ref": "#/$defs/ResearchScope",
          "default": "none",
          "description": "Research scope determined by workflow: none|light|deep"
        },
        "research_completed": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Epoch seconds when research validation passed",
          "title": "Research Completed"
        },
        "research_rationale": {
          "default": "",
          "description": "Explanation of why research was required and how the scope was determined",
          "title": "Research Rationale",
          "type": "string"
        },
        "expected_url_count": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "LLM-determined expected number of research URLs based on task complexity",
          "title": "Expected Url Count"
        },
        "minimum_url_count": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "LLM-determined minimum acceptable URL count for adequate research",
          "title": "Minimum Url Count"
        },
        "url_requirement_reasoning": {
          "default": "",
          "description": "LLM-generated explanation of why specific URL count is needed for this task",
          "title": "Url Requirement Reasoning",
          "type": "string"
        },
        "research_complexity_analysis": {
          "anyOf": [
            {
              "additionalProperties": true,
              "type": "object"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Detailed complexity analysis factors from LLM (domain, tech maturity, integration scope, etc.)",
          "title": "Research Complexity Analysis"
        },
        "internal_research_required": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Whether internal codebase research is needed (None=undetermined, True=required, False=not needed)",
          "title": "Internal Research Required"
        },
        "related_code_snippets": {
          "description": "Related code snippets from the codebase that are relevant to this task",
          "items": {
            "type": "string"
          },
          "title": "Related Code Snippets",
          "type": "array"
        },
        "risk_assessment_required": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Whether risk assessment is needed (None=undetermined, True=required, False=not needed)",
          "title": "Risk Assessment Required"
        },
        "identified_risks": {
          "description": "Areas that could be harmed by the proposed changes",
          "items": {
            "type": "string"
          },
          "title": "Identified Risks",
          "type": "array"
        },
        "risk_mitigation_strategies": {
          "description": "Strategies to mitigate identified risks",
          "items": {
            "type": "string"
          },
          "title": "Risk Mitigation Strategies",
          "type": "array"
        },
        "design_patterns_enforcement": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Whether design patterns are required for this task (None=undetermined, True=required, False=not needed)",
          "title": "Design Patterns Enforcement"
        },
        "plan_approved_at": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Timestamp when plan was approved by judge_coding_plan (None=not approved)",
          "title": "Plan Approved At"
        },
        "plan_rejection_count": {
          "default": 0,
          "description": "Number of times the plan has been rejected (max 1 allowed)",
          "title": "Plan Rejection Count",
          "type": "integer"
        },
        "code_approved_files": {
          "additionalProperties": {
            "type": "integer"
          },
          "description": "Dictionary mapping file paths to approval timestamps from judge_code_change",
          "title": "Code Approved Files",
          "type": "object"
        },
        "testing_approved_at": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Timestamp when testing was approved by judge_testing_implementation (None=not approved)",
          "title": "Testing Approved At"
        },
        "all_approvals_validated": {
          "default": false,
          "description": "Whether all required approvals (plan, code, testing) have been validated",
          "title": "All Approvals Validated",
          "type": "boolean"
        }
      },
      "required": [
        "title",
        "description",
        "task_size"
      ],
      "title": "TaskMetadata",
      "type": "object"
    },
    "TaskSize": {
      "description": "Task size classification for workflow optimization.\n\nSizes are based on estimated complexity and time requirements:\n- XS: Extra Small - Simple fixes, typos, minor config changes (< 30 minutes)\n- S: Small - Minor features, simple refactoring (30 minutes - 2 hours)\n- M: Medium - Standard features, moderate complexity (2-8 hours) - DEFAULT\n- L: Large - Complex features, multiple components (1-3 days)\n- XL: Extra Large - Major system changes, architectural updates (3+ days)\n\nThis classification determines planning complexity and validation depth:\n- XS/S: Basic planning requirements, streamlined validation\n- M: Standard planning and validation\n- L/XL: Comprehensive planning with enhanced validation (library plans, risk assessment, design patterns)\n\nAll tasks follow the unified workflow: CREATED \u2192 PLANNING \u2192 PLAN_APPROVED \u2192 IMPLEMENTING \u2192 REVIEW_READY \u2192 TESTING \u2192 COMPLETED",
      "enum": [
        "xs",
        "s",
        "m",
        "l",
        "xl"
      ],
      "title": "TaskSize",
      "type": "string"
    },
    "TaskState": {
      "description": "Coding task state enum with well-documented transitions.\n\nState Transitions:\n- CREATED \u2192 PLANNING: Task created, ready for planning phase (XS/S may skip to IMPLEMENTING)\n- PLANNING \u2192 PLAN_PENDING_APPROVAL: Plan created, awaiting user approval\n- PLAN_PENDING_APPROVAL \u2192 PLANNING: User requests plan changes\n- PLAN_PENDING_APPROVAL \u2192 PLAN_APPROVED: User approves plan\n- PLAN_APPROVED \u2192 IMPLEMENTING: Implementation phase started\n- IMPLEMENTING \u2192 IMPLEMENTING: Multiple code changes during implementation\n- IMPLEMENTING \u2192 REVIEW_READY: Implementation complete, ready for code review\n- REVIEW_READY \u2192 TESTING: Code review approved, ready for testing validation\n- TESTING \u2192 TESTING: Multiple test iterations\n- TESTING \u2192 COMPLETED: All tests validated; task completed successfully\n- Any state \u2192 BLOCKED: Task blocked by external dependencies\n- Any state \u2192 CANCELLED: Task cancelled\n- BLOCKED \u2192 Previous state: Unblocked, return to previous state\n\nUsage:\n- CREATED: Default state for new tasks, all tasks proceed to planning (unified workflow)\n- PLANNING: Planning phase in progress (set when planning starts)\n- PLAN_PENDING_APPROVAL: Plan created, awaiting user approval and potential iteration\n- PLAN_APPROVED: Plan validated and approved (set by judge_coding_plan)\n- IMPLEMENTING: Implementation phase in progress (set when coding starts)\n- REVIEW_READY: Implementation complete and ready for code review\n- TESTING: Testing/validation phase after code review approval\n- COMPLETED: Task completed successfully (set by judge_coding_task_completion)\n- BLOCKED: Task blocked by external dependencies (manual override)\n- CANCELLED: Task cancelled (manual override)",
      "enum": [
        "created",
        "planning",
        "plan_pending_approval",
        "plan_approved",
        "implementing",
        "testing",
        "review_ready",
        "completed",
        "blocked",
        "cancelled"
      ],
      "title": "TaskState",
      "type": "string"
    },
    "WorkflowGuidance": {
      "description": "Canonical workflow guidance model used across the system.\n\nReturned by tools to provide consistent next steps and instructions for\nthe coding assistant. This is the single source of truth for the\nWorkflowGuidance schema.",
      "properties": {
        "next_tool": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Next tool to call, or None if workflow complete",
          "title": "Next Tool"
        },
        "reasoning": {
          "default": "",
          "description": "Clear explanation of why this tool should be used next",
          "title": "Reasoning",
          "type": "string"
        },
        "preparation_needed": {
          "description": "List of things that need to be prepared before calling the recommended tool",
          "items": {
            "type": "string"
          },
          "title": "Preparation Needed",
          "type": "array"
        },
        "guidance": {
          "default": "",
          "description": "Detailed step-by-step guidance for the AI assistant",
          "title": "Guidance",
          "type": "string"
        },
        "research_required": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Whether research is required for this task (only determined for new CREATED tasks)",
          "title": "Research Required"
        },
        "research_scope": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Research scope: 'none', 'light', or 'deep' (only determined for new CREATED tasks)",
          "title": "Research Scope"
        },
        "research_rationale": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Explanation of research requirements (only determined for new CREATED tasks)",
          "title": "Research Rationale"
        },
        "internal_research_required": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Whether internal codebase analysis is needed (only determined for new CREATED tasks)",
          "title": "Internal Research Required"
        },
        "risk_assessment_required": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Whether risk assessment is needed (only determined for new CREATED tasks)",
          "title": "Risk Assessment Required"
        },
        "design_patterns_enforcement": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Whether design patterns are required (only determined for new CREATED tasks)",
          "title": "Design Patterns Enforcement"
        },
        "plan_required_fields": {
          "description": "Structured specification of required fields for judge_coding_plan tool",
          "items": {
            "$ref": "#/$defs/PlanRequiredField"
          },
          "title": "Plan Required Fields",
          "type": "array"
        }
      },
      "title": "WorkflowGuidance",
      "type": "object"
    }
  },
  "properties": {
    "action": {
      "description": "Action taken: 'created' or 'updated'",
      "title": "Action",
      "type": "string"
    },
    "context_summary": {
      "description": "Summary of the task context and current state",
      "title": "Context Summary",
      "type": "string"
    },
    "current_task_metadata": {
      "$ref": "#/$defs/TaskMetadata",
      "description": "ALWAYS current state of task metadata after operation"
    },
    "workflow_guidance": {
      "$ref": "#/$defs/WorkflowGuidance",
      "description": "LLM-generated next steps and instructions from shared method"
    }
  },
  "required": [
    "action",
    "context_summary",
    "current_task_metadata",
    "workflow_guidance"
  ],
  "title": "TaskAnalysisResult",
  "type": "object"
}

Notes

  • Always call this first for coding work. Use the exact task_id returned for all later tools; recover with get_current_coding_task if missing.

Inputs: task_title (required), user_request (required), task_description (required), tags, +4 more. Returns: action, context_summary, workflow_guidance, current_task_metadata

start_sessionC

Start a new agent session with a goal and optional constraints.

Inputs: goal (required), context, task_id, metadata, +3 more. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.5/5.0

    Scored across 28 tools

    Disambiguation3/5

    Some tool clusters overlap in purpose: router_chat vs agent_llm_request both make LLM calls, list_mcp_servers vs list_mcp_tools are easy to confuse, and the judge_* family shares a similar naming pattern despite targeting different phases. Most tools are distinct, but the boundaries between some are unclear without reading the full descriptions.

    Naming Consistency4/5

    The vast majority of tools follow a verb_noun snake_case pattern (start_session, set_coding_task, judge_code_change). Exceptions like the memory_* noun-prefixed family, router_chat, and agent_llm_request deviate, but the overall convention is still fairly uniform.

    Tool Count2/5

    At 28 tools, this server exceeds the 25-tool threshold and spans many subdomains (memory, sessions, MCP, coding workflow). Each tool appears purposeful, but the large surface area creates context and selection overhead for an agent.

    Completeness4/5

    The server covers the full coding task lifecycle (plan, code review, testing, completion) and provides robust memory, session, and MCP management. Minor gaps like no session teardown or MCP disconnect exist, but agents can work around them.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      Not graded
      maintenance
      A local MCP server for RAG memory, semantic search, and context optimization using Ollama and SQLite. It serves as a central hub that manages document embeddings, text compression, and proxies calls to other sub-MCP servers.
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      A local-first LLM routing MCP server that keeps sensitive data on your own models, with fail-closed privacy and manager-worker delegation, exposing route and complete tools to any MCP client.
      72 PyPI
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      A self-hostable MCP server that routes prompts to multiple LLM providers using declarative policies, with multi-role orchestration for independence and verification.
      MIT