🇧🇷 Português · 🇺🇸 English

Faz AI Kanban

⚠️ O Faz AI está em fase alpha.

O projeto é novo e muda rápido: quase toda semana sai uma versão, e nem tudo foi testado em todas as ferramentas de IA e sistemas operacionais. Erros e comportamentos inesperados podem acontecer, e telas, comandos e o formato do board ainda podem mudar de uma versão para outra.

Use à vontade, mas com esse cuidado em mente: revise o que a IA fizer antes de aprovar e não dependa do board como único registro de algo importante. Se algo quebrar ou parecer estranho, conte numa issue: é assim que ele sai do alpha.

Obrigado a quem está baixando e testando.

Publiquei a extensão no marketplace do Cursor e fui dormir. Quando acordei para instalá-la na minha máquina de trabalho, ela já tinha 160 downloads. Eu não esperava isso, e fiquei muito feliz.

A cada pessoa que instalou, abriu o board e deu uma chance a um projeto que acabou de nascer: muito obrigado. É por vocês que ele continua.

O Faz AI é totalmente gratuito e open source (licença MIT), e contribuições são bem-vindas: conte o que funcionou e o que não funcionou, abra uma issue ou mande um pull request.

Euclides G Catunda

Gostou? Ajude o Faz AI a crescer.

Um projeto novo melhora com o retorno de quem usa. Se ele já te poupou tempo, estes gestos de um minuto fazem muita diferença:

• ⭐ Dê uma estrela no repositório do GitHub: é o que mais ajuda outras pessoas a encontrarem o projeto.
• 💬 Avalie a extensão na loja onde você a instalou, com estrelas e, se puder, duas linhas sobre o que achou: VS Code Marketplace ou Open VSX (a loja do Cursor).
• 🐞 Encontrou um bug? Abra uma issue dizendo o que você fez, o que esperava e o que aconteceu. A versão da extensão e o editor que você usa ajudam bastante.
• 💡 Tem uma ideia ou sugestão? Conte numa issue: fluxos que faltam, telas confusas e integrações que você gostaria de ver.

Antes de abrir, vale uma olhada nas issues já abertas: às vezes a ideia já existe, e um 👍 nela ajuda a decidir a ordem do que vem a seguir.

Um board kanban dentro do editor (VS Code e Cursor), feito para conduzir Spec-Driven Development (SDD) junto com uma IA. Você organiza o trabalho em histórias e sub-tarefas; a IA lê o board, produz os artefatos de cada fase e move os cards conforme avança.

Primeiros passos

Em cinco minutos você tem uma tarefa andando no board, com a IA trabalhando nela.

1. Instale e abra. Instale Faz AI Kanban no VS Code ou no Cursor (pelo marketplace da própria ferramenta), abra a pasta do seu projeto e clique no ícone Faz AI na barra lateral. Cada pasta tem o seu board, já com as fases do fluxo.
2. Conecte a IA ao board. Em Configurações → Harness de IA, escolha a ferramenta do projeto (Claude Code, Codex, Cursor, Kimi Code ou GitHub Copilot). Na aba Tudo que a ferramenta carrega, na ferramenta, clique em Instalar (padrão da ferramenta) na seção Servidores MCP e de novo na seção Skills, para a skill do fluxo, que ensina a IA a conduzir as fases.
3. Crie a tarefa. Na coluna Backlog, clique em + Novo card, escreva o título (por exemplo, "Login com Google") e dê Enter. Duplo clique abre o card: descreva o que você quer, em Markdown, e, se quiser, escolha o modelo da IA e as skills que ela deve ler.
4. Deixe a IA começar. Arraste o card para Discovery e clique em Trabalhar na fase no card. A IA lê o card pelo board, analisa o problema e conversa com você na aba Conversa. Quando termina, o status muda para Aguardando revisão: é a sua vez.
5. Revise e siga. Leia o documento da fase, responda ou clique em Aprovar (ou Pedir ajustes). Com a aprovação, a história avança para PRD, Spec, Plan e Implementação, sempre com a IA produzindo e você aprovando. As sub-tarefas da implementação nascem no workflow de baixo e a IA as conclui uma a uma.

Para o dia a dia: o contador N com você no topo mostra o que espera por você, o Chat deixa você pedir à IA, em linguagem natural, para criar e mover cards, e o heartbeat pode chamar a IA sozinho quando há pendência com ela.

Por que isso poupa contexto

A IA gasta contexto com o que carrega em toda sessão. O board existe para ela carregar só o necessário, na hora certa:

• Cada card é uma sessão nova e curta. Em vez de uma conversa longa que acumula tudo, a IA abre o card pelo board (get_card), faz aquele trabalho e para. O histórico fica no card, e não na janela de contexto.
• Skills só quando indicadas. Uma skill automática põe a descrição dela em toda sessão; marcada como Só quando indicada, ela só entra nos cards que a pedem. Em Harness de IA → Tudo que a ferramenta carrega, o board mostra quantas skills são automáticas e quantos caracteres de descrição elas colocam em toda sessão.
• Agentes que restringem. Um agente pode liberar só alguns servidores MCP e ferramentas, e a sessão limpa dispensa as personalizações da sua pasta de usuário: menos definições de ferramentas carregadas sem necessidade (o que o Claude Code e o Cursor impõem por parâmetro está na tabela de Agentes).
• Documentos como anexos. PRD, Spec e Plan ficam anexados à história; a IA os lê quando o card precisa, em vez de recebê-los colados em cada mensagem.
• Modelo certo para cada tarefa. Regras de sugestão e o modelo por card ou por agente evitam usar o modelo mais caro onde o mais leve basta.

A economia de contexto de skills sob demanda é documentada no Claude Code e no Cursor; nas outras ferramentas, a documentação diz só que a IA deixa de invocar a skill sozinha. O board não promete um percentual: ele mostra, no inventário, o que está sendo carregado.

Para que serve

• Planejar em fases. As colunas das histórias são as fases do fluxo: Backlog, Discovery, PRD, Spec, Plan, Implementação, Homologação, Concluído e Cancelado. Cada história se desdobra em sub-tarefas, que têm um fluxo próprio (A fazer, Em andamento, Concluído).
• Dizer à IA o que fazer em cada fase. Cada coluna tem uma instrução para a IA e, se a fase gera um documento (Discovery, PRD, Spec, Plan), o modelo desse documento. No Discovery a IA analisa o problema e conversa com você antes de qualquer requisito; na Homologação a história só é concluída com a sua aprovação.
• Trabalhar com a IA no mesmo quadro. A extensão expõe o board por MCP. Claude Code, Codex, Cursor, Kimi Code, GitHub Copilot ou outro cliente MCP podem consultar e editar tudo o que a interface permite, e as mudanças aparecem no board na hora.
• Saber com quem está cada card. Todo card em que a IA atua tem um status (Pronto, Em execução, Aguardando resposta, Aguardando revisão, Aprovado, Bloqueado) que mostra se a pendência está com você ou com a IA.
• Revisar antes de a IA avançar. Nas colunas que exigem aprovação (Discovery, PRD, Spec, Plan e Homologação, por padrão), a IA termina o trabalho, pede a revisão e para. Ela só move o card depois que você aprova.
• Ver o que espera por você. O filtro "Com você", o contador no ícone da barra lateral e um aviso do editor mostram quando a IA pede revisão, faz uma pergunta ou trava num impedimento. A IA, por sua vez, pergunta ao board o que está com ela.
• Dizer à IA como executar cada card. Cada card pode indicar o modelo, o nível de esforço e as skills obrigatórias. O modelo pode ser sugerido por regras a partir do tamanho da tarefa.
• Decidir antes o que a IA usa. Um agente define as skills, os servidores MCP, as ferramentas e o modelo de cada fase ou card, em vez de a ferramenta descobrir sozinha durante a conversa. Toda execução pelo board roda através de um agente.
• Ver e configurar o harness inteiro. Para cada ferramenta de IA instalada, o board mostra o que ela carrega (instruções, skills, subagentes, comandos, hooks, servidores MCP, plugins e configurações), separado entre o projeto, a sua pasta de usuário e os plugins.

Como usar

1. Abra uma pasta no editor e clique no ícone Faz AI na barra lateral. Cada pasta tem o seu board.
2. Crie histórias com + Novo card e arraste-as entre as colunas. Clicar numa história mostra só as sub-tarefas dela; duplo clique abre o detalhe.
3. No detalhe do card ficam o status, a descrição em Markdown, os campos, o checklist, as sub-tarefas, a conversa e os anexos. A conversa é o lugar em que você e a IA falam sobre o card. Os documentos das fases (PRD, Spec, Plan…) são construídos nas sub-tarefas, mas ficam anexados à história; nas sub-tarefas eles aparecem como links.
4. Busque por texto ou pelo ID (#12). A seção Filtros da barra lateral filtra por tipo, campos, datas e relacionamentos.
5. Cards podem ser arquivados (coluna "Arquivados" no fim de cada linha) ou enviados para a Lixeira, de onde podem ser restaurados.

Por padrão, uma história não é concluída nem avança de fase enquanto tiver sub-tarefas em aberto daquela fase. Essas regras podem ser desligadas nas configurações.

No topo do board, N com você mostra quantos cards esperam revisão, resposta ou desbloqueio (um clique filtra só eles), e um indicador aparece enquanto a IA trabalha em algum card.

Cada card tem uma barra na cor do tipo, com o ID, o tipo e os botões de abrir e de ações. Abaixo vêm o título (inteiro no tooltip, se não couber), o status com um ícone de com quem está a pendência (robô para a IA, pessoa para você) e há quanto tempo ele está assim, os campos, o modelo de IA (ex.: "Sonnet 5.5 - baixo") e, no rodapé, os contadores, a branch e o PR. Cards com pendência sua ganham a borda na cor do status, e o LED da barra diz o estado do card de relance: verde piscando devagar enquanto a IA trabalha nele (na história, também quando ela trabalha numa sub-tarefa), amarelo quando ele espera por você, vermelho quando está bloqueado e apagado quando não há nada acontecendo.

Vínculos entre cards

Além das sub-tarefas, qualquer card pode ser vinculado a outro, de qualquer workflow, em Vínculos no card aberto (como em Kanbanize ou Businessmap): pai, filho ou relativo. Busque o outro card pelo número ou título e escolha o tipo do vínculo. O rodapé do card no board mostra o vínculo e, se há filhos, quantos já estão encerrados. O vínculo repetido e o que fecharia um ciclo (o pai já ser filho do card) são recusados.

Um pai vinculado segue a regra de Configurações → Regras: quando o último filho em aberto entra numa coluna de conclusão, o board pergunta (ou move sozinho, conforme a regra) se o pai também vai para a conclusão. A IA usa as ferramentas link_cards e unlink_cards, e o get_card devolve os vínculos.

A seção Vínculos também mostra, só para exibição, a relação de sub-tarefa: numa sub-tarefa, um grupo "Pai" com a história; numa história, a contagem de sub-tarefas com um atalho até a seção Sub-tarefas. Essa relação é somente leitura (sem botão de remover) e não entra na regra de conclusão acima, que continua valendo só para o vínculo manual de pai/filho.

Dependência e sub-tarefas em paralelo

Um card pode depender de outro: em Vínculos, escolha "precisa terminar antes deste card" (o outro é pré-requisito) ou "só começa depois deste card". O card aberto mostra os grupos Depende de (com quantas dependências ainda estão em aberto) e Libera. O board recusa ciclo de dependência.

A IA usa isso para acelerar a Implementação. No Plan ela declara a ordem entre as sub-tarefas (create_card com depends_on, ou link_cards com depends_on): uma depende da outra quando usa o que ela produz ou quando as duas alteram os mesmos arquivos. Na Implementação, o get_card da história devolve em subtasksNow o que pode rodar agora, e a IA delega as sub-tarefas sem dependência pendente a subagentes simultâneos, cada um com o modelo do seu card; ao fim da rodada ela verifica o conjunto, faz o commit e parte para a rodada seguinte. start_work recusa a sub-tarefa que ainda espera outra. Sem dependências declaradas, todas as sub-tarefas em aberto são consideradas independentes. Depende de a ferramenta de IA ter subagentes (o Claude Code tem); sem eles, a execução segue uma por vez, na ordem das dependências. Projetos que já tinham a skill do fluxo instalada continuam com o texto antigo dela (o board não sobrescreve uma skill que você pode ter ajustado): apague-a e instale de novo em Configurações para receber a instrução nova.

Board no navegador, fora do editor

O board não depende da janela do editor:

• Abrir no navegador (no topo do board, ou o comando Faz AI: Abrir board no navegador) abre o mesmo board numa aba do navegador. O editor continua aberto e é ele que guarda o board; as duas telas ficam sincronizadas.
• Sem o editor: rode ~/.faz-ai/bin/faz-ai na pasta do projeto (ou faz-ai <pasta>). O comando serve o board no navegador, com o servidor MCP, a execução da IA e o heartbeat, e fica rodando até você encerrar com Ctrl+C. O atalho é criado pela extensão e usa os mesmos dados dela; precisa do Node.js no PATH. Para chamar só faz-ai, ponha ~/.faz-ai/bin no PATH. faz-ai --help lista as opções (--port, --data, --no-open).

A página só responde em 127.0.0.1 e exige o segredo que vem no link aberto pelo editor ou pelo terminal (ele fica guardado num cookie, então o endereço pode ir para os favoritos). O tema "Sistema" acompanha o claro ou escuro do VS Code no editor e o do sistema operacional no navegador, sempre com as cores do próprio board. No navegador, os filtros abrem na própria barra do board. Um board é servido por um lugar de cada vez: com o editor aberto na pasta, use Abrir no navegador; o faz-ai do terminal avisa e não inicia.

Usando com IA

1. Em Configurações → Harness de IA, escolha a ferramenta do projeto (Claude Code, Codex, Cursor, Kimi Code ou GitHub Copilot).
2. Na aba Tudo que a ferramenta carrega, escolha a ferramenta e, na seção Servidores MCP, clique em Instalar (padrão da ferramenta). O board registra o servidor faz-ai no arquivo global que a ferramenta lê.
3. Na seção Skills da mesma ferramenta, clique em Instalar (padrão da ferramenta) para a skill do fluxo (faz-ai-fluxo): ela ensina a IA a conduzir os cards pelas fases, gerar os documentos, pedir revisão e retomar pendências. Pode ser editada.

Global ou neste projeto. Os dois itens ficam só na seção do tipo, em cada ferramenta, cada um com dois botões:

O registro global não leva a pasta do projeto: a ponte do board acha o board subindo a partir da pasta em que a ferramenta foi aberta. O do projeto vale sobre o global naquele projeto, então instalar no projeto com um global já instalado pede confirmação, assim como substituir uma skill do fluxo que já existe no destino (o que foi ajustado nela se perde). O comando Faz AI: Instalar o MCP do board (global) da paleta faz a instalação padrão na ferramenta do projeto, e a ferramenta install_flow_skill do MCP aceita scope (user, o padrão, ou project). 4. Abra uma sessão nova da ferramenta na pasta do projeto e peça, por exemplo, "liste os cards do board", "pegue a história #1 e escreva o PRD" ou "veja o que está pendente no board e dê andamento".

Enquanto faltar alguma coisa para o board trabalhar com a ferramenta, uma faixa amarela fica no topo do board, em todas as telas, e no painel de chat. Ela confere o Node.js (o servidor do board roda com ele), a linha de comando da ferramenta, o login dela (no Cursor, por cursor-agent status), o registro do servidor do board no arquivo que a ferramenta lê (no Claude, vale também o registro para o seu usuário, de claude mcp add -s user), um registro apontando para um node ou um caminho que não existe mais ou para outra pasta, e o nível de permissão. Cada item diz o efeito e traz a ação: o comando para copiar, Instalar o MCP do board (abre a seção Servidores MCP da ferramenta) ou o atalho para o Harness de IA. A faixa não fecha: some sozinha quando o último item é resolvido. A conferência roda ao abrir o board, quando a ferramenta ou a permissão mudam, depois de conectar, a cada 5 minutos e em Verificar de novo, que relê também o PATH do terminal (um node instalado com o board aberto é encontrado sem recarregar a janela), e diz quando nada mudou.

No Claude e no Cursor, o servidor do board não registrado aparece como recomendado, fora da contagem: as execuções pelo board levam o servidor sozinhas, e o registro só falta para a IA enxergar o board nas suas conversas fora dele. Sozinho, esse item vira uma linha discreta em vez da faixa. Enquanto a linha de comando falta ou está sem login, os botões de IA do card ficam desligados, com o motivo na dica.

Fluxo sugerido: a IA lê a história e a instrução da fase, cria uma sub-tarefa para construir o documento da fase, anexa o documento à história e pede a revisão pela conversa do card. Você responde no próprio card:

• Aprovar deixa o card Aprovado, e a IA o leva para a próxima coluna.
• Pedir ajustes devolve o card para a IA com o seu texto na conversa.
• Se a IA fizer uma pergunta, o card fica Aguardando resposta; ao responder na conversa, ele volta para a IA.
• Bloquear registra um impedimento, com o motivo.

Chat com a IA

Para dar ordens ao board em linguagem natural, use o Chat: na barra lateral do editor, a seção Chat com a IA (abaixo de Board e Filtros); no navegador, o botão Chat do topo, que abre um painel à direita. Escreva, por exemplo, "crie uma história Login com Google e três sub-tarefas" ou "o que está esperando por mim?". A IA do projeto responde e age pelas ferramentas do board: cria, move e vincula cards, e consulta o que há nele. Abaixo do campo você escolhe o modelo e o esforço das próximas mensagens (a escolha fica lembrada). Enter envia, Shift+Enter quebra a linha, Parar interrompe e Limpar apaga a conversa. O histórico fica guardado por projeto.

O chat usa a mesma execução em segundo plano dos cards, então vale o limite de Configurações → Harness de IA → "O que a IA pode fazer" (por padrão, só o board) e o tempo limite de lá.

Trabalhar na fase e Refinar com IA

O card tem dois botões que chamam a ferramenta do projeto em segundo plano. Não é um chat ao vivo: a resposta chega como mensagem na conversa quando a execução termina, e enquanto isso o card fica "Em execução" (com um botão Parar).

• Trabalhar na fase faz o trabalho da coluna em que o card está, o mesmo que o heartbeat faria: em Discovery analisa o problema, em PRD escreve o PRD, em Implementação escreve o código (se a permissão deixar). Lê a conversa e responde a ela, e termina passando a vez: pede revisão, faz uma pergunta, bloqueia ou move o card. Se Tags, Esforço da atividade, Modelo e Skills estiverem todos vazios, ela os preenche antes. Fica no cabeçalho do card e na conversa (com texto escrito, Enviar e trabalhar na fase manda a mensagem antes).
• Refinar com IA só deixa o card claro e completo para quem vai trabalhar nele: reescreve título e descrição (sem inventar requisito; o que estiver ambíguo vira uma lista "Dúvidas em aberto"), revisa Tags, Esforço da atividade, Modelo e Skills mesmo que já tenham valor e acrescenta ao checklist os passos que faltam. Não trabalha a fase, não cria sub-tarefas, não move o card e não mexe em arquivos: roda só com o board (no Kimi, que não tem esse nível, o pedido proíbe mexer em arquivos). No fim, resume na conversa o que mudou (com o texto anterior da descrição, se a reescreveu) e o card volta ao status que tinha, também quando a execução falha: a falha fica na conversa, sem bloquear o card. Um refino não conta como execução sem progresso para o modo autônomo.

Imagens coladas na mensagem viram anexos do card e a IA as recebe.

• O que a IA pode fazer nessas execuções se define em Configurações → Harness de IA → Execução pela conversa: só o board (padrão), board e arquivos do projeto, ou sem restrições. O nível em uso aparece ao lado do botão, com um atalho para mudar. A IA é avisada do limite: se o trabalho pedir mais do que o nível permite, ela bloqueia o card dizendo qual opção escolher.
• O Kimi Code, quando roda em segundo plano, só funciona no nível "sem restrições". O Cursor aceita os três: em "só o board" e "board e arquivos" a sessão dele recebe só as ferramentas do nível (leitura e MCP; leitura, MCP e edição), sem terminal.
• A ferramenta precisa estar instalada e autenticada. A CLI não precisa estar no PATH: o board a procura também nas pastas de instalação usuais e dentro das extensões do editor (quem só usa a extensão do Claude Code ou do Codex já tem o executável). A do Cursor é a cursor-agent (o instalador de curl https://cursor.com/install -fsS | bash cria também o atalho agent); entre na conta uma vez com cursor-agent login.
• Com o Claude Code, o servidor do board vai na linha de comando de cada execução: não depende de instalar o MCP nem da aprovação do .mcp.json. Com o Cursor, o board usa o registro global do ~/.cursor/mcp.json quando ele leva a este board; sem ele (ou numa worktree fora da pasta do projeto), grava o servidor no .cursor/mcp.json antes de rodar (e põe o arquivo no .git/info/exclude quando o cria). Nas outras ferramentas, instale antes.
• Quando a história tem pasta de trabalho própria (worktree), a ferramenta recebe essa pasta junto com a do projeto, inclusive o Cursor.
• Parar e o tempo limite encerram a ferramenta e tudo o que ela iniciou (servidores MCP, testes, comandos). O Claude Code não roda "sem restrições" como root (contêineres, WSL como root): o board avisa. Sem Node.js no PATH, o servidor do board roda com o runtime do próprio editor.
• Se a execução falhar ou passar do tempo limite, o card fica Bloqueado com o motivo e o fim da saída da ferramenta. O log completo está no painel Saída → Faz AI (ou no terminal do faz-ai).

Consumo, custo e inventário de cada execução

Cada vez que a IA roda (pela conversa, pelo heartbeat ou pelo modo autônomo), o board registra no banco o que a execução consumiu: tokens de entrada, de saída, de leitura de cache e de criação de cache, o custo em dólar, o número de turnos e o id da sessão da ferramenta. Registra também o inventário do que a IA usou: ferramentas nativas, ferramentas de MCP (com o servidor de cada uma), subagentes e skills, com a contagem de chamadas.

• O custo vem de duas fontes. Quando a ferramenta informa o custo, o board grava esse valor. Quando não informa, ele estima: multiplica os tokens pelo preço por milhão de tokens do modelo, que você preenche em Configurações → Modelos de IA (os quatro preços: entrada, saída, leitura e criação de cache) ou pelo MCP com upsert_model. O custo estimado vem sempre marcado como "(estimado)". Modelo sem os quatro preços não tem custo calculado: o valor fica em branco, nunca 0.
• No canal de log (Saída → Faz AI), a saída da ferramenta aparece em linhas legíveis, e no fim de cada execução vem uma linha de resumo com entrada, saída, leitura e criação de cache, turnos e custo, por exemplo Consumo: 1.250 entrada · 3.400 saída · 52.000 leitura de cache · 9.100 criação de cache · 8 turnos · US$ 0,4210 (estimado). Turnos e custo ficam de fora quando a ferramenta não os informa.
• O Copilot fica sem consumo medido. Ele não tem saída estruturada, então as execuções dele são registradas, mas sem tokens, custo nem inventário. Onde aparecer "não medido", é isso: falta de medição, não consumo zero. O mesmo vale para execuções que terminam antes de a ferramenta informar o consumo.
• Perguntas no chat do board também entram no registro, sem card associado.
• O detalhe de cada execução é guardado por uma janela que você configura, de 1 a 24 meses (o mês corrente mais os anteriores). O padrão é 6 meses. Depois da janela o detalhe é descartado, mas os totais por mês nunca expiram. Antes o prazo era 12 meses; o padrão menor mantém o arquivo do banco dentro do limite de tamanho. Onde ajustar, e o que acontece ao baixar a janela, está em Painel de métricas, logo abaixo.

Painel de métricas

O botão Métricas, o quarto da navegação do topo (Board, Métricas, Lixeira, Configurações), mostra o que o board registrou sobre o trabalho e o uso da IA. Funciona no editor e também no board aberto pelo navegador.

• Filtros. O período pode ser Hoje, 7 dias, 30 dias, Este mês, Últimos 12 meses, Tudo ou um Intervalo livre (data inicial e final). O filtro Workflow restringe os números a um workflow, e Limpar filtros volta ao padrão. Abaixo dos controles o painel escreve o período consultado.
• Cinco totais. Atividades concluídas (cards que chegaram a uma coluna de conclusão), execuções de IA, tokens, custo e tempo de IA. O tempo de IA é a soma da duração de cada execução: execuções simultâneas somam, então o total pode passar do tempo decorrido no relógio. O que não foi medido aparece como "não medido", nunca como 0, e quando só parte das execuções foi medida o aviso diz quantas ficaram de fora.
• Custo e tokens por mês. Gráfico de barras, uma série por vez (alternador Custo / Tokens). O mês em andamento aparece com hachura, porque ainda não terminou; um mês sem nenhum dado é um espaço marcado "sem dado", não uma barra de altura zero. Abaixo do gráfico fica uma tabela com os mesmos números e uma coluna de observação (parcial, sem dado, só total mensal).
• Onde o consumo aconteceu. O consumo do período repartido por fase, tipo de card, modelo, ferramenta de IA, esforço ou perfil (seletor Recortar por), em barras horizontais na medida escolhida em Medida da barra: custo, tokens, execuções ou tempo de IA. Ao lado fica a tabela com as quatro medidas. As categorias além do limite somam numa linha "outros". Alcança a série inteira do período, inclusive os meses já arquivados.
• Quanto tempo o card fica na fase. Uma linha por fase com as permanências, a mediana, a média, as desconhecidas e quantos cards estão nela agora. São permanências, não cards: um card que volta para a fase conta duas vezes. É tempo de relógio, diferente do tempo de IA do corte por fase.
• Lead time. Da criação do card até a primeira conclusão, dos cards concluídos no período: a mediana em destaque, a média, quantos entraram na conta, quantos ficaram desconhecidos e a lista por card, ordenável. Desconhecido é o card cuja data de criação não está no detalhe guardado (o mês foi descartado ou o card é anterior ao log); a data não é estimada.
• Fases mais caras e Cards mais caros. Dois rankings lado a lado, em tabelas que você ordena por custo, tokens, execuções ou tempo de IA clicando no cabeçalho (ou com Enter/Espaço). O padrão é o custo quando o período tem custo medido e o tempo de IA quando não tem, e a tela escreve o critério em vigor. As fases alcançam a série inteira; os cards, só o detalhe guardado, e cada bloco avisa isso.
• O que a IA usou. Ferramentas, ferramentas de MCP (com o servidor em coluna própria), subagentes e skills, com o número de execuções e de usos. "Ainda não medido" (nenhuma execução gravou inventário) é diferente de "nenhum registro no período".
• Tokens e custo. Tokens contam mesmo quando o modelo não tem preço configurado; o custo soma só as execuções que têm preço, e o aviso diz quantas ficaram de fora. Antes de o board medir consumo, custo e inventário aparecem como "não medido" e quase todo lead time como desconhecido: é o comportamento esperado, não falha.
• Detalhe guardado. Mostra a janela de retenção do detalhe das execuções e quanto espaço ela ocupa. Dá para configurá-la de 1 a 24 meses (padrão 6). Aumentar grava na hora. Baixar pede confirmação, que diz quantos meses perdem o detalhe, e o descarte só acontece na próxima abertura do board. Os totais por mês continuam. O campo grava ao pressionar Enter ou ao sair dele. Os tempos e o inventário leem só o detalhe guardado: um mês descartado sai desses blocos.
• Avisos de honestidade, sempre junto do número: desde quando o log do board existe (antes disso não há dado, o número não está pequeno); o aviso de que o período pedido foi cortado no início do log; e os meses que só têm o total mensal (entram na série, mas sem corte por dimensão nem detalhe por card). Com um workflow filtrado, um mês consolidado antes de o log guardar o workflow fica de fora dos números, e o aviso diz isso.

Métricas de uso com get_metrics

Durante a conversa de um card, a IA pode consultar estatísticas agregadas do histórico do board — uso, duração e custo de execuções — sem precisar abrir nenhum painel. Chame a ferramenta get_metrics em linguagem natural: "quanto tempo de IA o card #72 consumiu?", "qual tipo de card consome mais este mês?", "qual agente foi usado mais?". A ferramenta responde em uma tabela compacta, otimizada para economizar tokens.

• A agregação pode agrupar por fase (phase), tipo de card (card_type), ferramenta de IA (tool), modelo (model), esforço (effort), perfil (profile), card (card), agente (agent), skill (skill), ferramenta usada (used_tool) ou ferramenta de MCP (mcp_tool). Omita para obter apenas o total do período.
• tool e used_tool não são a mesma coisa: tool é a ferramenta de IA que rodou (claude, codex); used_tool e mcp_tool são o que a execução usou (Read, Bash, get_card). Em mcp_tool o servidor vem numa coluna própria, ou "servidor não registrado" quando o nome não o trouxe.
• Filtros de período (data inicial e final, em AAAA-MM-DD), card (ex. 72 ou #72), e dimensões (ex. fase, modelo, tipo de card).
• Nas dimensões agent, skill, used_tool e mcp_tool a tabela mostra só a contagem de execuções e de usos (sem tokens nem custo, que não é possível repartir entre componentes de uma execução). effort e profile têm tokens e custo.
• Tokens contam mesmo sem preço configurado para o modelo; o custo vem só das execuções que têm preço.
• Os tempos do painel (permanência por fase e lead time) não estão no get_metrics.
• Valores não medidos aparecem como "-" (nunca 0), por exemplo as execuções do Copilot. Custo estimado a partir do preço do modelo vem marcado como estimado.
• Sempre informa desde quando o histórico do board existe e quais períodos têm apenas totais mensais (sem detalhe por execução). Períodos fora da janela de retenção (6 meses por padrão) não têm detalhe e só agregam os totais já consolidados.

Branch e pasta de trabalho por história

Cada história trabalha numa branch própria, criada pelo board (ex.: historia/12-login-com-google). Por padrão ela vem com uma worktree: uma pasta de trabalho separada, ao lado do projeto, onde a IA altera o código sem tocar na sua pasta nem nas suas alterações em andamento. As sub-tarefas fazem commits na branch da história.

• A branch é criada quando a IA começa a implementação (ela chama prepare_workspace) ou pelo botão Criar branch da história no card.
• O card mostra a branch e abre a pasta de trabalho numa janela nova.
• Em Configurações → Git ficam o modo (worktree, branch na própria pasta ou desligado), o padrão do nome da branch, a pasta das worktrees, o merge automático do PR ao aprovar a homologação e a detecção automática de merges, com o arquivamento das histórias já publicadas (ligada por padrão).
• Cada worktree é uma cópia de trabalho: as dependências precisam ser instaladas nela.

Pull request e merge na Homologação

Na Homologação a IA envia a branch, abre o pull request da história, registra o endereço no card e pede a sua revisão. O card mostra o link do PR.

O merge automático é opcional e começa desligado (Configurações → Git). Com ele ligado, quando você aprova uma história que está na última coluna antes da conclusão:

1. o board faz o merge do PR pelo GitHub CLI (gh), no tipo configurado (squash, merge ou rebase);
2. só com o merge feito o card vai para Concluído, e a pasta de trabalho da história é removida;
3. se o merge falhar (conflito, checks obrigatórios, sem acesso), o card fica Bloqueado com o erro e continua na Homologação.

O merge não acontece se a história não tiver PR registrado ou ainda tiver sub-tarefas em aberto. Com o merge automático desligado, aprovar só marca o card, e a IA o move para Concluído.

Detecção automática de merges

O board pode observar o pull request de uma história entregue e detectar quando ele é mergeado, concluindo a história automaticamente. A opção nasce ligada (Configurações → Git, Concluir a história quando o pull request for mergeado). Uma rotina periódica verifica o estado do PR a cada intervalo configurável (Verificar a cada (minutos), padrão 15, faixa de 5 a 1440). Quando o merge é detectado:

1. o board grava o commit do merge no card;
2. registra na conversa que a história foi concluída;
3. move o card para Concluído e remove a pasta de trabalho.

Se o pull request é fechado sem merge, o board registra um aviso na conversa uma única vez. O merge continua sendo feito pela pessoa, manualmente ou pelo merge automático; o board só observa. Falhas na consulta do estado do PR (sem rede, sem autenticação, sem o gh instalado) não bloqueiam nada — o aviso aparece no log, e a rotina continua tentando no próximo intervalo.

Na mesma rodada, depois de olhar os pull requests, o board dá o último passo do ciclo: quando a versão que contém uma história concluída é publicada, ele registra na conversa qual versão a levou (tag e link da release) e arquiva o card. Assim a coluna Concluído fica só com o que está mergeado e ainda não chegou a quem usa; o que já foi entregue vai para os arquivados do workflow, de onde você pode desarquivar a qualquer momento. Não há o que ligar: o passo vem junto com a detecção de merges, no mesmo intervalo e no mesmo liga/desliga, e nasce ligado com ela.

Uma história conta como publicada quando existe uma tag que contém o commit do merge e que tem uma release publicada no GitHub — é o que o npm run release deste projeto cria. Tag sem release não vale, release em rascunho não vale, pré-lançamento vale. A versão registrada é a mais antiga entre as que contêm o commit, pela data de publicação. O critério é conservador de propósito: arquivar tarde se corrige na rodada seguinte, arquivar cedo esconde um card sem ninguém notar.

Tudo aqui é melhor esforço. Projeto sem releases, fora do GitHub ou numa máquina sem o gh simplesmente não arquiva nada: nenhum card é bloqueado e o motivo aparece uma vez no log. O board nunca publica versão — ele só lê o que você publicou — e histórias concluídas antes desta versão, que não têm o commit do merge guardado, continuam sendo arquivadas por você, com um clique.

Heartbeat

Com o heartbeat ligado (Configurações → Harness de IA), o board chama a IA sozinho a cada intervalo, enquanto o editor estiver aberto na pasta do projeto. Em cada rodada ela avança os cards aprovados, responde às mensagens pendentes e trabalha nos cards prontos, uma história por vez. No modo "Worktree por história", Tocar histórias em paralelo (na mesma tela; nasce desligado) faz o heartbeat tocar várias histórias ao mesmo tempo, cada uma na sua pasta de trabalho: duas por padrão, até seis em Histórias ao mesmo tempo; o limite conta toda execução em andamento, inclusive as chamadas à mão. Fora desse modo, e no modo autônomo (cujas histórias são empilhadas), continua uma por vez, e o campo fica desligado. A tela de Git explica o motivo em cada modo: com branch na própria pasta, duas histórias ao mesmo tempo trocariam a branch uma debaixo da outra e misturariam alterações; com worktree elas ficam isoladas, ao custo de mais uma cópia dos arquivos em disco por história (com as dependências instaladas em cada uma) e de mais memória e processador enquanto várias sessões de IA, testes e builds rodam juntos.

• Sem pendência com a IA, nada é executado.
• A fila da rodada segue a ordem do board: os bugs primeiro e, depois, de cima para baixo — o que decide é a posição do card, não o número dele nem o que já foi aprovado.
• Cards que estão com você (aguardando revisão ou resposta, bloqueados) não são tocados, a menos que você tenha deixado uma mensagem sem resposta na conversa.
• Rodar o heartbeat agora (nas configurações ou pelo comando Faz AI: Rodar o heartbeat agora) começa uma rodada na hora, mesmo com o heartbeat desligado. Faz AI: Parar as execuções da IA e o modo autônomo interrompe tudo.
• A barra de status mostra os cards em execução e a hora da próxima rodada.
• O coração no topo direito do board mostra o heartbeat: vermelho e batendo quando ele está rodando; cinza e parado quando está desligado ou não consegue rodar (sem ligação com o Faz AI ou sem a ferramenta). Clicar nele liga e desliga o heartbeat.
• As execuções usam a mesma permissão e o mesmo tempo limite do botão "Trabalhar na fase".

Quais colunas exigem aprovação, e em quais a IA atua, se define em Configurações → Workflows e colunas. Você mesmo pode mover qualquer card sem aprovação.

Modo autônomo (YOLO)

Uma história pode ser marcada como YOLO: no painel do card, ligue Modo autônomo (o board pede uma confirmação, porque o modo abre mão de toda aprovação). A partir daí a IA toca a história sozinha, sem pedir autorização nem confirmação para nada:

• Do Backlog até a última coluna em que a IA atua (Homologação, no board padrão): ela faz o Discovery, o PRD, a Spec e o Plan, cria as sub-tarefas, implementa uma por uma e, nessa última coluna, abre o pull request, registra com set_pull_request e para ali — a história fica aguardando a sua revisão. As colunas que exigem aprovação deixam de segurar o card, e o pedido de revisão da IA vira aprovação na hora, com o resumo registrado na conversa.
• Sem perguntas: a IA não usa ask_question; diante de uma dúvida ela decide e registra a decisão e o motivo na conversa. Só um impedimento real (acesso, ambiente, falha que ela não resolve) bloqueia o card.
• Sem merge: a IA para na última coluna em que atua, com o pull request aberto; o merge e o avanço até Concluído continuam sendo seus. Concluído quer dizer mergeado.
• Sem restrições: nas execuções do modo, a IA roda com a permissão "Sem restrições" (altera arquivos e roda comandos), porque precisa de git e do gh. Ligar o modo é aceitar isso para a história.
• Em fila e em pilha: o autopiloto toca as histórias em modo autônomo uma de cada vez, na ordem do board — bugs na frente, depois de cima para baixo —, e segue para a próxima história da fila assim que a atual é entregue (parada na última coluna da IA, com o pull request registrado), sem esperar a sua revisão nem o intervalo do heartbeat. A branch de cada história parte da branch da história de número anterior que já tem branch, e o pull request é aberto com --base nela, formando uma pilha de PRs; quando a ordem do board faz uma história rodar antes de outra de número menor, a branch dela parte da principal e o pull request sai solto, fora da pilha.
• Dividir um pedido grande: a IA pode criar as histórias seguintes a partir de uma história em modo autônomo (create_card com autonomous_from). Elas nascem em modo autônomo, entram na fila e ganham um vínculo relativo com a história de origem (pulado em silêncio se já existir qualquer vínculo entre as duas). Ela nunca liga o modo numa história que você não ligou.
• Freios: o autopiloto para quando a IA bloqueia o card ou quando uma execução falha (o card fica Bloqueado, com o motivo) e bloqueia a história depois de 3 execuções seguidas que não avançaram nada. Ao destravar o card, ele continua sozinho.

O botão do modo autônomo no topo do board aparece enquanto houver história na fila e diz o que o clique faz: Pausar modo autônomo (aceso, com o autopiloto tocando; pausar interrompe a IA) ou Retomar modo autônomo (apagado, pausado). Pelo editor: Faz AI: Pausar o modo autônomo (YOLO), Faz AI: Retomar o modo autônomo (YOLO) e Faz AI: Parar as execuções da IA e o modo autônomo. Ao abrir o editor, o autopiloto não começa sozinho: ele liga quando você ativa o modo numa história ou retoma. O heartbeat não toca histórias em modo autônomo; elas são do autopiloto.

Agentes

Um agente (Configurações → Agentes) diz como a IA trabalha num card: que skills ela lê, a que servidores MCP e ferramentas (disponíveis e negadas) tem acesso, que modelo e esforço usa e se a sessão é limpa (sem as personalizações da sua pasta de usuário e sem invocação automática de skills). Toda execução pelo board roda através de um agente: o escolhido no card; senão, o da fase (Workflows e colunas → Fase); senão, o padrão do board. O board sempre tem ao menos um, o Agente padrão, que não restringe nada.

Para configurar sem ter de conhecer cada skill ou ferramenta:

• O que este agente faz: uma frase de intenção. Com ela, o botão Sugerir pela intenção marca as skills (e os servidores MCP) cujo nome ou descrição combinam. A sugestão é por palavras, local e sem chamar IA; você confirma o que fica.
• Skills: a mesma janela de escolha do card, com busca, abas por origem e caixa de seleção.
• Ferramentas: conjuntos prontos (Só leitura, Editar código) e a lista editável.
• Subagente da ferramenta: opcional, um arquivo de agente da própria ferramenta (por exemplo, .claude/agents/revisor.md) para conduzir a sessão.

Cada execução pelo board ("Trabalhar na fase", "Refinar com IA" e heartbeat) é uma sessão nova, só com o que está no card. O agente vira parâmetros da linha de comando onde a ferramenta aceita; o resto segue no prompt, como instrução:

As skills vão sempre pelo caminho do arquivo. Numa conversa aberta por você, o agente chega à IA pelo get_card, como orientação.

Harness de IA

Em Configurações → Harness de IA fica tudo que as ferramentas de IA carregam, em três abas: Ferramenta e execução (a IA do projeto e como o board a chama), Do projeto (o arquivo de regras, as skills e os agentes que fazem parte do repositório, editáveis ali) e Tudo que a ferramenta carrega. Nesta última, em Tudo que cada ferramenta carrega, há uma aba por ferramenta com oito seções (instruções e regras, skills, subagentes, comandos e prompts, hooks, servidores MCP, plugins, configurações e permissões), cada uma dividida em três escopos:

• Projeto: arquivos desta pasta; valem só aqui e vão no repositório. Esse grupo aparece sempre, em destaque, e diz quando o projeto não tem nada daquele tipo.
• Global: arquivos da sua pasta de usuário (~/.claude, ~/.codex, ~/.copilot…); valem em todos os seus projetos. Toda alteração neles pede confirmação.
• Plugins: vêm de pacotes instalados; não são alterados pelo board, mas podem ser copiados.

O que dá para fazer:

• Ler a lista sem esforço. Cada item mostra o nome, a descrição como dica (limitada a duas linhas) e, numa linha própria, o caminho do arquivo por inteiro. Clicar no caminho abre o arquivo no editor, onde ele também é editado.
• Agir em vários de uma vez. Cada linha tem uma caixa de seleção, e a do cabeçalho marca o grupo todo. Com itens marcados aparece uma barra: deixar as skills automáticas ou só quando indicadas, copiar para o projeto ou para o global, e apagar, sempre com confirmação.
• Criar um item no lugar e no formato que a ferramenta espera, apagar, e copiar skills, subagentes, comandos e regras do global ou de um plugin para o projeto (e do projeto para o global).
• Servidores MCP: acrescentar e remover, no formato de cada arquivo.
• Hooks e permissões: acrescentar e remover hooks e regras de permitir, perguntar e negar.
• Buscar e instalar skills de uma pasta ou de um repositório git: o board lista as skills encontradas e copia só as que você escolher. Nada do repositório é executado.

Skills sob demanda

Cada skill tem um modo:

• Automática: a IA vê a descrição em toda sessão e decide quando usar.
• Só quando indicada: a IA não a invoca sozinha; vale quando um card a indica ou quando é chamada pelo nome.
• Desligada (só no projeto): a ferramenta não a enxerga, mas um card ainda pode indicá-la.

O campo "Skills" do card mostra um resumo do que está marcado e abre uma janela para escolher: busca por nome ou descrição, abas Todas / Marcadas / Projeto / Globais / Plugins e uma caixa de seleção por skill, com a origem à vista. Funciona com centenas de skills. O card entrega à IA o caminho do arquivo de cada skill, então ela não precisa estar à vista da ferramenta para ser usada. Assim dá para ter muitas skills disponíveis sem ocupar o contexto de toda sessão. A economia de contexto é documentada no Claude Code e no Cursor; nas outras ferramentas, a documentação diz só que a IA deixa de invocar a skill sozinha.

Para não marcar skills card a card, escolha-as no tipo: em Configurações → Tipos de card → Padrões por tipo, as skills do campo "Skills" (e o modelo) ficam preenchidas em todo card novo daquele tipo. Cada card ainda pode mudá-las.

Modelos e referências

Modelos de classe e exemplos de código ficam dentro da pasta da skill (references/, assets/, scripts/). O botão Arquivos de cada skill lista, cria e apaga esses arquivos, e Criar skill de modelos cria no projeto uma skill própria para eles. O card que indica a skill recebe os caminhos dos arquivos de apoio.

O editor precisa estar aberto na pasta do projeto para a IA alcançar o board. O registro manual, os formatos de cada ferramenta e a solução de problemas estão em docs/mcp.md.

Configurações

Sobre os modelos: Detectar modelos lê a lista da ferramenta (no Kimi Code, da configuração local; no Cursor, dos modelos da sua conta, pelo comando cursor-agent models, lido ao abrir o board com a CLI autenticada, e a primeira lista lida substitui a embutida uma vez só; nas outras, uma lista embutida que pode ser editada); os preços que você preencheu continuam lá depois de detectar de novo. No Cursor, a lista traz uma linha por nível de cada modelo (claude-opus-5-5-low, -medium, -high…); o board junta as variantes num modelo com os níveis dele. As versões rápidas (-fast, respondem mais depressa e cobram mais pelos mesmos tokens) ficam de fora até você ligar Incluir os modos rápidos no cartão do Cursor: aí cada uma entra como um modelo à parte ("Claude Opus 5.5 1M Fast"), com preço próprio, só para os modelos que estão no catálogo; desligar a chave as tira do catálogo. Pelo MCP, é a regra includeFastModels do update_rules. No plano gratuito do Cursor só o Auto roda: os outros modelos são recusados antes de começar (o card bloqueado explica como escolher Auto), e por isso as regras de sugestão do Cursor começam todas em Auto. As regras de sugestão combinam condições com E e OU, por exemplo Esforço da atividade = Alto E Tags = backend. O resultado é sempre uma sugestão: no card, o modelo e o esforço podem ser trocados a qualquer momento.

Quando uma versão nova da extensão muda o board padrão, o board pergunta se você quer atualizá-lo (ou use Faz AI: Atualizar board para o padrão atual). A atualização só acrescenta o que falta: nenhum card sai do lugar e o que você personalizou é mantido. Uma cópia do banco é gravada antes.

Preços do Cursor

A referência é a tabela de preços do Cursor. O board não a consulta sozinho: os preços são mantidos à mão em Modelos de IA ou pela IA com upsert_model.

• Auto tem preço variável. O Cursor cobra o preço de lista do modelo para o qual cada pedido foi roteado, então não há tarifa fixa para cadastrar. O modelo auto já vem com Preço variável ligado: os campos de preço dão lugar a um aviso, e a execução fica sem custo estimado (em branco, nunca um número inventado). A chave existe em todo modelo; pelo MCP, é o variable_price do upsert_model.
• Tarifa do Cursor (Cursor Token Rate). Nos planos Teams e Enterprise, o Cursor cobra US$ 0,25 por milhão de tokens (entrada, saída e cache) por cima do preço dos modelos de terceiros; os modelos do próprio Cursor (Composer e Grok) são isentos. Ligue Somar a tarifa do Cursor no cartão do Cursor (pelo MCP, cursorTokenRate no update_rules) e a estimativa passa a somá-la. Vale para as execuções seguintes: o custo das já registradas não muda.
• Modo rápido e contexto longo. O modo rápido costuma custar 2x e entra como um modelo à parte, com preço próprio (ver Incluir os modos rápidos acima). O contexto longo (mais de 256 mil tokens) pode custar 2x, e 3x junto com o modo rápido, mas não é separado: o Cursor só informa o total de tokens da execução, e a estimativa usa a tarifa cadastrada.
• Como os nomes se correspondem. O identificador na ferramenta é o id que cursor-agent models lista (claude-opus-5-5); o nome é o da linha na tabela de preços; no board o modelo fica como cursor:claude-opus-5-5, e cada versão rápida tem o seu (cursor:claude-opus-5-5-fast). Com isso a IA consegue ler a tabela e preencher os preços pelo upsert_model.

Onde ficam os dados

O board e os anexos ficam no armazenamento da extensão, fora do repositório. Cada pasta tem o seu arquivo de banco (boards/<chave da pasta>.db), então janelas em projetos diferentes não interferem uma na outra. Na primeira vez, o board parte de uma cópia do banco único das versões anteriores (fazai.db), que fica intacto. Regras e skills são arquivos da pasta do projeto e entram no git normalmente. Evite abrir a mesma pasta em duas janelas do editor ao mesmo tempo: a última a salvar vence (a extensão avisa quando isso acontece).

Backup do board

Para levar o board a outra máquina ou guardar uma cópia, use Configurações → Backup:

• Exportar board gera um arquivo <nome do board>-<data>.fazai.json com tudo o que está no board: colunas, tipos, campos, regras, modelos, agentes, cards (inclusive arquivados e na lixeira), conversas, checklists, vínculos, histórico e os anexos embutidos. Só o board da pasta atual sai no arquivo. Ele contém as conversas e os anexos: guarde-o com cuidado.
• Importar de um arquivo… mostra um resumo (nome, cards, anexos, tamanho, versão) e, depois da confirmação, grava uma cópia do banco (<arquivo>.bak, ao lado dele), move os anexos do board atual para uma pasta de backup (<anexos>.bak-<data>), apaga o board atual e o substitui pelo do arquivo, com os mesmos números de card. O board importado passa a ser o desta pasta. Nada muda no banco se o arquivo for inválido ou se algo falhar no meio. A confirmação diz que os anexos foram para backup. Arquivo de importação com id de card ou nome de anexo contendo caminho (../) é recusado.

Um arquivo exportado por uma versão anterior da extensão é atualizado ao ser importado; um arquivo de versão mais nova é recusado com a versão necessária. Importar com a IA executando um card não é permitido: espere a execução terminar. No navegador o fluxo é o mesmo, com o download e a escolha do arquivo feitos pela própria página. Limites conhecidos: o histórico mensal consolidado do log não vai no arquivo, e as branches e pastas de trabalho das histórias são importadas como estavam na máquina de origem (recrie a pasta pelo botão do card).

Desenvolvimento

npm install
npm run build
npm test
npm run typecheck

O npm test também roda o lint e confere a formatação; npm run format formata tudo. Para o git blame pular o commit que só formatou o código: git config blame.ignoreRevsFile .git-blame-ignore-revs.

Pressione F5 para abrir o Extension Development Host. O código fica em src/extension (host e servidor MCP), src/webview (interface em React), src/shared (modelo, protocolo e as regras do board usadas pelo host e pela interface), src/mcp-bridge (ponte stdio usada pelos clientes de IA) e src/cli (o board fora do editor).

Para testar a interface sem o editor, node dist/cli.js <pasta> --data <pasta de dados de teste> serve o board no navegador. Os testes cobrem a ativação da extensão (com um editor de mentira em test/fakes/vscode.ts) e o servidor da página (test/webServer.test.ts).

Preparar o ambiente de desenvolvimento

O repositório tem todo o código, mas alguns itens ficam fora do git. Num clone novo (outra máquina, por exemplo), eles precisam ser refeitos:

Os três últimos só são necessários para publicar. A main só aceita mudanças por pull request, e o script já cuida disso: npm run release -- <patch|minor|major> parte da main atualizada e limpa, testa, cria a branch release/vX.Y.Z e nela ajusta a versão e os CHANGELOGs ("Não lançado" vira a versão), faz o commit e empacota. Publica nas duas lojas, envia a branch, abre o PR para a main e, com o push concluído, faz o merge (squash). Por fim atualiza a main local, apaga a branch de release (local e remota) e cria a tag e a GitHub Release com o .vsix. Se algo parar depois da publicação, npm run release -- finish retoma de onde parou (na branch de release ou na main), sem publicar de novo. --dry-run ensaia sem publicar. As opções estão no topo de scripts/release.mjs.

Entre empacotar e publicar, o release abre o .vsix e confere os quatro arquivos de vitrine (README.md, README_EN.md, CHANGELOG.md, CHANGELOG_EN.md): o changelog precisa ter o título da versão que está saindo no topo, sem nenhum "Não lançado"/"Unreleased" sobrando em lugar nenhum, e o README precisa ter os blocos de aviso de fase alpha e de agradecimento. Falhando qualquer coisa, o release recusa antes de publicar em qualquer loja. O renomear de "Não lançado" para a versão acontece em todos os modos, inclusive no --dry-run; quando o release não chega a commitar (dry-run ou --no-git), os CHANGELOGs renomeados são restaurados ao original ao final. Sem nenhuma seção "Não lançado"/"Unreleased" para renomear, use --allow-no-notes — só é exigida quando faltar essa seção e a primeira seção do CHANGELOG não for a versão que está saindo.

Dois cuidados:

• se reescrever o texto de um bloco de aviso do README, atualize a tabela SHOWCASE em scripts/releaseCheck.mjs com o novo texto; do contrário o release recusa publicar um README correto, por desenho (falso positivo).
• um Ctrl+C no meio do release pode deixar os CHANGELOGs com o título renomeado em disco; desfaça com git checkout CHANGELOG.md CHANGELOG_EN.md.

Histórico de versões

O que mudou em cada versão está no CHANGELOG.md.

Licença

MIT