create-sdd-workflow 0.1.0

package/AGENTS.md

@@ -0,0 +1,110 @@
+# AGENTS.md
+
+## Objetivo
+
+Este repositório usa um workflow SDD com Grill-me, PreSpec Técnica e TLC Spec-Driven.
+
+O agente deve seguir os documentos e templates do diretório `/workflow` antes de gerar documentação ou implementar código.
+
+## Estrutura de documentação
+
+- `docs/product/Brief_Inicial.md`: brief curto criado na etapa inicial.
+- `docs/product/PRD_Principal.md`: fonte de verdade de produto.
+- `docs/technical/PreSpec_Tecnica.md`: ponte entre produto e engenharia.
+- `docs/technical/Domain_Model.md`: entidades, regras, status e invariantes.
+- `docs/technical/Architecture.md`: módulos, camadas e decisões técnicas macro.
+- `docs/technical/API_Contracts.md`: contratos conceituais por caso de uso.
+- `docs/technical/Test_Strategy.md`: estratégia de testes e cenários prioritários.
+- `docs/decisions/`: ADRs.
+- `.specs/project/`: contexto persistente do projeto.
+- `.specs/features/`: specs executáveis por fatia vertical.
+
+## Regras de entrevista
+
+- Brief inicial: até 3 perguntas, uma por vez, com resposta recomendada.
+- PRD Principal: até 30 blocos, com 3 a 5 perguntas por bloco.
+- Compressão do PRD: até 5 perguntas.
+- PreSpec Técnica: até 10 perguntas.
+- Derivação dos docs técnicos: 0 perguntas por padrão.
+- Specs TLC por fatia: até 5 perguntas, se necessário.
+
+## Comandos do workflow
+
+- `/iniciar-projeto-sdd`: criar estrutura e, se houver nome/ideia, gerar rascunho do Brief Inicial.
+- `/continuar-sdd`: continuar a partir do estado registrado em `.specs/project/STATE.md`.
+- Quando houver mais de um próximo caminho, mostrar opções numeradas e aguardar escolha do usuário.
+
+Antes de continuar, ler `.specs/project/STATE.md` e `docs/product/Brief_Inicial.md` quando existir.
+
+Se houver uma próxima etapa inequívoca no `STATE.md`, continuar automaticamente. Se houver mais de um caminho válido, mostrar opções numeradas e aguardar escolha.
+
+Após concluir o Grill-me de produto ou atingir o limite de blocos, gerar automaticamente `docs/product/PRD_Principal.md`.
+
+Após gerar o PRD, parar e mostrar opções numeradas antes de iniciar a compressão/revisão.
+
+Após concluir a compressão/revisão do PRD, parar e mostrar opções numeradas antes de iniciar a PreSpec Técnica.
+
+## Regras do Brief Inicial
+
+O Brief Inicial deve seguir exatamente o template de `workflow/01-brief-template.md`.
+
+- Não adicionar seções.
+- Não criar `docs/product/Brief_Inicial.md` vazio durante o setup.
+- O usuário não deve preencher o template manualmente; o Brief Inicial nasce de um Grill-me curto.
+- Se o comando inicial trouxer nome e ideia, usar esses dados como contexto inicial da entrevista do brief.
+- Se faltar nome ou ideia, criar a estrutura e iniciar o Grill-me do Brief Inicial.
+- Criar `.specs/project/STATE.md` desde o setup e atualizar a etapa atual, próxima decisão e log curto após gerar o brief.
+- Não criar `.specs/project/PROJECT.md` nem `.specs/project/ROADMAP.md` no setup; criar apenas na derivação técnica, depois da PreSpec.
+- Não perguntar sobre stack, banco, framework, arquitetura, implementação, deploy ou código.
+- Não fazer perguntas fora do escopo das 8 seções do template.
+- Gerar o Brief Inicial com base nas respostas do Grill-me do brief, usando premissas e dúvidas.
+- Manter o Brief Inicial conservador, sem preencher lacunas relevantes por inferência forte.
+- Fazer no máximo 3 perguntas de brief.
+- Apresentar opções numeradas após criar ou atualizar o Brief Inicial.
+- Se algo puder ser assumido sem grande risco, registrar como premissa na seção mais adequada.
+- Se algo não for essencial agora, registrar em `8. Dúvidas iniciais`.
+- Após criar ou atualizar o Brief Inicial, parar e mostrar opções numeradas antes de iniciar o Grill-me de produto.
+
+## Regras do PRD Principal
+
+O PRD Principal deve ser enxuto, autoexplicativo e orientado a produto.
+
+Não deve conter:
+
+- código;
+- schema de banco;
+- endpoints detalhados;
+- escolha de framework;
+- detalhes de deploy;
+- implementação prematura.
+
+## Regras da PreSpec Técnica
+
+A PreSpec Técnica deve traduzir produto em direção técnica conceitual.
+
+Ela pode conter entidades conceituais, permissões, regras de domínio, validações, contratos conceituais, riscos técnicos, estratégia inicial de testes e backlog por fatias verticais.
+
+Ela não deve escolher stack específica sem decisão explícita.
+
+## Regras de derivação técnica
+
+Ao derivar docs técnicos, o agente deve gerar os documentos sem nova entrevista, salvo inconsistência crítica.
+
+## Regras de implementação
+
+- Implementar uma fatia vertical por vez.
+- Não alterar escopo sem atualizar documentação.
+- Não criar dependências novas sem justificativa.
+- Criar ou atualizar testes relevantes.
+- Atualizar `.specs/project/STATE.md` ao final de cada etapa.
+- Registrar decisões importantes como ADR.
+
+## Definition of Done
+
+Uma etapa só está concluída quando:
+
+- o artefato esperado foi criado ou atualizado;
+- o documento segue o template correspondente;
+- decisões em aberto foram registradas;
+- inconsistências foram apontadas;
+- o próximo passo está claro.

package/README.md

@@ -0,0 +1,45 @@
+# create-sdd-workflow
+
+Scaffold an SDD documentation workflow with Brief Inicial, PRD, PreSpec, technical docs, and vertical-slice specs.
+
+## Usage
+
+```sh
+npx create-sdd-workflow
+```
+
+```sh
+npx create-sdd-workflow ./my-project
+```
+
+```sh
+npx create-sdd-workflow ./my-project --name "StudyFlow" --idea "An app for study reviews"
+```
+
+The command creates the workflow structure and prepares `.specs/project/STATE.md`.
+
+It does not create an empty `docs/product/Brief_Inicial.md`. The Brief Inicial is generated by a short Grill-me interview with up to 3 questions.
+
+## What It Creates
+
+```txt
+workflow/
+docs/
+  product/
+  technical/
+  decisions/
+.specs/
+  project/STATE.md
+  features/
+AGENTS.md
+```
+
+## Flow
+
+1. Run `npx create-sdd-workflow`.
+2. Use the generated `STATE.md` to start the Brief Inicial Grill-me.
+3. Generate `docs/product/Brief_Inicial.md`.
+4. Choose from numbered options to enrich the brief, continue to product discovery, or pause.
+5. Generate the PRD, review it, approve it, then generate PreSpec and technical docs.
+
+See `manual_workflow_sdd_grillme_tlc.md` for the full tutorial.

package/bin/create-sdd-workflow.js

@@ -0,0 +1,249 @@
+#!/usr/bin/env node
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+const rootDir = path.resolve(__dirname, "..");
+const defaultWorkflowDir = path.join(rootDir, "workflow");
+
+function printHelp() {
+  console.log(`Usage:
+  create-sdd-workflow [directory] [--force] [--name "Name"] [--idea "Initial idea"]
+
+Examples:
+  npx create-sdd-workflow
+  npx create-sdd-workflow ./my-project
+  npx create-sdd-workflow ./my-project --name "StudyFlow" --idea "An app for study reviews"
+
+Options:
+  --force       Overwrite existing generated files
+  --name        Register the project name in STATE.md
+  --idea        Register the initial idea in STATE.md
+  --help, -h    Show this help
+
+The command creates the workflow structure and prepares the project for the
+Brief Inicial Grill-me. It never creates an empty Brief_Inicial.md.`);
+}
+
+function parseArgs(argv) {
+  const result = {
+    targetDir: ".",
+    force: false,
+    name: "",
+    idea: ""
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+
+    if (arg === "--help" || arg === "-h") {
+      result.help = true;
+      continue;
+    }
+
+    if (arg === "--force") {
+      result.force = true;
+      continue;
+    }
+
+    if (arg === "--name") {
+      result.name = readValue(argv, index, "--name");
+      index += 1;
+      continue;
+    }
+
+    if (arg === "--idea") {
+      result.idea = readValue(argv, index, "--idea");
+      index += 1;
+      continue;
+    }
+
+    if (arg.startsWith("--")) {
+      throw new Error(`Unknown option: ${arg}`);
+    }
+
+    if (result.targetDir === ".") {
+      result.targetDir = arg;
+      continue;
+    }
+
+    throw new Error(`Unexpected argument: ${arg}`);
+  }
+
+  return result;
+}
+
+function readValue(argv, index, optionName) {
+  const value = argv[index + 1];
+  if (!value || value.startsWith("--")) {
+    throw new Error(`Missing value for ${optionName}`);
+  }
+  return value;
+}
+
+function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+function writeFile(filePath, content, force) {
+  if (fs.existsSync(filePath) && !force) {
+    console.log(`preserved: ${filePath}`);
+    return;
+  }
+
+  ensureDir(path.dirname(filePath));
+  fs.writeFileSync(filePath, content);
+  console.log(`created: ${filePath}`);
+}
+
+function copyFile(source, destination, force) {
+  if (fs.existsSync(destination) && !force) {
+    console.log(`preserved: ${destination}`);
+    return;
+  }
+
+  ensureDir(path.dirname(destination));
+  fs.copyFileSync(source, destination);
+  console.log(`created: ${destination}`);
+}
+
+function copyWorkflow(workflowSource, targetDir, force) {
+  if (!fs.existsSync(path.join(workflowSource, "00-AGENTS-template.md"))) {
+    throw new Error(`Missing workflow templates at: ${workflowSource}`);
+  }
+
+  for (const entry of fs.readdirSync(workflowSource)) {
+    if (entry.endsWith(".md")) {
+      copyFile(
+        path.join(workflowSource, entry),
+        path.join(targetDir, "workflow", entry),
+        force
+      );
+    }
+  }
+
+  copyFile(
+    path.join(workflowSource, "00-AGENTS-template.md"),
+    path.join(targetDir, "AGENTS.md"),
+    force
+  );
+}
+
+function touch(filePath) {
+  ensureDir(path.dirname(filePath));
+  fs.closeSync(fs.openSync(filePath, "a"));
+}
+
+function todayIso() {
+  return new Date().toISOString().slice(0, 10);
+}
+
+function buildState({ name, idea }) {
+  const today = todayIso();
+
+  if (name && idea) {
+    return `# Estado do Projeto
+
+## Etapa atual
+
+Setup do workflow criado. Dados iniciais recebidos para o Grill-me do Brief.
+
+## Último artefato
+
+Nenhum artefato de produto criado ainda.
+
+## Próxima decisão
+
+Continuar o Grill-me do Brief Inicial para gerar \`docs/product/Brief_Inicial.md\`.
+
+## Dados iniciais
+
+- Nome: ${name}
+- Ideia: ${idea}
+
+## Log curto
+
+- ${today} — Setup do workflow criado.
+- ${today} — Dados iniciais registrados para o Grill-me do Brief.
+
+## Observações
+
+- O Brief Inicial não deve ser criado vazio.
+- O usuário não deve preencher o template manualmente.
+- O Brief Inicial deve ser gerado por um Grill-me curto, com até 3 perguntas.
+- Após gerar o Brief Inicial, o fluxo deve mostrar opções numeradas.
+`;
+  }
+
+  return `# Estado do Projeto
+
+## Etapa atual
+
+Setup do workflow criado.
+
+## Último artefato
+
+Nenhum artefato de produto criado ainda.
+
+## Próxima decisão
+
+Continuar o Grill-me do Brief Inicial para coletar nome, ideia e lacunas essenciais antes de gerar \`docs/product/Brief_Inicial.md\`.
+
+## Log curto
+
+- ${today} — Setup do workflow criado.
+
+## Observações
+
+- O Brief Inicial não deve ser criado vazio.
+- O usuário não deve preencher o template manualmente.
+- O Brief Inicial deve ser gerado por um Grill-me curto, com até 3 perguntas.
+- Após gerar o Brief Inicial, o fluxo deve mostrar opções numeradas.
+`;
+}
+
+function main() {
+  const options = parseArgs(process.argv.slice(2));
+
+  if (options.help) {
+    printHelp();
+    return;
+  }
+
+  const targetDir = path.resolve(process.cwd(), options.targetDir);
+  const workflowSource = process.env.SDD_WORKFLOW_TEMPLATE_DIR
+    ? path.resolve(process.env.SDD_WORKFLOW_TEMPLATE_DIR)
+    : defaultWorkflowDir;
+
+  ensureDir(path.join(targetDir, "workflow"));
+  ensureDir(path.join(targetDir, "docs", "product"));
+  ensureDir(path.join(targetDir, "docs", "technical"));
+  ensureDir(path.join(targetDir, "docs", "decisions"));
+  ensureDir(path.join(targetDir, ".specs", "project"));
+  ensureDir(path.join(targetDir, ".specs", "features"));
+
+  copyWorkflow(workflowSource, targetDir, options.force);
+
+  touch(path.join(targetDir, "docs", "product", ".gitkeep"));
+  touch(path.join(targetDir, "docs", "technical", ".gitkeep"));
+  touch(path.join(targetDir, "docs", "decisions", ".gitkeep"));
+  touch(path.join(targetDir, ".specs", "features", ".gitkeep"));
+
+  writeFile(
+    path.join(targetDir, ".specs", "project", "STATE.md"),
+    buildState(options),
+    options.force
+  );
+
+  console.log("observação: docs/product/Brief_Inicial.md será gerado pelo Grill-me do Brief");
+  console.log("próximo passo: conduza até 3 perguntas para gerar o Brief Inicial");
+  console.log(`setup SDD concluído em: ${targetDir}`);
+}
+
+try {
+  main();
+} catch (error) {
+  console.error(`error: ${error.message}`);
+  process.exit(1);
+}