scaffold-mvp · diff
v1.0.0 to v1.1.0
107 added, 32 removed. Audit A to A.
---
name: scaffold-mvp
license: MIT
- description: Initialize a new project with an agile, high-productivity MVP stack. Focused on clean engineering boundaries, atomic configurations, and system stability without rush or architectural shortcuts. Use when starting a new project in an empty repository. Part of the afonsoft/skills collection.
+ description: Use when starting a new project in an empty repository. Initializes an agile, high-productivity MVP stack with clean engineering boundaries, atomic configurations, and system stability without architectural shortcuts. User-facing questions and recommendations must be in Portuguese (pt-BR). Part of the afonsoft/skills collection.
metadata:
- version: "1.0.0"
+ version: "1.1.0"
visibility: public
author: afonsoft
url: https://github.com/afonsoft/skills
---
# Scaffold MVP
- ## Gatilho
- Ativada **apenas** em repositórios novos, logo após a execução do `/grill-me-with-spec` (que estabelece a linguagem compartilhada, o domínio e a SPEC SDD).
+ ## Trigger
- ## Regra de Ouro (Inviolável)
- **É expressamente proibido construir componentes de UI base ou infraestrutura do zero.**
- O reuso de componentes compartilhados e de bibliotecas maduras focado em velocidade de prototipação é prioridade máxima e inegociável.
+ This skill is activated **only** in brand-new repositories, right after `/grill-me-with-spec` has established the shared language, domain, and SPEC SDD.
- ## Estabilidade e Cadência Técnica (Anti-Atropelo)
- A velocidade de um MVP não pode gerar códigos instáveis ou atropelos estruturais. A integridade sintática e arquitetural do sistema é soberana. O agente deve cumprir disciplinadamente:
- 1. **Verificação de Compilação Incremental**: Após instalar qualquer dependência ou criar um diretório estrutural base, execute o comando de compilação ou checagem de tipos local (ex: `npx tsc --noEmit`, `go build`, `cargo check`). Nunca acumule alterações sem certificar que o build atual passa.
- 2. **Zero Pseudocódigo**: É expressamente proibido usar comentários de escape como `// ...` ou `// resto do código aqui` na criação das rotas ou arquivos do scaffold. Cada arquivo instanciado deve ser auto-contido e plenamente funcional comercialmente.
- 3. **Setup de Dependências Seguro**: Defina as versões das bibliotecas de forma exata. Sempre rode a instalação explicitamente para garantir a atualização limpa dos lockfiles (`package-lock.json`, `go.sum`, `yarn.lock`).
- 4. **Construção de Pontes e Contratos**: Se o MVP depender de serviços externos (como banco ou autenticação), forneça stubs/mocks utilizáveis localmente no scaffold. Evite que o app lance crashes não tratados na primeira inicialização.
+ ## Golden Rule (Non-Negotiable)
- ## Fluxo de Trabalho
+ **It is strictly forbidden to build base UI components or infrastructure from scratch.**
- ### Fase 1: Ingestão de Contexto e Proposta Técnica (Bootstrap Alinhado)
- Você não deve realizar "interrogatórios genéricos" sobre o negócio, pois o domínio já foi estabelecido pela skill predecessora.
+ Reuse shared components and mature libraries focused on prototyping speed. This is the highest priority and non-negotiable. Always prefer shadcn/ui, Radix, MUI, or equivalent proven UI kits over custom components.
- 1. **Leia obrigatoriamente** o `CONTEXT.md` e a pasta `docs/adr/`.
- 2. Baseado no domínio do negócio descoberto, elabore uma infraestrutura hiper-produtiva. Assuma uma postura consultiva e opinativa a favor da velocidade.
- 3. Se o contexto sugerir uma aplicação web padrão, proponha categoricamente o ecossistema comprovado: **Next.js + Tailwind + shadcn/ui**. Se for outro perfil (ex: CLI, Worker, Backend puro), proponha a stack de MVP equivalente na respectiva linguagem.
- 4. **Validação Obrigatória:** Apresente a stack escolhida e pergunte explicitamente:
- > "Baseado no nosso contexto de domínio, proponho iniciar com [STACK_ESCOLHIDA] para máxima produtividade sem reinventar a roda. Você concorda com esta stack ou temos alguma restrição técnica não mapeada?"
+ ## Stability and Technical Cadence (No Rushing)
- ### Fase 2: Execução Técnico-Estrutural
- Apenas prossiga após a anuência explícita do usuário. Se o usuário sugerir mudanças, adeque o bootstrap. Quando aprovado:
+ MVP speed must not produce unstable code or structural shortcuts. Syntactic and architectural integrity is sovereign. The agent must follow:
- 1. **Inicialização do Projeto (package.json / go.mod / pyproject.toml):** Configure o ecossistema.
- 2. **Instalação da Stack Base:** (Ex: `npx shadcn-ui@latest init` se aplicável).
- 3. **Estruturação de Diretórios Ágeis:** Crie a hierarquia focada no reuso de código:
- - `/components/shared` (para componentes UI reutilizáveis injetados via bibliotecas)
- - `/lib` (funções úteis e integrações de serviço)
- - `/hooks` (lógica de estado customizada)
- 4. **Gerar README Ágil:** Documente comandos de execução local, visão arquitetural adotada e como a prototipação rápida deve ser guiada (focando em reuso).
+ 1. **Incremental compilation check**: After installing any dependency or creating a base directory, run the local build or type check command (e.g., `npx tsc --noEmit`, `go build`, `cargo check`). Never accumulate changes without confirming the current build passes.
+ 2. **Zero pseudo-code**: Escape comments such as `// ...` or `// rest of the code here` are forbidden in routes or scaffold files. Every created file must be self-contained and commercially functional.
+ 3. **Safe dependency setup**: Pin exact library versions. Always run the explicit install command to ensure clean lockfile updates (`package-lock.json`, `go.sum`, `yarn.lock`, `pnpm-lock.yaml`).
+ 4. **Bridge and contract building**: If the MVP depends on external services (database, auth), provide locally usable stubs or mocks. Avoid unhandled crashes on the first startup.
- ## Critérios de Retorno
- Finalize atualizando/registrando a stack base no `CONTEXT.md` (sob Detalhes Técnicos) e devolva o fluxo ao Orchestrator informando que o terreno está pronto para desenvolvimento de features.
+ ## Workflow
+
+ ### Phase 1 — Context Ingestion and Stack Proposal (Aligned Bootstrap)
+
+ Do not perform generic business interrogation; the predecessor skill already established the domain.
+
+ 1. **Read** `CONTEXT.md`, `docs/adr/`, and the approved `.specs/SPEC-*.md`.
+ 2. Based on the discovered domain, design a hyper-productive infrastructure. Be consultative and opinionated in favor of speed.
+ 3. If the context suggests a standard web app, categorically propose the proven ecosystem: **Next.js + Tailwind + shadcn/ui**. For other profiles (CLI, worker, pure backend), propose the equivalent MVP stack in the respective language.
+ 4. **Mandatory validation:** Present the chosen stack and ask the user in Portuguese:
+
+ ```text
+ Baseado no nosso contexto de dominio, proponho iniciar com [STACK_ESCOLHIDA] para maxima produtividade sem reinventar a roda.
+
+ Voce concorda com esta stack ou temos alguma restricao tecnica ainda nao mapeada?
+
+ ➡️ Meu palpite: concordo com a proposta.
+ ```
+
+ Wait for explicit user approval. If the user wants changes, adapt the bootstrap. If the user agrees, proceed.
+
+ ### Phase 2 — Technical and Structural Execution
+
+ Proceed only after explicit user approval.
+
+ 1. **Project initialization** (`package.json`, `go.mod`, `pyproject.toml`, `Cargo.toml`, etc.): configure the ecosystem.
+ 2. **Base stack installation** (e.g., `npx shadcn-ui@latest init` where applicable).
+ 3. **Agile directory structure** focused on code reuse:
+ - `/components/shared` — reusable UI components injected via libraries
+ - `/lib` — utility functions and service integrations
+ - `/hooks` — custom state logic
+ 4. **Generate a lean README** documenting:
+ - local run commands
+ - adopted architectural view
+ - how rapid prototyping should be guided (reuse first)
+ 5. **Run the build/type check** after each significant step. Fix any error before moving on.
+
+ ## Stack Decision Tree
+
+ Use this table to propose a reasonable default. Confirm with the user before committing.
+
+ | Profile | Default MVP stack | UI kit |
+ | --- | --- | --- |
+ | Web app (SaaS, marketing, dashboard) | Next.js 15 + Tailwind + React Server Components | shadcn/ui |
+ | CLI / script | Node.js + Commander or Python + Click / Typer | — |
+ | API / backend | Node.js/Express or .NET 8 or FastAPI | — |
+ | Mobile | React Native (Expo) or Flutter | nativewind / shadcn RN |
+ | Data / ML | Python + Pydantic + FastAPI or Jupyter | — |
+
+ If the user has a different preference, ask in Portuguese:
+
+ ```text
+ A stack padrao para este perfil e [STACK_SUGERIDA]. Voce confirma ou prefere uma alternativa?
+
+ ➡️ Meu palpite: confirmo a stack padrao.
+ ```
+
+ ## External Service Stubs
+
+ For every external dependency (database, cache, queue, auth, object storage, payment), create a local, runnable stub:
+
+ - Use Docker Compose or a local in-memory implementation where possible.
+ - Provide a `.env.example` with all required keys and fake local values.
+ - Add a health-check script.
+ - Never leave the app crashing on startup when a service is missing.
+
+ ## Return Criteria
+
+ Before handing back to the orchestrator:
+
+ - [ ] `CONTEXT.md` is updated with the chosen stack under **Technical Details**.
+ - [ ] `README.md` exists with run commands and a short architecture note.
+ - [ ] The build / type check passes cleanly.
+ - [ ] Lockfiles are updated and committed.
+ - [ ] No pseudo-code, `TODO`, or `// ...` escape comments remain in scaffold files.
+ - [ ] External dependencies have local stubs or mocks.
+
+ Then return control to the orchestrator reporting that the ground is ready for feature development.
+
+ ## Common Mistakes
+
+ | Mistake | Fix |
+ | --- | --- |
+ | Custom UI base components | Use a proven UI kit. |
+ | Skipping build checks | Run build/type check after every structural step. |
+ | Leaving `// ...` comments | Every file must be self-contained and functional. |
+ | No local stubs for external services | Add Docker / in-memory / env-example stubs. |
+ | Proceeding without user stack approval | Ask and wait for explicit Portuguese confirmation. |
+
+ ## References
+
+ - `grill-me-with-spec` — for producing the SPEC SDD that precedes this skill
+ - `create-agent-harness` — for installing the agent harness in the new repo
+ - `create-issues` — for turning Epics into GitHub Issues