| start_sessionC | Start a new agent session with a goal and optional constraints. |
| configure_brainC | Configure the default or session-specific brain model. |
| get_brain_configD | – |
| configure_memoryB | Configure memory embedding/rerank settings (global or per-session). |
| link_taskD | – |
| log_eventC | Log an event to a session. |
| get_session_contextC | Retrieve the full context of a session. |
| agent_llm_requestC | Make a request to an OpenAI-compatible LLM provider. |
| memory_indexC | Index texts into the local memory store using embeddings. |
| memory_searchC | Search memory with embeddings and optional reranking. |
| memory_deleteA | Delete a document or entire namespace from memory. |
| memory_list_namespacesD | – |
| memory_statsD | – |
| refresh_codexC | Scan and index local codebase. |
| router_chatB | Main brain chat tool with optional memory + workflow guidance. |
| connect_mcp_serverC | Connect to another MCP server. |
| list_mcp_serversA | List all configured MCP server connections. |
| call_mcp_toolC | Call a tool on a connected MCP server. |
| list_mcp_toolsB | List available tools on a connected MCP server. |
| set_coding_taskA | Set Coding TaskDescriptionCreate or update coding task metadata and receive dynamic workflow guidance. This is the mandatory entry point for any coding work. Critical Tool WarningSkipping 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 useAny user request requiring logical code changes or creation of new files (new apps, features, refactors, bug fixes)
Argsuser_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{
"$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 |
| get_current_coding_taskA | Get Current Coding TaskDescriptionRetrieve 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 WarningSkipping 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 useArgsReturnsfound: 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 |
| request_plan_approvalA | Request Plan ApprovalDescriptionPresent 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 useAfter 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
PrerequisitesTask must be in PLANNING state Complete plan, design, and research must be prepared Task metadata must exist (call set_coding_task first if needed)
Argsplan: 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)
Returnsapproved: 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 OptionsThe tool presents three options to the user: Approve — Proceed with the plan as-is (transitions to PLAN_APPROVED state) Modify — Request changes to the plan (returns to PLANNING state with feedback) Reject — Start over with a different approach (returns to PLANNING state)
Workflow IntegrationOn 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
NotesThis 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
|
| raise_obstacleA | Raise ObstacleDescriptionInvolve the user to resolve blockers or conflicts by presenting options and context. Argsproblem: 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 |
| raise_missing_requirementsA | Raise Missing RequirementsDescriptionElicit missing requirements and clarifications from the user when details are insufficient for implementation. Argscurrent_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 |
| judge_coding_task_completionA | Judge Coding Task CompletionDescriptionFinal validation gate before declaring a task complete. Called when workflow_guidance.next_tool == "judge_coding_task_completion". Critical Tool WarningSkipping 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.
PrerequisitesArgstask_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{
"$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"
}
NotesThe 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.
|
| judge_coding_planA | Judge Coding PlanDescriptionValidate a proposed plan and design against requirements, research needs, and risks. Called when workflow_guidance.next_tool == "judge_coding_plan". Critical Tool WarningSkipping 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.
PrerequisitesThoroughly 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) checksIf 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
Argstask_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{
"$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"
}
NotesFollow 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.
|
| judge_code_changeA | Judge Code ChangeDescriptionReview 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 WarningSkipping 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 useHuman-in-the-Loop (HITL) checksIf 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
Argstask_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{
"$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.
|
| judge_testing_implementationA | Judge Testing ImplementationDescriptionValidate 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 WarningSkipping 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.
Argstask_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{
"$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"
}
NotesUse 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).
|
