Satlab Protocol

English · Português (BR)

English

A repository of skills for coding agents (Claude Code, Cursor, and compatible tools). The core is the SatLab Protocol: a full stack, stack- and project-type-agnostic engineering workflow — meant for any codebase you work on (backend, frontend, mobile, CLI, data, and so on).

To install it in a project via npm, use the published package: npx @satlab/protocol init copies skills and rules, configures Lexomni in the IDE's mcp.json, and offers a guided Context7 setup (npx ctx7 setup) — you do not need to install those MCPs by hand beforehand (just follow the wizard and restart the IDE when asked). The default content (SatLab guidelines) to index in Lexomni comes from the satlab-lexomni repository and must be copied or downloaded from there, per that project's instructions — it is not bundled into @satlab/protocol.

Beyond the orchestrator there are subskills used only when they earn their place: library/API documentation (Context7), large-scale refactoring, critical code review, E2E tests for browser flows and, only when the task involves a web interface, frontend implementation, stack-specific guidelines, motion, and UI review.

When work is organized into sprints, the board of record is GitHub Issues/Projects: the agent creates the issue (with your approval on the text), names the sprint folder after its number, ties every commit back with (#N), and closes the loop through gh after you confirm the merge.

Roles

• Human: owner of business rules, priorities, trade-offs, sign-off, and the architectural decisions that matter.
• Agent: technical executor following SKILL.md — specification, tests, code, refactoring, and review in the protocol's format.

What lives in this repository

| Path (repo root) | Contents | |------------------|----------| | skills/satlab-protocol/SKILL.md | The complete protocol, written for the agent | | skills/satlab-protocol/templates.md | Templates for aligning requirement, spec, ADR, and plan (team + agent) | | rules/satlab-protocol.mdc | Cursor/Claude rule (copied to .cursor/rules or .claude/rules by init) | | skills/satlab-protocol/context7-mcp/ | Helper skill: current library/API docs via Context7 | | skills/satlab-protocol/large-scale-refactor/ | Large refactors and structural migrations | | skills/satlab-protocol/critical-code-review/ | Code review in auditor mode | | skills/satlab-protocol/security-scan/ | Mandatory at the end of every implementation: security sweep — trust boundary, object-level authorization, timing side channels, secret exposure, cache on shared layers, rate limiting, disclosure, dependency advisories. Produces security-scan.md; every finding is the human's to decide | | skills/satlab-protocol/backend-guidelines/ | Mandatory on any backend task: how the server behaves — trust boundary, caching and invalidation, transactions, idempotency, query shape, pagination, safe migrations, background work, external failure. Stack-agnostic | | skills/satlab-protocol/frontend-master/ | Mandatory on any frontend task: how the interface looks — aesthetic direction, typography, color, composition | | skills/satlab-protocol/frontend-guidelines/ | Mandatory alongside frontend-master: how it behaves and communicates — server/client boundary, separation of responsibilities, end-user copy, loading/empty/error states, accessibility floor. Stack-agnostic | | skills/satlab-protocol/web-design-guidelines/ | UI and accessibility audit during critical code review | | skills/satlab-protocol/design-motion-principles/ | Motion and interaction: Create mode (build purposeful motion) and Audit mode (review existing animation, emit an HTML report) | | skills/satlab-protocol/generating-end-to-end-tests/ | E2E tests (Playwright, Cypress, Selenium) for multi-step user workflows | | skills/satlab-protocol/llm-council/ | On demand: high-stakes decisions — 5 advisors, peer review, chairman synthesis |

Subskills live inside the main skill's directory (satlab-protocol/<name>/SKILL.md), not at the top level of .claude/skills/. An ls .claude/skills will not list them — that is expected, not a broken install.

Project install (recommended): from the project root, run npx @satlab/protocol init. The wizard copies skills/ and rules/ into .cursor/skills, .cursor/rules (or the .claude/... equivalent), wires Lexomni into mcp.json, and asks whether to run Context7 right away (use --skip-context7 to skip the question). Then use the satlab-lexomni repository for the SatLab Lexomni content (clone or download).

Supported targets

One run installs into as many of these as you pick. The wizard labels each by the folder, with the tool name as a caption, because the folder is what actually matters.

| Folder | Tools that read it | MCP | |---|---|---| | .claude/skills/ · .claude/rules/ · CLAUDE.md | Claude Code | .mcp.json (project) | | .cursor/skills/ · .cursor/rules/ | Cursor | .cursor/mcp.json | | .github/instructions/ · .github/copilot-instructions.md | GitHub Copilot | .vscode/mcp.json (servers key) | | .clinerules/ | Cline | — | | .roo/rules/ | Roo Code | — | | .devin/rules/ · .windsurf/rules/ | Devin Desktop (formerly Windsurf) | vendor config | | .junie/rules/ · .junie/AGENTS.md | JetBrains Junie | — | | .continue/rules/ | Continue | — | | AGENTS.md | Codex, Gemini CLI, Zed, Aider, Jules, Amp — 30+ agents | — |

AGENTS.md is the widest reach for the least effort. It is stewarded by the Agentic AI Foundation at the Linux Foundation, and several tools read nothing else. It installs on its own, creating no folder. When the file already exists, your own content is preserved — the protocol's section lives inside a managed block and only that block is rewritten.

Installation

Via npm package (recommended)

1. In the project folder, or a folder shared across projects: npx @satlab/protocol init.
2. Pick where it goes. The wizard lists the folder each tool reads — .claude/skills/, .cursor/rules/, .github/instructions/, AGENTS.md and others — and pre-selects whatever it already found in your project. Pick as many as you need; one run installs them all.
3. Complete the rest of the menu (file copy, Lexomni, optional Context7).
4. Restart your editor and register the satlab-protocol skill per your tool's documentation.
5. Get the default Lexomni content (SatLab) from the satlab-lexomni repository — clone or download it and follow its instructions to copy/configure the material into Lexomni (index and guidelines). That content is not shipped inside @satlab/protocol.

You do not need to install the Lexomni server or Context7 by hand first: init handles the mcp.json entry and the Context7 flow when you accept it. satlab-lexomni is only the source of the indexed material, not the MCP binary.

Runtime requirement: Node >=23.5.0 || ^22.13.0 || ^20.17.0. On Node 18 the CLI dies with a SyntaxError inside @inquirer/core — styleText from node:util only exists from 20.12 onward.

Updating a project that already has it

npx @satlab/protocol@latest update

Run it from the root of a project that has already been through init. It reads .satlab/targets.json to know which targets you installed, so it asks nothing about where. It then compares the manifest shipped in the package against what is installed, file by file, and labels each one:

| | State | What it means | |---|---|---| | · | up to date | Installed version matches the packaged one | | ↑ | update | Versions differ — shows installed → new | | + | new | The file is in the package and not in your project | | ✎ | edited locally | You changed this file after installing. It is never overwritten without a separate confirmation | | ✕ | no longer shipped | The file left the package. Removal is a separate question, defaulting to no |

Nothing is copied or deleted without your approval, and files outside the protocol's manifest are never touched. A project installed before 2.0.0 has no .satlab/targets.json; the first update infers the targets from the manifests already installed, records them once, and carries on.

Always use @latest. Without it npx reuses whatever tree it downloaded at some point and runs an old CLI — which then compares its own manifest against your project and reports everything up to date while you are behind. If in doubt, check with npx @satlab/protocol@latest --version; to clear the cache, delete the matching folder under ~/.npm/_npx/.

Manual (clone or copy this repository)

1. Clone the repository or copy the folder you want into the project.
2. Put the skills where your tool loads them from (e.g. ./.cursor/skills or ./.claude/skills).
3. Register the satlab-protocol skill pointing at the corresponding SKILL.md, per your client's documentation (Cursor, Claude Code, etc.).
4. In this mode, configure Lexomni and Context7 by hand — see the table below. Note that the MCP file differs per tool: Claude Code reads .mcp.json at the project root, Cursor reads .cursor/mcp.json, and VS Code reads .vscode/mcp.json with a servers key instead of mcpServers.
5. Use the satlab-lexomni repository as the source of the default content (SatLab guidelines) to copy or download and hook into Lexomni, per the satlab-lexomni README.

Dependencies (MCPs)

Anyone using npx @satlab/protocol init already gets Lexomni applied to mcp.json and can finish Context7 through the wizard itself. The links below are reference material (documentation, troubleshooting, or manual installation if you skip the CLI):

| Tool | What for | |------|----------| | Lexomni (MCP) | Guidelines and references for your process — install / usage | | Context7 (MCP) | Current library and API documentation — install |

Default Lexomni content (SatLab)

The default SatLab guidelines and documents for Lexomni are not embedded in this repository or in the npm package: get them from the satlab-lexomni repository — clone or download that project and follow its instructions to make the content available to Lexomni (copying, paths, and indexing).

init only registers the Lexomni MCP server in the IDE; loading the SatLab index from satlab-lexomni is a separate step, described in the satlab-lexomni repository itself and in the Lexomni documentation.

The details of when and how the agent uses each MCP live in SKILL.md and the subskills.

How to work with it

• Be explicit in the request: the problem, the expected behavior, what counts as done, and what is out of scope. The agent will ask for whatever is missing — answering early avoids rework.
• Take part in the decisions that are not just code: new patterns, exceptions to ADRs, stack choices on a new project, the team's definition of done.
• On large or risky changes, align spec and tests with the agent before implementation; the protocol expects this — your job is to validate that the tests reflect the right business rule.
• You do not need to memorize phases or checklists: the agent runs the step-by-step per SKILL.md. This README only makes clear what you need to have in place (a project with the protocol installed — preferably via npx @satlab/protocol init) and how to participate (requirement, sign-off, ADRs).

Values the protocol assumes, shared by team and agent: without a verifiable specification there is no solid basis for a test; without a test before production code the loop does not close; a "green" delivery includes minimal refactoring and a critical review at the end — the operational detail is in SKILL.md.

The gates only you can open

As of 1.7.0 the protocol has points where the agent stops and waits for you. These are not ceremony: each one exists because something got through before.

| Gate | What the agent does | What it never does alone | |------|---------------------|---------------------------| | Sprint issue | Writes title and body from the deepened requirement and shows them to you | Run gh issue create without your approval — issue text is public and permanent | | Commit | Proposes the message as type(scope): description(#N) and stages by explicit path | Commit without an approved message, use git add ., or commit non-chore work on the default branch | | Push and merge | Tells you what is pending publication and hands you the command | git push. Publishing is always yours | | Parallel execution | Points out which tasks are independent and asks whether to run them across agents, and how many | Spawn a subagent on its own judgement, or exceed the number you named | | Closing the sprint | Comments the delivery and closes the issue through gh | Close before you confirm the merge — "green" is not a merge | | Security findings | Sweeps every implementation, writes security-scan.md, and brings each finding to you separately | Fix a finding or open an issue for it on its own judgement. You choose per finding: fix now, issue, or accepted risk |

On top of that, the agent does not propose committing code that was not exercised end to end: whenever the change touches an SDK, an API, a database, or the network, it hands you a manual test path against the real system, plus what a healthy run prints. A green suite says the logic is right, not that it works.

What the sprint leaves behind

A rule that got settled, tested end to end, and signed off by you becomes a skill inside the repository it governs (<repo>/.claude/skills/) — not one more ADR, not a note in the global skills. An ADR records why something was decided, once; a skill records how the work is done from now on, and carries the scars: what broke before, what the obvious approach gets wrong. That accumulation is exactly what the skill sweep at the start of the next sprint will find.

When this package makes sense

When you want work driven by requirements, tests, refactoring, and structured review — from a bug fix to a feature, an architecture decision, or a brand-new project — without being tied to a specific stack.

Português (BR)

Repositório de skills para agentes (Claude Code, Cursor e ferramentas compatíveis). O núcleo é o SatLab Protocol: fluxo de engenharia full stack e agnóstico de stack e de tipo de projeto — pensado para qualquer codebase em que vocês trabalhem (backend, frontend, mobile, CLI, dados, etc.).

Para instalar no projeto via npm, use o pacote publicado: o comando npx @satlab/protocol init copia skills e regras, configura o Lexomni no mcp.json do IDE e oferece o setup do Context7 (npx ctx7 setup) de forma guiada — não é necessário instalar esses MCPs manualmente antes (basta seguir o assistente e reiniciar o IDE quando pedido). O conteúdo padrão (guidelines SatLab) para indexar no Lexomni vem do repositório satlab-lexomni e deve ser copiado ou baixado de lá, conforme as instruções desse projeto — não é embutido no @satlab/protocol.

Além do orquestrador, há sub-skills usadas só quando faz sentido: documentação de libs/APIs (Context7), refatoração em larga escala, revisão crítica de código, testes E2E de fluxos de browser e, só se a tarefa envolver interface web, implementação de frontend, diretrizes de stack, motion e revisão de UI.

Quando o trabalho é organizado em sprints, o quadro de referência é o GitHub Issues/Projects: o agente cria a issue (com seu aceite no texto), nomeia a pasta da sprint pelo número dela, amarra cada commit de volta com (#N) e fecha o ciclo pelo gh depois que você confirma o merge.

Papéis

• Humano: dono de regra de negócio, prioridades, trade-offs, aceite e decisões arquiteturais que importam.
• Agente: executor técnico que segue o SKILL.md — especificação, testes, código, refatoração e revisão no formato do protocolo.

O que existe neste repositório

| Caminho (raiz do repo) | Conteúdo | |------------------------|----------| | skills/satlab-protocol/SKILL.md | Protocolo completo para o agente | | skills/satlab-protocol/templates.md | Modelos úteis para alinhar requisito, spec, ADR e plano (time + agente) | | rules/satlab-protocol.mdc | Regra Cursor/Claude (copiada para .cursor/rules ou .claude/rules pelo init) | | skills/satlab-protocol/context7-mcp/ | Skill auxiliar: docs atuais de libs/APIs via Context7 | | skills/satlab-protocol/large-scale-refactor/ | Refatorações grandes ou migrações estruturais | | skills/satlab-protocol/critical-code-review/ | Revisão de código em modo auditor | | skills/satlab-protocol/security-scan/ | Obrigatória ao fim de toda implementação: varredura de segurança — fronteira de confiança, autorização no nível do objeto, canais laterais de tempo, exposição de segredo, cache em camada compartilhada, rate limit, vazamento em erro e log, advisories de dependência. Gera security-scan.md; cada achado é decisão do humano | | skills/satlab-protocol/backend-guidelines/ | Obrigatória em qualquer tarefa de backend: como o servidor se comporta — fronteira de confiança, cache e invalidação, transações, idempotência, formato de query, paginação, migração segura, trabalho em background, falha externa. Agnóstica de stack | | skills/satlab-protocol/frontend-master/ | Obrigatória em qualquer tarefa de frontend: como a interface se parece — direção estética, tipografia, cor, composição | | skills/satlab-protocol/frontend-guidelines/ | Obrigatória junto da frontend-master: como ela se comporta e comunica — fronteira server/client, separação de responsabilidades, texto para o usuário final, estados de loading/vazio/erro, piso de acessibilidade. Agnóstica de stack | | skills/satlab-protocol/web-design-guidelines/ | Auditoria de UI e acessibilidade durante a revisão crítica | | skills/satlab-protocol/design-motion-principles/ | Motion e interação: modo Create (construir animação com propósito) e modo Audit (revisar animação existente e emitir relatório HTML) | | skills/satlab-protocol/generating-end-to-end-tests/ | Testes E2E (Playwright, Cypress, Selenium) para fluxos de usuário multi-step | | skills/satlab-protocol/llm-council/ | Sob demanda: decisões de alto risco — 5 advisors, peer review e síntese do chairman |

As sub-skills moram dentro do diretório da skill principal (satlab-protocol/<nome>/SKILL.md), não na raiz de .claude/skills/. Um ls .claude/skills não lista elas — isso é esperado, não é instalação quebrada.

Instalação no projeto (recomendado): na raiz do projeto, rode npx @satlab/protocol init. O assistente copia skills/ e rules/ para .cursor/skills, .cursor/rules (ou equivalente .claude/...), integra o Lexomni ao mcp.json e pergunta se deseja rodar o Context7 na hora (use --skip-context7 para pular a pergunta). Em seguida, use o repositório satlab-lexomni para o conteúdo Lexomni SatLab (clone ou download).

Alvos suportados

Uma execução instala em quantos você marcar. O assistente rotula cada um pela pasta, com o nome da ferramenta como legenda, porque é a pasta que importa de fato.

| Pasta | Ferramentas que leem | MCP | |---|---|---| | .claude/skills/ · .claude/rules/ · CLAUDE.md | Claude Code | .mcp.json (projeto) | | .cursor/skills/ · .cursor/rules/ | Cursor | .cursor/mcp.json | | .github/instructions/ · .github/copilot-instructions.md | GitHub Copilot | .vscode/mcp.json (chave servers) | | .clinerules/ | Cline | — | | .roo/rules/ | Roo Code | — | | .devin/rules/ · .windsurf/rules/ | Devin Desktop (ex-Windsurf) | config do fornecedor | | .junie/rules/ · .junie/AGENTS.md | JetBrains Junie | — | | .continue/rules/ | Continue | — | | AGENTS.md | Codex, Gemini CLI, Zed, Aider, Jules, Amp — mais de 30 agentes | — |

O AGENTS.md é o maior alcance pelo menor esforço. É mantido pela Agentic AI Foundation, na Linux Foundation, e várias ferramentas não leem mais nada além dele. Instala sozinho, sem criar pasta nenhuma. Se o arquivo já existir, o que você escreveu é preservado — a seção do protocolo vive num bloco gerenciado e só esse bloco é reescrito.

Instalação

Via pacote npm (recomendado)

1. Na pasta do projeto ou pasta em comum entre projetos: npx @satlab/protocol init.
2. Escolha onde instalar. O assistente lista a pasta que cada ferramenta lê — .claude/skills/, .cursor/rules/, .github/instructions/, AGENTS.md e outras — e já vem com o que ele encontrou no seu projeto pré-marcado. Marque quantas quiser; uma execução instala em todas.
3. Conclua o resto do menu (cópia de arquivos, Lexomni, Context7 opcional).
4. Reinicie o editor e registre o skill satlab-protocol conforme a documentação da sua ferramenta.
5. Obtenha o conteúdo padrão Lexomni (SatLab) a partir do repositório satlab-lexomni — clone ou baixe o repositório e siga as instruções dele para copiar/configurar o material no Lexomni (índice e guidelines). Esse conteúdo não é distribuído dentro do @satlab/protocol.

Não é preciso instalar manualmente o servidor Lexomni nem o Context7 antes: o init cuida da entrada no mcp.json e do fluxo do Context7 quando você aceitar. O satlab-lexomni é só a fonte do material indexado no Lexomni, não o binário do MCP.

Requisito de runtime: Node >=23.5.0 || ^22.13.0 || ^20.17.0. Em Node 18 o CLI quebra com SyntaxError no @inquirer/core — o styleText de node:util só existe a partir do 20.12.

Atualizar um projeto já instalado

npx @satlab/protocol@latest update

Rode na raiz do projeto que já passou pelo init. Ele lê o .satlab/targets.json para saber onde você instalou, então não pergunta nada sobre destino. Depois compara o manifesto do pacote com o instalado, arquivo por arquivo, e rotula cada um:

| | Estado | O que significa | |---|---|---| | · | up to date | Versão instalada igual à empacotada | | ↑ | update | Versões diferentes — mostra instalada → nova | | + | new | Arquivo está no pacote e não no seu projeto | | ✎ | edited locally | Você editou esse arquivo depois de instalar. Nunca é sobrescrito sem confirmação separada | | ✕ | no longer shipped | O arquivo saiu do pacote. A remoção é pergunta à parte, com default não |

Nada é copiado nem apagado sem o seu aceite, e arquivos fora do manifesto do protocolo nunca são tocados. Projeto instalado antes da 2.0.0 não tem .satlab/targets.json; o primeiro update infere os alvos a partir dos manifestos já instalados, registra uma vez e segue.

Use sempre @latest. Sem isso o npx reaproveita a árvore que já baixou em algum momento e executa uma versão antiga do CLI — que vai comparar o manifesto dela com o seu projeto e reportar "tudo atualizado" estando desatualizado. Se desconfiar, confira com npx @satlab/protocol@latest --version; para limpar o cache, apague a pasta correspondente em ~/.npm/_npx/.

Manual (clone ou cópia deste repositório)

1. Clone o repositório ou copie a pasta desejada para o projeto.
2. Coloque as skills onde a ferramenta as carrega (ex.: ./.cursor/skills ou ./.claude/skills).
3. Registrem o skill satlab-protocol apontando para o SKILL.md correspondente, conforme a documentação do cliente (Cursor, Claude Code, etc.).
4. Nesse modo, configure Lexomni e Context7 à mão — veja a tabela abaixo. Atenção: o arquivo de MCP muda por ferramenta: o Claude Code lê .mcp.json na raiz do projeto, o Cursor lê .cursor/mcp.json, e o VS Code lê .vscode/mcp.json com a chave servers em vez de mcpServers.
5. Use o repositório satlab-lexomni como fonte do conteúdo padrão (guidelines SatLab) a ser copiado ou baixado e ligado ao Lexomni, conforme o README do satlab-lexomni.

Dependências (MCPs)

Quem usa npx @satlab/protocol init já recebe o Lexomni aplicado no mcp.json e pode concluir o Context7 pelo próprio assistente. Os links abaixo servem como referência (documentação, troubleshooting ou instalação manual se você não usar o CLI):

| Ferramenta | Para quê | |------------|----------| | Lexomni (MCP) | Guidelines e referências do seu processo — instalação / uso | | Context7 (MCP) | Documentação atual de bibliotecas e APIs — instalação |

Conteúdo padrão Lexomni (SatLab)

O material padrão de guidelines e documentos SatLab para o Lexomni não fica embutido neste repositório nem no pacote npm: deve ser obtido a partir do repositório satlab-lexomni — clone ou baixe esse projeto e siga as instruções dele para disponibilizar o conteúdo ao Lexomni (cópia, caminhos e indexação).

O init apenas registra o servidor MCP Lexomni no IDE; carregar o índice SatLab a partir do satlab-lexomni é um passo separado, descrito no próprio repositório satlab-lexomni e na documentação do Lexomni.

Detalhes de quando e como o agente usa cada MCP estão no SKILL.md e nas sub-skills.

Como proceder

• Seja explícito no pedido: problema, comportamento esperado, o que conta como pronto e o que está fora de escopo. O agente vai pedir o que faltar — responder cedo evita retrabalho.
• Participe das decisões que não são só código: novos padrões, exceções a ADRs, stack em projeto novo, definição de “pronto” em time.
• Nas mudanças grandes ou arriscadas, alinhem spec e testes com o agente antes da implementação; o protocolo prevê isso — o seu papel é validar se os testes refletem a regra de negócio certa.
• Não precisa decorar fases nem checklist: quem executa o passo a passo é o agente segundo o SKILL.md. O README só deixa claro o que vocês precisam ter (projeto com protocolo instalado — de preferência via npx @satlab/protocol init) e como participar (requisito, aceite, ADRs).

Valores que o protocolo pressupõe (comuns ao time e ao agente): sem especificação verificável não há base sólida para teste; sem teste antes do código de produção o fluxo não fecha; entrega “green” inclui refatoração mínima e revisão crítica no fim — o detalhe operacional está no SKILL.md.

Os portões que só você abre

A partir da 1.7.0 o protocolo tem pontos em que o agente para e espera você. Não são formalidade: cada um existe porque algo escapou antes.

| Portão | O que o agente faz | O que ele nunca faz sozinho | |--------|--------------------|------------------------------| | Issue da sprint | Escreve título e corpo a partir do requisito aprofundado e te mostra | Rodar gh issue create sem seu aceite — texto de issue é público e permanente | | Commit | Propõe a mensagem no formato tipo(escopo): descrição(#N) e faz stage por caminho explícito | Comitar sem aprovação da mensagem, usar git add ., ou comitar trabalho que não seja chore na branch default | | Push e merge | Diz o que está pendente de publicação e te entrega o comando | git push. Publicação é sempre sua | | Execução paralela | Aponta quais tasks são independentes e pergunta se roda em multiagentes e quantos | Abrir subagente por conta própria, ou passar do número que você disse | | Fechar a sprint | Comenta a entrega e fecha a issue pelo gh | Fechar antes de você confirmar o merge — "green" não é merge | | Achados de segurança | Varre toda implementação, escreve o security-scan.md e traz cada achado separadamente | Corrigir um achado ou abrir issue por conta própria. Você escolhe por achado: corrigir agora, issue, ou risco aceito |

Além disso, o agente não propõe commit de código que não foi exercitado ponta a ponta: quando a mudança toca SDK, API, banco ou rede, ele te entrega um caminho de teste manual contra o sistema real, com o que uma execução saudável imprime. Suíte verde diz que a lógica está certa, não que funciona.

O que fica para trás quando a sprint acaba

Regra que ficou definida, testada ponta a ponta e aprovada por você vira skill dentro do repositório que ela governa (<repo>/.claude/skills/) — não um ADR a mais, não anotação na global. O ADR registra por que algo foi decidido, uma vez; a skill registra como o trabalho é feito daqui em diante, e carrega as cicatrizes: o que quebrou antes, o que a abordagem óbvia erra. É esse acúmulo que a varredura de skills no início da próxima sprint vai encontrar.

Quando faz sentido usar este pacote

Quando quiserem trabalho orientado a requisito, testes, refatoração e revisão estruturada — desde correção de bug até feature, definição de arquitetura ou projeto novo — sem amarrar a um stack específico.