⚡ Instalação em 30 segundos

npm install -g devflowcdt     # instala os comandos "devflowcdt" (alias: "devflow-mcp")
devflowcdt setup              # pergunta email/senha do DevFlow, TESTA o login e salva com segurança
devflowcdt install-skill      # instala o guia de uso (Claude) e o prompt /devflow (Codex)

💡 O setup é interativo: a senha não aparece na tela e é validada antes de salvar (em ~/.devflow-mcp/.env). A config pública do Firebase já vem embutida — você só informa email e senha.

# Claude Code
claude mcp add devflow --scope user -- devflowcdt

// Claude Desktop  →  claude_desktop_config.json
{ "mcpServers": { "devflow": { "command": "devflowcdt" } } }

# Codex  →  ~/.codex/config.toml
[mcp_servers.devflow]
command = "devflowcdt"

Rode devflowcdt config pra ver isso a qualquer momento.

npm install -g devflowcdt@latest && devflowcdt install-skill

Ao iniciar, o servidor consulta o npm; se a sua versão estiver atrás do latest, ele avisa em toda resposta.

🗺️ O fluxo do Kanban (7 fases)

flowchart LR
    A([📥 Backlog]) --> B([📝 Planejando])
    B --> C([🔍 Plan Review])
    C --> D([✅ Aprovado])
    D --> E([🛠️ Em Progresso])
    E --> F([🧪 QA Review])
    F --> G([🏁 Concluído])

    classDef admin fill:#fee2e2,stroke:#dc2626,color:#991b1b;
    classDef dev fill:#dbeafe,stroke:#2563eb,color:#1e40af;
    class A,B,E dev;
    class C,D,F,G admin;

| 🔵 Usuário comum faz | 🔴 Só admin faz | |:--|:--| | Criar task → levar até Planejando | Aprovar o planejamento (Plan Review → Aprovado) | | Submeter proposta (entra em Plan Review) | Concluir a task (QA → Concluído) + pontuar | | Tocar de Aprovado até QA Review | Deletar / purgar / criar projeto |

🔐 O papel (admin/comum) é lido do banco (users/{uid}/role) a cada ação — nunca de variável de ambiente. Um usuário não consegue se promover.

🎯 Regras obrigatórias (o servidor faz cumprir)

🧮 Sistema de Dificuldade (3 fases)

Três ações exigem uma análise estruturada (senão a ação é recusada):

• Fase 1 — create_task: nível 1–5 + justificativa técnica + motivo da prioridade. Adiciona o bloco de dificuldade + bloqueio de planejamento.
• Fase 2 — review_proposal (aprovar): reavalia o nível analisando o plano da UI + o que o usuário fornecer (arquivo OU texto). Remove o bloqueio.
• Fase 3 — complete_task: análise dos commits; calcula os pontos com o nível final.
• Tradução/i18n/localização como escopo principal: dificuldade máxima Média (nível 2); i18n incidental em feature/refatoração não aciona o teto.
• Calibração conservadora: nível 4/5 é exceção e nível 1/2 também é auditado; sem evidência forte o servidor reduz, com sinais fortes eleva para o piso coerente.
• Claude Max/full-time: IA reduz esforço mecânico, não risco técnico. Boas classificações olham contrato, dados, segurança, integração, regressão e decisões reais.
• Prioridade ≠ dificuldade: prioridade mede impacto/urgência; dificuldade mede complexidade/risco de implementação. Uma não pode inflar a outra.
• Negação não conta como sinal: "sem backend/schema/RLS/API" não sustenta nível alto; menção nominal a auth/email/financeiro também não basta sem alteração real.
• Tempo é sinal secundário na Fase 3: usa tempo informado em analysis.deliveryTimeHours ou intervalo entre commits. started/completed do DevFlow só entra se houver um único commit. Sem evidência suficiente, ignora tempo.
• OmniTeams: regra exclusiva por projeto/repo; commits são analisados por autor git, não por branch, e conclusão sem análise de commits é bloqueada.
• Conflito de planejamento: check_work_conflicts cruza arquivos/tabelas/endpoints do plano contra tasks approved/in_progress do projeto.

🛡️ Anti-manipulação & Churn Floor

• Anti-inflação: a IA ignora nível/prioridade que o usuário pedir ("dá uma aumentada", "bota 5"). Tentativas viram aviso carimbado no card.
• Churn Floor calibrado: na Fase 3, se você passar repoPath, o servidor lê o git de verdade (gross/net, revisitação, reverts). Churn só pesa forte com sinais mais altos e ainda passa pela calibração anti-inflação.
• Sem branch: o servidor pode filtrar commits pelo autor do responsável e devolver hunks para revisão linha a linha.
• Cycle time: fonte principal é commit time real (firstCommitAt→lastCommitAt) ou tempo informado pelo usuário/admin. O tempo do MCP/DevFlow pode incluir espera/admin/review e só é fallback para task com commit único.
• Descrição limpa: o servidor substitui o bloco gerado pelos marcadores e mantém notas de calibração compactas para não poluir o card.
• Flag de inflação: nível alto + diff trivial + sem churn → aviso "revisar".
• Fairness gate: score final >=100 ou nível 4/5 exige analysis.scoreDivergenceReview com comparação detalhada contra tasks médias/pares. Se a diferença não for sustentada por commits, risco e impacto real, a conclusão deve reduzir o nível ou reprovar QA.

📊 A pontuação (finalScore) é calculada na conclusão pela fórmula oficial (base por dificuldade × prioridade × prazo × qualidade × tempo × churn × bugs), gravada em gamification/scores e alimenta os rankings.

🧰 Ferramentas (34)

list_tasks · get_task · create_task (Fase 1) · update_task · move_task_phase · add_comment · assign_task · delete_task (admin, soft) · restore_task · purge_task (admin, hard) · create_task_branch · analyze_commits

check_work_conflicts (taskId ou text/file/url; detecta arquivos/tabelas/endpoints em conflito) · send_notification (admin) · list_notifications (uid opcional; padrão = usuário logado) · mark_notification_read

list_pool · claim_task · submit_proposal (exige plano real: text/file/url) · review_proposal (admin, Fase 2) · review_qa (admin, reject) · complete_task (admin, Fase 3 + pontua + churn floor)

list_projects · get_project · get_board (Kanban por projeto) · create_project (admin) · list_users · get_user · my_metrics

get_ranking (general/weekly/monthly + escolha de semana/mês) · get_project_ranking · score_evolution · get_gamification · list_notifications · mark_notification_read · list_suggestions · create_suggestion · get_difficulty_system

💬 Exemplos

"Minhas tasks high do LinkBiz"        → list_tasks {mine:true, priority:"high", project:"LinkBiz"}
"O que tem no bolsão do eVolDx?"      → list_pool {project:"eVolDx"}
"Cria a task X no projeto Y"          → create_task {title, project, repoPath, analysis:{...}}
"Ranking dessa semana"                → get_ranking {scope:"weekly"}
"Conclui a task Z" (admin)            → analyze_commits → complete_task {taskId, repoPath, analysis:{...}}

🌿 Branch automática

create_task { createBranch: true } gera um nome tipo feature/T123-titulo e salva no campo branch. Passe repoPath (repo git local) para criar/checkout de verdade; branchBase define a origem (ex.: main). Mesmo sem createBranch, passar repoPath faz o MCP ler git rev-parse --abbrev-ref HEAD e salvar a branch atual na task. Também passe repoPath ao mover fases, enviar/aprovar planejamento, reprovar QA ou concluir, para manter task.branch sincronizada.

🖼️ Foto de perfil — não suportada (por design do app)

O DevFlow não guarda avatar no backend (sem campo de foto, sem Storage; o ranking usa as iniciais do nome). Testado photoURL no Auth e 21 nomes de campo — nenhum é renderizado. Trocar a foto exigiria mudança no app.

🔒 Segurança

| Camada | O que protege | Onde | |:--|:--|:--| | MCP (este pacote) | papel verificado por ação, gates de fase, dificuldade obrigatória, churn floor, anti-manipulação | cliente | | Firebase Security Rules | impede escrita direta no banco que pula o MCP — a trava definitiva | servidor (responsabilidade do tech lead — ver SECURITY-RULES.md) |

• 🔑 Credenciais ficam em ~/.devflow-mcp/.env (fora do git). Nunca comite senha/token.
• A apiKey do Firebase é config pública de cliente (não é segredo).
• ⚠️ As travas do MCP são defesa-em-profundidade; sem as Security Rules, alguém com o login ainda pode escrever direto no banco.

Feito para a CDT · MCP do DevFlow · github.com/Victorow/mcp-devflow