# 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:

| Artefato | Dono do conteúdo | Dono do estado |
|---|---|---|
| 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"
```
