ganbatte-os 0.2.42 → 0.2.44

package/.gos/agents/profiles/ganbatte-os-master.md

@@ -47,6 +47,7 @@ persona_profile:
 
   communication:
     tone: commanding
+    tone_hibrido: "Commanding em decisao e orquestracao; didatico e orientado a produto (explicacao simples primeiro, pouca linguagem tecnica) ao explicar. Ref: libraries/architecture-stack-policy.md"
     emoji_frequency: low
 
     vocabulary:
@@ -91,6 +92,7 @@ persona:
     - "Cloudflare Pages helper: oferecer cloudflare-pages-setup ao iniciar projeto novo ou ao adicionar binding/env"
     - "Security best practices: aplicar libraries/security-best-practices.md por default (RLS Supabase, secrets via wrangler, validacao Zod front+back)"
     - "Engineering best practices: TypeScript strict, conventional commits, hexagonal-ish em continuo, achatar em descartavel (libraries/engineering-best-practices.md)"
+    - "Arquitetura antes de codigo: referencia (Figma Make/Stitch/outro projeto) e triagem — avaliar objetivo/contexto/hosting/servicos/alternativa-mais-simples antes de copiar; definir/atualizar stack (docs/stack.md + ADR) antes de implementar; own-vs-managed consciente em auth/deploy/DB; Mermaid p/ fluxos (auth/dados/jornada). Ref: libraries/architecture-stack-policy.md"
 
 # ─── PROACTIVE SUGGESTIONS ───────────────────────────────────
 # Trigger patterns onde o master sugere skills/libs proativamente, sem o usuario pedir.
@@ -131,11 +133,13 @@ proactive_suggestions:
       Codigo dessa tela vai incluir os 5 estados obrigatorios: skeleton (loading), empty (lista vazia + CTA), error (com retry), success, default. Lucide icons em tudo, sem emoji.
 
   decisao_arquitetural:
-    triggers: [qual banco, qual auth, qual hospedar, qual stack, escolher tecnologia, adr]
+    triggers: [qual banco, qual auth, qual hospedar, qual stack, escolher tecnologia, adr, copiar de, reproduzir, igual ao, mesmo que o projeto]
     sugerir:
       - "adr-tech-decisions para formalizar com perguntas ao usuario"
+      - "avaliar referencia antes de copiar (objetivo/contexto/hosting/servicos/alternativa-mais-simples) — libraries/architecture-stack-policy.md"
+      - "own-vs-managed em auth/deploy/DB: nao defaultar Supabase/Firebase por habito"
     output_template: |
-      Decisao arquitetural -> /gos:skills:adr-tech-decisions sempre pergunta antes de chumbar e consulta cloudflare-stack-kb + supabase-stack-kb. Posso rodar.
+      Antes de cravar: uma referencia (Figma Make/Stitch/outro projeto) e ponto de partida, nao decisao. Avalio objetivo, onde roda, servicos ja existentes e se ha alternativa mais simples — e so entao decido stack/auth/deploy. Decisao arquitetural -> /gos:skills:adr-tech-decisions formaliza (pergunta antes de chumbar, consulta cloudflare-stack-kb + supabase-stack-kb). Posso rodar.
 
 # ─── OUTPUT POLICY ───────────────────────────────────────────
 # Regras estritas de saida em codigo gerado.
@@ -157,6 +161,11 @@ output_policy:
     rule: "Conversa default em chat: zero emoji. Use texto direto."
     excecao: "Usuario pede explicitamente."
 
+  explicabilidade_produto:
+    rule: "Antes/junto de cada acao ou decisao relevante (rotear skill, gerar plano, escolher stack/tech, delegar, commitar), enunciar em 1-2 frases de PRODUTO/NEGOCIO o que sera feito, por que e qual o impacto — em linguagem que um usuario NAO-tecnico acompanha. Objetivo: tecnico e nao-tecnico sempre sabem minimamente o que esta acontecendo."
+    camada_tecnica: "Profundidade tecnica e camada opcional: entra sob demanda do usuario ou ao registrar decisao (ADR/stack). Nunca substitui a explicacao de produto."
+    ref: "libraries/architecture-stack-policy.md"
+
 # ─── DEFAULT STACK ───────────────────────────────────────────
 # Quando usuario nao especifica, master propoe este stack.
 default_stack:
@@ -207,9 +216,8 @@ comprehension_gate:
     - "Direct command execution (*help, *status, *exit)"
     - "Explicit user instruction to skip comprehension ('just do X', 'direto')"
   complementary_rules:
-    - "research-discipline.md"
-    - "think-before-act.md"
-    - "context-first-antes-acao.md"
+    - "demand-elegance.md"
+    - "plan-mode.md"
 
 # ─── ROUTING MATRIX ───────────────────────────────────────────
 #

package/.gos/libraries/architecture-stack-policy.md

@@ -0,0 +1,43 @@
+# Architecture & Stack Policy (G-OS)
+
+Decisão de arquitetura antes de código. Uma referência é ponto de partida, não decisão travada — e nenhuma implementação relevante começa sem a stack definida e a decisão registrada.
+
+## Referência ≠ decisão arquitetural
+
+Quando o input vem de outro projeto, do Figma Make, do Stitch ou de qualquer referência, o código é **material de triagem** — nunca cópia obrigatória. Antes de reproduzir componente, estrutura ou tecnologia, avaliar:
+
+- Qual é o objetivo real da funcionalidade e em que contexto ela roda.
+- Onde a aplicação será hospedada e quais serviços já existem (DB, auth, storage, e-mail, infra).
+- Se a tecnologia da referência ainda é a melhor escolha para **este** projeto e este destino.
+- Se há alternativa mais simples, coerente, econômica ou fácil de manter (compõe com `libraries/lazy-dev-policy.md`).
+
+Copiar a referência sem essa avaliação é como decisão arquitetural acidental — o que esta policy existe para impedir.
+
+## Stack-first (obrigatória)
+
+Nenhuma implementação relevante começa sem a stack definida. Os artefatos já têm dono único no G-OS — reutilizar, não duplicar:
+
+- **stack-do-projeto** → `docs/stack.md` (stack-of-record), mantido por `stack-profiler` (`*stack refresh|show|drift`). É contrato: todo plano trava `stack_ref: docs/stack.md@<sha>`; mudança de stack exige ADR + flag `--allow-arch-change`.
+- **decisões-arquiteturais** → `docs/adr/ADR-NNN-*.md`, mantidas por `adr-tech-decisions`.
+- **fluxos/** → `dirs.fluxos` do `plan-paths.json` (default `docs/fluxos/`), onde vivem os diagramas.
+
+A stack não evolui por acidente (por adicionar biblioteca durante o dev): cada escolha relevante tem finalidade clara e compatível com a arquitetura. Faltando informação para decidir, registrar a decisão como **pendente** com as opções e o que muda entre elas — nunca escolher arbitrário.
+
+## Auth & serviços próprios
+
+Não defaultar Supabase Auth / Firebase Auth (ou qualquer serviço) só porque aparece na referência. Avaliar own-vs-managed por contexto — Better Auth, fluxo próprio de cadastro/sessão, SMTP para confirmação/recuperação, DB próprio para usuários/sessões/permissões — pesando complexidade, segurança, personalização, controle dos dados, custo, manutenção, lock-in e compatibilidade com a infra escolhida. Escolher o que atende ao projeto, não o mais conhecido.
+
+## Diagramas Mermaid (padrão)
+
+Gerar diagramas Mermaid para os fluxos que ajudam a entender o produto — sem exigir conhecimento técnico avançado de quem lê: auth, cadastro/confirmação de e-mail, recuperação de senha, sessão, permissões/perfis, fluxos de negócio, integrações entre serviços, processamento de dados, jornada do usuário e arquitetura geral. Vivem no `plan.md` (quando cabe) e em `dirs.fluxos`.
+
+## Comunicação explicável (híbrido)
+
+Commanding em decisão e orquestração. Mas **toda ação ou decisão relevante acompanha uma explicação em nível de produto/negócio** — o quê será feito, por quê e qual o impacto — em linguagem simples, para que qualquer usuário (técnico ou não) saiba minimamente o que está acontecendo. O detalhe técnico é camada opcional: entra sob demanda ou ao registrar a decisão (ADR/stack). Português (pt-BR), explicação simples primeiro, profundidade depois.
+
+## Aplicação no G-OS
+
+- Regra sempre-ativa referenciada pelo `gos-master` (`core_principles`); explicabilidade reforçada no `output_policy` do master.
+- Donos dos artefatos: `stack-profiler` (stack.md) e `adr-tech-decisions` (ADRs) — esta policy rege o comportamento, não cria canal novo.
+- `plan-blueprint` avalia a referência antes de copiar (Fase 2.3) e emite os diagramas Mermaid de fluxo quando há auth/dados/jornada.
+- `check-plan.js` avisa (warn, não bloqueia) quando um plano com auth/fluxo de dados não traz diagrama Mermaid.

package/.gos/scripts/integrations/check-plan.js

@@ -18,6 +18,8 @@
  * 5. Cada T-NN*.md: head -1 == "---" E frontmatter contem `status: pendente`
  *    E `id:`, `plan_id:`, `seq:`, `title:`, E body tem `## Critérios de aceite`.
  * 6. Nenhum T-NN*.md tem secao `## Status` no body (formato bugado legado).
+ * 7. (warn, nao bloqueia) plan.md com "## Fluxo de auth/dados" deveria trazer
+ *    bloco ```mermaid (architecture-stack-policy.md).
  *
  * Exit code:
  *   0 = plano valido, usavel pelo pipeline
@@ -54,6 +56,13 @@ if (!fs.existsSync(planFile)) {
   if (!plan.startsWith('---\n')) {
     errors.push(`plan.md sem frontmatter YAML (head -1 != "---")`);
   }
+  // Mermaid (nao bloqueia): plano com fluxo de auth/dados deveria trazer diagrama.
+  // Regra: libraries/architecture-stack-policy.md.
+  const declaresFlow = /^## Fluxo de (auth|dados)/m.test(plan);
+  const hasMermaid = /```mermaid/.test(plan);
+  if (declaresFlow && !hasMermaid) {
+    warnings.push('plan.md tem "## Fluxo de auth/dados" sem bloco ```mermaid — architecture-stack-policy sugere diagrama de fluxo (auth/dados/jornada) p/ tecnico e nao-tecnico entenderem. Nao bloqueia.');
+  }
 }
 
 if (!fs.existsSync(contextFile)) {

package/.gos/skills/adr-tech-decisions/SKILL.md

@@ -11,6 +11,7 @@ sourceDocs:
   - libraries/cloudflare-stack-kb.md
   - libraries/supabase-stack-kb.md
   - templates/adr-tmpl.yaml
+  - libraries/architecture-stack-policy.md
 use-when:
   - tem-se PRD pronto e precisa decidir arquitetura
   - antes de plan-blueprint quando o projeto e novo

package/.gos/skills/plan-blueprint/SKILL.md

@@ -7,6 +7,7 @@ sourceDocs:
   - templates/planTemplate.md
   - templates/contextTemplate.md
   - playbooks/plan-creation-playbook.md
+  - libraries/architecture-stack-policy.md
 use-when:
   - criar plano de implementação para uma tela específica
   - input começa com URL Figma (auto-detectado)
@@ -173,6 +174,19 @@ Saída desta fase é uma seção **"Aderência à Stack"** no plano — não red
 
 **Modo `--allow-arch-change`**: pode propor alteração. Gerar ADR em `dirs.adr` (template `templates/adr-tmpl.yaml`) ANTES de prosseguir. Plano referencia o ADR e marca `arch_change: true` no frontmatter.
 
+### 2.3 Avaliar referência antes de copiar (preventivo)
+
+Base: `libraries/architecture-stack-policy.md`. Quando a tela deriva de uma **referência** (Figma Make, Stitch, outro projeto, componente colado), o código é triagem — nunca cópia obrigatória. Antes de reproduzir componente/estrutura/tecnologia, confrontar com o `stack.md`:
+
+a) **Objetivo/contexto**: a funcionalidade e o destino (onde roda, hosting, serviços já existentes) justificam a tech da referência? Ou há alternativa mais simples/coerente com a stack registrada (compõe com `libraries/lazy-dev-policy.md`)?
+b) **Own-vs-managed** (auth/deploy/DB/e-mail): não herdar Supabase/Firebase/etc. da referência por hábito — só se o `stack.md` já os declara ou se a avaliação apontar.
+c) **Divergência que implica mudança de stack** → não copiar direto: rodar em modo `--allow-arch-change` (gera ADR) ou registrar decisão **pendente** em `## Backend pendings`/`spec.md` com as opções. Nunca cravar arbitrário.
+d) Referência 100% aderente ao `stack.md` → seguir; registrar em 1 linha no plano que a referência foi avaliada e aderente.
+
+É a versão **preventiva** da Fase 1.6 (que limpa starter legado depois): aqui avalia-se antes de trazer para dentro.
+
+**Diagramas Mermaid**: quando esta tela envolve **auth, fluxo de dados relevante ou jornada do usuário**, emitir o(s) diagrama(s) Mermaid correspondente(s) direto no `plan.md` (seções `## Fluxo de auth` / `## Fluxo de dados` / navegação do `planTemplate.md`). A jornada sai da Fase 1.4 (`## Interações & Estados`); auth/dados saem daqui (Fase 2). Ajuda técnico e não-técnico a entender o produto.
+
 ### 2.4 Schema/contrato gate (executa antes de Fase 3)
 
 Quando a tela exibe ou consome dados, validar contrato backend ANTES de emitir tasks frontend dependentes — evita o padrão PLAN-012/013 (schema descoberto incompleto durante execução).
@@ -244,6 +258,7 @@ Para cada plano (incluindo filhos), os 4 passos abaixo são **obrigatórios e at
 - `<dirs.planos>/PLAN-NNN-<slug>/spec.md` existe (não-vazio, sem placeholders nos critérios de aceite globais).
 - `<dirs.planos>/PLAN-NNN-<slug>/tasks/` existe e contém ≥1 `T-NN*.md`.
 - Para CADA `T-NN*.md`: `head -1` = `---` E grep `^status: pendente$` retorna match. Cada task tem `## Critérios de aceite (DoD)` não-vazio. Use o gate da Phase 3.5 do `plan-to-tasks`. Falha → regerar tasks; se persistir, abortar com erro explícito ao usuário citando os arquivos malformados.
+- Quando a tela tem **auth ou fluxo de dados relevante**: `plan.md` contém ≥1 bloco ` ```mermaid ` dos fluxos (Fase 2.3). `check-plan.js` **avisa** (não bloqueia) se faltar.
 - `progress.txt` aponta para o plano novo.
 
 ### Gate determinístico — ÚLTIMA ação obrigatória do `*plan`

package/.gos/skills/stack-profiler/SKILL.md

@@ -6,6 +6,7 @@ allowedTools: [Read, Glob, Grep, Bash, Write, Edit, AskUserQuestion]
 sourceDocs:
   - templates/stackTemplate.md
   - playbooks/plan-creation-playbook.md
+  - libraries/architecture-stack-policy.md
 use-when:
   - primeiro setup do projeto no fluxo de planos do G-OS
   - stack mudou (libs, framework, ORM, auth, hosting)

package/.gos/templates/planTemplate.md

@@ -104,10 +104,33 @@ Decisões possíveis:
 - Entrada: <de onde vem>
 - Saída: <para onde vai>
 
+```mermaid
+flowchart LR
+  Origem[<de onde vem>] --> Tela[<esta tela>]
+  Tela --> Destino[<para onde vai>]
+```
+
 ## Fluxo de dados
 
+```mermaid
+flowchart TD
+  Tela[<tela>] --> Fetch[<fetch/server action>]
+  Fetch --> Fonte[<endpoint/tabela>]
+  Fonte --> Componente[<componente>] --> Render[render]
 ```
-<diagrama textual: tela → fetch → componente → render>
+
+## Fluxo de auth
+
+> Preencher SÓ quando a tela exige autenticação/autorização (senão remover a seção). Diagrama em linguagem que técnico e não-técnico entendam.
+
+```mermaid
+flowchart TD
+  Usuario[Usuário] --> Acao[<login / signup / acesso protegido>]
+  Acao --> Verifica{Autenticado?}
+  Verifica -- não --> Redireciona[<redireciona p/ login>]
+  Verifica -- sim --> Autoriza{Tem permissão?}
+  Autoriza -- não --> Nega[<403 / sem acesso>]
+  Autoriza -- sim --> Acessa[<acessa a tela>]
 ```
 
 ## Plano de execução

package/.gos/templates/stackTemplate.md

@@ -70,3 +70,4 @@ read_only_backend: <true|false>
 - README: <path>
 - CLAUDE.md: <path>
 - ADRs ativas: <lista>
+- Diagramas de fluxo (Mermaid): <dirs.fluxos, default docs/fluxos/ — auth, dados, jornada, arquitetura>

package/AGENTS.md

@@ -2,53 +2,55 @@
 
 ## Objetivo
 
-Este repo existe para acelerar design-to-code e entrega de sprint.
-
-## Agentes
-
-| ID | Slash Command | Foco |
-|----|--------------|------|
-| **gos-master** | `/gos:agents:gos-master` | Orquestrador master — routing, skills, squads, workflows |
-| **architect** | `/gos:agents:architect` | Stack, padroes tecnicos, revisoes de arquitetura |
-| **dev** | `/gos:agents:dev` | Implementacao de features, hooks, refinamentos |
-| **devops** | `/gos:agents:devops` | Git, branches, CI/CD, automacoes de entrega |
-| **po** | `/gos:agents:po` | Backlog, scope, priorizacao |
-| **qa** | `/gos:agents:qa` | Testes, quality gates, revisao de codigo |
-| **sm** | `/gos:agents:sm` | Sprint, planning, sync com stakeholders |
-| **squad-creator** | `/gos:agents:squad-creator` | Orquestracao de times multi-agentes |
-| **ux-design-expert** | `/gos:agents:ux-design-expert` | Design de interfaces, tokens, design systems |
-
-## Skills
-
-| Skill | Slash Command | Funcao |
-|-------|--------------|--------|
-| **design-to-code** | `/gos:skills:design-to-code` | Converte Figma/screenshot em componentes React |
-| **figma-implement-design** | `/gos:skills:figma-implement-design` | Implementa design Figma com fidelidade 1:1 |
-| **figma-make-analyzer** | `/gos:skills:figma-make-analyzer` | Analisa output do Figma Make |
-| **make-code-triage** | `/gos:skills:make-code-triage` | Classifica codigo do Figma Make por categoria |
-| **make-version-diff** | `/gos:skills:make-version-diff` | Compara versoes de output Figma Make |
-| **component-dedup** | `/gos:skills:component-dedup` | Detecta componentes duplicados |
-| **frontend-dev** | `/gos:skills:frontend-dev` | Build componentes, pages, hooks (React/Next.js) |
-| **interface-design** | `/gos:skills:interface-design` | Design de interface com metodologia intent-first |
-| **react-best-practices** | `/gos:skills:react-best-practices` | Otimizacao de performance React/Next.js |
-| **react-doctor** | `/gos:skills:react-doctor` | Diagnostico de saude de componentes React |
-| **plan-to-tasks** | `/gos:skills:plan-to-tasks` | Converte plano em tasks acionaveis |
-| **agent-teams** | `/gos:skills:agent-teams` | Coordena multiplos agentes em time |
-| **git-ssh-setup** | `/gos:skills:git-ssh-setup` | Configura identidade SSH para o workspace |
-| **stack-profiler** | `/gos:skills:stack-profiler` | Mantem `docs/stack.md` (stack-of-record canonica) |
-| **plan-blueprint** | `/gos:skills:plan-blueprint` | Cria plano por tela (1 tela = 1 plano) |
-| **progress-tracker** | `/gos:skills:progress-tracker` | Memoria L1 (`progress.txt`) + state machine |
+Kit de desenvolvimento com IA: design-to-code, implementacao, otimizacao e seguranca.
+
+## Entrypoints (2 slash commands)
+
+A superficie user-facing sao **dois** comandos. As skills e os demais agentes NAO sao digitados — o `gos-master` os invoca a partir da sua intencao.
+
+| Entrypoint | Foco |
+|------------|------|
+| `/gos:agents:gos-master` | Orquestrador — decide skills/agentes/subagents/squads e executa |
+| `/gos:agents:ux-design-expert` | Design de interfaces, tokens, design systems |
+
+## Agentes internos (delegacao, nao-slash)
+
+O master delega a especialistas via Task tool: `architect`, `dev`, `devops`, `po`, `qa`, `sm` (facilitador de planejamento de dev), `squad-creator`, `security-auditor`, `perf-optimizer`. Fonte: `.gos/agents/profiles/`.
+
+## Skills (auto-discoveraveis, invocadas pelo master)
+
+34 skills, agrupadas por capacidade. Catalogo completo em `.gos/skills/registry.json`.
+
+- **Design → codigo**: `design-to-code`, `figma-implement-design`, `figma-make-analyzer`, `make-code-triage`, `make-version-diff`, `figma-print-diff`, `interface-design`, `ui-guardrails`, `prototype-orchestrator`
+- **Frontend/React**: `frontend-dev`, `react-best-practices`, `react-doctor`, `component-dedup`, `cloudflare-pages-setup`, `typeform-form-pattern`, `timer-component-pattern`
+- **Pipeline de planos**: `stack-profiler`, `plan-blueprint`, `plan-to-tasks`, `execute-plan`, `validate-plan`, `progress-tracker`, `audit-screenshots`
+- **Qualidade**: `security-review`, `perf-review`, `simplify-review`
+- **Produto/texto/utilitarios**: `idea-intake`, `prd-from-intake`, `adr-tech-decisions`, `humanizer`, `gos-caveman`, `gos-compress`, `agent-teams`, `git-ssh-setup`
+
+## Arquitetura & Stack (regra sempre-ativa)
+
+Decisao de arquitetura vem antes do codigo — policy: `.gos/libraries/architecture-stack-policy.md`.
+
+- **Referencia != decisao**: codigo de Figma Make/Stitch/outro projeto e triagem; avaliar objetivo/contexto/hosting/servicos/alternativa-mais-simples antes de copiar.
+- **Stack-first**: nada relevante comeca sem `docs/stack.md` definido (contrato; mudar exige ADR em `docs/adr/`). Falta info => decisao pendente com opcoes.
+- **Own-vs-managed**: auth/deploy/DB avaliados por contexto, nunca defaultados por habito.
+- **Mermaid**: diagramas de fluxo (auth, dados, jornada, arquitetura) no `plan.md` e em `dirs.fluxos`.
+- **Master explicavel**: cada acao vem com explicacao de produto/negocio (o que/por que/impacto) em linguagem simples; detalhe tecnico sob demanda.
 
 ## Plan Pipeline
 
-Pipeline padronizado para criacao de planos por tela. Stack-of-record (`docs/stack.md`) e contrato — alteracoes exigem ADR.
+Toda tela = 1 plano. Stack-of-record (`docs/stack.md`) e contrato — alteracoes exigem ADR. Divisao: **Senior planeja (plan), Junior implementa (execute), Senior audita (validate)** — modelo por etapa em `.gos-local/models.json`.
 
 | Comando | Skill | Funcao |
 |---------|-------|--------|
 | `*stack [refresh\|show\|drift]` | `stack-profiler` | Mantem `docs/stack.md` |
-| `*plan <tela>` | `plan-blueprint` | Cria plano + tasks + context + atualiza `progress.txt` |
+| `*plan <tela>` | `plan-blueprint` | Cria `plan.md` + `context.md` + `spec.md` + `tasks/` (com criterios de aceite) |
+| `*execute-plan <PLAN-NNN>` | `execute-plan` | Implementa task-a-task com visual gate + loop de correcao |
+| `*validate-plan <PLAN-NNN>` | `validate-plan` | Audita, corrige gaps, roda seguranca + performance + doc-sync |
 | `*progress [show\|set\|status]` | `progress-tracker` | State machine `pendente -> em-andamento -> validacao -> concluido` |
 
+Auditorias sob demanda: `*security-review`, `*perf-review`, `*simplify-review`.
+
 Paths do projeto-cliente sao resolvidos via `.gos-local/plan-paths.json` (incluindo `knowledge_sources` como Postman, regras-de-negocio, ADRs). Playbook: `.gos/playbooks/plan-creation-playbook.md`.
 
 ## Plan Mode Protocol

package/CLAUDE.md

@@ -37,6 +37,16 @@ Todo texto gerado deve passar por correcao ortografica e remocao de padroes de I
 - **Documentacao sempre sincronizada** (`libraries/doc-sync-policy.md`): regra de negocio criada/alterada/removida => atualizar docs impactadas (regras-de-negocio, fluxos, permissoes, ADR, seeds, contratos) no mesmo PR. `plan.md` `## Impacto documental` declara; `validate-plan` bloqueia o fechamento se algo ficou dessincronizado.
 - **Anti-over-engineering** (`libraries/lazy-dev-policy.md`): escrever so o necessario — reuso > stdlib > native > dep > 1 linha > minimo. Nunca cortar validacao/seguranca/a11y.
 
+## Arquitetura & Stack (decisao antes de codigo)
+
+Regra sempre-ativa: `libraries/architecture-stack-policy.md`. Decisao de arquitetura vem antes do codigo.
+
+- **Referencia != decisao**: codigo de Figma Make/Stitch/outro projeto e triagem — avaliar objetivo, contexto, hosting, servicos (DB/auth/storage/e-mail) e alternativa mais simples ANTES de copiar. Nunca cravar a tech da referencia por habito.
+- **Stack-first**: nenhuma implementacao relevante comeca sem stack definida. `stack-do-projeto` = `docs/stack.md` (contrato via `stack_ref`; mudar exige ADR), `decisoes-arquiteturais` = `docs/adr/`. Falta info => registrar decisao pendente com opcoes, nunca escolher arbitrario.
+- **Auth/servicos own-vs-managed**: nao defaultar Supabase/Firebase por aparecer na referencia — avaliar Better Auth/fluxo proprio/SMTP/DB proprio por contexto (custo, controle, lock-in, infra).
+- **Diagramas Mermaid**: gerar Mermaid para fluxos que ajudam a entender o produto (auth, dados, jornada, permissoes, integracoes, arquitetura). Vivem no `plan.md` e em `dirs.fluxos` (default `docs/fluxos/`).
+- **Master explicavel**: toda acao/decisao relevante vem com explicacao em nivel de produto/negocio (o que, por que, impacto) em linguagem simples — tecnico e nao-tecnico entendem; detalhe tecnico e camada opcional.
+
 ## Comandos do Workspace
 
 | Comando | O que faz |
@@ -50,14 +60,20 @@ Todo texto gerado deve passar por correcao ortografica e remocao de padroes de I
 
 ## Slash Commands
 
-### Agents (invoke via /gos:agents:{id})
-gos-master | architect | dev | devops | po | qa | sm | squad-creator | ux-design-expert
+Superficie user-facing = **2 entrypoints**. As skills e demais agentes NAO sao digitados; o `gos-master` os invoca a partir da intencao (o usuario guia com `*comandos` no chat, ex.: `*plan`, `*security-review`).
+
+### Entrypoints (slash)
+- `/gos:agents:gos-master` — orquestrador; decide skills/agentes/subagents/squads e executa.
+- `/gos:agents:ux-design-expert` — design de interface, tokens, design systems.
+
+### Agentes internos (delegacao, nao-slash)
+architect | dev | devops | po | qa | sm | squad-creator | security-auditor | perf-optimizer
 
-### Skills (invoke via /gos:skills:{slug})
-design-to-code | figma-implement-design | figma-make-analyzer | make-code-triage | make-version-diff | component-dedup | frontend-dev | interface-design | react-best-practices | react-doctor | plan-to-tasks | agent-teams | git-ssh-setup | humanizer | stack-profiler | plan-blueprint | progress-tracker | execute-plan | validate-plan | audit-screenshots | security-review | perf-review | simplify-review
+### Skills (auto-discoveraveis, invocadas pelo master — 34, ver `.gos/skills/registry.json`)
+design-to-code | figma-implement-design | figma-make-analyzer | make-code-triage | make-version-diff | component-dedup | frontend-dev | interface-design | react-best-practices | react-doctor | plan-to-tasks | agent-teams | git-ssh-setup | humanizer | stack-profiler | plan-blueprint | progress-tracker | execute-plan | validate-plan | audit-screenshots | security-review | perf-review | simplify-review | idea-intake | prd-from-intake | adr-tech-decisions | prototype-orchestrator | gos-caveman | gos-compress | figma-print-diff | ui-guardrails | cloudflare-pages-setup | typeform-form-pattern | timer-component-pattern
 
-### IDEs suportadas (npm run sync:ides gera adapters)
-Claude Code | Cursor | Gemini CLI | Qwen Code | Antigravity | Opencode | Kilo Code | **Codex IDE Extension** (ambiente de execucao, comando primario `*execute-plan`)
+### IDEs suportadas (npm run sync:ides gera adapters p/ 6)
+Claude Code | **Codex IDE Extension** (executor, comando primario `*execute-plan`) | Qwen Code | Opencode | Gemini CLI | Antigravity. Cursor e Kilo Code consomem regras via arquivo (`.cursor/`, `.kilocode/`), sem adapters gerados.
 
 ## Model routing por etapa (Junior executa, Senior audita)
 

package/GEMINI.md

@@ -2,16 +2,24 @@
 
 Use este projeto como um kit de desenvolvimento: design-to-code, implementacao, otimizacao e seguranca.
 
+## Entrypoints
+
+Superficie user-facing = 2 slash commands. As skills sao invocadas pelo master, nao digitadas.
+
+- `/gos:agents:gos-master` — orquestrador; decide skills/agentes/squads e executa.
+- `/gos:agents:ux-design-expert` — design de interface, tokens, design systems.
+
 ## Prioridades
 
-- Figma, Figma Make e Stitch para React/Next.js
-- planejamento por tela (plano + tasks com criterios de aceite)
-- auditoria de seguranca e performance
+- Figma, Figma Make e Stitch para React/Next.js (codigo de referencia = triagem; avaliar antes de copiar)
+- arquitetura antes de codigo: stack-first (`docs/stack.md` + ADR), own-vs-managed consciente, Mermaid p/ fluxos — `.gos/libraries/architecture-stack-policy.md`
+- planejamento por tela (`*plan` → `*execute-plan` → `*validate-plan`, com criterios de aceite)
+- auditoria de seguranca e performance (`*security-review`, `*perf-review`)
 - revisao de qualidade antes de entrega
+- master explicavel: cada acao explicada em nivel de produto/negocio (tecnico e nao-tecnico entendem)
 
 ## Fontes principais
 
 - `AGENTS.md`
 - `CLAUDE.md`
-- `docs/toolchain-map.md`
-- `skills/registry.json`
+- `.gos/skills/registry.json`

package/README.md

@@ -8,493 +8,127 @@ Framework operacional de desenvolvimento: prototipacao, design-to-code, implemen
 [![NPM Home](https://img.shields.io/badge/NPM-Registry-red)](https://www.npmjs.com/package/ganbatte-os)
 ![Node >= 18](https://img.shields.io/badge/Node.js-%3E%3D18-green)
 
-O **ganbatte-os** organiza agentes de IA, skills e squads num workspace pronto para uso. Ele orquestra o ciclo completo de desenvolvimento — da prototipacao à implementação, otimização e segurança — conectando Figma e as principais IDEs de IA (Claude Code, Gemini, Cursor, etc). Baseado nos padrões do framework `.a8z-OS`.
+O **ganbatte-os** e um workspace de IA para desenvolvimento. Você conversa com **um orquestrador** e ele decide sozinho quais skills, agentes e squads acionar — do Figma ao código, passando por implementação, otimização e segurança. Funciona nas principais IDEs de IA (Claude Code, Codex, Qwen, Opencode, Gemini, Antigravity).
 
-## Quick Start
+## Instalação
 
-### 1. Instalação
+Instalação **global** (recomendada):
 
 ```bash
-mkdir meu-projeto && cd meu-projeto
-git init
-npm install ganbatte-os
-./node_modules/.bin/gos install
+npm install -g ganbatte-os
 ```
 
-Alternativa global:
+Depois, dentro do seu projeto:
 
 ```bash
-npm install -g ganbatte-os
+mkdir meu-projeto && cd meu-projeto
+git init            # recomendado (habilita versionamento e updates)
 gos install
 ```
 
-Alternativa direto do GitHub (ultima versao do main):
+O `gos install` cria uma estrutura enxuta na raiz:
 
-```bash
-npm install github:adrianomorais-ganbatte/g-os
-./node_modules/.bin/gos install
-```
+- `.gos/` — núcleo do framework (agentes, skills, scripts). Somente leitura.
+- `AGENTS.md`, `CLAUDE.md`, `GEMINI.md` — instruções que a IDE lê automaticamente.
+- `packages/` — onde vive o código do seu app.
+- adapters de IDE (`.claude/`, `.codex/`, `.qwen/`, `.opencode/`, `.gemini/`, `.agent/`) — gerados automaticamente.
 
-### 2. Pós-Instalação
-Após rodar o install, o framework criará uma estrutura limpa na sua raiz:
-- `.gos/` — O núcleo do framework (Agentes, Skills, Scripts).
-- `AGENTS.md`, `CLAUDE.md`, `GEMINI.md` — Instruções para as IDEs.
-- `packages/` — Onde você deve colocar o código do seu aplicativo.
+Atualizar o CLI global depois: `npm install -g ganbatte-os@latest` · atualizar o framework num projeto: `gos install --force`.
 
-### 3. Comandos do Workspace
+## Como usar: duas portas de entrada
 
-| Comando | Equivalente CLI | O que faz |
-|---------|-----------------|-----------|
-| `npm run gos:init` | `gos init` | Setup pos-clone: configura `upstream`, cria `.gos-local/`, gera IDE adapters |
-| `npm run gos:update` | `gos update` | Fetch + merge do upstream (**apenas em fork/clone do g-os**) |
-| `npm run gos:doctor` | `gos doctor` | Health-check (42+ checks: skills, agents, IDE adapters, upstream alcançável, stashes acumulados, modo workspace) |
-| `npm run gos:version` | `gos version` | Versão instalada, modo do workspace e atualizações pendentes |
-| `npm run gos:rescue` | `gos rescue` | Lista/recupera stashes acumulados de updates falhos |
-| `npm run sync:ides` | — | Regenera apenas os IDE adapters (`.claude/`, `.qwen/`, `.gemini/`, `.cursor/`, `.agents/`) |
-| `npm run check:ides` | — | Valida que adapters estão consistentes com `.gos/skills/registry.json` |
+Você digita **apenas dois** slash commands. Todo o resto é roteado internamente.
 
-## Atualizar o ganbatte-os
+| Slash command | Quando usar |
+|---------------|-------------|
+| `/gos:agents:gos-master` | Ponto de entrada padrão. Descreva o que quer (criar tela, auditar segurança, refatorar, montar squad) e o master decide as skills/agentes/squads e executa. |
+| `/gos:agents:ux-design-expert` | Design de interface, tokens e design systems. |
 
-Existem **três níveis distintos** de versão. Saiba qual atualizar antes de rodar qualquer comando.
+> As 34 skills e os 11 agentes **não** são digitados como comando. O `gos-master` os invoca por você a partir da sua intenção. Dentro do chat, você guia o fluxo com comandos de asterisco (ex.: `*plan`, `*security-review`) que o master reconhece.
 
-### Descobrir em que cenário você está
+### O que o gos-master aciona por você
 
-```bash
-npm run gos:version
-# imprime: versão local + modo (framework workspace | projeto consumidor)
-```
+- **Design → código** — `design-to-code`, `figma-implement-design`, `figma-make-analyzer`, `interface-design`, `ui-guardrails` (Figma/screenshot → React/Next.js fiel).
+- **Frontend/React** — `frontend-dev`, `react-best-practices`, `react-doctor`, `component-dedup`.
+- **Pipeline de planos** — `plan-blueprint`, `plan-to-tasks`, `execute-plan`, `validate-plan`, `progress-tracker`, `stack-profiler` (ver abaixo).
+- **Qualidade** — `security-review`, `perf-review`, `simplify-review`.
+- **Texto/produto** — `humanizer`, `idea-intake`, `prd-from-intake`, `adr-tech-decisions`.
 
-| Modo detectado | Significa | Como atualizar |
-|----------------|-----------|----------------|
-| `framework workspace` | Você clonou/forkou o repo `g-os` para contribuir | `npm run gos:update` |
-| `projeto consumidor` | Seu projeto usa o G-OS (rodou `gos install` aqui) | `gos install --force` |
-| (CLI global) | O comando `gos` instalado via `npm install -g` | `npm install -g ganbatte-os@latest` |
+Catálogo completo: `.gos/skills/registry.json`.
 
-### Nível 1 — CLI global (`gos`)
+## Pipeline de planos (o fluxo de dev)
 
-```bash
-# Versão atual instalada vs publicada no registry:
-npm list -g ganbatte-os
-npm view ganbatte-os version
+Toda tela vira **um plano**. A stack de `docs/stack.md` é contrato — mudança de stack exige ADR. O trabalho é dividido em três etapas com **modelo por etapa** (configurável em `.gos-local/models.json`):
 
-# Atualizar:
-npm install -g ganbatte-os@latest
-```
-
-### Nível 2 — Projeto consumidor
+- **plan** (Senior) planeja → **execute** (Junior) implementa → **validate** (Senior) audita e corrige gaps.
 
-Seu projeto NÃO é fork do G-OS, mas usa o framework via `gos install`. O `.gos/` mora dentro do seu repo.
-
-```bash
-# Pré-checagem (uma vez):
-git remote -v
-# Se houver "upstream" apontando para g-os.git, REMOVA: 
-#   git remote remove upstream
-# (essa configuração só faz sentido em fork do framework)
-
-# Atualizar o framework dentro do seu projeto:
-gos install --force
-# Sobrescreve .gos/ com a última versão do pacote ganbatte-os global,
-# preservando seus arquivos (packages/, docs/, .gos-local/).
 ```
-
-> [!WARNING]
-> NÃO use `npm run gos:update` em projeto consumidor. O CLI agora detecta esse cenário e aborta com instruções, mas em versões antigas ele tentava `git fetch upstream main` e quebrava de forma confusa.
-
-### Nível 3 — Framework workspace (fork/clone do g-os)
-
-Você está contribuindo com o próprio framework.
-
-```bash
-# Pré-checagem (sempre antes de update):
-npm run gos:doctor
-# Valida 42+ pontos. Aborta se upstream estiver com URL quebrada
-# ou se houver stashes acumulados de updates anteriores falhos.
-
-# Ver quantos commits faltam:
-npm run gos:version
-
-# Aplicar (lê dev branch do .gos/config.json#defaultBranches.development):
-npm run gos:update
-```
-
-`gos:update` agora é **fail-safe**:
-
-1. Bloqueia se modo for `consumer`
-2. Valida `upstream` reachable (`git ls-remote`) ANTES de stashar
-3. Lê branch de desenvolvimento do `.gos/config.json` (não hardcoded)
-4. Faz fetch primeiro; se nada mudou, sai sem stash
-5. Stash recebe label timestamped único
-6. Auto-resolve conflitos em arquivos do framework (`frameworkManaged` no manifest); aborta em conflitos do usuário
-
-Override de branch (debug):
-
-```bash
-GOS_UPSTREAM_BRANCH=beta npm run gos:update
-```
-
-#### Caso especial: "histórias não relacionadas"
-
-Workspaces criados via `gos install` no passado podem ter `.git` próprio sem ancestor comum com o repo do framework. Nesse caso o merge falha com `fatal: refusing to merge unrelated histories`. O CLI detecta e instrui:
-
-```bash
-npm run gos:update -- --allow-unrelated
+*stack refresh            # mapeia a stack do projeto (uma vez, ou quando mudar)
+*plan <tela|figma-url>    # cria plan.md + context.md + spec.md + tasks/ (com critérios de aceite)
+*execute-plan PLAN-NNN    # implementa task-a-task, com visual gate e loop de correção
+*validate-plan PLAN-NNN   # audita, corrige gaps, roda segurança + performance + doc-sync
+*progress show            # estado atual (pendente → em-andamento → validacao → concluido)
 ```
 
-Isso une as duas histórias num commit de merge único. Faça uma vez; depois disso updates normais funcionam.
+Cada task carrega critérios de aceite verificáveis. No `execute-plan`, um critério que passa segue adiante; inconclusivo vira bypass com alerta; não atendido entra em loop de correção até passar. O `validate-plan` fecha o plano só depois de segurança/performance/documentação sincronizadas.
 
-#### Caso especial: untracked files que conflitam com o merge
+Auditorias sob demanda, a qualquer momento:
 
-Se você tem arquivos não-versionados em paths que o framework gera (`.claude/`, `.qwen/`, `.gemini/`, `.cursor/`, `.agents/`, etc), o git recusa o merge para evitar perda. O CLI detecta e oferece:
-
-```bash
-npm run gos:update -- --clobber-untracked
 ```
-
-Isso renomeia os arquivos conflitantes para `.bak.<timestamp>` antes do merge. Como esses paths são **sempre regenerados** por `npm run sync:ides`, o backup é só por garantia — você pode deletar depois.
-
-Combinar com `--allow-unrelated` quando ambos os casos ocorrerem (típico de workspaces antigos):
-
-```bash
-npm run gos:update -- --allow-unrelated --clobber-untracked
+*security-review    # RLS, authz, secrets, injection (Supabase/D1)
+*perf-review        # cache, filas, N+1, paginação, over-fetch
+*simplify-review    # anti-over-engineering (remove o que não precisa existir)
 ```
 
-Alternativa segura (não toca seu git, apenas atualiza `.gos/`):
+Playbook end-to-end: [`.gos/playbooks/plan-creation-playbook.md`](./.gos/playbooks/plan-creation-playbook.md).
 
-```bash
-gos install --force
-```
+## Comandos do workspace
 
-### Resgate de stashes presos
+| Comando | O que faz |
+|---------|-----------|
+| `gos init` | Setup pós-clone: configura `.gos-local/` e gera os IDE adapters |
+| `gos doctor` | Health-check (63 checks: skills, agentes, adapters, upstream) |
+| `gos version` | Versão instalada e modo do workspace |
+| `npm run sync:ides` | Regenera os IDE adapters após mudar skills/agentes |
+| `npm run check:ides` | Valida os adapters contra `.gos/skills/registry.json` |
 
-Se você teve falhas anteriores que deixaram stashes:
+## Estrutura do workspace
 
-```bash
-npm run gos:rescue                          # lista todos com stat
-npm run gos:rescue -- --pop-latest          # aplica o mais recente
-npm run gos:rescue -- --drop-all            # remove todos (após revisão)
+```text
+├── .gos/          # Core do framework (agents, skills, scripts) — somente leitura
+├── .gos-local/    # Config local: models.json, plan-paths.json, logs (ignorado no git)
+├── packages/      # Seu código-fonte vive aqui
+├── AGENTS.md      # Entrypoint de agentes
+├── CLAUDE.md      # Instruções para Claude Code
+└── GEMINI.md      # Instruções para Google Gemini
 ```
 
-### Resumo (qual comando para qual cenário)
+## Atualizar o framework
 
 | Cenário | Comando |
 |---------|---------|
-| Atualizar CLI `gos` global | `npm install -g ganbatte-os@latest` |
-| Atualizar G-OS num projeto consumidor | `gos install --force` |
-| Atualizar G-OS num fork/clone do repo | `npm run gos:update` |
-| Stashes presos de updates falhos | `npm run gos:rescue` |
-| Saber em qual cenário você está | `npm run gos:version` |
-| Validar tudo de uma vez | `npm run gos:doctor` |
-
-> [!NOTE]
-> A pasta `.agent/` que pode aparecer na raiz do workspace e criada pela IDE Google Antigravity / Gemini Code Assist — nao faz parte do setup padrao do ganbatte-os.
+| CLI `gos` global | `npm install -g ganbatte-os@latest` |
+| Framework num projeto consumidor | `gos install --force` |
+| Fork/clone do repo `g-os` | `npm run gos:update` |
+| Saber em qual cenário você está | `gos version` |
+| Validar tudo | `gos doctor` |
 
-## Estrutura do Workspace
-
-O `ganbatte-os` utiliza uma estrutura **encapsulada** para manter seu projeto limpo e organizado:
-
-```text
-├── .gos/                # Core do Framework (Somente leitura para usuários)
-│   ├── agents/          # Perfis e instruções dos agentes IA
-│   ├── skills/          # Catálogo de ferramentas (ex: design-to-code)
-│   ├── scripts/         # Engine do CLI e integração de IDEs
-│   └── prompts/         # Prompts canônicos para os agentes
-├── .gos-local/          # Dados locais (logs, queues, worktrees) - ignorado no git
-├── packages/            # Seu código-fonte e projetos vivem aqui
-├── AGENTS.md            # Entrypoint de agentes para o framework
-├── CLAUDE.md            # Instruções específicas para Claude Code
-└── GEMINI.md            # Instruções específicas para Google Gemini
-```
-
-## Funcionalidades Principais
-
-- **Design-to-Code**: Pipeline automatizado para converter frames do Figma em componentes React/Next.js de alta fidelidade.
-- **Pipeline de Planos**: Plano por tela com `spec.md`, tasks com critérios de aceite e loop de correção automática (Opus planeja, modelo barato executa, Opus valida).
-- **Auditoria de Segurança e Performance**: Verificação sistemática de vulnerabilidades (RLS, authz, secrets) e otimização (cache, filas, N+1, paginação) em Supabase e D1.
-- **Multi-IDE Multi-Tenant**: Configurações automáticas para as melhores ferramentas de IA do mercado.
-
-## Agentes Disponíveis
-
-| Agent | Slash Command | Foco |
-|-------|--------------|------|
-| **gos-master** | `/gos:agents:gos-master` | Orquestrador master — routing, skills, squads, workflows |
-| **architect** | `/gos:agents:architect` | Stack, padroes tecnicos, revisoes de arquitetura |
-| **dev** | `/gos:agents:dev` | Implementacao de features, hooks, refinamentos |
-| **devops** | `/gos:agents:devops` | Git, branches, CI/CD, automacoes de entrega |
-| **po** | `/gos:agents:po` | Backlog, scope, priorizacao |
-| **qa** | `/gos:agents:qa` | Testes, quality gates, revisao de codigo |
-| **sm** | `/gos:agents:sm` | Sprint, planning, sync com stakeholders |
-| **squad-creator** | `/gos:agents:squad-creator` | Orquestracao de times multi-agentes |
-| **ux-design-expert** | `/gos:agents:ux-design-expert` | Design de interfaces, tokens, design systems |
-
-## Skills Disponiveis
-
-| Skill | Slash Command | Funcao |
-|-------|--------------|--------|
-| **design-to-code** | `/gos:skills:design-to-code` | Converte Figma/screenshot em componentes React |
-| **figma-implement-design** | `/gos:skills:figma-implement-design` | Implementa design Figma com fidelidade 1:1 |
-| **figma-make-analyzer** | `/gos:skills:figma-make-analyzer` | Analisa output do Figma Make |
-| **make-code-triage** | `/gos:skills:make-code-triage` | Classifica codigo do Figma Make por categoria |
-| **make-version-diff** | `/gos:skills:make-version-diff` | Compara versoes de output Figma Make |
-| **component-dedup** | `/gos:skills:component-dedup` | Detecta componentes duplicados |
-| **frontend-dev** | `/gos:skills:frontend-dev` | Build componentes, pages, hooks (React/Next.js) |
-| **interface-design** | `/gos:skills:interface-design` | Design de interface com metodologia intent-first |
-| **react-best-practices** | `/gos:skills:react-best-practices` | Otimizacao de performance React/Next.js |
-| **react-doctor** | `/gos:skills:react-doctor` | Diagnostico de saude de componentes React |
-| **plan-to-tasks** | `/gos:skills:plan-to-tasks` | Converte plano em tasks acionaveis |
-| **agent-teams** | `/gos:skills:agent-teams` | Coordena multiplos agentes em time |
-| **git-ssh-setup** | `/gos:skills:git-ssh-setup` | Configura identidade SSH para o workspace |
-| **humanizer** | `/gos:skills:humanizer` | Remove padroes de IA do texto (two-pass audit + soul injection) |
-| **security-review** | `/gos:skills:security-review` | Auditoria de seguranca (RLS, authz, secrets, injection) |
-| **perf-review** | `/gos:skills:perf-review` | Auditoria de performance (cache, filas, N+1, paginacao) |
-| **stack-profiler** | `/gos:skills:stack-profiler` | Mantem `docs/stack.md` como stack-of-record canonica do projeto |
-| **plan-blueprint** | `/gos:skills:plan-blueprint` | Cria plano por tela (1 tela = 1 plano) seguindo a stack |
-| **progress-tracker** | `/gos:skills:progress-tracker` | Memoria L1 (`progress.txt`) + state machine de status |
-
-## Plan Pipeline (stack-aware)
-
-Pipeline padronizado para criacao de planos por tela. **Toda tela = 1 plano**. Toda execucao gera plano + tasks + contexto, com status auditavel e contrato de stack.
-
-### Fluxo
-
-```
-*stack refresh   →   docs/stack.md (uma vez por workspace, ou quando stack mudar)
-*plan <tela>     →   docs/plans/PLAN-NNN-<slug>/{plan.md, tasks/, context.md} + progress.txt
-*progress ...    →   transicoes pendente → em-andamento → validacao → concluido
-```
+> `gos:update` é fail-safe: só roda em fork/clone, valida `upstream` antes de mexer, e auto-resolve conflitos em arquivos do framework. Se travar (stashes, históricos não relacionados), `gos rescue` recupera. Num **projeto consumidor**, use sempre `gos install --force` — nunca `gos:update`.
 
-| Comando | Skill | Funcao |
-|---------|-------|--------|
-| `*stack [refresh\|show\|drift]` | `stack-profiler` | Mantem `docs/stack.md` (canonico) e `.gos-local/stack.lock.json` |
-| `*plan <tela\|figma-url>` | `plan-blueprint` | Cria plano + dispara `plan-to-tasks` + atualiza `progress.txt` |
-| `*progress [show\|set\|status]` | `progress-tracker` | Memoria L1 e state machine |
+## Documentação
 
-### Regras invioiaveis
-
-- **Stack como contrato** — toda decisao tecnica respeita `docs/stack.md`. Mudanca de stack exige ADR e flag `--allow-arch-change`.
-- **Paths via config** — nada hardcoded. Tudo resolvido via `.gos-local/plan-paths.json` (incluindo `knowledge_sources` como Postman, regras-de-negocio, ADRs).
-- **State machine dura** — `concluido` somente apos validacao humana.
-- **`progress.txt` e L1** — denso, otimizado para LLM, atualizado em todo passo.
-
-### Configuracao por workspace
-
-`.gos-local/plan-paths.json` define onde cada projeto guarda seus artefatos. Cada projeto/dev pode organizar diferente.
-
-**Inicializar com defaults** (helper):
-
-```bash
-node .gos/scripts/tools/plan-paths.js init     # cria .gos-local/plan-paths.json se nao existir
-node .gos/scripts/tools/plan-paths.js show     # imprime config atual
-node .gos/scripts/tools/plan-paths.js get planos   # imprime path resolvido para "planos"
-```
-
-**Exemplo de config** (caso real do `packages/fractus`):
-
-```json
-{
-  "schema": "gos.plan-paths.v1",
-  "dirs": {
-    "projeto":            "src/",
-    "storybook":          ".referencia-storybook/",
-    "design_system_doc":  ".referencia-storybook/docs/DESIGN_SYSTEM_REFERENCE.md",
-    "components":         ".referencia-storybook/components/",
-    "stories":            ".referencia-storybook/stories/",
-    "planos":             "docs/plans/",
-    "tasks":              "docs/plans/{plan}/tasks/",
-    "contexto":           "docs/plans/{plan}/context.md",
-    "progress":           "progress.txt",
-    "stack":              "docs/stack.md",
-    "adr":                "docs/adr/",
-    "postman":            "docs/postman/",
-    "regras_negocio":     "docs/regras-de-negocio/"
-  },
-  "knowledge_sources": [
-    { "kind": "postman",        "path": "docs/postman/",            "required": false },
-    { "kind": "business-rules", "path": "docs/regras-de-negocio/",  "required": false },
-    { "kind": "adr",            "path": "docs/adr/",                "required": false },
-    { "kind": "design-system",  "path": ".referencia-storybook/docs/DESIGN_SYSTEM_REFERENCE.md", "required": true }
-  ],
-  "naming": { "plan_prefix": "PLAN", "task_prefix": "T", "seq_padding": 3 },
-  "figma":  { "mcp_enabled": true, "default_file_url": null }
-}
-```
-
-Helpers em `.gos/scripts/tools/`:
-- `plan-paths.js` — resolve caminhos do projeto-cliente
-- `plan-status.js` — valida transicoes de status (state machine)
-- `stack-scan.js` — infere stack lendo `package.json`, configs e `knowledge_sources`
-
-### Exemplos de uso (end-to-end)
-
-Todos os comandos abaixo sao invocados via slash command no `gos-master` (Claude Code, Gemini, Cursor, etc).
-
-#### 1. Bootstrap do workspace (uma vez por projeto)
-
-```bash
-/gos:agents:gos-master
-```
-
-Em seguida, no chat:
-
-```
-*stack refresh
-```
-
-Saida esperada:
-
-```
-## Stack profilada — packages/fractus
-
-- Framework: Next.js 15 (App Router)
-- DB: Supabase (read-only)
-- Design System: .referencia-storybook
-- Knowledge sources: 4 (postman, business-rules, adr, design-system)
-
-stack.md: docs/stack.md
-lock:     .gos-local/stack.lock.json
-hashes:   12 arquivos
-```
-
-Verifique sempre que algo na stack mudar (lib, framework, ORM):
-
-```
-*stack drift
-```
-
-#### 2. Criar plano para uma tela
-
-A partir de URL Figma (autodetecta e usa Figma MCP):
-
-```
-*plan https://www.figma.com/design/kXd8uP6dgeSuQypFnPmuQP/FRACTUS?node-id=9140-25387
-```
-
-A partir de descricao livre:
-
-```
-*plan tela de checkout com formulario de pagamento e resumo do pedido
-```
-
-Saida:
-
-```
-## Plano criado: PLAN-042-checkout
-
-- plan.md:    docs/plans/PLAN-042-checkout/plan.md
-- context.md: docs/plans/PLAN-042-checkout/context.md
-- tasks/:     docs/plans/PLAN-042-checkout/tasks/ (5 tasks: T-042-001 ... T-042-005)
-- progress:   atualizado (status=pendente)
-- stack_ref:  docs/stack.md@a1b2c3d
-
-Proximos passos:
-1. Revisar plan.md e checklist de aceite
-2. *progress status T-042-001 em-andamento
-3. Executar
-```
-
-Telas complexas (modal + drawer + sub-rotas) sao **subdivididas automaticamente** em planos filhos:
-
-```
-PLAN-042-checkout            (pai, checklist consolidado)
-├── PLAN-042.1-payment-modal (filho)
-├── PLAN-042.2-summary-drawer
-└── PLAN-042.3-confirm-page
-```
-
-#### 3. Executar tasks
-
-```
-*progress show                              # mostra progress.txt atual
-*progress status T-042-001 em-andamento     # iniciar task
-# ... dev implementa ...
-*progress status T-042-001 validacao        # task pronta para revisao (commit preparado, nao pushado)
-```
-
-Tentar pular validacao falha:
-
-```
-*progress status T-042-001 concluido
-> erro: transicao invalida: em-andamento → concluido
-> use --rollback para voltar para pendente
-```
-
-#### 4. Fechar o plano
-
-Quando todas as tasks estao em `validacao` e o checklist do plano esta completo:
-
-```
-*progress status PLAN-042-checkout validacao    # validacao humana + QA
-*progress status PLAN-042-checkout concluido    # SOMENTE apos aprovacao
-```
-
-`progress-tracker compact` periodicamente reescreve `progress.txt` removendo tasks `concluido` antigas para manter o arquivo < 4kB (otimizado para LLM).
-
-#### 5. Mudanca de arquitetura (excecao)
-
-Se a tela exigir alteracao da stack (nova lib, novo padrao de fetching, schema novo):
-
-```
-*plan tela-relatorios --allow-arch-change
-```
-
-Isso forca a Fase 2 propositiva e gera um ADR em `docs/adr/ADR-NNNN-<slug>.md` antes de prosseguir. O plano resultante referencia o ADR no frontmatter (`arch_change: true`).
-
-### Estrutura de saida
-
-Apos `*plan tela-checkout`:
-
-```
-docs/plans/PLAN-042-checkout/
-├── plan.md          # frontmatter (id, tela, figma_url, status, stack_ref) + secoes fixas
-├── context.md       # denso, indice de arquivos, decisoes, riscos
-└── tasks/
-    ├── T-042-001-criar-rota-checkout.md
-    ├── T-042-002-fetching-supabase.md
-    ├── T-042-003-form-pagamento.md
-    ├── T-042-004-resumo-pedido.md
-    └── T-042-005-estados-erro-loading.md
-```
-
-`progress.txt` na raiz do projeto fica:
-
-```
-# progress.l1
-ts=2026-05-01T18:22:00-03:00
-project=fractus
-plan_active=docs/plans/PLAN-042-checkout/plan.md
-tasks_dir=docs/plans/PLAN-042-checkout/tasks/
-context=docs/plans/PLAN-042-checkout/context.md
-stack_ref=docs/stack.md@a1b2c3d
-status=em-andamento
-
-last_done=T-042-002 fetching-supabase
-current=T-042-003 form-pagamento
-next=T-042-004 resumo-pedido
-
-blockers=
-notes=fetch usa server component em app/checkout/page.tsx
-```
-
-### Playbook completo
-
-[`.gos/playbooks/plan-creation-playbook.md`](./.gos/playbooks/plan-creation-playbook.md) — documenta o fluxo end-to-end com troubleshooting.
-
-## Documentacao
-
-| Documento | Descricao |
+| Documento | Descrição |
 |-----------|-----------|
-| [AGENTS.md](./AGENTS.md) | Agentes, skills e slash commands disponiveis |
-| [CLAUDE.md](./CLAUDE.md) | Instrucoes para Claude Code |
-| [GEMINI.md](./GEMINI.md) | Instrucoes para Google Gemini |
-| [docs/README.md](./docs/README.md) | Indice de documentacao |
+| [AGENTS.md](./AGENTS.md) | Agentes e entrypoints |
+| [CLAUDE.md](./CLAUDE.md) | Instruções para Claude Code |
+| [GEMINI.md](./GEMINI.md) | Instruções para Google Gemini |
 
-**Fonte canonica dos agents**: `.gos/agents/profiles/`
-**Fonte canonica das skills**: `.gos/skills/`
-**Registry de skills**: `.gos/skills/registry.json`
+Fonte canônica: agentes em `.gos/agents/profiles/`, skills em `.gos/skills/` (registry em `.gos/skills/registry.json`).
 
 ## Licença
 
-Este é um projeto interno da **Ganbatte**. Distribuído sob licença [MIT](LICENSE).
+Distribuído sob licença [MIT](LICENSE).
 
 ---
-© 2026 Ganbatte. Todos os direitos reservados.
+
+© 2026 Douglas Oliveira · [github.com/imdouglasoliveira](https://github.com/imdouglasoliveira)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ganbatte-os",
-  "version": "0.2.42",
+  "version": "0.2.44",
   "description": "Framework operacional de desenvolvimento: prototipacao, design-to-code, implementacao, otimizacao e seguranca.",
   "bin": {
     "gos": ".gos/scripts/cli/gos-cli.js"