1. Introdução · versão 2.0.0

Como usar em um projeto

manifesto/00-introducao/02-como-usar.md

O Manifesto nasce no repositório jhowdev e é levado aos projetos como uma pasta manifesto/, copiada inteira. Um projeto novo nasce de um dos modelos de projeto do jhowdev, que já trazem a pasta; um projeto que já existe recebe a pasta copiada e o scripts/manifesto-pull.mjs para mantê-la atualizada.

Os modelos de projeto

Três pontos de partida, gerados por um comando no jhowdev (ADR 076 de lá):

pnpm boilerplate:build <vazio|manifesto|monorepo> <destino> --nome "Meu Projeto" --slug meu-projeto \
  [--autor "Nome <email>"] [--descricao "..."] [--producao] [--git]

Modelo	O que traz
Vazio	Só um `README.md` e o `.gitignore`. Para quem vai decidir tudo na primeira decisão.
Manifesto	A pasta `manifesto/` na versão em vigor, a `.specs/` com a ADR 001 de fundação já preenchida, `CLAUDE.md` e `AGENTS.md`, a pasta `.secrets/` padrão, o `compose.yml` do banco local e o kit de ferramentas.
Monorepo	Tudo do modelo Manifesto e um app pronto na stack universal (Next.js, Prisma, OpenAPI e Scalar, Zustand, shadcn/ui, Vitest), com smoke e varredura de acesso; com `--producao`, o pacote de produção num servidor próprio.

O nome e o slug entram em todo lugar (pacote, banco, contêineres, ADR 001), e as portas locais são derivadas do slug para não colidir com outros projetos. A ADR 001 é a de fundação; as próximas recebem o número pela reserva do Gestor (sem ele, o maior número existente + 1).

Com o Gestor (recomendado)

O caminho mais curto para um projeto novo é o Criar projeto do Gestor: ele gera o repositório a partir de um destes modelos, cria o projeto de tarefas e o espaço de desenvolvimento, e deixa o MCP do Gestor pronto para o agente. Daí em diante, o Gestor guarda o controle (tarefas, prazos, ciclos) e o repositório guarda as ADRs. O que o Gestor dá ao método está em Gestor; o projeto que não o usa segue Sem o Gestor, sem perder nada do método.

Passo a passo (projeto que já existe)

Copiar a pasta manifesto/ do jhowdev para a raiz do projeto (num projeto gerado por um modelo, ela já está lá). Ela é read-only no projeto: não se edita o Manifesto ali. Correções e evoluções da metodologia são ADRs no jhowdev, onde ganham uma versão nova.

A estrutura de docs do projeto vive em .specs/:

.specs/
├── adr/         ← unidades de trabalho (foco do dia a dia)
├── notes/       ← anotações humanas (a IA ignora — ver .specs/notes/CLAUDE.md)
└── readme.md    ← explica a estrutura conforme ela cresce

Outras pastas (ex.: .specs/model/, .specs/stack/, .specs/design/) surgem quando uma ADR as cria — não se adianta estrutura que ainda não é necessária.

Ajustar o CLAUDE.md na raiz do projeto. Ele aponta para o Manifesto e descreve o contexto operacional do projeto (comandos, setup, ambiente). Há um modelo de CLAUDE.md.
Começar a trabalhar. Tudo o que mexe no código começa por uma ADR, e o agente decide isso sozinho pela regra de Tarefa ou ADR. Os modelos trazem o esqueleto dos seis arquivos e uma ADR de exemplo completa.

Manter o Manifesto atualizado

A versão que o projeto usa está em manifesto/VERSION, e o que mudou em cada versão, em manifesto/CHANGELOG.md. Para trazer a versão mais nova do jhowdev:

pnpm manifesto:pull            # baixa só manifesto/ do jhowdev, troca a pasta e mostra o diff
git diff manifesto/            # revisar
git add manifesto/ && git commit -m "docs(manifesto): atualiza para a X.Y.Z"

Para ficar numa versão publicada — por exemplo, na 1.x depois que a 2.0.0 saiu —, peça a versão: pnpm manifesto:pull --versao 1.2.1 traz a pasta da etiqueta manifesto-v1.2.1 do jhowdev (cada versão publicada tem a sua etiqueta) e confere que o VERSION trazido diz a mesma versão.

O comando nunca commita sozinho, recusa rodar com mudança não commitada em manifesto/ e tem --dry-run para só ver o que mudaria. Fora de um repositório git, ou com arquivo ignorado pelo .gitignore dentro de manifesto/, ele também recusa, salvo com --force (aí a pasta antiga fica em .manifesto-pull-anterior/ para conferir). O jhowdev é privado: sem credencial no https, use --from git@github.com:josephpatrick1/jhowdev.git, a variável MANIFESTO_REPO ou um caminho local. A versão nova só chega pelo padrão (a main) depois que o jhowdev a publica lá. Ele é um arquivo só (scripts/manifesto-pull.mjs, Node e git, sem dependência): basta copiar o arquivo do jhowdev para scripts/ e acrescentar "manifesto:pull": "node scripts/manifesto-pull.mjs" ao package.json. Atualizar o Manifesto é trabalho como outro qualquer: registre na ADR em que isso acontece.

O que é universal e o que é do projeto

Universal (vem do Manifesto, igual em todo projeto): o fluxo de ADR, a stack obrigatória, os padrões de manifesto/architecture/, as regras de git e segurança.
Do projeto (nasce nas ADRs e em .specs/stack/): regras de negócio, modelos de dados, stacks adicionais, glossário de domínio.

.specs/stack/ guarda as escolhas técnicas próprias do projeto — aquilo que vai além da stack universal definida no Manifesto. O nome “stack” aqui é proposital: separa o que é do projeto do que é padrão universal (manifesto/architecture/).