# Agentic SDD Loop
Este módulo documenta o loop operacional para agents e clients que precisam conduzir uma demanda de entrada até artefatos SDD rastreáveis, com avaliação, retry, memória e checkpoints humanos. Ele não substitui o fluxo SDD; ele amarra as peças existentes em uma receita portátil.
## Resumo executivo
- Decisão: o loop oficial é `agentic-sdd-loop`, declarado em `templates/workflows/agentic-sdd-loop.yaml`.
- Escopo: intake, planejamento durável, gates, pós-planejamento supervisionado, observabilidade e handoff entre clients.
- Estado: workflow v1 conservador; automatiza até o primeiro gate humano e delega execução/review/memory ao motor supervisionado.
- Próximo passo: rode `sdd workflow validate agentic-sdd-loop --json` e depois `sdd workflow run agentic-sdd-loop --input "<demanda>" --json`.
## Rastreabilidade
- Origem: evolução dos workflows dinâmicos em `docs/WORKFLOWS.md`, motor autônomo em `docs/orquestrador-autonomo-de-demandas-sdd/` e guias de compatibilidade de provider.
- Artefato atual: `docs/AGENTIC-SDD-LOOP.md`.
- Workflow: `templates/workflows/agentic-sdd-loop.yaml`.
- Estado atual: documentação e recipe local.
- Evidências esperadas: `.sdd/workflows/agentic-sdd-loop.json`, `.sdd/workflows/standard-sdd.json`, `.sdd/workflows.jsonl`, `.sdd/orchestrator.jsonl`, `.sdd/evaluations.jsonl` e `docs/<slug>/traceability-map.yaml`.
## Quando usar
Use `agentic-sdd-loop` quando a entrada vier de texto livre, card, bot, webhook ou agente externo e você quiser um caminho padronizado para:
- resolver a entrada em uma orquestração canônica;
- criar ou retomar o artifact store local;
- rodar o planejamento até o primeiro gate;
- deixar evidência durável para qualquer client continuar;
- preparar execução/review/memory supervisionadas sem autoaprovar checkpoints.
Para bugs já reproduzíveis, use `bugfix-diagnostic-loop`. Para uma task de implementação já pronta, use `deep-execution-review`. Para onboarding de stack e hardening de skills, use `discovery-skill-hardening`.
## Comandos principais
```bash
sdd workflow validate agentic-sdd-loop --json
sdd workflow run agentic-sdd-loop --input "<demanda>" --max-iterations 3 --json
sdd workflow status agentic-sdd-loop --json
```
Depois do primeiro gate aprovado, continue pelo motor SDD:
```bash
sdd demand approve <id> --gate prd --by "<pessoa>"
sdd auto run --real
sdd auto run --real --through review
sdd auto run --real --through memory
sdd auto run --real --unattended
```
Use `--real` somente quando o provider/adapter estiver configurado e autorizado. Sem `--real`, o runner sintético continua útil para validar o contrato e o estado.
`--unattended` é o modo 100% automático: ele aceita gates de planejamento pendentes com `channel: automation`, usa `sdd-auto` como autor auditável e, quando `--through` não é informado, segue até `memory`. Isso não representa aprovação humana; a origem automática fica em `.sdd/state/<slug>.json` e os eventos `gate_auto_accept` ficam em `.sdd/orchestrator.jsonl`.
## Guia de uso recomendado
Use `agentic-sdd-loop` como porta de entrada padrão quando a demanda chegar por agent, card, issue, webhook, bot ou texto livre e ainda precisar de normalização antes de virar execução. Para uma feature já especificada e pronta para planejamento, `standard-sdd` continua suficiente. Para uma validação sem tocar código, use `dry-run-sdd`.
### Caminho feliz
1. Rode o loop com a demanda original:
```bash
sdd workflow run agentic-sdd-loop --input "<demanda>" --max-iterations 3 --json
```
2. Verifique o envelope agentic em `.sdd/workflows/agentic-sdd-loop.json`.
3. Verifique o planejamento interno em `.sdd/workflows/standard-sdd.json`.
4. Revise o PRD e registre decisão humana no gate:
```bash
sdd demand approve <id> --gate prd --by "<pessoa>"
```
5. Continue pelo motor supervisionado conforme a capacidade do provider:
```bash
sdd auto run --real
sdd auto run --real --through review
sdd auto run --real --through memory
sdd auto run --real --unattended
```
6. Ao final, confirme que `docs/<slug>/traceability-map.yaml`, artefatos aprovados e memória estão atualizados.
### Melhores práticas para agents
- Preserve a entrada original em `--input`; ela é a âncora de rastreabilidade do ciclo.
- Consulte `sdd workflow status agentic-sdd-loop --json` antes de retomar um trabalho interrompido.
- Não reexecute o loop do zero quando houver checkpoint pendente; aprove, rejeite ou ajuste o gate e continue pelo motor SDD.
- Não trate `--unattended` como aprovação humana: ele autoaceita PRD, Tech Spec e Refinement como `channel: automation`, mas não aprova merge, release ou deploy.
- Use `.sdd/workflows/agentic-sdd-loop.json` para entender o estado do envelope agentic e `.sdd/workflows/standard-sdd.json` para auditar o planejamento SDD interno.
- Em clients com comando dedicado, use `agentic-sdd-loop` em vez de colar instruções longas no chat.
- Em modo Markdown-only, mantenha artefatos aprovados em `docs/<slug>/` e atualize `traceability-map.yaml`.
- Em integrações externas, mantenha links para Jira, Linear, GitHub, GitLab, Slack ou webhooks como referências; a fonte operacional continua sendo artifact store, checkpoints e traces locais.
### Quando usar cada modo
| Entrada ambígua de agent, card, issue, webhook ou bot | `agentic-sdd-loop` |
| Feature já clara e pronta para planejamento SDD | `standard-sdd` |
| Validação sem escrita de código | `dry-run-sdd` |
| Bug reproduzível com ciclo de hipótese e correção | `bugfix-diagnostic-loop` |
| Task de implementação pronta para execução/review | `deep-execution-review` |
| Etapa isolada ou retomada manual | `/idea`, `/prd`, `/techspec`, `/tasks`, `/execution`, `/review` |
### Leitura dos relatórios
`agentic-sdd-loop.json` responde "onde o envelope agentic parou?". Use-o para ver nodes executados, checkpoint ativo e eventos do workflow externo. `standard-sdd.json` responde "o que o planejamento SDD produziu?". Use-o para conferir artefatos, demanda pausada, estado de aprovação e prontidão para execução.
Se os relatórios divergirem, trate o relatório externo como fonte do estado do loop e o relatório interno como fonte dos artefatos de planejamento. Em seguida rode `sdd workflow status agentic-sdd-loop --json` para obter uma visão atualizada.
## Arquitetura do loop
```mermaid
flowchart TD
A["Entrada: texto, card, bot ou webhook"] --> B["resolve-input"]
B --> C["standard-sdd planning loop"]
C --> D["PRD checkpoint"]
D -->|aprovado| E["Tech Spec, Tasks e Refinement pelo motor SDD"]
E --> F["ready_for_exec"]
F --> G["Execution supervisionada"]
G --> H["ADR quando houver decisão"]
H --> I["Review + avaliação"]
I -->|falhou com evidência nova| G
I -->|aprovado| J["Memory"]
D -->|rejeitado| K["volta para PRD/Idea com decisão humana"]
I -->|sem progresso| L["stopped_no_progress / handoff humano"]
```
## Mapeamento das partes do loop
| Intake | `sdd resolve-input`, `sdd demand enqueue` | demanda em `.sdd/queue/` e nome canônico |
| Estado | `.sdd/state/<slug>.json` | cursor, status, approvals, attempts e last_error |
| Planejamento | `standard-sdd` dentro de `agentic-sdd-loop` | `01-idea.md`, `02-prd.md`, traceability-map |
| Checkpoint | node `checkpoint` e `sdd demand approve/reject` | approvals no estado durável |
| Execução | `sdd auto run --real --through execution|review|memory` | `06-execution.md`, `.sdd/execution-runs.jsonl` |
| Avaliação | `sdd eval stage`, `sdd eval orchestration`, `sdd quality report` | `.sdd/evaluations.jsonl` |
| Retry | `deep-execution-review` ou `bugfix-diagnostic-loop` | workflow report + novas evidências |
| Memória | `08-memory.md` e skill `memory` | decisões e links compactados |
| Observabilidade | `sdd trace`, `sdd mcp serve`, `sdd workflow status` | JSONL local e MCP read-only |
## Política de progresso
O loop só deve continuar quando houver pelo menos uma destas evidências novas:
- nova hipótese;
- nova fonte consultada;
- escopo menor e mais preciso;
- evidência nova de teste, diff, trace, log, review ou avaliação.
Pare e faça handoff humano quando repetir:
- o mesmo erro sem evidência nova;
- o mesmo diff;
- o mesmo comando;
- a mesma busca;
- uma avaliação crítica sem mudança de hipótese ou escopo.
Essa política é implementada em `runtime::optimization::evaluate_productive_loop` e deve orientar qualquer agent mesmo quando o client não expuser o runner de workflow completo.
## Contrato por client
### `.agents` e Antigravity
- Fonte portável: `.agents/skills/orchestration/SKILL.md`.
- Regra Antigravity: `.agents/rules/sdd.md`.
- Uso recomendado:
- carregue a skill `orchestration`;
- rode `sdd workflow run agentic-sdd-loop --input "<demanda>" --json`;
- se comandos não estiverem disponíveis, registre o comando necessário e materialize artefatos Markdown em `docs/<slug>/`.
### `.codex`
- Command/playbook: `.codex/commands/agentic-sdd-loop.md`.
- Agent manifest: `.agents/agents/sdd-orchestrator/AGENT.md`.
- Skill portável: `.agents/skills/orchestration/SKILL.md`.
- Uso recomendado:
- use `/agentic-sdd-loop "<demanda>"` quando a aplicação expuser comandos de `.codex/commands`;
- quando não expuser, abra o playbook e rode `sdd workflow run agentic-sdd-loop --input "<demanda>" --max-iterations 3 --json` pelo terminal;
- mantenha `.agents` como contrato comum e `.codex` como superfície nativa do Codex;
- use o adapter de execução Codex apenas depois dos checkpoints humanos e com workspace autorizado.
### `.claude`
- Skill: `.claude/skills/orchestration/SKILL.md`.
- Command: `.claude/commands/agentic-sdd-loop.md`.
- Uso recomendado:
- use `/agentic-sdd-loop "<demanda>"` para intake de agent, card, webhook ou texto livre;
- resolva o CLI antes de qualquer etapa;
- rode o workflow;
- use subagents por etapa apenas depois que o artifact store existir;
- nunca marque PRD, Tech Spec, Refinement ou Review como `approved` sem decisão humana.
### Devin CLI
- Skill nativa: `.devin/skills/agentic-sdd-loop/SKILL.md`.
- Agent: `.devin/agents/sdd-orchestrator/AGENT.md`.
- Skills por etapa: `.devin/skills/<stage>/SKILL.md`.
- Uso recomendado:
- trate `agentic-sdd-loop` como skill de entrada;
- preserve `.sdd/state` e `.sdd/workflows`;
- se o provider não tiver modo headless confiável, registre `manual:<stage>` e pare.
### `.opencode`
- Command: `.opencode/commands/agentic-sdd-loop.md`.
- Agent: `.opencode/agents/sdd-orchestrator.md`.
- Uso recomendado:
- use o command para iniciar;
- mantenha permissões de edição em `ask`;
- deixe `sdd` executar validações e persistência.
### `.trae`
- Command: `.trae/commands/agentic-sdd-loop.md`.
- Skill: `.trae/skills/orchestration/SKILL.md`.
- Rules: `.trae/rules/`.
- Uso recomendado:
- se o shell não encontrar `sdd`, use `cargo run --bin sdd --` apenas no checkout fonte;
- fora do checkout fonte, reporte PATH/instalação ausente;
- não substitua artifact store por chat-only output.
## Guardrails
- Nenhum workflow autoaprova gate humano.
- `agentic-sdd-loop` não faz merge, release ou deploy.
- Execution com escrita no workspace exige adapter autorizado.
- Ferramentas opcionais como CodeGraph, MCP, browser, subagents e runtime adapters devem ter fallback por Markdown, CLI e artifact store.
- Texto humano em PT-BR preserva acentuação; slugs, comandos, paths e schemas continuam ASCII quando necessário.
## Validação de prontidão
```bash
sdd workflow validate agentic-sdd-loop --json
sdd workflow list --json
sdd clients doctor --strict
sdd skills doctor --strict
sdd capabilities doctor --targets all
```
Para uma orquestração real:
```bash
sdd eval orchestration --name "<ciclo>" --json
sdd quality report --name "<ciclo>" --json
sdd trace summary --orchestration "<ciclo>" --json
```