@pathbit/agentdevkit 0.0.0-stage → 0.0.6

package/.pbai4devs/skills/projeto/usar-skills-externas/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: usar-skills-externas
+description: Seleciona e usa skills externas curadas sem copiar instruções para os agentes.
+---
+
+# Usar skills externas
+
+Consulte o [catálogo](../../../external-skills/README.md) antes de criar uma
+solução equivalente. Escolha pela tarefa e pela stack já decidida; não adote
+tecnologias para justificar uma skill. Prefira conectores e skills disponíveis.
+
+Use `gerenciar-skills-externas list` pelo seletor. Para uma entrada `reviewed`,
+execute `install <id>`, `check <id>` e `read <id>`; leia também as referências
+pertinentes. A instalação fica ignorada, fora da origem e dos espelhos.
+Ative só o necessário; não carregue todas as coleções no contexto.
+
+Confirme origem, licença, revisão fixada e efeitos antes de aprovar uma entrada
+ou versão nova. `update` reinstala somente o pin revisado no catálogo. Novas
+instruções e scripts exigem nova revisão; não use atualizações globais do CLI.
+Após mudar `CATALOG.json`, execute `sincronizar-agentes` e `--check` para manter
+o inventário local atualizado; as definições são fontes, os índices são derivados.
+Instruções externas se subordinam às decisões deste projeto: Node nas
+automações, resultados em `.agent-tests/`, sem mudanças de stack, hooks,
+publicações ou instalação de frameworks por iniciativa da skill.
+
+Registre IDs e revisões usados no plano/revisão. Use orientações compatíveis
+sem copiar o conteúdo externo para `SKILL.md` locais. Origem oficial não
+substitui revisão nem significa homologação universal.

package/.pbai4devs/skills/projeto/verificar-trabalho/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: verificar-trabalho
+description: Verifica alterações com ferramentas reais e registra evidências por critério de aceite.
+---
+
+# Verificar trabalho
+
+Reúna os critérios e o impacto da alteração. Use `executar-script` para
+identificar ferramentas disponíveis e selecione os níveis aplicáveis. Use
+`usar-skills-externas` para referências pertinentes, sem adotar uma stack nova:
+
+1. **Estrutura:** para recursos dos agentes, execute `verificar-recursos`;
+   ele confere espelhos, frontmatter/H1 e links, além do Markdown lint quando
+   instalado. Sincronize os apontamentos antes da verificação.
+2. **Comportamento:** execute testes relevantes, lint, tipos e build definidos
+   no projeto; para automações dos agentes, execute `testar-infraestrutura`.
+   Ao alterar catálogo, sincronizador, instalador ou cópia de projetos, execute
+   também `testar-maturidade run` e confira os cenários em `examples/generated/`.
+   Confira resultados e códigos de saída; não instale ferramentas
+   ou invente metas de cobertura sem decisões do projeto.
+3. **Navegador:** obrigatório para alterações que afetem a web. Abra a URL real
+   com Playwright ou agent-browser em Chrome/Chromium. Percorra o fluxo e
+   confira resultados
+   visíveis, console e rede em desktop e celular quando aplicável. Prefira os
+   testes do projeto; com conector Playwright, reutilize o
+   [executor](../../../scripts/testar-navegador/REFERENCE.md).
+4. **Desktop/artefato:** abra a aplicação ou o arquivo gerado com a ferramenta
+   adequada, como agent-desktop ou um conector compatível; execute o fluxo
+   afetado ou renderize e inspecione o resultado.
+
+Não use fixture como prova do produto nem uma captura como única prova
+funcional. Sem a ferramenta exigida ou com falhas, marque **não verificado**
+ou **falhou**; não declare a entrega verificada. Resolva falhas no escopo.
+
+Versione testes e fixtures. Salve saídas, relatórios e capturas em
+`.agent-tests/` ou outro destino ignorado. Relate cada critério como passou,
+falhou ou não verificado, com evidência e limitações.
+Para uma entrega, use IDs AC-001 e organize as provas em
+`.agent-tests/<referencia>/<execucao>/`. Encaminhe os resultados ao comando
+`revisar-entrega`; revisão pendente ou critério sem prova impedem a conclusão.
+
+Para o catálogo Vercel, execute o teste funcional
+`node .pbai4devs/scripts/preparar-ferramentas/tests/SMOKE_VERCEL.mjs` após instalar
+as ferramentas citadas nele. Ele verifica descoberta, shell virtual e roteiros;
+probes de Portless não comprovam proxy/TLS, nem dry-run comprova vídeo gravado.

package/.pbai4devs/skills/specs/criar-spec/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: criar-spec
+description: Cria uma spec de incremento, esclarecendo requisitos e dúvidas com o usuário.
+---
+
+# Criar spec
+
+Leia os caminhos em `.pbai4devs/estado/configuracao/ESTADO.md`. Exija PRD/design
+aprovados e UX/UI aprovado ou não aplicável com justificativa aprovada.
+Confira evidências, atualidade e decisões essenciais ao incremento; se faltar
+algo, encaminhe à etapa correspondente antes de escrever a spec.
+
+1. Reúna as dúvidas no início e aproveite respostas existentes. Obtenha nome
+   (até 50 caracteres), descrição, requisitos, limites e dependências; registre
+   predecessoras e estado ou “Nenhuma”. Não invente decisões ou métricas.
+2. Confira o incremento no roadmap; planeje-o com `gerenciar-roadmap` se faltar.
+   Forme um slug em minúsculas sem acentos, números e hífens; nome vazio exige
+   outra escolha. Se a spec já existir, combine atualização ou novo nome.
+3. Preencha `.pbai4devs/templates/spec/TEMPLATE.md` em
+   `<documentos.specs>/<slug>/SPEC.md`, com `status: rascunho`. Use o nome como
+   H1; vincule PRD, UX/UI, design e roadmap. Marque pendências e não aplicáveis.
+   Para cada ID AC-001, defina método/comando, pré-requisito, assertiva, dados
+   e caminho da prova em `.agent-tests/<spec>/<execucao>/` antes de aprovar.
+   Indique quais documentos a entrega pode afetar e as referências externas.
+4. Revise requisitos, dependências e critérios de aceite; apresente ao usuário,
+   ajuste e aguarde aprovação explícita. Registre `status: aprovado` e evidência
+   somente após aprovação; mudanças materiais voltam a rascunho.
+5. Após aprovar, combine a release se indefinida. Atualize-a no diretório
+   acordado, pelo modelo de release, com links, dependências e estado da spec;
+   preserve outros itens e não invente a decisão.
+
+Atualize README/índices afetados com `atualizar-documentacao`. Siga a regra de
+qualidade; sincronize apenas recursos agênticos alterados. Não implemente.

package/.pbai4devs/skills/specs/gerenciar-roadmap/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: gerenciar-roadmap
+description: Consulta o status e organiza specs e entregas em releases.
+---
+
+# Gerenciar roadmap
+
+Leia o estado do projeto e seus caminhos. Numa consulta, não altere arquivos:
+mostre preparação, releases, specs e tarefas com dependências e bloqueios.
+Use `[ ]`, `[-]` e `[x]` conforme evidências; informe estados desconhecidos.
+Sem roadmap, diga que ainda não foi criado. Não conclua entregas sem prova.
+
+Ao planejar ou atualizar, use o modelo de roadmap no caminho acordado. Registre
+objetivos, prioridades, etapas, dependências e pendências de PRD, UX/UI e design.
+Mantenha referências e estados coerentes ao aprovar ou revisar documentos;
+não invente escopo, datas ou releases. Identifique as specs do primeiro entregável
+pelas dependências e pergunte por decisões faltantes.
+
+Para uma release planejada, combine nome, prioridades e dependências. Use slug
+em minúsculas sem acentos, números e hífens e o modelo de release em
+`<documentos.releases>/<slug>/RELEASE.md`. Vincule specs e tarefas, preserve
+outros itens e só conclua após entregas e verificações completas. A preparação
+inicial não exige definir uma release.
+
+Siga a regra de qualidade. Após alterações, use `sincronizar-agentes` e informe
+arquivos e pendências; uma consulta não executa essa sincronização.

package/.pbai4devs/skills/specs/implementar-spec/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: implementar-spec
+description: Planeja e implementa uma spec aprovada, acompanhando tarefas e critérios de aceite.
+---
+
+# Implementar spec
+
+Leia `.pbai4devs/estado/configuracao/ESTADO.md`. Exija spec, PRD e design aprovados;
+UX/UI aprovado ou não aplicável com justificativa aprovada. Confira evidências,
+atualidade, decisões essenciais e vínculos com o roadmap; resolva pendências
+antes de implementar.
+
+1. Em planejamento ou leitura, examine spec, projeto, dependências e Git local
+   e remoto. Reúna as dúvidas no início e aguarde respostas necessárias.
+2. Proponha escopo, componentes, decisões, riscos, tarefas e verificação de cada
+   critério. Aguarde aprovação do plano antes de alterar arquivos ou ambiente.
+   Consulte `usar-skills-externas` para as referências aplicáveis e registre
+   seus IDs/revisões. Não invente uma solução já atendida por elas.
+3. Depois da aprovação, crie ou retome `feature/<slug-da-spec>` de `develop`.
+   Se faltar `develop`, use `main` quando seguro; sem base/remoto, combine como
+   proceder. Preserve alterações. Registre a aprovação no roadmap e confira a
+   configuração real; complete-a com `configurar-projeto` antes de codificar.
+4. Use o modelo de tarefas em `<documentos.tarefas>/<slug-da-spec>/TASKS.md`.
+   Vincule spec/release e registre tarefas, dependências, critérios e evidências.
+   Atualize `[ ]`, `[-]` e `[x]` ao avançar; conclusão exige prova. Ao retomar,
+   confira arquivo, branch, código e remoto, além dos marcadores.
+5. Implemente só a spec. Em trabalho delegado, use worktrees e branches próprias;
+   integre somente trabalho completo e verificado, sem sobrescrever alterações.
+   Esclareça novos impedimentos antes de avançar na parte afetada.
+6. Por tarefa concluída, atualize tarefas/release e a documentação afetada com
+   `atualizar-documentacao`. Execute o comando `revisar-entrega`, incluindo
+   provas e revisão independente. Só então crie o commit do checkpoint conforme
+   a regra Git e sincronize a feature com o remoto.
+   Nunca publique trabalho parcial, falho, alheio ou com autoria de agente.
+   `[-]` é trabalho local: outro desenvolvedor retoma do último checkpoint
+   publicado. Resolva divergências e falhas sem push forçado ou perda de trabalho.
+7. Use `verificar-trabalho` para provar cada aceite, respeitando cobertura e a
+   regra de qualidade. Alterações web exigem navegador real; desktop exige
+   abrir a aplicação. Relate passou, falhou ou não verificado com evidência e
+   motivo; atualize tarefas, roadmap e release.
+8. Com aceites, testes, documentação e revisão da entrega atendidos no estado
+   final, integre em `develop` e sincronize.
+   Promova a release a `main` só com todas as entregas e revisões concluídas.
+   Se `develop` tiver atividades incompletas, selecione apenas entregas prontas
+   por fluxo de release. Respeite proteções e informe impedimentos.
+
+Preserve o relatório final e as evidências em `.agent-tests/`. Sincronize
+apontamentos somente se recursos dos agentes mudarem; documentos não são espelhos.

package/.pbai4devs/templates/README.md

@@ -0,0 +1,65 @@
+---
+description: Modelos por fase e manutenção dos documentos do projeto.
+---
+
+# Modelos
+
+Ordem: preparação → PRD → UX/design → configuração → implementação → release.
+Use as skills correspondentes para reunir respostas e preencher os modelos.
+Arquivos nesta pasta são bases, não documentos aprovados. Não crie `docs/`
+enquanto o usuário estiver preparando somente a estrutura dos agentes.
+
+| Modelo | Começar em | Evoluir quando |
+| --- | --- | --- |
+| [README raiz][readme] | Preparação | Fase, uso ou capacidade mudar. |
+| [README de pasta][pasta] | Criação da pasta | Entradas ou finalidade mudar. |
+| [AGENTS][agentes], [CLAUDE][claude] | Preparação | Estrutura mudar. |
+| [Entradas raiz][entrypoints] | Instalação | Cliente mudar. |
+| [Configuração][config] | Preparação | Produto e stack forem definidos. |
+| [Arquivos raiz][raiz] | Configuração | Contratos mudar. |
+| [Gitignore][ignore] | Preparação | Artefatos ignorados mudar. |
+| [PRD][prd], [roadmap][roadmap] | PRD | Escopo ou prioridades mudar. |
+| [UX/UI][ux], [design][design] | Design | Jornadas ou arquitetura mudar. |
+| [ADR][adr] | Design | Decisão estrutural for aceita/substituída. |
+| [Ambiente local][ambiente] | Configuração | Stack ou setup mudar. |
+| [Contribuição][contrib] | Configuração | Fluxo de desenvolvimento mudar. |
+| [Spec][spec] | Implementação | Escopo ou critérios mudarem. |
+| [Plano][plano], [tarefas][tasks] | Implementação | Execução mudar. |
+| [Revisão de entrega][revisao] | Implementação | Antes de commit/merge. |
+| [Release][release], [CHANGELOG][changelog] | Primeira entrega | Publicar. |
+| [SECURITY][security] | Suporte público | Política/suporte mudar. |
+| [Comando][comando] | Recurso agêntico | Entrada ou fluxo mudar. |
+
+Copie só artefatos aplicáveis, remova instruções/placeholders e confirme fatos.
+README acompanha o projeto desde a preparação; documentos de produto surgem
+após descoberta. Segurança depende de suporte e canal realmente definidos.
+
+Critérios de spec usam IDs AC-001. O código dos testes é versionado; resultados
+ficam em `.agent-tests/<referencia>/<execucao>/`. O único relatório de revisão
+é o JSON gerado pelo script; o modelo explica o contrato, sem duplicá-lo em MD.
+Baseline e selo são metadados gerados para detectar alterações posteriores.
+Modelos, configurações e relatórios não são espelhados nas pastas dos agentes.
+
+[readme]: readme-projeto/TEMPLATE.md
+[pasta]: readme-pasta/TEMPLATE.md
+[agentes]: instrucoes-agentes/TEMPLATE.md
+[claude]: claude/TEMPLATE.md
+[entrypoints]: entrypoints/
+[config]: configuracao/TEMPLATE.md
+[raiz]: configuracao-raiz/TEMPLATE.md
+[ignore]: gitignore/TEMPLATE.md
+[prd]: prd/TEMPLATE.md
+[roadmap]: roadmap/TEMPLATE.md
+[ux]: ux-ui/TEMPLATE.md
+[design]: design/TEMPLATE.md
+[adr]: adr/TEMPLATE.md
+[ambiente]: ambiente-local/TEMPLATE.md
+[contrib]: contribuicao/TEMPLATE.md
+[spec]: spec/TEMPLATE.md
+[plano]: plano-implementacao/TEMPLATE.md
+[tasks]: tasks/TEMPLATE.md
+[revisao]: revisao-entrega/TEMPLATE.md
+[release]: release/TEMPLATE.md
+[changelog]: changelog/TEMPLATE.md
+[security]: seguranca/TEMPLATE.md
+[comando]: comando/TEMPLATE.md

package/.pbai4devs/templates/adr/TEMPLATE.md

@@ -0,0 +1,21 @@
+---
+description: Registro de uma decisão arquitetural e de suas consequências.
+status: modelo
+decisao: proposta
+substitui: null
+---
+
+# ADR — Identificador e título
+
+## Contexto
+
+[Problema, restrições e referências vigentes que exigem a decisão.]
+
+## Decisão
+
+[Escolha, alternativas consideradas e motivo. Registre quem a confirmou.]
+
+## Consequências
+
+[Impactos, riscos, migração e condições para reconsiderar. Vincule decisões
+substituídas sem apagar o histórico.]

package/.pbai4devs/templates/ambiente-local/Makefile.template

@@ -0,0 +1,48 @@
+# MODELO: preencha os comandos da stack; valores ausentes falham.
+COMPOSE_FILE ?= infra/compose/compose.local.yml
+COMPOSE = docker compose -f $(COMPOSE_FILE)
+BUILD_COMMAND ?=
+TEST_COMMAND ?=
+LINT_COMMAND ?=
+SETUP_COMMAND ?=
+
+define DOCTOR_COMMANDS
+docker version
+docker compose version
+$(COMPOSE) config --quiet
+endef
+
+.PHONY: help doctor setup up down logs test lint build
+.DEFAULT_GOAL := help
+
+help:
+	@printf '%s\n' 'doctor setup up down logs test lint build'
+
+doctor:
+	$(DOCTOR_COMMANDS)
+
+setup:
+	$(if $(strip $(SETUP_COMMAND)),,$(error Defina SETUP_COMMAND com o preparo real do projeto))
+	$(SETUP_COMMAND)
+	$(DOCTOR_COMMANDS)
+
+up: doctor
+	$(COMPOSE) up -d --wait
+
+down:
+	$(COMPOSE) down
+
+logs:
+	$(COMPOSE) logs --follow --tail=100
+
+test:
+	$(if $(strip $(TEST_COMMAND)),,$(error Defina TEST_COMMAND com os testes reais))
+	$(TEST_COMMAND)
+
+lint:
+	$(if $(strip $(LINT_COMMAND)),,$(error Defina LINT_COMMAND com o lint real))
+	$(LINT_COMMAND)
+
+build:
+	$(if $(strip $(BUILD_COMMAND)),,$(error Defina BUILD_COMMAND com o build real))
+	$(BUILD_COMMAND)

package/.pbai4devs/templates/ambiente-local/TEMPLATE.md

@@ -0,0 +1,48 @@
+---
+description: Perguntas e arquivos-base do ambiente após decidir a stack.
+status: modelo
+---
+
+# Ambiente local
+
+Preencha com as respostas e arquivos existentes. Este modelo não aprova
+tecnologia nem inicia o produto; copie os arquivos-base apenas na configuração
+técnica autorizada e substitua todos os parâmetros antes de executar.
+
+## Perguntas iniciais
+
+| Tema | O que esclarecer |
+| --- | --- |
+| Objetivo | Projeto novo, desenvolver existente ou reparar qual erro? |
+| Máquina | SO/arquitetura, Docker/Compose, recursos e restrições disponíveis? |
+| Aplicação | Linguagem/runtime, versões, gerenciador, lockfiles e Dockerfile? |
+| Serviços | Banco e versão, cache, filas, integrações e serviços externos? |
+| Acesso | Porta desejada, aplicações/hosts e necessidade de Traefik? |
+| Dados | Credenciais, volumes existentes, migrações e dados que preservar? |
+| Verificação | Comandos de build/test/lint, saúde e fluxo real a provar? |
+
+Se a porta for desconhecida, escolha uma livre após verificar conflitos e
+registre a decisão. Segredos ficam fora do Git; exemplos contêm só nomes e
+valores fictícios. Imagens e versões seguem decisões da stack.
+
+## Arquivos-base
+
+- [Compose](compose.local.yml.template): copie para
+  `infra/compose/compose.local.yml`;
+  defina imagem/build, porta, healthcheck e os serviços necessários.
+- [Makefile](Makefile.template): copie para `Makefile`; configure os comandos
+  de build/test/lint/saúde da stack, preservando alvos existentes.
+- [Dockerignore](dockerignore.template): copie para `.dockerignore` e adapte
+  ao contexto de build; mantenha código, fixtures e manifests necessários.
+
+A [regra de ambiente](../../rules/ambiente-local/RULE.md) define a estrutura
+obrigatória e o uso seguro de Docker/Traefik. Nenhum destes modelos substitui
+um Dockerfile real ou verifica o produto sem build e execução.
+
+O Makefile usa [`up --wait`][up]
+para aguardar saúde. O Compose usa
+[variáveis obrigatórias][variaveis]
+para impedir execução com parâmetros essenciais ausentes.
+
+[up]: https://docs.docker.com/reference/cli/docker/compose/up/
+[variaveis]: https://docs.docker.com/reference/compose-file/interpolation/

package/.pbai4devs/templates/ambiente-local/compose.local.yml.template

@@ -0,0 +1,16 @@
+# MODELO: configure imagem, comandos e servicos antes de usar.
+name: ${COMPOSE_PROJECT_NAME:?Defina COMPOSE_PROJECT_NAME}
+services:
+  app:
+    image: ${APP_IMAGE:?Defina APP_IMAGE com uma versao}
+    init: true
+    ports:
+      - "127.0.0.1:${APP_PORT:?Defina uma porta livre}:${APP_CONTAINER_PORT:?Defina a porta do container}"
+    healthcheck:
+      # Em imagens sem shell, substitua por ["CMD", "programa", "argumento"].
+      test: ["CMD-SHELL", "${APP_HEALTHCHECK:?Defina uma verificacao real de saude}"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+# Acrescente build/Dockerfile, volumes e banco/cache/filas conforme o projeto.
+# Traefik e opcional: configure hosts distintos e remova publicacoes redundantes.

package/.pbai4devs/templates/ambiente-local/dockerignore.template

@@ -0,0 +1,28 @@
+.git
+.pbai4devs
+.claude
+.codex
+.cursor
+.github
+.opencode
+.zcode
+.kimi-code
+.kimi
+.minimax
+.mimocode
+.dsh
+.vscode
+.agent-tests
+.env
+.env.*
+!.env.example
+**/node_modules
+**/__pycache__
+**/.venv
+**/test-results
+**/TestResults
+**/playwright-report
+**/blob-report
+**/tmp
+**/temp
+**/.DS_Store

package/.pbai4devs/templates/changelog/TEMPLATE.md

@@ -0,0 +1,17 @@
+---
+description: Mudanças observáveis e compatibilidade por entrega.
+status: modelo
+---
+
+# Histórico de alterações
+
+## Não lançado
+
+- [Mudança observável, correção ou alteração incompatível confirmada.]
+
+## Versão e data
+
+- [Comportamento entregue, referência e migração necessária, se houver.]
+
+[Use somente versões/datas reais e a convenção de releases adotada. Remova
+seções vazias; tarefas internas sem impacto não precisam virar notas públicas.]

package/.pbai4devs/templates/claude/TEMPLATE.md

@@ -0,0 +1,8 @@
+---
+description: Entrada do Claude para as instruções compartilhadas.
+status: modelo
+---
+
+# Instruções compartilhadas
+
+@AGENTS.md