@pathbit/agentdevkit 0.0.0-stage → 0.0.5

package/README.md

@@ -1,3 +1,89 @@
-# Temporary Holding Version
+---
+description: Instruções e fluxo de trabalho para agentes de código.
+language: pt
+---
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# AgentDevKit
+
+[English](README.en.md) · [Español](README.es.md) · [Pacote npm][npm-package]
+
+Uma forma de organizar o trabalho com agentes de código, do planejamento à
+verificação. Você mantém skills, regras, comandos e perfis em `.pbai4devs`;
+o kit gera os apontamentos que cada cliente sabe encontrar.
+
+Use com Codex, Claude, Cursor, Copilot, OpenCode e outros
+[clientes compatíveis](.pbai4devs/COMPATIBILIDADE.md). Há uma origem;
+cada cliente conserva seu formato de descoberta. No repositório, o código
+fica em `src/`, os testes em `tests/` e os recursos compartilhados em
+`.pbai4devs/`. Pastas nativas, entradas e preferências são geradas localmente.
+
+## Começar em um projeto
+
+Com Node.js 18+ e npm, execute na pasta do seu projeto, sem login:
+
+```console
+npx @pathbit/agentdevkit init
+```
+
+Escolha os agentes na pergunta inicial ou informe `--agents codex,claude`.
+A escolha fica salva no projeto; `agents` permite consultá-la ou alterá-la.
+Sem interação ou escolha anterior, o padrão é `all` (todos os clientes).
+
+Depois, abra o projeto no seu agente e peça:
+
+> Leia AGENTS.md e use a skill proximos-passos para orientar meu trabalho.
+
+Windows, instalação sem Node, simulação e atualização estão no
+[guia de instalação](docs/guides/installation.md). A distribuição usa a
+versão publicada no [npm público][packages] e na [release v0.0.5][release],
+sem instalação global. Instalação e atualização usam o pacote do registro;
+os arquivos da release servem para conferir os artefatos publicados.
+O idioma da CLI pode ser `pt`, `en` ou `es`.
+
+## Encontre o que precisa
+
+| Quero… | Ler |
+| --- | --- |
+| Entender e começar | [Wiki](docs/README.md) |
+| Planejar ou retomar um projeto | [Fluxo de trabalho](docs/guides/workflow.md) |
+| Criar uma skill ou comando | [Recursos](docs/guides/resources.md) |
+| Instalar ferramentas e comprovar uma entrega | [Ferramentas e testes][tests] |
+| Consultar opções ou resolver um erro | [CLI][cli] · [Soluções][help] |
+| Melhorar o próprio kit | [Contribuir](CONTRIBUTING.md) |
+| Experimentar os cenários | [Exemplos](https://github.com/pathbit/AgentDevKit/tree/master/examples) |
+
+## Desenvolver este repositório
+
+Com Node.js 24+ e npm, na raiz:
+
+```console
+npm ci --ignore-scripts
+npm run check
+npm test
+npm run examples
+```
+
+Os exemplos aparecem em `examples/generated/`. Para testar todos os cenários,
+use `npm run test:examples`; para verificar o pacote, `npm run verify`.
+O [guia de desenvolvimento](docs/maintainers/development.md) explica a árvore
+e os comandos.
+
+Instalar o kit prepara instruções. As ferramentas são instaladas por uma ação
+separada; PRD, design e specs surgem quando você inicia o planejamento.
+Projetos existentes preservam seu código e suas decisões.
+
+[Changelog](CHANGELOG.md) · [Roadmap](docs/product/roadmap.md) · [Licença MIT](LICENSE)
+
+Encontrou um problema ou tem uma ideia? [Abra uma issue][issues] pelos
+[formulários de contribuição](docs/maintainers/community.md).
+
+**[ Próximo passo ]** Siga a [instalação](docs/guides/installation.md) e peça
+ao seu agente para ler `AGENTS.md`.
+
+[tests]: docs/guides/tools-and-testing.md
+[cli]: docs/guides/cli.md
+[help]: docs/guides/troubleshooting.md
+[issues]: https://github.com/pathbit/AgentDevKit/issues/new/choose
+[packages]: docs/maintainers/packages.md
+[release]: https://github.com/pathbit/AgentDevKit/releases/tag/v0.0.5
+[npm-package]: https://www.npmjs.com/package/@pathbit/agentdevkit

package/bin/README.md

@@ -0,0 +1,8 @@
+---
+description: Entrada executável do pacote AgentDevKit.
+---
+
+# Executável
+
+`agentdevkit.mjs` prepara Node.js 24+ quando necessário e inicia a CLI.
+Este diretório pertence ao pacote; não é copiado para projetos atendidos.

package/bin/agentdevkit.mjs

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import { realpathSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { ensureRuntime, environmentWithNode } from '../.pbai4devs/scripts/preparar-ferramentas/BOOTSTRAP.mjs';
+
+const file = fileURLToPath(import.meta.url);
+export async function run(argv = process.argv.slice(2), options = {}) {
+  const version = options.nodeVersion || process.versions.node;
+  const language = argv.includes('en') ? 'en' : argv.includes('es') ? 'es' : 'pt';
+  if (!(options.bun ?? process.versions.bun) && Number(version.split('.')[0]) >= 24) {
+    const { main } = await import('../src/cli.mjs'); return main(argv, options);
+  }
+  let error;
+  try {
+    if (Number(version.split('.')[0]) < 18) throw new Error('Instale Node.js 24+ pelo gerenciador do sistema operacional.');
+    const runtime = await (options.ensureRuntime || ensureRuntime)({ root: resolve(dirname(file), '..'), run: options.spawn || spawnSync });
+    const result = (options.spawn || spawnSync)(runtime.node, [file, ...argv], { stdio: 'inherit', env: environmentWithNode(process.env, runtime.node) });
+    if (result.error) throw result.error;
+    return result.status ?? 1;
+  } catch (cause) { error = cause; }
+  const message = language === 'en' ? 'Could not prepare Node.js 24+.' : language === 'es' ? 'No se pudo preparar Node.js 24+.' : 'Não foi possível preparar Node.js 24+.';
+  const next = [{ command: 'https://nodejs.org/en/download', label: 'Node.js 24+' }];
+  const output = options.stdout || process.stdout;
+  if (argv.includes('--json')) output.write(`${JSON.stringify({ ok: false, command: 'runtime', language, message, detail: error?.message, next })}\n`);
+  else output.write(`${message}\n\n[ ${language === 'en' ? 'Next step' : language === 'es' ? 'Próximo paso' : 'Próximo passo'} ]\n  > ${next[0].command}\n`);
+  return 1;
+}
+
+function isEntrypoint() {
+  try { return Boolean(process.argv[1]) && realpathSync(resolve(process.argv[1])) === realpathSync(file); }
+  catch { return false; }
+}
+if (isEntrypoint()) process.exitCode = await run();

package/docs/README.md

@@ -0,0 +1,81 @@
+---
+description: Wiki do AgentDevKit, do primeiro uso à manutenção do kit.
+language: pt
+---
+
+# Wiki do AgentDevKit
+
+O AgentDevKit organiza instruções de trabalho para agentes de código. A pasta
+`.pbai4devs` guarda a origem; as pastas dos clientes apontam para ela. Você
+pode trocar de agente sem manter várias cópias das mesmas instruções.
+
+## Organização
+
+| Pasta | Conteúdo |
+| --- | --- |
+| [Guias](guides/README.md) | Instalação, uso, comandos e solução de problemas. |
+| [Produto](product/README.md) | Requisitos, experiência, arquitetura e roadmap. |
+| [Manutenção](maintainers/README.md) | Desenvolvimento, comunidade e publicação. |
+| [Specs](specs/README.md) | Escopo e critérios de aceite de cada incremento. |
+
+## Comece pelo seu objetivo
+
+| Objetivo | Caminho |
+| --- | --- |
+| Primeiro uso | [Instalar][install] → [seguir o fluxo][flow] |
+| Projeto em andamento | [Instalar com simulação][install] → [retomar][flow] |
+| Personalizar agentes | [Recursos][resources] → [compatibilidade][clients] |
+| Executar ou verificar algo | [CLI](guides/cli.md) → [ferramentas e testes][tests] |
+| Corrigir uma dificuldade | [Soluções e recuperação](guides/troubleshooting.md) |
+| Contribuir com o kit | [Contribuir][contrib] → [design](product/design.md) |
+| Desenvolver e experimentar | [Guia rápido][development] → [exemplos][examples] |
+| Preparar uma versão | [Manutenção e releases](maintainers/maintenance.md) |
+| Publicar ou instalar o pacote npm | [npm público](maintainers/packages.md) |
+| Relatar um bug ou propor melhoria | [Participar](maintainers/community.md) |
+
+## Entenda os termos
+
+| Termo | Significado |
+| --- | --- |
+| Skill | Procedimento que o agente segue para uma tarefa. |
+| Regra | Orientação aplicável a um contexto de trabalho. |
+| Comando | Entrada para executar um caso de uso. |
+| Perfil de agente | Papel especializado, como revisão. |
+| Adaptador | Traduz referências para o formato de cada cliente. |
+| Espelho | Apontamento gerado para um recurso da origem. |
+| Template | Modelo que será preenchido com decisões do projeto. |
+| Spec | Escopo de uma entrega com critérios verificáveis. |
+| Evidência | Registro de uma verificação realmente executada. |
+
+O agente lê e executa as instruções conforme as capacidades de seu cliente.
+A CLI instala, sincroniza e diagnostica arquivos. Ter um apontamento correto
+não comprova que determinado cliente carregou ou executou a skill.
+
+## Conheça este produto
+
+- [PRD](product/prd.md): problema, público, requisitos e limites.
+- [Experiência da CLI](product/ux-ui.md): interação, idiomas e saídas.
+- [Design técnico](product/design.md): componentes, estado e preservação de arquivos.
+- [Roadmap](product/roadmap.md) e [specs](specs/README.md): escopo das entregas.
+- [Changelog](../CHANGELOG.md): mudanças por versão.
+
+Esta wiki documenta **o AgentDevKit** e fica versionada junto ao código.
+Os projetos que recebem o kit usam os
+[templates](../.pbai4devs/templates/README.md) para seus próprios documentos,
+após perguntas e decisões. A instalação não copia esta wiki para `docs/`
+do projeto atendido.
+
+Os guias completos estão em português; os READMEs de entrada também existem
+em [inglês](../README.en.md) e [espanhol](../README.es.md). O idioma salvo pela
+CLI orienta a comunicação dos agentes, sem traduzir documentos existentes.
+
+[Voltar ao projeto](../README.md)
+
+[install]: guides/installation.md#instalar
+[flow]: guides/workflow.md
+[clients]: ../.pbai4devs/COMPATIBILIDADE.md
+[tests]: guides/tools-and-testing.md
+[contrib]: ../CONTRIBUTING.md
+[examples]: https://github.com/pathbit/AgentDevKit/tree/master/examples
+[resources]: guides/resources.md
+[development]: maintainers/development.md

package/docs/guides/README.md

@@ -0,0 +1,14 @@
+---
+description: Guias de instalação, uso e verificação do AgentDevKit.
+---
+
+# Guias de uso
+
+- [Instalação](installation.md)
+- [Comandos da CLI](cli.md)
+- [Fluxo de trabalho](workflow.md)
+- [Recursos dos agentes](resources.md)
+- [Ferramentas e testes](tools-and-testing.md)
+- [Solução de problemas](troubleshooting.md)
+
+[Voltar à documentação](../README.md)

package/docs/guides/cli.md

@@ -0,0 +1,81 @@
+---
+description: Comandos, opções e respostas do AgentDevKit.
+---
+
+# Referência da CLI
+
+Execute o pacote do npm público por `npx`, sem login:
+
+```console
+npx @pathbit/agentdevkit --help
+```
+
+Nas tabelas, `agentdevkit` representa esse executável. No checkout das fontes,
+use `npm run cli -- <comando>` ou `node bin/agentdevkit.mjs`.
+Esse código não é copiado ao projeto
+atendido; lá os comandos de manutenção usam o pacote por `npx`.
+
+## Comandos
+
+| Comando | Resultado |
+| --- | --- |
+| `init [pasta]` | Instala ou reaplica os recursos. |
+| `update` | Usa os recursos da versão do pacote executado. |
+| `sync` | Reconstrói as derivações da fonte do projeto. |
+| `sync --check` | Confere as derivações sem escrever. |
+| `doctor` | Diagnostica a instalação. |
+| `next` | Orienta a próxima etapa do projeto. |
+| `lang [idioma]` | Consulta ou altera o idioma: pt, en ou es. |
+| `agents` | Consulta clientes disponíveis e seleção local. |
+| `agents codex,claude` | Altera a seleção local. |
+| `agents all` | Habilita todos os clientes. |
+| `tools <ação>` | Executa o gerenciador de ferramentas. |
+| `--help`, `--version` | Ajuda ou versão do pacote. |
+
+Sem comando, a CLI executa `init`, que pode criar arquivos. `language` é alias
+de `lang`; `clients`, de `agents`. O idioma não traduz documentos existentes.
+
+## Opções
+
+| Opção | Uso |
+| --- | --- |
+| `--target <pasta>` | Projeto-alvo; não combine com a pasta de `init`. |
+| `--lang <idioma>` | Idioma desta execução. |
+| `--agents <lista>` | IDs separados por vírgula, ou `all`. |
+| `--clients <lista>` | Alias de `--agents`. |
+| `--yes`, `-y` | Evita perguntas iniciais; não força conflitos. |
+| `--dry-run` | Exibe o plano sem aplicar alterações. |
+| `--force` | Substitui conflitos gerenciados, com backup. |
+| `--json` | Produz uma resposta JSON para automação. |
+
+O primeiro uso interativo reúne idioma e clientes. Sem interação, valem as
+opções explícitas, a escolha local salva e, por último, `all`. Confira os
+[IDs e dependências](../../.pbai4devs/COMPATIBILIDADE.md).
+
+`update` não procura automaticamente a próxima versão: execute o pacote
+da versão desejada. `sync` não atualiza a fonte distribuída.
+A seleção e os derivados são locais; o source compartilhado permanece no Git.
+
+## Ferramentas
+
+As ações são `list`, `setup`, `install`, `update`, `check`, `info`, `run`
+e `unlock`. Consultar ou executar não instala silenciosamente.
+`setup` prepara as ferramentas compatíveis; outros comandos podem receber
+um nome ou grupo. Consulte [ferramentas e testes](tools-and-testing.md).
+
+## JSON e retorno
+
+As respostas incluem `ok`, `command`, `version`, `language`, `target` e
+`next`. Conforme a operação, há seleção, plano, conflitos, backup e erros.
+Leia os campos estruturados, não dependa da tradução da mensagem.
+
+| Código | Significado |
+| --- | --- |
+| `0` | Operação concluída; examine também o tipo da resposta. |
+| `1` | Falha, conflito ou diagnóstico com pendências. |
+| `2` | Argumentos inválidos; ferramentas podem propagar outros códigos. |
+
+`doctor` verifica o kit, não o produto inteiro. `next` pode terminar com
+sucesso enquanto orienta uma etapa ainda pendente.
+
+[Wiki](../README.md) · [Solução de problemas](troubleshooting.md)

package/docs/guides/installation.md

@@ -0,0 +1,78 @@
+---
+description: Instalação do AgentDevKit e geração local dos agentes.
+---
+
+# Instalação
+
+O pacote traz o gerador e as fontes compartilhadas. A instalação prepara
+`.pbai4devs` e cria somente os apontamentos dos agentes escolhidos.
+
+## Pré-requisitos
+
+Use Node.js 18+ com npm para iniciar o pacote. O launcher prepara Node 24+
+quando o runtime atual é antigo; o núcleo e as ferramentas usam Node 24+.
+A extração de runtime usa o executável nativo `tar`, sem scripts shell.
+
+Sem Node/npm, o agente precisa primeiro instalar o runtime pelo mecanismo do
+sistema operacional e continuar. `npx` não funciona antes dessa instalação.
+O [guia de preparo][bootstrap] explica as duas situações.
+
+## Instalar
+
+O pacote [`@pathbit/agentdevkit`](../maintainers/packages.md) é publicado no
+npm público. Execute na pasta do projeto, sem login:
+
+```console
+npx @pathbit/agentdevkit init
+```
+
+Sem comando adicional, o pacote executa `init`. Em terminal interativo,
+pergunta idioma e agentes. No aplicativo desktop, peça ao agente para reunir
+as escolhas no chat e usar `--lang` e `--agents` na CLI.
+
+Consulte [CLI](cli.md) para acrescentar seleção, destino e simulação. `--json`,
+`--yes`, `--dry-run` ou ausência de terminal interativo evitam perguntas.
+Sem escolha explícita ou salva, `all` mantém todos os clientes compatíveis.
+
+## O que fica no projeto
+
+| Conteúdo | Tratamento |
+| --- | --- |
+| `.pbai4devs` com recursos e templates | Fonte compartilhada versionável. |
+| Skills, regras e comandos nos clientes | Apontamentos locais gerados. |
+| Entradas da raiz criadas pelo kit | Arquivos locais gerados. |
+| Índices, manifesto e seleção pessoal | Derivados locais ignorados. |
+| Código, documentos e configurações humanas | Preservados. |
+| Downloads e resultados de testes | Locais e ignorados. |
+
+O gerador completo permanece no pacote npm. Ele não copia `bin/`, `src/`,
+`scripts/release/` ou os testes do produto para o projeto atendido.
+Instalar o kit não inicia uma aplicação nem instala todas as ferramentas.
+
+## Git e migração
+
+Um `.gitignore` dentro de `.pbai4devs` só controla essa árvore. Para os
+apontamentos externos, o kit gera exclusões locais do Git, sem ignorar
+workflows, formulários de issues ou configurações humanas em `.github`.
+Sem Git, uma proteção no `.gitignore` da raiz evita incluir os derivados
+quando o repositório for iniciado.
+
+Arquivos já rastreados exigem migração do índice: apenas saídas identificadas
+do kit podem deixar de ser rastreadas, preservando seus bytes no disco.
+Revise o plano e os conflitos em um projeto existente; use `--dry-run` antes
+de aplicar. Conteúdo humano não deve ser classificado como saída do gerador.
+
+## Atualizar e escolher agentes
+
+Use a versão desejada do pacote para executar `update`. A escolha salva
+continua válida; `agents` consulta e `agents codex,claude` altera a seleção.
+`agents all` habilita todos. As pastas compartilhadas permanecem quando
+necessárias para outro cliente, como `.agents` para Codex e Antigravity.
+
+O [fluxo de trabalho](workflow.md) orienta a próxima etapa do projeto.
+Se houver erro, consulte [solução de problemas](troubleshooting.md).
+
+[Wiki](../README.md) · [Release 0.0.5][release]
+
+[bootstrap]: ../../.pbai4devs/scripts/preparar-ferramentas/BOOTSTRAP.md
+[release]: https://github.com/pathbit/AgentDevKit/releases/tag/v0.0.5

package/docs/guides/resources.md

@@ -0,0 +1,121 @@
+---
+description: Tipos de recursos, fontes compartilhadas e ciclo de manutenção.
+---
+
+# Recursos compartilhados
+
+[Documentação](../README.md) · [Fluxo](workflow.md) ·
+[Ferramentas e testes](tools-and-testing.md)
+
+Edite a origem em `.pbai4devs`. As pastas dos clientes contêm referências e
+metadados de descoberta; editar uma cópia gerada cria divergência.
+O catálogo local `catalog.json` permite encontrar recursos por tipo.
+O hub permanece completo mesmo com poucos clientes selecionados. Apenas os
+apontamentos necessários são gerados; consulte ou altere a seleção com `agents`
+na [CLI](cli.md). Pastas compartilhadas podem atender mais de um cliente.
+
+## Escolher o tipo certo
+
+Os caminhos abaixo são relativos a `.pbai4devs/`.
+
+| Tipo | Responsabilidade | Fonte |
+| --- | --- | --- |
+| Skill | Procedimento e decisões. | `skills/<grupo>/<nome>/SKILL.md` |
+| Regra | Convenção aplicada a um contexto. | `rules/<nome>/RULE.md` |
+| Comando | Entrada de um caso de uso. | `commands/<nome>/COMMAND.md` |
+| Agente | Papel, ferramentas e limites. | `agents/<nome>/AGENT.md` |
+| Modelo | Base a preencher. | `templates/<nome>/TEMPLATE.md` |
+| Tool | Configuração e entrada de uma CLI. | `tools/<nome>/TOOL.json` |
+| Script | Automação executável reutilizável. | `scripts/<nome>/SCRIPT.mjs` |
+
+Uma skill explica como decidir; um script executa a operação. Um comando
+encaminha a essas fontes, sem repetir suas instruções. Uma regra mantém uma
+convenção recorrente; um agente define quem revisa ou executa determinado papel.
+
+Modelos não são documentos aprovados do produto. Ferramentas usam um
+`SCRIPT.mjs` fino para delegar ao instalador comum; não precisam de cópias em
+cada cliente nem de outro instalador escrito do zero.
+
+## Criar ou evoluir
+
+Comece por [criar-recurso][recurso] para localizar um fluxo já existente.
+Use o criador específico quando souber o tipo:
+
+- [criar-skill][skill]: procedimento reutilizável.
+- [criar-regra][regra]: convenção com contexto e ativação definidos.
+- [criar-comando][comando]: caso de uso e encaminhamento.
+- [criar-agente][agente]: perfil especializado, como revisão em leitura.
+
+```text
+Use criar-skill para orientar a revisão de contratos de API.
+Confira se há algo equivalente, reúna dúvidas e proponha uma fonte concisa.
+Reutilize scripts e ferramentas existentes; não copie instruções nos clientes.
+```
+
+Defina finalidade, entrada, saída, pré-requisitos e o que comprova a conclusão.
+Reúna dúvidas antes de tomar decisões. Detalhes opcionais podem ficar em
+referências próximas; o arquivo principal deve continuar fácil de encontrar.
+
+## Metadados e formatos
+
+Markdown usa frontmatter YAML e um H1. Skills precisam de `name` e
+`description`. Regras definem `trigger`: `always_on`, `model_decision`, `glob`
+ou `manual`; `glob` exige `globs`, e decisão do modelo exige descrição útil.
+
+Metadados específicos de um cliente ficam em YAML ao lado da fonte, como
+`agents/revisor/claude.yaml`. O manifesto registra sua aplicação. Para evoluir
+os adaptadores do AgentDevKit, edite `templates/clients/ADAPTERS.json` no hub.
+Consulte a [compatibilidade][compatibilidade] antes de prometer descoberta.
+
+O agrupamento varia conforme o formato realmente suportado pelo cliente.
+Uma referência correta não prova que o aplicativo a carregou automaticamente.
+Não use symlinks para substituir os apontamentos Markdown.
+
+## Sincronizar e conferir
+
+Após criar, editar, renomear ou remover uma fonte, execute na raiz do projeto:
+
+```sh
+node .pbai4devs/scripts/sincronizar-agentes/SCRIPT.mjs
+node .pbai4devs/scripts/sincronizar-agentes/SCRIPT.mjs --check
+node .pbai4devs/scripts/verificar-recursos/SCRIPT.mjs
+```
+
+O primeiro comando atualiza apontamentos e índices; `--check` só compara.
+O manifesto instalado respeita os clientes escolhidos. Não o substitua por uma
+lista de todos para reparar recursos; altere a seleção pela CLI se necessário.
+Conflitos de conteúdo próprio exigem revisão. Quando a substituição for
+intencional, `--force` faz backup local antes de reparar caminhos gerenciados.
+Não apague pastas inteiras para contornar um conflito.
+
+O `--force` desse script pode limpar extras nas quatro áreas dos clientes,
+com backup. Ele não equivale a `agentdevkit sync --force`: a CLI controla sua
+própria lista de arquivos e preserva recursos locais não registrados por ela.
+Escolha a operação pelo escopo; não prometa preservação indistinta.
+
+Não edite ou versione `catalog.json`, `skills.json`, `rules.json` ou
+`agents.json`: são derivados locais. Configurações nativas e documentos
+do projeto não devem ser substituídos por cópias desses índices.
+
+## O que permanece fora dos espelhos
+
+Somente os quatro tipos agênticos têm apontamentos: skills, regras, comandos
+e agentes. Modelos, scripts, tools, testes, estado e guias ficam na origem.
+Downloads de tools e [skills externas][externas] permanecem locais e ignorados.
+
+O código de testes e as fixtures necessárias são fontes versionáveis.
+Resultados não são fontes. Consulte os [modelos de ignore][ignore] e confira
+com Git que a alteração não ocultou arquivos necessários ou incluiu artefatos.
+Mantenha um README conciso ao criar uma pasta de primeiro nível no hub.
+
+**[ Próximo passo ]** Escolha o criador, edite a fonte e use sync/check.
+Para provas reais, consulte [ferramentas e testes](tools-and-testing.md).
+
+[recurso]: ../../.pbai4devs/skills/projeto/criar-recurso/SKILL.md
+[skill]: ../../.pbai4devs/skills/projeto/criar-skill/SKILL.md
+[regra]: ../../.pbai4devs/skills/projeto/criar-regra/SKILL.md
+[comando]: ../../.pbai4devs/skills/projeto/criar-comando/SKILL.md
+[agente]: ../../.pbai4devs/skills/projeto/criar-agente/SKILL.md
+[compatibilidade]: ../../.pbai4devs/COMPATIBILIDADE.md
+[externas]: ../../.pbai4devs/external-skills/README.md
+[ignore]: ../../.pbai4devs/templates/gitignore/TEMPLATE.md

package/docs/guides/tools-and-testing.md

@@ -0,0 +1,85 @@
+---
+description: Preparo das ferramentas e escolha de verificações reais.
+---
+
+# Ferramentas e testes
+
+O kit traz definições e automações. Instalar o kit não instala todas as tools
+nem escolhe a stack da aplicação. Consulte o [catálogo][tools].
+
+## Runtime e preparo
+
+O núcleo usa Node.js 24+ com npm. O launcher aceita Node 18+ e prepara o runtime
+atual quando necessário. Sem Node, o agente precisa instalá-lo pelo mecanismo
+do sistema operacional antes de iniciar `npx`.
+
+Para preparar somente o runtime a partir do hub:
+
+```console
+node .pbai4devs/scripts/preparar-ferramentas/BOOTSTRAP.mjs --runtime-only
+```
+
+O mesmo JavaScript atende aos sistemas suportados. Não há bootstrap PowerShell,
+SH ou Bash no kit. O executável nativo `tar` é usado sem shell para extrair o
+arquivo oficial após conferir SHA-256. Veja o [guia do bootstrap][bootstrap].
+
+Quando a tarefa pedir instalação das ferramentas:
+
+```console
+node .pbai4devs/scripts/preparar-ferramentas/SCRIPT.mjs setup
+```
+
+`setup` reutiliza instalações saudáveis e verifica as compatíveis. Um nome
+ou grupo limita a seleção. `check`, `info` e `run` não trocam uma consulta
+por instalação. Downloads, caches e recibos permanecem locais e ignorados.
+
+## Escolher a prova
+
+| Mudança | Verificação |
+| --- | --- |
+| Lógica ou API | Testes e assertivas de resultado. |
+| Fluxo web | Navegador real, ações e resultado visível. |
+| Aplicativo desktop | Abrir o aplicativo e executar o fluxo. |
+| Documento visual | Renderizar ou abrir o artefato e inspecionar. |
+| Gerador e Git | Instalar, sincronizar e comparar arquivos/índice. |
+
+Use [verificar-trabalho][verify] para vincular aceites às provas. Web pode usar
+[agent-browser][browser] ou o conector Playwright; desktop pode usar
+[agent-desktop][desktop]. Confira console, rede, permissões e efeitos reais.
+Uma captura isolada não demonstra o funcionamento completo.
+
+## Verificar o AgentDevKit
+
+No checkout, `npm test` verifica o produto; `npm run test:infra` verifica as
+automações compartilhadas; `npm run check` valida as fontes. Os perfis de
+[CI](../maintainers/maintenance.md) evitam repetir a suíte completa em cada sistema.
+
+Os testes do produto ficam em `tests/`, na raiz. Os testes compartilhados
+ficam em `scripts/<nome>/tests/` dentro do hub. Em uma aplicação atendida,
+o código de testes segue os diretórios acordados para aquele projeto.
+
+A [matriz de maturidade][matrix] usa oito projetos sintéticos. Ela comprova
+contratos do kit; não aprova um produto real nem certifica todos os aplicativos.
+Os pareceres simulados dessa matriz não substituem revisão independente.
+Use `npm run examples` para preparar as cópias e `npm run test:examples`
+para executá-las em `examples/generated/`. O [guia dos exemplos][examples]
+explica cada cenário; o [guia de desenvolvimento](../maintainers/development.md)
+reúne as verificações do repositório.
+
+## Guardar os resultados
+
+Código de testes e fixtures são versionados. Relatórios, capturas, vídeos,
+downloads e saídas locais são ignorados, inclusive `.playwright*` em qualquer
+caixa. Registre passou, falhou ou não verificado; não transforme ausência de
+prova em sucesso. Feche a entrega pela [revisão][review].
+
+[Wiki](../README.md) · [Recursos](resources.md)
+
+[tools]: ../../.pbai4devs/tools/README.md
+[bootstrap]: ../../.pbai4devs/scripts/preparar-ferramentas/BOOTSTRAP.md
+[verify]: ../../.pbai4devs/skills/projeto/verificar-trabalho/SKILL.md
+[browser]: ../../.pbai4devs/tools/agent-browser/README.md
+[desktop]: ../../.pbai4devs/tools/agent-desktop/README.md
+[matrix]: ../../.pbai4devs/scripts/testar-maturidade/README.md
+[review]: ../../.pbai4devs/commands/revisar-entrega/COMMAND.md
+[examples]: https://github.com/pathbit/AgentDevKit/tree/master/examples