ganbatte-os 0.2.42 → 0.2.43

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/AGENTS.md +30 -38
  2. package/CLAUDE.md +12 -6
  3. package/GEMINI.md +10 -4
  4. package/README.md +73 -439
  5. package/package.json +1 -1
package/AGENTS.md CHANGED
@@ -2,53 +2,45 @@
2
2
 
3
3
  ## Objetivo
4
4
 
5
- Este repo existe para acelerar design-to-code e entrega de sprint.
6
-
7
- ## Agentes
8
-
9
- | ID | Slash Command | Foco |
10
- |----|--------------|------|
11
- | **gos-master** | `/gos:agents:gos-master` | Orquestrador master — routing, skills, squads, workflows |
12
- | **architect** | `/gos:agents:architect` | Stack, padroes tecnicos, revisoes de arquitetura |
13
- | **dev** | `/gos:agents:dev` | Implementacao de features, hooks, refinamentos |
14
- | **devops** | `/gos:agents:devops` | Git, branches, CI/CD, automacoes de entrega |
15
- | **po** | `/gos:agents:po` | Backlog, scope, priorizacao |
16
- | **qa** | `/gos:agents:qa` | Testes, quality gates, revisao de codigo |
17
- | **sm** | `/gos:agents:sm` | Sprint, planning, sync com stakeholders |
18
- | **squad-creator** | `/gos:agents:squad-creator` | Orquestracao de times multi-agentes |
19
- | **ux-design-expert** | `/gos:agents:ux-design-expert` | Design de interfaces, tokens, design systems |
20
-
21
- ## Skills
22
-
23
- | Skill | Slash Command | Funcao |
24
- |-------|--------------|--------|
25
- | **design-to-code** | `/gos:skills:design-to-code` | Converte Figma/screenshot em componentes React |
26
- | **figma-implement-design** | `/gos:skills:figma-implement-design` | Implementa design Figma com fidelidade 1:1 |
27
- | **figma-make-analyzer** | `/gos:skills:figma-make-analyzer` | Analisa output do Figma Make |
28
- | **make-code-triage** | `/gos:skills:make-code-triage` | Classifica codigo do Figma Make por categoria |
29
- | **make-version-diff** | `/gos:skills:make-version-diff` | Compara versoes de output Figma Make |
30
- | **component-dedup** | `/gos:skills:component-dedup` | Detecta componentes duplicados |
31
- | **frontend-dev** | `/gos:skills:frontend-dev` | Build componentes, pages, hooks (React/Next.js) |
32
- | **interface-design** | `/gos:skills:interface-design` | Design de interface com metodologia intent-first |
33
- | **react-best-practices** | `/gos:skills:react-best-practices` | Otimizacao de performance React/Next.js |
34
- | **react-doctor** | `/gos:skills:react-doctor` | Diagnostico de saude de componentes React |
35
- | **plan-to-tasks** | `/gos:skills:plan-to-tasks` | Converte plano em tasks acionaveis |
36
- | **agent-teams** | `/gos:skills:agent-teams` | Coordena multiplos agentes em time |
37
- | **git-ssh-setup** | `/gos:skills:git-ssh-setup` | Configura identidade SSH para o workspace |
38
- | **stack-profiler** | `/gos:skills:stack-profiler` | Mantem `docs/stack.md` (stack-of-record canonica) |
39
- | **plan-blueprint** | `/gos:skills:plan-blueprint` | Cria plano por tela (1 tela = 1 plano) |
40
- | **progress-tracker** | `/gos:skills:progress-tracker` | Memoria L1 (`progress.txt`) + state machine |
5
+ Kit de desenvolvimento com IA: design-to-code, implementacao, otimizacao e seguranca.
6
+
7
+ ## Entrypoints (2 slash commands)
8
+
9
+ 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.
10
+
11
+ | Entrypoint | Foco |
12
+ |------------|------|
13
+ | `/gos:agents:gos-master` | Orquestrador — decide skills/agentes/subagents/squads e executa |
14
+ | `/gos:agents:ux-design-expert` | Design de interfaces, tokens, design systems |
15
+
16
+ ## Agentes internos (delegacao, nao-slash)
17
+
18
+ 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/`.
19
+
20
+ ## Skills (auto-discoveraveis, invocadas pelo master)
21
+
22
+ 34 skills, agrupadas por capacidade. Catalogo completo em `.gos/skills/registry.json`.
23
+
24
+ - **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`
25
+ - **Frontend/React**: `frontend-dev`, `react-best-practices`, `react-doctor`, `component-dedup`, `cloudflare-pages-setup`, `typeform-form-pattern`, `timer-component-pattern`
26
+ - **Pipeline de planos**: `stack-profiler`, `plan-blueprint`, `plan-to-tasks`, `execute-plan`, `validate-plan`, `progress-tracker`, `audit-screenshots`
27
+ - **Qualidade**: `security-review`, `perf-review`, `simplify-review`
28
+ - **Produto/texto/utilitarios**: `idea-intake`, `prd-from-intake`, `adr-tech-decisions`, `humanizer`, `gos-caveman`, `gos-compress`, `agent-teams`, `git-ssh-setup`
41
29
 
42
30
  ## Plan Pipeline
43
31
 
44
- Pipeline padronizado para criacao de planos por tela. Stack-of-record (`docs/stack.md`) e contrato — alteracoes exigem ADR.
32
+ 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`.
45
33
 
46
34
  | Comando | Skill | Funcao |
47
35
  |---------|-------|--------|
48
36
  | `*stack [refresh\|show\|drift]` | `stack-profiler` | Mantem `docs/stack.md` |
49
- | `*plan <tela>` | `plan-blueprint` | Cria plano + tasks + context + atualiza `progress.txt` |
37
+ | `*plan <tela>` | `plan-blueprint` | Cria `plan.md` + `context.md` + `spec.md` + `tasks/` (com criterios de aceite) |
38
+ | `*execute-plan <PLAN-NNN>` | `execute-plan` | Implementa task-a-task com visual gate + loop de correcao |
39
+ | `*validate-plan <PLAN-NNN>` | `validate-plan` | Audita, corrige gaps, roda seguranca + performance + doc-sync |
50
40
  | `*progress [show\|set\|status]` | `progress-tracker` | State machine `pendente -> em-andamento -> validacao -> concluido` |
51
41
 
42
+ Auditorias sob demanda: `*security-review`, `*perf-review`, `*simplify-review`.
43
+
52
44
  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`.
53
45
 
54
46
  ## Plan Mode Protocol
package/CLAUDE.md CHANGED
@@ -50,14 +50,20 @@ Todo texto gerado deve passar por correcao ortografica e remocao de padroes de I
50
50
 
51
51
  ## Slash Commands
52
52
 
53
- ### Agents (invoke via /gos:agents:{id})
54
- gos-master | architect | dev | devops | po | qa | sm | squad-creator | ux-design-expert
53
+ 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`).
55
54
 
56
- ### Skills (invoke via /gos:skills:{slug})
57
- 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
55
+ ### Entrypoints (slash)
56
+ - `/gos:agents:gos-master` — orquestrador; decide skills/agentes/subagents/squads e executa.
57
+ - `/gos:agents:ux-design-expert` — design de interface, tokens, design systems.
58
58
 
59
- ### IDEs suportadas (npm run sync:ides gera adapters)
60
- Claude Code | Cursor | Gemini CLI | Qwen Code | Antigravity | Opencode | Kilo Code | **Codex IDE Extension** (ambiente de execucao, comando primario `*execute-plan`)
59
+ ### Agentes internos (delegacao, nao-slash)
60
+ architect | dev | devops | po | qa | sm | squad-creator | security-auditor | perf-optimizer
61
+
62
+ ### Skills (auto-discoveraveis, invocadas pelo master — 34, ver `.gos/skills/registry.json`)
63
+ 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
64
+
65
+ ### IDEs suportadas (npm run sync:ides gera adapters p/ 6)
66
+ 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.
61
67
 
62
68
  ## Model routing por etapa (Junior executa, Senior audita)
63
69
 
package/GEMINI.md CHANGED
@@ -2,16 +2,22 @@
2
2
 
3
3
  Use este projeto como um kit de desenvolvimento: design-to-code, implementacao, otimizacao e seguranca.
4
4
 
5
+ ## Entrypoints
6
+
7
+ Superficie user-facing = 2 slash commands. As skills sao invocadas pelo master, nao digitadas.
8
+
9
+ - `/gos:agents:gos-master` — orquestrador; decide skills/agentes/squads e executa.
10
+ - `/gos:agents:ux-design-expert` — design de interface, tokens, design systems.
11
+
5
12
  ## Prioridades
6
13
 
7
14
  - Figma, Figma Make e Stitch para React/Next.js
8
- - planejamento por tela (plano + tasks com criterios de aceite)
9
- - auditoria de seguranca e performance
15
+ - planejamento por tela (`*plan` → `*execute-plan` → `*validate-plan`, com criterios de aceite)
16
+ - auditoria de seguranca e performance (`*security-review`, `*perf-review`)
10
17
  - revisao de qualidade antes de entrega
11
18
 
12
19
  ## Fontes principais
13
20
 
14
21
  - `AGENTS.md`
15
22
  - `CLAUDE.md`
16
- - `docs/toolchain-map.md`
17
- - `skills/registry.json`
23
+ - `.gos/skills/registry.json`
package/README.md CHANGED
@@ -8,493 +8,127 @@ Framework operacional de desenvolvimento: prototipacao, design-to-code, implemen
8
8
  [![NPM Home](https://img.shields.io/badge/NPM-Registry-red)](https://www.npmjs.com/package/ganbatte-os)
9
9
  ![Node >= 18](https://img.shields.io/badge/Node.js-%3E%3D18-green)
10
10
 
11
- 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`.
11
+ 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).
12
12
 
13
- ## Quick Start
13
+ ## Instalação
14
14
 
15
- ### 1. Instalação
15
+ Instalação **global** (recomendada):
16
16
 
17
17
  ```bash
18
- mkdir meu-projeto && cd meu-projeto
19
- git init
20
- npm install ganbatte-os
21
- ./node_modules/.bin/gos install
18
+ npm install -g ganbatte-os
22
19
  ```
23
20
 
24
- Alternativa global:
21
+ Depois, dentro do seu projeto:
25
22
 
26
23
  ```bash
27
- npm install -g ganbatte-os
24
+ mkdir meu-projeto && cd meu-projeto
25
+ git init # recomendado (habilita versionamento e updates)
28
26
  gos install
29
27
  ```
30
28
 
31
- Alternativa direto do GitHub (ultima versao do main):
29
+ O `gos install` cria uma estrutura enxuta na raiz:
32
30
 
33
- ```bash
34
- npm install github:adrianomorais-ganbatte/g-os
35
- ./node_modules/.bin/gos install
36
- ```
31
+ - `.gos/` — núcleo do framework (agentes, skills, scripts). Somente leitura.
32
+ - `AGENTS.md`, `CLAUDE.md`, `GEMINI.md` — instruções que a IDE lê automaticamente.
33
+ - `packages/` — onde vive o código do seu app.
34
+ - adapters de IDE (`.claude/`, `.codex/`, `.qwen/`, `.opencode/`, `.gemini/`, `.agent/`) — gerados automaticamente.
37
35
 
38
- ### 2. Pós-Instalação
39
- Após rodar o install, o framework criará uma estrutura limpa na sua raiz:
40
- - `.gos/` — O núcleo do framework (Agentes, Skills, Scripts).
41
- - `AGENTS.md`, `CLAUDE.md`, `GEMINI.md` — Instruções para as IDEs.
42
- - `packages/` — Onde você deve colocar o código do seu aplicativo.
36
+ Atualizar o CLI global depois: `npm install -g ganbatte-os@latest` · atualizar o framework num projeto: `gos install --force`.
43
37
 
44
- ### 3. Comandos do Workspace
38
+ ## Como usar: duas portas de entrada
45
39
 
46
- | Comando | Equivalente CLI | O que faz |
47
- |---------|-----------------|-----------|
48
- | `npm run gos:init` | `gos init` | Setup pos-clone: configura `upstream`, cria `.gos-local/`, gera IDE adapters |
49
- | `npm run gos:update` | `gos update` | Fetch + merge do upstream (**apenas em fork/clone do g-os**) |
50
- | `npm run gos:doctor` | `gos doctor` | Health-check (42+ checks: skills, agents, IDE adapters, upstream alcançável, stashes acumulados, modo workspace) |
51
- | `npm run gos:version` | `gos version` | Versão instalada, modo do workspace e atualizações pendentes |
52
- | `npm run gos:rescue` | `gos rescue` | Lista/recupera stashes acumulados de updates falhos |
53
- | `npm run sync:ides` | — | Regenera apenas os IDE adapters (`.claude/`, `.qwen/`, `.gemini/`, `.cursor/`, `.agents/`) |
54
- | `npm run check:ides` | — | Valida que adapters estão consistentes com `.gos/skills/registry.json` |
40
+ Você digita **apenas dois** slash commands. Todo o resto é roteado internamente.
55
41
 
56
- ## Atualizar o ganbatte-os
42
+ | Slash command | Quando usar |
43
+ |---------------|-------------|
44
+ | `/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. |
45
+ | `/gos:agents:ux-design-expert` | Design de interface, tokens e design systems. |
57
46
 
58
- Existem **três níveis distintos** de versão. Saiba qual atualizar antes de rodar qualquer comando.
47
+ > 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.
59
48
 
60
- ### Descobrir em que cenário você está
49
+ ### O que o gos-master aciona por você
61
50
 
62
- ```bash
63
- npm run gos:version
64
- # imprime: versão local + modo (framework workspace | projeto consumidor)
65
- ```
51
+ - **Design → código** — `design-to-code`, `figma-implement-design`, `figma-make-analyzer`, `interface-design`, `ui-guardrails` (Figma/screenshot → React/Next.js fiel).
52
+ - **Frontend/React** — `frontend-dev`, `react-best-practices`, `react-doctor`, `component-dedup`.
53
+ - **Pipeline de planos** — `plan-blueprint`, `plan-to-tasks`, `execute-plan`, `validate-plan`, `progress-tracker`, `stack-profiler` (ver abaixo).
54
+ - **Qualidade** — `security-review`, `perf-review`, `simplify-review`.
55
+ - **Texto/produto** — `humanizer`, `idea-intake`, `prd-from-intake`, `adr-tech-decisions`.
66
56
 
67
- | Modo detectado | Significa | Como atualizar |
68
- |----------------|-----------|----------------|
69
- | `framework workspace` | Você clonou/forkou o repo `g-os` para contribuir | `npm run gos:update` |
70
- | `projeto consumidor` | Seu projeto usa o G-OS (rodou `gos install` aqui) | `gos install --force` |
71
- | (CLI global) | O comando `gos` instalado via `npm install -g` | `npm install -g ganbatte-os@latest` |
57
+ Catálogo completo: `.gos/skills/registry.json`.
72
58
 
73
- ### Nível 1 — CLI global (`gos`)
59
+ ## Pipeline de planos (o fluxo de dev)
74
60
 
75
- ```bash
76
- # Versão atual instalada vs publicada no registry:
77
- npm list -g ganbatte-os
78
- npm view ganbatte-os version
61
+ 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`):
79
62
 
80
- # Atualizar:
81
- npm install -g ganbatte-os@latest
82
- ```
83
-
84
- ### Nível 2 — Projeto consumidor
63
+ - **plan** (Senior) planeja → **execute** (Junior) implementa → **validate** (Senior) audita e corrige gaps.
85
64
 
86
- Seu projeto NÃO é fork do G-OS, mas usa o framework via `gos install`. O `.gos/` mora dentro do seu repo.
87
-
88
- ```bash
89
- # Pré-checagem (uma vez):
90
- git remote -v
91
- # Se houver "upstream" apontando para g-os.git, REMOVA:
92
- # git remote remove upstream
93
- # (essa configuração só faz sentido em fork do framework)
94
-
95
- # Atualizar o framework dentro do seu projeto:
96
- gos install --force
97
- # Sobrescreve .gos/ com a última versão do pacote ganbatte-os global,
98
- # preservando seus arquivos (packages/, docs/, .gos-local/).
99
65
  ```
100
-
101
- > [!WARNING]
102
- > 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.
103
-
104
- ### Nível 3 — Framework workspace (fork/clone do g-os)
105
-
106
- Você está contribuindo com o próprio framework.
107
-
108
- ```bash
109
- # Pré-checagem (sempre antes de update):
110
- npm run gos:doctor
111
- # Valida 42+ pontos. Aborta se upstream estiver com URL quebrada
112
- # ou se houver stashes acumulados de updates anteriores falhos.
113
-
114
- # Ver quantos commits faltam:
115
- npm run gos:version
116
-
117
- # Aplicar (lê dev branch do .gos/config.json#defaultBranches.development):
118
- npm run gos:update
119
- ```
120
-
121
- `gos:update` agora é **fail-safe**:
122
-
123
- 1. Bloqueia se modo for `consumer`
124
- 2. Valida `upstream` reachable (`git ls-remote`) ANTES de stashar
125
- 3. Lê branch de desenvolvimento do `.gos/config.json` (não hardcoded)
126
- 4. Faz fetch primeiro; se nada mudou, sai sem stash
127
- 5. Stash recebe label timestamped único
128
- 6. Auto-resolve conflitos em arquivos do framework (`frameworkManaged` no manifest); aborta em conflitos do usuário
129
-
130
- Override de branch (debug):
131
-
132
- ```bash
133
- GOS_UPSTREAM_BRANCH=beta npm run gos:update
134
- ```
135
-
136
- #### Caso especial: "histórias não relacionadas"
137
-
138
- 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:
139
-
140
- ```bash
141
- npm run gos:update -- --allow-unrelated
66
+ *stack refresh # mapeia a stack do projeto (uma vez, ou quando mudar)
67
+ *plan <tela|figma-url> # cria plan.md + context.md + spec.md + tasks/ (com critérios de aceite)
68
+ *execute-plan PLAN-NNN # implementa task-a-task, com visual gate e loop de correção
69
+ *validate-plan PLAN-NNN # audita, corrige gaps, roda segurança + performance + doc-sync
70
+ *progress show # estado atual (pendente → em-andamento → validacao → concluido)
142
71
  ```
143
72
 
144
- Isso une as duas histórias num commit de merge único. Faça uma vez; depois disso updates normais funcionam.
73
+ 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.
145
74
 
146
- #### Caso especial: untracked files que conflitam com o merge
75
+ Auditorias sob demanda, a qualquer momento:
147
76
 
148
- 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:
149
-
150
- ```bash
151
- npm run gos:update -- --clobber-untracked
152
77
  ```
153
-
154
- 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.
155
-
156
- Combinar com `--allow-unrelated` quando ambos os casos ocorrerem (típico de workspaces antigos):
157
-
158
- ```bash
159
- npm run gos:update -- --allow-unrelated --clobber-untracked
78
+ *security-review # RLS, authz, secrets, injection (Supabase/D1)
79
+ *perf-review # cache, filas, N+1, paginação, over-fetch
80
+ *simplify-review # anti-over-engineering (remove o que não precisa existir)
160
81
  ```
161
82
 
162
- Alternativa segura (não toca seu git, apenas atualiza `.gos/`):
83
+ Playbook end-to-end: [`.gos/playbooks/plan-creation-playbook.md`](./.gos/playbooks/plan-creation-playbook.md).
163
84
 
164
- ```bash
165
- gos install --force
166
- ```
85
+ ## Comandos do workspace
167
86
 
168
- ### Resgate de stashes presos
87
+ | Comando | O que faz |
88
+ |---------|-----------|
89
+ | `gos init` | Setup pós-clone: configura `.gos-local/` e gera os IDE adapters |
90
+ | `gos doctor` | Health-check (63 checks: skills, agentes, adapters, upstream) |
91
+ | `gos version` | Versão instalada e modo do workspace |
92
+ | `npm run sync:ides` | Regenera os IDE adapters após mudar skills/agentes |
93
+ | `npm run check:ides` | Valida os adapters contra `.gos/skills/registry.json` |
169
94
 
170
- Se você teve falhas anteriores que deixaram stashes:
95
+ ## Estrutura do workspace
171
96
 
172
- ```bash
173
- npm run gos:rescue # lista todos com stat
174
- npm run gos:rescue -- --pop-latest # aplica o mais recente
175
- npm run gos:rescue -- --drop-all # remove todos (após revisão)
97
+ ```text
98
+ ├── .gos/ # Core do framework (agents, skills, scripts) — somente leitura
99
+ ├── .gos-local/ # Config local: models.json, plan-paths.json, logs (ignorado no git)
100
+ ├── packages/ # Seu código-fonte vive aqui
101
+ ├── AGENTS.md # Entrypoint de agentes
102
+ ├── CLAUDE.md # Instruções para Claude Code
103
+ └── GEMINI.md # Instruções para Google Gemini
176
104
  ```
177
105
 
178
- ### Resumo (qual comando para qual cenário)
106
+ ## Atualizar o framework
179
107
 
180
108
  | Cenário | Comando |
181
109
  |---------|---------|
182
- | Atualizar CLI `gos` global | `npm install -g ganbatte-os@latest` |
183
- | Atualizar G-OS num projeto consumidor | `gos install --force` |
184
- | Atualizar G-OS num fork/clone do repo | `npm run gos:update` |
185
- | Stashes presos de updates falhos | `npm run gos:rescue` |
186
- | Saber em qual cenário você está | `npm run gos:version` |
187
- | Validar tudo de uma vez | `npm run gos:doctor` |
188
-
189
- > [!NOTE]
190
- > 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.
110
+ | CLI `gos` global | `npm install -g ganbatte-os@latest` |
111
+ | Framework num projeto consumidor | `gos install --force` |
112
+ | Fork/clone do repo `g-os` | `npm run gos:update` |
113
+ | Saber em qual cenário você está | `gos version` |
114
+ | Validar tudo | `gos doctor` |
191
115
 
192
- ## Estrutura do Workspace
193
-
194
- O `ganbatte-os` utiliza uma estrutura **encapsulada** para manter seu projeto limpo e organizado:
195
-
196
- ```text
197
- ├── .gos/ # Core do Framework (Somente leitura para usuários)
198
- │ ├── agents/ # Perfis e instruções dos agentes IA
199
- │ ├── skills/ # Catálogo de ferramentas (ex: design-to-code)
200
- │ ├── scripts/ # Engine do CLI e integração de IDEs
201
- │ └── prompts/ # Prompts canônicos para os agentes
202
- ├── .gos-local/ # Dados locais (logs, queues, worktrees) - ignorado no git
203
- ├── packages/ # Seu código-fonte e projetos vivem aqui
204
- ├── AGENTS.md # Entrypoint de agentes para o framework
205
- ├── CLAUDE.md # Instruções específicas para Claude Code
206
- └── GEMINI.md # Instruções específicas para Google Gemini
207
- ```
208
-
209
- ## Funcionalidades Principais
210
-
211
- - **Design-to-Code**: Pipeline automatizado para converter frames do Figma em componentes React/Next.js de alta fidelidade.
212
- - **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).
213
- - **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.
214
- - **Multi-IDE Multi-Tenant**: Configurações automáticas para as melhores ferramentas de IA do mercado.
215
-
216
- ## Agentes Disponíveis
217
-
218
- | Agent | Slash Command | Foco |
219
- |-------|--------------|------|
220
- | **gos-master** | `/gos:agents:gos-master` | Orquestrador master — routing, skills, squads, workflows |
221
- | **architect** | `/gos:agents:architect` | Stack, padroes tecnicos, revisoes de arquitetura |
222
- | **dev** | `/gos:agents:dev` | Implementacao de features, hooks, refinamentos |
223
- | **devops** | `/gos:agents:devops` | Git, branches, CI/CD, automacoes de entrega |
224
- | **po** | `/gos:agents:po` | Backlog, scope, priorizacao |
225
- | **qa** | `/gos:agents:qa` | Testes, quality gates, revisao de codigo |
226
- | **sm** | `/gos:agents:sm` | Sprint, planning, sync com stakeholders |
227
- | **squad-creator** | `/gos:agents:squad-creator` | Orquestracao de times multi-agentes |
228
- | **ux-design-expert** | `/gos:agents:ux-design-expert` | Design de interfaces, tokens, design systems |
229
-
230
- ## Skills Disponiveis
231
-
232
- | Skill | Slash Command | Funcao |
233
- |-------|--------------|--------|
234
- | **design-to-code** | `/gos:skills:design-to-code` | Converte Figma/screenshot em componentes React |
235
- | **figma-implement-design** | `/gos:skills:figma-implement-design` | Implementa design Figma com fidelidade 1:1 |
236
- | **figma-make-analyzer** | `/gos:skills:figma-make-analyzer` | Analisa output do Figma Make |
237
- | **make-code-triage** | `/gos:skills:make-code-triage` | Classifica codigo do Figma Make por categoria |
238
- | **make-version-diff** | `/gos:skills:make-version-diff` | Compara versoes de output Figma Make |
239
- | **component-dedup** | `/gos:skills:component-dedup` | Detecta componentes duplicados |
240
- | **frontend-dev** | `/gos:skills:frontend-dev` | Build componentes, pages, hooks (React/Next.js) |
241
- | **interface-design** | `/gos:skills:interface-design` | Design de interface com metodologia intent-first |
242
- | **react-best-practices** | `/gos:skills:react-best-practices` | Otimizacao de performance React/Next.js |
243
- | **react-doctor** | `/gos:skills:react-doctor` | Diagnostico de saude de componentes React |
244
- | **plan-to-tasks** | `/gos:skills:plan-to-tasks` | Converte plano em tasks acionaveis |
245
- | **agent-teams** | `/gos:skills:agent-teams` | Coordena multiplos agentes em time |
246
- | **git-ssh-setup** | `/gos:skills:git-ssh-setup` | Configura identidade SSH para o workspace |
247
- | **humanizer** | `/gos:skills:humanizer` | Remove padroes de IA do texto (two-pass audit + soul injection) |
248
- | **security-review** | `/gos:skills:security-review` | Auditoria de seguranca (RLS, authz, secrets, injection) |
249
- | **perf-review** | `/gos:skills:perf-review` | Auditoria de performance (cache, filas, N+1, paginacao) |
250
- | **stack-profiler** | `/gos:skills:stack-profiler` | Mantem `docs/stack.md` como stack-of-record canonica do projeto |
251
- | **plan-blueprint** | `/gos:skills:plan-blueprint` | Cria plano por tela (1 tela = 1 plano) seguindo a stack |
252
- | **progress-tracker** | `/gos:skills:progress-tracker` | Memoria L1 (`progress.txt`) + state machine de status |
253
-
254
- ## Plan Pipeline (stack-aware)
255
-
256
- 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.
257
-
258
- ### Fluxo
259
-
260
- ```
261
- *stack refresh → docs/stack.md (uma vez por workspace, ou quando stack mudar)
262
- *plan <tela> → docs/plans/PLAN-NNN-<slug>/{plan.md, tasks/, context.md} + progress.txt
263
- *progress ... → transicoes pendente → em-andamento → validacao → concluido
264
- ```
116
+ > `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`.
265
117
 
266
- | Comando | Skill | Funcao |
267
- |---------|-------|--------|
268
- | `*stack [refresh\|show\|drift]` | `stack-profiler` | Mantem `docs/stack.md` (canonico) e `.gos-local/stack.lock.json` |
269
- | `*plan <tela\|figma-url>` | `plan-blueprint` | Cria plano + dispara `plan-to-tasks` + atualiza `progress.txt` |
270
- | `*progress [show\|set\|status]` | `progress-tracker` | Memoria L1 e state machine |
118
+ ## Documentação
271
119
 
272
- ### Regras invioiaveis
273
-
274
- - **Stack como contrato** — toda decisao tecnica respeita `docs/stack.md`. Mudanca de stack exige ADR e flag `--allow-arch-change`.
275
- - **Paths via config** — nada hardcoded. Tudo resolvido via `.gos-local/plan-paths.json` (incluindo `knowledge_sources` como Postman, regras-de-negocio, ADRs).
276
- - **State machine dura** — `concluido` somente apos validacao humana.
277
- - **`progress.txt` e L1** — denso, otimizado para LLM, atualizado em todo passo.
278
-
279
- ### Configuracao por workspace
280
-
281
- `.gos-local/plan-paths.json` define onde cada projeto guarda seus artefatos. Cada projeto/dev pode organizar diferente.
282
-
283
- **Inicializar com defaults** (helper):
284
-
285
- ```bash
286
- node .gos/scripts/tools/plan-paths.js init # cria .gos-local/plan-paths.json se nao existir
287
- node .gos/scripts/tools/plan-paths.js show # imprime config atual
288
- node .gos/scripts/tools/plan-paths.js get planos # imprime path resolvido para "planos"
289
- ```
290
-
291
- **Exemplo de config** (caso real do `packages/fractus`):
292
-
293
- ```json
294
- {
295
- "schema": "gos.plan-paths.v1",
296
- "dirs": {
297
- "projeto": "src/",
298
- "storybook": ".referencia-storybook/",
299
- "design_system_doc": ".referencia-storybook/docs/DESIGN_SYSTEM_REFERENCE.md",
300
- "components": ".referencia-storybook/components/",
301
- "stories": ".referencia-storybook/stories/",
302
- "planos": "docs/plans/",
303
- "tasks": "docs/plans/{plan}/tasks/",
304
- "contexto": "docs/plans/{plan}/context.md",
305
- "progress": "progress.txt",
306
- "stack": "docs/stack.md",
307
- "adr": "docs/adr/",
308
- "postman": "docs/postman/",
309
- "regras_negocio": "docs/regras-de-negocio/"
310
- },
311
- "knowledge_sources": [
312
- { "kind": "postman", "path": "docs/postman/", "required": false },
313
- { "kind": "business-rules", "path": "docs/regras-de-negocio/", "required": false },
314
- { "kind": "adr", "path": "docs/adr/", "required": false },
315
- { "kind": "design-system", "path": ".referencia-storybook/docs/DESIGN_SYSTEM_REFERENCE.md", "required": true }
316
- ],
317
- "naming": { "plan_prefix": "PLAN", "task_prefix": "T", "seq_padding": 3 },
318
- "figma": { "mcp_enabled": true, "default_file_url": null }
319
- }
320
- ```
321
-
322
- Helpers em `.gos/scripts/tools/`:
323
- - `plan-paths.js` — resolve caminhos do projeto-cliente
324
- - `plan-status.js` — valida transicoes de status (state machine)
325
- - `stack-scan.js` — infere stack lendo `package.json`, configs e `knowledge_sources`
326
-
327
- ### Exemplos de uso (end-to-end)
328
-
329
- Todos os comandos abaixo sao invocados via slash command no `gos-master` (Claude Code, Gemini, Cursor, etc).
330
-
331
- #### 1. Bootstrap do workspace (uma vez por projeto)
332
-
333
- ```bash
334
- /gos:agents:gos-master
335
- ```
336
-
337
- Em seguida, no chat:
338
-
339
- ```
340
- *stack refresh
341
- ```
342
-
343
- Saida esperada:
344
-
345
- ```
346
- ## Stack profilada — packages/fractus
347
-
348
- - Framework: Next.js 15 (App Router)
349
- - DB: Supabase (read-only)
350
- - Design System: .referencia-storybook
351
- - Knowledge sources: 4 (postman, business-rules, adr, design-system)
352
-
353
- stack.md: docs/stack.md
354
- lock: .gos-local/stack.lock.json
355
- hashes: 12 arquivos
356
- ```
357
-
358
- Verifique sempre que algo na stack mudar (lib, framework, ORM):
359
-
360
- ```
361
- *stack drift
362
- ```
363
-
364
- #### 2. Criar plano para uma tela
365
-
366
- A partir de URL Figma (autodetecta e usa Figma MCP):
367
-
368
- ```
369
- *plan https://www.figma.com/design/kXd8uP6dgeSuQypFnPmuQP/FRACTUS?node-id=9140-25387
370
- ```
371
-
372
- A partir de descricao livre:
373
-
374
- ```
375
- *plan tela de checkout com formulario de pagamento e resumo do pedido
376
- ```
377
-
378
- Saida:
379
-
380
- ```
381
- ## Plano criado: PLAN-042-checkout
382
-
383
- - plan.md: docs/plans/PLAN-042-checkout/plan.md
384
- - context.md: docs/plans/PLAN-042-checkout/context.md
385
- - tasks/: docs/plans/PLAN-042-checkout/tasks/ (5 tasks: T-042-001 ... T-042-005)
386
- - progress: atualizado (status=pendente)
387
- - stack_ref: docs/stack.md@a1b2c3d
388
-
389
- Proximos passos:
390
- 1. Revisar plan.md e checklist de aceite
391
- 2. *progress status T-042-001 em-andamento
392
- 3. Executar
393
- ```
394
-
395
- Telas complexas (modal + drawer + sub-rotas) sao **subdivididas automaticamente** em planos filhos:
396
-
397
- ```
398
- PLAN-042-checkout (pai, checklist consolidado)
399
- ├── PLAN-042.1-payment-modal (filho)
400
- ├── PLAN-042.2-summary-drawer
401
- └── PLAN-042.3-confirm-page
402
- ```
403
-
404
- #### 3. Executar tasks
405
-
406
- ```
407
- *progress show # mostra progress.txt atual
408
- *progress status T-042-001 em-andamento # iniciar task
409
- # ... dev implementa ...
410
- *progress status T-042-001 validacao # task pronta para revisao (commit preparado, nao pushado)
411
- ```
412
-
413
- Tentar pular validacao falha:
414
-
415
- ```
416
- *progress status T-042-001 concluido
417
- > erro: transicao invalida: em-andamento → concluido
418
- > use --rollback para voltar para pendente
419
- ```
420
-
421
- #### 4. Fechar o plano
422
-
423
- Quando todas as tasks estao em `validacao` e o checklist do plano esta completo:
424
-
425
- ```
426
- *progress status PLAN-042-checkout validacao # validacao humana + QA
427
- *progress status PLAN-042-checkout concluido # SOMENTE apos aprovacao
428
- ```
429
-
430
- `progress-tracker compact` periodicamente reescreve `progress.txt` removendo tasks `concluido` antigas para manter o arquivo < 4kB (otimizado para LLM).
431
-
432
- #### 5. Mudanca de arquitetura (excecao)
433
-
434
- Se a tela exigir alteracao da stack (nova lib, novo padrao de fetching, schema novo):
435
-
436
- ```
437
- *plan tela-relatorios --allow-arch-change
438
- ```
439
-
440
- 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`).
441
-
442
- ### Estrutura de saida
443
-
444
- Apos `*plan tela-checkout`:
445
-
446
- ```
447
- docs/plans/PLAN-042-checkout/
448
- ├── plan.md # frontmatter (id, tela, figma_url, status, stack_ref) + secoes fixas
449
- ├── context.md # denso, indice de arquivos, decisoes, riscos
450
- └── tasks/
451
- ├── T-042-001-criar-rota-checkout.md
452
- ├── T-042-002-fetching-supabase.md
453
- ├── T-042-003-form-pagamento.md
454
- ├── T-042-004-resumo-pedido.md
455
- └── T-042-005-estados-erro-loading.md
456
- ```
457
-
458
- `progress.txt` na raiz do projeto fica:
459
-
460
- ```
461
- # progress.l1
462
- ts=2026-05-01T18:22:00-03:00
463
- project=fractus
464
- plan_active=docs/plans/PLAN-042-checkout/plan.md
465
- tasks_dir=docs/plans/PLAN-042-checkout/tasks/
466
- context=docs/plans/PLAN-042-checkout/context.md
467
- stack_ref=docs/stack.md@a1b2c3d
468
- status=em-andamento
469
-
470
- last_done=T-042-002 fetching-supabase
471
- current=T-042-003 form-pagamento
472
- next=T-042-004 resumo-pedido
473
-
474
- blockers=
475
- notes=fetch usa server component em app/checkout/page.tsx
476
- ```
477
-
478
- ### Playbook completo
479
-
480
- [`.gos/playbooks/plan-creation-playbook.md`](./.gos/playbooks/plan-creation-playbook.md) — documenta o fluxo end-to-end com troubleshooting.
481
-
482
- ## Documentacao
483
-
484
- | Documento | Descricao |
120
+ | Documento | Descrição |
485
121
  |-----------|-----------|
486
- | [AGENTS.md](./AGENTS.md) | Agentes, skills e slash commands disponiveis |
487
- | [CLAUDE.md](./CLAUDE.md) | Instrucoes para Claude Code |
488
- | [GEMINI.md](./GEMINI.md) | Instrucoes para Google Gemini |
489
- | [docs/README.md](./docs/README.md) | Indice de documentacao |
122
+ | [AGENTS.md](./AGENTS.md) | Agentes e entrypoints |
123
+ | [CLAUDE.md](./CLAUDE.md) | Instruções para Claude Code |
124
+ | [GEMINI.md](./GEMINI.md) | Instruções para Google Gemini |
490
125
 
491
- **Fonte canonica dos agents**: `.gos/agents/profiles/`
492
- **Fonte canonica das skills**: `.gos/skills/`
493
- **Registry de skills**: `.gos/skills/registry.json`
126
+ Fonte canônica: agentes em `.gos/agents/profiles/`, skills em `.gos/skills/` (registry em `.gos/skills/registry.json`).
494
127
 
495
128
  ## Licença
496
129
 
497
- Este é um projeto interno da **Ganbatte**. Distribuído sob licença [MIT](LICENSE).
130
+ Distribuído sob licença [MIT](LICENSE).
498
131
 
499
132
  ---
500
- © 2026 Ganbatte. Todos os direitos reservados.
133
+
134
+ © 2026 Douglas Oliveira · [github.com/imdouglasoliveira](https://github.com/imdouglasoliveira)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "ganbatte-os",
3
- "version": "0.2.42",
3
+ "version": "0.2.43",
4
4
  "description": "Framework operacional de desenvolvimento: prototipacao, design-to-code, implementacao, otimizacao e seguranca.",
5
5
  "bin": {
6
6
  "gos": ".gos/scripts/cli/gos-cli.js"