@komexa/kickoff-mcp

English | Português

Copilot de estrutura para vibe coders. Transforma ideias em projetos rastreáveis. Guia o kickoff, gera documentação completa, quebra requisitos em tasks e acompanha cobertura — tudo offline, integrado ao seu agente de IA.

Funciona com Claude Code, Cursor, Windsurf, Aider e qualquer IDE com suporte a MCP.

📚 Changelog e release notes completas: https://www.npmjs.com/package/@komexa/kickoff-mcp?activeTab=code

Por que usar

Vibe coding é rápido — mas sem estrutura, o projeto vira uma bola de neve de features sem rastreabilidade. O kickoff-mcp resolve isso:

| Problema | Solução | |----------|---------| | "Perdi o fio do projeto" | get_project_brief — resumo completo em 300 tokens | | "Não sei o que implementar agora" | next_task — próxima task prioritária com contexto, schema e fluxo | | "Feature nova sem registro" | add_feature — REQ-ID automático, docs atualizados | | "Não sei o que já foi feito" | validate_coverage — cobertura por REQ-ID, % por prioridade | | "Formulário não bate com o banco" | validate_integrity — detecta campos faltantes entre UI↔API↔DB | | "Agente inventou cor/componente fora do design" | validate_design — trava paleta, tokens e componentes aprovados | | "Feature nova esqueceu soft delete / LGPD" | add_feature expande CRUD + soft delete + LGPD + auditoria em sub-REQs | | "Quero ver o progresso" | Dashboard React em localhost:4242 |

Instalação

npm install -g @komexa/kickoff-mcp

Configurar como servidor MCP

Adicione ao arquivo de configuração do seu agente (.mcp.json, claude_desktop_config.json, etc.):

{
  "mcpServers": {
    "kickoff-mcp": {
      "command": "npx",
      "args": ["-y", "@komexa/kickoff-mcp"]
    }
  }
}

Inicializar em um projeto existente

cd /caminho/do/projeto
npx @komexa/kickoff-mcp init

Cria o .mcp.json com o servidor configurado e o CLAUDE.md com o contexto do projeto.

Início rápido

1. npx @komexa/kickoff-mcp init     ← configura o projeto
2. Abra o Claude Code (ou sua IDE)
3. Diga: "iniciar kickoff"          ← entrevista guiada começa
4. Docs gerados automaticamente
5. next_task → implementa → complete_task → repete

Tools MCP

get_project_brief

Resumo compacto do projeto (~300 tokens). Use no início de cada sessão para orientar o agente sem gastar contexto com leitura manual de docs.

Retorna: nome, stack, % de cobertura, próxima task pendente, data da última validação, fatos de ambiente.

kickoff_project

Entrevista guiada em 5 blocos que gera 15+ documentos na raiz do projeto:

| Bloco | O que levanta | |-------|---------------| | Identidade | Nome, tipo, descrição, problema, solução | | Stack | Tecnologias por camada com justificativa | | Features | Funcionalidades, critérios de aceite, prioridade (must/should/could), fase (mvp/post) | | Modelo de dados | Entidades, schema SQL, relacionamentos | | Design System | Framework CSS, biblioteca de componentes, paleta, fonte, radius, spacing |

Fluxo com review step (REQ-067): start → entrevista → review (summary estruturado + 3 opções: adicionar features, editar REQs, confirmar) → generate (persiste docs + KICKOFF_SUMMARY.md).

Documentos gerados:

projeto/
├── REQUIREMENTS.md          ← fonte da verdade (REQ-IDs)
├── CLAUDE.md                ← instruções para Claude Code
├── docs/
│   ├── PRD.md               ← Product Requirements Document
│   ├── SAD.md               ← Software Architecture Document
│   ├── ERD.md               ← Entity Relationship Diagram
│   ├── FLOWS.md             ← Diagramas de fluxo por feature
│   ├── DESIGN_SYSTEM.md     ← tokens, paleta, componentes aprovados (REQ-065)
│   ├── KICKOFF_SUMMARY.md   ← snapshot do kickoff confirmado (REQ-067)
│   ├── RUNBOOK.md           ← Setup, comandos, env vars
│   ├── LEGAL.md             ← Licença e privacidade
│   └── PROCESS.md           ← Processo de desenvolvimento
├── .agents/
│   ├── rules/
│   │   ├── project-context.md
│   │   ├── requirements-guide.md
│   │   ├── coding-standards.md    ← doc comments gerados na linguagem do projeto
│   │   └── task-workflow.md
│   └── skills/
│       ├── add-feature.md
│       ├── validate-coverage.md
│       └── create-skill.md
└── .kickoff/
    ├── db.sqlite            ← índice SQLite (cache reconstruível)
    ├── LEARNINGS.md         ← top 15 erros→soluções memorializados
    └── .gitignore

Se o projeto já tiver REQUIREMENTS.md, oferece atualizar, regenerar ou reiniciar — sem sobrescrever trabalho existente.

add_feature

Registra uma nova feature com REQ-ID único, atualiza REQUIREMENTS.md e docs afetados.

Parâmetros:
  description   — descrição da feature
  priority      — must | should | could
  phase         — mvp | post
  completeness  — (REQ-066) flags booleanas para expandir a feature em sub-REQs

Feature completeness (REQ-066): se a feature é uma entidade de domínio (ex: "Leads"), a tool pergunta se precisa de listagem, detalhe, formulário, delete (hard/soft), export, RBAC, LGPD e auditoria. Cada flag positiva gera um sub-REQ dedicado e respeita a ordem TDD no breakdown:

| Sub-REQ | O que gera | |---------|------------| | REQ-XXX-A-LIST | Tela de listagem + endpoint paginado | | REQ-XXX-B-DETAIL | Tela de detalhe + endpoint GET | | REQ-XXX-C-FORM | Formulário de criação/edição + endpoints POST/PUT | | REQ-XXX-D-DELETE | Deleção (soft delete com deleted_at + filtros em queries) | | REQ-XXX-E-EXPORT | Export (CSV/XLSX) + endpoint | | REQ-XXX-F-RBAC | Permissões por role | | REQ-XXX-G-LGPD | Consentimento, direito ao esquecimento, export de dados pessoais | | REQ-XXX-H-AUDIT | Timestamps + user tracking |

Também alerta features não rastreadas: ao rodar validação, arquivos sem // REQ-XXX aparecem como "não rastreados".

validate_coverage

Varre o codebase e classifica cada REQ-ID:

| Status | Significado | |--------|-------------| | ✅ coberto | REQ-ID encontrado no código com critérios de aceite atendidos | | ⚠️ parcial | Implementação existe, falta algum critério | | ❌ pendente | Sem implementação rastreável |

Estratégia inteligente de tokens (REQ-045, REQ-068):

| Cenário | Behavior | Custo | |---------|----------|-------| | Ollama conectado | Análise semântica (mapeia código → REQ-IDs sem comentários). Resultado cacheado por hash de REQUIREMENTS.md | Ollama usa seus tokens locais; tool retorna só resumo (quase zero tokens Claude) | | Ollama + cache válido | Carrega resultado anterior (instantâneo) | Zero tokens (ambos) | | Ollama indisponível | Nada automático. User chama manualmente se precisar → varredura rápida por regex | User controla; minimiza tokens |

Quando chamar validate_coverage:

• ✅ Ao fim de uma task significativa (implementou novos REQ-IDs)
• ✅ Antes de committar (verificar cobertura)
• ✅ Quando o usuário pedir relatório de progresso
• ❌ NÃO a cada mudança trivial (economiza tokens)

Salva relatório em VALIDATION_REPORT.md com timestamp e tabela detalhada.

validate_integrity

Detecta campos faltantes entre camadas (UI ↔ API ↔ DB) via análise AST.

Suporta:

• TypeScript / JavaScript — interfaces, types, Zod schemas, controllers, formulários React
• C# — classes, properties, Entity Framework models, DTOs, controllers

Exemplo: campo `email` existe no form React mas não no endpoint POST → alerta gerado

validate_design

Trava o Design System capturado no kickoff (REQ-065). Varre .tsx/.css/.scss e alerta quando detecta cores literais (hex/rgb/hsl) ou componentes fora da paleta e tokens aprovados.

• Gera docs/DESIGN_VALIDATION.md com as violações
• Regra ⛔ Design Constraints injetada em .agents/rules/coding-standards.md — impede o agente de inventar cores/componentes sem REQ de UI
• Rode após qualquer task que toca UI

task_manager

Gerenciamento completo de tasks com ciclo automatizado next_task → implementa → complete_task.

Actions disponíveis

| Action | O que faz | |--------|-----------| | next_task | Seleciona a task mais urgente, marca como in_progress, retorna contexto completo | | complete_task | Valida cobertura, cria git commit, marca task/subtasks/milestone como done | | breakdown_req | Quebra um REQ-ID em subtasks TDD + cria milestone automático | | create_task | Cria task manual vinculada a um REQ-ID | | list_tasks | Kanban por status (todo / in_progress / done / blocked) | | update_task | Atualiza status, horas estimadas, assignee | | create_milestone | Cria milestone manual com prazo | | stats | Estatísticas: tasks, horas, progresso por REQ, milestones |

Ordem TDD (breakdown automático)

Tasks são geradas e executadas nesta ordem para cada REQ-ID:

1. Schema/Types       → interfaces, tipos, schema SQL
2. Backend + Tests    → testes primeiro, implementação depois
3. Frontend           → UI consumindo o backend testado
4. validate_integrity → confirma que os dados fluem entre camadas

Contexto retornado pelo next_task

• Schema SQL das entidades relevantes (do ERD)
• Diagrama de fluxo da feature (do FLOWS)
• Critérios de aceite (do REQUIREMENTS)
• Checklist de subtasks
• Milestone e prazo
• Plano de implementação detalhado (se Ollama disponível)

Gantt / Sprint Timeline

Campo start_date nas tasks + config hours_per_day. Dashboard exibe Gantt com zoom dia/semana, cores por status e atrasos em vermelho.

dev_context

Memória persistente de ambiente e erros. Disponível como tool MCP e como CLI.

| Action | O que faz | |--------|-----------| | get | Lista fatos de ambiente salvos (platform, shell, node, paths, etc.) | | set | Salva um fato de ambiente como chave→valor | | remember | Memoriza um par erro→solução com score de confiança | | find | Busca soluções por padrão (semântico com Ollama, textual sem) | | translate | Acessa histórico completo de pares error→solution no SQLite | | sync | Promove top 15 soluções do SQLite para .kickoff/LEARNINGS.md |

O init detecta automaticamente: platform, shell, Node.js version, Python, package manager e salva como fatos de ambiente.

Dados sensíveis (tokens, IPs, paths pessoais) são sanitizados antes de persistir.

Soluções são sugeridas com score de confiança (success_count / total) — threshold mínimo de 0.5.

query_project_brain

Busca full-text search (FTS5) em requisitos por palavras-chave.

• Tokenizador unicode61 com remove_diacritics → suporte nativo a pt-BR
• Retorna: req_id, título, prioridade e critério de aceite dos N resultados mais relevantes
• Sincronizado via triggers com a tabela requirements

review_code

Análise semântica de código via Ollama (qwen2.5-coder recomendado).

Detecta bugs, campos faltantes, REQ-IDs sem anotação. Fallback silencioso se Ollama estiver indisponível.

progress_report

Relatório de progresso e cobertura.

Modos:
  summary  — % por prioridade (must/should/could) + milestones
  full     — tabela completa com status por REQ-ID

CLI

# Setup
kickoff-mcp init [dir]                          # Configura projeto (.mcp.json + CLAUDE.md + .agents/)
kickoff-mcp regenerate [dir]                    # Regenera .agents/ sem refazer kickoff
kickoff-mcp rebuild-index [dir]                 # Reconstrói SQLite a partir dos .md

# Validação
kickoff-mcp validate [dir]                      # Valida cobertura de requisitos
kickoff-mcp validate-integrity [entity]         # Valida integridade entre camadas (UI/API/DB)
kickoff-mcp validate-design [dir]               # Valida aderência ao Design System

# Reports e dashboard
kickoff-mcp report [summary|full]               # Relatório de progresso
kickoff-mcp dashboard [dir]                     # Abre dashboard em localhost:4242

# Automação
kickoff-mcp watch [cooldown-ms]                 # Daemon auto-valida on save (default cooldown: 2s)
kickoff-mcp add-feature <desc> [prio] [fase]    # Registra feature (must/should/could, mvp/post)

# Memória de ambiente
kickoff-mcp dev-context get                     # Lista fatos de ambiente
kickoff-mcp dev-context set <key> <value>       # Salva fato
kickoff-mcp dev-context remember <erro> <sol>   # Memoriza solução para erro
kickoff-mcp dev-context find <pattern>          # Busca soluções (semântico com Ollama)
kickoff-mcp dev-context sync                    # Atualiza LEARNINGS.md

# Avançado
kickoff-mcp review <arquivo> [foco]             # Review de código via Ollama
kickoff-mcp info                                # Status do sistema (versão, SQLite, Ollama)

Dashboard

kickoff-mcp dashboard
# Acesse: http://localhost:4242

| Aba | Conteúdo | |-----|----------| | Overview | Cobertura por prioridade, métricas globais, drawer de detalhes de REQ | | Tasks | Kanban (todo/in_progress/done/blocked), subtasks expandíveis, sprint timeline Gantt | | Workflows | Pipeline MCP, histórico de validações, milestones timeline | | Schema | Entidades, campos por camada (UI/API/DB), issues de integridade detectadas | | Design System | Preview dos tokens capturados no kickoff (paleta, fonte, radius, componentes aprovados) |

Atualiza em tempo real via SSE (Server-Sent Events) — mudanças nos .md refletem sem refresh.

Ollama (opcional — recomendado para projetos grandes)

Ativa análise semântica de cobertura, enriquecimento de tasks, review de código e busca inteligente. Zero custo de tokens Claude — Ollama roda localmente com seu modelo.

Por que usar Ollama

| Feature | Sem Ollama | Com Ollama | |---------|-----------|-----------| | validate_coverage | Detecta // REQ-XXX | Análise semântica (sem comentários) + cache | | task_manager | Descrição genérica | Plano detalhado + schema + fluxo | | query_project_brain | Busca textual (LIKE) | Busca semântica inteligente | | review_code | Não disponível | Análise de bugs e aderência a REQs | | Custo tokens Claude | Mínimo | Análise no Ollama (seus tokens locais) |

Setup

# 1. Instalar Ollama
curl -fsSL https://ollama.com/install.sh | sh   # macOS/Linux
# Windows: https://ollama.com/download

# 2. Baixar modelos
# Para busca semântica
ollama pull nomic-embed-text    # 274 MB — padrão
ollama pull bge-small           # 67 MB  — balanceado

# Para análise de cobertura e review
ollama pull qwen2.5-coder:7b    # 7.3GB — recomendado (análise semântica forte)
ollama pull gemma2:9b           # 5.5GB — alternativa equilibrada

# Para enriquecimento de tasks
ollama pull gemma4:e4b          # lighter, fast

Variáveis de ambiente

# .env na raiz do projeto (adicione ao .gitignore)
KICKOFF_OLLAMA_URL=http://127.0.0.1:11434
KICKOFF_OLLAMA_MODEL=qwen2.5-coder:7b      # análise de cobertura
KICKOFF_OLLAMA_GEN_MODEL=qwen2.5-coder:7b  # tasks + review

Estratégia de cache (REQ-045)

Análise de cobertura é cacheada por hash de REQUIREMENTS.md:

• 1ª execução: Ollama analisa (~30s para grandes codebases) → resultado salvo em SQLite
• 2ª+ execução: cache hit instantâneo (ZERO custo)
• Quando REQUIREMENTS.md muda: cache invalidado automaticamente

Resultado: projetos grandes rodam análise semântica uma vez, depois usam cache.

Persona sênior (REQ-068)

Todos os prompts enviados ao Ollama (enrichTasksWithOllama, review_code, reschedule_ai) incluem persona "arquiteto de software sênior com 10–15 anos de experiência em [stack do projeto]" e exigem considerar:

• Edge cases e tratamento de erros
• Segurança (OWASP top 10)
• Escalabilidade
• CRUD completo (não só happy path) — soft delete, LGPD, auditoria
• Testes unitários e de integração
• Acessibilidade (WCAG) quando for UI
• Aderência a REQUIREMENTS, SAD, ERD, FLOWS, DESIGN_SYSTEM

Output estruturado em seções obrigatórias: Arquivos, Schema, Endpoints, Validações, Edge cases, Testes, Segurança/Compliance.

Diferença com e sem Ollama

| Sem Ollama | Com Ollama | |------------|------------| | Contexto estático (schema + fluxo + critérios) | + Plano de implementação detalhado com persona sênior (arquivos, rotas, validações, edge cases, OWASP) | | Busca textual (LIKE) em soluções memorizadas | Busca semântica por similaridade de embeddings | | Validação por regex (// REQ-XXX) | + Varredura semântica — infere REQ mesmo sem comentário | | Sem review de código | Review com análise de bugs, melhorias, REQ-IDs faltantes, OWASP e compliance |

Economia de tokens (REQ-NF-001, REQ-045)

Filosofia: Controle total do usuário

Sem Ollama:

• Nenhuma validação automática (você decide quando validar)
• Minimal token consumption (só o que você pede)
• Varredura rápida por regex quando chamar validate_coverage

Com Ollama:

• Análise semântica poderosa (local, seus tokens Ollama)
• Resultado cacheado (próximas chamadas = instantâneo)
• Tool retorna só resumo pequeno (quase zero tokens Claude)

Comparação de custos

| Operação | Tokens Claude | Tokens Ollama | |----------|---------------|---------------| | Sem Ollama + sem validate | 0 | 0 | | Sem Ollama + validate | ~20 (resposta regex) | 0 | | Com Ollama + 1ª validate | ~5 (resumo) | ~1000 (análise) | | Com Ollama + 2ª+ validate | ~5 (cache hit) | 0 | | Variação de projeto | 50–500 arquivos | Escalável |

Insight: Projetos grandes ganham com Ollama — análise pesada feita uma vez, depois cache grátis.

Rastreabilidade REQ-ID

Adicione // REQ-XXX no topo de cada arquivo criado ou modificado:

// REQ-042
export function initProject(dir: string) { ... }

O validate_coverage usa esses comentários como âncoras. Com Ollama, a varredura semântica complementa a detecção por regex.

Suporte a múltiplos agentes

O kickoff-mcp init gera regras e skills em .agents/ compatíveis com qualquer agente que leia markdown:

• Claude Code → CLAUDE.md + .agents/rules/
• Cursor → .agents/rules/ + .agents/skills/
• Windsurf → .agents/rules/
• Aider → .agents/rules/

As regras geradas incluem o padrão de doc comments da linguagem do projeto (JSDoc para TS/JS, /// <summary> para C#, docstrings para Python, GoDoc para Go, etc.).

Arquitetura

Claude Code / Cursor / Windsurf
  │  stdio (MCP protocol)
  ▼
@komexa/kickoff-mcp (src/index.ts)
  ├── tools/kickoff.ts              ← entrevista guiada + gera 15+ docs
  ├── tools/add-feature.ts          ← registra feature, atualiza .md
  ├── tools/validate.ts             ← varre codebase vs REQ-IDs
  ├── tools/validate-integrity.ts   ← detecta gaps UI↔API↔DB via AST
  ├── tools/task-manager.ts         ← tasks, subtasks, milestones, ciclo TDD
  ├── tools/report.ts               ← relatório de cobertura
  ├── tools/dev-context.ts          ← memória de ambiente e erros
  ├── tools/query-brain.ts          ← busca FTS5 em requisitos
  ├── tools/project-brief.ts        ← resumo compacto para início de sessão
  ├── tools/review-code.ts          ← review semântico via Ollama
  └── tools/validate-design.ts      ← trava Design System (REQ-065)
  │
  ├── core/doc-generator.ts         ← Handlebars → .md (15+ templates)
  ├── core/sqlite-index.ts          ← índice SQLite (.kickoff/db.sqlite)
  ├── core/coverage.ts              ← classificação coberto/parcial/pendente
  ├── core/ollama-enricher.ts       ← enriquecimento de tasks (estático + LLM)
  ├── core/ollama-persona.ts        ← persona arquiteto sênior (REQ-068)
  ├── core/file-watcher.ts          ← daemon auto-validate on save
  ├── core/fs-reader.ts             ← leitura de .md e codebase
  └── core/context-injector.ts      ← injeta contexto do projeto nos prompts
  │
  dashboard/server.ts               ← HTTP localhost:4242 + SSE
  dashboard/ui/                     ← Vite + React (overview, tasks, workflows, schema, design system)

Decisões arquiteturais

| ADR | Decisão | |-----|---------| | 001 | .md são fonte da verdade; SQLite é cache reconstruível automaticamente | | 002 | MCP usa stdio transport — compatível com Claude Code, Cursor, Windsurf | | 003 | Dashboard roda em processo separado — MCP não fica bloqueado pelo HTTP | | 004 | Vite builda React para estático; MCP serve os arquivos buildados |

Desenvolvimento

git clone https://github.com/komexa/kickoff-mcp.git
cd kickoff-mcp

npm install
npm run dev          # watch mode (MCP + UI em paralelo)
npm run build        # build completo (TypeScript + Vite)
npm run build:mcp    # compila apenas o MCP server
npm run build:ui     # builda apenas o dashboard React
npm test             # roda testes
npm run lint         # ESLint + TypeScript check

npx . init           # testa o CLI localmente
npx . dashboard      # testa o dashboard localmente

Licença

MIT — veja LICENSE.

Desenvolvido por Komexa Studio.