PLAYBOOK — Do zero ao primeiro cliente pagante

Guia único e de ponta a ponta para usar este boilerplate e lançar um micro-SaaS com Big Design Upfront (BDFU): ideia + benchmark → documentação de negócio (docs/) → specs técnicas por módulo (specs/, Spec Kit) → desenvolvimento → cloud → lançar → vender → medir (GTM + Hotjar) e iterar.

Como usar: leia uma vez inteiro. Depois avance fase por fase em cascata — só passe para a próxima quando o gate da fase atual estiver ok. Sem calendário, sem estimativa de semanas: termina uma etapa, começa a seguinte. Cada fase tem entrada, o que fazer, saída e gate. Não comece a codar produto antes de concluir as Fases 1–3 (ideia, docs, specs).

• Idioma: processo/negócio em pt-BR; código, UI, APIs e identificadores técnicos em inglês (ver .specify/memory/constitution.md).
• Onde mora cada coisa: ver Mapa de arquivos no fim.
• Serviços e credenciais: checklist único — contas, API keys e envs em uma lista só.
• Regra de ouro: pensar e documentar o produto inteiro antes de implementar; na Fase 4, agentes em paralelo só onde specs não dependem uma da outra.
• Modo cascata: F0 → gate → F1 → gate → … → F8. Não pule fase; não planeje duração — execute até o gate passar.
• Go-horse no dia a dia: prompts de correção, polish e hotfix vão direto — sem spec (ver Spec vs go-horse).
• Dia a dia no Cursor: pipeline de chats — CURSOR.md (spec → implement → revisão → browser → você testa).

---

Por que BDFU neste boilerplate?

Big Design Upfront = definir ideia, benchmark, documentação de negócio, specs técnicas e backlog completo antes de escrever código de produto.

Expand table full width

Quando BDFU é má ideia: produto altamente incerto sem boilerplate, equipe grande com stakeholders conflitantes, ou mercado que muda semanalmente. Quando BDFU é boa ideia (seu caso): boilerplate reutilizável, agentes para executar specs em paralelo, e você prefere clareza total antes de build.

---

Visão geral do fluxo

flowchart TD
    F0[Fase 0 — Bootstrap<br/>fork + rebrand] --> F1[Fase 1 — Ideia + benchmark<br/>hipótese + concorrência]
    F1 --> F2[Fase 2 — Docs completos<br/>todas as áreas do negócio]
    F2 --> F3[Fase 3 — Specs técnicas<br/>Spec Kit specs/001…NNN]
    F3 --> F4[Fase 4 — Desenvolver tudo<br/>implement por spec]
    F4 --> F5[Fase 5 — Cloud<br/>local → produção]
    F5 --> F6[Fase 6 — Lançar<br/>GTM + Hotjar + campanha]
    F6 --> F7[Fase 7 — Vender]
    F7 --> F8[Fase 8 — Medir e iterar]
    F8 -->|ajuste ou v2| F3

Expand table full width

Meta: produto completo (conforme specs) no ar com instrumentação — avance fase a fase até o gate passar; sem meta de calendário.

---

Serviços e credenciais — checklist único

Use esta lista de uma vez ao preparar o fork: contas a criar, chaves a gerar e onde colar no projeto. Detalhe de deploy: cloud/BOOTSTRAP.md. Templates de env: .env.example (raiz), apps/*/.env.example, cloud/dokploy/environments/*.production.env.example.

Regra: nunca commite secrets. Preencha .env local (gitignored) e variáveis no Dokploy (produção). Senhas completas só no gerenciador de senhas — não no chat.

Obrigatório para produção

Expand table full width

Obrigatório para subir local (dev)

Expand table full width

Opcional — lançamento (Fase 6)

Expand table full width

Ordem sugerida (greenfield)

1. Fase 0: fork + rebrand (packages/brand) + pnpm rebrand:sync + raiz .env com GEMINI_API_KEY e FALAI_API_KEY.
2. Antes da Fase 5: contas DO + domínio + Stripe (test) + Google OAuth + Resend.
3. Fase 5: cloud/BOOTSTRAP.md — DO infra → Dokploy → GitHub → deploy → DNS → preencher envs de produção da tabela acima.
4. Fase 6: GTM (website) + GA4/Hotjar (app) — setup em development/06-tracking-attribution.md.

Checklist rápido (marque ao configurar):

[ ] Digital Ocean — token, droplet, IP reservado, volumes, firewall
[ ] Digital Ocean Spaces — bucket + access key/secret
[ ] Domínio — DNS apontando para IP reservado
[ ] GitHub — repo + OAuth no Dokploy
[ ] Dokploy — painel + envs por app
[ ] Google OAuth — client ID + secret + redirect URLs (local + prod)
[ ] Stripe — keys test/live, prices, webhook secret
[ ] Resend — API key, domínio verificado, SMTP_* no service
[ ] Gemini + Fal.ai — API keys na raiz (.env) para `pnpm blog:create`
[ ] Secrets — JWT, Hasura admin, Postgres (prod)
[ ] (Fase 6) GTM website + GA4/Hotjar app + Ads (se campanha)

---

Princípios

1. Cascata por gate. Só avance de fase quando o gate passar — sem paralelizar fases.
2. Design completo antes de código de produto. Ideia → benchmark → docs → specs → implement (F0 rebrand via packages/brand antes dos docs).
3. Uma spec por capacidade. Todo módulo em docs/product/04 vira specs/NNN-nome/.
4. Spec Before Code (módulos, não prompts). Capacidade nova ou contrato novo → spec. Correções e ajustes pequenos → go-horse (sem spec). Ver Spec vs go-horse.
5. Dados pós-launch. GTM + Hotjar guiam iteração — não entrevistas em massa antes de shippar.
6. Feedback qualitativo pontual. Alguns clientes ativos depois do launch, quando os dados apontarem fricção.
7. Agentes na Fase 4. Paralelo entre specs independentes; specs com dependência rodam em sequência.
8. Escopo congelado na Fase 3. Mudanças de escopo entram como nova spec ou revisão explícita do índice — não "no meio do código".

---

Spec vs go-horse (decisão do projeto)

Decisão: BDFU vale para módulos e portfólio v1 (Fases 1–4). No dia a dia, a maioria dos prompts é go-horse — implementa direto, sem abrir spec, sem /speckit.*.

Expand table full width

Faixa 1 — Go-horse (padrão operacional)

Use para a maioria dos prompts no Cursor:

• Bug que restaura comportamento já esperado (ou óbvio)
• Copy, CSS, layout, loading, acessibilidade pontual
• Lint, refactor sem mudar contrato
• Ajuste de env local, typo, log
• Hotfix em produção

Documentação: automático via hook commit-msg para feat:/fix:/perf: → linha em docs/development/08-changelog.md (Unreleased). [skip-changelog] para pular. chore:/docs:/refactor: → nada.

Faixa 2 — Amend na spec existente

Mudança pequena dentro de um módulo que já tem spec (shipped ou em progresso):

• Adicionar task em tasks.md e marcar [x], ou
• Nota em implementation-status.md

Sem spec:new, sem /speckit.analyze de novo.

Faixa 3 — Feature nova (módulo)

Quando inventa capacidade nova → use o modelo do dia a dia em CURSOR.md: um prompt com a descrição da funcionalidade; a IA cria spec.md + plan.md + tasks.md de uma vez.

---

Desenvolvimento de features no Cursor

Prompts práticos, pipeline de chats e exemplos: CURSOR.md — Prompt 1 (spec) → Prompt 2 (implement) → Prompt 3 (revisão) → Prompt 4 (browser) → Prompt 5 (aceite).

O PLAYBOOK cobre gates de fase (F0→F8) e decisão go-horse vs spec; o como operar no Cursor fica no CURSOR.md.

---

Fase 0 — Bootstrap (fork + rebrand)

Entrada: este boilerplate clonado. Saída: repo com identidade da marca, env examples alinhados e apps rodando.

A estrutura é o template; o conteúdo de negócio será substituído nas Fases 1–2. A engenharia (apps/*, cloud/, .specify/) é reaproveitada.

Rebrand: editar packages/brand/ + pnpm rebrand:sync. Logos, cores e metadata HTML vêm do pacote no dev/build — sem spec formal. Checklist de referência: specs/001-setup-initial/checklists/requirements.md.

0.1 — Verificar que o template sobe

pnpm install
pnpm cloud:up
pnpm dev                 # todos → :3001, :3002, :3000, :3003
pnpm dev:app             # só app
pnpm dev:service         # só API
pnpm dev:website         # só site
pnpm dev:backoffice      # só admin

0.2 — Brand package (humano)

Edite packages/brand/ — guia em packages/brand/README.md:

1. packages/brand/src/config.ts — nome, slug, domínios, cores, tipografia, env.local
2. packages/brand/assets/logos/ — logo.svg, logo-light.svg, logo-dark.svg
3. packages/brand/assets/icons/ — favicon, og-image, etc.
4. (opcional) packages/brand/src/theme.css — tokens CSS

Apps consomem @framework/brand automaticamente; não copie assets manualmente para cada app.

0.3 — Propagar env e cloud

pnpm rebrand:sync

Atualiza brand-data.json, apps/*/.env.example e cloud/dokploy/* a partir de config.ts. Depois copie .env.example → .env (ou .env.local) em cada app e preencha secrets.

Opcional: rename @framework/* → @sua-marca/* se npm.scope estiver em brandConfig.npm.scope (manual ou prompt no Cursor).

i18n: strings de produto em src/locales/ — traduza no Cursor; não usa Gemini.

0.4 — Validar

pnpm cloud:up && pnpm dev

• App (:3001) e website (:3000) exibem logo e nome da marca
• Nenhum secret de produção commitado (só placeholders em .env.example)

Gate Fase 0: pnpm rebrand:sync rodado; 4 apps sobem local sem erro; identidade visual alinhada a packages/brand.

Specs de plataforma 002+ (auth, billing…) já vêm shipped no boilerplate — implemente specs de produto na Fase 4.

---

Fase 1 — Ideia + benchmark

Entrada: conceito do micro-SaaS. Saída: hipótese clara + benchmark documentado.

1.1 — One-pager da ideia

Escreva em docs/strategy/01-vision-mission-values.md (rascunho inicial) ou num bloco no topo de docs/product/01:

## Ideia (one-pager)

- **Problema:** …
- **Solução:** …
- **ICP:** …
- **Diferencial:** …
- **Modelo de receita:** …
- **Por que agora:** …

1.2 — Benchmark competitivo

Preencha docs/strategy/03-market-competition.md:

Expand table full width

Template de linha de benchmark:

| [Concorrente] | [Preço] | [Força principal] | [Fraqueza] | [O que copiamos / evitamos] |

1.3 — Decisão go / no-go (interna)

Expand table full width

Gate Fase 1: one-pager + benchmark com ≥5 referências + decisão go documentada.

---

Fase 2 — Documentação completa (docs/)

Entrada: ideia + benchmark. Saída: todas as áreas de negócio preenchidas — não só o mínimo.

Siga a ordem do docs/README.md:

Camada 1 — Estratégia (docs/strategy/)

Expand table full width

Camada 2 — Produto + GTM

Expand table full width

Camada 3 — Entrega + Operação

Expand table full width

Artefato-chave: inventário de módulos

docs/product/04-features-modules.md deve listar todo o produto v1:

• Cada linha = um módulo ou feature
• Coluna Spec: specs/NNN-nome (preencher na Fase 3)
• Status inicial: 🔴 planned ou 🟡 partial (se já existe no boilerplate)

docs/product/05-roadmap-prioritization.md lista todos os itens v1 (não só MVP) — a ordem de implementação vem na Fase 3 via dependências entre specs.

Gate Fase 2: inventário completo em product/04 (seu produto) e docs de negócio preenchidos para o fork — sem TBD crítico nos arquivos 01–05 de strategy, product, marketing, sales, development. (No repo template, placeholders TBD são normais; ver development/00-boilerplate-status.md.)

---

Fase 3 — Specs técnicas por módulo (Spec Kit)

Entrada: docs completos + inventário em product/04. Saída: uma pasta specs/NNN-nome/ por módulo, índice em specs/README.md.

Specs de plataforma (002–006): já shipped no boilerplate. Na Fase 3, specs novas são só módulos de produto (007+ no fork).

Como especificar (dia a dia no Cursor)

Por módulo: Chat 1 do pipeline CURSOR.md — descreva a funcionalidade; IA cria spec + plan + tasks de uma vez.

Repita até cobrir todo product/04. Revisão manual da spec antes de enfileirar implementação.

Comandos slash (/speckit.specify, clarify, analyze, implement) são opcionais — equivalentes aos prompts do CURSOR.md.

Referências: CURSOR.md · development/03-spec-implementation-flow.md

Como quebrar o produto

1. Copie cada linha de docs/product/04 → uma spec numerada.
2. Fork greenfield: rebrand na Fase 0 (packages/brand + pnpm rebrand:sync) antes das specs de produto.
3. Agrupe só o que não faz sentido separar (ex.: "login" + "registro" → uma spec auth).
4. Registre no índice specs/README.md (template incluído no repo).
5. Marque dependências entre specs (ex.: billing depende de auth).

Exemplo de índice (plataforma + produto):

Expand table full width

Quality gates (por spec e global)

Por spec:

• spec.md — user stories P1/P2/P3, FR-xxx, edge cases
• checklists/requirements.md — completo (gerado na especificação; equivalente a /speckit.specify)
• Checklists de domínio (/speckit.checklist) — security/ux conforme risco
• plan.md — paths reais do monorepo
• tasks.md — IDs, arquivos, [P] para paralelo
• /speckit.analyze — sem gaps críticos

Global (antes da Fase 4):

• specs/README.md — todas as specs v1 listadas com status
• Nenhuma dependência circular entre specs
• Toda linha de product/04 mapeada para uma spec
• Ordem de implementação definida (topological sort das dependências)

Gate Fase 3: todo product/04 mapeado; cada módulo com spec + plan + tasks (criados via CURSOR.md — Prompt 1).

---

Fase 4 — Desenvolver o produto inteiro

Entrada: specs fechadas. Saída: produto v1 implementado localmente, conforme documentação.

Go-horse durante a Fase 4: polish e bugfix dentro do escopo → direto, sem nova spec. Ver Spec vs go-horse.

Como implementar (dia a dia no Cursor)

Por spec: Chats 2–4 do pipeline CURSOR.md — implement → revisão código → browser QA → você aceita (Chat 5).

Pré-requisito: pnpm cloud:up && pnpm dev.

Ordem de execução (portfólio)

1. Fase 0 — rebrand (packages/brand + pnpm rebrand:sync).
2. Specs 002–006 (plataforma) já shipped; specs 007+ (produto) na ordem de dependência em specs/README.md.
3. Specs sem dependência entre si → paralelo (multi-agent).
4. Specs com dependência → linear (trunk primeiro).

pnpm spec:use -- 6
# Cursor: /speckit.implement
pnpm lint

Validar antes de marcar shipped

Checklist rápido por spec:

• Todos os FR-xxx da spec cobertos
• tasks.md — tasks relevantes marcadas [x]
• pnpm lint + pnpm build nos apps afetados
• Happy path testado manualmente (login, fluxo principal, erro esperado)
• Migrations/metadata Hasura aplicam sem conflito
• Help docs em apps/app/public/docs/ se feature visível ao cliente
• specs/README.md → status shipped
• docs/product/04 → 🟢 live
• docs/development/08-changelog.md se user-facing

Integração contínua local

pnpm cloud:up      # se precisar de DB/Hasura
pnpm dev           # app :3001 · service :3002 · website :3000 · backoffice :3003
pnpm lint
pnpm build

Gate Fase 4: 100% das specs v1 com status shipped; happy paths funcionando local.

---

Fase 5 — Cloud (local → produção)

Entrada: produto v1 local. Saída: produção saudável.

Antes de começar, percorra o checklist de serviços e credenciais — DO, Spaces, OAuth, Stripe, Resend e secrets.

Expand table full width

pnpm dokploy:pre-deploy
pnpm dokploy:post-deploy
pnpm dokploy:health

Checklist pré-público: health checks, backup Postgres, legal, billing Stripe, revisão de error_logs.

Gate Fase 5: produção responde; billing e legal publicados.

---

Fase 6 — Lançar (instrumentação — Opção B)

Entrada: produto completo em produção. Saída: campanha no ar + dados desde o dia 1.

Guia completo: development/06-tracking-attribution.md.

Expand table full width

Checklist: docs/marketing/05-campaigns-launches.md.

Gate Fase 6: GTM ativo no website; GA4 + Hotjar ativos no app; funil mensurável; UTMs chegando ao Postgres.

---

Fase 7 — Vender

PLG + sales-assisted conforme docs/sales/. Primeiros pagantes; objeções reais em docs/sales/03.

---

Fase 8 — Medir, iterar e feedback pontual

Entrada: produto no ar com dados. Saída: ajustes guiados por GTM/Hotjar.

Loop pós-launch

1. GA4/GTM — funil marketing (website) + produto (app)
2. Hotjar — website (landing/pricing via GTM) + app (UX logado)
3. error_logs — erros que afetam conversão (query em 07-security-observability)
4. Priorizar ajustes → go-horse (faixa 1) ou nova spec (faixa 3) se for capacidade nova

Feedback qualitativo: poucos clientes ativos quando os dados indicarem padrão.

Métricas: preencher docs/**/06-*.md com números reais.

---

Checklist mestre (BDFU)

[ ] F0  packages/brand editado (config + assets)
[ ] F0  pnpm rebrand:sync (env examples + cloud/dokploy)
[ ] F0  pnpm dev ok — logo/título nos apps
[ ] F1  One-pager da ideia escrito
[ ] F1  Benchmark ≥5 referências em strategy/03
[ ] F2  docs/strategy/ 01–06 preenchidos
[ ] F2  docs/product/ 01–07 preenchidos (04 = inventário completo)
[ ] F2  docs/marketing/ 01–06 preenchidos
[ ] F2  docs/sales/ 01–06 preenchidos
[ ] F2  docs/development/ 01–09 preenchidos
[ ] F2  docs/operations/ 01–05 preenchidos (legal rascunho mínimo)
[ ] F3  specs/README.md com índice de todas as specs v1
[ ] F3  Cada módulo de product/04 → specs/NNN-nome/
[ ] F3  Todas as specs: spec + plan + tasks + analyze verde
[ ] F4  Todas as specs implementadas (status shipped)
[ ] F4  lint + build verdes
[ ] F5  Produção saudável + legal + billing
[ ] F6  GTM + Hotjar + campanha launch
[ ] F7  Primeiros pagantes
[ ] F8  Loop GTM/Hotjar ativo

---

Mapa de arquivos

Expand table full width

---

Anti-padrões (BDFU mal feito)

• ❌ Codar portfólio v1 antes de fechar docs + specs (Fase 4 sem Fase 3).
• ❌ Abrir spec nova ou /speckit.* para todo prompt pequeno — use go-horse (faixa 1).
• ❌ Specs sem link com docs/product/04 (perde rastreabilidade negócio → código).
• ❌ Pular /speckit.analyze em qualquer spec v1 de módulo novo (faixa 3).
• ❌ Mudar escopo de módulo (faixa 3) no meio da Fase 4 sem atualizar spec + índice.
• ❌ Lançar sem GTM + Hotjar — perde o feedback loop pós-launch.
• ❌ Duplicar regra de negócio no frontend.
• ❌ Lançar ao público sem legal, billing e observabilidade.

---

Resumo: cascata F0→F8 — gate ok, próxima fase. BDFU para módulos; go-horse para prompts do dia a dia. Benchmark → documente → especifique → desenvolva → suba → lance → meça.