# Ideia — SDD CLI (TUI)

**Etapa:** 1 — Product Discovery · **Data:** 2026-06-06 · **Estado:** draft

---

## Problema

O `sdd` hoje opera exclusivamente como harness determinístico invocado por agentes externos (Claude Code, Codex, opencode, Cursor). Toda a inteligência do fluxo reside no agente externo. Quem usa o terminal diretamente não tem como interagir com o fluxo SDD de forma guiada — só consegue invocar subcomandos isolados (`sdd idea`, `sdd prd`) sem visibilidade de estado, progresso ou artefatos anteriores.

**Problemas concretos:**
- Nenhum feedback visual durante etapas longas (sem loader, sem progresso, sem streaming).
- Impossível navegar entre etapas com contexto (o usuário precisa lembrar manualmente em que etapa está e o que já foi aprovado).
- Checkpoints humanos são invisíveis na CLI atual — o fluxo para ou avança sem sinalização clara.
- Artefatos em `docs/<slug>/` não têm forma interativa de serem visualizados ou aprovados no terminal.
- O `sdd` não tem modo de operação sem agente externo: não chama providers de IA por conta própria nem exibe output em streaming.

---

## Objetivo

Criar uma experiência **standalone e interativa no terminal**: uma TUI (Terminal User Interface) com loaders dinâmicos, navegação por etapas e iteração ao vivo, que permita conduzir o fluxo SDD diretamente pelo terminal, sem depender de Claude Code, Cursor ou qualquer editor/agente por cima. O modelo de referência é o `opencode`/Charm: TUI rica, com progresso, input e resultados formatados em tempo real.

**Proposta de valor:** para o engenheiro no terminal, o SDD CLI (TUI) é a primeira forma de conduzir o fluxo Spec-Driven completo (Ideia → Memória) sem agente/editor externo, com feedback visual ao vivo, navegação guiada e checkpoints como parte do produto.

**Diferenciais frente ao `sdd` atual:** loaders/spinners, navegação interativa com estado, checkpoints com aprovação na tela, Markdown renderizado inline, streaming do output da IA.

**Diferenciais frente a opencode/Charm:** não é chat genérico — é fluxo estruturado e opinionado; cada "tela" é uma etapa SDD rastreável; integra com o artifact store local (`docs/<slug>/`) e o `traceability-map.yaml`.

---

## Usuários

**Persona primária — Engenheiro solo / tech lead no terminal:** usa o terminal como ambiente principal (scripts, CI interativo, SSH, ambientes sem GUI); confortável com TUIs (git, lazygit, k9s); valoriza feedback imediato sem sair do terminal.

**Persona secundária — Dev em projetos pessoais/OSS:** não tem licença de Claude Code ou não quer depender de agente pago; quer explorar o fluxo SDD interativamente.

**Fora do escopo de persona:** equipes que já têm Claude Code/Codex configurados — o harness atual já as atende.

---

## Critérios de sucesso

- Um usuário consegue conduzir uma orquestração da Ideia até a Memória inteiramente pela TUI, sem invocar um agente externo.
- Toda etapa de IA exibe loader/streaming; nenhuma etapa longa fica sem feedback visual por mais de ~200ms.
- Todo checkpoint humano (PRD, Tech Spec, Refinement, Merge) é apresentado como prompt explícito de aprovação na tela.
- Artefatos aprovados são gravados em `docs/<slug>/` e refletidos no `traceability-map.yaml` automaticamente, idênticos em contrato aos gerados pelo harness.
- Tempo da abertura da TUI à primeira tela útil < 1s.
- A TUI roda em macOS e Linux nos terminais comuns (iTerm2, Terminal.app, alacritty, kitty) sem corromper o layout.

---

## Jornada principal

1. `sdd tui` (ou `sdd` sem subcomando) dentro de um projeto com `.sdd/` instalado.
2. Tela inicial lista orquestrações de `docs/` com estado + opção de criar nova.
3. Nova orquestração: digita a ideia em linguagem natural; loader enquanto a IA processa a etapa `idea`.
4. Artefato gerado é exibido inline (Markdown renderizado); editar / regenerar / aprovar.
5. Aprovação (checkpoint): salva em `docs/<slug>/01-idea.md` e atualiza o `traceability-map.yaml`.
6. Progressão: PRD → Tech Spec → Tasks (→ Refinement opcional) com o mesmo ciclo loader → visualização → aprovação.
7. Checkpoint crítico antes de Execution e antes de Merge: painel de confirmação com resumo de risco.
8. Após Memory: resumo da orquestração com todos os artefatos e links.

---

## MVP sugerido

| Funcionalidade | Descrição |
|---|---|
| Comando `sdd tui` | Ponto de entrada; carrega a TUI no terminal |
| Tela de orquestrações | Lista existentes com estado; opção de criar nova |
| Input de ideia | Campo de texto para a feature em linguagem natural |
| Loader dinâmico | Spinner/progress enquanto a etapa de IA processa |
| Streaming de output | Exibe o texto gerado conforme chega (se o provider suportar) |
| Visualização de artefato | Markdown renderizado inline (sem editor externo) |
| Aprovação de checkpoint | Aprovar / Regenerar / Editar com atalhos de teclado |
| Salvamento automático | Grava o artefato e atualiza o `traceability-map.yaml` |
| Navegação por etapas | Avança/recua com visibilidade do estado atual |
| Provider configurado | Usa o provider de `sdd.config.yaml` para chamar a IA |

**Crates candidatas (a confirmar na Tech Spec):** `ratatui`, `crossterm`, `tokio`, `reqwest`.

**Fora do MVP:** múltiplos providers/seletor na TUI; editor inline completo; diff entre versões; Agent Teams paralelos na TUI; integrações externas (Jira/Confluence/Bitbucket) na TUI; plugin de editor; instalador empacotado; Windows.

---

## Hipóteses

1. **Demanda:** devs que usam `sdd` querem experiência standalone sem Claude Code (não validado).
2. **Viabilidade técnica:** é possível invocar providers (Anthropic/OpenAI) direto do binário Rust com streaming, sem o agente externo, mantendo qualidade — depende dos prompts embarcados.
3. **Usabilidade:** Ratatui oferece experiência fluida o suficiente para o fluxo (streaming + Markdown + navegação tem curva não trivial).
4. **Adoção:** parte do uso via harness migra para a TUI quando disponível.

---

## Riscos iniciais

| Risco | Severidade | Descrição |
|---|---|---|
| Subagents de IA não existem fora do agente externo | Alto | O fluxo depende de subagents em `.claude/agents/` que só rodam no Claude Code. A TUI precisaria replicar esses prompts no binário ou orquestrar chamadas diretas ao provider — mudança arquitetural, não só nova UI. |
| Qualidade dos artefatos cai sem o contexto do agente | Alto | Subagents têm contexto da conversa, leitura de arquivos e iteração. Chamada HTTP direta pode produzir artefatos inferiores. |
| Complexidade de TUI com streaming + Markdown | Médio | Viável em Ratatui, mas trabalhoso. |
| Dependências novas no Cargo.toml | Médio | `ratatui`/`crossterm`/`tokio`/`reqwest`: conflito de versão, cross-compile, tamanho do binário. |
| Fragmentação de experiência | Baixo-Médio | Dois modos (harness e TUI) podem divergir nos artefatos. |
| Compatibilidade de terminal | Baixo | Terminais antigos podem não suportar features de TUI. |

---

## Perguntas em aberto (decisivas para o PRD)

1. **Modelo de execução da IA na TUI** — chamar provider direto (HTTP + prompt embarcado) ou delegar a um processo `claude`/`opencode` local? Define toda a arquitetura.
2. **Prompts dos subagents** — duplicados no binário? Como sincronizar com `.claude/agents/*.md`?
3. **Provider no MVP** — só o de `sdd.config.yaml` ou seletor mínimo?
4. **TUI substitui ou complementa o harness?**
5. **Critério de qualidade do artefato gerado sem agente.**
6. **Autenticação com o provider** — variável de ambiente ou fluxo interativo?
7. **Edição de artefatos** — `$EDITOR` externo ou só aprovar/regenerar?

---

## Rastreabilidade

| Campo | Valor |
|---|---|
| Orquestração | `criar-um-cli-poderoso-...-sdd-cli` |
| Artefato de origem | `00-risk-classification.md` (risco: medium, fator: external_dependency) |
| Próximo artefato | `02-prd.md` (aguarda aprovação desta Ideia) |
| Estado no traceability-map | `idea: pending` |
