# Onboarding de projeto para SDD
Use este procedimento na primeira vez que a pipeline entra em um projeto.
## Passo 1 — Copiar a camada
Preferencialmente use:
```bash
cd /caminho/do/projeto
sdd init
```
Também é possível inicializar de fora:
```bash
sdd init --root /caminho/do/projeto
```
Use `--dry-run` para auditar antes de escrever; nesse modo nenhum arquivo é criado. Use `--force` apenas quando quiser substituir uma instalação existente. Use `--preset <nome>` para substituir a detecção automática. Use `--with-ci` para levar testes/workflow e `--with-examples` para levar exemplos. Use `--with-claude-plugin` somente se quiser testar o plugin Claude empacotado; para uso normal, os comandos diretos do projeto evitam duplicidade.
Quando `optimization.codegraph.auto_index` estiver ativo, o `sdd init` tenta rodar `codegraph init -i .` no root do projeto depois de materializar a camada. Se CodeGraph não estiver instalado, a instalação continua e o fluxo usa fallback local (`git`/`rg`) até o índice existir.
Se o projeto já tem `.sdd/` instalado, prefira atualizar em vez de reinstalar:
```bash
sdd update
sdd clients doctor
```
`sdd upgrade` é alias de `sdd update`. O update preserva `sdd.config.yaml`, `docs/<orquestracao>/` e skills/rules locais extras por padrão; use `--update-config` apenas quando quiser regenerar a configuração.
O layout padrão é compacto. A raiz do projeto recebe somente os arquivos descobertos por Claude/Codex e a configuração do projeto:
- `AGENTS.md`
- `CLAUDE.md`
- `.claude/`
- `.codex/`
- `.agents/`
- `.cursor/`
- `.opencode/`
- `sdd.config.yaml`
Todo suporte reutilizável fica em `.sdd/`.
Copie os diretórios e arquivos da camada SDD para a raiz do projeto alvo:
- `.claude/`
- `.codex/`
- `.agents/`
- `.cursor/`
- `.opencode/`
- `AGENTS.md`
- `CLAUDE.md`
- `.sdd/`
- `sdd.config.yaml`
Crie `sdd.config.yaml` a partir de `.sdd/sdd.config.example.yaml`.
Inicialize também o fallback local de artefatos para a primeira orquestração:
```bash
sdd init "minha-primeira-orquestracao"
```
## Passo 2 — Preencher configuração
Preencha:
- tipo de projeto;
- stack;
- provedores de issue/docs/repo/CI/chat;
- paths de fonte, testes, docs e migrations;
- comandos de install, lint, typecheck, test e build;
- regras de risco.
- providers disponíveis, modelo padrão e `auth_env` de cada provider;
- `runtime.node_effect_bridge.enabled`, mantendo `false` até haver decisão explícita;
- `memory.index_path`, mantendo `.sdd/memory/learnings.jsonl` como cache derivado.
Sem comandos confiáveis, Execution e Review não devem prometer validação total.
Valide providers sem expor segredo:
```bash
sdd providers list
sdd providers doctor --json
```
Use flags para sobrescrever config quando necessário: `--provider`, `--model`, `--offline`. A ordem é flags, env, config e defaults. Nunca registre valores de API keys/tokens em docs, logs, traceability map ou memory.
## Passo 3 — Discovery
Rode `/sdd discover` e confirme:
- os paths existem;
- a stack declarada bate com o codebase;
- os comandos funcionam;
- padrões de arquitetura e teste foram identificados;
- riscos recorrentes estão documentados.
O discovery vira memória inicial do projeto.
## Passo 4 — Ajustar adapters
Mapeie os donos:
| Ideia | Jira/Slack/Form | Jira |
| PRD | Confluence/Markdown | Jira epic |
| Tech Spec | Confluence/Markdown | Jira |
| Tasks | Jira/Linear/GitHub Issues | Jira/Linear/GitHub Issues |
| Código | Git provider | PR |
| ADR | Confluence/Notion/Markdown | Traceability map |
| Review | PR | CI/PR status |
| Memory | Confluence/Markdown | Traceability map |
Se o projeto não usa Atlassian, troque os adapters, não o fluxo.
Se qualquer integração externa estiver ausente ou parcial, use `docs/<slug-da-orquestracao>/` como dono local do conteúdo até o adapter estar pronto.
## Passo 5 — Definir policy de risco
Marque como Refinement obrigatório quando houver:
- migration;
- feature flag;
- dependência externa;
- dados sensíveis;
- auth/permissões;
- pagamento;
- impacto cross-layer.
Marque Agent Team obrigatório quando houver:
- arquitetura cross-layer;
- segurança;
- contrato de dados;
- performance;
- brownfield com baixa confiança.
## Passo 6 — Testar um dry run
Execute uma feature simples:
```text
/sdd orchestration "adicionar texto auxiliar em uma tela existente"
```
Pare antes de Execution se ainda estiver calibrando o projeto.
## Passo 7 — Publicar convenções
Documente no repositório alvo:
- onde ficam PRD/Tech Spec/Memory;
- qual padrão de nome cria `docs/<slug-da-orquestracao>/`;
- padrão de nomes para branches e PRs;
- quais gates são obrigatórios;
- quais comandos validam o projeto;
- quem aprova produto, arquitetura, merge e deploy.
## Passo 8 — Operar em produção
Só relaxe checkpoints quando houver histórico:
- pelo menos algumas features completas;
- review sem achados críticos recorrentes;
- CI confiável;
- rastreabilidade consistente;
- memória útil para ciclos seguintes.
## Presets
Use o preset mais próximo e ajuste:
- `generic`: fallback seguro.
- `frontend-react`: React/TypeScript.
- `backend-node`: Node/TypeScript com APIs e migrations.
- `hono-api`: API Hono/TypeScript, incluindo workers.
- `python-api`: API FastAPI.
- `rust-api`: API Rust com Axum, Actix, Rocket, Poem, Salvo, Warp ou Tonic.
- `monorepo`: apps/packages/services.
- `infra`: Terraform/Kubernetes/infra.
## Validação pós-instalação
```bash
sdd doctor
sdd ci
sdd artifact status "minha-primeira-orquestracao"
```