# SDD Bot
Integração Slack-first para o fluxo SDD. O bot conecta Slack, Jira, Bitbucket 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 Jira (coluna de backlog/ideia) com status `/bloqueado`.
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 promove o card no Jira, faz commit com marcador de aprovação e arquiva o canal.
---
## Pré-requisitos
| 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 | Cloud ou Server acessível | token de API gerado |
| Bitbucket | Cloud ou Server acessível | App Password gerado |
---
## 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`.
| `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)
| `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)
| `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`, `jira`, `bitbucket`, `llm` e `sdd`. Veja `.sdd/bot/sdd-bot.config.example.yaml` para a referência completa.
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
```