AgentPM

Cuando se llama a la herramienta apm_task:

1. Validación de parámetros:

   • Valida el parámetro action (obligatorio, debe ser una de las acciones válidas)
   • Valida el parámetro projectRoot (obligatorio, debe ser una ruta absoluta)
   • Valida los parámetros específicos de la acción:
     • Para get_single: Valida el parámetro id (obligatorio, cadena no vacía)
     • Para filter_by_status: Valida el parámetro status (obligatorio, debe ser un estado válido)
     • Para filter_by_priority: Valida el parámetro priority (obligatorio, debe ser una prioridad válida)
   • Valida los parámetros opcionales: file, withSubtasks y containsText

2. Recuperación de tareas:

   • Lee el archivo de tareas desde la ubicación especificada (por defecto apm-artifacts/artifacts.json si no se proporciona)
   • Extrae la lista de tareas del archivo

3. Ejecución de la acción:

   • Ejecuta la acción apropiada según el parámetro action:
     • get_all: Devuelve todas las tareas, opcionalmente filtradas por estado
     • get_single: Devuelve una tarea específica por ID
     • get_next: Devuelve la siguiente tarea en la que trabajar según dependencias y estado
     • filter_by_status: Devuelve tareas filtradas por estado
     • filter_by_priority: Devuelve tareas filtradas por prioridad

4. Procesamiento específico de la acción:

   • Para get_all y filter_by_status:
     • Filtra tareas por estado si se especifica
     • Maneja subtareas según el parámetro withSubtasks
     • Calcula métricas de resumen
   • Para get_single:
     • Analiza el ID de la tarea para determinar si es una subtarea
     • Encuentra la tarea o subtarea específica
   • Para get_next:
     • Filtra las tareas completadas
     • Aplica filtros de prioridad y texto si se especifican
     • Verifica la satisfacción de dependencias
     • Prioriza y selecciona la siguiente tarea
   • Para filter_by_priority:
     • Filtra tareas por prioridad
     • Maneja subtareas según el parámetro withSubtasks
     • Calcula métricas de resumen

5. Formato de respuesta:

   • Devuelve una respuesta JSON estructurada que contiene:
     • Los datos de la tarea solicitada
     • Estado de éxito y mensaje
     • Información contextual sobre la consulta
     • Marcas de tiempo e información de sesión

6. Manejo de errores:

   • Maneja errores de validación (campos obligatorios faltantes, valores no válidos)
   • Maneja errores de archivo no encontrado
   • Maneja errores de tarea no encontrada
   • Devuelve respuestas de error estandarizadas con información de contexto

Solicitud JSON-RPC

{
  "method": "apm_task",
  "params": {
    "action": "get_all|get_single|get_next|filter_by_status|filter_by_priority",
    "projectRoot": "/absolute/path/to/project",
    "file": "optional/path/to/artifacts.json",
    "id": "5",  // Required for get_single action
    "status": "pending|in-progress|done|deferred|cancelled",  // For get_all and filter_by_status actions
    "priority": "high|medium|low",  // For get_next and filter_by_priority actions
    "withSubtasks": true|false,
    "containsText": "optional search text"  // For get_next action
  }
}

Respuesta JSON-RPC

Para las acciones get_all y filter_by_status:

{
  "content": [
    {
      "type": "text",
      "text": {
        "success": true,
        "data": {
          "tasks": [
            {
              "id": "1",
              "title": "Task 1",
              "description": "Description",
              "status": "pending",
              "priority": "high",
              "dependencies": []
            }
          ],
          "stats": {
            "totalTasks": 10,
            "completedTasks": 3,
            "pendingTasks": 5,
            "inProgressTasks": 2,
            "taskCompletionPercentage": 30
          },
          "filter": "pending"
        },
        "message": "Found 5 tasks with status 'pending'",
        "memory": {
          "sessionId": "session-123456",
          "context": {
            "lastQuery": {
              "action": "get_all",
              "status": "pending",
              "withSubtasks": false
            },
            "projectRoot": "/path/to/project",
            "timestamp": "2023-06-15T10:30:00Z"
          }
        }
      }
    }
  ]
}

Para la acción get_single:

{
  "content": [
    {
      "type": "text",
      "text": {
        "success": true,
        "data": {
          "task": {
            "id": "5",
            "title": "Implement Feature",
            "description": "Create the feature",
            "status": "pending",
            "priority": "high",
            "dependencies": ["3", "4"],
            "details": "Implementation details..."
          }
        },
        "message": "Found task: Implement Feature",
        "memory": {
          "sessionId": "session-123456",
          "context": {
            "lastQuery": {
              "action": "get_single",
              "id": "5"
            },
            "projectRoot": "/path/to/project",
            "timestamp": "2023-06-15T10:30:00Z"
          }
        }
      }
    }
  ]
}

Para la acción get_next:

{
  "content": [
    {
      "type": "text",
      "text": {
        "success": true,
        "data": {
          "nextTask": {
            "id": "2",
            "title": "Next Task",
            "description": "Description",
            "status": "pending",
            "priority": "high",
            "dependencies": []
          },
          "allTasks": [
            /* Array of all tasks */
          ]
        },
        "message": "Found next task: Next Task",
        "memory": {
          "sessionId": "session-123456",
          "context": {
            "lastQuery": {
              "action": "get_next",
              "priority": "high",
              "containsText": null
            },
            "taskCount": 10,
            "readyTaskCount": 3,
            "timestamp": "2023-06-15T10:30:00Z"
          }
        }
      }
    }
  ]
}

Para la acción filter_by_priority:

{
  "content": [
    {
      "type": "text",
      "text": {
        "success": true,
        "data": {
          "tasks": [
            {
              "id": "1",
              "title": "Task 1",
              "description": "Description",
              "status": "pending",
              "priority": "high",
              "dependencies": []
            }
          ],
          "stats": {
            "totalTasks": 10,
            "completedTasks": 3,
            "pendingTasks": 5,
            "inProgressTasks": 2,
            "taskCompletionPercentage": 30
          },
          "filter": "high"
        },
        "message": "Found 5 tasks with priority 'high'",
        "memory": {
          "sessionId": "session-123456",
          "context": {
            "lastQuery": {
              "action": "filter_by_priority",
              "priority": "high",
              "withSubtasks": false
            },
            "projectRoot": "/path/to/project",
            "timestamp": "2023-06-15T10:30:00Z"
          }
        }
      }
    }
  ]
}

1. Validación de parámetros:

   • Valida el parámetro action (obligatorio, debe ser una de las acciones válidas)
   • Valida el parámetro projectRoot (obligatorio, debe ser una ruta absoluta)
   • Valida los parámetros específicos de la acción según la acción que se esté realizando
   • Valida los parámetros opcionales como file

2. Ejecución de la acción:

   • Ejecuta la acción apropiada según el parámetro action:
     • create: Crea una nueva tarea con las propiedades especificadas
     • update: Actualiza una tarea existente con nueva información
     • update_status: Cambia el estado de una o más tareas
     • delete: Elimina una tarea del proyecto
     • add_subtask: Añade una subtarea a una tarea existente
     • remove_subtask: Elimina una subtarea de una tarea
     • clear_subtasks: Elimina todas las subtareas de una o más tareas
     • expand: Descompone una tarea en subtareas usando IA
     • expand_all: Expande todas las tareas pendientes en subtareas usando IA

3. Operaciones con archivos:

   • Lee el archivo de tareas desde la ubicación especificada (por defecto apm-artifacts/artifacts.json si no se proporciona)
   • Actualiza los datos de las tareas según la acción realizada
   • Escribe los datos actualizados de las tareas de vuelta al archivo
   • Genera archivos de tarea individuales si es necesario (a menos que skipGenerate sea verdadero)

4. Integración con IA (para ciertas acciones):

   • Usa Claude AI para la expansión y actualización de tareas
   • Opcionalmente usa Perplexity AI para operaciones respaldadas por investigación
   • Genera subtareas inteligentes basadas en el contexto de la tarea

5. Formato de respuesta:

   • Devuelve una respuesta JSON estructurada que contiene:
     • Datos específicos de la acción (tarea, subtareas, etc.)
     • Mensaje de éxito
     • Guía de comunicación con el usuario
     • Instrucciones para el agente sobre los siguientes pasos

6. Manejo de errores:

   • Maneja errores de validación (campos obligatorios faltantes, valores no válidos)
   • Maneja errores de archivo no encontrado
   • Maneja errores de tarea no encontrada
   • Maneja errores del servicio de IA
   • Devuelve respuestas de error estandarizadas con información de contexto

Solicitud JSON-RPC

{
  "method": "apm_task_modify",
  "params": {
    "action": "create|update|update_status|delete|add_subtask|remove_subtask|clear_subtasks|expand|expand_all",
    "projectRoot": "/absolute/path/to/project",
    // Action-specific parameters
    // For create action
    "title": "Task Title",
    "description": "Task Description",
    "priority": "high|medium|low",
    "dependencies": "1,2,3",
    "details": "Implementation details",
    "testStrategy": "Test strategy",
    // For update action
    "id": "1",
    "prompt": "Update information",
    "research": true|false,
    "researchOnly": true|false,
    // For update_status action
    "id": "1",
    "status": "pending|in-progress|done|deferred|cancelled",
    // For delete action
    "id": "1",
    "confirm": true|false,
    // For add_subtask action
    "id": "1",
    "title": "Subtask Title",
    "description": "Subtask Description",
    "details": "Subtask details",
    "dependencies": "1.1,1.2",
    "status": "pending|in-progress|done|deferred|cancelled",
    "taskId": "2", // Existing task ID to convert to subtask
    "skipGenerate": true|false,
    // For remove_subtask action
    "id": "1.1",
    "convert": true|false,
    "skipGenerate": true|false,
    // For clear_subtasks action
    "id": "1", // Can be comma-separated for multiple tasks
    "all": true|false, // Clear subtasks from all tasks
    // For expand action
    "id": "1",
    "num": 3, // Number of subtasks to generate
    "prompt": "Additional context",
    "research": true|false,
    "force": true|false,
    // For expand_all action
    "num": 3,
    "prompt": "Additional context",
    "research": true|false,
    "force": true|false,
    // Common optional parameters
    "file": "optional/path/to/artifacts.json"
  }
}

Respuesta JSON-RPC

{
  "content": [
    {
      "type": "text",
      "text": {
        "success": true,
        "data": {
          // Action-specific response data
          // For create action
          "task": {
            "id": "1",
            "title": "Task Title",
            "description": "Task Description",
            "status": "pending",
            "priority": "high",
            "dependencies": ["1", "2", "3"],
            "details": "Implementation details",
            "testStrategy": "Test strategy"
          },
          // For update action
          "task": {
            "id": "1",
            "title": "Updated Task Title",
            "description": "Updated Task Description",
            "status": "pending",
            "priority": "high",
            "dependencies": ["1", "2", "3"],
            "details": "Updated implementation details",
            "testStrategy": "Updated test strategy"
          },
          // For update_status action
          "updatedTasks": [
            {
              "id": "1",
              "title": "Task Title",
              "status": "done"
            }
          ],
          // For delete action
          "removedTask": {
            "id": "1",
            "title": "Task Title",
            "description": "Task Description",
            "status": "pending",
            "priority": "high",
            "dependencies": [],
            "details": "Implementation details",
            "testStrategy": "Test strategy"
          },
          // For add_subtask action
          "task": {
            "id": "1",
            "title": "Task Title",
            "description": "Task Description",
            "status": "pending",
            "priority": "high",
            "dependencies": [],
            "details": "Implementation details",
            "testStrategy": "Test strategy",
            "subtasks": [
              {
                "id": "1.1",
                "title": "Subtask Title",
                "description": "Subtask Description",
                "status": "pending",
                "details": "Subtask details",
                "dependencies": []
              }
            ]
          },
          // For remove_subtask action
          "task": {
            "id": "1",
            "title": "Task Title",
            "description": "Task Description",
            "status": "pending",
            "priority": "high",
            "dependencies": [],
            "details": "Implementation details",
            "testStrategy": "Test strategy",
            "subtasks": []
          },
          // For clear_subtasks action
          "updatedTasks": [
            {
              "id": "1",
              "title": "Task Title",
              "description": "Task Description",
              "status": "pending",
              "priority": "high",
              "dependencies": [],
              "details": "Implementation details",
              "testStrategy": "Test strategy"
            }
          ],
          // For expand action
          "task": {
            "id": "1",
            "title": "Task Title",
            "description": "Task Description",
            "status": "pending",
            "priority": "high",
            "dependencies": [],
            "details": "Implementation details",
            "testStrategy": "Test strategy",
            "subtasks": [
              {
                "id": "1.1",
                "title": "Generated Subtask 1",
                "description": "Description for Generated Subtask 1",
                "status": "pending",
                "details": "Details for Generated Subtask 1",
                "dependencies": []
              },
              {
                "id": "1.2",
                "title": "Generated Subtask 2",
                "description": "Description for Generated Subtask 2",
                "status": "pending",
                "details": "Details for Generated Subtask 2",
                "dependencies": ["1.1"]
              },
              {
                "id": "1.3",
                "title": "Generated Subtask 3",
                "description": "Description for Generated Subtask 3",
                "status": "pending",
                "details": "Details for Generated Subtask 3",
                "dependencies": ["1.2"]
              }
            ]
          },
          // For expand_all action
          "expandedTasks": [
            {
              "id": "1",
              "title": "Task Title",
              "description": "Task Description",
              "status": "pending",
              "priority": "high",
              "dependencies": [],
              "details": "Implementation details",
              "testStrategy": "Test strategy",
              "subtasks": [
                {
                  "id": "1.1",
                  "title": "Generated Subtask 1",
                  "description": "Description for Generated Subtask 1",
                  "status": "pending",
                  "details": "Details for Generated Subtask 1",
                  "dependencies": []
                },
                {
                  "id": "1.2",
                  "title": "Generated Subtask 2",
                  "description": "Description for Generated Subtask 2",
                  "status": "pending",
                  "details": "Details for Generated Subtask 2",
                  "dependencies": ["1.1"]
                },
                {
                  "id": "1.3",
                  "title": "Generated Subtask 3",
                  "description": "Description for Generated Subtask 3",
                  "status": "pending",
                  "details": "Details for Generated Subtask 3",
                  "dependencies": ["1.2"]
                }
              ]
            }
          ]
        },
        "message": "Action-specific success message",
        "userCommunication": {
          "message": "User-friendly message about the action result"
        },
        "agentInstructions": "Instructions for the AI agent on how to proceed"
      }
    }
  ]
}

Cuando se llama a la herramienta apm_task_generate:

1. Validación de parámetros:

   • Valida el parámetro projectRoot (obligatorio, debe ser una ruta absoluta)
   • Valida los parámetros opcionales: file y output

2. Recuperación de tareas:

   • Lee el archivo de tareas desde la ubicación especificada (por defecto artifacts.json si no se proporciona)
   • Devuelve un error si el archivo de tareas no se encuentra o está vacío

3. Preparación del directorio:

   • Se asegura de que el directorio de salida exista (lo crea si es necesario)
   • Usa el directorio de artefactos predeterminado si no se especifica un directorio de salida

4. Proceso de generación de archivos:

   • Para cada tarea en los datos de tareas:
     • Genera un archivo markdown con los detalles de la tarea
     • Incluye todas las propiedades de la tarea (título, descripción, estado, dependencias, etc.)
     • Formatea las subtareas como secciones anidadas si están presentes
     • Usa una convención de nomenclatura coherente basada en los IDs de las tareas
   • Crea un formato bien estructurado y legible para cada archivo de tarea

5. Formato de respuesta:

   • Devuelve una respuesta JSON estructurada que contiene:
     • Estado de éxito
     • El número de archivos de tarea generados
     • La ruta al directorio de artefactos
     • La ruta al archivo de tareas
     • Un mensaje de éxito
     • Información de contexto (marca de tiempo, número de tareas)

6. Manejo de errores:

   • Maneja errores de archivo no encontrado
   • Maneja errores de creación de directorio
   • Maneja errores de escritura de archivos
   • Devuelve respuestas de error estandarizadas con información de contexto

Solicitud JSON-RPC

{
  "method": "apm_task_generate",
  "params": {
    "projectRoot": "/absolute/path/to/project",
    "file": "optional/path/to/artifacts.json",
    "output": "optional/path/to/output/directory"
  }
}

Respuesta JSON-RPC

{
  "content": [
    {
      "type": "text",
      "text": {
        "success": true,
        "data": {
          "success": true,
          "taskCount": 10,
          "artifactsDir": "/path/to/project/apm-artifacts",
          "tasksPath": "/path/to/project/apm-artifacts/artifacts.json"
        },
        "message": "Generated 10 task files in /path/to/project/apm-artifacts",
        "context": {
          "timestamp": "2023-06-15T10:30:00Z",
          "taskCount": 10
        }
      }
    }
  ]
}

Cuando se llama a la herramienta apm_project_brief_create:

1. Validación de parámetros:

   • Valida el parámetro projectRoot (obligatorio, debe ser una ruta absoluta)
   • Valida los parámetros opcionales: sessionId, input, stage, response, exportFormat y maxTasks

2. Manejo de sesión:

   • Si no se proporciona sessionId, inicia una nueva sesión de entrevista
   • Si se proporciona un sessionId, continúa una sesión de entrevista existente
   • Mantiene el estado a través de múltiples interacciones

3. Proceso de entrevista:

   • Guía al usuario a través de una entrevista estructurada con múltiples etapas:
     • Visión general del proyecto: Información básica sobre el propósito y el alcance del proyecto
     • Metas y partes interesadas: Objetivos del proyecto y partes involucradas
     • Restricciones: Limitaciones, requisitos y límites
     • Tecnologías: Stack técnico y herramientas
     • Cronograma y fases: Calendario del proyecto e hitos principales
     • Funcionalidades: Requisitos detallados de funcionalidad
     • Revisión: Confirmación final y ajustes
   • Hace preguntas contextualmente relevantes basadas en respuestas anteriores
   • Procesa las respuestas del usuario para construir un resumen completo del proyecto

4. Generación de tareas:

   • Después de completar la entrevista, genera tareas basadas en el resumen del proyecto
   • Crea una jerarquía de tareas estructurada con dependencias adecuadas
   • Organiza las tareas por fases y funcionalidades
   • Limita el número de tareas según el parámetro maxTasks
   • Guarda las tareas en el archivo artifacts.json

5. Formato de respuesta:

   • Para sesiones nuevas: Devuelve un ID de operación para el seguimiento del proceso de entrevista
   • Para sesiones en curso: Devuelve la siguiente pregunta o la confirmación de la generación de tareas
   • Incluye guía de comunicación con el usuario con respuestas sugeridas
   • Proporciona pasos siguientes y comandos claros

6. Manejo de errores:

   • Maneja errores de validación
   • Maneja errores de archivo no encontrado
   • Maneja errores de procesamiento de la entrevista
   • Devuelve respuestas de error estandarizadas con información de contexto

Solicitud JSON-RPC

{
  "method": "apm_project_brief_create",
  "params": {
    "projectRoot": "/absolute/path/to/project",
    "sessionId": "optional-session-id-for-continuing-interviews",
    "input": "optional/path/to/existing/brief.json",
    "stage": "project_overview|goals_and_stakeholders|constraints|technologies|timeline_and_phases|features|review",
    "response": "Your answer to the current interview question",
    "exportFormat": "json|markdown|text",
    "maxTasks": 10
  }
}

Respuesta JSON-RPC

{
  "content": [
    {
      "type": "text",
      "text": {
        "operationId": "project-brief-123456",
        "message": "Project brief interview started",
        "nextAction": "check_operation_status",
        "checkStatusCommand": "apm_project_brief_status --operationId=project-brief-123456",
        "metadata": {
          "userCommunication": {
            "message": "I'm starting the project brief interview process.",
            "expectationType": "immediate",
            "suggestedResponse": "I'll start the project brief interview process. I'll ask you a series of questions to gather information about your project. Let's begin with understanding your project overview."
          }
        }
      }
    }
  ]
}

Cuando se llama a la herramienta apm_project_brief_status:

1. Validación de parámetros:

   • Valida el parámetro projectRoot (obligatorio, debe ser una ruta absoluta)
   • Valida el parámetro operationId (obligatorio, cadena no vacía)

2. Recuperación de estado:

   • Obtiene el estado de la operación desde AsyncOperationManager
   • Devuelve un error si la operación no se encuentra
   • Proporciona información detallada sobre el estado actual de la operación

3. Informe de progreso:

   • Devuelve el porcentaje de progreso actual (0-100)
   • Proporciona un mensaje descriptivo sobre la etapa actual
   • Incluye marcas de tiempo para creación, actualizaciones y finalización (si corresponde)

4. Guía de comunicación con el usuario:

   • Para operaciones en ejecución, proporciona respuestas sugeridas para mantener informado al usuario
   • Para operaciones completadas, sugiere los siguientes pasos
   • Para operaciones fallidas, explica qué salió mal y cómo proceder

5. Formato de respuesta:

   • Devuelve una respuesta JSON estructurada que contiene:
     • ID de operación
     • Estado actual (pendiente, en ejecución, completada, fallida)
     • Porcentaje de progreso
     • Mensaje de estado
     • Marcas de tiempo (creada, actualizada, completada)
     • Guía de comunicación con el usuario

6. Manejo de errores:

   • Maneja casos en los que la operación no se encuentra
   • Maneja errores internos durante la recuperación de estado
   • Devuelve respuestas de error estandarizadas con información de contexto

Solicitud JSON-RPC

{
  "method": "apm_project_brief_status",
  "params": {
    "projectRoot": "/absolute/path/to/project",
    "operationId": "project-brief-123456"
  }
}

Respuesta JSON-RPC

{
  "content": [
    {
      "type": "text",
      "text": {
        "operationId": "project-brief-123456",
        "status": "running",
        "progress": 65,
        "message": "Generating tasks",
        "createdAt": "2023-06-15T10:30:00Z",
        "updatedAt": "2023-06-15T10:30:05Z",
        "completedAt": null,
        "metadata": {
          "operationType": "task-generation",
          "userCommunication": {
            "message": "Task generation is in progress.",
            "expectationType": "long_wait",
            "estimatedTimeSeconds": 180,
            "suggestedResponse": "The task generation is in progress (65% complete).\n\nWhile we wait, here's what's happening behind the scenes:\n- The AI is analyzing your project requirements\n- It's identifying key components, features, and dependencies\n- It will create a structured task breakdown with proper sequencing\n- Tasks will be saved to the apm-artifacts directory, along with an overall project brief.\n\nYou can ask me to \"check status\" anytime if you'd like an update, or we can discuss other aspects of your project while we wait."
          }
        }
      }
    }
  ]
}

Cuando se llama a la herramienta apm_project_brief_result:

1. Validación de parámetros:

   • Valida el parámetro projectRoot (obligatorio, debe ser una ruta absoluta)
   • Valida el parámetro operationId (obligatorio, cadena no vacía)

2. Recuperación de resultados:

   • Obtiene el resultado de la operación desde AsyncOperationManager
   • Devuelve un error si el resultado no está disponible (operación no completada o no encontrada)
   • Devuelve un error si la operación falló

3. Procesamiento de resultados:

   • Extrae las tareas generadas del resultado de la operación
   • Incluye rutas de archivo a los artefactos guardados
   • Proporciona información de sesión para posibles acciones de seguimiento
   • Sugiere los siguientes pasos para el usuario

4. Formato de respuesta:

   • Devuelve una respuesta JSON estructurada que contiene:
     • ID de operación y estado
     • Tareas generadas con títulos, descripciones, prioridades y detalles
     • Rutas de archivo a los artefactos guardados (artifacts.json, resumen del proyecto en markdown)
     • Información de sesión (sessionId, projectBriefUri, interviewStateUri)
     • Sugerencia de siguiente acción y comando
     • Guía de comunicación con el usuario

5. Manejo de errores:

   • Maneja casos en los que la operación no se encuentra
   • Maneja casos en los que la operación aún está en ejecución
   • Maneja casos en los que la operación falló
   • Devuelve respuestas de error estandarizadas con información de contexto

6. Guía para el usuario:

   • Proporciona pasos siguientes claros para el usuario
   • Sugiere comandos para ver y gestionar las tareas generadas
   • Incluye mensajes fáciles de usar que explican los resultados

Solicitud JSON-RPC

{
  "method": "apm_project_brief_result",
  "params": {
    "projectRoot": "/absolute/path/to/project",
    "operationId": "project-brief-123456"
  }
}

Respuesta JSON-RPC

{
  "content": [
    {
      "type": "text",
      "text": {
        "operationId": "project-brief-123456",
        "status": "completed",
        "message": "Task generation completed successfully",
        "tasks": [
          {
            "id": "1",
            "title": "Set up project infrastructure",
            "description": "Initialize the project repository and set up basic infrastructure",
            "status": "pending",
            "priority": "high",
            "dependencies": [],
            "details": "Create the repository, set up CI/CD, and configure development environment"
          }
        ],
        "tasksPath": "/path/to/project/apm-artifacts/artifacts.json",
        "markdownPath": "/path/to/project/apm-artifacts/project-brief.md",
        "sessionId": "session-123456",
        "projectBriefUri": "resource://project-brief-123456",
        "interviewStateUri": "resource://interview-state-123456",
        "nextAction": "view_tasks",
        "suggestedCommand": "apm_get_tasks",
        "userCommunication": {
          "message": "I've successfully generated tasks based on your project brief. You can now view and manage these tasks using the task management tools.",
          "expectationType": "immediate",
          "suggestedResponse": "Great! I've generated a set of tasks based on your project requirements. These tasks have been saved to your project directory and are ready for you to work on. You can view them using the 'apm_get_tasks' command. Would you like to see the tasks now?"
        }
      }
    }
  ]
}

Cuando se llama a la herramienta apm_dependencies:

1. Validación de parámetros:

   • Valida el parámetro action (obligatorio, debe ser una de las acciones válidas)
   • Valida el parámetro projectRoot (obligatorio, debe ser una ruta absoluta)
   • Valida los parámetros específicos de la acción:
     • Para add y remove: Valida los parámetros id y dependsOn (obligatorios, cadenas no vacías)
   • Valida los parámetros opcionales: file

2. Recuperación de tareas:

   • Lee el archivo de tareas desde la ubicación especificada (por defecto apm-artifacts/artifacts.json si no se proporciona)
   • Extrae la lista de tareas del archivo

3. Ejecución de la acción:

   • Ejecuta la acción apropiada según el parámetro action:
     • add: Añade una dependencia entre dos tareas
     • remove: Elimina una dependencia entre dos tareas
     • validate: Comprueba si hay problemas de dependencias (referencias circulares, dependencias faltantes)
     • fix: Corrige automáticamente los problemas de dependencias

4. Procesamiento Específico de Acción:

   • Para add:
     • Encuentra la tarea que dependerá de otra
     • Encuentra la tarea de la que se dependerá
     • Comprueba si la dependencia ya existe
     • Añade la dependencia si no existe
     • Valida las dependencias para asegurar que no haya referencias circulares
   • Para remove:
     • Encuentra la tarea que depende de otra
     • Comprueba si la dependencia existe
     • Elimina la dependencia si existe
   • Para validate:
     • Comprueba dependencias circulares
     • Comprueba dependencias faltantes
     • Devuelve los resultados de validación
   • Para fix:
     • Corrige dependencias faltantes eliminándolas
     • Corrige dependencias circulares rompiendo los ciclos
     • Devuelve los resultados de corrección

5. Operaciones de Archivo:

   • Actualiza los datos de las tareas en memoria
   • Escribe las tareas actualizadas de vuelta al archivo
   • Genera archivos de tarea individuales

6. Formato de Respuesta:

   • Devuelve una respuesta JSON estructurada que contiene:
     • Datos específicos de la acción (tarea, tarea de dependencia, resultados de validación, resultados de corrección)
     • Estado de éxito y mensaje
     • Información contextual sobre la operación
     • Marcas de tiempo e información de sesión

7. Manejo de Errores:

   • Maneja errores de validación (campos obligatorios faltantes, valores no válidos)
   • Maneja errores de archivo no encontrado
   • Maneja errores de tarea no encontrada
   • Maneja errores de dependencia circular
   • Devuelve respuestas de error estandarizadas con información de contexto

Solicitud JSON-RPC

{
  "method": "apm_dependencies",
  "params": {
    "action": "add|remove|validate|fix",
    "projectRoot": "/absolute/path/to/project",
    // Action-specific parameters
    // For add and remove actions
    "id": "1",
    "dependsOn": "2",
    // Common optional parameters
    "file": "optional/path/to/artifacts.json"
  }
}

Respuesta JSON-RPC

{
  "content": [
    {
      "type": "text",
      "text": {
        "success": true,
        "data": {
          // Action-specific response data
          // For add action
          "task": {
            "id": "1",
            "title": "Task 1",
            "description": "Description for Task 1",
            "status": "pending",
            "priority": "high",
            "dependencies": ["2"]
          },
          "dependencyTask": {
            "id": "2",
            "title": "Task 2",
            "description": "Description for Task 2",
            "status": "pending",
            "priority": "medium",
            "dependencies": []
          },
          "tasksPath": "/path/to/project/apm-artifacts/artifacts.json"
        },
        "message": "Added dependency: Task 1 now depends on task 2",
        "memory": {
          "sessionId": "session-123456",
          "context": {
            "taskId": "1",
            "dependsOn": "2",
            "timestamp": "2023-06-15T10:30:00Z"
          }
        }
      }
    }
  ]
}

Para la acción validate:

{
  "content": [
    {
      "type": "text",
      "text": {
        "success": true,
        "data": {
          "validationResults": {
            "circularDependencies": [
              {
                "taskId": "1",
                "path": ["1", "3", "2", "1"]
              }
            ],
            "missingDependencies": [
              {
                "taskId": "4",
                "missingDependencies": ["999"]
              }
            ],
            "valid": false
          },
          "tasksPath": "/path/to/project/apm-artifacts/artifacts.json"
        },
        "message": "Dependency issues detected",
        "memory": {
          "sessionId": "session-123456",
          "context": {
            "timestamp": "2023-06-15T10:30:00Z",
            "validationResults": {
              "circularDependencies": [
                {
                  "taskId": "1",
                  "path": ["1", "3", "2", "1"]
                }
              ],
              "missingDependencies": [
                {
                  "taskId": "4",
                  "missingDependencies": ["999"]
                }
              ],
              "valid": false
            }
          }
        }
      }
    }
  ]
}

Para la acción fix:

{
  "content": [
    {
      "type": "text",
      "text": {
        "success": true,
        "data": {
          "fixResults": {
            "circularDependenciesFixed": [
              {
                "taskId": "2",
                "removedDependencies": ["1"]
              }
            ],
            "missingDependenciesFixed": [
              {
                "taskId": "4",
                "removedDependencies": ["999"]
              }
            ],
            "fixesApplied": true
          },
          "tasksPath": "/path/to/project/apm-artifacts/artifacts.json"
        },
        "message": "Dependency issues fixed",
        "memory": {
          "sessionId": "session-123456",
          "context": {
            "timestamp": "2023-06-15T10:30:00Z",
            "fixResults": {
              "circularDependenciesFixed": [
                {
                  "taskId": "2",
                  "removedDependencies": ["1"]
                }
              ],
              "missingDependenciesFixed": [
                {
                  "taskId": "4",
                  "removedDependencies": ["999"]
                }
              ],
              "fixesApplied": true
            }
          }
        }
      }
    }
  ]
}

Cuando se llama a la herramienta apm_complexity_node:

1. Validación de Parámetros:

   • Valida el parámetro projectRoot (obligatorio, debe ser una ruta absoluta)
   • Valida los parámetros opcionales: file, output, markdownOutput, threshold, model y research
   • Aplica valores predeterminados para los parámetros opcionales:
     • output: "apm-artifacts/resources/reports/task-complexity-report.json"
     • markdownOutput: "apm-artifacts/resources/reports/task-complexity-report.md"
     • threshold: 5 (las tareas con complejidad ≥ 5 se recomendarán para expansión)
     • research: false (si se debe usar Perplexity AI para análisis respaldado por investigación)

2. Recuperación de Tareas:

   • Lee el archivo de tareas desde la ubicación especificada (por defecto artifacts.json si no se proporciona)
   • Extrae la lista de tareas del archivo
   • Filtra las tareas para incluir solo aquellas que no estén 'done' ni 'cancelled'
   • Omite las tareas que ya tienen subtareas (ya que ya han sido desglosadas)

3. Proceso de Análisis de Tareas:

   • Para cada tarea:
     • Calcula factores básicos de complejidad:
       • Longitud de la descripción (0-0.2 puntos)
       • Longitud de los detalles (0-0.2 puntos)
       • Número de dependencias (0-0.2 puntos)
       • Factor de prioridad (alta: 0.2, media: 0.1, baja: 0 puntos)
       • Número de términos técnicos (0-0.2 puntos)
     • Si la investigación está habilitada, mejora el análisis con Perplexity AI
     • Utiliza Claude AI para analizar la complejidad en una escala del 1 al 10
     • Recomienda un número de subtareas según la complejidad
     • Genera indicaciones y comandos de expansión

4. Generación de Informes:

   • Crea un informe de complejidad con:
     • Análisis específico de la tarea (ID, título, puntuación de complejidad, subtareas recomendadas)
     • Indicaciones de expansión para desglosar tareas complejas
     • Comandos a ejecutar para la expansión de tareas
     • Metadatos (marca de tiempo de generación, umbral, recuentos de tareas, complejidad promedio)
   • Se asegura de que los directorios de salida existan
   • Escribe el informe JSON en la ruta de salida especificada
   • Formatea el informe en un documento markdown legible
   • Escribe el informe markdown en la ruta de salida markdown especificada

5. Formato de Respuesta:

   • Devuelve una respuesta JSON estructurada que contiene:
     • Los datos completos del informe de complejidad
     • El informe formateado como cadena markdown
     • Rutas de archivo de salida para los informes JSON y markdown
     • Estadísticas de análisis de tareas (tareas analizadas, tareas complejas encontradas)
     • Guía de comunicación con el usuario
     • Instrucciones del agente para los siguientes pasos

6. Manejo de Errores:

   • Maneja errores de archivo no encontrado
   • Maneja errores de creación de directorios
   • Maneja errores de escritura de archivos
   • Devuelve respuestas de error estandarizadas con información de contexto

Solicitud JSON-RPC

{
  "method": "apm_complexity_node",
  "params": {
    "projectRoot": "/absolute/path/to/project",
    "file": "optional/path/to/artifacts.json",
    "output": "apm-artifacts/resources/reports/task-complexity-report.json",
    "markdownOutput": "apm-artifacts/resources/reports/task-complexity-report.md",
    "threshold": 5,
    "model": "optional-model-name",
    "research": false
  }
}

Respuesta JSON-RPC

{
  "content": [
    {
      "type": "text",
      "text": {
        "success": true,
        "data": {
          "report": {
            "tasks": [
              {
                "taskId": "15",
                "title": "Implement GraphQL API Integration",
                "complexity": 8,
                "recommendedSubtasks": 6,
                "expansionPrompt": "Break down the implementation...",
                "expansionCommand": "apm_task_modify_node --action=expand --id=15 --num=6"
              }
            ],
            "metadata": {
              "generated": "2025-04-24T14:40:04.508Z",
              "threshold": 5,
              "totalTasks": 4,
              "averageComplexity": 7
            }
          },
          "formattedReport": "# Task Complexity Analysis Report\n\n## Report Summary\n\n- **Generated:** 4/24/2025, 7:40:04 AM\n- **Complexity Threshold:** 5\n- **Total Tasks Analyzed:** 4\n- **Average Complexity:** 7.0\n\n## Task Analysis\n\n### 🔴 Task 15: Implement GraphQL API Integration\n\n- **Complexity Score:** **8/10 ⚠️\n- **Recommended Subtasks:** 6\n- **Action Required:** This task should be broken down into subtasks\n- **Expansion Command:** `apm_task_modify_node --action=expand --id=15 --num=6`\n\n**Expansion Guidance:**\nBreak down the implementation of the GraphQL API integration...\n\n---\n\n## Recommendations\n\nThe following tasks should be prioritized for breakdown:\n\n- Task 15: Implement GraphQL API Integration (Complexity: 8/10)\n",
          "jsonOutputPath": "/path/to/project/apm-artifacts/resources/reports/task-complexity-report.json",
          "markdownOutputPath": "/path/to/project/apm-artifacts/resources/reports/task-complexity-report.md",
          "tasksAnalyzed": 4,
          "complexTasks": 1
        },
        "message": "Analyzed 4 tasks and identified 1 complex task that should be broken down.",
        "userCommunication": {
          "message": "I've analyzed your project tasks and identified which ones might benefit from being broken down into subtasks. Here's the complexity report:\n\n# Task Complexity Analysis Report\n\n...",
          "expectationType": "immediate"
        },
        "agentInstructions": "The complexity analysis is complete. The report has been formatted for display and saved as both JSON and Markdown. You can suggest using 'apm_task_modify_node' with the 'expand' action for tasks with high complexity scores."
      }
    }
  ]
}