create-sdd-workflow 0.1.0

package/manual_workflow_sdd_grillme_tlc.md

@@ -0,0 +1,472 @@
+# Tutorial — Usando a skill `iniciar-projeto-sdd`
+
+Este tutorial explica como usar a skill `iniciar-projeto-sdd` para transformar uma ideia inicial em documentação de produto, documentação técnica e specs executáveis por fatias verticais.
+
+A skill conduz um workflow SDD com:
+
+- Brief Inicial;
+- Grill-me do Brief Inicial;
+- Grill-me de produto;
+- PRD Principal;
+- compressão/revisão do PRD;
+- PreSpec Técnica;
+- documentos técnicos derivados;
+- specs TLC por fatia vertical.
+
+O objetivo não é implementar código imediatamente. O objetivo é criar uma base clara de produto e engenharia antes da execução.
+
+## 1. Quando usar
+
+Use esta skill quando você estiver começando um projeto novo e quiser gerar documentação guiada antes de implementar.
+
+Exemplos de pedidos:
+
+```txt
+/iniciar-projeto-sdd
+```
+
+```txt
+/iniciar-projeto-sdd Nome: Meu Produto. Ideia: Uma ferramenta para organizar estudos com IA.
+```
+
+```txt
+iniciar projeto sdd
+```
+
+```txt
+crie a estrutura do workflow SDD
+```
+
+Para retomar depois:
+
+```txt
+/continuar-sdd
+```
+
+## 2. O que a skill cria
+
+Ao iniciar, a skill cria a estrutura base do projeto:
+
+```txt
+workflow/
+  00-AGENTS-template.md
+  01-brief-template.md
+  02-grillme-brief-prompt.md
+  03-grillme-product-prompt.md
+  04-prd-template.md
+  05-prd-compression-prompt.md
+  06-prespec-prompt.md
+  07-derive-docs-prompt.md
+  08-tlc-execution-prompt.md
+  09-quality-checklists.md
+
+docs/
+  product/
+  technical/
+  decisions/
+
+.specs/
+  project/
+    STATE.md
+  features/
+
+AGENTS.md
+```
+
+O arquivo `.specs/project/STATE.md` é o marcador de estado do fluxo. Antes de continuar qualquer etapa, a skill deve ler esse arquivo.
+
+## 3. Setup inicial
+
+Existem dois jeitos de começar.
+
+### Com nome e ideia
+
+Se você passar nome e ideia no comando inicial, a skill cria a estrutura e registra esses dados no `STATE.md`.
+
+Exemplo:
+
+```txt
+/iniciar-projeto-sdd Nome: StudyFlow. Ideia: Um app para ajudar estudantes a organizar revisões.
+```
+
+Resultado esperado:
+
+- estrutura do workflow criada;
+- `AGENTS.md` criado;
+- `.specs/project/STATE.md` criado;
+- nome e ideia registrados como contexto inicial.
+
+Depois disso, o agente inicia o Grill-me do Brief Inicial. Ele pode usar nome e ideia como contexto e fazer apenas as perguntas que ainda forem necessárias.
+
+### Sem nome ou ideia
+
+Se você rodar apenas:
+
+```txt
+/iniciar-projeto-sdd
+```
+
+a skill cria somente a estrutura e o `STATE.md`.
+
+Ela não cria `docs/product/Brief_Inicial.md` vazio.
+
+Nesse caso, o agente inicia o Grill-me do Brief Inicial perguntando primeiro o essencial para conseguir gerar o brief.
+
+## 4. Brief Inicial
+
+O Brief Inicial é um documento curto para registrar a ideia bruta sem inventar detalhes demais.
+
+Arquivo gerado:
+
+```txt
+docs/product/Brief_Inicial.md
+```
+
+Regras importantes:
+
+- você não preenche esse template manualmente;
+- a skill usa um Grill-me curto para preencher o brief;
+- o limite é de até 3 perguntas;
+- as perguntas vêm uma por vez;
+- cada pergunta vem com uma resposta recomendada;
+- registra lacunas como dúvidas iniciais;
+- usa premissas apenas quando forem seguras;
+- não pergunta sobre stack, banco, framework, deploy, arquitetura ou código.
+
+Depois de gerar o Brief Inicial, a skill mostra opções numeradas:
+
+```txt
+Escolha o próximo passo:
+
+1. Enriquecer o Brief Inicial.
+2. Continuar para o Grill-me de produto.
+3. Pausar para revisão manual.
+```
+
+Você responde com o número da opção.
+
+## 5. Grill-me do brief
+
+Esta etapa acontece automaticamente para criar o Brief Inicial.
+
+Ela também pode ser usada depois, caso você escolha a opção de enriquecer o brief.
+
+Limites:
+
+- até 3 perguntas;
+- uma pergunta por vez;
+- cada pergunta deve vir com uma resposta recomendada;
+- perguntas apenas sobre as 8 seções do Brief Inicial.
+
+Ao final, a skill cria ou atualiza `docs/product/Brief_Inicial.md` e mostra opções numeradas para o próximo passo.
+
+## 6. Grill-me de produto
+
+Esta é a etapa principal de descoberta de produto.
+
+A skill usa o Brief Inicial como fonte base e faz perguntas para gerar um PRD enxuto e autoexplicativo.
+
+Você chega nesta etapa escolhendo a opção `Continuar para o Grill-me de produto` depois do Brief Inicial.
+
+Limites:
+
+- até 30 blocos;
+- cada bloco tem de 3 a 5 perguntas;
+- cada pergunta vem com uma resposta recomendada;
+- o limite é por blocos, não por número total de perguntas.
+
+O Grill-me de produto pode cobrir:
+
+- problema e contexto;
+- público-alvo;
+- proposta de valor;
+- escopo do MVP;
+- funcionalidades principais;
+- regras de negócio;
+- fluxos principais;
+- métricas, riscos e decisões em aberto.
+
+Nesta etapa a skill não deve perguntar sobre:
+
+- stack;
+- banco;
+- framework;
+- endpoints;
+- schema;
+- ORM;
+- deploy;
+- arquitetura;
+- implementação.
+
+Quando a entrevista termina ou atinge o limite, a skill gera automaticamente o PRD Principal.
+
+## 7. PRD Principal
+
+Arquivo gerado:
+
+```txt
+docs/product/PRD_Principal.md
+```
+
+O PRD é a fonte de verdade de produto.
+
+Ele deve conter:
+
+1. Resumo
+2. Problema
+3. Público-alvo
+4. Proposta de valor
+5. Objetivos do MVP
+6. Escopo do MVP
+7. Funcionalidades principais
+8. Regras de negócio principais
+9. Fluxos principais
+10. Requisitos funcionais
+11. Requisitos não funcionais
+12. Critérios de aceite
+13. Métricas de sucesso
+14. Riscos e mitigação
+15. Decisões tomadas
+16. Decisões em aberto
+
+Depois de gerar o PRD, a skill deve:
+
+- atualizar `.specs/project/STATE.md`;
+- parar o fluxo;
+- mostrar opções numeradas antes da compressão/revisão.
+
+Exemplo:
+
+```txt
+Escolha o próximo passo:
+
+1. Revisar e compactar o PRD.
+2. Pausar para revisão manual.
+```
+
+## 8. Compressão e revisão do PRD
+
+Esta etapa só começa quando você escolhe a opção `Revisar e compactar o PRD`.
+
+Objetivo:
+
+- reduzir redundância;
+- melhorar clareza;
+- preservar decisões importantes;
+- preservar escopo e fora de escopo;
+- preservar critérios de aceite;
+- remover detalhes técnicos prematuros.
+
+Limite:
+
+- até 5 perguntas, apenas se houver lacunas importantes.
+
+Ao final, a skill atualiza o PRD e o `STATE.md`.
+
+Depois disso, ela para novamente e pede aprovação explícita do PRD revisado antes de iniciar a PreSpec Técnica.
+
+Exemplo:
+
+```txt
+Escolha o próximo passo:
+
+1. Aprovar PRD revisado e gerar PreSpec Técnica.
+2. Fazer ajustes no PRD.
+3. Pausar.
+```
+
+## 9. PreSpec Técnica
+
+Esta etapa só começa depois que você escolhe a opção `Aprovar PRD revisado e gerar PreSpec Técnica`.
+
+Arquivo gerado:
+
+```txt
+docs/technical/PreSpec_Tecnica.md
+```
+
+A PreSpec é a ponte entre produto e engenharia. Ela ainda não escolhe stack nem entra em implementação detalhada.
+
+Ela pode tratar de:
+
+- entidades conceituais;
+- permissões;
+- dados essenciais;
+- regras de domínio;
+- validações;
+- contratos conceituais;
+- riscos técnicos;
+- estratégia inicial de testes;
+- backlog por fatias verticais.
+
+Limite:
+
+- até 10 perguntas técnicas conceituais, se forem necessárias.
+
+Não deve perguntar sobre:
+
+- framework específico;
+- ORM específico;
+- biblioteca específica;
+- provedor de deploy;
+- código;
+- implementação detalhada.
+
+## 10. Derivação técnica
+
+Depois da PreSpec, a skill deriva os documentos técnicos especializados.
+
+Arquivos esperados:
+
+```txt
+docs/technical/Domain_Model.md
+docs/technical/Architecture.md
+docs/technical/API_Contracts.md
+docs/technical/Test_Strategy.md
+docs/decisions/ADR-*.md
+.specs/project/PROJECT.md
+.specs/project/ROADMAP.md
+.specs/features/[feature]/spec.md
+.specs/features/[feature]/design.md
+.specs/features/[feature]/tasks.md
+```
+
+Regra principal:
+
+- a skill não faz nova entrevista nessa etapa, salvo inconsistência crítica entre PRD e PreSpec.
+
+É nessa fase, e não no setup, que `PROJECT.md` e `ROADMAP.md` devem nascer.
+
+## 11. TLC por fatia vertical
+
+Depois que os documentos técnicos e specs existem, a execução passa a ser por fatia vertical.
+
+Cada fatia deve ter:
+
+```txt
+.specs/features/[feature]/spec.md
+.specs/features/[feature]/design.md
+.specs/features/[feature]/tasks.md
+```
+
+A skill deve trabalhar uma fatia por vez.
+
+Regras:
+
+- não alterar escopo global sem atualizar documentação;
+- não implementar fora da fatia selecionada;
+- fazer até 5 perguntas se houver lacunas relevantes;
+- atualizar `STATE.md` ao final;
+- marcar tasks concluídas;
+- registrar decisões importantes como ADR.
+
+## 12. Máquina de estados
+
+A skill não segue uma lista linear cega. Ela lê `.specs/project/STATE.md` e decide o próximo passo.
+
+Fluxo resumido:
+
+```txt
+Setup
+  ↓
+Grill-me do Brief Inicial
+  ↓
+Brief Inicial gerado
+  ↓
+opções: enriquecer brief / continuar / pausar
+  ↓
+Grill-me de produto
+  ↓
+PRD Principal
+  ↓
+checkpoint: confirmar compressão/revisão
+  ↓
+PRD revisado
+  ↓
+checkpoint: aprovar PRD revisado
+  ↓
+PreSpec Técnica
+  ↓
+Docs técnicos derivados
+  ↓
+Specs TLC
+  ↓
+Execução por fatia vertical
+```
+
+Se houver uma próxima etapa inequívoca no `STATE.md`, a skill pode continuar automaticamente.
+
+Se houver mais de um caminho válido, ela deve mostrar opções numeradas e aguardar sua escolha.
+
+## 13. Checkpoints obrigatórios
+
+A skill deve parar e pedir confirmação nestes pontos:
+
+1. depois de criar ou atualizar o Brief Inicial;
+2. depois de gerar o PRD Principal;
+3. depois de revisar/compactar o PRD;
+4. antes de iniciar implementação de uma fatia vertical se houver lacunas relevantes.
+
+Essa confirmação deve ser apresentada como opções numeradas, não como exigência de digitar uma frase específica.
+
+O checkpoint mais importante é este:
+
+```txt
+PRD revisado → aprovação explícita → PreSpec Técnica
+```
+
+Isso evita que decisões técnicas nasçam antes da fonte de verdade de produto estar aprovada.
+
+## 14. Comandos úteis
+
+Iniciar estrutura sem brief:
+
+```txt
+/iniciar-projeto-sdd
+```
+
+Iniciar com brief:
+
+```txt
+/iniciar-projeto-sdd Nome: [nome]. Ideia: [ideia].
+```
+
+Continuar fluxo:
+
+```txt
+/continuar-sdd
+```
+
+Nos checkpoints, escolha uma das opções numeradas mostradas pelo agente.
+
+## 15. Checklist rápido de uso
+
+Para usar em um projeto novo:
+
+1. Rode `/iniciar-projeto-sdd`.
+2. Responda o Grill-me curto do Brief Inicial.
+3. A skill gera `docs/product/Brief_Inicial.md`.
+4. Escolha se deseja enriquecer o brief, continuar ou pausar.
+5. Se escolher continuar, responda o Grill-me de produto.
+6. Responda os blocos de perguntas.
+7. Revise o PRD gerado.
+8. Escolha se deseja revisar/compactar o PRD.
+9. Depois da revisão, escolha se aprova o PRD revisado e gera a PreSpec.
+10. Gere a PreSpec Técnica.
+11. Derive os documentos técnicos.
+12. Execute uma fatia vertical por vez.
+
+## 16. Distribuição futura via npm/npx
+
+A skill foi organizada para poder virar um pacote npm/npx no futuro.
+
+O pacote deve incluir:
+
+- `skills/iniciar-projeto-sdd/SKILL.md`;
+- `skills/iniciar-projeto-sdd/scripts/init_sdd_project.sh`;
+- `skills/iniciar-projeto-sdd/assets/workflow/`;
+- `skills/iniciar-projeto-sdd/references/workflow-summary.md`.
+
+O comando npx deve conseguir rodar em qualquer diretório alvo, copiar os templates de `assets/workflow` e preservar `SDD_WORKFLOW_TEMPLATE_DIR` como opção para desenvolvimento local.
+
+Instalação global em `~/.agents/skills` não é parte obrigatória deste fluxo. Ela pode ser usada como conveniência local, mas a distribuição planejada é via npm/npx.

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "create-sdd-workflow",
+  "version": "0.1.0",
+  "description": "Scaffold an SDD documentation workflow with Brief, PRD, PreSpec, technical docs, and vertical-slice specs.",
+  "type": "commonjs",
+  "bin": {
+    "create-sdd-workflow": "bin/create-sdd-workflow.js"
+  },
+  "files": [
+    "bin/",
+    "workflow/",
+    "skills/iniciar-projeto-sdd/",
+    "manual_workflow_sdd_grillme_tlc.md",
+    "AGENTS.md",
+    "README.md"
+  ],
+  "keywords": [
+    "sdd",
+    "spec-driven",
+    "workflow",
+    "documentation",
+    "prd",
+    "prespec",
+    "scaffold",
+    "codex"
+  ],
+  "author": "Vonderheidon",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "smoke": "node bin/create-sdd-workflow.js /tmp/create-sdd-workflow-smoke --force --name Smoke --idea \"Validate package scaffold\""
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/skills/iniciar-projeto-sdd/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: iniciar-projeto-sdd
+description: Inicializa e conduz um workflow SDD com Grill-me, Brief Inicial, PRD, PreSpec Técnica, docs derivados e TLC por fatias verticais. Use quando o usuário pedir /iniciar-projeto-sdd, iniciar um projeto SDD, criar a estrutura /workflow, ou transformar uma ideia em documentação guiada.
+---
+
+# Iniciar Projeto SDD
+
+Use esta skill para inicializar automaticamente um projeto com o workflow SDD + Grill-me + PreSpec + TLC.
+
+## Fluxo
+
+1. Extraia do pedido do usuário, se existirem, `Nome` e `Ideia`.
+2. Rode `scripts/init_sdd_project.sh` no diretório alvo para criar a estrutura base sem sobrescrever arquivos existentes.
+   - Se houver nome e ideia, passe `--name "[nome]" --idea "[ideia]"` para registrar esses dados no estado inicial.
+   - Se não houver nome e ideia, rode apenas o setup.
+3. O setup deve criar `.specs/project/STATE.md` desde o começo.
+4. O setup não deve criar `.specs/project/PROJECT.md` nem `.specs/project/ROADMAP.md`; esses arquivos só nascem na derivação técnica, depois da PreSpec.
+5. O setup não deve criar `docs/product/Brief_Inicial.md` vazio.
+6. Após o setup, inicie o Grill-me do Brief Inicial automaticamente para preencher o brief.
+7. Faça no máximo 3 perguntas de brief, uma por vez, cada uma com resposta recomendada.
+8. Se nome e ideia já foram fornecidos, trate-os como contexto inicial e pergunte apenas o que ainda for necessário.
+9. Não faça perguntas fora do escopo das 8 seções do Brief Inicial.
+10. Ao terminar a entrevista curta, gere `docs/product/Brief_Inicial.md` usando exatamente `workflow/01-brief-template.md`.
+11. Use premissas e dúvidas iniciais para preencher lacunas que não bloqueiam o entendimento.
+12. Atualize `.specs/project/STATE.md` com a etapa atual, próxima decisão e log curto.
+13. Depois de criar ou atualizar o Brief Inicial, pare e apresente opções numeradas para o usuário escolher.
+14. Só avance para PRD depois que o usuário escolher a opção de continuar para o Grill-me de produto.
+
+## Regras da Etapa 1
+
+- O Brief Inicial deve conter exatamente estas seções:
+  1. Ideia em uma frase
+  2. Problema percebido
+  3. Público imaginado
+  4. Solução imaginada
+  5. Contexto de uso
+  6. Resultado esperado
+  7. Restrições conhecidas
+  8. Dúvidas iniciais
+- Não adicione seções.
+- Não pergunte sobre stack, banco, framework, arquitetura, implementação, deploy ou código.
+- Não crie `docs/product/Brief_Inicial.md` vazio durante o setup.
+- Use Grill-me para preencher o Brief Inicial; o usuário não deve precisar preencher o template manualmente.
+- Faça no máximo 3 perguntas de brief, uma por vez.
+- Para cada pergunta, forneça uma resposta recomendada.
+- Mantenha o Brief Inicial conservador: não preencha lacunas relevantes por inferência forte.
+- Se algo puder ser assumido sem grande risco, registre como premissa na seção mais adequada.
+- Se algo não for essencial agora, registre em `8. Dúvidas iniciais`.
+- Após gerar o brief, apresente opções numeradas em vez de exigir comandos em linguagem natural.
+
+## Comandos de ativação esperados
+
+Trate estes pedidos como equivalentes:
+
+- `/iniciar-projeto-sdd`
+- `/iniciar-projeto-sdd Nome: X. Ideia: Y.`
+- `iniciar projeto sdd`
+- `use iniciar-projeto-sdd`
+- `crie a estrutura do workflow SDD`
+
+## Continuação do fluxo
+
+Trate `/continuar-sdd` e `continuar sdd` como pedidos para retomar o fluxo a partir do estado atual.
+
+Antes de continuar, leia `.specs/project/STATE.md` e `docs/product/Brief_Inicial.md`.
+
+Se o estado indicar que o Brief Inicial ainda não existe, continue o Grill-me do Brief Inicial.
+
+Se houver uma próxima etapa inequívoca no `STATE.md`, continue automaticamente.
+
+Se houver mais de um caminho válido, mostre opções numeradas e aguarde escolha do usuário.
+
+Após gerar o Brief Inicial, apresente opções como:
+
+1. Enriquecer o Brief Inicial com até 3 perguntas.
+2. Continuar para o Grill-me de produto.
+3. Pausar para revisão manual.
+
+Após gerar o PRD Principal, apresente opções como:
+
+1. Revisar e compactar o PRD.
+2. Pausar para revisão manual.
+
+Após revisar/compactar o PRD, apresente opções como:
+
+1. Aprovar PRD revisado e gerar PreSpec Técnica.
+2. Fazer ajustes no PRD.
+3. Pausar.
+
+Se o usuário escolher enriquecer o brief, use `workflow/02-grillme-brief-prompt.md`.
+
+Se o usuário escolher continuar para produto, use `workflow/03-grillme-product-prompt.md`.
+
+No Grill-me de produto, faça até 30 blocos, com 3 a 5 perguntas por bloco.
+
+O limite se aplica aos blocos, não ao número total de perguntas. Cada pergunta dentro do bloco deve vir acompanhada de uma resposta recomendada.
+
+Quando o Grill-me de produto terminar ou atingir o limite de blocos, gere automaticamente `docs/product/PRD_Principal.md` usando `workflow/04-prd-template.md`.
+
+Não peça confirmação adicional para gerar o PRD depois que a entrevista de produto estiver concluída.
+
+Após gerar o PRD, pare o fluxo, atualize `.specs/project/STATE.md` e peça confirmação antes de iniciar a compressão/revisão do PRD.
+
+## Próximas etapas
+
+Conduza o fluxo como uma máquina de estados baseada em `.specs/project/STATE.md`, não como uma lista linear.
+
+### Estados e transições
+
+1. **Setup sem Brief Inicial**
+   - Pré-condição: `docs/product/Brief_Inicial.md` não existe.
+   - Próxima ação: conduzir o Grill-me do Brief Inicial.
+   - Faça até 3 perguntas, uma por vez, com resposta recomendada.
+   - Ao final, gere `docs/product/Brief_Inicial.md`.
+   - Não rode Grill-me de brief, Grill-me de produto ou PRD.
+
+2. **Brief Inicial em rascunho**
+   - Pré-condição: `docs/product/Brief_Inicial.md` existe.
+   - Mostre opções numeradas:
+     1. Enriquecer o Brief Inicial.
+     2. Continuar para o Grill-me de produto.
+     3. Pausar para revisão manual.
+   - Aguarde escolha.
+
+3. **Grill-me de produto concluído**
+   - Gere automaticamente `docs/product/PRD_Principal.md` usando `workflow/04-prd-template.md`.
+   - Atualize `.specs/project/STATE.md`.
+   - Pare e mostre opções numeradas antes de iniciar `workflow/05-prd-compression-prompt.md`.
+
+4. **PRD gerado, aguardando compressão/revisão**
+   - Só use `workflow/05-prd-compression-prompt.md` após o usuário escolher essa opção.
+   - Ao concluir a compressão/revisão, atualize `docs/product/PRD_Principal.md` e `.specs/project/STATE.md`.
+   - Pare e mostre opções numeradas antes de iniciar a PreSpec.
+
+5. **PRD revisado/aprovado, aguardando PreSpec**
+   - Só use `workflow/06-prespec-prompt.md` após o usuário escolher aprovar o PRD revisado e gerar a PreSpec.
+   - Gere `docs/technical/PreSpec_Tecnica.md`.
+   - Atualize `.specs/project/STATE.md`.
+
+6. **PreSpec concluída, aguardando derivação técnica**
+   - Use `workflow/07-derive-docs-prompt.md`.
+   - Não faça nova entrevista, salvo inconsistência crítica.
+   - Crie `.specs/project/PROJECT.md` e `.specs/project/ROADMAP.md` apenas nesta fase ou depois dela.
+
+7. **Docs técnicos e specs derivados**
+   - Use `workflow/08-tlc-execution-prompt.md` para executar uma fatia vertical por vez.
+
+Crie `.specs/project/PROJECT.md` e `.specs/project/ROADMAP.md` apenas durante a derivação técnica, depois da PreSpec.
+
+Use `references/workflow-summary.md` apenas quando precisar relembrar limites e responsabilidades de cada etapa.