Começar¶
Clone o toolkit, valide o repositório, sincronize um agente e invoque uma skill no projeto da aplicação que você está construindo.
Pré-requisitos¶
Sistemas suportados: Windows, Linux (Ubuntu, Debian e derivados) e macOS.
| Requisito | Notas |
|---|---|
| PowerShell | Windows: 5.1+ ou pwsh 7+ (recomendado). Linux / macOS: somente pwsh 7+ — Windows PowerShell 5.1 não existe nesses OS. (guia de instalação) |
| Git | Clonar / atualizar este repositório |
| Agente alvo | Pelo menos um de: Cursor, Claude Code, Codex, GitHub Copilot, Antigravity, OpenCode, Grok Build, ZCode (ADE), Hermes, OpenHands |
1. Clone¶
git clone https://github.com/tibursocampos/agent-dev-toolkit.git agent-dev-toolkit
cd agent-dev-toolkit
2. Abrir o Smart Manager¶
Entrada principal — menu interativo (wizards de agente/alvo, Help):
pwsh -NoProfile -File .\scripts\toolkit.ps1
| Menu (rótulos em inglês no CLI) | Resultado |
|---|---|
| Validate core only | Só contratos do repo — sem escrita no ambiente do agente |
| Sync agent | Publica skills/policy/hooks no alvo escolhido |
| Validate agent | validate-core + teste smoke do adaptador para um agente |
| Sync then validate | Sync e, em seguida, teste smoke no mesmo alvo |
| Uninstall agent | Remove arquivos gerenciados do toolkit (desinstalação seletiva — não limpa a pasta de instalação inteira) |
3. Validar o repositório (seguro)¶
Confirma que o toolkit está saudável sem escrever no ambiente do agente:
pwsh -NoProfile -File .\scripts\toolkit.ps1 -Action ValidateCore
4. Sincronizar um agente¶
Padrão seguro — fixture in-repo¶
Sync não interativo omite -InstallRoot e grava a fixture do adaptador em scripts/validation/fixtures/. Use para aprendizado e teste smoke seguro em CI; não altera o ambiente real do agente.
pwsh -NoProfile -File .\scripts\toolkit.ps1 -Action Sync -Agent cursor
pwsh -NoProfile -File .\scripts\toolkit.ps1 -Action Validate -Agent cursor -Quiet
No menu interativo, escolha In-repo fixture para o mesmo caminho seguro.
Ambiente real do agente — ativação explícita¶
Caminhos sob %USERPROFILE% / $HOME são recusados salvo se você passar -AllowUserHome (ou confirmar no wizard). O Sync interativo deixa o menu de alvo em Live agent home (pasta de instalação real) por padrão — confirme antes de gravar.
Cursor → ~/.cursor¶
pwsh -NoProfile -File .\scripts\toolkit.ps1 -Action Sync -Agent cursor `
-InstallRoot "$env:USERPROFILE\.cursor" -AllowUserHome
Claude Code → ~/.claude¶
pwsh -NoProfile -File .\scripts\toolkit.ps1 -Action Sync -Agent claude `
-InstallRoot "$env:USERPROFILE\.claude" -AllowUserHome
GitHub Copilot — Mode obrigatório¶
pwsh -NoProfile -File .\scripts\toolkit.ps1 -Action Sync -Agent copilot -Mode user `
-InstallRoot "$env:USERPROFILE\.copilot" -AllowUserHome
pwsh -NoProfile -File .\scripts\toolkit.ps1 -Action Sync -Agent copilot -Mode repo `
-InstallRoot "D:\Source\MyApp\.github"
No Mode repo, o InstallRoot costuma ser a pasta .github do repositório da aplicação, então -AllowUserHome muitas vezes não é necessário.
Outras pastas de instalação real¶
| Agente | InstallRoot típico |
|---|---|
antigravity |
$env:USERPROFILE\.gemini |
codex |
~/.codex (produto/AGENTS/rules); skills USER opcionais ~/.agents/skills via -UserScope + -AllowUserHome — ver Adaptadores / Usando skills |
opencode |
$env:USERPROFILE\.config\opencode |
grok |
$env:USERPROFILE\.grok |
zcode |
$env:USERPROFILE\.zcode |
hermes |
$env:USERPROFILE\.hermes |
openhands |
Raiz do repo (skills em .agents/skills); usuário live $env:USERPROFILE\.agents (skills em skills/) |
Sempre adicione -AllowUserHome quando o InstallRoot resolver sob o perfil do usuário. Detalhes de layout: Adaptadores.
Simulação (dry run)¶
pwsh -NoProfile -File .\scripts\sync-agent.ps1 -Agent cursor -WhatIf
5. O que é publicado¶
Todo sync prepara <InstallRoot>/sdd/ (sessions/ + seed de manifest.json schema v2 quando ausente). Artefatos típicos:
| Agente | Sob InstallRoot |
|---|---|
| Cursor | skills/, rules/*.mdc, AGENTS.md, hooks/ |
| Claude | skills/, rules/*.md, CLAUDE.md, hooks + settings.json mesclado |
| Copilot | skills/, instructions/, copilot-instructions.md |
| Codex | plugin/ (+ marketplace), rules/*.md, AGENTS.md materializado; .agents/skills opcional com -UserScope (dual-root — skills e rules não compartilham um único TOOLKIT_ROOT) |
| Hermes | skills/, AGENTS.md (sem árvore rules/); plugin agent-dev-toolkit-guard + agent-hooks path/secrets; config.yaml apenas chaves gerenciadas |
| OpenHands | Projeto: .agents/skills/, .agents/agents/, AGENTS.md, .openhands/hooks (guard_pre_tool.sh path/secrets), .plugin/plugin.json. Skills do usuário live: ~/.agents/skills |
| Outros | Ver Adaptadores e Arquitetura |
Armazenamento SDD (primeira gravação Classic): as skills perguntam repositório vs global quando o projeto ainda não está no manifesto.
- Repositório —
features/+memory-bank/na raiz do projeto da aplicação - Global — a mesma árvore sob
{{SDD_ROOT}}/<repo-id>/(fora do git do projeto)
Install/sync: docs/INSTALL.md. Layout do core: docs/domains/core.md. Contrato de storage: core/sdd/STORAGE.md.
6. Abrir o projeto da aplicação¶
Abra o repositório da aplicação que você quer alterar (não só este toolkit). Após um sync na instalação real, confira o router + uma skill de exemplo no InstallRoot desse agente (exemplos):
%USERPROFILE%\.claude\CLAUDE.md
%USERPROFILE%\.claude\skills\sdd-spec\SKILL.md
%USERPROFILE%\.claude\skills\help-skills\SKILL.md
Ou no Cursor: %USERPROFILE%\.cursor\AGENTS.md e skills\…. Reinicie ou recarregue o agente se as skills não aparecerem. Aceite os hooks na UI do agente se solicitado.
7. Primeira skill¶
Prefira ids de skill; forma slash quando o host suportar:
help-skills
Depois SDD clássico:
sdd-spec
sdd-plan - <prd-path>
sdd-develop - <plan-path> - Step 1
Normalização opcional de handoff (mesma trilha — não é um quarto estágio): read-sdd-artifact → source_context tipado. Invocation (direct / orchestrated) e provenance (agreed / invented) ficam dentro desses skill ids — veja Usando skills e docs/domains/core.md.
Mudança pequena sem SDD completo: developer ou uma skill de stack como dotnet-developer. Escolher trilha Classic SDD / Backlog Refine / Orchestrated Delivery: Usando skills.
Depois de commit e push, abra um PR com open-github-pr (feature → develop; modo release develop → master/main). Detalhes: Usando skills.
8. Depois de git pull¶
Reexecute o sync para cada agente que você usa. Sync é atualização no lugar (update-in-place): sobrescreve arquivos gerenciados e remove skills gerenciadas que saíram de core/skills/. Preserva sdd/sessions/ e sdd/manifest.json.
9. Desinstalação (seletiva)¶
Remove skills, policy/rules, routers e hooks gerenciados pelo toolkit — não a pasta de instalação inteira do agente. Preserva sdd/sessions/ e sdd/manifest.json.
pwsh -NoProfile -File .\scripts\toolkit.ps1 -Action Uninstall -Agent claude
Solução de problemas¶
| Sintoma | Correção |
|---|---|
| Sync recusa InstallRoot | Adicione -AllowUserHome ou confirme no wizard |
| Copilot TE02 | Mode ausente/inválido — passe -Mode user ou -Mode repo |
| Skills ausentes no IDE | Sync no ambiente real do agente; reinicie/aceite os hooks se necessário |
| Esperava escrita no ambiente em run tipo CI | Use fixtures / omita InstallRoot real |
Próximo: Usando skills · Caveman · Adaptadores · Créditos · Mantenedores