# @komexa/kickoff-mcp

**[English](README.en.md)** | 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.

---

## 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 |
| "Quero ver o progresso" | Dashboard React em `localhost:4242` |

---

## Instalação

```bash
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.):

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

### Inicializar em um projeto existente

```bash
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 4 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 |

**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
│   ├── 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
```

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 |

Detecta `// REQ-XXX` no topo dos arquivos. Com Ollama, faz **varredura semântica** — infere a qual REQ pertence mesmo sem comentário.

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
```

---

### `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

```bash
# 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)

# 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

```bash
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 |

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

---

## Ollama (opcional)

Ativa enriquecimento de tasks, review de código e busca semântica. Fallback silencioso para modo estático se indisponível.

### Setup

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

# 2. Modelo de embeddings (busca semântica)
ollama pull nomic-embed-text    # 274 MB — padrão
ollama pull bge-small           # 67 MB  — balanceado
ollama pull all-minilm          # 23 MB  — leve

# 3. Modelo de geração (tasks + review de código)
ollama pull gemma4:e4b          # padrão
ollama pull qwen2.5-coder:7b    # recomendado para review
```

### Variáveis de ambiente

```bash
# .env na raiz do projeto (adicione ao .gitignore)
KICKOFF_OLLAMA_URL=http://127.0.0.1:11434
KICKOFF_OLLAMA_MODEL=nomic-embed-text       # embeddings
KICKOFF_OLLAMA_GEN_MODEL=gemma4:e4b         # geração
```

### Diferença com e sem Ollama

| Sem Ollama | Com Ollama |
|------------|------------|
| Contexto estático (schema + fluxo + critérios) | + Plano de implementação detalhado (arquivos, rotas, validações) |
| 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 |

---

## Rastreabilidade REQ-ID

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

```typescript
// 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
  │
  ├── 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/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)
```

### 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

```bash
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](./LICENSE).

---

Desenvolvido por **[Komexa Studio](https://komexa.com)**.
