Começar¶
Publique o agent-dev-toolkit em um ou mais agentes de código e abra o projeto que você quer mudar.
| Caminho | Quando |
|---|---|
| Opção 0 — Bootstrap de release (recomendado) | Baixe um entrypoint de bootstrap nas GitHub Releases. Ele busca o zip por HTTPS, confere o SHA256, extrai e abre toolkit.ps1. Sem clone completo. |
| Opção 1 (depois do clone) | Smart Manager interativo: pwsh -NoProfile -File .\scripts\toolkit.ps1 |
| Opção 2+ | Sync e verificações não interativos em CLI |
O repositório é público. Clone e fork à vontade. Contribuições upstream não são aceitas. Veja Mantenedores.
Pré-requisitos¶
SO suportado: Windows, Linux (Ubuntu, Debian e derivados) e macOS.
| Requisito | Notas |
|---|---|
| PowerShell | Windows: PowerShell 5.1+ ou pwsh 7+ (recomendado). Linux / macOS: pwsh 7+ apenas. |
| Git | Necessário na opção 1 / 2+ (clone). A opção 0 não exige Git. |
| Agente alvo | Pelo menos um de: Cursor, Claude Code, Codex, GitHub Copilot, Antigravity, OpenCode, Grok Build, ZCode ADE, Hermes, OpenHands |
| Rede (opção 0) | HTTPS para as GitHub Releases. Usa curl (preferido) ou Invoke-WebRequest. O bootstrap não usa a CLI gh, Node nem um .exe compilado. |
0. Bootstrap de release¶
O entrypoint baixa o zip, confere o SHA256 e abre o CLI.
| Sistema | Download |
|---|---|
| Windows (recomendado) | bootstrap.bat |
| Windows (somente pelo terminal PowerShell) | bootstrap.ps1 |
| Linux e macOS | bootstrap.ps1 bootstrap.sh |
No Windows, bootstrap.bat é o launcher guiado. Ele remove a marca de download do navegador em bootstrap.ps1 e inicia o PowerShell com -ExecutionPolicy Bypass, preferindo pwsh e usando o Windows PowerShell como alternativa. No Linux e macOS, execute bootstrap.ps1 com pwsh -NoProfile -File; o wrapper opcional bootstrap.sh precisa estar executável e ao lado do bootstrap.ps1. Qualquer um dos comandos abre o Smart Manager interativo no terminal.
Não dê clique duplo em bootstrap.ps1
Um download pelo navegador pode marcar o bootstrap.ps1 como arquivo da Internet, e a política RemoteSigned pode bloqueá-lo. Execute com pwsh -NoProfile -File .\bootstrap.ps1 por um terminal, ou baixe com curl.exe, que evita a marca. Você também pode usar Unblock-File depois de revisar o arquivo.
Checksum inválido sai com código diferente de zero. Não há extração nem handoff.
Publicado por .github/workflows/publish-release-bootstrap.yml:
| Artefato | Nome |
|---|---|
| Zip do toolkit | agent-dev-toolkit.zip |
| Sidecar SHA256 | agent-dev-toolkit.zip.sha256 |
| Entrypoints | bootstrap.ps1, bootstrap.bat, bootstrap.sh |
Sobrescreva owner/repo com -Owner / -Repo ou TOOLKIT_RELEASE_OWNER / TOOLKIT_RELEASE_REPO. Sobrescreva nomes de assets com -ZipAssetName / -ChecksumAssetName ou TOOLKIT_RELEASE_ZIP_ASSET / TOOLKIT_RELEASE_CHECKSUM_ASSET.
Flags do bootstrap¶
| Flag / env | Função |
|---|---|
| (padrão) | Depois do SHA256 ok, extrai e abre o toolkit.ps1 interativo |
-NoExtract |
Só verifica o checksum |
-SkipSync |
Para depois de uma extração bem-sucedida |
-DirectSync |
Depois de extrair, chama sync-agent.ps1 |
-SyncWhatIf |
Com -DirectSync, encaminha -WhatIf para sync-agent.ps1 |
-Agent / TOOLKIT_SYNC_AGENT |
Id de agente do registro quando -DirectSync (padrão cursor) |
-InstallRoot / -AllowUserHome / -Mode / -UserScope |
Encaminhados para sync-agent.ps1 quando -DirectSync roda |
-ZipAssetName / TOOLKIT_RELEASE_ZIP_ASSET |
Sobrescreve o asset do zip (padrão agent-dev-toolkit.zip) |
-ChecksumAssetName / TOOLKIT_RELEASE_CHECKSUM_ASSET |
Sobrescreve o asset do checksum (padrão agent-dev-toolkit.zip.sha256) |
-ExpectedSha256 |
SHA256 hexadecimal (pula o download do checksum) |
-LocalZipPath + -SkipDownload |
Smoke offline, sem rede |
-Extract |
Alias legado sem efeito (a extração fica ligada, salvo -NoExtract) |
1. Clone (alternativa)¶
git clone https://github.com/tibursocampos/agent-dev-toolkit.git agent-dev-toolkit
cd agent-dev-toolkit
Depois do download¶
O menu, cada -Action, sync, validação e desinstalação estão em CLI.
Abra o repositório da aplicação no agente e siga para Primeiro uso. O caminho de uma feature é Entrega orquestrada.
Qual fluxo escolher?¶
Não sabe qual fluxo se encaixa no seu trabalho? Escolha antes de começar:
| Fluxo | Use quando | Skill de entrada |
|---|---|---|
| Entrega orquestrada | Feature com várias histórias, código brownfield ou especialistas | orchestrate-analyze |
| SDD clássico | Uma história já clara, sem necessidade de especialistas | sdd-spec |
| Refinar item do backlog | Item informal (bug, história de usuário, história técnica) antes do SDD | refine-story |
| Revisão de requisito | Questionar critérios de aceitação ou contratos antes do SDD | requirement-review |
Os fluxos não são pré-requisitos uns dos outros. Veja o guia de decisão completo (ainda só em inglês): Choosing the flow.
Solução de problemas¶
| Sintoma | Causa provável | Correção |
|---|---|---|
| O sync recusa o InstallRoot | Caminho sob o perfil do usuário sem o opt-in | Acrescente -AllowUserHome, ou confirme no assistente |
| Copilot TE02 | -Mode ausente ou inválido |
Passe -Mode user ou -Mode repo |
| Skills ausentes na IDE | Só o fixture foi sincronizado, ou o agente precisa reiniciar | Sincronize o home ao vivo. Confie nos hooks na UI do agente se ela pedir |
| Uma execução local falha como a CI falharia | O comando esperava escrita no home | Use fixtures ou smokes do Validation lab |
Próximo: Primeiro uso.