AgentPM

Quando a ferramenta apm_task é chamada:

1. Validação de Parâmetros:

   • Valida o parâmetro action (obrigatório, deve ser uma das ações válidas)
   • Valida o parâmetro projectRoot (obrigatório, deve ser um caminho absoluto)
   • Valida parâmetros específicos da ação:
     • Para get_single: Valida o parâmetro id (obrigatório, string não vazia)
     • Para filter_by_status: Valida o parâmetro status (obrigatório, deve ser um status válido)
     • Para filter_by_priority: Valida o parâmetro priority (obrigatório, deve ser uma prioridade válida)
   • Valida parâmetros opcionais: file, withSubtasks e containsText

2. Recuperação de Tarefas:

   • Lê o arquivo de tarefas do local especificado (padrão para apm-artifacts/artifacts.json se não fornecido)
   • Extrai a lista de tarefas do arquivo

3. Execução da Ação:

   • Executa a ação apropriada com base no parâmetro action:
     • get_all: Retorna todas as tarefas, opcionalmente filtradas por status
     • get_single: Retorna uma tarefa específica por ID
     • get_next: Retorna a próxima tarefa para trabalhar com base em dependências e status
     • filter_by_status: Retorna tarefas filtradas por status
     • filter_by_priority: Retorna tarefas filtradas por prioridade

4. Processamento Específico da Ação:

   • Para get_all e filter_by_status:
     • Filtra tarefas por status se especificado
     • Lida com subtarefas com base no parâmetro withSubtasks
     • Calcula métricas de resumo
   • Para get_single:
     • Analisa o ID da tarefa para determinar se é uma subtarefa
     • Encontra a tarefa ou subtarefa específica
   • Para get_next:
     • Filtra tarefas concluídas
     • Aplica filtros de prioridade e texto se especificados
     • Verifica a satisfação de dependências
     • Prioriza e seleciona a próxima tarefa
   • Para filter_by_priority:
     • Filtra tarefas por prioridade
     • Lida com subtarefas com base no parâmetro withSubtasks
     • Calcula métricas de resumo

5. Formatação da Resposta:

   • Retorna uma resposta JSON estruturada contendo:
     • Os dados da tarefa solicitada
     • Status e mensagem de sucesso
     • Informações contextuais sobre a consulta
     • Carimbos de data/hora e informações de sessão

6. Tratamento de Erros:

   • Trata erros de validação (campos obrigatórios ausentes, valores inválidos)
   • Trata erros de arquivo não encontrado
   • Trata erros de tarefa não encontrada
   • Retorna respostas de erro padronizadas com informações de contexto

Solicitação 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
  }
}

Resposta JSON-RPC

Para as ações get_all e 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 a ação 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 a ação 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 a ação 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. Validação de Parâmetros:

   • Valida o parâmetro action (obrigatório, deve ser uma das ações válidas)
   • Valida o parâmetro projectRoot (obrigatório, deve ser um caminho absoluto)
   • Valida parâmetros específicos da ação com base na ação que está sendo executada
   • Valida parâmetros opcionais como file

2. Execução da Ação:

   • Executa a ação apropriada com base no parâmetro action:
     • create: Cria uma nova tarefa com as propriedades especificadas
     • update: Atualiza uma tarefa existente com novas informações
     • update_status: Altera o status de uma ou mais tarefas
     • delete: Remove uma tarefa do projeto
     • add_subtask: Adiciona uma subtarefa a uma tarefa existente
     • remove_subtask: Remove uma subtarefa de uma tarefa
     • clear_subtasks: Remove todas as subtarefas de uma ou mais tarefas
     • expand: Divide uma tarefa em subtarefas usando IA
     • expand_all: Expande todas as tarefas pendentes em subtarefas usando IA

3. Operações de Arquivo:

   • Lê o arquivo de tarefas do local especificado (padrão para apm-artifacts/artifacts.json se não for fornecido)
   • Atualiza os dados das tarefas com base na ação executada
   • Grava os dados atualizados das tarefas de volta no arquivo
   • Gera arquivos de tarefa individuais se necessário (a menos que skipGenerate seja verdadeiro)

4. Integração com IA (para certas ações):

   • Usa Claude AI para expansão e atualização de tarefas
   • Opcionalmente usa Perplexity AI para operações com base em pesquisa
   • Gera subtarefas inteligentes com base no contexto da tarefa

5. Formatação da Resposta:

   • Retorna uma resposta JSON estruturada contendo:
     • Dados específicos da ação (tarefa, subtarefas, etc.)
     • Mensagem de sucesso
     • Orientação de comunicação com o usuário
     • Instruções do agente para os próximos passos

6. Tratamento de Erros:

   • Trata erros de validação (campos obrigatórios ausentes, valores inválidos)
   • Trata erros de arquivo não encontrado
   • Trata erros de tarefa não encontrada
   • Trata erros de serviço de IA
   • Retorna respostas de erro padronizadas com informações de contexto

Solicitação 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"
  }
}

Resposta 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"
      }
    }
  ]
}

Quando a ferramenta apm_task_generate é chamada:

1. Validação de Parâmetros:

   • Valida o parâmetro projectRoot (obrigatório, deve ser um caminho absoluto)
   • Valida parâmetros opcionais: file e output

2. Recuperação de Tarefas:

   • Lê o arquivo de tarefas do local especificado (padrão para artifacts.json se não for fornecido)
   • Retorna um erro se o arquivo de tarefas não for encontrado ou estiver vazio

3. Preparação do Diretório:

   • Garante que o diretório de saída exista (cria-o se necessário)
   • Usa o diretório de artefatos padrão se nenhum diretório de saída for especificado

4. Processo de Geração de Arquivos:

   • Para cada tarefa nos dados de tarefas:
     • Gera um arquivo markdown com os detalhes da tarefa
     • Inclui todas as propriedades da tarefa (título, descrição, status, dependências, etc.)
     • Formata subtarefas como seções aninhadas, se presentes
     • Usa uma convenção de nomenclatura consistente com base nos IDs das tarefas
   • Cria um formato bem estruturado e legível para cada arquivo de tarefa

5. Formatação da Resposta:

   • Retorna uma resposta JSON estruturada contendo:
     • Status de sucesso
     • O número de arquivos de tarefa gerados
     • O caminho para o diretório de artefatos
     • O caminho para o arquivo de tarefas
     • Uma mensagem de sucesso
     • Informações de contexto (timestamp, contagem de tarefas)

6. Tratamento de Erros:

   • Trata erros de arquivo não encontrado
   • Trata erros de criação de diretório
   • Trata erros de gravação de arquivo
   • Retorna respostas de erro padronizadas com informações de contexto

Solicitação JSON-RPC

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

Resposta 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
        }
      }
    }
  ]
}

Quando a ferramenta apm_project_brief_create é chamada:

1. Validação de Parâmetros:

   • Valida o parâmetro projectRoot (obrigatório, deve ser um caminho absoluto)
   • Valida parâmetros opcionais: sessionId, input, stage, response, exportFormat e maxTasks

2. Tratamento de Sessão:

   • Se nenhum sessionId for fornecido, inicia uma nova sessão de entrevista
   • Se um sessionId for fornecido, continua uma sessão de entrevista existente
   • Mantém o estado entre múltiplas interações

3. Processo de Entrevista:

   • Guia o usuário por uma entrevista estruturada com múltiplos estágios:
     • Visão Geral do Projeto: Informações básicas sobre o propósito e o escopo do projeto
     • Metas e Partes Interessadas: Objetivos do projeto e partes envolvidas
     • Restrições: Limitações, requisitos e limites
     • Tecnologias: Stack técnico e ferramentas
     • Cronograma e Fases: Cronograma do projeto e marcos principais
     • Recursos: Requisitos detalhados de funcionalidade
     • Revisão: Confirmação final e ajustes
   • Faz perguntas contextualmente relevantes com base nas respostas anteriores
   • Processa as respostas do usuário para construir um briefing abrangente do projeto

4. Geração de Tarefas:

   • Após concluir a entrevista, gera tarefas com base no briefing do projeto
   • Cria uma hierarquia de tarefas estruturada com dependências adequadas
   • Organiza tarefas por fases e recursos
   • Limita o número de tarefas com base no parâmetro maxTasks
   • Salva tarefas no arquivo artifacts.json

5. Formatação da Resposta:

   • Para novas sessões: Retorna um ID de operação para rastrear o processo de entrevista
   • Para sessões contínuas: Retorna a próxima pergunta ou confirmação da geração de tarefas
   • Inclui orientação de comunicação com o usuário com respostas sugeridas
   • Fornece próximos passos e comandos claros

6. Tratamento de Erros:

   • Trata erros de validação
   • Trata erros de arquivo não encontrado
   • Trata erros de processamento de entrevista
   • Retorna respostas de erro padronizadas com informações de contexto

Solicitação 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
  }
}

Resposta 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."
          }
        }
      }
    }
  ]
}

Quando a ferramenta apm_project_brief_status é chamada:

1. Validação de Parâmetros:

   • Valida o parâmetro projectRoot (obrigatório, deve ser um caminho absoluto)
   • Valida o parâmetro operationId (obrigatório, string não vazia)

2. Recuperação de Status:

   • Obtém o status da operação do AsyncOperationManager
   • Retorna um erro se a operação não for encontrada
   • Fornece informações detalhadas sobre o estado atual da operação

3. Relatório de Progresso:

   • Retorna a porcentagem de progresso atual (0-100)
   • Fornece uma mensagem descritiva sobre o estágio atual
   • Inclui timestamps para criação, atualizações e conclusão (se aplicável)

4. Orientação de Comunicação com o Usuário:

   • Para operações em execução, fornece respostas sugeridas para manter os usuários informados
   • Para operações concluídas, sugere próximos passos
   • Para operações com falha, explica o que deu errado e como proceder

5. Formatação da Resposta:

   • Retorna uma resposta JSON estruturada contendo:
     • ID da operação
     • Status atual (pendente, em execução, concluída, com falha)
     • Porcentagem de progresso
     • Mensagem de status
     • Timestamps (criado, atualizado, concluído)
     • Orientação de comunicação com o usuário

6. Tratamento de Erros:

   • Trata casos em que a operação não é encontrada
   • Trata erros internos durante a recuperação de status
   • Retorna respostas de erro padronizadas com informações de contexto

Solicitação JSON-RPC

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

Resposta 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."
          }
        }
      }
    }
  ]
}

Quando a ferramenta apm_project_brief_result é chamada:

1. Validação de Parâmetros:

   • Valida o parâmetro projectRoot (obrigatório, deve ser um caminho absoluto)
   • Valida o parâmetro operationId (obrigatório, string não vazia)

2. Recuperação de Resultado:

   • Obtém o resultado da operação do AsyncOperationManager
   • Retorna um erro se o resultado não estiver disponível (operação não concluída ou não encontrada)
   • Retorna um erro se a operação falhou

3. Processamento de Resultado:

   • Extrai as tarefas geradas do resultado da operação
   • Inclui caminhos de arquivo para os artefatos salvos
   • Fornece informações de sessão para possíveis ações de acompanhamento
   • Sugere próximos passos para o usuário

4. Formatação da Resposta:

   • Retorna uma resposta JSON estruturada contendo:
     • ID da operação e status
     • Tarefas geradas com títulos, descrições, prioridades e detalhes
     • Caminhos de arquivo para os artefatos salvos (artifacts.json, markdown do briefing do projeto)
     • Informações de sessão (sessionId, projectBriefUri, interviewStateUri)
     • Sugestão de próxima ação e comando
     • Orientação de comunicação com o usuário

5. Tratamento de Erros:

   • Trata casos em que a operação não é encontrada
   • Trata casos em que a operação ainda está em execução
   • Trata casos em que a operação falhou
   • Retorna respostas de erro padronizadas com informações de contexto

6. Orientação ao Usuário:

   • Fornece próximos passos claros para o usuário
   • Sugere comandos para visualizar e gerenciar as tarefas geradas
   • Inclui mensagens amigáveis explicando os resultados

Solicitação JSON-RPC

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

Resposta 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?"
        }
      }
    }
  ]
}

Quando a ferramenta apm_dependencies é chamada:

1. Validação de Parâmetros:

   • Valida o parâmetro action (obrigatório, deve ser uma das ações válidas)
   • Valida o parâmetro projectRoot (obrigatório, deve ser um caminho absoluto)
   • Valida parâmetros específicos da ação:
     • Para add e remove: Valida os parâmetros id e dependsOn (obrigatórios, strings não vazias)
   • Valida parâmetros opcionais: file

2. Recuperação de Tarefas:

   • Lê o arquivo de tarefas do local especificado (padrão para apm-artifacts/artifacts.json se não for fornecido)
   • Extrai a lista de tarefas do arquivo

3. Execução da Ação:

   • Executa a ação apropriada com base no parâmetro action:
     • add: Adiciona uma dependência entre duas tarefas
     • remove: Remove uma dependência entre duas tarefas
     • validate: Verifica problemas de dependência (referências circulares, dependências ausentes)
     • fix: Corrige automaticamente problemas de dependência

4. Processamento Específico por Ação:

   • Para add:
     • Encontra a tarefa que dependerá de outra
     • Encontra a tarefa da qual se dependerá
     • Verifica se a dependência já existe
     • Adiciona a dependência se ela não existir
     • Valida dependências para garantir que não haja referências circulares
   • Para remove:
     • Encontra a tarefa que depende de outra
     • Verifica se a dependência existe
     • Remove a dependência se ela existir
   • Para validate:
     • Verifica dependências circulares
     • Verifica dependências ausentes
     • Retorna os resultados da validação
   • Para fix:
     • Corrige dependências ausentes removendo-as
     • Corrige dependências circulares quebrando os ciclos
     • Retorna os resultados das correções

5. Operações de Arquivo:

   • Atualiza os dados das tarefas em memória
   • Grava as tarefas atualizadas de volta no arquivo
   • Gera arquivos individuais de tarefas

6. Formatação da Resposta:

   • Retorna uma resposta JSON estruturada contendo:
     • Dados específicos da ação (tarefa, tarefa de dependência, resultados de validação, resultados de correção)
     • Status de sucesso e mensagem
     • Informações contextuais sobre a operação
     • Carimbos de data/hora e informações da sessão

7. Tratamento de Erros:

   • Trata erros de validação (campos obrigatórios ausentes, valores inválidos)
   • Trata erros de arquivo não encontrado
   • Trata erros de tarefa não encontrada
   • Trata erros de dependência circular
   • Retorna respostas de erro padronizadas com informações de contexto

Solicitação 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"
  }
}

Resposta 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 a ação 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 a ação 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
            }
          }
        }
      }
    }
  ]
}

Quando a ferramenta apm_complexity_node é chamada:

1. Validação de Parâmetros:

   • Valida o parâmetro projectRoot (obrigatório, deve ser um caminho absoluto)
   • Valida parâmetros opcionais: file, output, markdownOutput, threshold, model e research
   • Aplica valores padrão para parâmetros opcionais:
     • output: "apm-artifacts/resources/reports/task-complexity-report.json"
     • markdownOutput: "apm-artifacts/resources/reports/task-complexity-report.md"
     • threshold: 5 (tarefas com complexidade ≥ 5 serão recomendadas para expansão)
     • research: false (se deve usar Perplexity AI para análise baseada em pesquisa)

2. Recuperação de Tarefas:

   • Lê o arquivo de tarefas do local especificado (padrão: artifacts.json se não for fornecido)
   • Extrai a lista de tarefas do arquivo
   • Filtra as tarefas para incluir apenas aquelas que não estão 'done' (concluídas) nem 'cancelled' (canceladas)
   • Ignora tarefas que já possuem subtarefas (pois já foram detalhadas)

3. Processo de Análise de Tarefas:

   • Para cada tarefa:
     • Calcula fatores básicos de complexidade:
       • Comprimento da descrição (0-0,2 pontos)
       • Comprimento dos detalhes (0-0,2 pontos)
       • Quantidade de dependências (0-0,2 pontos)
       • Fator de prioridade (alta: 0,2, média: 0,1, baixa: 0 pontos)
       • Quantidade de termos técnicos (0-0,2 pontos)
     • Se a pesquisa estiver habilitada, aprimora a análise com Perplexity AI
     • Usa Claude AI para analisar a complexidade em uma escala de 1 a 10
     • Recomenda um número de subtarefas com base na complexidade
     • Gera prompts de expansão e comandos

4. Geração de Relatórios:

   • Cria um relatório de complexidade com:
     • Análise específica por tarefa (ID, título, pontuação de complexidade, subtarefas recomendadas)
     • Prompts de expansão para detalhar tarefas complexas
     • Comandos para executar a expansão de tarefas
     • Metadados (carimbo de data/hora da geração, limite, contagens de tarefas, complexidade média)
   • Garante que os diretórios de saída existam
   • Grava o relatório JSON no caminho de saída especificado
   • Formata o relatório em um documento markdown legível
   • Grava o relatório markdown no caminho de saída markdown especificado

5. Formatação da Resposta:

   • Retorna uma resposta JSON estruturada contendo:
     • Os dados completos do relatório de complexidade
     • O relatório formatado como uma string markdown
     • Caminhos dos arquivos de saída para os relatórios JSON e markdown
     • Estatísticas da análise de tarefas (tarefas analisadas, tarefas complexas encontradas)
     • Orientação de comunicação com o usuário
     • Instruções do agente para os próximos passos

6. Tratamento de Erros:

   • Trata erros de arquivo não encontrado
   • Trata erros de criação de diretório
   • Trata erros de gravação de arquivo
   • Retorna respostas de erro padronizadas com informações de contexto

Solicitação 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
  }
}

Resposta 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."
      }
    }
  ]
}