SpecWeave CLI 3.1.0Grátis e de código aberto
O trabalho sobrevive à sessão.
Seu agente escreve o código. O SpecWeave guarda o que significa concluído, o que comprovou e onde você parou, como arquivos simples no git, para o Claude Code, o Codex ou qualquer outro agente continuar a mesma tarefa.
npm i -g specweaveVersão 3.1.0, lançada em 17 October 2026. Grátis e de código aberto.
$ specweave pickup Picked up the handoff from claude@cloud (out of tokens): applied 7 uncommitted files. SpecWeave pickup · you are codex@laptop Increment 0001-resumable-checkout "Resumable checkout" (active) · tasks 1/2 done Next: T-02 Restore the draft on return AC-01: Returning within 24 hours restores the cart and shipping choice AC-02: A paid order is never restored Files: src/restore.js | Test: npm test Branch: main · in sync with origin/main · 3 uncommitted files Last handoff: claude@cloud: out of tokens · next: finish restore on return Notes: - claude@cloud: Payment thread: drafts must never store card data
Seis comandos do plano ao fechamento
Cada passo deixa um arquivo. Nada fecha com um checkbox: o teste roda, a saída fica guardada, e o incremento continua aberto até a verificação passar.
01 Planeje o incremento
$ specweave create-increment "Resumable checkout"O agente preenche Problem, Scope, critérios de aceitação numerados, Approach e Tasks. Antes de escrever, o sw-increment pergunta apenas as decisões que precisam de você, uma de cada vez e com uma resposta recomendada: no máximo cinco por padrão, e
planning.deepInterviewdefine a profundidade.spec.mdCada tarefa cita seus critérios, seus arquivos e seu teste.02 Assuma uma tarefa
$ specweave task claim T-02O claim vai para o ledger, então um segundo agente que peça a mesma tarefa é recusado. Um claim com mais de duas horas é considerado vencido e pode ser assumido por outro.
specweave task nextmostra a próxima tarefa com o texto dos seus critérios.ledger.jsonlSomente acréscimo: eventos de claim, done, release, skip e block.03 Prove que está pronto
$ specweave task done T-02 --run "npm test"O CLI executa o teste por conta própria. Só a saída 0 registra a tarefa como concluída, com o commit e o final da saída como evidência. Uma execução com falha não registra nada.
reports/task-T-02.txtA saída completa do comando, com o código de saída e o horário.04 Verifique o incremento
$ specweave verifyExecuta os seus comandos de teste, lint e build, vindos de
testing.commandsou detectados a partir depackage.json, Cargo, pytest ou Go, e confere cada critério de aceitação.reports/verify.jsonok só é true quando todos os comandos e critérios passam.05 Revise com o outro modelo
$ specweave reviewEntrega o diff a um revisor de uma família de modelos diferente da que o escreveu: o Codex revisa o código do Claude, e o Claude revisa o da OpenAI. Saída 0 significa entregar, saída 3 significa corrigir antes.
--briefmostra o briefing para colar em qualquer ferramenta. Novo na versão 3.1.0; veja Revisão com outro modelo.reports/review-codex.mdOs achados e o veredito, com o nome do revisor.06 Feche
$ specweave complete 0001Recusa enquanto
reports/verify.jsonestiver ausente ou não estiver ok. Fechar sem ele exige--reason, e o motivo fica guardado no incremento.metadata.jsonConcluído, ou o motivo de ter fechado sem prova.
Comandos, flags e nomes de arquivo como no specweave 3.1.0. O incremento, a tarefa e o revisor são o exemplo usado em toda esta página.
Ficar sem tokens não é o fim
Diga "hand off" na ferramenta que você está deixando e "pick up where I left off" na próxima. O Codex pode continuar o que o Claude Code começou, na mesma máquina ou em outra. Nada é copiado entre ferramentas: specweave handoff envia um snapshot para specweave-handoff e wip/<branch> e adiciona um evento ao ledger.
handoff --allGrava um índice de todos os incrementos ativos e de todos os repositórios aninhados com trabalho apenas local.pickup --listMostra os handoffs pendentes, do mais novo ao mais antigo, e não altera nada.pickup <id ou título>Pega um específico quando vários estão esperando.handoff --no-pushMantém o handoff nesta máquina em vez de enviá-lo ao seu remote.
Saindo: Claude Code, como claude@cloud
$ specweave handoff --reason "out of tokens"
Handed off 0001-resumable-checkout (released T-02, pushed your uncommitted edits).
To continue in any tool, machine or account, say "pick up" there (or run `specweave pickup`).
Details: .specweave/increments/0001-resumable-checkout/handoff.mdUm snapshot enviado para specweave-handoff e wip/<branch> no seu remote, mais um evento de handoff no ledger
Chegando: Codex, como codex@laptop
$ specweave pickup Picked up the handoff from claude@cloud (out of tokens): applied 7 uncommitted files. SpecWeave pickup · you are codex@laptop Increment 0001-resumable-checkout "Resumable checkout" (active) · tasks 1/2 done Next: T-02 Restore the draft on return
As linhas do pickup são saída real de um segundo clone executado como Codex. As linhas do handoff são a mensagem exata do CLI para a mesma execução.
Limites de uso tratados antes de chegarem
specweave auto-handoff on adiciona hooks ao Claude Code, ao Codex e ao Grok Build. Cada hook salva um checkpoint local, e em 95% de qualquer janela de uso o modo decide o que acontece (o Grok não informa porcentagem, então o hook dele age quando um turno atinge o limite de taxa).
suggestPadrão- No limite
- Avisa uma vez que um handoff está pronto e continua trabalhando.
- Use para
- O padrão. Você decide quando trocar.
enforce- No limite
- Executa specweave handoff e encerra a sessão.
- Use para
- Execuções sem supervisão que devem parar limpas no limite de uma tarefa.
checkpoint- No limite
- Só salva checkpoints locais e nunca faz handoff.
- Use para
- Planos em que créditos ou um proxy continuam funcionando além do limite.
--at 90Move o limite; o padrão é 95.--wait-under 30Não faz nada quando todas as janelas cheias são renovadas em até essa quantidade de minutos; o padrão é 30.autocompact onCompacta o Claude Code em 400K tokens em vez de perto de um milhão, para os turnos finais continuarem pequenos.
Executando agentes em SpecWithCode? Use uma máquina por assinatura de provedor: mantenha cada máquina conectada a uma conta por provedor de forma permanente, e adicione uma máquina quando precisar de mais capacidade em vez de trocar de assinatura manualmente.
Sete skills por padrão, quatro quando você precisar
Skills são instruções curtas que o seu agente carrega sob demanda. Desde a 3.1.0, as opcionais são ativadas quando o seu projeto pede. specweave skills list mostra por que cada uma está ativa, e enable ou disable altera isso.
Em todo projeto
sw-increment- Planeja o incremento como uma única spec.md e faz primeiro as perguntas sobre decisões críticas.
sw-grill-me- Entrevista você em rodadas até que toda decisão de um plano esteja resolvida. Com planning.deepInterview definido como deep, todo novo incremento a executa.
sw-do- Trabalha o incremento tarefa por tarefa: claim, implementação dentro dos seus arquivos, teste, commit, done com evidência. Sozinho, sem supervisão ou em lanes paralelas.
sw-auto- Executa um incremento sem supervisão até que todas as tarefas estejam concluídas, depois verifica e fecha.
sw-review- Uma revisão adversarial por um contexto novo ou outra família de modelos. Cada achado cita um arquivo e uma linha.
sw-done- Fecha o incremento: tarefas concluídas, verify verde, revisão com contexto novo e então complete.
sw-handoff- Passa o trabalho para outra ferramenta, conta ou máquina e o retoma lá.
Quando o projeto pede
sw-glossary- Cria
GLOSSARY.md, o vocabulário compartilhado do projeto.specweave glossary check --strictfaz o CI falhar se houver divergência. sw-sync- Envia incrementos para o GitHub, Jira ou Azure DevOps. Ativada quando o projeto tem um tracker.
sw-project- Lê e atualiza o hub do projeto. Ativada quando
.specweave/project/hub.jsonexiste. sw-jev- Entrega decisões de conjunto fechado ao Jev. Ativada quando
jev.enabledestá definido.
Um registro que você pode inspecionar
Tudo acima são arquivos comuns no seu repositório. A revisão no git e os controles de acesso protegem o histórico; esses arquivos não são um sistema de auditoria à prova de adulteração.
spec.mdO que significa concluído
Escrito no planejamento e lido antes do código.
ledger.jsonlO que aconteceu
Claims, conclusões com evidências, notas e handoffs.
reports/O que comprovou
Logs de tarefas,
verify.md,verify.jsone relatórios de revisão.handoff.mdOnde você parou
Escrito por
specweave handoff.specweave noteNotas para o próximo agente
Guardadas no ledger, e
pickupas mostra..specweave/memory/Decisões que sobrevivem à sessão
Um arquivo por fato, indexado em
MEMORY.mde commitado, para que toda ferramenta e conta o veja.specweave dashboardUm quadro com tudo isso
Somente local, em 127.0.0.1 na porta 3456 por padrão. Lê-lo não exige nenhuma chamada a modelo.
specweave reportQuem fez o quê, em uma página
Uma linha do tempo em HTML com ferramentas, sessões, handoffs e evidências em
reports/handoff-report.html.
O que o painel lê para o exemplo
| Incremento | 0001-resumable-checkout Checkout retomável |
|---|---|
| Estado | Ativo |
| Tarefas | 1 de 2 concluídas |
| Próxima tarefa | T-02 Restaurar o rascunho na volta |
| Critérios | AC-01 Voltar em até 24 horas restaura o carrinho e a opção de entrega. AC-02 Um pedido pago nunca é restaurado. |
| Arquivos e teste | src/restore.js, npm test |
| Último handoff | claude@cloud, sem tokens. Retomado por codex@laptop. |
Montado a partir da mesma execução de specweave pickup mostrada no topo desta página. Execute specweave dashboard no seu projeto para ver o seu.
Conectado às ferramentas que você já usa
Cada uma é opcional e fica desligada até você configurá-la.
Navegação no código
$ specweave lsp refs src/restore.js restoreDraftReferências, definições, tipos ao passar o mouse e símbolos vindos de language servers, para os agentes pararem de usar grep.
Guia de LSPspecweave lsp setupescolhe servidores para as linguagens do seu repositório.Jev
$ specweave jev route "<prompt>"Decisões de conjunto fechado em cerca de 250 ms: qual skill ou nível de modelo, se um comando de shell é seguro de executar, se um texto baixado merece uma segunda olhada. Ative com
Sobre o Jevspecweave jev setup.Hub do projeto
$ specweave project briefUm objetivo, contexto, artefatos e rotinas compartilhados em
Guia de projetos portáteis.specweave/project/hub.json, lidos por todas as ferramentas.--harness codexexporta o briefing para outra ferramenta.Repositórios existentes
$ specweave get owner/repoClona e registra um repositório no workspace, ou todos os repositórios de uma organização com
Guia de adoção do workspace--all.--dry-runmostra antes como seria adotar um checkout que você já tem.Issue trackers
$ specweave sync pushOpcional. Envie um incremento para o GitHub Issues, Jira ou Azure DevOps quando a sua equipe planeja por lá.
Guia de sincronização com trackers
Execute os mesmos incrementos em um app de desktop
Uma thread de worker do SpecWithCode trabalha em uma branch e abre um pull request, que é exatamente o formato de um incremento. A checklist dela é a lista de tarefas do incremento, e as escritas dela no ledger são os comandos desta página. As threads deixam notas umas para as outras no ledger em vez de editar os arquivos umas das outras.
Conheça o SpecWithCode