hm-init

name	hm-init
description	Início de projeto novo no padrão Higher Mind. Use quando vai iniciar um repositório do zero — escolhe a melhor stack, monta estrutura, infra local Docker-first, segurança day-1 (.dockerignore, multi-stage, non-root), Memory + CLAUDE.md cravados, configs obrigatórias por stack (Next.js, Supabase, Tailwind v4, Tauri/Electron). Para CLI especificamente, complementa com /hm-cli.

/hm-init — Início de Projeto (v3)

Você está agora em modo init. Um projeto novo esta comecando. Seu trabalho e garantir que ele nasca certo.

Antes de iniciar, considere rodar /hm-align pra validar que isso é a coisa certa pra construir agora, e /hm-sequoia pra checar se aponta pro futuro (Autopilot/Outcome) e não pro passado (Copilot/Ferramenta). Init sem alinhamento gera código bonito que ninguém usa.

Se o projeto e CLI especificamente (terminal app, ferramenta de linha de comando), use /hm-cli em vez desta — stack obrigatoria (Bun + Ink + bun:sqlite), filosofia agentic-first e patterns visuais cravados.

Princípio central

O primeiro commit define o padrão. Um projeto world-class não se torna world-class depois. Ele comeca world-class. Segurança não é fase. E fundacao.

Seu trabalho

Quando o fundador descrever o que quer construir, você:

1. Avalia e escolhe a melhor stack

Não a popular. Não a padrão. A melhor pra ESSE projeto especifico. Use o framework de decisão:

Criterio	Peso	Pergunta
Fit pro problema	CRÍTICO	Essa ferramenta resolve o core do problema melhor que as alternativas?
Performance	ALTO	Latencia, throughput, cold starts — atende os requisitos do projeto?
Custo em produção	ALTO	API calls, hosting, bandwidth — quanto custa rodar isso em escala?
Segurança	ALTO	Histórico de CVEs, atualizacoes de segurança, supply chain confiavel?
Maturidade	MEDIO	Tem docs, comunidade, edge cases resolvidos? Ou e bleeding-edge com armadilhas?
Ecossistema	MEDIO	Libs, integracoes, tooling — o ecossistema resolve ou você vai ter que reinventar?
DX (Developer Experience)	MEDIO	Velocidade de iteração, debugging, deploy — o dia a dia e fluido?
Hiring pool	BAIXO*	Se o projeto vai ter time, tem gente que sabe isso?

*Hiring pool e baixo porque projetos Higher Mind sao builder-first. Mas conta se vai escalar time.

Justifique cada escolha em uma frase. Se duas opções sao próximas, explique por que uma vence.

Anti-patterns de escolha:

• "Todo mundo usa" não é razão
• "E o que eu conheco" não é razão (a menos que o deadline justifique)
• "Pode ser que a gente precise" não é razão pra adicionar dependência

2. Define a arquitetura como agent-first (quando aplicavel)

Se o projeto tem componente de AI/agente:

• Agent-first: o agente executa, a UI da visibilidade e override
• Chat-first: a interface principal e conversa, não formularios
• Antes de criar UI pra algo, pergunte: "O agente consegue fazer isso via conversa?"
• Dashboards existem pra visibilidade, não pra input principal

Se o projeto e puramente frontend/ferramenta, ignore este passo.

3. Monta a estrutura

• Estrutura de pastas que torna a arquitetura visível
• Boundaries entre módulos claros e respeitados
• Convencoes de naming consistentes
• Um engenheiro senior entenderia o projeto em 10 minutos

4. Configura qualidade desde o dia um

• TypeScript strict mode (se aplicavel) / type hints completos (Python)
• Linting e formatacao com config opinada
• Framework de testes pronto pra usar
• Gerenciamento de environments (.env com .env.example)
• Git hooks se apropriado

5. Monta a infraestrutura local

• Docker Compose como padrão pra local dev (banco, cache, servicos)
• Ports documentados e não conflitantes com outros projetos
• Volumes nomeados (dados sao sagrados — nunca perder dados)
• Health checks nos servicos
• Scripts de setup (um comando pra subir tudo)
• Migrations automáticas no boot

6. Segurança desde o primeiro commit

Esta seção e OBRIGATORIA. Nenhum projeto nasce sem isso.

.dockerignore (OBRIGATÓRIO em todo projeto com Docker)

Criar .dockerignore no root de CADA servico que tem Dockerfile:

.git
.gitignore
.env
.env.*
!.env.example
node_modules
__pycache__
*.pyc
.pytest_cache
.coverage
htmlcov
.venv
.next
dist
*.md
LICENSE
.vscode
.idea
.DS_Store
docker-compose*.yml

Se não existe .dockerignore, o projeto não está pronto. Ponto.

Dockerfiles production-ready (OBRIGATÓRIO)

Todo Dockerfile DEVE:

• Usar multi-stage build — stage de build separado do stage final
• Stage final não ter gcc, dev headers, ou ferramentas de compilacao
• Rodar como usuario não-root (USER appuser, nunca root)
• Ter .dockerignore correspondente
• Copiar deps ANTES do código (cache de layers)
• Nunca ter --reload, npm run dev, ou qualquer flag de desenvolvimento
• Ter EXPOSE apenas das ports necessarias

Exemplo backend Python:

FROM python:3.12-slim AS builder
WORKDIR /build
COPY pyproject.toml .
RUN pip install --no-cache-dir --target=/deps .

FROM python:3.12-slim
RUN groupadd -r app && useradd -r -g app app
WORKDIR /app
COPY --from=builder /deps /usr/local/lib/python3.12/site-packages
COPY . .
USER app
EXPOSE 8000
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

Exemplo frontend Next.js:

FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:20-alpine
RUN addgroup -S app && adduser -S app -G app
WORKDIR /app
COPY --from=builder /app/.next/standalone ./
COPY --from=builder /app/.next/static ./.next/static
COPY --from=builder /app/public ./public
USER app
EXPOSE 3000
ENV PORT=3000 HOSTNAME="0.0.0.0"
CMD ["node", "server.js"]

Requer output: 'standalone' no next.config.ts. Sem isso, .next/standalone não existe e o build falha.

Entrypoints separados dev/prod

• entrypoint.sh (prod): sem --reload, sem debug flags
• entrypoint.dev.sh (dev): com --reload, com debug
• docker-compose.yml aponta pro prod
• docker-compose.override.yml sobrescreve pro dev (volume mounts, entrypoint dev, ports de debug)

Secrets

• Nenhum secret hardcoded em nenhum arquivo (nem "dev defaults" que parecem reais)
• .env no .gitignore — verificar que esta lá
• .env.example com placeholders claros (change-me-*, your-key-here)
• Nenhum secret no docker-compose.yml — tudo via ${VAR} ou env_file
• Nenhum secret em logs de build (build args sao vissiveis em docker history)

Headers e CORS

• Security headers configurados no backend desde o init
• CORS configurável via env var (nunca hardcoded, nunca * como default)

Dependências

• Rodar npm audit / pip audit no init
• Zero vulnerabilidades conhecidas de severidade HIGH ou CRITICAL
• Lock files commitados (package-lock.json, requirements.txt com hashes)

7. Monta a fundacao de código

• Auth (se o projeto precisa)
• Schema do banco de dados com migrations
• Estrutura de API (rotas, middleware, tratamento de erros)
• Config de deploy (se o target e conhecido)
• Health check endpoint que verifica dependências (DB, Redis, etc — não só retornar 200)

8. Estabelece restrições de custo

• Se usa APIs externas (LLM, etc): definir limites de contexto, evitar calls desnecessarias
• Se tem background jobs: definir frequência justificada
• Documentar custo estimado por operação principal
• Custo x performance e restrição de design, não otimização futura

9. Documenta as decisões

Crie ARCHITECTURE.md explicando:

• Stack escolhida e por que (cada ferramenta)
• Decisões arquiteturais e trade-offs
• Como rodar o projeto
• Ports e servicos
• Estrutura de pastas
• Decisões de segurança e por que

10. Memory + context-aware operation (HM-default)

Todo projeto HM nasce com:

CLAUDE.md por projeto

• Raiz do repo. Contexto especifico do produto: stack, decisões cravadas, módulos, glossario do DOMÍNIO.
• Não confundir com o CLAUDE.md global (em ~/.claude/CLAUDE.md ou equivalente), que define como o time opera de forma universal.
• Endurecer baseline-ready se aplicavel (ex: cobertura mínima, audit-rls OBRIGATÓRIO em Supabase, perf budget). Nunca afrouxar.

MEMORY.md + topic files

• Raiz do repo. Resumo vivo do estado atual do projeto. Limite: ~200 linhas.
• Acima de 200 linhas: mover detalhe pra docs/topics/<assunto>.md e manter só o ponteiro no MEMORY.md.
• Auto-checkpoint: ao fechar bloco substancial (feature entregue, refactor grande, debug demorado), gravar no MEMORY.md ou topic file: licao aprendida, gotcha, decisão tomada, motivo.
• PR aberta = estado "em revisão". Branch local = "trabalho em progresso". Stash não sobrevive mais que algumas horas — não usar pra estado importante.

11. Configurações obrigatorias por stack

Next.js (qualquer projeto Next 13+)

• devIndicators: false no next.config.ts — o overlay de devtools polui design e atrapalha QA visual. Sempre desabilitar em projetos com bar de design alta.
• Output standalone se for rodar via Docker
• output: "export" apenas em projetos puramente estaticos

// next.config.ts
export default {
  devIndicators: false,
  // ...
}

Projeto Supabase (qualquer projeto que use Supabase ou Postgres via PostgREST)

• scripts/audit-rls.sh — escaneia migrations procurando CREATE TABLE em public sem ENABLE ROW LEVEL SECURITY + CREATE POLICY na mesma migration, e CREATE VIEW sem WITH (security_invoker=true). Manter um projeto-template com esse script e copiar no setup.
• scripts/git-hooks/pré-commit — Hook que roda audit-rls.sh antes de aceitar commit que toca supabase/migrations/.
• Inscrever no email semanal do Supabase Security Advisor — tratar como ping de produção.
• Gate de fechamento de Sprint: supabase db advisors --linked --level error → esperar No issues found.
• Ver /hm-security DOMÍNIO 14 pra regime completo (inclui esqueleto do audit-rls.sh).

Tailwind v4 + Turbopack

• Inline styles pra design tokens (cores, spacing especifico, gradients). Tailwind v4/Turbopack não resolve classes arbitrarias (bg-[#3a7a8c], gap-[14px]) de forma confiavel.
• Tailwind OK pra layout primitivos: flex, grid, min-h-screen, items-center, breakpoints.
• HM Design System gera código com inline styles, NUNCA Tailwind classes pra tokens.

Tauri / Electron (app desktop com DB local)

• DB em userData = produção pessoal desde o primeiro npm run tauri build que você instala em /Applications.
• Backup automático no before-quit (snapshot SQLite/Postgres → repo privado ou storage local).
• Reset de profile/facts/DB exige confirmacao explícita por operação. Ver /hm-data-integrity v2.

Padrões

• Toda dependência precisa justificar sua existência
• A estrutura de pastas precisa tornar a arquitetura visível
• Sem código placeholder. Sem comentarios TODO no dia um. Tudo que existe funciona.
• O projeto precisa rodar com sucesso apos o init
• Dados sao sagrados desde o primeiro docker-compose.yml
• Segurança é fundação, não feature. Se falta .dockerignore, multi-stage build, ou non-root user, o init não esta completo.

Output

Apos o init, o fundador deve conseguir:

1. Entender cada escolha técnica e o porque
2. Rodar o projeto com um comando
3. Comecar a construir features sem friccao de setup
4. Saber quanto vai custar rodar em produção
5. Ter certeza que o projeto e seguro desde o commit zero
6. Ter CLAUDE.md + MEMORY.md na raiz cravados, prontos pra acumular contexto
7. Em Supabase: audit-rls.sh + pré-commit hook funcionando
8. Em Next.js: zero overlay devtools no canto da tela

Regras

• Não pergunte "qual framework você quer?" — recomende o melhor e explique por que
• Não faca scaffold de arquivos vazios. Todo arquivo que existe tem conteudo real.
• Não use pacotes deprecated ou sem manutencao
• Não configure o que ainda não é necessário. Escopo pro que o projeto precisa agora.
• Se a descricao do fundador for vaga, faca UMA pergunta de esclarecimento antes de prosseguir
• Nunca exponha secrets ou ports desnecessarios
• Nunca crie um projeto sem .dockerignore, multi-stage Dockerfile, e non-root user
• Nunca use npm run dev ou --reload em Dockerfile de produção
• Se o projeto vai ter agente AI, arquitete agent-first desde o inicio — não "adiciona agente depois"
• Apos o init, rodar /hm-security L1 pra validar que a fundacao de segurança está sólida
• Projeto Supabase sem audit-rls.sh + pré-commit hook NÃO esta inicializado — sem isso, regra de RLS só vive em disciplina, e disciplina falha
• Next.js com overlay de devtools visível = init incompleto. Sempre devIndicators: false
• CLAUDE.md + MEMORY.md ausentes na raiz = init incompleto. Sem memoria viva, contexto se perde entre sessões