Mantenedores¶
Notas para operadores e colaboradores que mantêm o agent-dev-toolkit saudável. Clone e fork públicos são bem-vindos para uso e customização local; o fluxo de contribuição via PR da comunidade no repositório upstream não é o canal previsto hoje.
Política (resumo)¶
| Regra | Detalhe |
|---|---|
| Clone / fork | Qualquer pessoa pode clonar ou fazer fork e adaptar localmente |
| PRs no upstream | Não fazem parte do fluxo atual de contribuição da comunidade; priorize customizações no seu fork |
| Issues | Apenas bugs (sem canal de feature/RFC) |
| Segurança | Reporte via SECURITY.md, não em Issues públicas |
Leituras aprofundadas no GitHub:
- CONTRIBUTING.md
- docs/REPO_GOVERNANCE.md
- SECURITY.md
- docs/ARCHITECTURE.md — layout completo; visão no site: Arquitetura
- docs/CREDITS.md — inspiração de terceiros; site: Créditos
Validação (local)¶
Nenhum destes passos escreve no ambiente real de um agente. Prefira caminhos de fixture em InstallRoot; nunca use -AllowUserHome para “fazer o CI passar”.
Suíte core (contratos, grafo de skills, fixtures — obrigatória antes do merge para mantenedores):
pwsh -NoProfile -File .\scripts\validation\validate-core.ps1
# Alias:
pwsh -NoProfile -File .\scripts\validation\validate-all.ps1
# Quiet (estilo CI):
pwsh -NoProfile -File .\scripts\validation\validate-core.ps1 -Quiet
Validação por agente (validate-core + teste smoke do adaptador contra fixture):
pwsh -NoProfile -File .\scripts\validate-agent.ps1 -Agent cursor
pwsh -NoProfile -File .\scripts\validate-agent.ps1 -Agent claude
pwsh -NoProfile -File .\scripts\validate-agent.ps1 -Agent copilot -Mode user
Harnesses de teste smoke de CI (espelham o comportamento de cópia efêmera do Actions):
pwsh -NoProfile -File .\scripts\validation\Invoke-CursorCiSmoke.ps1
pwsh -NoProfile -File .\scripts\validation\Invoke-AntigravityCiSmoke.ps1
pwsh -NoProfile -File .\scripts\validation\Invoke-ClaudeCiSmoke.ps1
pwsh -NoProfile -File .\scripts\validation\Invoke-CodexCiSmoke.ps1
pwsh -NoProfile -File .\scripts\validation\Invoke-CopilotCiSmokeSuite.ps1
pwsh -NoProfile -File .\scripts\validation\Invoke-OpenCodeCiSmoke.ps1
pwsh -NoProfile -File .\scripts\validation\Invoke-GrokCiSmoke.ps1
pwsh -NoProfile -File .\scripts\validation\Invoke-ZCodeCiSmoke.ps1
Matriz completa, regras de segurança e workflows de CI:
- docs/VALIDATION.md
- validate-toolkit.yml — check obrigatório validate
- docs.yml — build MkDocs / deploy Pages
Scripts de operador (inventory → preflight → harvest)¶
Mesmo fluxo de skills; esses scripts acrescentam gates determinísticos — não um segundo CLI do toolkit. Ordem sugerida numa feature consumidora:
| Ordem | Script | Papel |
|---|---|---|
| 1 | scripts/inventory/Invoke-MemoryBankInventory.ps1 |
ready | not-ready sob memory-bank/.inventory/ |
| 2 | scripts/validation/Invoke-PrdPlanChangePreflight.ps1 |
Bloqueia O3 se PRD/PLAN/CHANGE inconsistentes |
| 3 | Develop (sdd-develop / O3; claim PLAN-LEDGER opcional) |
Gates de sessão + hold opcional no ledger |
| 4 | scripts/trace/Invoke-TraceHarvest.ps1 |
Resume somente features/NNN-slug/TRACE.jsonl |
pwsh -NoProfile -File .\scripts\inventory\Invoke-MemoryBankInventory.ps1 `
-RepoPath . -BankPath .\memory-bank -AllowCreateInventory
pwsh -NoProfile -File .\scripts\validation\Invoke-PrdPlanChangePreflight.ps1 `
-FeatureRoot features\<NNN-slug> `
-PlanPath features\<NNN-slug>\<story>\PLAN\PLAN_....md
pwsh -NoProfile -File .\scripts\trace\Invoke-TraceHarvest.ps1 `
-FeatureRoot features\<NNN-slug>
CLI PLAN-LEDGER: scripts/ledger/Invoke-PlanLedgerClaim.ps1. Só ponteiros (sem colar schema): docs/VALIDATION.md · docs/domains/cli-scripts.md. Claims de emissor TRACE: Adaptadores.
Fluxo Git dos mantenedores¶
Colaboradores com permissão de escrita usam branches normais: feature/<slug> → develop → master/main. Prefira /open-github-pr após /commit / /push (feature → develop; modo release develop → master/main). PRs de release usam o template em .github/PULL_REQUEST_TEMPLATE/release.md. Check de CI obrigatório: validate. Ver a seção Maintainers only (repository owner) em CONTRIBUTING.md (título em inglês no documento fonte).