create-sdd-workflow 0.1.0

package/skills/iniciar-projeto-sdd/assets/workflow/00-AGENTS-template.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/skills/iniciar-projeto-sdd/assets/workflow/01-brief-template.md

@@ -0,0 +1,17 @@
+# Brief Inicial — [Nome do Projeto]
+
+## 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

package/skills/iniciar-projeto-sdd/assets/workflow/02-grillme-brief-prompt.md

@@ -0,0 +1,27 @@
+# Grill-me do Brief
+
+Use grill-me para preencher ou enriquecer o brief inicial.
+
+## Objetivo
+
+Transformar minha ideia inicial em um Brief Inicial claro antes de iniciar o PRD, sem exigir preenchimento manual do template.
+
+## Regras
+
+- Faça no máximo 3 perguntas.
+- Faça uma pergunta por vez.
+- Para cada pergunta, forneça sua resposta recomendada.
+- Se ainda não existir `docs/product/Brief_Inicial.md`, use as respostas para gerar o brief.
+- Se o brief já existir, use as respostas para enriquecê-lo.
+- Mantenha o Brief Inicial conservador: não preencha lacunas relevantes por inferência forte.
+- Use premissas e dúvidas iniciais para lacunas que não bloqueiam o entendimento.
+- Pergunte apenas o que muda significativamente o entendimento do produto.
+- Não pergunte sobre stack, banco, framework, arquitetura, implementação, deploy ou código.
+- Não faça perguntas fora do escopo das 8 seções do template de `workflow/01-brief-template.md`.
+- Se algo puder ser assumido sem grande risco, registre como premissa.
+- Se algo não for essencial agora, registre como dúvida inicial.
+- Ao final, gere `docs/product/Brief_Inicial.md` seguindo exatamente o template do workflow.
+- Pare após gerar ou atualizar o brief e apresente opções numeradas:
+  1. Enriquecer mais o Brief Inicial.
+  2. Continuar para o Grill-me de produto.
+  3. Pausar para revisão manual.

package/skills/iniciar-projeto-sdd/assets/workflow/03-grillme-product-prompt.md

@@ -0,0 +1,37 @@
+# Grill-me de Produto
+
+Use grill-me para gerar um PRD Principal enxuto e autoexplicativo.
+
+## Contexto
+
+Já existe um brief inicial. Use esse brief como fonte base.
+
+## Objetivo
+
+Coletar informações de produto suficientes para gerar um PRD Principal, sem entrar em implementação técnica.
+
+## Blocos sugeridos
+
+1. Problema e contexto.
+2. Público-alvo e personas.
+3. Proposta de valor.
+4. Escopo do MVP.
+5. Funcionalidades principais.
+6. Regras de negócio.
+7. Fluxos principais.
+8. Métricas, riscos e decisões em aberto.
+
+## Regras da entrevista
+
+- Faça no máximo 30 blocos.
+- Cada bloco deve ter entre 3 e 5 perguntas.
+- 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.
+- Não faça perguntas repetidas.
+- Não pergunte sobre stack, banco, framework, endpoints, schema, ORM, deploy ou arquitetura.
+- Se uma resposta permitir uma suposição razoável, registre como premissa.
+- Se algo não for essencial para o MVP, registre como fora de escopo ou decisão em aberto.
+- Antes de ultrapassar 30 blocos, pare e liste lacunas restantes.
+- Não gere o PRD antes de concluir a entrevista ou atingir o limite de blocos.
+- Ao concluir a entrevista ou atingir o limite de blocos, gere automaticamente `docs/product/PRD_Principal.md` usando `workflow/04-prd-template.md`.
+- Após gerar o PRD, pare e peça confirmação antes de iniciar `workflow/05-prd-compression-prompt.md`.

package/skills/iniciar-projeto-sdd/assets/workflow/04-prd-template.md

@@ -0,0 +1,37 @@
+# PRD Principal — [Nome do Produto]
+
+## 1. Resumo
+
+## 2. Problema
+
+## 3. Público-alvo
+
+## 4. Proposta de valor
+
+## 5. Objetivos do MVP
+
+## 6. Escopo do MVP
+
+### 6.1 Incluído
+
+### 6.2 Fora de escopo
+
+## 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

package/skills/iniciar-projeto-sdd/assets/workflow/05-prd-compression-prompt.md

@@ -0,0 +1,33 @@
+# Compressão e Revisão do PRD
+
+Revise e compacte o PRD Principal.
+
+## Objetivo
+
+Transformar o documento em uma versão enxuta, autoexplicativa e pronta para servir como fonte de verdade de produto.
+
+## Pré-condição
+
+Só iniciar esta etapa após confirmação explícita do usuário, depois que `docs/product/PRD_Principal.md` já existir.
+
+## Regras
+
+- Antes de reescrever, faça até 5 perguntas apenas se forem necessárias para resolver lacunas importantes.
+- Remova redundâncias.
+- Una seções repetidas.
+- Preserve decisões importantes.
+- Preserve regras de negócio verificáveis.
+- Preserve critérios de aceite.
+- Preserve escopo e fora de escopo.
+- Remova detalhes técnicos de implementação.
+- Não inclua stack.
+- Não inclua código.
+- Não inclua endpoints.
+- Não inclua schema de banco.
+- Use linguagem objetiva.
+- Mantenha a estrutura padrão do PRD.
+- Ao final, liste possíveis lacunas restantes sem iniciar nova entrevista.
+- Ao final, atualize `.specs/project/STATE.md`, pare o fluxo e apresente opções numeradas antes de iniciar `workflow/06-prespec-prompt.md`:
+  1. Aprovar PRD revisado e gerar PreSpec Técnica.
+  2. Fazer ajustes no PRD.
+  3. Pausar.

package/skills/iniciar-projeto-sdd/assets/workflow/06-prespec-prompt.md

@@ -0,0 +1,52 @@
+# PreSpec Técnica
+
+A partir do PRD Principal aprovado, gere uma PreSpec Técnica.
+
+## Objetivo
+
+Criar uma ponte entre produto e engenharia, preparando o projeto para documentação técnica e specs por fatia vertical.
+
+## Pré-condição
+
+Só iniciar esta etapa após aprovação explícita do PRD revisado/comprimido.
+
+## Antes de gerar
+
+Faça até 10 perguntas técnicas conceituais se forem necessárias.
+
+Pode perguntar sobre:
+
+- entidades do domínio;
+- permissões;
+- dados essenciais;
+- regras de validação;
+- integrações obrigatórias;
+- restrições operacionais;
+- requisitos não funcionais críticos;
+- riscos técnicos;
+- estratégia inicial de testes.
+
+Não deve perguntar sobre:
+
+- framework específico;
+- ORM específico;
+- biblioteca específica;
+- provedor de deploy;
+- implementação detalhada;
+- código.
+
+## Estrutura da PreSpec
+
+1. Finalidade
+2. Fontes
+3. Fronteira técnica do MVP
+4. Princípios técnicos
+5. Modelo conceitual inicial
+6. Regras de domínio críticas
+7. Permissões e escopo de dados
+8. Contratos conceituais por caso de uso
+9. Validações principais
+10. Riscos técnicos
+11. Estratégia inicial de testes
+12. Backlog por fatias verticais
+13. Decisões que devem virar ADR

package/skills/iniciar-projeto-sdd/assets/workflow/07-derive-docs-prompt.md

@@ -0,0 +1,32 @@
+# Derivação dos Documentos Técnicos
+
+A partir do PRD Principal aprovado e da PreSpec Técnica, derive os documentos técnicos especializados.
+
+## Regra principal
+
+Não faça novas perguntas, salvo inconsistência crítica que impeça a geração.
+
+## Gere
+
+1. `docs/technical/Domain_Model.md`
+2. `docs/technical/Architecture.md`
+3. `docs/technical/API_Contracts.md`
+4. `docs/technical/Test_Strategy.md`
+5. ADRs iniciais em `docs/decisions/`
+6. `.specs/project/PROJECT.md`
+7. `.specs/project/ROADMAP.md`
+8. `.specs/project/STATE.md`
+9. `.specs/features/[feature]/spec.md`
+10. `.specs/features/[feature]/design.md`
+11. `.specs/features/[feature]/tasks.md`
+
+## Regras
+
+- Não duplicar texto desnecessário.
+- Cada documento deve ter responsabilidade clara.
+- `Domain_Model.md` deve conter entidades, regras, status, permissões e invariantes.
+- `Architecture.md` deve conter módulos, camadas, fronteiras e decisões arquiteturais.
+- `API_Contracts.md` deve conter contratos conceituais, entradas, saídas, erros e regras.
+- `Test_Strategy.md` deve conter riscos, tipos de teste e cenários prioritários.
+- ADRs devem registrar decisões importantes com contexto e consequências.
+- Specs por fatia devem ter `spec.md`, `design.md` e `tasks.md`.

package/skills/iniciar-projeto-sdd/assets/workflow/08-tlc-execution-prompt.md

@@ -0,0 +1,32 @@
+# TLC por Fatia Vertical
+
+Use tlc-spec-driven para trabalhar na próxima fatia vertical.
+
+## Leia antes
+
+- `AGENTS.md`
+- `docs/product/PRD_Principal.md`
+- `docs/technical/PreSpec_Tecnica.md`
+- `docs/technical/Domain_Model.md`
+- `docs/technical/Architecture.md`
+- `docs/technical/API_Contracts.md`
+- `docs/technical/Test_Strategy.md`
+- `.specs/project/PROJECT.md`
+- `.specs/project/ROADMAP.md`
+- `.specs/project/STATE.md`
+- `.specs/features/[feature]/spec.md`
+- `.specs/features/[feature]/design.md`
+- `.specs/features/[feature]/tasks.md`
+
+## Objetivo
+
+Validar e executar a fatia vertical selecionada.
+
+## Regras
+
+- Faça no máximo 5 perguntas se houver lacunas relevantes na fatia.
+- Não altere escopo global sem registrar decisão.
+- Não implemente fora da fatia selecionada.
+- Atualize `STATE.md` ao final.
+- Marque tasks concluídas.
+- Registre decisões novas como ADR quando necessário.

package/skills/iniciar-projeto-sdd/assets/workflow/09-quality-checklists.md

@@ -0,0 +1,35 @@
+# Checklists de Qualidade
+
+## PRD
+
+- [ ] O problema está claro?
+- [ ] O público-alvo está claro?
+- [ ] A proposta de valor está clara?
+- [ ] O MVP está bem delimitado?
+- [ ] Existe seção de fora de escopo?
+- [ ] As funcionalidades estão descritas sem implementação técnica?
+- [ ] As regras de negócio são verificáveis?
+- [ ] Existem fluxos principais?
+- [ ] Existem requisitos funcionais?
+- [ ] Existem requisitos não funcionais?
+- [ ] Existem critérios de aceite?
+- [ ] Existem métricas de sucesso?
+- [ ] Existem riscos e mitigações?
+- [ ] Existem decisões tomadas?
+- [ ] Existem decisões em aberto?
+- [ ] O documento evita código, stack, endpoints e schema?
+- [ ] O documento pode ser lido em aproximadamente 15 minutos?
+
+## PreSpec
+
+- [ ] A fronteira técnica do MVP está clara?
+- [ ] O documento continua agnóstico de tecnologia quando apropriado?
+- [ ] As entidades principais estão identificadas?
+- [ ] As regras críticas de domínio estão claras?
+- [ ] As permissões estão descritas?
+- [ ] Os contratos conceituais estão descritos?
+- [ ] As validações principais estão listadas?
+- [ ] Os riscos técnicos foram registrados?
+- [ ] Existe estratégia inicial de testes?
+- [ ] Existe backlog por fatias verticais?
+- [ ] Decisões importantes foram marcadas para ADR?

package/skills/iniciar-projeto-sdd/references/workflow-summary.md

@@ -0,0 +1,69 @@
+# Workflow SDD — Resumo Operacional
+
+## Etapas
+
+0. Setup do projeto: criar estrutura, `AGENTS.md`, templates e `.specs/project/STATE.md`, sem criar `Brief_Inicial.md` vazio.
+1. Grill-me do Brief Inicial: até 3 perguntas, uma por vez, com resposta recomendada.
+2. Brief Inicial: gerar o documento no template curto e parar com opções numeradas.
+3. Grill-me de produto: até 30 blocos, com 3 a 5 perguntas por bloco.
+4. PRD Principal: gerar sem novas perguntas.
+5. Compressão do PRD: até 5 perguntas, se necessário.
+6. PreSpec Técnica: até 10 perguntas conceituais.
+7. Derivação técnica: 0 perguntas por padrão.
+8. TLC por fatia vertical: até 5 perguntas por fatia.
+
+## Separação de camadas
+
+- Brief e PRD são documentos de produto.
+- PreSpec é ponte técnica conceitual.
+- Docs técnicos derivados detalham domínio, arquitetura, contratos e testes.
+- TLC executa uma fatia vertical por vez.
+
+## Regra de ouro
+
+Não iniciar implementação antes de existir pelo menos PRD, PreSpec, docs técnicos mínimos e spec da fatia vertical.
+
+## Checkpoint obrigatório
+
+O comando inicial do workflow cria a estrutura e inicia o Grill-me do Brief Inicial. Depois de gerar o Brief Inicial, o agente deve mostrar opções numeradas antes de iniciar o Grill-me de produto.
+
+## Estado persistente
+
+Crie `.specs/project/STATE.md` desde o setup. Atualize o arquivo quando o Brief Inicial for criado, quando o usuário escolher enriquecer o brief, e quando avançar para Grill-me de produto.
+
+Mantenha um log curto em ordem cronológica com data e etapa concluída.
+
+Não crie `.specs/project/PROJECT.md` nem `.specs/project/ROADMAP.md` no setup. Eles só devem ser gerados durante a derivação técnica, depois da PreSpec.
+
+## Entrada do comando
+
+- Com `Nome` e `Ideia`: criar estrutura e registrar os dados no `STATE.md` para o Grill-me do Brief.
+- Sem `Nome` ou sem `Ideia`: criar estrutura e iniciar o Grill-me do Brief para coletar o essencial.
+
+## Continuação
+
+Aceite `/continuar-sdd` como retomada do fluxo.
+
+Antes de continuar, leia `STATE.md` e o Brief Inicial. Se o brief não existir, continue o Grill-me do Brief.
+
+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.
+
+No Grill-me de produto, use até 30 blocos, com 3 a 5 perguntas por bloco. O limite se aplica aos blocos, não ao número total de perguntas.
+
+Quando o Grill-me de produto terminar ou atingir o limite de blocos, gere automaticamente `docs/product/PRD_Principal.md` usando o template padrão.
+
+Depois de gerar o PRD, pare e mostre opções numeradas antes de iniciar a compressão/revisão.
+
+Depois da compressão/revisão do PRD, pare novamente e mostre opções numeradas antes de iniciar a PreSpec Técnica.
+
+## Estilo do brief
+
+O Brief Inicial deve ser gerado por Grill-me curto, não preenchido manualmente pelo usuário. Use premissas apenas quando forem seguras e marque lacunas relevantes como dúvidas iniciais.
+
+Após gerar o Brief Inicial, mostre opções numeradas para enriquecer o brief, continuar para produto ou pausar.
+
+## Distribuição
+
+A skill deve continuar autocontida para empacotamento futuro via npm/npx. O pacote deve levar `SKILL.md`, `scripts/init_sdd_project.sh`, `assets/workflow/` e este resumo.
+
+Instalação global em `~/.agents/skills` não é etapa obrigatória do workflow; trate como conveniência local opcional.

package/skills/iniciar-projeto-sdd/scripts/init_sdd_project.sh

@@ -0,0 +1,182 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+target_dir="."
+force=""
+project_name=""
+project_idea=""
+today="$(date +%F)"
+
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+skill_dir="$(cd "$script_dir/.." && pwd)"
+repo_root="$(cd "$script_dir/../../.." && pwd)"
+
+template_source="${SDD_WORKFLOW_TEMPLATE_DIR:-}"
+if [[ -z "$template_source" ]]; then
+  if [[ -d "$skill_dir/assets/workflow" ]]; then
+    template_source="$skill_dir/assets/workflow"
+  elif [[ -d "$repo_root/workflow" ]]; then
+    template_source="$repo_root/workflow"
+  else
+    printf 'erro: não encontrei templates do workflow.\n' >&2
+    printf 'defina SDD_WORKFLOW_TEMPLATE_DIR ou instale assets/workflow junto da skill.\n' >&2
+    exit 1
+  fi
+fi
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --force)
+      force="--force"
+      shift
+      ;;
+    --name)
+      project_name="${2:-}"
+      shift 2
+      ;;
+    --idea)
+      project_idea="${2:-}"
+      shift 2
+      ;;
+    --help|-h)
+      cat <<'EOF'
+Uso:
+  init_sdd_project.sh [diretório] [--force] [--name "Nome"] [--idea "Ideia inicial"]
+
+Cria a estrutura, templates e STATE.md.
+Com --name e --idea, registra esses dados no STATE.md para iniciar o Grill-me do Brief.
+
+Por padrão, copia templates de assets/workflow da skill ou de workflow/ no repositório.
+Use SDD_WORKFLOW_TEMPLATE_DIR=/caminho/workflow para sobrescrever a origem.
+EOF
+      exit 0
+      ;;
+    *)
+      if [[ "$target_dir" == "." ]]; then
+        target_dir="$1"
+      else
+        printf 'argumento desconhecido: %s\n' "$1" >&2
+        exit 2
+      fi
+      shift
+      ;;
+  esac
+done
+
+mkdir -p \
+  "$target_dir/workflow" \
+  "$target_dir/docs/product" \
+  "$target_dir/docs/technical" \
+  "$target_dir/docs/decisions" \
+  "$target_dir/.specs/project" \
+  "$target_dir/.specs/features"
+
+write_file() {
+  local path="$1"
+  if [[ -e "$path" && "$force" != "--force" ]]; then
+    printf 'preservado: %s\n' "$path"
+    return
+  fi
+  mkdir -p "$(dirname "$path")"
+  cat > "$path"
+  printf 'criado: %s\n' "$path"
+}
+
+copy_template() {
+  local source="$1"
+  local destination="$2"
+
+  if [[ -e "$destination" && "$force" != "--force" ]]; then
+    printf 'preservado: %s\n' "$destination"
+    return
+  fi
+
+  mkdir -p "$(dirname "$destination")"
+  cp "$source" "$destination"
+  printf 'criado: %s\n' "$destination"
+}
+
+if [[ ! -f "$template_source/00-AGENTS-template.md" ]]; then
+  printf 'erro: template ausente: %s/00-AGENTS-template.md\n' "$template_source" >&2
+  exit 1
+fi
+
+for template in "$template_source"/*.md; do
+  copy_template "$template" "$target_dir/workflow/$(basename "$template")"
+done
+
+copy_template "$template_source/00-AGENTS-template.md" "$target_dir/AGENTS.md"
+
+touch \
+  "$target_dir/docs/product/.gitkeep" \
+  "$target_dir/docs/technical/.gitkeep" \
+  "$target_dir/docs/decisions/.gitkeep" \
+  "$target_dir/.specs/features/.gitkeep"
+
+if [[ -n "$project_name" && -n "$project_idea" ]]; then
+  write_file "$target_dir/.specs/project/STATE.md" <<EOF
+# 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: $project_name
+- Ideia: $project_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.
+EOF
+  printf 'observação: docs/product/Brief_Inicial.md será gerado pelo Grill-me do Brief\n'
+  printf 'próximo passo: conduza até 3 perguntas para gerar o Brief Inicial\n'
+else
+  write_file "$target_dir/.specs/project/STATE.md" <<EOF
+# 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.
+EOF
+  printf 'observação: docs/product/Brief_Inicial.md não é criado vazio no setup\n'
+  printf 'próximo passo: conduza até 3 perguntas para gerar o Brief Inicial\n'
+fi
+
+printf 'setup SDD concluído em: %s\n' "$target_dir"