ganbatte-os 0.2.30 → 0.2.32

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

@@ -81,6 +81,8 @@ persona:
     - Follow Conventional Commits for all git operations
     - Treat Figma Make output as triage material, not production code
     - "Comprehension Gate: Before delegating to any agent, skill, or workflow, first understand what needs to be done — read relevant code, docs, and state; document findings; only then route"
+    - "Stack como contrato: toda decisão técnica respeita docs/stack.md; alterações de stack exigem ADR explícita e flag --allow-arch-change"
+    - "Paths via config: nada hardcoded — todos os caminhos do projeto-cliente vêm de .gos-local/plan-paths.json"
 
 # ─── COMPREHENSION GATE ──────────────────────────────────────
 # Applies before any delegation to agent, skill, or workflow.
@@ -90,6 +92,8 @@ comprehension_gate:
   trigger: "Before any delegation to agent, skill, or workflow"
   protocol:
     step_0_scan: "Read relevant files, docs, recent commits related to the request"
+    step_0_5_stack: "If routing to planning/implementation: load docs/stack.md (path from .gos-local/plan-paths.json). If absent, abort and dispatch stack-profiler refresh."
+    step_0_6_progress: "If progress.txt exists at the configured path: read it for active plan/task context (memória L1)."
     step_1_document: "State what exists (current state, patterns, constraints) in factual terms"
     step_2_assess: "Determine which agent/skill/workflow is appropriate based on evidence, not assumption"
     step_3_delegate: "Route with context summary so the target has full picture"
@@ -186,6 +190,22 @@ routing_matrix:
     triggers: [architecture, system design, technical design, ADR]
     target: agent:architect
 
+  stack_profile:
+    triggers: [stack, stack profile, refresh stack, stack drift, stack-of-record]
+    target: skill:stack-profiler
+    notes: Run on first setup or whenever stack changes (libs, framework, ORM, auth, hosting)
+
+  plan_creation:
+    triggers: [plan, plano, screen plan, tela, criar plano, blueprint, plano de tela]
+    target: skill:plan-blueprint
+    pre_action: Validate docs/stack.md exists; if not, dispatch stack-profiler first
+    notes: 1 tela = 1 plano. Subdivide automaticamente quando há múltiplas seções autônomas
+
+  progress_tracking:
+    triggers: [progress, status, progress.txt, memoria curta, l1]
+    target: skill:progress-tracker
+    notes: State machine pendente → em-andamento → validacao → concluido
+
   product_decisions:
     triggers: [PRD, requirements, product decision, scope, feature priority]
     target: agent:po
@@ -262,6 +282,17 @@ commands:
     args: "[plan|status|sync]"
     description: Sprint operations via ClickUp integration
 
+  # Plan pipeline (stack-aware)
+  - name: stack
+    args: "[refresh|show|drift]"
+    description: Mantém docs/stack.md (stack-of-record do projeto)
+  - name: plan
+    args: "<tela|figma-url|descricao> [--from-figma-mcp] [--allow-arch-change]"
+    description: Cria plano por tela (plan + tasks + context + progress.txt)
+  - name: progress
+    args: "[init|show|set <plan>|status <task> <novo-status>|compact|read]"
+    description: Gerencia progress.txt (memória L1) e state machine de status
+
   # Quality
   - name: check
     args: "[tsc|tests|all]"
@@ -297,7 +328,7 @@ available_squads:
   - name: git-operations
     purpose: SSH setup, quality gate, safe commit+push
 
-# ─── AVAILABLE SKILLS (15) ────────────────────────────────────
+# ─── AVAILABLE SKILLS (18) ────────────────────────────────────
 available_skills:
   - design-to-code
   - figma-implement-design
@@ -314,6 +345,9 @@ available_skills:
   - plan-to-tasks
   - agent-teams
   - git-ssh-setup
+  - stack-profiler
+  - plan-blueprint
+  - progress-tracker
 
 # ─── PLAYBOOKS ────────────────────────────────────────────────
 available_playbooks:
@@ -321,6 +355,7 @@ available_playbooks:
   - sprint-planner-playbook.md
   - squad-pipeline-runner.md
   - ssh-multi-account-setup.md
+  - plan-creation-playbook.md
 
 # ─── SCRIPTS & TOOLS ─────────────────────────────────────────
 scripts:
@@ -336,6 +371,15 @@ scripts:
     - name: clickup.js
       path: scripts/tools/clickup.js
       purpose: ClickUp API v2 CLI for sprint/task management
+    - name: plan-paths.js
+      path: scripts/tools/plan-paths.js
+      purpose: Resolve paths do projeto-cliente (.gos-local/plan-paths.json)
+    - name: plan-status.js
+      path: scripts/tools/plan-status.js
+      purpose: State machine de status (pendente → em-andamento → validacao → concluido)
+    - name: stack-scan.js
+      path: scripts/tools/stack-scan.js
+      purpose: Inferir stack do projeto-cliente (auxilia stack-profiler)
 
 # ─── SECURITY ─────────────────────────────────────────────────
 security:
@@ -402,6 +446,12 @@ security:
 - `*sprint status` - Check sprint progress
 - `*sprint sync` - Sync with ClickUp
 
+**Plan pipeline (stack-aware):**
+
+- `*stack [refresh|show|drift]` - Mantém docs/stack.md
+- `*plan <tela|figma-url|descrição>` - Cria plano por tela
+- `*progress [show|set|status|compact]` - Gerencia progress.txt (L1)
+
 **Framework:**
 
 - `*doctor` - Health check (gos-cli.js doctor)

package/.gos/playbooks/plan-creation-playbook.md

@@ -0,0 +1,122 @@
+# Playbook — Criação de planos por tela
+
+Pipeline determinístico do G-OS para transformar uma tela (Figma, descrição, screenshot) em `{plano + tasks + contexto + entrada-progress}` respeitando a stack-of-record do projeto.
+
+## Quando usar
+
+- Toda nova tela em projeto que consome o G-OS
+- Reescrita ou refatoração de tela existente
+- Cada tela = 1 plano (subdividido em filhos quando complexa)
+
+## Pré-requisitos do workspace
+
+1. `.gos-local/plan-paths.json` configurado (paths do projeto + `knowledge_sources`)
+2. `docs/stack.md` válido e sem drift (gerado por `stack-profiler`)
+3. `progress.txt` na raiz (criado automaticamente no primeiro `*plan`)
+
+## Fluxo end-to-end
+
+### 0. Bootstrap (uma vez por workspace)
+
+```
+*stack refresh
+```
+
+Lê configs do projeto + `knowledge_sources` (Postman, regras-de-negocio, ADRs, design system) e grava `docs/stack.md` + `.gos-local/stack.lock.json`.
+
+Se `plan-paths.json` ausente, a skill cria interativamente.
+
+### 1. Verificar drift antes de planejar
+
+```
+*stack drift
+```
+
+Se houver drift, decidir entre:
+- `*stack refresh` (atualizar stack.md, planos antigos ficam com stack_ref antigo — ok)
+- ignorar e prosseguir (apenas se a mudança não afeta a tela)
+
+### 2. Criar plano
+
+```
+*plan <tela|figma-url|descrição>
+```
+
+`plan-blueprint` executa:
+1. Fase 1 — Mapeamento Visual & Componentização
+2. Fase 2 — Aderência à Stack (sem redefinir arquitetura)
+3. Fase 3 — Plano de Execução
+
+Saídas:
+- `<dirs.planos>/PLAN-NNN-<slug>/plan.md`
+- `<dirs.planos>/PLAN-NNN-<slug>/context.md`
+- `<dirs.planos>/PLAN-NNN-<slug>/tasks/T-NNN-NN-*.md`
+- `progress.txt` atualizado com plano ativo
+
+### 3. Revisar e aceitar
+
+Humano revisa:
+- componentes mapeados x ausentes
+- aderência à stack (especialmente endpoints/regras)
+- checklist de aceite
+
+Se aprovado, prosseguir. Caso contrário: ajustar manualmente ou rerodar `*plan` com refinamento.
+
+### 4. Executar tasks
+
+Para cada task, dev (humano ou LLM):
+
+```
+*progress status T-NNN-NN em-andamento
+```
+
+Implementa, commita localmente (sem push), atualiza:
+
+```
+*progress status T-NNN-NN validacao
+```
+
+### 5. Validação
+
+Quando todas as tasks do plano estiverem `validacao` e o checklist do plano estiver completo:
+
+```
+*progress status PLAN-NNN-<slug> validacao
+```
+
+Validação humana + QA. Se aprovado:
+
+```
+*progress status PLAN-NNN-<slug> concluido
+```
+
+(Status `concluido` SOMENTE após validação. Antes disso, qualquer task/plano fica em `validacao`.)
+
+### 6. Commit & resumo
+
+`devops` skill prepara commit (não pusha). Resumo do que foi feito é gerado a partir das tasks `concluido` desde o último commit.
+
+## Regras invioláveis
+
+1. **Stack como contrato** — toda decisão respeita `stack.md`. Mudança de stack exige ADR e flag `--allow-arch-change`.
+2. **Read-only respeitado** — se `stack.md` declara backend read-only, plano nunca propõe migration.
+3. **State machine dura** — `concluido` só após validação humana.
+4. **Paths via config** — nada hardcoded; tudo de `plan-paths.json`.
+5. **`progress.txt` é L1** — denso, otimizado para LLM, sempre atualizado.
+
+## Troubleshooting
+
+| Sintoma | Causa provável | Ação |
+|---------|----------------|------|
+| `*plan` aborta com "stack.md ausente" | Bootstrap não rodou | `*stack refresh` |
+| Drift detectado constantemente | `package.json` muda muito | Aceitar drift e rerunar refresh por sprint |
+| Task `concluido` sem passar por `validacao` | Tentativa de bypass | State machine bloqueia — usar `--rollback` se for engano |
+| Plano referencia endpoint que não existe | Postman desatualizado | Atualizar coleção, `*stack refresh`, replanejar |
+
+## Skills relacionadas
+
+- `stack-profiler` — produz/mantém `stack.md`
+- `plan-blueprint` — cria plano por tela
+- `plan-to-tasks` — decompõe plano em tasks (chamada automaticamente)
+- `progress-tracker` — gerencia `progress.txt`
+- `clickup` — sync opcional para tracking externo (não obrigatório)

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

@@ -0,0 +1,144 @@
+---
+name: plan-blueprint
+description: Cria um plano padronizado para uma tela (1 plano = 1 tela) seguindo a stack-of-record do projeto. Produz {plano, tasks, contexto, entrada-progress.txt} em três fases (Mapeamento → Aderência à stack → Execução). Pré-requisito duro: docs/stack.md existir. Subdivide automaticamente telas com seções autônomas múltiplas.
+argument-hint: "<tela|figma-url|descrição> [--from-figma-mcp] [--allow-arch-change]"
+allowedTools: [Read, Glob, Grep, Bash, Write, Edit, Agent, AskUserQuestion]
+sourceDocs:
+  - templates/planTemplate.md
+  - templates/contextTemplate.md
+  - playbooks/plan-creation-playbook.md
+use-when:
+  - criar plano de implementação para uma tela específica
+  - input começa com URL Figma (auto-detectado)
+  - planejar feature de UI com componentes do design system
+do-not-use-for:
+  - planejamento de sprint inteira (use sprint-planner)
+  - decomposição de plano pronto em tasks (use plan-to-tasks)
+  - alterações que mudam stack (gerar ADR primeiro, depois rodar com --allow-arch-change)
+metadata:
+  category: planning
+---
+
+Você está executando como **Tech Lead Frontend / Arquiteto Sênior** via skill `plan-blueprint`.
+
+## Input
+
+$ARGUMENTS
+
+Auto-detecção de input:
+- URL `https://www.figma.com/...` → ativa modo Figma MCP
+- caminho de arquivo `.md`/`.png`/`.jpg` → modo descrição com referência visual
+- texto livre → modo descrição
+
+Flags:
+- `--from-figma-mcp` — força leitura via Figma MCP
+- `--allow-arch-change` — libera Fase 2 propositiva (gera ADR)
+
+## Pré-requisitos (gate)
+
+1. Resolver paths via `.gos-local/plan-paths.json` (criar se ausente).
+2. **Verificar `docs/stack.md` (caminho de `dirs.stack`)**:
+   - Se ausente: ABORTAR. Despachar `stack-profiler refresh` e instruir o usuário a re-executar.
+   - Se presente: ler integralmente. Verificar drift via `*stack drift` antes de prosseguir.
+3. Ler `progress.txt` se existir (memória L1).
+
+## Fase 1 — Mapeamento Visual & Componentização
+
+### 1.1 Carregar referências do design system
+
+Ler (paths via `plan-paths.json`):
+- `dirs.design_system_doc`
+- `dirs.components/` (inspecionar nomes e props)
+- `dirs.stories/` (entender padrões de uso)
+
+### 1.2 Analisar a tela
+
+Se Figma MCP ativo: invocar Figma MCP para extrair árvore de nodes.
+Caso contrário: trabalhar pela descrição/screenshot fornecido.
+
+### 1.3 Mapear componentes
+
+Produzir tabela:
+
+| Elemento (Figma/descrição) | Componente do DS | Variant | Props relevantes |
+|----------------------------|------------------|---------|-------------------|
+
+Listar **componentes ausentes** separadamente — sinalizar como bloqueio ou candidato a criação (vai virar task própria).
+
+## Fase 2 — Aderência à Stack
+
+**Modo padrão (sem `--allow-arch-change`)**: SOMENTE referenciar a stack já registrada em `stack.md`. Para cada dado/ação da tela, listar:
+
+- Endpoint/tabela/serviço já existente (consultando `knowledge_sources` — Postman, regras-de-negócio, schema)
+- Padrão de fetching a usar (do `stack.md`)
+- Server vs Client component (do `stack.md`)
+
+Saída desta fase é uma seção **"Aderência à Stack"** no plano — não redefine arquitetura.
+
+**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.
+
+## Fase 3 — Plano de Execução
+
+Para cada elemento mapeado:
+
+1. Estrutura de pastas/rotas (seguindo convenções de `stack.md`)
+2. Lógica de fetching (onde o data source é chamado)
+3. Montagem da view (composição dos componentes do DS)
+4. Estado e interatividade (client components estritamente onde necessário)
+
+## Subdivisão automática
+
+Se a análise identificar mais de 3 seções autônomas (modais, drawers, sub-rotas com fetching próprio), gerar **planos filhos** numerados:
+
+- Plano pai: `PLAN-NNN-<slug>` (visão geral + checklist consolidado)
+- Filhos: `PLAN-NNN.1-<slug>`, `PLAN-NNN.2-<slug>` (cada um com suas tasks)
+
+Frontmatter linka via `parent_plan` / `children_plans`.
+
+## Saída
+
+Para cada plano (incluindo filhos):
+
+1. `<dirs.planos>/PLAN-NNN-<slug>/plan.md` — gerado a partir de `templates/planTemplate.md`. Frontmatter inclui `stack_ref: <dirs.stack>@<sha-curto>` para travar a versão da stack.
+2. `<dirs.planos>/PLAN-NNN-<slug>/context.md` — gerado a partir de `templates/contextTemplate.md`. Denso, indexado.
+3. Disparar `plan-to-tasks` automaticamente apontando para o `plan.md` recém-criado → produz tasks em `<dirs.tasks>` (resolvido com `{plan}` substituído).
+4. Disparar `progress-tracker set-current` apontando o plano novo → atualiza `progress.txt`.
+
+Resumo final:
+
+```
+## 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)
+- progress:   atualizado (status=pendente)
+- stack_ref:  docs/stack.md@a1b2c3d
+
+Próximos passos:
+1. Revisar plan.md e checklist de aceite
+2. *progress status T-042-01 em-andamento
+3. Executar
+```
+
+## Regras críticas
+
+- **Reuso estrito**: priorizar componentes existentes. Componente novo só com justificativa no plano.
+- **Backend read-only respeitado**: se `stack.md` declara backend read-only, plano NUNCA propõe schema novo.
+- **Next.js App Router**: decisão server vs client é explícita por elemento.
+- **Sem prosa decorativa**: plano deve ser executável, denso, com critérios mensuráveis.
+
+## Model guidance
+
+| Escopo | Modelo |
+|--------|--------|
+| Tela simples (1 form, 1 listagem) | `sonnet` |
+| Tela complexa, subdivisão necessária | `opus` |
+| Replanejamento incremental | `sonnet` |
+
+## Instructions
+
+1. NUNCA prosseguir sem `stack.md` válido.
+2. Resolver TODOS os paths via `plan-paths.json`.
+3. Status inicial do plano e tasks: `pendente`.
+4. Não pushar nada — apenas escrever arquivos locais.

package/.gos/skills/plan-to-tasks/SKILL.md

@@ -23,9 +23,9 @@ $ARGUMENTS
 
 ### Phase 1 — Read & understand the input
 1. If `$ARGUMENTS` is a file path, read that file. If it's a description, work from the description.
-2. Read `./.G-OS/agents/tasks-writer.system.md` to internalize the DoD for tasks.
-3. Read `./.G-OS/templates/taskTemplate.md` to get the exact format.
-4. Read `./.G-OS/tasks/README.md` (if it exists) to understand the current task naming convention.
+2. Resolver paths via `.gos-local/plan-paths.json` (helper: `scripts/tools/plan-paths.js`). Se ausente, criar com defaults.
+3. Read `templates/taskTemplate.md` (canonical do framework) para o formato exato — superseda qualquer template legado em `.G-OS/templates/`.
+4. Se o input for um plano gerado por `plan-blueprint`, herdar `plan_id` do frontmatter para encadear `T-NNN-NN` corretamente.
 
 ### Phase 2 — Decompose into tasks
 Analyze the plan and extract:
@@ -41,15 +41,15 @@ Rules:
 
 ### Phase 3 — Generate task files
 
-For each task, create a file following the project docs convention:
+For each task, create a file following o caminho resolvido em `plan-paths.json`:
 
-**Primary location (per-project):** `docs/tasks/NN-name/TASK-NN-desc.md`
-Where `NN` matches the plan prefix and tasks use zero-padded sequence (01, 02, ...).
+**Primary location:** `<dirs.tasks>` com `{plan}` substituído pelo `plan_id` do plano (ex.: `docs/plans/PLAN-042-checkout/tasks/T-042-01-<slug>.md`).
 
-**Fallback (framework tasks):** `./.G-OS/tasks/TASK-<YYYYMM>-<seq>.md`
-Use only if `docs/tasks/` does not exist or for framework-internal tasks.
+**Fallback** (apenas se rodando sem `plan-paths.json` ou para tasks internas do framework): `./.gos/data/tasks/T-<YYYYMM>-<seq>.md`.
 
-Use this template (from `./.G-OS/templates/taskTemplate.md`):
+Naming: usar `naming.task_prefix` e `naming.seq_padding` do `plan-paths.json` (defaults: `T`, padding 3 → `T-042-001`).
+
+Use this template (from `templates/taskTemplate.md`):
 
 ```markdown
 ---

package/.gos/skills/progress-tracker/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: progress-tracker
+description: Gerencia progress.txt como memória L1 (curta, otimizada para LLM) na raiz do projeto-cliente. Suporta init, set-current, update-status (state machine), compact e read. Sempre consultado quando há dúvida sobre plano/task ativo.
+argument-hint: "[init|show|set <plan>|status <task> <novo-status>|compact|read]"
+allowedTools: [Read, Write, Edit, Bash]
+sourceDocs:
+  - templates/progressTemplate.txt
+  - playbooks/plan-creation-playbook.md
+use-when:
+  - inicializar progress.txt no workspace
+  - definir qual plano está ativo
+  - transicionar status de plano/task
+  - LLM com dúvida sobre o que está sendo feito
+  - compactar progress.txt removendo tasks concluídas antigas
+do-not-use-for:
+  - planejamento (plan-blueprint)
+  - decomposição (plan-to-tasks)
+  - leitura de stack (stack-profiler)
+metadata:
+  category: project-context
+---
+
+Você está executando a skill `progress-tracker`. Mantém a memória L1 do projeto.
+
+## Conceito
+
+`progress.txt` é a **memória de curta duração** que toda LLM consulta quando precisa saber:
+- qual plano está ativo
+- qual task está em execução
+- o que foi feito por último
+- o que vem a segur
+- bloqueios atuais
+
+Formato denso, sem prosa, otimizado para tokens. Inspirado em `caveman-main` e `sandeco-token`. Localização default: raiz do projeto-cliente (path resolvido em `dirs.progress` do `plan-paths.json`).
+
+## State machine
+
+```
+pendente → em-andamento → validacao → concluido
+```
+
+Transições válidas:
+- `pendente → em-andamento`: livre
+- `em-andamento → validacao`: requer commit preparado (não pushado)
+- `validacao → concluido`: requer aprovação humana
+- `* → pendente`: rollback (libera a transição via flag `--rollback`)
+
+Transições inválidas falham com mensagem do helper `scripts/tools/plan-status.js`.
+
+## Subcomandos
+
+### `init`
+
+Cria `progress.txt` se ausente, usando `templates/progressTemplate.txt`. Não sobrescreve se já existir.
+
+### `show` (default)
+
+Imprime `progress.txt`.
+
+### `set <plan-id>`
+
+Fixa o plano ativo. Ex.: `*progress set PLAN-042-checkout`. Atualiza:
+- `plan_active=<dirs.planos>/<plan-id>/plan.md`
+- `tasks_dir=<dirs.planos>/<plan-id>/tasks/`
+- `context=<dirs.planos>/<plan-id>/context.md`
+- `status=pendente` (se for primeira ativação)
+
+### `status <task-id> <novo-status>`
+
+Muda status de uma task. Valida via state machine. Atualiza `progress.txt` (`last_done`, `next`) e o frontmatter do task file. Se a task fechar o checklist do plano, sugere `*progress status <plan-id> validacao`.
+
+### `compact`
+
+Reescreve `progress.txt` removendo tasks `concluido` antigas (manter < 4kB). Mantém apenas:
+- plano ativo
+- últimas 3 tasks `concluido`
+- todas tasks `em-andamento`/`validacao`/`pendente` do plano ativo
+- bloqueios e notas curtas
+
+### `read`
+
+Mesmo que `show`. Disponível como verbo explícito para integração com `comprehension_gate` do gos-master.
+
+## Formato `progress.txt`
+
+```
+# progress.l1
+ts=2026-05-01T18:22:00-03:00
+project=<nome>
+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-03 montar-form-pagamento
+current=T-042-04 integrar-supabase-orders
+next=T-042-05 estado-erro-checkout
+
+blockers=
+notes=fetch usa server component em app/checkout/page.tsx
+```
+
+## Regras
+
+- Sempre resolver `dirs.progress` via `plan-paths.json` antes de ler/escrever.
+- Nunca remover bloqueios sem confirmação.
+- `compact` só remove `concluido` antigas — nunca toca `em-andamento`.
+- Toda alteração registra `ts` em ISO 8601.
+
+## Saída
+
+Após qualquer alteração, mostrar diff curto:
+
+```
+[progress] PLAN-042-checkout / T-042-03 → concluido
+last_done=T-042-03 montar-form-pagamento
+current=T-042-04 integrar-supabase-orders
+```
+
+## Instructions
+
+1. Skill silenciosa — não tagarela, devolve estado.
+2. State machine é dura — bloquear transições inválidas.
+3. Nunca apagar `progress.txt` sem `compact` explícito.

package/.gos/skills/registry.json

@@ -19,6 +19,9 @@
     { "slug": "git-ssh-setup", "path": "skills/git-ssh-setup/SKILL.md" },
     { "slug": "humanizer", "path": "skills/humanizer/SKILL.md" },
     { "slug": "weekly-update", "path": "skills/weekly-update/SKILL.md" },
-    { "slug": "slack-review", "path": "skills/slack-review/SKILL.md" }
+    { "slug": "slack-review", "path": "skills/slack-review/SKILL.md" },
+    { "slug": "stack-profiler", "path": "skills/stack-profiler/SKILL.md" },
+    { "slug": "plan-blueprint", "path": "skills/plan-blueprint/SKILL.md" },
+    { "slug": "progress-tracker", "path": "skills/progress-tracker/SKILL.md" }
   ]
 }

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

@@ -0,0 +1,138 @@
+---
+name: stack-profiler
+description: Produz e mantém docs/stack.md como fonte canônica da stack-of-record do projeto. Lê arquivos de configuração, design system, Postman, regras de negócio e ADRs (paths resolvidos via .gos-local/plan-paths.json). Usar antes de criar planos ou quando a stack do projeto mudou.
+argument-hint: "[refresh|show|drift]"
+allowedTools: [Read, Glob, Grep, Bash, Write, Edit, AskUserQuestion]
+sourceDocs:
+  - templates/stackTemplate.md
+  - playbooks/plan-creation-playbook.md
+use-when:
+  - primeiro setup do projeto no fluxo de planos do G-OS
+  - stack mudou (libs, framework, ORM, auth, hosting)
+  - drift detectado entre stack.md e arquivos-fonte
+  - antes de qualquer execução de plan-blueprint sem stack.md presente
+do-not-use-for:
+  - decisões pontuais de tela (use plan-blueprint)
+  - alteração de stack (gera ADR, não rerruna profiler cego)
+metadata:
+  category: project-context
+---
+
+Você está executando a skill `stack-profiler`. Ela define o contrato técnico do projeto que todas as demais skills do pipeline de planos respeitam.
+
+## Input
+
+$ARGUMENTS
+
+Subcomandos:
+- `refresh` (default) — varre fontes e (re)escreve `docs/stack.md`
+- `show` — imprime o `stack.md` atual
+- `drift` — compara hashes em `.gos-local/stack.lock.json` com arquivos-fonte; alerta se mudaram
+
+## Pré-requisitos
+
+1. Resolver paths via `.gos-local/plan-paths.json`. Se não existir, criar com defaults e perguntar apenas o que não puder inferir.
+2. Carregar template `templates/stackTemplate.md`.
+
+## Procedimento — `refresh`
+
+### Fase 1 — Ler fontes canônicas
+
+Ler (quando existirem, todos relativos à raiz do projeto-cliente):
+- `package.json`, `tsconfig*.json`
+- `next.config.*`, `vite.config.*`, `tailwind.config.*`, `postcss.config.*`
+- `prisma/schema.prisma`, `drizzle.config.*`, `supabase/`
+- `README.md`, `CLAUDE.md`
+- Cada `knowledge_sources[].path` declarado em `plan-paths.json`:
+  - `design-system` — extrair tokens, componentes-chave
+  - `postman` — listar coleções e endpoints expostos (extrair `name`, `request.method`, `request.url.raw`)
+  - `business-rules` — listar arquivos com títulos/escopos
+  - `adr` — listar ADRs ativas
+
+### Fase 2 — Inferir e perguntar
+
+Inferir automaticamente:
+- Framework principal e versão (`dependencies` em package.json)
+- Runtime (Node, Bun, Edge)
+- ORM efetivo (Prisma, Drizzle, Supabase client)
+- UI lib + design system
+- Hosting (vercel.json, netlify.toml, Dockerfile)
+
+Perguntar ao usuário (apenas o que não conseguir inferir, em uma única rodada):
+- Auth provider efetivo
+- Padrão preferido de fetching (server component, server action, client + SWR, etc.)
+- Backend é read-only para a aplicação (sem criar schema novo)?
+- Restrições explícitas (ex.: "não introduzir novas libs sem ADR")
+
+### Fase 3 — Gravar `stack.md`
+
+Caminho: o que estiver em `dirs.stack` do `plan-paths.json` (default `docs/stack.md`).
+
+Seções obrigatórias (ver `templates/stackTemplate.md`):
+1. Framework & runtime
+2. UI / Design System (com link para o doc canônico)
+3. Estado & dados
+4. Auth
+5. Backend / DB (incluir flag `read_only: true|false`)
+6. Padrões de fetching
+7. Convenções de pastas e rotas
+8. Fontes de conhecimento do projeto (lista cada `knowledge_source` com path resolvido + resumo)
+9. Restrições
+10. Links internos (docs, ADRs ativas)
+
+### Fase 4 — Atualizar lock
+
+Gravar `.gos-local/stack.lock.json`:
+
+```json
+{
+  "schema": "gos.stack-lock.v1",
+  "generated_at": "<iso>",
+  "stack_path": "<dirs.stack>",
+  "sources": [
+    { "path": "package.json", "sha256": "..." },
+    { "path": "docs/postman/Fractus.postman_collection.json", "sha256": "..." }
+  ]
+}
+```
+
+## Procedimento — `drift`
+
+1. Ler `.gos-local/stack.lock.json`.
+2. Recalcular sha256 de cada `sources[].path`.
+3. Listar mudanças. Se houver, sugerir `*stack refresh` e listar planos com `stack_ref` divergente (escanear `dirs.planos`).
+
+## Procedimento — `show`
+
+Imprimir o conteúdo de `dirs.stack`. Se ausente, instruir `*stack refresh`.
+
+## Saída
+
+Após `refresh`:
+
+```
+## Stack profilada — <projeto>
+
+- Framework: Next.js 15 (App Router)
+- DB: Supabase (read-only)
+- Design System: .referencia-storybook
+- Knowledge sources: 3 (postman, business-rules, adr)
+
+stack.md: docs/stack.md
+lock: .gos-local/stack.lock.json
+hashes: 12 arquivos
+```
+
+## Model guidance
+
+| Escopo | Modelo |
+|--------|--------|
+| Refresh em projeto pequeno/médio | `sonnet` |
+| Projeto grande com muita ambiguidade | `opus` |
+| `show` / `drift` | `haiku` |
+
+## Instructions
+
+1. Sempre resolver paths via `plan-paths.json` antes de tocar filesystem do projeto.
+2. Não inventar tecnologia — se não conseguir inferir, perguntar.
+3. Nunca propor mudança de stack neste skill — só registrar o que existe.

package/.gos/templates/contextTemplate.md

@@ -0,0 +1,35 @@
+---
+plan_id: PLAN-<NNN>-<slug>
+generated_at: <iso>
+---
+
+# Contexto — <tela>
+
+> Documento denso para a LLM — não é prosa para humanos. Indexa arquivos, decisões e riscos relevantes para executar o plano sem perder contexto.
+
+## Arquivos relevantes
+
+| Path | Função |
+|------|--------|
+| `<path>` | <função> |
+
+## Componentes do DS já em uso (próximos)
+
+- `<componente>` — usado em `<onde>`
+
+## Endpoints / regras-de-negócio referenciados
+
+- `<endpoint>` — Postman: `<ref>` — método: `<METHOD>`
+- `<regra>` — path: `<ref>`
+
+## Decisões tomadas durante o planejamento
+
+- <decisão> (motivo: <ref>)
+
+## Riscos abertos
+
+- <risco>
+
+## Notas curtas (livre)
+
+- <nota>

package/.gos/templates/planTemplate.md

@@ -0,0 +1,77 @@
+---
+id: PLAN-<NNN>-<slug>
+tela: <nome da tela>
+figma_url: <url ou null>
+status: pendente
+parent_plan: <PLAN-NNN ou null>
+children_plans: []
+stack_ref: docs/stack.md@<sha-curto>
+arch_change: false
+created_at: <iso>
+validated_at: null
+---
+
+# <Título da tela>
+
+## Contexto
+
+<Por que esta tela existe — referência ao PRD, ticket, decisão de produto.>
+
+## Componentes mapeados
+
+| Elemento | Componente do DS | Variant | Props |
+|----------|------------------|---------|-------|
+|          |                  |         |       |
+
+## Componentes ausentes
+
+> Listar componentes não cobertos pelo DS. Cada um vira task de criação separada (priorizar reuso/extensão antes de propor novo).
+
+- <ausente 1 — sugestão: estender X | criar novo>
+
+## Aderência à Stack
+
+> Sem redefinir arquitetura. Apenas referenciar o que já existe em `stack.md`.
+
+- **Dados consumidos**: <endpoint Postman | tabela | regra-de-negocio> — path: <ref>
+- **Padrão de fetching**: <server component | server action | client+cache>
+- **Auth requerida**: <sim/não> — provider: <ref `stack.md`>
+- **Restrições aplicáveis**: <listar do `stack.md`>
+
+> Se `arch_change: true`: ADR de referência: `docs/adr/ADR-XXXX-<slug>.md`
+
+## Fluxo de navegação
+
+- Rota: `<src/app/.../page.tsx>`
+- Entrada: <de onde vem>
+- Saída: <para onde vai>
+
+## Fluxo de dados
+
+```
+<diagrama textual: tela → fetch → componente → render>
+```
+
+## Plano de execução
+
+1. **Estrutura de pastas/rotas** — criar `<path>`
+2. **Fetching** — `<server-component em page.tsx | server-action>` consumindo `<endpoint/tabela>`
+3. **Montagem da view** — compor `<componentes>`
+4. **Estado e interatividade** — `<descrever>`
+
+## Checklist de aceite
+
+- [ ] Tela renderiza com dados reais
+- [ ] Estados de loading e erro tratados
+- [ ] Acessibilidade básica (keyboard nav, aria)
+- [ ] Responsivo (mobile + desktop)
+- [ ] Sem console errors/warnings
+- [ ] TypeScript válido (`tsc --noEmit`)
+- [ ] Reutilização ≥ X% de componentes do DS
+- [ ] <critério específico da tela 1>
+- [ ] <critério específico da tela 2>
+
+## Riscos & Rollback
+
+- <risco>
+- Rollback: <git tag/branch>

package/.gos/templates/progressTemplate.txt

@@ -0,0 +1,15 @@
+# progress.l1
+ts=<iso>
+project=<nome>
+plan_active=<path/plan.md>
+tasks_dir=<path/tasks/>
+context=<path/context.md>
+stack_ref=docs/stack.md@<sha>
+status=pendente
+
+last_done=
+current=
+next=
+
+blockers=
+notes=

package/.gos/templates/stackTemplate.md

@@ -0,0 +1,72 @@
+---
+schema: gos.stack.v1
+project: <nome>
+generated_at: <iso>
+read_only_backend: <true|false>
+---
+
+# Stack-of-record — <projeto>
+
+> Este arquivo é a fonte canônica da stack. Todo plano (`plan-blueprint`) referencia este documento via `stack_ref`. Alterações aqui exigem ADR.
+
+## 1. Framework & runtime
+- Framework: <Next.js 15 / Vite / etc>
+- Runtime: <Node 20 / Bun / Edge>
+- Linguagem: <TypeScript / JavaScript>
+- Build: <turbopack / webpack / vite>
+
+## 2. UI / Design System
+- Lib UI base: <shadcn / radix / mui>
+- Design system path: <path>
+- Tokens: <path ou descrição>
+- Convenção de variants: <tailwind-variants / cva / cn>
+
+## 3. Estado & dados
+- Estado client: <zustand / jotai / context>
+- Cache/data: <swr / react-query / server cache>
+- Forms: <react-hook-form / formik>
+- Validação: <zod / yup>
+
+## 4. Auth
+- Provider: <supabase-auth / clerk / next-auth>
+- Estratégia: <session cookies / jwt>
+- Middleware: <path>
+
+## 5. Backend / DB
+- DB: <supabase / postgres / mongo>
+- ORM: <prisma / drizzle / supabase-js>
+- Read-only?: <sim|não>
+- Migrations: <permitidas|proibidas>
+
+## 6. Padrões de fetching
+- Server components: <quando usar>
+- Server actions: <quando usar>
+- Client + cache: <quando usar>
+- Convenção de erro/loading: <descrever>
+
+## 7. Convenções de pastas e rotas
+- Rotas: <src/app/...>
+- Componentes: <src/components/...>
+- Hooks: <src/hooks/...>
+- Helpers: <src/lib/...>
+
+## 8. Fontes de conhecimento do projeto
+
+> Listadas a partir de `knowledge_sources` em `.gos-local/plan-paths.json`.
+
+| Tipo | Path | Resumo |
+|------|------|--------|
+| design-system | <path> | <resumo> |
+| postman | <path> | <N coleções, M endpoints> |
+| business-rules | <path> | <N módulos> |
+| adr | <path> | <N ADRs ativas> |
+
+## 9. Restrições
+- <ex.: não introduzir nova lib sem ADR>
+- <ex.: não alterar schema sem migration aprovada>
+- <ex.: i18n é obrigatório em toda string visível>
+
+## 10. Links internos
+- README: <path>
+- CLAUDE.md: <path>
+- ADRs ativas: <lista>

package/.gos/templates/taskTemplate.md

@@ -0,0 +1,40 @@
+---
+id: T-<NNN>-<NN>
+plan_id: PLAN-<NNN>-<slug>
+seq: <NN>
+title: <verbo imperativo + objeto>
+area: <ui-ux|frontend|fetching|state|tests|infra>
+labels: [agent:<slug>, type:<feature|refactor|bug|chore>]
+priority: <P0|P1|P2>
+estimate: "<2h|4h|1d>"
+status: pendente
+valida_em: <referência ao critério no checklist do plano>
+assignees: []
+links: []
+---
+
+## Contexto
+
+<Por que esta task existe — referência direta ao plano pai e ao critério de aceite.>
+
+## Objetivo
+
+<Resultado esperado em 1-2 frases.>
+
+## Plano de execução
+
+- [ ] Passo 1
+- [ ] Passo 2
+- [ ] Passo 3
+
+## Critérios de aceitação (DoD)
+
+- [ ] Implementação atende `valida_em` do plano
+- [ ] Tests/CI verdes
+- [ ] Sem regressões
+- [ ] <métrica específica>
+
+## Riscos & Rollback
+
+- <risco>
+- Rollback: <comando>

package/AGENTS.md

@@ -37,6 +37,21 @@ Este repo existe para acelerar design-to-code e entrega de sprint.
 | **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 |
+
+## Plan Pipeline
+
+Pipeline padronizado para criacao de planos por tela. Stack-of-record (`docs/stack.md`) e contrato — alteracoes exigem ADR.
+
+| Comando | Skill | Funcao |
+|---------|-------|--------|
+| `*stack [refresh\|show\|drift]` | `stack-profiler` | Mantem `docs/stack.md` |
+| `*plan <tela>` | `plan-blueprint` | Cria plano + tasks + context + atualiza `progress.txt` |
+| `*progress [show\|set\|status]` | `progress-tracker` | State machine `pendente -> em-andamento -> validacao -> concluido` |
+
+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

@@ -48,4 +48,20 @@ Todo texto gerado deve passar por correcao ortografica e remocao de padroes de I
 gos-master | architect | dev | devops | po | qa | sm | squad-creator | ux-design-expert
 
 ### 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 | sprint-planner | clickup | plan-to-tasks | agent-teams | git-ssh-setup
+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 | sprint-planner | clickup | plan-to-tasks | agent-teams | git-ssh-setup | stack-profiler | plan-blueprint | progress-tracker
+
+## Plan Pipeline (stack-aware)
+
+Pipeline padronizado para criacao de planos por tela. Toda tela = 1 plano. Stack-of-record (`docs/stack.md`) e contrato — alteracoes de stack exigem ADR.
+
+| Comando | Skill | Funcao |
+|---------|-------|--------|
+| `*stack [refresh|show|drift]` | `stack-profiler` | Mantem `docs/stack.md` (canonico do projeto) |
+| `*plan <tela>` | `plan-blueprint` | Cria plano + tasks + context + atualiza `progress.txt` |
+| `*progress [show|set|status]` | `progress-tracker` | Memoria L1 + state machine de status |
+
+State machine: `pendente -> em-andamento -> validacao -> concluido` (concluido somente apos validacao humana).
+
+Paths do projeto-cliente sao resolvidos via `.gos-local/plan-paths.json` — nada hardcoded. Nesse arquivo declara-se onde estao `docs/plans/`, `docs/postman/`, `docs/regras-de-negocio/`, design system, etc. Cada projeto/dev pode organizar diferente.
+
+Playbook completo: `.gos/playbooks/plan-creation-playbook.md`

package/README.md

@@ -43,18 +43,38 @@ Após rodar o install, o framework criará uma estrutura limpa na sua raiz:
 
 ### 3. Comandos do Workspace
 
-A partir da raiz do seu projeto, você pode gerenciar o framework:
+A partir da raiz do seu projeto:
 
-| Comando | O que faz |
-|---------|-----------|
-| `npm run gos:init` | Setup pos-clone (remote, dirs, IDEs, sync framework pai) |
-| `npm run gos:update` | Fetch upstream + merge + re-sync IDEs + sync framework pai |
-| `npm run gos:doctor` | Valida integridade do workspace e IDEs |
-| `npm run gos:version` | Mostra versao e checa atualizacoes |
-| `npm run sync:ides` | Regenera adapters para Claude, Gemini, Cursor e outras |
-| `npm run check:ides` | Valida compatibilidade dos IDE adapters |
-| `npm run clickup` | CLI ClickUp (tarefas, sprints, status) |
-| `npm run doctor` | Alias direto para gos:doctor |
+| Comando | Equivalente CLI | O que faz |
+|---------|-----------------|-----------|
+| `npm run gos:init` | `gos init` | Setup pos-clone: configura `upstream`, cria dirs (`.gos-local/`), gera IDE adapters, sincroniza com framework pai |
+| `npm run gos:update` | `gos update` | `git fetch upstream` + merge `upstream/main` + `npm install` + re-sync IDE adapters |
+| `npm run gos:doctor` | `gos doctor` | Valida integridade do workspace, registry de skills, IDE adapters, presenca de Git remote |
+| `npm run gos:version` | `gos version` | Mostra versao instalada e checa se ha atualizacoes pendentes em `upstream/main` |
+| `npm run sync:ides` | — | Regenera apenas os IDE adapters (`.claude/`, `.qwen/`, `.gemini/`, `.cursor/`, `.agents/`) |
+| `npm run check:ides` | — | Valida que todos os adapters estao consistentes com `.gos/skills/registry.json` |
+| `npm run clickup` | — | CLI ClickUp (tarefas, sprints, status) |
+
+**Atualizar o G-OS no seu workspace:**
+
+```bash
+npm run gos:update
+# equivalente a: git fetch upstream && git merge upstream/main && npm install && npm run sync:ides
+```
+
+Em caso de divergencia local nao resolvivel automaticamente, o comando aborta e instrui resolucao manual. Se quiser inspecionar antes:
+
+```bash
+npm run gos:version   # mostra versao atual + commits pendentes em upstream
+git fetch upstream    # ver mudancas sem aplicar
+git log HEAD..upstream/main --oneline
+```
+
+**Health-check apos qualquer mudanca:**
+
+```bash
+npm run gos:doctor    # 40+ checks (skills, agents, IDE adapters, git remote)
+```
 
 ### Via CLI global (`gos`)
 
@@ -64,7 +84,7 @@ Apos `npm install -g ganbatte-os`:
 |---------|-----------|
 | `gos install` | Instala framework em diretorio novo |
 | `gos init` | Inicializa workspace existente |
-| `gos update` | Atualiza framework |
+| `gos update` | Atualiza framework (mesma logica de `npm run gos:update`) |
 | `gos doctor` | Health-check |
 | `gos version` | Versao instalada |
 
@@ -130,6 +150,237 @@ O `ganbatte-os` utiliza uma estrutura **encapsulada** para manter seu projeto li
 | **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) |
 | **weekly-update** | `/gos:skills:weekly-update` | Resumo semanal de tasks ClickUp → humaniza → posta no Slack (requer aprovacao) |
+| **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
+```
+
+| 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 |
+
+### 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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ganbatte-os",
-  "version": "0.2.30",
+  "version": "0.2.32",
   "description": "Framework operacional para design-to-code, squads de entrega e sprint sync com ClickUp.",
   "bin": {
     "gos": ".gos/scripts/cli/gos-cli.js"