🚪 Install gate: setup como state machine

Instalador comum trata o setup como script linear: roda do início ao fim, e se quebrar no meio o user fica órfão. O install gate trata como state machine: cada execução pergunta "em que estado eu estou?", decide o próximo passo, executa, salva o novo estado. Re-rodar é seguro. Parar no meio é seguro. Voltar amanhã e continuar é a operação padrão.

  ┌──────────────────────────────────────────────────────────────┐
  │                    install.sh inicia                         │
  └──────────────────────────────────────────────────────────────┘
                              │
                              ▼
              ┌─────────────────────────────┐
              │  Lê _install-state.json     │
              │  (cria se não existir)      │
              └─────────────────────────────┘
                              │
                              ▼
              ┌─────────────────────────────┐
              │  phase = ?                  │
              └─────────────────────────────┘
                              │
        ┌─────────────┬───────┴───────┬────────────────┐
        ▼             ▼               ▼                ▼
   [fresh]       [brand-ctx]    [skills-install]  [welcome]
        │             │               │                │
        ▼             ▼               ▼                ▼
   pergunta      coleta dados    instala skills    quick-win
   básicos       de marca        do catálogo       opcional
        │             │               │                │
        └─────────────┴───────┬───────┴────────────────┘
                              ▼
              ┌─────────────────────────────┐
              │  Marca passo como done      │
              │  Salva _install-state.json  │
              │  Imprime próximo passo      │
              └─────────────────────────────┘
                              │
                              ▼
                         [exit 0]
        

A virada conceitual: o instalador não é dono do tempo do user. Ele oferece passos, registra o que foi feito, sai limpo. O user volta quando quiser e o gate sabe exatamente onde retomar.

Um único arquivo na raiz do projeto carrega o estado. Pequeno, legível, versionado em git (ou em .gitignore se for por-máquina). É o contrato entre o instalador, os hooks e o próprio user.

{
  "version": "1.2.0",
  "schema": "iamasters-os/install-state/v1",
  "phase": "skills-install",
  "fresh": false,
  "started_at": "2026-05-18T20:11:43-03:00",
  "updated_at": "2026-05-18T20:38:09-03:00",
  "completed_steps": [
    {
      "id": "brand-context",
      "blocking": true,
      "completed_at": "2026-05-18T20:14:22-03:00",
      "artifact": "context/brand.md"
    },
    {
      "id": "claude-md-bootstrap",
      "blocking": true,
      "completed_at": "2026-05-18T20:16:01-03:00",
      "artifact": "CLAUDE.md"
    }
  ],
  "pending_steps": [
    { "id": "skills-install",      "blocking": true,  "estimated_minutes": 5 },
    { "id": "hooks-install",       "blocking": true,  "estimated_minutes": 3 },
    { "id": "welcome-quick-win",   "blocking": false, "estimated_minutes": 4 }
  ],
  "skipped_steps": [],
  "machine": {
    "os": "linux",
    "shell": "bash",
    "claude_code_version": "2.5.1"
  }
}
        

{
  "version": "1.2.0",
  "schema": "iamasters-os/install-state/v1",
  "phase": "brand-context",
  "fresh": true,
  "completed_steps": [],
  "pending_steps": [
    { "id": "brand-context",       "blocking": true,  "estimated_minutes": 6 },
    { "id": "claude-md-bootstrap", "blocking": true,  "estimated_minutes": 2 },
    { "id": "skills-install",      "blocking": true,  "estimated_minutes": 5 },
    { "id": "hooks-install",       "blocking": true,  "estimated_minutes": 3 },
    { "id": "welcome-quick-win",   "blocking": false, "estimated_minutes": 4 },
    { "id": "mcp-extras",          "blocking": false, "estimated_minutes": 5 }
  ],
  "skipped_steps": []
}
        

Nem todo passo é igual. Alguns precisam acontecer antes do OS sequer funcionar (bloqueantes). Outros melhoram a experiência mas o sistema roda sem (opcionais). O install gate distingue os dois explicitamente — porque misturar gera o pior dos dois mundos: ou o user é forçado a coisas que não precisa, ou pula coisas que vão quebrar depois.

Logo após os passos bloqueantes, o gate oferece uma demonstração concreta que prova o OS funciona pro caso real do user. Não é tutorial. Não é vídeo. É um artefato gerado com os dados que ele acabou de fornecer no brand-context, em <5min.

projects/welcome/
├── README.md                  # "Sua primeira vitória — feita pelo OS"
├── brand-applied-demo.html    # landing com cores/tom do brand-context
├── prompt-usado.md            # transparência: o prompt que gerou o artefato
└── proximos-passos.md         # 3 sugestões de próximos projetos
        

O quick-win não é marketing — é o teste de fumaça do próprio OS. Se ele falha, o user sabe imediatamente que algo está errado antes de tentar usar pra valer. Se passa, o user já tem 1 caso concreto pra mostrar pro chefe/cliente na próxima reunião.

Idempotência é a regra de ouro do install gate: rodar ./install.sh cem vezes seguidas deve produzir o mesmo resultado de rodar uma vez. Nenhum arquivo do user é sobrescrito sem aviso. Nenhum passo já feito é refeito. Nenhuma pergunta já respondida volta.

#!/usr/bin/env bash
set -euo pipefail

STATE_FILE="_install-state.json"
TEMPLATE_FILE=".iamasters/_install-state.template.json"

# 1. Inicializa state se não existir (fresh=true)
if [[ ! -f "$STATE_FILE" ]]; then
  cp "$TEMPLATE_FILE" "$STATE_FILE"
  jq '.fresh = true | .started_at = (now | todate)' \
     "$STATE_FILE" > "$STATE_FILE.tmp" && mv "$STATE_FILE.tmp" "$STATE_FILE"
fi

# 2. Lê fase atual
PHASE=$(jq -r '.phase' "$STATE_FILE")

# 3. Executa o handler da fase (case dispatch)
case "$PHASE" in
  brand-context)
    run_brand_context_step          # só pergunta se faltar
    advance_phase "claude-md-bootstrap"
    ;;
  claude-md-bootstrap)
    run_claude_md_step              # gera só se CLAUDE.md ausente
    advance_phase "skills-install"
    ;;
  skills-install)
    run_skills_install              # checa cada skill, pula se já instalada
    advance_phase "hooks-install"
    ;;
  hooks-install)
    run_hooks_install               # idempotente via jq merge em settings
    advance_phase "welcome-quick-win"
    ;;
  welcome-quick-win)
    run_quick_win_step              # opcional, pergunta antes
    advance_phase "done"
    ;;
  done)
    echo "✓ Install já completo. Use --reset para reinstalar."
    exit 0
    ;;
  *)
    echo "✗ Fase desconhecida: $PHASE"; exit 1
    ;;
esac
        

Depois do install, na primeira vez que o user abre o Claude Code no projeto, um hook SessionStart lê o _install-state.json, vê fresh=true, mostra um checklist com os próximos 5 passos sugeridos — e marca fresh=false para nunca mais aparecer automaticamente.

╭─────────────────────────────────────────────────────────────╮
│  Bem-vindo ao iAmasters OS — instalação completa ✓          │
├─────────────────────────────────────────────────────────────┤
│  Próximos 5 passos sugeridos:                               │
│                                                             │
│    1. Abrir projects/welcome/brand-applied-demo.html        │
│    2. Ler CLAUDE.md (3 min) — entender as regras do OS      │
│    3. Rodar /skills para ver o que está instalado           │
│    4. Criar seu 1º projeto: /new-project <nome>             │
│    5. Quando travar, rodar /doctor                          │
│                                                             │
│  Este checklist não aparece de novo. Use /welcome para ver. │
╰─────────────────────────────────────────────────────────────╯