From claudex-forge
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 funcao serverless, refatorar codigo, "manda pro codex", "revisa com codex", "codex review", "abre uma PR", "/claudex-forge". 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. Tambem acionar quando o pedido vier so com os atalhos da skill: --build, --findbugs, --debug-browser, --full-investigate, --fiel, --desafio, --no-bench, --no-shot, "sem revisao", "so plano", "so implementa". NAO acionar para: consultas de dados no banco (usar MCP especifico do projeto), perguntas que nao envolvam codigo, leitura passiva de arquivos.
How this skill is triggered — by the user, by Claude, or both
Slash command
/claudex-forge:claudex-forgeThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
> ⚠️ **Template — exige configuracao**
references/fase-0-investigacao.mdreferences/fase-1-benchmark.mdreferences/fase-1-plano.mdreferences/fase-2-codex-revisao.mdreferences/fase-3-implementacao.mdreferences/fase-4-revisao.mdreferences/fase-5-codex-final.mdscripts/finalize_phase_4.shscripts/log-codex-timing.shscripts/safe-merge.shscripts/scan-hardcode.shscripts/verify-review-fingerprint.sh⚠️ Template — exige configuracao Este plugin foi gerado a partir do template
claudex-forge. Antes de usar, voce precisa:
- Rodar
setup.sh(na raiz do plugin) e preencher as variaveis do seu projeto (claudex.config.json)- Preencher
references/arquitetura.mdcom a arquitetura do seu codebase- Preencher
references/boas-praticas.mdcom convencoes do seu time- Preencher
references/codex-context.mdcom as regras fixas que o Codex le antes de revisarSem isso, a skill nao tem como saber o nome do seu projeto, paths, stack, MCPs disponiveis.
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:
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.
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):
Setup inicial — gerar SLUG/TIMESTAMP/RUN_DIR/WORKTREE_DIR e detectar SOFase 0 — Investigacao (ler references/fase-0-investigacao.md)Fase 1 — Plano: desenhar comportamento + plano + auditoria boas praticas (ler references/fase-1-plano.md)Fase 2 — Revisao do Codex (ler references/fase-2-codex-revisao.md)Fase 3 — Implementacao (ler references/fase-3-implementacao.md)Fase 4 — Revisao e Relatorio (ler references/fase-4-revisao.md)Fase 5 — Revisao final do Codex (ler references/fase-5-codex-final.md)Regras de uso da TodoList:
in_progress ao ENTRAR em cada fase, antes de qualquer Read/Bash/Skill da fase.completed ANTES de avancar para a proxima tarefa.--build pula Fase 0; "sem revisao" pula Fases 2 e 5), marcar a fase pulada como completed com nota "pulada por atalho" no contexto.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.
Aplicar o CLAUDE.md global do projeto, se houver (~/.claude/CLAUDE.md):
Essas regras valem em TODOS os artefatos desta skill (TL;DRs das Fases 1, 2 e 5, body de PR, AskUserQuestion, resumo final). Nao reescrever as regras aqui — referenciar.
Matriz de escalonamento (LEI nesta skill) — o que sobe pro usuario e o que se decide sozinho:
1-plan.md ("decidi X porque Y, reversivel") e deixa os revisores da Fase 2 desafiarem. Perguntar isso so transfere chute pra quem nao tem como julgar.A Fase 4 nao tem TL;DR formatado proprio — usa linha unica de progresso (ver references/fase-4-revisao.md secao "Transicao para Fase 5"). O detalhe rico das 3 etapas vai pro 4-summary.md em disco e aparece consolidado no template final da Fase 5.
FASE 0 (Investigacao opcional) ──→ FASE 1 (Plano: P0 + 3 passos) ──→ FASE 2 (Revisao Codex) ──→ decisao?
│ P0 pesquisa/benchmark (cond.) ↑ │
├─ findbugs (codigo) P1 desenhar comportamento └── Ajustar ─────────────┘
├─ debug-browser (runtime) P2 plano + ancoragem │
└─ pular P3 auditoria boas praticas Seguir ──────────────────┘
↓
FASE 3 (Implementacao) ──→ 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.
Enquanto este fluxo estiver ativo (Fase 0 ate fim da Fase 5), as seguintes regras globais ficam SUSPENSAS:
gh pr create, sempre abrir a URL da PR no navegador" — SUSPENSA. Nao abrir o link da PR no navegador em nenhuma fase exceto 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.
Liberacao: so na Fase 5, apos o Codex retornar "Seguir", roda gh pr ready <PR> (converte draft em pronta) e ai sim $OPEN_CMD <URL> (resolvido por SO no Setup inicial).
Nunca chamar o tool ExitPlanMode em nenhuma fase do fluxo /claudex-forge. O box nativo do Claude Code ("Ready to code? / Here is Claude's plan / Would you like to proceed?") atropela o template da Fase 1 e despeja o plano completo cru no terminal, ignorando o TL;DR formatado (🧨/🔎/⏰/💡/👉).
Por que: o /claudex-forge ja tem checkpoint proprio de aprovacao de plano (Fase 2 final — o usuario aprova o plano final consolidado antes da Fase 3). ExitPlanMode duplica esse checkpoint com formato errado e quebra o fluxo de TL;DR + arquivo separado.
Comportamento correto:
ExitPlanMode em nenhuma fase — o plano sempre vai pra ${RUN_DIR}/1-plan.md + TL;DR formatado no terminal conforme references/fase-1-plano.md.Anti-padrao real (observado em uso): o modelo entrou em plan mode no meio do fluxo e usou ExitPlanMode no fim da Fase 1, exibindo o plano tecnico completo de 200+ linhas no terminal em vez do TL;DR de 5 blocos. Resultado: o usuario nao tinha como ler aquilo em linguagem de diretor.
SEMPRE use ${RUN_DIR}/... com os nomes numerados:
${RUN_DIR}/1-plan.md (arquivo de trabalho) + 1-plan-v<N>.md (snapshots) + 1-plan-final.md${RUN_DIR}/2-review-r<N>.md + 2-changelog.md${RUN_DIR}/3-smoke-test.md (se aplicavel)${RUN_DIR}/4-summary.md${RUN_DIR}/5-final-review.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.
Antes de afirmar algo como verdade ou de seguir com uma decisao, classifique a duvida. As duas metades tem tratamento OPOSTO:
O erro que esta regua existe pra matar e cravar fato sem verificar — causa-raiz de diagnostico errado (ex: cravar "a causa e a integracao externa X" sem testar; era um token vencido que um request de teste pegaria na hora). Ela aumenta a VERIFICACAO de fato, nao o numero de perguntas — esta skill e anti-interrupcao de proposito, e isso continua valendo.
Pause APENAS nestes 7 casos. Em qualquer outra situacao, anuncie a proxima fase e siga.
--build, --findbugs, etc.).references/fase-2-codex-revisao.md secao "Como decidir o que aplicar". Se "Ajustar" com todos ajustes internos, NAO pausar — aplicar sozinho e seguir.fase-2-codex-revisao.md secao "Aprovacao do plano final"."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".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 uso real: 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.references/fase-4-revisao.md.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 → finalize_phase_4.sh). Continuo = sem devolver controle pro usuario entre as etapas.
"No mesmo turno" e diferente de "na mesma chamada de tool":
A unica forma de pausa permitida dentro da Fase 4 e os 7 casos da secao "Quando parar para perguntar" acima.
| Situacao | Acao |
|---|---|
| Code Review terminou sem issues novos | Anunciar Simplify e seguir |
| Simplify terminou sem mudancas | Anunciar Security Review e seguir |
| Security Review terminou | Rodar scripts/finalize_phase_4.sh (1 chamada Bash que gera 4-summary.md, atualiza state, imprime linha de progresso e dispara codex exec da Fase 5) — sua proxima resposta comeca com o tool call, sem texto antes |
| Codex (Fase 2 ou 5) retornou "Seguir" | Anunciar proxima fase e seguir |
| Codex retornou "Ajustar" — TODOS os ajustes internos | Aplicar/rejeitar sozinho, nova rodada no mesmo turno (NAO pausar) |
| Codex retornou "Ajustar" — algum item de produto/dado/regra | Pausar SO nesse item, perguntar em linguagem de diretor |
| Codex retornou "Bloquear" | Pausar, discutir |
| Codex pediu "Ajustar" pela 4a rodada seguida | Pausar (limite de 3 rodadas automaticas estourou) |
| 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 |
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-forge comeca gerando um identificador unico que vai ser usado em todas as fases. Isso evita colisao quando voce roda /claudex-forge em terminais paralelos.
Os valores
{{...}}abaixo sao substituidos pelosetup.shlendoclaudex.config.json. Se voce ainda ve{{...}}literal aqui, o setup nao rodou — pare e rode./setup.shna raiz do plugin.
# Slug curto baseado no pedido. Python translitera acento (NFKD): o `tr -cd` puro APAGA
# acentos ("adicao de campo" virava "adio-de-campo"), e o `iconv //TRANSLIT` do BSD/Mac
# corrompe (mete til, come letras). Python normaliza igual nos 3 sistemas. Pedido vai por
# env var (nao argv/stdin) pra preservar UTF-8.
SLUG=$(PEDIDO_SLUG="$PEDIDO" python3 -c "import os,unicodedata,re; s=unicodedata.normalize('NFKD',os.environ.get('PEDIDO_SLUG','')).encode('ascii','ignore').decode().lower(); print(re.sub(r'[^a-z0-9]+','-',s).strip('-')[:30])" 2>/dev/null)
[ -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
# Fallback no MESMO formato (8 digitos - 6 digitos), senao o nome do run sai fora do padrao
TIMESTAMP="$(date +%Y%m%d)-$(printf '%06d' "$((RANDOM % 1000000))")"
echo "⚠️ TIMESTAMP veio incompleto, ajustado pra: $TIMESTAMP"
fi
# Deteccao de SO — paths configurados via setup.sh, definidos em claudex.config.json
#
# SKILL_DIR_ABS = pasta absoluta DESTA skill (contem scripts/ e references/).
# FONTE DA VERDADE: o "Base directory for this skill" que o harness te informou ao
# carregar /claudex-forge. Se voce tem esse valor, exporte-o ANTES deste bloco
# (`export SKILL_DIR_ABS="<base dir>"`) — o `${SKILL_DIR_ABS:-...}` abaixo preserva ele.
# Os defaults por SO sao so fallback.
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
# SKILL_DIR_ABS — use o "Base directory for this skill" do harness se exportado;
# senao tenta o caminho padrao de plugin instalado do Claude Code.
SKILL_DIR_ABS="${SKILL_DIR_ABS:-$HOME/.claude/plugins/cache/{{REPO_OWNER}}/claudex-forge/skills/claudex-forge}"
RUN_DIR="${RUN_DIR_BASE}/${SLUG}-${TIMESTAMP}"
WORKTREE_DIR="${WORKTREE_BASE}/${SLUG}-${TIMESTAMP}"
BRANCH="feat/${SLUG}-${TIMESTAMP}"
# Sanity check ANTES do mkdir: no Mac, `mkdir -p "D:/..."` criaria pasta
# literal `D:` dentro do CWD sem erro. Checar a string ANTES de criar — depois
# de criada, a pasta errada ja existe e o check nao desfaz nada.
if [ "$OS_KIND" != "windows" ] && [[ ! "$RUN_DIR" =~ ^/ ]]; then
echo "❌ RUN_DIR nao e caminho absoluto Unix: $RUN_DIR — abort (nada foi criado)"
exit 1
fi
mkdir -p "$RUN_DIR"
[ ! -d "$RUN_DIR" ] && echo "❌ mkdir falhou em $RUN_DIR" && exit 1
# ⚠️ ISOLAMENTO DE SESSAO — CRIAR WORKTREE IMEDIATAMENTE
#
# Usuarios frequentemente rodam varias sessoes /claudex-forge em paralelo.
# O working tree principal ($REPO_DIR) tem UM UNICO HEAD por pasta — se duas
# sessoes rodam `git checkout` simultaneamente la, uma sobrescreve a outra
# (HEAD nao tem locking). Resultado ja observado: commits indo parar em
# branches da outra sessao.
#
# Solucao: cada execucao do /claudex-forge tem seu proprio worktree (pasta
# separada apontando pro mesmo .git, com HEAD independente). Criado AQUI,
# no setup, antes de qualquer git command. Nao na Fase 3 — la e tarde demais
# (Fase 0/1/2 ja teriam rodado na pasta compartilhada).
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. Usamos `origin/main` como base
# do worktree pra ele comecar atualizado.
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. O working directory persiste entre chamadas Bash DIRETAS —
# mas sub-skills (code-review, simplify, etc) podem desvia-lo. Por isso existe o
# invariante de isolamento mais abaixo: ao voltar de qualquer sub-skill, conferir o CWD.
cd "$WORKTREE_DIR"
# Inicializar state.json com fase atual
echo '{"phase":0,"step":null,"status":"in_progress","pr":null}' > "$RUN_DIR/state.json"
# ⚠️ GUARD — SKILL_DIR_ABS precisa apontar pra pasta REAL da skill (com scripts/).
# Sem isso o finalize_phase_4.sh (transicao Fase 4 -> 5) aborta com exit 1, e o
# fluxo trava no fim da Fase 4 esperando voce pedir. Falha aqui, alto e cedo:
if [ ! -f "${SKILL_DIR_ABS}/scripts/finalize_phase_4.sh" ]; then
echo "❌ SKILL_DIR_ABS errado: $SKILL_DIR_ABS (nao achei scripts/finalize_phase_4.sh)."
echo " Use o 'Base directory for this skill' que o harness te deu: exporte"
echo " SKILL_DIR_ABS=<base dir> e re-rode o setup inicial."
exit 1
fi
# ⚙️ env.sh — fonte UNICA das variaveis do run. Em vez de cada fase remontar 10
# variaveis na mao (e esquecer SKILL_DIR_ABS — causa-raiz do trava da Fase 4->5),
# elas fazem `source "$RUN_DIR/env.sh"`. Valores ja resolvidos, baked no arquivo.
cat > "$RUN_DIR/env.sh" <<EOF
export SLUG="$SLUG"
export TIMESTAMP="$TIMESTAMP"
export OS_KIND="$OS_KIND"
export RUN_DIR="$RUN_DIR"
export RUN_DIR_BASE="$RUN_DIR_BASE"
export WORKTREE_BASE="$WORKTREE_BASE"
export WORKTREE_DIR="$WORKTREE_DIR"
export BRANCH="$BRANCH"
export REPO_DIR="$REPO_DIR"
export OPEN_CMD="$OPEN_CMD"
export SKILL_DIR_ABS="$SKILL_DIR_ABS"
EOF
echo "✅ Run setup: OS=$OS_KIND"
echo " RUN_DIR=$RUN_DIR"
echo " WORKTREE_DIR=$WORKTREE_DIR (branch $BRANCH)"
echo " SKILL_DIR_ABS=$SKILL_DIR_ABS"
echo " env.sh salvo — fases seguintes fazem: source \"\$RUN_DIR/env.sh\""
Anote SLUG, TIMESTAMP, OS_KIND, RUN_DIR, RUN_DIR_BASE, WORKTREE_BASE, WORKTREE_DIR, BRANCH, REPO_DIR, OPEN_CMD, SKILL_DIR_ABS no contexto da sessao. Todas tambem ficam salvas em ${RUN_DIR}/env.sh — qualquer fase que precise delas faz source "$RUN_DIR/env.sh" em vez de regerar. Isso vale especialmente pra Fase 2, Fase 4 e Fase 5, que dependem de SKILL_DIR_ABS (e era justamente ele que vinha vazio e travava a transicao Fase 4 -> 5).
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:
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: <SLUG>-<TIMESTAMP>
RUN_DIR: <caminho>
BRANCH: <nome>
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)
├── 1-spec-items.md (OBRIGATORIO sempre que houver referencia de design — Figma/print/prototipo; inventario numerado com extracao dupla cega; ausente so em task sem design)
├── handoff-pr-2.md (so quando o run dividiu em 2 PRs — heranca da 2ª PR, escrito ANTES do merge da 1ª)
├── 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 funcao serverless/migration/RPC)
├── 4-summary.md (Fase 4 — input curto pro Codex Fase 5, gerado por finalize_phase_4.sh)
├── 5-final-review.md (Fase 5 — output do Codex; sobrescrito a cada rodada se houver "Ajustar")
├── state.json (checkpoint — fase/etapa atual)
└── env.sh (variaveis do run — fonte unica; fases fazem `source env.sh`)
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, etc). 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.${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:
{ "phase": 4, "step": "code_review", "status": "in_progress", "pr": 285 }
phase: 0-5step: na Fase 4 — code_review | simplify | security_review. (Nao existem steps summary/completed na pratica: o finalize_phase_4.sh fecha a Fase 4 escrevendo direto {phase: 5, step: null} — nao espere encontra-los no state.json.) 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 | blockedvisual: 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)Quando escrever:
{phase: N, step: <primeiro ou null>, status: in_progress}{phase: 4, step: <proxima>, status: in_progress}{phase: N, status: completed} ANTES de anunciar a proximaA 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:
in_progress na TodoListstate.json ao terminarcompleted na TodoListPor padrao a Fase 1 roda o Passo 0 condicional + os 3 passos completos (pesquisa/benchmark → desenhar comportamento → plano + ancoragem → auditoria de boas praticas). O usuario pode pular passos/fases dizendo:
--build — pula o Passo 0 e o Passo 1 (desenho) da Fase 1, vai direto pro plano/implementacao (quando o plano ja foi discutido)--fiel — pula o Passo 1 de desenho de comportamento; usa o que ja foi dito--no-bench — pula o benchmark de produto do Passo 0; segue pro Passo 1--no-shot — pula o gate do checkpoint visual na Fase 3 (so pra mudanca de tela trivial; ver references/fase-3-implementacao.md)--desafio ou "questiona antes" — forca o Claude a desenhar/questionar o comportamento mesmo se a premissa parecer firmeNota: a Fase 1 NAO pergunta "Fiel ou Desafio?" / "decisao fechada ou pode mudar?". Por padrao ela desenha o comportamento (Passo 1, via
superpowers:brainstorming) ANTES de listar arquivos, e audita o plano com as skills da stack (Passo 3) ANTES do Codex. Verreferences/fase-1-plano.md.
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".
skills/claudex-forge/
├── SKILL.md (este arquivo — esqueleto + setup)
├── scripts/
│ ├── finalize_phase_4.sh (encerra Fase 4 + dispara Fase 5 numa unica chamada, com vigia de tempo)
│ └── safe-merge.sh (roda os checks e SO mergeia se todos passarem)
└── references/
├── arquitetura.md (PREENCHIDO PELO USUARIO — schema, paginas, funcoes, componentes)
├── boas-praticas.md (PREENCHIDO PELO USUARIO — conventional commits, regras de codigo, comandos de deploy)
├── codex-context.md (PREENCHIDO PELO USUARIO — contexto fixo do projeto pra Codex; lido pelo finalize_phase_4.sh)
├── fase-0-investigacao.md (Fase 0)
├── fase-1-plano.md (Fase 1)
├── fase-1-benchmark.md (Fase 1 — Passo 0 benchmark de produto)
├── fase-2-codex-revisao.md (Fase 2)
├── fase-3-implementacao.md (Fase 3)
├── fase-4-revisao.md (Fase 4)
└── fase-5-codex-final.md (Fase 5)
arquitetura.md e boas-praticas.md sao lidos sob demanda dentro da Fase 1 (planejar) e Fase 3 (implementar). codex-context.md e lido pelo codex exec automaticamente (ele e passado como path absoluto pro prompt do Codex). A skill checks-local (gate de testes/typecheck) e instalada separadamente como sub-skill do plugin — ver README.
Esta secao e parcialmente auto-detectada pelo setup, mas o usuario deve revisar. O detalhamento da stack vive em references/arquitetura.md e references/boas-praticas.md.
| CLI | Uso |
|---|---|
git | Operacoes locais — OBRIGATORIO |
codex | Revisao do plano (Fase 2) e revisao final (Fase 5) — OBRIGATORIO |
gh | GitHub (PRs, draft, ready, merge, leitura de repo) — OBRIGATORIO. No Mac, se o gh nao estiver logado direto, pegar o token (ex: do Keychain) e usar via GH_TOKEN="$TOKEN" gh .... No Windows/Linux geralmente funciona nativo. |
{{CLI_BACKEND}} | CLI do seu backend (ex: supabase, firebase, planetscale) — opcional, conforme stack |
{{CLI_DEPLOY}} | CLI do seu provedor de deploy (ex: vercel, netlify) — opcional, conforme stack |
{{MCP_TABLE_PLACEHOLDER}}
Os MCPs do seu projeto sao detectados em runtime — use so os que existirem no seu ambiente. Exemplos comuns que valem mapear em boas-praticas.md: MCP do seu backend (migrations, deploy de funcao, leitura de logs), MCP de browser (testar UI), MCP de pesquisa web.
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 Passo 1 — desenhar comportamento/regra de negocio antes do plano (padrao, salvo escape) |
superpowers:writing-plans | Fase 1 Passo 2 — gerar plano detalhado (arquivos, tasks, riscos) |
| skills de boas praticas do seu stack (se instaladas) | Fase 1 Passo 3 + Fase 3 — ex: as oficiais de React, Postgres, Next, etc. Detecte e use so as que existem |
| skill de handoff de design (se instalada) | Fase 1 (porta de entrada) — quando o pedido traz design pronto (Figma/print/prototipo): gera o spec de implementacao ANTES do plano. Sem skill, extrair o spec + inventario numerado manualmente (ver references/fase-1-plano.md, Passo 1) |
frontend-design:frontend-design | Fase 1 — apenas tela nova/redesign grande (NAO pra modificar componente existente, NAO pra implementar design ja pronto) |
code-review:code-review | Fase 4 etapa 1 |
simplify | Fase 4 etapa 2 |
security-review | Fase 4 etapa 3 |
checks-local (sub-skill deste plugin) | Fase 3 (gate antes da PR) + Fase 5 (gate antes do merge) — roda os checks do seu stack local |
findbugs (sub-skill deste plugin) | Fase 0 opcao 2 ou 4 — pipeline de bug (3 fases / 5 agentes) |
debug-browser | Fase 0 opcao 3 ou 4 (se instalada) |
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".
npx claudepluginhub cassianodiniz/cassiano.diniz --plugin claudex-forgeGuides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.