--- name: claudex-dev description: | Plugin de desenvolvimento de software com revisao integrada do Codex (GPT). Ciclo completo: investigacao opcional -> plano -> revisao Codex -> implementacao com smoke test -> revisao em camadas -> revisao final. Acionar sempre que o usuario mencionar: implementar feature, corrigir bug, escrever migration, criar/editar edge function, refatorar codigo, "manda pro codex", "revisa com codex", "codex review", "abre uma PR", "/claudex-dev". Filosofia: sequencial e continuo — nao pausa entre fases, so nos 7 casos taxativos abaixo. Fornece versionamento de plano + changelog, aprendizado entre runs, deteccao de loop e smoke test runtime. NAO acionar para: consultas de dados no banco (usar MCP especifico do projeto), perguntas que nao envolvam codigo, leitura passiva de arquivos. --- # /claudex-dev — Desenvolvimento com Revisao Integrada do Codex > ⚠️ **Template — exige configuracao** > Este plugin foi gerado a partir do template `claudex-dev`. Antes de usar, voce **precisa**: > 1. Rodar `setup.sh` (na raiz do plugin) e preencher as variaveis do seu projeto > 2. Preencher `references/arquitetura.md` com a arquitetura do seu codebase > 3. Preencher `references/boas-praticas.md` com convencoes do seu time > > Sem isso, a skill nao tem como saber o nome do seu projeto, paths, stack, MCPs disponiveis. ## ⚠️ Passo 0 — Sanity check rapido (PRIMEIRA acao) O `setup.sh` ja verifica todos os pre-requisitos no momento da instalacao do plugin. Aqui em runtime, fazer apenas um **sanity check de 1 linha** pra cobrir o caso raro do usuario ter desinstalado algo apos o setup: ```bash MISSING="" for cmd in codex gh git; do command -v "$cmd" >/dev/null 2>&1 || MISSING="$MISSING $cmd" done [ -n "$MISSING" ] && echo "❌ Faltam CLIs:$MISSING — rode ./setup.sh no diretorio do plugin pra ver como instalar" ``` **Modo silencioso:** se passar, nao printar nada e seguir pra TodoList. Se faltar algo, mostrar a 1 linha acima e parar — o usuario rerroda o setup pra ver as instrucoes completas. --- ## ⚠️ PRIMEIRA acao obrigatoria — Criar TodoList do fluxo **ANTES de qualquer outra coisa** (antes de ler references, antes de perguntar nada, antes de rodar Bash), crie a TodoList do fluxo usando o TaskCreate tool. Isso e o que mantem o fluxo coerente quando a skill esta dividida em capitulos — sem a TodoList, voce vai abrir o capitulo errado ou pular fase. **Tarefas a criar (na ordem):** 1. `Setup inicial — gerar SLUG/TIMESTAMP/RUN_DIR/WORKTREE_DIR e detectar SO` 2. `Fase 0 — Investigacao (ler references/fase-0-investigacao.md)` 3. `Fase 1 — Plano (ler references/fase-1-plano.md)` 4. `Fase 2 — Revisao do Codex (ler references/fase-2-codex-revisao.md)` 5. `Fase 3 — Implementacao (ler references/fase-3-implementacao.md)` 6. `Fase 4 — Revisao e Relatorio (ler references/fase-4-revisao.md)` 7. `Fase 5 — Revisao final do Codex (ler references/fase-5-codex-final.md)` **Regras de uso da TodoList:** - Marcar `in_progress` ao ENTRAR em cada fase, antes de qualquer Read/Bash/Skill da fase. - Marcar `completed` ANTES de avancar para a proxima tarefa. - Se o atalho do usuario pular uma fase (ex: `--build` pula Fase 0; `"sem revisao"` pula Fases 2 e 5), marcar a fase pulada como `completed` com nota "pulada por atalho" no contexto. - Se uma fase voltar (Codex pediu "Ajustar" e voce voltou pra Fase 2), criar nova entrada `Fase 2 — rodada 2` em vez de remarcar a antiga. A TodoList aparece visivel pro usuario — se voce travar no meio, ele ve em qual fase parou. --- ## Estilo de comunicacao **Aplicar o CLAUDE.md global** do projeto, se houver (`~/.claude/CLAUDE.md`): - Linguagem de diretor (nao de engenheiro) — sem jargao denso - Opcoes A/B/C com trade-off dos dois lados - Nao estimar tempo de implementacao (usar risco/escopo/reversibilidade) - Tom direto, sem floreio - TL;DRs em formato de plano (problema/descobri/risco/solucao/decisao) Essas regras valem em TODOS os artefatos desta skill (TL;DRs das Fases 1/2/4/5, body de PR, AskUserQuestion, resumo final). --- ## Maquina de estados ``` FASE 0 (Investigacao opcional) ──→ FASE 1 (Plano: P0 + 3 passos) ──→ FASE 2 (Revisao Codex) ──→ decisao? │ P0 pesquisa/benchmark (cond.) ↑ │ ├─ findbugs (estatico) P1 desenhar comportamento └── Ajustar ─────────────┘ ├─ debug-browser (runtime) P2 plano + ancoragem │ └─ pular P3 auditoria boas praticas Seguir ──→ Aprovacao do plano final ↓ FASE 3 (Implementacao + smoke test) ──→ FASE 4 (Revisao + Relatorio) ↓ FASE 5 (Revisao Final Codex) ──→ Postar ``` **Regra de ouro:** ao terminar uma fase, anuncie "Fase X concluida. Iniciando Fase Y..." e avance. Nunca pare entre fases esperando permissao — o usuario ja autorizou o fluxo completo ao acionar esta skill. ### 🔒 SUSPENSAO DE MEMORIA GLOBAL durante /claudex-dev **Enquanto este fluxo estiver ativo (Fase 0 ate fim da Fase 5), regras globais como "apos `gh pr create`, sempre abrir URL no browser" ficam SUSPENSAS.** A PR so deve ser aberta no navegador na Fase 5 com decisao "Seguir". **Por que:** o usuario nao pode ver/clicar Merge na PR antes do Codex revisar o codigo final (Fase 5). Se a PR for aberta no navegador antes disso, ele acaba mergeando enquanto a revisao ainda esta rodando. ### Caminhos do run **SEMPRE** use `${RUN_DIR}/...` com os nomes numerados: - `${RUN_DIR}/1-plan.md` (arquivo de trabalho) + `1-plan-v.md` (snapshots) + `1-plan-final.md` - `${RUN_DIR}/2-review-r.md` + `2-changelog.md` - `${RUN_DIR}/3-smoke-test.md` (se aplicavel) - `${RUN_DIR}/4-summary.md` - `${RUN_DIR}/5-final-review-r.md` `${RUN_DIR}` e definido pelo Setup inicial abaixo (resolve por SO automaticamente). Se voce nao tiver `${RUN_DIR}` na sessao, volte ao Setup inicial. ### Nao presumir — regua de fato vs. intencao Antes de **afirmar algo como verdade** ou de **seguir com uma decisao**, classifique a duvida. As duas metades tem tratamento OPOSTO: - **Duvida de FATO** (esse arquivo existe? a coluna se chama assim? a causa do bug e essa? essa API funciona desse jeito?) → **nunca chute e nunca pergunte ao usuario** — **VERIFIQUE na fonte real**: codigo (grep/Read), banco de dados, doc viva (WebFetch / pesquisa web). O modelo "lembra" de um fato errado com a mesma confianca com que acerta; so a verificacao separa os dois. E perguntar ao usuario um fato que voce mesmo pode checar tambem e erro — ele ve o codigo/banco direto, nao quer ser o seu grep. - **Duvida de INTENCAO / decisao de negocio** (qual escopo ele quer? qual das 2 interpretacoes? trocar esse comportamento muda uma regra de negocio?) → **nao presuma**: mostre as opcoes e pergunte (caso #5 abaixo + bloco de divergencia da Fase 1). O erro que esta regua existe pra matar e **cravar fato sem verificar** — causa-raiz de diagnostico errado (ex: cravar "a causa e o componente X" ou "e config externa" sem abrir o codigo nem testar a hipotese). Ela aumenta a VERIFICACAO de fato, **nao** o numero de perguntas — esta skill e anti-interrupcao de proposito, e isso continua valendo. ### Quando parar para perguntar (taxativo) Pause **APENAS** nestes 7 casos. Em qualquer outra situacao, anuncie a proxima fase e siga. 1. **Escolha da Fase 0** — perguntar opcao 1-5 (construir / findbugs / debug-browser / os dois / pular). Excecao: usuario usou atalho (`--build`, `--findbugs`, etc.). 2. **Codex retornou "Ajustar" (com algum item em produto/dado/regra de negocio) ou "Bloquear"** — Fase 2 ou Fase 5. Ver criterio detalhado em `references/fase-2-codex-revisao.md` secao "Como decidir o que aplicar". Se "Ajustar" com todos ajustes internos, NAO pausar — aplicar sozinho e seguir. 3. **Aprovacao do plano final antes da Fase 3** — depois que Codex aprovou o plano (em qualquer rodada), mostrar plano final consolidado + changelog e aguardar OK do usuario antes de partir pra implementacao. 4. **Acao irreversivel pendente** — migration destrutiva (DROP, ALTER TYPE, RENAME, RLS modificada), force-push, reset --hard, deletar branch com trabalho. Mostrar o que vai fazer e pedir autorizacao especifica. 5. **Ambiguidade real no pedido original** — pedido vago com 2+ interpretacoes plausiveis. Criterio objetivo: e vago quando falta verbo de acao concreto OU falta objeto especifico. 6. **Usuario pediu pausa explicitamente** — "para ai", "deixa eu ver", "espera", "mostra antes". 7. **Checkpoint visual da Fase 3** — quando o diff toca tela, mostrar o screenshot e aguardar aprovacao visual ANTES de commitar (gate duro com escape `"sem print"`). Esta pausa e obrigatoria, nao cai nos anti-padroes de "nao pare". Ver `references/fase-3-implementacao.md` secao "Gate do checkpoint visual". ### Quando NAO parar (anti-padroes proibidos) - ❌ **Apos fase concluida sem issues** ("Code Review nao achou nada. Sigo?") → seguir direto - ❌ **Antes de fase de leitura/relatorio** (Fase 4 e Fase 5 nao tem efeito colateral no primeiro passo) → seguir direto - ❌ **"Proximo passo: X. Sigo?"** quando X e a proxima fase prevista no fluxo → trocar por "Iniciando X." e executar - ❌ **Mostrar tabela de resultados positivos e perguntar se continua** → mostra e segue na mesma mensagem - ❌ **Pedir confirmacao para algo que o usuario ja autorizou ao acionar /claudex-dev** → o acionamento e a autorizacao do fluxo completo - ❌ **Apos abrir PR (fim da Fase 3), perguntar "rodo a revisao agora?"** → Fase 4 e parte do fluxo, segue direto - ❌ **Code Review (etapa 1 de 3 da Fase 4) terminou sem issues, perguntar "tem mais algo?"** → Code Review NAO e fim da Fase 4. Anunciar "Iniciando Simplify" e seguir direto. - ❌ **Apos sub-skill (`code-review`, `simplify`, `security-review`) devolver controle, pausar antes de iniciar a proxima etapa** — sub-skill retornar NAO e um dos 7 casos taxativos de pausa. Anuncie o resultado E invoque a proxima coisa na MESMA mensagem. Padrao observado em sessoes reais: o modelo pausa aqui mesmo com as regras "sequencial e continuo" carregadas — a regra existe mas fica longe do ponto de decisao. Cada Etapa de `fase-4-revisao.md` tem um bloco 🚨 POS-RETORNO logo apos a invocacao da sub-skill pra reforcar isso no momento certo. - ❌ **Rodar 2 etapas em paralelo na Fase 4** — cada etapa precisa do codigo pos-etapa-anterior. Ver `references/fase-4-revisao.md`. ### Sequencial e continuo — exemplos concretos A Fase 4 (e a transicao Fase 4 → Fase 5) e o ponto onde o modelo mais erra. Use este padrao: ``` ❌ ERRADO #1 — pausa esperando o usuario "Code Review: 3 issues corrigidos. Sigo pra Simplify?" [devolve controle pro chat e espera resposta] ❌ ERRADO #2 — pula pra paralelo [invoca code-review E simplify na mesma chamada de tool] → quebra a corrente: simplify precisa do codigo JA corrigido pelo code-review. ✅ CERTO — sequencial e continuo "Code Review: 3 issues corrigidos. Iniciando Simplify." [NO MESMO TURNO, depois de atualizar state.json, invoca a Skill simplify — sem devolver controle pro chat, sem esperar autorizacao] ``` **Sequencial** = uma etapa termina, a proxima comeca (ordem fixa: code_review → simplify → security_review → summary). **Continuo** = sem devolver controle pro usuario entre as etapas. "No mesmo turno" e diferente de "na mesma chamada de tool": - Mesma chamada de tool = paralelo (proibido nas etapas de revisao) - Mesmo turno = sequencial sem pausa de chat (correto) A unica forma de pausa permitida dentro da Fase 4 e os 7 casos da secao "Quando parar para perguntar" acima. ### Tabela de decisao rapida | Situacao | Acao | |----------|------| | Code Review terminou sem issues novos | Anunciar **Simplify** e seguir | | Simplify terminou sem mudancas | Anunciar **Security Review** e seguir | | Security Review terminou | Gerar resumo consolidado (`4-summary.md`), depois anunciar Fase 5 | | Codex (Fase 2 ou 5) retornou "Seguir" | Anunciar proxima fase e seguir | | Codex retornou "Ajustar" com ajustes internos | Aplicar sozinho, rodar nova rodada de Codex | | Codex retornou "Ajustar" com algum em produto/dado/regra | Pausar so nesse, perguntar | | Codex retornou "Bloquear" | Pausar, discutir | | Plano inclui migration aditiva | Avancar (autorizacao ja dada na Fase 2) | | Plano inclui migration destrutiva | Pausar antes de aplicar, autorizacao especifica | | Pedido inicial era vago e ha 2+ interpretacoes | Pausar, listar opcoes | | Pedido inicial estava claro | Seguir direto, sem perguntar | | Fase 5 retornou "Seguir" | Informar PR pronta, fim do fluxo | --- ## ⚠️ Setup inicial OBRIGATORIO (PRIMEIRA acao apos criar a TodoList) **Esta e a PRIMEIRA acao apos criar a TodoList, ANTES de qualquer fase, ANTES de qualquer pergunta ao usuario.** **Regra:** se voce ainda nao definiu `RUN_DIR`, voce **NAO PODE** salvar planos, revisoes, relatorios ou qualquer arquivo do fluxo. **Toda execucao de `/claudex-dev` comeca gerando um identificador unico** que vai ser usado em todas as fases. Isso evita colisao quando voce roda `/claudex-dev` em terminais paralelos. ```bash # Slug curto baseado no pedido SLUG=$(echo "$PEDIDO" | tr '[:upper:]' '[:lower:]' | tr -cd '[:alnum:]-_ ' | tr ' ' '-' | head -c 30) [ -z "$SLUG" ] && SLUG="task" TIMESTAMP=$(date +%Y%m%d-%H%M%S) # Guard: TIMESTAMP precisa ter formato YYYYMMDD-HHMMSS completo. if ! [[ "$TIMESTAMP" =~ ^[0-9]{8}-[0-9]{6}$ ]]; then TIMESTAMP="$(date +%Y%m%d)-$(date +%s | tail -c 7)$RANDOM" fi # Deteccao de SO — paths configurados via setup.sh, definidos em claudex.config.json case "$(uname -s)" in MINGW*|MSYS*|CYGWIN*) OS_KIND="windows" RUN_DIR_BASE="{{RUN_DIR_BASE_WIN}}" WORKTREE_BASE="{{WORKTREE_BASE_WIN}}" REPO_DIR="{{REPO_PATH_WIN}}" OPEN_CMD="start" ;; Darwin) OS_KIND="mac" RUN_DIR_BASE="{{RUN_DIR_BASE_MAC}}" WORKTREE_BASE="{{WORKTREE_BASE_MAC}}" REPO_DIR="{{REPO_PATH_MAC}}" OPEN_CMD="open" ;; *) OS_KIND="linux" RUN_DIR_BASE="{{RUN_DIR_BASE_LINUX}}" WORKTREE_BASE="{{WORKTREE_BASE_LINUX}}" REPO_DIR="{{REPO_PATH_LINUX}}" OPEN_CMD="xdg-open" ;; esac RUN_DIR="${RUN_DIR_BASE}/${SLUG}-${TIMESTAMP}" WORKTREE_DIR="${WORKTREE_BASE}/${SLUG}-${TIMESTAMP}" BRANCH="feat/${SLUG}-${TIMESTAMP}" mkdir -p "$RUN_DIR" # Sanity check: confirma que o diretorio foi mesmo criado no SO local. if [ "$OS_KIND" != "windows" ] && [[ ! "$RUN_DIR" =~ ^/ ]]; then echo "❌ RUN_DIR nao e caminho absoluto Unix: $RUN_DIR — abort" exit 1 fi [ ! -d "$RUN_DIR" ] && echo "❌ mkdir falhou em $RUN_DIR" && exit 1 # ⚠️ ISOLAMENTO DE SESSAO — CRIAR WORKTREE IMEDIATAMENTE # # Usuarios frequentemente rodam varias sessoes /claudex-dev em paralelo. # O working tree principal ($REPO_DIR) tem UM UNICO HEAD por pasta — se # duas sessoes rodam `git checkout` simultaneamente, uma sobrescreve a outra # (HEAD nao tem locking). Resultado: commits vazam entre branches. # # Solucao: cada execucao do /claudex-dev tem seu proprio worktree (pasta # separada com .git compartilhado, HEAD independente). Criado AQUI no setup, # ANTES de qualquer git command. Nao pode ser adiado para Fase 3. if ! git -C "$REPO_DIR" rev-parse --is-inside-work-tree >/dev/null 2>&1; then echo "❌ $REPO_DIR nao e um repo git valido — abort" exit 1 fi # `fetch` sincroniza referencias do remoto SEM mexer no HEAD do working tree # principal — outras sessoes nao sao afetadas. git -C "$REPO_DIR" fetch --quiet origin main if [ -d "$WORKTREE_DIR" ]; then echo "ℹ️ Worktree ja existe em $WORKTREE_DIR — reusando" else git -C "$REPO_DIR" worktree add "$WORKTREE_DIR" -b "$BRANCH" origin/main \ || { echo "❌ git worktree add falhou — abort"; exit 1; } fi # CWD da sessao = worktree. Todo Bash subsequente roda aqui automaticamente. cd "$WORKTREE_DIR" # Inicializar state.json com fase atual echo '{"phase":0,"step":null,"status":"in_progress","pr":null}' > "$RUN_DIR/state.json" echo "✅ Run setup: OS=$OS_KIND" echo " RUN_DIR=$RUN_DIR" echo " WORKTREE_DIR=$WORKTREE_DIR (branch $BRANCH)" ``` **Anote `SLUG`, `TIMESTAMP`, `OS_KIND`, `RUN_DIR`, `WORKTREE_DIR`, `BRANCH`, `REPO_DIR`, `OPEN_CMD` no contexto da sessao.** Todas as fases vao reusar essas variaveis — nao gere de novo. ### 🔒 Invariante de isolamento (vale em TODAS as fases) Apos o setup inicial, o CWD da sessao **deve sempre** ser `$WORKTREE_DIR`. Nunca `cd "$REPO_DIR"` durante o fluxo (excecao unica: cleanup pos-merge, na Fase 5). Se um comando reseta o CWD (alguns sub-skills fazem isso), **a proxima coisa que voce faz e voltar pro worktree**: `cd "$WORKTREE_DIR"`. Nao "vou rodar so uma coisinha no repo principal" — qualquer git command la quebra o isolamento. Guard rapido no comeco de qualquer fase que tenha duvida: ```bash if [ "$(pwd)" != "$WORKTREE_DIR" ]; then echo "⚠️ CWD desviou: $(pwd) — voltando pro worktree" cd "$WORKTREE_DIR" fi ``` **Comunicacao obrigatoria ao usuario** apos o setup: ``` 🗂️ Run iniciado: - RUN_DIR: BRANCH: ``` Sem essa linha visivel ao usuario, ele nao sabe onde os arquivos do run estao. **Estrutura de arquivos do run:** ``` ${RUN_DIR}/ ├── 0-findbugs-report.md (opcional, Fase 0) ├── 0-debug-browser-report.md (opcional, Fase 0) ├── 0-benchmark.md (opcional, Fase 1 Passo 0 — pesquisa de mercado quando organiza area de negocio) ├── 1-plan.md (arquivo de trabalho — sempre a versao atual) ├── 1-plan-v1.md (snapshot do plano original — nunca modificado) ├── 1-plan-v2.md (snapshot apos rodada 1 de ajustes) ├── 1-plan-v3.md (snapshot apos rodada 2 — se houver) ├── 1-plan-final.md (copia da versao aprovada — usada pela Fase 3) ├── 1-plan-tldr.md (TL;DR do plano final, exibido no terminal) ├── 2-review-r1.md (Fase 2 rodada 1 — markdown do Codex) ├── 2-review-r2.md (Fase 2 rodada 2, se houver) ├── 2-review-r3.md (Fase 2 rodada 3, se houver — max) ├── 2-review-tldr.md (TL;DR consolidado de todas as rodadas) ├── 2-changelog.md (mudancas do plano original ao final, por rodada) ├── 3-smoke-test.md (opcional — se Fase 3 rodou smoke test em backend) ├── 4-summary.md (Fase 4 — resumo consolidado) ├── 5-final-review-r1.md (Fase 5 rodada 1) ├── 5-final-review-r2.md (Fase 5 rodada 2, se houver) ├── 5-final-review-r3.md (Fase 5 rodada 3, se houver — max) ├── 5-final-review-tldr.md (TL;DR exibido) └── state.json (checkpoint — fase/etapa atual) ``` **Acervo entre runs (em `${RUN_DIR_BASE}`, um nivel acima dos runs individuais):** - `_patterns.md` — padroes tecnicos aprendidos (erros recorrentes que o Codex ja corrigiu). Lido no Passo 0 da Fase 1. - `_benchmarks.md` — acervo de benchmark de produto por area de negocio (o que ja descobrimos sobre como o mercado organiza CRM, leads, kanban, envio). Lido e atualizado pelo Passo 0 da Fase 1 (ver `references/fase-1-benchmark.md`). E o que faz o repertorio de produto crescer entre features, em vez de pesquisar do zero toda vez. ## 📍 state.json — checkpoint do fluxo `${RUN_DIR}/state.json` rastreia onde voce esta. **Toda acao com efeito colateral** (chamada Agent, `codex exec`, `gh pr`) **DEVE** comecar lendo este arquivo. **Toda transicao** (entre fases ou entre etapas da Fase 4) **DEVE** atualiza-lo ANTES de prosseguir. **Schema:** ```json { "phase": 4, "step": "code_review", "status": "in_progress", "pr": 285 } ``` - `phase`: 0-5 - `step`: na Fase 4 — `code_review` | `simplify` | `security_review` | `summary` | `completed`. Na Fase 3, quando o diff toca tela — `visual_checkpoint` (gate do print, ver `references/fase-3-implementacao.md`). `null` nas demais fases. - `status`: `in_progress` | `completed` | `blocked` - `visual`: so quando houve checkpoint visual na Fase 3 — `approved` | `skipped_escape` | `blocked_failure`. So commitar UI com `approved` ou `skipped_escape`. - `pr`: numero da PR (a partir da Fase 3) --- ## Fluxo das fases — leia o capitulo certo A SKILL.md tem so o esqueleto. **Para cada fase, leia o arquivo de reference indicado abaixo NO MOMENTO em que entrar nessa fase** (nao antes — economia de contexto): | Fase | Quando entra | Arquivo a ler | |------|--------------|---------------| | 0 | Apos Setup inicial, se houver duvida sobre investigacao | `references/fase-0-investigacao.md` | | 1 | Apos Fase 0 (ou direto, se atalho `--build`) | `references/fase-1-plano.md` | | 2 | Apos plano salvo em `1-plan.md` | `references/fase-2-codex-revisao.md` | | 3 | Apos Codex aprovar plano + usuario aprovar plano final | `references/fase-3-implementacao.md` | | 4 | Apos PR draft criada | `references/fase-4-revisao.md` | | 5 | Apos `4-summary.md` salvo | `references/fase-5-codex-final.md` | **Sequencia padrao em cada fase:** 1. Marcar a tarefa correspondente como `in_progress` na TodoList 2. Ler o arquivo de reference indicado acima (1 Read) 3. Executar os passos da fase conforme o reference 4. Atualizar `state.json` ao terminar 5. Marcar a tarefa como `completed` na TodoList 6. Anunciar "Fase X concluida. Iniciando Fase Y..." e avancar (sem perguntar) --- ## Atalhos O usuario pode pular fases dizendo: - **"sem revisao"** — pula Fase 2 e Fase 5 (implementa direto, sem Codex) - **"so plano"** — executa apenas Fase 1 e Fase 2 - **"so implementa"** / **`--build`** — pula Fase 1-2 (incluindo Passo 0), vai direto pra Fase 3 (quando o plano ja foi discutido) - **"sem brainstorming"** / **`--fiel`** — pula o desenho de comportamento da Fase 1; usa o que ja foi dito - **"sem benchmark"** / **`--no-bench`** — pula o benchmark de produto do Passo 0 da Fase 1; segue pro desenho - **"sem pesquisa"** — pula o Passo 0 inteiro da Fase 1 (benchmark de produto + pesquisa tecnica) - **"sem skills"** — pula a auditoria de boas praticas (Passo 3 da Fase 1) - **"sem print"** / **`--no-shot`** — pula o gate do checkpoint visual na Fase 3 (so pra mudanca de tela trivial) - **"brainstorma isso"** — forca brainstorming mesmo em pedido especifico **Atalhos da Fase 0 (investigacao):** - **`--build`** ou **"so construir"** — pula a Fase 0 inteira, vai direto pra Fase 1 - **`--findbugs`** ou **"caca bug em [arquivo]"** — forca opcao 2 (so `findbugs`), pula a pergunta inicial - **`--debug-browser`** ou **"investiga runtime de [tela]"** — forca opcao 3 (so `debug-browser`), pula a pergunta inicial - **`--full-investigate`** ou **"investiga tudo em [tela]"** — forca opcao 4 (debug-browser + findbugs) Quando um atalho pular uma fase, **ainda marcar a tarefa correspondente como `completed`** na TodoList com nota "pulada por atalho". --- ## Referencia rapida de arquivos ``` skills/claudex-dev/ ├── SKILL.md (este arquivo — esqueleto + setup) └── references/ ├── arquitetura.md (PREENCHIDO PELO USUARIO — schema, paginas, edge functions, componentes) ├── boas-praticas.md (PREENCHIDO PELO USUARIO — convencoes de commit, codigo, etc) ├── fase-0-investigacao.md ├── fase-1-plano.md ├── fase-2-codex-revisao.md ├── fase-3-implementacao.md ├── fase-4-revisao.md └── fase-5-codex-final.md ``` `arquitetura.md` e `boas-praticas.md` sao lidos sob demanda dentro da Fase 1 (planejar) e Fase 3 (implementar). --- ## Ferramentas e ambiente — CONFIGURAR PELO USUARIO **Esta secao e auto-detectada pelo setup, mas o usuario deve revisar.** ### CLIs esperadas | CLI | Uso | |---|---| | `gh` | GitHub (PRs, draft, ready, merge) | | `codex` | Revisao do plano (Fase 2) e revisao final (Fase 5) — OBRIGATORIO | | `git` | Operacoes locais — OBRIGATORIO | | `{{CLI_BACKEND}}` | CLI do seu backend (ex: supabase, firebase, planetscale) — opcional | | `{{CLI_DEPLOY}}` | CLI do seu provedor de deploy (ex: vercel, netlify) — opcional | ### MCPs disponiveis {{MCP_TABLE_PLACEHOLDER}} Os MCPs do seu projeto sao detectados em runtime — usar so os que voce tiver. ### Skills externas opcionais A skill referencia outras skills do ecossistema quando estao disponiveis. Se nao estiverem instaladas, segue sem. | Skill | Quando usar | |---|---| | skill de pesquisa profunda (deep research / funil com fontes) | Fase 1 Passo 0 — benchmark de produto + pesquisa tecnica + confirmar fonte viva externa. Ver `references/fase-1-benchmark.md` | | MCP de search/scrape (se houver) | Fase 1 Passo 0 — varredura leve / raspar URL de benchmark (fallback: jina.ai → WebFetch → anotar lacuna) | | `superpowers:brainstorming` | Fase 1 — pedido vago | | `superpowers:writing-plans` | Fase 1 — gerar plano detalhado | | `code-review:code-review` | Fase 4 etapa 1 | | `simplify` | Fase 4 etapa 2 | | `security-review` | Fase 4 etapa 4 | | `findbugs` (incluida neste plugin) | Fase 0 opcao 2 ou 4 | | `debug-browser` | Fase 0 opcao 3 ou 4 (se instalada) | --- ## Aprendizado entre runs Em `${RUN_DIR_BASE}/_patterns.md` fica um arquivo compartilhado entre runs que acumula padroes que o Codex pediu pra ajustar repetidamente. A Fase 1 le esse arquivo pra evitar erros recorrentes. A Fase 5 atualiza ele apos cada run. Ver detalhes em `references/fase-5-codex-final.md` secao "Padroes recorrentes".