# SDD Bot
Integração Slack-first para o fluxo SDD. O bot conecta Slack, um work tracker (Jira ou GitHub Issues/Projects), um repo provider (Bitbucket ou GitHub) e o CLI `sdd` para transformar uma descrição de feature em card, worktree e canal de sessão em segundos — sem sair do Slack.
---
## O que o bot faz
Ao receber `/sdd bot-criar <descrição>` em um canal de comandos, o bot executa automaticamente:
1. Gera um título conciso para o card usando o LLM configurado.
2. Cria o card no work tracker configurado com status `/bloqueado` por comentário.
3. Cria um worktree git isolado para o card (`<worktrees_root>/<card-id>`).
4. Faz push da branch e cria a estrutura de documentação (`docs/<card-id>/`).
5. Cria um canal privado no Slack para o card, convida o solicitante e os admins.
6. Executa as etapas `risk` e `idea` do CLI `sdd` no worktree, gerando os artefatos `risk-classification.md` e `idea.md`.
7. Faz commit e push dos artefatos gerados.
8. Envia os arquivos para o canal da sessão e aguarda aprovação.
Enquanto o card estiver aberto, o solicitante pode refinar os artefatos com `/sdd card-editar` ou aprovar com `/aprovado`, que registra `/aprovado` no work tracker, faz commit com marcador de aprovação quando aplicável e arquiva o canal.
---
## Pré-requisitos
| Requisito | Versão mínima | Observação |
|---|---|---|
| Node.js | 20.x LTS | `node --version` |
| npm | 10.x | incluído no Node 20 |
| pm2 | qualquer | `npm i -g pm2` |
| CLI `sdd` | instalado e autenticado | `sdd doctor` |
| Slack App | configurada com Socket Mode | veja seção abaixo |
| Jira ou GitHub | Work tracker acessível | Jira API token ou GitHub App/token |
| Bitbucket ou GitHub | Repo provider acessível | token com permissão de push/PR |
## Resiliência de integrações
Os providers Jira/GitHub usam timeout explícito, classificação de status (`auth_forbidden`, `not_found`, `rate_limited`, `server_error`) e redaction de tokens em mensagens de erro. Leituras seguras (`GET`) fazem retry limitado em timeout/conexão, `429` e `5xx`; escritas como criação de issue, comentário e PR não são repetidas automaticamente.
No GitHub, os parâmetros opcionais `request_timeout_ms`, `max_attempts` e `retry_base_delay_ms` permitem ajustar a política por projeto. O receiver de webhooks valida assinatura HMAC, limita payload e responde `413 payload_too_large` para corpos acima do limite configurado.
---
## Instalação rápida
```bash
# 1. A partir da raiz do projeto SDD, instale as dependências do bot
cd bot
npm install
# 2. Gere o arquivo de configuração interativamente
sdd bot install
# O assistente solicita tokens e valida cada campo antes de gravar
# .sdd/bot/sdd-bot.config.yaml (adicionado ao .gitignore automaticamente).
# 3. Inicie o bot em produção com pm2
pm2 start npm --name sdd-bot -- run start
pm2 save
# 4. Verifique o status
sdd bot status
```
Para iniciar sem pm2 (sessão única):
```bash
npm run start
```
---
## Comandos disponíveis
### `/sdd bot-criar <descrição>`
**Canal:** `<prefix>-comandos`
Cria um novo card SDD completo a partir da descrição. O bot responde com o ID do card criado e o link para o canal de sessão aberto em `<prefix>-tasks`.
Exemplo:
```
/sdd bot-criar Adicionar autenticação OAuth2 com Google no portal do cliente
```
---
### `/sdd card-editar <novo texto>`
**Canal:** canal de sessão do card (dentro de `<prefix>-tasks`)
Reavalia os artefatos do card com contexto adicional. O bot regenera `risk-classification.md` e `idea.md` no worktree, exibe um diff das alterações e faz novo commit e push.
Exemplo:
```
/sdd card-editar Incluir suporte a login com conta corporativa (Azure AD)
```
---
### `/aprovado`
**Canal:** canal de sessão do card (dentro de `<prefix>-tasks`)
Aprova os artefatos atuais do card. Apenas o criador do card ou um administrador do workspace pode aprovar. O bot:
- Atualiza o status do `idea.md` para `/aprovado`.
- Faz commit com marcador de aprovação e push.
- Registra a aprovação no canal de logs (`<prefix>-logs`).
- Notifica o canal da sessão e o arquiva.
---
## Estrutura de canais
O bot organiza os canais usando um prefixo derivado dos 4 primeiros caracteres de `slack.session_name`. Com `session_name: "cijira"` o prefixo é `ciji`.
| Canal | Visibilidade | Finalidade |
|---|---|---|
| `ciji-comandos` | Público ou privado | Entrada de comandos `/sdd bot-criar` |
| `ciji-logs` | Privado (admins) | Auditoria de todas as operações do bot |
| `ciji-tasks` | Grupo | Contém os canais individuais de cada card ativo |
| `ciji-tasks-<card-id>` | Privado | Sessão isolada de cada card (criado automaticamente) |
Os canais de sessão são arquivados automaticamente após `/aprovado`.
---
## Estrutura de arquivos por card
Para cada card `<PROJ-ID>`, o bot cria:
```
.worktree/
<PROJ-ID>/ # worktree git isolado (branch <PROJ-ID>)
docs/
<PROJ-ID>/
risk-classification.md # saída da etapa sdd risk
idea.md # saída da etapa sdd idea
.sdd/
bot/
sessions.json # estado das sessões ativas (gerado em runtime)
sdd-bot.config.yaml # configuração do bot (não versionar)
```
Os arquivos de artefato incluem um cabeçalho com metadados de rastreabilidade (card ID, versão, status) gerenciado pelo `FileHeaderManager`.
---
## Permissões da Slack App
Crie a Slack App em [api.slack.com/apps](https://api.slack.com/apps) e configure:
### Bot Token Scopes (OAuth & Permissions)
| Escopo | Necessário para |
|---|---|
| `channels:manage` | Criar e arquivar canais públicos |
| `channels:read` | Ler informações de canais públicos |
| `chat:write` | Postar mensagens |
| `files:write` | Enviar arquivos de artefatos |
| `groups:write` | Criar e arquivar canais privados |
| `groups:read` | Ler informações de canais privados |
| `users:read` | Resolver IDs de usuários admin |
| `users:read.email` | Resolver usuários por e-mail (opcional) |
| `commands` | Registrar o slash command `/sdd` |
### App-Level Token Scopes (Socket Mode)
| Escopo | Necessário para |
|---|---|
| `connections:write` | Conexão via Socket Mode (sem servidor HTTP exposto) |
### Slash Commands
Registre o comando `/sdd` apontando para qualquer URL placeholder (Socket Mode não usa URL). Habilite **Socket Mode** em Settings → Socket Mode.
---
## Configuração
Copie o template e preencha os valores:
```bash
cp .sdd/bot/sdd-bot.config.example.yaml .sdd/bot/sdd-bot.config.yaml
```
O arquivo contém comentários detalhados para cada campo. As seções obrigatórias são `slack`, `llm` e `sdd`, além do provider selecionado em `integrations.work_tracker`/`integrations.repo`. Veja `.sdd/bot/sdd-bot.config.example.yaml` para Jira/Bitbucket e GitHub.
Para GitHub:
```yaml
integrations:
work_tracker: github
repo: github
github:
owner: minha-org
repo: meu-repo
base_branch: main
auth:
app_id: "12345"
installation_id: "67890"
private_key_env: GITHUB_APP_PRIVATE_KEY
token_env: GITHUB_TOKEN
project:
owner_type: organization
owner: minha-org
number: 1
webhook_secret_env: GITHUB_WEBHOOK_SECRET
webhook:
enabled: false
port: 8787
path: /github/webhook
request_timeout_ms: 10000
max_attempts: 3
retry_base_delay_ms: 250
```
O bot cria Issues como `GH-<número>`, adiciona ao Projects v2 quando configurado, usa comentários `/bloqueado`/`/aprovado` como gate compatível com o CLI e cria draft PR quando uma branch/worktree local existir. O provider GitHub usa timeout explícito, retry conservador e tratamento de `429`; ajuste `request_timeout_ms`, `max_attempts` e `retry_base_delay_ms` apenas quando o ambiente exigir. O receiver de webhooks é opcional: ele valida `X-Hub-Signature-256` e despacha `issues`, `issue_comment`, `pull_request`, `check_suite`, `workflow_run` e eventos Projects v2 best-effort.
Variável de ambiente opcional para sobrescrever a raiz do projeto:
```bash
export SDD_BOT_ROOT=/caminho/absoluto/para/o/projeto
```
---
## Resolução de problemas
**O bot não inicia — erro de configuração**
```bash
sdd bot status
# ou
sdd doctor
```
Verifique se `.sdd/bot/sdd-bot.config.yaml` existe e se todos os campos obrigatórios estão preenchidos. O bot exibe a seção e o campo ausentes na mensagem de erro.
**Erro `session_name deve ter ao menos 4 caracteres`**
O campo `slack.session_name` no config tem menos de 4 caracteres. Ajuste para um nome com no mínimo 4 letras.
**Erro ao criar worktree — branch já existe**
A branch `<card-id>` já existe no repositório. Verifique com `git branch -a` e remova a branch conflitante antes de retentar.
**Mensagens duplicadas no canal**
Reiniciar o bot sem arquivar a sessão anterior pode causar duplicatas. Execute `sdd bot status` para listar sessões ativas e arquive manualmente os canais com sessão aberta antes de reiniciar.
**Erro de permissão Jira / Bitbucket**
Confirme que o token configurado tem acesso ao projeto (`project_key`) e ao repositório (`repo_slug`) respectivos. Tokens Jira expiram; gere um novo em id.atlassian.com se necessário.
---
## Desenvolvimento
```bash
# Modo de desenvolvimento com ts-node (hot-reload manual)
npm run dev
# Build para produção
npm run build
# Iniciar a partir do build
npm run start
```
Os testes de unidade ficam em `bot/test/` (quando presentes) e podem ser executados com:
```bash
npm test
```
Para inspecionar logs do pm2 em tempo real:
```bash
pm2 logs sdd-bot
```