| name | anvil-docs |
| description | Organização documental do anvil: onde cada documento mora, como a spec se chama, e o que acontece com ela quando fecha. Use para montar a árvore docs/ num projeto novo, adotar um docs/ existente e bagunçado, regenerar o índice, ou arquivar uma spec promovendo o que virou canônico. |
Organização documental
Esta skill responde três perguntas: onde o documento mora, como ele se
chama e o que acontece com ele quando a spec fecha.
Ela cobre só o que as skills de fluxo não cobrem. O conteúdo de spec.md e
dos tickets é integralmente das skills originais — o anvil define a pasta, não o
que vai dentro dela.
Verbos
| verbo | quando | onde está |
|---|
scaffold | projeto novo, docs/ vazio ou ausente | aqui embaixo |
adopt | docs/ existente com conteúdo fora do padrão | ADOPT.md |
index | depois de criar, mudar ou arquivar spec | INDEX.md |
archive | spec fechada | ARCHIVE.md |
Sem verbo explícito: se docs/ não existe ou só tem os README de domínio, é
scaffold. Se tem conteúdo, é adopt — nunca presuma que dá para só criar por
cima.
A árvore canônica
docs/
├── index.md gerado pelo verbo `index`
├── agents/issue-tracker.md ● o perfil que as skills de fluxo leem
├── architecture/ ● desenho do sistema
│ ├── context.md glossário ubíquo (anvil-domain-modeling)
│ ├── context-map.md só em repositório multi-contexto
│ └── adr/ decisões, uma por arquivo
├── discovery/ ● pesquisa e notas (anvil-research)
├── specs/ ●
│ ├── {NNN}-{tipo}-{nome}/
│ │ ├── spec.md anvil-to-spec — inclui as User Stories
│ │ ├── issues/NN-slug.md anvil-to-tickets, um arquivo por ticket
│ │ ├── map.md anvil-wayfinder, quando usado
│ │ ├── ui/ fluxos e comportamento desta mudança
│ │ ├── architecture/ ADRs e modelos desta mudança
│ │ └── discovery/ pesquisa desta mudança
│ └── archive/ specs concluídas
│
├── prd/ ○ escopo de produto
├── ui/ ○ design system e fluxos duráveis
├── qa/ ○ estratégia de teste
└── project/ ○ plano e atualizações datadas
● o scaffold cria · ○ reconhecido, mas nasce só quando algo for
escrito ali
Os quatro com ○ não têm skill que escreva neles. Pasta vazia com README
prometendo um autor que não existe ensina quem lê a ignorar a árvore inteira —
então eles não nascem antes de ter conteúdo. Continuam canônicos: o
validate.sh docs-paths não reclama deles quando aparecem.
Duas camadas espelhadas: base, que é a verdade do projeto hoje, e
por spec, que é o escopo de uma mudança pendente.
Quem escreve onde
| domínio | quem |
|---|
architecture/context.md e adr/ | anvil-grill e anvil-domain-modeling, enquanto decidem |
discovery/ | anvil-research — ele diz "salve onde o repositório já guarda essas notas", então escreve aqui se a pasta existir |
specs/{id}/spec.md | anvil-to-spec. Inclui as User Stories — no anvil a spec é a unidade, e absorve o que num PRD seria épico e story |
specs/{id}/issues/ | anvil-to-tickets |
specs/{id}/ui/ | anvil-grill. Fluxo de usuário, comportamento de interface e wireframe são decisão que vira artefato — a mesma natureza de um ADR. Quando a pergunta só se responde vendo rodar, o anvil-prototype gera as variantes, você escolhe, e a decisão volta para o documento; o protótipo em si é descartável e vive fora da main |
agents/issue-tracker.md | anvil-setup |
prd/ · ui/ · qa/ · project/ | ninguém. São para o que você escrever à mão |
Nenhuma skill autora PRD. O modelo é o das skills de fluxo: a spec é a
unidade e carrega suas próprias User Stories. Se você quiser uma camada de épico
atravessando specs, ela é escrita à mão em prd/ — e aí a pasta nasce.
A regra de decisão:
- Descreve o projeto como ele é hoje →
docs/<domínio>/
- É específico de uma mudança pendente →
docs/specs/{id}/<domínio>/
- Nasceu numa spec mas virou canônico → fica na spec e é promovido no
arquivamento
Não há spec-meta.yaml, tasks.md nem gate.yaml no fluxo normal. O estado é
lido do disco: spec.md existe → especificado; issues/ com Status: diferente
de resolved → em andamento; todos resolved → implementado; pasta sob
archive/ → arquivado.
Nome da spec: branch e pasta são strings diferentes
branch: {tipo}/{NNN}-{nome} → feature/012-checkout-coupon
pasta: docs/specs/{NNN}-{tipo}-{nome} → docs/specs/012-feature-checkout-coupon
O tipo aparece nos dois, em posições diferentes: no branch é um segmento de
caminho, que agrupa no git branch; na pasta é parte do nome, o que mantém
docs/specs/ plano, sem um nível de diretório por tipo.
Resolva sempre pelo prefixo numérico, nunca por igualdade de string. Código
que assume branch == nome da pasta quebra. A transformação é determinística — o
segmento antes da / é o tipo, o resto é {NNN}-{nome} — mas as duas strings
nunca são iguais.
Tipos: feature · fix · hotfix · gmud · refactor · experimental ·
extension.
Trabalho sem spec usa {tipo}/{nome} sem número — chore/, docs/, ci/,
build/. O número é o que marca "isto tem spec"; usá-lo fora disso torna a marca
inútil.
Promoção
Artefato dentro de specs/{id}/ que deve virar canônico declara destino e modo
no front-matter:
---
promote: docs/architecture/adr/adr-0007-coupon-service.md
promote_mode: copy
---
| modo | comportamento no arquivamento |
|---|
copy | copia para o destino; se já existir, pergunta antes |
append | anexa o corpo, sem o front-matter, ao fim do destino |
manual | não aplica; imprime o arquivo e o destino sugerido para o usuário aplicar |
Sem promote:, o artefato congela dentro da spec arquivada e não toca a base.
O front-matter precisa começar na coluna zero. Um mapa raiz inteiramente
indentado falha antes da leitura.
Escreva o artefato para onde ele vai morar, não para onde está. O modo copy
exige que o destino fique idêntico à origem, então link relativo tem que resolver
no destino.
scaffold
- Criar só os quatro que têm escritor:
architecture/adr/, discovery/,
specs/archive/ e agents/. Nunca sobrescrever uma que já existe.
prd/, ui/, qa/ e project/ não nascem agora — nascem quando alguém
escrever neles.
- Cada pasta criada recebe um
README.md curto dizendo quem escreve ali.
- Chamar o
anvil-setup para escrever docs/agents/issue-tracker.md a partir
do perfil em templates/issue-tracker-anvil.md.
É esse arquivo que faz as skills de fluxo publicarem em docs/specs/ sem
conhecerem esse caminho.
- Rodar o verbo
index.
Se docs/ já tiver conteúdo fora dos domínios canônicos, pare e use adopt.
Contrato de stack
Adicionar uma stack ao anvil é preencher seis lacunas conhecidas, sem tocar no
fluxo do bench. O contrato está em STACK-CONTRACT.md.
Verificação
bash scripts/validate.sh docs-paths — as saídas declaradas ficam sob os
domínios canônicos. Consultivo, não bloqueia.bash scripts/validate.sh ship-ready — a spec do branch atual está fechada.
É o que o hook de merge chama.bash scripts/find-dupes.sh docs — conteúdo duplicado: mesmo hash, mesmo
identificador de artefato, mesmo título. O adopt roda no começo e no fim;
vale rodar à mão depois de qualquer movimentação em massa.
