# 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

| Situação | Modo recomendado |
|---|---|
| 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

| Parte | Superfície SDD | Evidência |
|---|---|---|
| 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`

- Workflow: `.devin/workflows/agentic-sdd-loop.md`.
- Agent: `.devin/agents/sdd-orchestrator/AGENT.md`.
- Skills por etapa: `.devin/skills/<stage>/SKILL.md`.
- Uso recomendado:
  - trate `agentic-sdd-loop` como playbook 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
```
