Planf3: a meta-skill de planejamento internalizada

createPlan(userPrompt, options) (packages/planf3/src/index.ts:244–269) materializa plan.html em <outputDir>/<slug>/ (default .alembic/plans/). A decisão central está em generatePlanWithModel (packages/planf3/src/model.ts:69–108): offline ou sem adapters ⇒ undefined — e o chamador cai no template determinístico (defaultPlan, index.ts:148–233); online, roteia para o T2 mais barato via pickAdapter(Tier.T2) (ou o modelo pinado por --model via adapterForModel), pede um JSON no schema planContentSchema (types.ts:15–24: title, purpose, problem, solution, phases[] com min 1, validationCommands, questionables, notes) e valida na borda. O retorno carrega a etiqueta: source: 'llm' | 'fallback'.

// trecho real, não editado
if (options.offline || options.adapters === undefined) {
  return undefined;
}

A robustez online também é defensiva: o texto do modelo passa por extractJsonObject (model.ts:17–35), que varre do último } de trás para frente até o { balanceado — "models wrap JSON in prose or fences, so we scan back… rather than trusting the whole reply" — e o resultado ainda precisa passar no planContentSchema.safeParse. Modelo que devolve lixo vira err tipado, e o comando cai no fallback (index.ts:259–265): o plano SEMPRE existe.

Pense como… um arquiteto com prancheta elétrica e régua-T: se a energia cair (offline), o desenho sai na régua-T — mais padronizado, menos personalizado, mas com TODAS as vistas obrigatórias. Onde quebra: um arquiteto cansado pula seções; o template não pula nunca — as 5 fases (Scope, Design, Build, Proof, Ship) e os 3 comandos de validação (pnpm -r typecheck, pnpm -r build, pnpm -w test) estão sempre lá (index.ts:170–223).

O comando alembic plan "<prompt>" (runPlanCommand, apps/cli/src/commands.ts:2586–2647) não para no HTML. Depois do createPlan, ele chama loadPlanHtml (packages/forge/src/plan-loader.ts:21–44) para EXTRAIR os artefatos do próprio HTML e escreve, lado a lado no plan-dir: GOAL.md (o goal extraído), validation-contract.md ({ version:'1', assertions } — com fallback ['GOAL.md is concrete','tests pass','publish gate clears'] se o plano não listou validação, commands.ts:2618–2623) e alembic.plan.ts (o starter com fases scope/build/proof). Ou seja: a saída de alembic plan é EXATAMENTE a entrada de alembic run --goal … --plan … — e do Scope Gate da lição 11.

O HTML gerado tem seções fixas — purpose, problem, solution, phases (cada fase com goal + checklist), validation (com o lembrete "🔁 The plan is not complete until every command passes", index.ts:135), questionables (opt-in via --questionable) e notes (index.ts:112–143). Essa anatomia não é invenção do pacote: é a skill Planf3 original internalizada — o diretório packages/planf3/skill/ (exportado como skillDir, index.ts:15) carrega o SKILL.md e 5 workflows: create-plan.md, build-plan.md, update-plan.md, update-references.md e image-generation.md.

Honestidade de superfície: o que NÃO está implementado

Duas funções exportadas lançam erro honesto em vez de fingir: updateReferences — "not implemented. No reference index is maintained by planf3 yet" (index.ts:355–359) — e generateImages — "not implemented. Add images manually or use an image-generation skill" (index.ts:367–374). Já updatePlan FUNCIONA: regenera o plano a partir de um change-prompt e sobrescreve o arquivo no mesmo diretório, preservando os irmãos GOAL/contrato (index.ts:333–348).

O pacote carrega seu próprio material didático: 7 imagens em packages/planf3/images/, referenciadas pelo README.md do pacote (linhas 11, 58, 64, 93, 115, 135 e 147). Elas documentam a FILOSOFIA da meta-skill — consulte-as no repositório (esta lição as cita por nome, de propósito, para você abrir as originais):