Config AGENTS.md
Gera AGENTS.md (arquivo de instruções para agentes de IA no padrão opencode) na raiz do projeto e em cada submódulo/subapp, a partir da descoberta real da estrutura (não de suposições).
Este skill produz documentação de contexto, não código de aplicação. O AGENTS.md raiz é o mapa; cada AGENTS.md de submódulo é o contrato local daquele módulo.
Quando usar
| Cenário |
Ação |
Monorepo com submódulos Git (microservices/*, apps/*, packages/*) |
AGENTS.md raiz + 1 por submódulo |
| Monorepo de workspace (TurboRepo, Cargo workspace, Gradle multi-module, .sln) |
AGENTS.md raiz + 1 por pacote/módulo relevante |
| Repositório único (single app) |
Apenas AGENTS.md raiz |
| Camadas da arquitetura como pastas/módulos |
1 por camada quando ela tem build/test próprios |
| Já existe AGENTS.md |
Atualizar preservando seções manuais (merge por marcadores) |
Se o usuário não especificar o escopo, detecte (Fase 0) e proponha a lista de arquivos antes de escrever.
Fase 0 — Descoberta da estrutura
Nunca assuma a topologia. Rode a detecção:
# 1. É monorepo? Submodules?
test -f .gitmodules && cat .gitmodules
# 2. Workspaces JS
cat package.json | grep -A20 '"workspaces"'
# 3. Gradle multi-module
cat settings.gradle 2>/dev/null || cat settings.gradle.kts 2>/dev/null
# 4. Cargo workspace
cat Cargo.toml 2>/dev/null | grep -A20 '\[workspace\]'
# 5. Solução .NET
find . -maxdepth 2 -name '*.sln'
# 6. Package managers por pasta
find . -maxdepth 3 \( -name package.json -o -name build.gradle -o -name build.gradle.kts \
-o -name pom.xml -o -name Cargo.toml -o -name '*.csproj' -o -name pubspec.yaml \
-o -name angular.json -o -name go.mod \) -not -path '*/node_modules/*' 2>/dev/null
Consultar references/discovery.md para o fluxo completo (submodules Git, workspaces, monorepo de microserviços).
Regra de fronteira de módulo
Um módulo é candidato a AGENTS.md próprio quando tem build/test independentes (build file próprio, settings.gradle que o inclui, workspaces entry, [workspace] members, ou entrada em .gitmodules).
Cada submódulo de microserviço = 1 AGENTS.md. Cada app de frontend/mobile = 1 AGENTS.md. Camada pura (ex.: domain/) só ganha AGENTS.md se tiver build próprio.
Fronteiras entre camadas: proteja com lint de arquitetura (dependency-cruiser/ESLint boundaries, ArchUnit, NetArchTest, Cargo/clippy) — ver ../docs/guides/layer-boundary-enforcement.md. Camada vira submódulo só com ciclo de vida/release próprio (ex.: shared kernel), nunca só para impedir import.
Fase 0.1 — Rastreamento de tarefas (Jira / GitHub) — escolha do usuário
Antes de gerar o AGENTS.md, perguntar e registrar onde as tarefas devem ser criadas — isso varia por projeto e pode usar MCP ou CLI (gh/API).
Onde criar as tarefas (issues) deste projeto?
[ ] Jira projeto/board: _____
[ ] GitHub Issues repo: _____ (vazio = origin)
[ ] Ambos
[ ] Nenhum (só OpenSpec .md)
Transporte: [ ] MCP [ ] CLI (gh/API) [ ] Auto
Direção: [ ] 1 via (OpenSpec → tracker) [ ] 2 vias
GitHub: [ ] 1 issue com os .md + checklist (single-issue) [ ] sub-issues
Triagem: [ ] label das issues que um agente pode pegar: _____ (ex.: ready-for-agent)
Bloqueios: [ ] relação nativa (blocked by) quando houver [ ] texto no corpo
Registrar em:
<projectRoot>/AGENTS.md → seção obrigatória quando houver tracker "Rastreamento de tarefas (Jira/GitHub)".
<docsPath>/planning/<projeto>/tracker-profile.md (formato em ../openspec-sync-issues/references/tracker-config.md).
- Opcional:
skills.config.json → bloco tracking.
Precedência: argumento do usuário > AGENTS.md existente > tracker-profile.md > skills.config.json > none.
Fase 0.1.1 — Provisionamento do tracker (fazer existir, não só declarar)
Após a escolha, verificar e provisionar os recursos no tracker — declarar sem criar deixa o próximo agente sem destino real para as issues:
- Repo (GitHub): se
repo não existir no remote (gh repo view <org>/<repo> falha), propor gh repo create <org>/<repo> --private --source=. --remote=origin + push. Confirmar antes.
- Project (GitHub Projects v2, quando o projeto usar board):
gh project create --owner <org> --title "<Título>"; linkar o repo (gh project link <n> --repo <org>/<repo>).
- Campo Status (ciclo de vida das issues): garantir as opções na ordem Backlog → Em desenvolvimento → Revisão → Concluído. O campo
Status default do GitHub traz Todo/In Progress/Done; quando não puder renomear (campo built-in sem field-update no gh), usar updateProjectV2Field (GraphQL) com singleSelectOptions (aceita id para renomear/reordenar e itens novos sem id; color e description são obrigatórios por opção). Salvar os IDs das opções no tracker-profile.md (seção status_options).
- Labels (GitHub): criar as labels do profile (
labels + openspec:<change> + triage_labels) se não existirem — gh label create.
- Issue espelho inicial (opcional, se já houver change ativa): delegar à
openspec-sync-issues — não criar issue manualmente.
Registrar em <docsPath>/planning/<projeto>/tracker-profile.md o que foi provisionado (repo, número/ID do project, status_field_id, status_options). IDs importam: gh project item-edit e o openspec-sync-issues usam esses IDs para transicionar status.
A sincronização em si é feita pela skill openspec-sync-issues (change → issue, tasks → subtasks, transições de status, archive → fechar). O AGENTS.md declara a escolha e os comandos de provisionamento/fluxo para todo agente saber onde criar tarefas e como atualizá-las.
Fase 0.2 — Modo de geração (preservação de formato)
Antes de escrever qualquer AGENTS.md, detecte o modo pelo estado do arquivo:
| Situação do arquivo |
Modo |
O que fazer |
| Não existe |
create |
Gerar pelo template, com os marcadores BEGIN/END:agents-md generated. |
| Existe com marcadores |
merge-generated |
Atualizar só o conteúdo entre marcadores; seções manuais intocadas. |
| Existe sem marcadores (formato editorial do time) |
preserve |
Não inserir marcadores: ler o arquivo inteiro, preservar idioma, títulos, ordem e estilo das seções existentes, atualizar apenas as seções equivalentes e acrescentar as que faltarem — com diff e confirmação antes de escrever. |
No modo preserve, a forma (idioma, títulos, tabelas) vem do arquivo existente; o skill contribui apenas com o conteúdo que falta (comandos reais, mapa de módulos, tracker, estado atual). Nunca reescreva uma seção existente sem mostrar o diff e obter confirmação.
A constituição do projeto (AGENTS.md existente + docs donos) prevalece sobre o template (norma em ../skills-standards.md §4.2). O template é ponto de partida, não camisa de força.
Fase 1 — Detecção de stack por módulo
Para cada módulo, detectar stack e layout de camadas:
| Indicador |
Stack |
Camadas esperadas |
build.gradle(.kts) + id 'java'/kotlin |
Java/Kotlin (Spring) |
hex: infrastructure/adapters/in|out, domínio puro |
pom.xml |
Java (Maven/Spring) |
idem |
package.json + @nestjs/* |
TypeScript (NestJS) |
src/modules/<bc>/{domain,application,infrastructure} |
package.json + react/next |
Next.js/React |
src/ |
angular.json |
Angular |
Clean Architecture por feature |
package.json + vue |
Vue 3 |
idem |
Cargo.toml |
Rust (Axum) |
domain/application/infrastructure/interfaces |
*.csproj |
C# (ASP.NET) |
Domain/Application/Infrastructure |
pubspec.yaml |
Flutter |
domain/data/presentation |
build.gradle(.kts) + com.android |
Android |
domain/data/presentation |
Consultar references/stack-detection.md para comandos de extração de build/test/run/lint/coverage por stack.
Regra: os comandos no AGENTS.md devem ser os reais do módulo (extraídos do build file), não genéricos. Se não encontrar, marque [confirmar]. Inclua o comando de lint de arquitetura (fronteiras entre camadas) na definição de pronto do módulo, quando a stack suportar — ver ../docs/guides/layer-boundary-enforcement.md.
Fase 2 — AGENTS.md da raiz
Gerar <projectRoot>/AGENTS.md com o template de references/root-agents-template.md. Seções (obrigatórias quando aplicáveis; no modo preserve, acrescentar as que faltarem sem reescrever as existentes):
- Visão do repositório — que tipo de monorepo é, topologia.
- Estado do projeto — 3-6 linhas: o que já existe hoje e onde está a estrutura-alvo (ex.: "fundação pronta; módulos em
...; alvo na seção 1 do docs/lld.md").
- Mapa de módulos — tabela: caminho · stack · papel · build/test · porta.
- Onde cada informação mora — dono único (norma em
skills-standards.md §4.2): docs donos do o quê, AGENTS.md dono do como, tracker dono de specs; apontar, nunca duplicar.
- Assunto → Onde ler — tabela de roteamento: assunto → documento e seção (ex.: "contrato da API →
docs/lld.md §3"). Só quando o projeto tem docs donos.
- Convenções globais — referência a
skills-standards.md (naming, Result com lista de erros, Tailwind, cobertura ≥95%) + as convenções locais reais do projeto.
- Fluxo de trabalho — requisito → análise → planejamento → desenvolvimento (ver
docs/guides/workflow-req-to-dev.md), adaptado ao fluxo real do projeto quando ele tiver um.
- Skills disponíveis — categorias (
req-*, analyse/*, core-*, backend-*, config-*, test-*, git-*, openspec-*).
- Análise especialista (
analyse/*) — seção obrigatória quando o projeto usa o fluxo req-*: lista as 12 skills especialistas e a matriz de acionamento (objetivo → skill).
- Rastreamento de tarefas (Jira/GitHub) — seção obrigatória quando houver tracker: declara o tracker (Jira e/ou GitHub), o transporte (MCP vs
gh/API), a direção, o modo GitHub, as labels de triagem e como as dependências viram bloqueio. Acrescenta o provisionamento (comandos para criar repo/project/labels quando faltarem — Fase 0.1.1) e o fluxo de status (Backlog → Em desenvolvimento → Revisão → Concluído, com quem transiciona em cada evento OpenSpec). Vem da Fase 0.1/0.1.1.
- Definição de pronto — os critérios e comandos reais de conclusão do projeto (testes, lint, tipos, build, validação visual), extraídos dos build files. É o DoD que as skills de apply/planejamento respeitam.
- Comandos transversais — subir infra (docker compose), atualizar submódulos, rodar cobertura global.
Idioma: gerar no idioma do projeto (o dos docs/AGENTS.md existentes). Sem docs, usar o idioma do time e registrar a escolha.
Fase 3 — AGENTS.md por submódulo
Para cada módulo detectado, gerar <module>/AGENTS.md com o template de references/submodule-agents-template.md:
- Papel do módulo — 1-2 linhas: qual serviço/camada é e do que depende.
- Estado atual — o que já existe no módulo hoje e onde está a estrutura-alvo (ex.: seção 1 do LLD); código novo nasce nela.
- Stack e versões — linguagem, framework, build tool (extraídos do build file).
- Layout / camadas — pastas reais (ex.:
infrastructure/adapters/in/web).
- Comandos — build, test, test coverage, run local, lint/fmt.
- Onde está cada assunto — tabela de roteamento: assunto → documento e seção (docs donos) e → skill/AGENTS.md, sem duplicar conteúdo (§4.2 do
skills-standards.md).
- Definição de pronto — os critérios e comandos reais de conclusão do módulo (suítes de teste, lint, tipos, build, validação visual quando houver).
- Convenções locais — naming, package base, padrões específicos do módulo (incluindo sufixos de arquivo e níveis de teste, quando existirem).
- Skills aplicáveis — quais skills deste repositório usar dentro deste módulo.
- Limites — o que este módulo não deve fazer (ex.: domínio sem anotação de framework).
Fase 4 — Idempotência e merge
AGENTS.md é documento vivo e frequentemente editado à mão. Ao atualizar, respeite o modo detectado na Fase 0.2:
create / merge-generated: delimitar o conteúdo gerenciado pelo skill com marcadores:
<!-- BEGIN:agents-md generated -->
...conteúdo gerado...
<!-- END:agents-md generated -->
- Nunca sobrescrever conteúdo fora dos marcadores (seções manuais do time).
- Se não houver marcadores e o arquivo existir: mostre um diff proposto e peça confirmação antes de escrever.
preserve (arquivo editorial, sem marcadores): não inserir marcadores. Ler o arquivo, atualizar apenas as seções equivalentes e acrescentar as que faltarem, mantendo idioma, títulos, ordem e estilo; mostrar diff e pedir confirmação antes de escrever.
Nunca commite automaticamente. Commit só via git-organized-commits quando o usuário pedir.
Fase 5 — Validação
Antes de finalizar:
Saída
<projectRoot>/
├── AGENTS.md ← mapa + convenções + fluxo
├── microservices/
│ ├── ordering/AGENTS.md ← contrato do submódulo
│ ├── billing/AGENTS.md
│ └── product-catalog/AGENTS.md
├── apps/
│ ├── web/AGENTS.md
│ └── backend/AGENTS.md
└── packages/
└── shared/AGENTS.md
Adapte a profundidade ao que foi detectado. Não crie AGENTS.md para pastas que não sejam módulos de build.
References
references/discovery.md — descobrir topologia (submodules, workspaces, microserviços).
references/stack-detection.md — comandos por stack e extração de build/test/run.
references/root-agents-template.md — template do AGENTS.md raiz.
references/submodule-agents-template.md — template do AGENTS.md de módulo.
../openspec-sync-issues/references/tracker-config.md — schema do tracker profile (Jira/GitHub + MCP/CLI).
../docs/guides/workflow-req-to-dev.md — fluxo requisito → análise → planejamento → desenvolvimento.
../docs/guides/analysis-expert-flow.md — fluxo das skills especialistas (analyse/*) e matriz de acionamento.
../docs/guides/skills-inventory.md — inventário das skills deste repositório.
Global Standards
- Consultar
../skills-standards.md para padrões globais de nomenclatura e convenções entre skills.
1---2name: config-agents-md3stack: agnostic4description: Gerar e manter arquivos AGENTS.md na raiz do projeto e em cada submódulo/subapp (monorepo, submodules Git, microserviços ou camadas da arquitetura). Faz a descoberta da estrutura, detecta a stack de cada módulo, mapeia comandos de build/test/run e monta um AGENTS.md raiz (mapa + convenções + fluxo) e um AGENTS.md por submódulo (stack, camadas, comandos, skills aplicáveis). Usar quando o pedido envolver criar/atualizar AGENTS.md, documentar o projeto para agentes de IA, preparar contexto de monorepo multi-stack ou de microserviços.5metadata:6 source: https://skillmd.com/skills/eskcti/config-agents-md7---89# Config AGENTS.md1011Gera **AGENTS.md** (arquivo de instruções para agentes de IA no padrão opencode) na **raiz do projeto** e em **cada submódulo/subapp**, a partir da descoberta real da estrutura (não de suposições).1213**Este skill produz documentação de contexto, não código de aplicação.** O AGENTS.md raiz é o *mapa*; cada AGENTS.md de submódulo é o *contrato local* daquele módulo.1415---1617## Quando usar1819| Cenário | Ação |20|---------|------|21| Monorepo com submódulos Git (`microservices/*`, `apps/*`, `packages/*`) | AGENTS.md raiz + 1 por submódulo |22| Monorepo de workspace (TurboRepo, Cargo workspace, Gradle multi-module, .sln) | AGENTS.md raiz + 1 por pacote/módulo relevante |23| Repositório único (single app) | Apenas AGENTS.md raiz |24| Camadas da arquitetura como pastas/módulos | 1 por camada quando ela tem build/test próprios |25| Já existe AGENTS.md | **Atualizar** preservando seções manuais (merge por marcadores) |2627Se o usuário não especificar o escopo, **detecte** (Fase 0) e proponha a lista de arquivos antes de escrever.2829---3031## Fase 0 — Descoberta da estrutura3233Nunca assuma a topologia. Rode a detecção:3435```bash36# 1. É monorepo? Submodules?37test -f .gitmodules && cat .gitmodules38# 2. Workspaces JS39cat package.json | grep -A20 '"workspaces"'40# 3. Gradle multi-module41cat settings.gradle 2>/dev/null || cat settings.gradle.kts 2>/dev/null42# 4. Cargo workspace43cat Cargo.toml 2>/dev/null | grep -A20 '\[workspace\]'44# 5. Solução .NET45find . -maxdepth 2 -name '*.sln'46# 6. Package managers por pasta47find . -maxdepth 3 \( -name package.json -o -name build.gradle -o -name build.gradle.kts \48 -o -name pom.xml -o -name Cargo.toml -o -name '*.csproj' -o -name pubspec.yaml \49 -o -name angular.json -o -name go.mod \) -not -path '*/node_modules/*' 2>/dev/null50```5152Consultar `references/discovery.md` para o fluxo completo (submodules Git, workspaces, monorepo de microserviços).5354### Regra de fronteira de módulo5556Um **módulo** é candidato a AGENTS.md próprio quando **tem build/test independentes** (build file próprio, `settings.gradle` que o inclui, `workspaces` entry, `[workspace] members`, ou entrada em `.gitmodules`).5758Cada submódulo de microserviço = **1 AGENTS.md**. Cada app de frontend/mobile = **1 AGENTS.md**. Camada pura (ex.: `domain/`) só ganha AGENTS.md se tiver build próprio.5960> **Fronteiras entre camadas**: proteja com **lint de arquitetura** (dependency-cruiser/ESLint boundaries, ArchUnit, NetArchTest, Cargo/clippy) — ver `../docs/guides/layer-boundary-enforcement.md`. Camada vira submódulo só com ciclo de vida/release próprio (ex.: shared kernel), **nunca** só para impedir import.6162---6364## Fase 0.1 — Rastreamento de tarefas (Jira / GitHub) — escolha do usuário6566Antes de gerar o AGENTS.md, **perguntar e registrar** onde as tarefas devem ser criadas — isso **varia por projeto** e **pode usar MCP ou CLI (`gh`/API)**.6768```69Onde criar as tarefas (issues) deste projeto?70[ ] Jira projeto/board: _____71[ ] GitHub Issues repo: _____ (vazio = origin)72[ ] Ambos73[ ] Nenhum (só OpenSpec .md)74Transporte: [ ] MCP [ ] CLI (gh/API) [ ] Auto75Direção: [ ] 1 via (OpenSpec → tracker) [ ] 2 vias76GitHub: [ ] 1 issue com os .md + checklist (single-issue) [ ] sub-issues77Triagem: [ ] label das issues que um agente pode pegar: _____ (ex.: ready-for-agent)78Bloqueios: [ ] relação nativa (blocked by) quando houver [ ] texto no corpo79```8081Registrar em:8283- `<projectRoot>/AGENTS.md` → seção **obrigatória quando houver tracker** "Rastreamento de tarefas (Jira/GitHub)".84- `<docsPath>/planning/<projeto>/tracker-profile.md` (formato em `../openspec-sync-issues/references/tracker-config.md`).85- Opcional: `skills.config.json` → bloco `tracking`.8687Precedência: argumento do usuário > `AGENTS.md` existente > `tracker-profile.md` > `skills.config.json` > `none`.8889### Fase 0.1.1 — Provisionamento do tracker (fazer existir, não só declarar)9091Após a escolha, **verificar e provisionar** os recursos no tracker — declarar sem criar deixa o próximo agente sem destino real para as issues:92931. **Repo** (GitHub): se `repo` não existir no remote (`gh repo view <org>/<repo>` falha), propor `gh repo create <org>/<repo> --private --source=. --remote=origin` + push. Confirmar antes.942. **Project** (GitHub Projects v2, quando o projeto usar board): `gh project create --owner <org> --title "<Título>"`; linkar o repo (`gh project link <n> --repo <org>/<repo>`).953. **Campo Status** (ciclo de vida das issues): garantir as opções na ordem **Backlog → Em desenvolvimento → Revisão → Concluído**. O campo `Status` default do GitHub traz `Todo/In Progress/Done`; quando não puder renomear (campo built-in sem `field-update` no `gh`), usar `updateProjectV2Field` (GraphQL) com `singleSelectOptions` (aceita `id` para renomear/reordenar e itens novos sem `id`; `color` e `description` são obrigatórios por opção). Salvar os IDs das opções no `tracker-profile.md` (seção `status_options`).964. **Labels** (GitHub): criar as labels do profile (`labels` + `openspec:<change>` + `triage_labels`) se não existirem — `gh label create`.975. **Issue espelho inicial** (opcional, se já houver change ativa): delegar à `openspec-sync-issues` — não criar issue manualmente.9899Registrar em `<docsPath>/planning/<projeto>/tracker-profile.md` o que foi provisionado (repo, número/ID do project, `status_field_id`, `status_options`). IDs importam: `gh project item-edit` e o `openspec-sync-issues` usam esses IDs para transicionar status.100101> A sincronização em si é feita pela skill `openspec-sync-issues` (change → issue, tasks → subtasks, transições de status, archive → fechar). O AGENTS.md **declara a escolha e os comandos de provisionamento/fluxo** para todo agente saber onde criar tarefas e como atualizá-las.102103## Fase 0.2 — Modo de geração (preservação de formato)104105Antes de escrever qualquer AGENTS.md, detecte o modo pelo estado do arquivo:106107| Situação do arquivo | Modo | O que fazer |108|---------------------|------|-------------|109| Não existe | `create` | Gerar pelo template, com os marcadores `BEGIN/END:agents-md generated`. |110| Existe com marcadores | `merge-generated` | Atualizar só o conteúdo entre marcadores; seções manuais intocadas. |111| Existe sem marcadores (formato editorial do time) | `preserve` | **Não inserir marcadores**: ler o arquivo inteiro, preservar idioma, títulos, ordem e estilo das seções existentes, atualizar apenas as seções equivalentes e acrescentar as que faltarem — com diff e confirmação antes de escrever. |112113No modo `preserve`, a forma (idioma, títulos, tabelas) vem do arquivo existente; o skill contribui apenas com o conteúdo que falta (comandos reais, mapa de módulos, tracker, estado atual). Nunca reescreva uma seção existente sem mostrar o diff e obter confirmação.114115> A constituição do projeto (AGENTS.md existente + docs donos) **prevalece** sobre o template (norma em `../skills-standards.md` §4.2). O template é ponto de partida, não camisa de força.116117---118119## Fase 1 — Detecção de stack por módulo120121Para cada módulo, detectar stack e layout de camadas:122123| Indicador | Stack | Camadas esperadas |124|-----------|-------|-------------------|125| `build.gradle(.kts)` + `id 'java'`/`kotlin` | Java/Kotlin (Spring) | hex: `infrastructure/adapters/in\|out`, domínio puro |126| `pom.xml` | Java (Maven/Spring) | idem |127| `package.json` + `@nestjs/*` | TypeScript (NestJS) | `src/modules/<bc>/{domain,application,infrastructure}` |128| `package.json` + `react`/`next` | Next.js/React | `src/` |129| `angular.json` | Angular | Clean Architecture por feature |130| `package.json` + `vue` | Vue 3 | idem |131| `Cargo.toml` | Rust (Axum) | `domain/application/infrastructure/interfaces` |132| `*.csproj` | C# (ASP.NET) | Domain/Application/Infrastructure |133| `pubspec.yaml` | Flutter | `domain/data/presentation` |134| `build.gradle(.kts)` + `com.android` | Android | `domain/data/presentation` |135136Consultar `references/stack-detection.md` para comandos de extração de **build/test/run/lint/coverage** por stack.137138> **Regra**: os comandos no AGENTS.md devem ser **os reais do módulo** (extraídos do build file), não genéricos. Se não encontrar, marque `[confirmar]`. Inclua o comando de **lint de arquitetura** (fronteiras entre camadas) na definição de pronto do módulo, quando a stack suportar — ver `../docs/guides/layer-boundary-enforcement.md`.139140---141142## Fase 2 — AGENTS.md da raiz143144Gerar `<projectRoot>/AGENTS.md` com o template de `references/root-agents-template.md`. Seções (obrigatórias quando aplicáveis; no modo `preserve`, acrescentar as que faltarem sem reescrever as existentes):1451461. **Visão do repositório** — que tipo de monorepo é, topologia.1472. **Estado do projeto** — 3-6 linhas: o que já existe hoje e onde está a estrutura-alvo (ex.: "fundação pronta; módulos em `...`; alvo na seção 1 do `docs/lld.md`").1483. **Mapa de módulos** — tabela: caminho · stack · papel · build/test · porta.1494. **Onde cada informação mora** — dono único (norma em `skills-standards.md` §4.2): docs donos do **o quê**, AGENTS.md dono do **como**, tracker dono de specs; apontar, nunca duplicar.1505. **Assunto → Onde ler** — tabela de roteamento: assunto → documento e seção (ex.: "contrato da API → `docs/lld.md` §3"). Só quando o projeto tem docs donos.1516. **Convenções globais** — referência a `skills-standards.md` (naming, Result com lista de erros, Tailwind, cobertura ≥95%) + as convenções locais reais do projeto.1527. **Fluxo de trabalho** — requisito → análise → planejamento → desenvolvimento (ver `docs/guides/workflow-req-to-dev.md`), adaptado ao fluxo real do projeto quando ele tiver um.1538. **Skills disponíveis** — categorias (`req-*`, `analyse/*`, `core-*`, `backend-*`, `config-*`, `test-*`, `git-*`, `openspec-*`).1549. **Análise especialista (`analyse/*`)** — seção obrigatória **quando o projeto usa o fluxo `req-*`**: lista as 12 skills especialistas e a matriz de acionamento (objetivo → skill).15510. **Rastreamento de tarefas (Jira/GitHub)** — seção obrigatória **quando houver tracker**: declara o tracker (Jira e/ou GitHub), o transporte (MCP vs `gh`/API), a direção, o modo GitHub, as labels de triagem e como as dependências viram bloqueio. Acrescenta o **provisionamento** (comandos para criar repo/project/labels quando faltarem — Fase 0.1.1) e o **fluxo de status** (Backlog → Em desenvolvimento → Revisão → Concluído, com quem transiciona em cada evento OpenSpec). Vem da Fase 0.1/0.1.1.15611. **Definição de pronto** — os critérios e comandos reais de conclusão do projeto (testes, lint, tipos, build, validação visual), extraídos dos build files. É o DoD que as skills de apply/planejamento respeitam.15712. **Comandos transversais** — subir infra (docker compose), atualizar submódulos, rodar cobertura global.158159> **Idioma**: gerar no idioma do projeto (o dos docs/AGENTS.md existentes). Sem docs, usar o idioma do time e registrar a escolha.160161---162163## Fase 3 — AGENTS.md por submódulo164165Para cada módulo detectado, gerar `<module>/AGENTS.md` com o template de `references/submodule-agents-template.md`:1661671. **Papel do módulo** — 1-2 linhas: qual serviço/camada é e do que depende.1682. **Estado atual** — o que já existe no módulo hoje e onde está a estrutura-alvo (ex.: seção 1 do LLD); código novo nasce nela.1693. **Stack e versões** — linguagem, framework, build tool (extraídos do build file).1704. **Layout / camadas** — pastas reais (ex.: `infrastructure/adapters/in/web`).1715. **Comandos** — build, test, test coverage, run local, lint/fmt.1726. **Onde está cada assunto** — tabela de roteamento: assunto → documento e seção (docs donos) e → skill/AGENTS.md, sem duplicar conteúdo (§4.2 do `skills-standards.md`).1737. **Definição de pronto** — os critérios e comandos reais de conclusão do módulo (suítes de teste, lint, tipos, build, validação visual quando houver).1748. **Convenções locais** — naming, package base, padrões específicos do módulo (incluindo sufixos de arquivo e níveis de teste, quando existirem).1759. **Skills aplicáveis** — quais skills deste repositório usar dentro deste módulo.17610. **Limites** — o que este módulo **não** deve fazer (ex.: domínio sem anotação de framework).177178---179180## Fase 4 — Idempotência e merge181182AGENTS.md é documento vivo e frequentemente editado à mão. Ao atualizar, respeite o modo detectado na Fase 0.2:183184- **`create` / `merge-generated`**: delimitar o conteúdo gerenciado pelo skill com marcadores:185186 ```markdown187 <!-- BEGIN:agents-md generated -->188 ...conteúdo gerado...189 <!-- END:agents-md generated -->190 ```191192 - **Nunca sobrescrever** conteúdo fora dos marcadores (seções manuais do time).193 - Se não houver marcadores e o arquivo existir: mostre um diff proposto e **peça confirmação** antes de escrever.194195- **`preserve`** (arquivo editorial, sem marcadores): **não inserir marcadores**. Ler o arquivo, atualizar apenas as seções equivalentes e acrescentar as que faltarem, mantendo idioma, títulos, ordem e estilo; mostrar diff e pedir confirmação antes de escrever.196- Nunca commite automaticamente. Commit só via `git-organized-commits` quando o usuário pedir.197198---199200## Fase 5 — Validação201202Antes de finalizar:203204- [ ] Cada módulo do mapa da raiz tem AGENTS.md correspondente.205- [ ] Todos os comandos foram extraídos dos build files (ou marcados `[confirmar]`); a definição de pronto do root e de cada módulo traz os comandos reais.206- [ ] AGENTS.md raiz aponta para os AGENTS.md dos submódulos e para os docs donos (tabela "Assunto → Onde ler").207- [ ] Idioma do projeto respeitado; no modo `preserve`, seções, títulos e estilo existentes foram mantidos.208- [ ] Análise especialista (`analyse/*`) presente quando o projeto usa o fluxo `req-*`; rastreamento presente quando há tracker (com labels de triagem e bloqueio).209- [ ] "Onde cada informação mora" presente, com as convenções remetendo a `skills-standards.md` (sem duplicar).210- [ ] Nenhuma seção manual foi perdida no merge.211212---213214## Saída215216```217<projectRoot>/218├── AGENTS.md ← mapa + convenções + fluxo219├── microservices/220│ ├── ordering/AGENTS.md ← contrato do submódulo221│ ├── billing/AGENTS.md222│ └── product-catalog/AGENTS.md223├── apps/224│ ├── web/AGENTS.md225│ └── backend/AGENTS.md226└── packages/227 └── shared/AGENTS.md228```229230> Adapte a profundidade ao que foi detectado. Não crie AGENTS.md para pastas que não sejam módulos de build.231232---233234## References235236- `references/discovery.md` — descobrir topologia (submodules, workspaces, microserviços).237- `references/stack-detection.md` — comandos por stack e extração de build/test/run.238- `references/root-agents-template.md` — template do AGENTS.md raiz.239- `references/submodule-agents-template.md` — template do AGENTS.md de módulo.240- `../openspec-sync-issues/references/tracker-config.md` — schema do tracker profile (Jira/GitHub + MCP/CLI).241- `../docs/guides/workflow-req-to-dev.md` — fluxo requisito → análise → planejamento → desenvolvimento.242- `../docs/guides/analysis-expert-flow.md` — fluxo das skills especialistas (`analyse/*`) e matriz de acionamento.243- `../docs/guides/skills-inventory.md` — inventário das skills deste repositório.244245## Global Standards246247- Consultar `../skills-standards.md` para padrões globais de nomenclatura e convenções entre skills.