菜单
Descobre, materializa, revisa, atualiza e remove o conjunto minimo util de agents especializados de um repo alvo ja preparado por stnl_project_context ou, em greenfield, por stnl_project_foundation.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Stack-neutral backend quality guardrail for implementation and review, focused on preserving project architecture, responsibilities, persistence patterns, contracts, transaction boundaries, testability, and basic backend safety.
Backend data persistence quality guardrail for implementation and review, focused on SQL, ORM, NoSQL, cache, migrations, transactions, indexes, query safety, bounded access, and consistency.
Stack-neutral frontend quality guardrail for implementation and review, focused on preserving UI boundaries, service/facade/store usage, component responsibility, form flows, mapping, async lifecycle safety, design system reuse, UI states, contract safety, performance, and testability.
Portable iOS Swift quality guardrail for implementation and review, focused on SwiftUI and UIKit boundaries, state ownership, concurrency safety, lifecycle cleanup, navigation, forms, networking, persistence, design system reuse, platform conventions, and testability.
Levanta contexto factual do projeto e materializa ou ressincroniza docs em docs/core, docs/units e docs/features com modos BOOTSTRAP, RESYNC e TBD_SYNC.
Estrutura a fundacao documental Sentinel de projetos greenfield, inception ou repos novos a partir de documentacao bruta, decisoes explicitas e contratos declarados, priorizando docs/features e preparando handoff futuro para stnl_project_context sem inventar fatos de codebase.
| name | stnl_project_agent_specializer |
| description | Descobre, materializa, revisa, atualiza e remove o conjunto minimo util de agents especializados de um repo alvo ja preparado por stnl_project_context ou, em greenfield, por stnl_project_foundation. |
Ler a base documental consolidada de um repo alvo já preparado por stnl_project_context ou, em greenfield, por stnl_project_foundation, construir um modelo factual intermediário normalizado e materializar, com validação e repair controlado, o conjunto mínimo útil de agents locais no runtime indicado por target.
Esta skill também revisa, atualiza e deleta artifacts locais obsoletos no output gerenciado do target quando forem parte do conjunto gerenciado, mantendo o orchestrator alinhado ao conjunto real de agents presentes e sem referências quebradas para artifacts de agent inexistentes.
Esta skill é um utilitário global. Ela não é um agent do workflow do projeto alvo.
stnl_project_context ou, em greenfield, por stnl_project_foundation, e precisa do primeiro conjunto de agents especializadostarget não existe, está incompleto, está em drift, ou contém artifacts gerenciados staleorchestrator local precisa voltar a refletir apenas os agents realmente materializadostools, remover excesso de privilégio e eliminar drift factual ou estruturalstnl_project_context no repo alvo, ou stnl_project_foundation quando o repo ainda for greenfield/inceptionagent-contract-shape, agent-specialization-quality-gate ou status-gates no repo alvo na v1.github/workflows/, ou qualquer automação confundida com workflow de agentsstnl_project_context já rodou anteriormente no repo alvo, ou stnl_project_foundation já materializou uma fundação greenfield sériadocs/**, especialmente docs/INDEX.md, docs/TBDS.md quando existir, docs/core/*, e os recortes de docs/units/* ou docs/features/* relevantestarget escolhido e, se necessário, limpar referências gerenciadas obsoletas desse mesmo runtimedocs/** como source of truth principal, com prioridade especial para o material consolidado por stnl_project_context ou, em greenfield, por stnl_project_foundationdocs/core/TESTING.md, quando existir, como referência principal da matriz local de harness/checks para validation-eval-designer e validation-runner; quando a base vier de stnl_project_context, pode representar realidade factual observada, e quando a base vier de stnl_project_foundation, deve ser lido como estratégia declarada, expectativa de validação ou baseline documental até evidência observada na codebasetarget opcional, com suporte mínimo a vscode e codex; quando omitido, usar vscode para preservar compatibilidade com o comportamento atualtarget, quando existirem, para revisão de drift, coerência operacional, metadata e stale artifactsallowed_models opcional quando o uso da skill quiser restringir ou ordenar a escolha de model dos agents especializados; quando houver mais de um item, tratar a ordem como mais forte/mais capaz primeiro e mais econômico/objetivo por último, salvo override explícitomodel_policy opcional e avançado para governar a preferência de model por agent, role fina ou defaults de compatibilidade:
reasoning_defaultcoding_defaultexecution_defaultagentsrolesUsar esta ordem de precedência no repo alvo:
docs/**, especialmente o kit consolidado por stnl_project_context ou, em greenfield, por stnl_project_foundationweb, apenas como apoio para especializar stack, integrações, frameworks, padrões ou contexto técnico externo atualweb nunca substitui evidência factual do projeto alvoRegras complementares:
docs/** descreve a verdade documental do projeto alvo; artifacts gerenciados de agents descrevem a materialização operacional local do target e não substituem essa verdade documentaldocs/**docs/**, incluindo caminhos externos de memória de repo ou canais persistentes equivalentesFeature CONTEXT em docs/features/<feature>/CONTEXT.md; documentação compartilhada deve ser tratada como shared canonical docs em docs/core/*, docs/TBDS.md, docs/INDEX.md e superfícies canônicas equivalentes já existentesdocs/**, Feature CONTEXT, shared canonical docs e documentation targets; não introduzir contrato paralelo de memóriastnl_project_foundation, preservar nos agents a diferenca entre declarado, observado, hipotese e TBD; nao transformar contrato esperado em implementacao existentedocs/core/TESTING.md, quando existir, é a referência primária para comandos canônicos, paths manuais aceitos, pré-requisitos e limites de harness dos agents de validação; tratar como factual observado quando a base vier de stnl_project_context, e como estratégia declarada quando a base vier de stnl_project_foundation até confirmação na codebasestnl_project_foundation, seguir rota canônica: se a direção ainda for documental, encaminhar para stnl_project_foundation MODE=REFINE; se a autoridade estiver migrando para a codebase, encaminhar para stnl_project_foundation MODE=HANDOFF e depois para stnl_project_context quando aplicávelweb só depois da leitura séria do projeto e apenas quando contexto externo atual realmente mudar a qualidade da especializaçãoEXECUTION BRIEF, VALIDATION PACK e EXECUTION PACKAGE são handoffs operacionais de rodada. A skill deve preservar essa regra em todo specialized gerado:
execution_brief.md, validation_pack.md ou execution_package.md;edit para planner, validation-eval-designer ou execution-package-designer por causa desses handoffs;orchestrator;workspaceStorage, chat-session-resources, content.txt, scratchpad ou paths temporários de runtime como fonte Sentinel;HANDOFF_MISSING, HANDOFF_INVALID, REQUEST_REPLAY_FROM_ORCHESTRATOR ou REQUEST_REGEN_FROM_OWNER ao orchestrator, sem inventar conteúdo, reabrir escopo ou buscar arquivo temporário.O orchestrator é o único dono da continuidade entre handoffs efêmeros: ele reenvia o handoff se ainda estiver no contexto, chama novamente o owner anterior para regenerar, volta um gate, ou bloqueia se a SPEC canônica não for suficiente.
targettargettarget quando estiverem stale, órfãos ou incoerentes com o conjunto decididoorchestrator alinhado ao conjunto real de agents materializadostargettarget em cada agent especializado do repo alvocoder-backendcoder-frontendcoder-iosdesignerexecution-package-designerfinalizerorchestratorplannerreviewerresyncvalidation-eval-designervalidation-runnerAntes de especializar qualquer agent, a skill deve classificá-lo em uma role class canônica:
router: orchestratorplanning: plannerproof-design: validation-eval-designerexecution-package-design: execution-package-designerexecutor: coder-backend, coder-frontend, coder-iosdesign-contributor: designersemantic-review: reviewerproof-execution: validation-runnerclosure: finalizersync: resyncPara cada role class, a skill deve impor no mínimo:
Regras:
execution-package-design; coders continuam especialistas por stack/projeto, mas executam pacotes explícitosrouter e planning devem ficar deliberadamente mais fracos que os executors em leitura e ferramentasproof-execution, closure e sync não podem compensar gaps upstream com rediscovery amploagent-contract-shapeagent-specialization-quality-gateexecution-lifecyclestatus-gatesContrato obrigatório do bundle interno:
reference/MANIFEST.mdreference/MANIFEST.md e necessários para a rodadatemplates/**, skills/**, ~/.agents/**, filesystem externo ou qualquer cópia fora do bundle instalado da própria skillreference/MANIFEST.md estiver ausente, bloquear com BLOCKED_REFERENCE_BUNDLE_MISSINGreference/MANIFEST.md estiver ausente, bloquear com BLOCKED_REFERENCE_BUNDLE_MISSINGstnl_project_agent_specializer, o arquivo ausente e a ação sugerida: node sentinel.mjs install e node sentinel.mjs doctorReferências internas esperadas devem vir do manifest instalado, incluindo:
reference/agents/reference/templates/codex/AGENTS.mdreference/templates/codex/config.tomlreference/docs/agents/reference/docs/workflow/targettarget define o runtime operacional para o qual a skill vai materializar artifacts no repo alvo.
Targets suportados:
vscode: comportamento compatível com a v1 atual; materializa agents em .github/agents/*.agent.mdcodex: materializa agents em .codex/agents/*.toml, materializa .codex/config.toml e materializa também AGENTS.md na raiz do repo alvoRegras:
target for omitido, usar vscodetarget sempre pertence ao repo alvo, nunca ao repo Sentinel Protocoltarget (vscode ou codex) pode relaxar executor READY/BLOCKED, consumer-side rejection de handoff inválido, runner apenas com artifact validável, ou finalizer com ledger explícito de DONE e resyncvscode usa o shape Markdown com frontmatter operacional em .github/agents/*.agent.mdcodex usa arquivos TOML em .codex/agents/*.toml com o shape próprio de custom agent do Codex, não como espelho do frontmatter endurecido de vscodecodex contém:
namedescriptionmodelmodel_reasoning_effortsandbox_modedeveloper_instructionsmodel é obrigatório em todo custom agent Codex gerenciado; herdar modelo da sessão, picker ou default implícito do runtime não é aceitável para artifacts Sentinel materializadosmodel_reasoning_effort é obrigatório em todo custom agent Codex gerenciado e deve ser derivado da criticidade da role classsandbox_mode é campo opcional documentado do runtime Codex; por política Sentinel, todo custom agent Codex materializado deve serializar sandbox_modesandbox_mode deve ser derivado da role class e da capability real do agent:
read-only para agents que apenas leem, analisam, roteiam, revisam ou desenhamworkspace-write para agents que precisam editar ou executar comandos locaisworkspace-write só libera a capacidade técnica mínima exigida pelo papel; não autoriza absorver responsabilidade fora da rolevalidation-runner usa workspace-write por necessidade de execução local de checks, mas suas developer_instructions continuam proibindo edição, fix, redesign de prova, replanning ou closurefinalizer e resync usam workspace-write porque o contrato atual permite edit para durable documentation em canonical docs under docs/**tools, agents, target, base_agent_version, specialization_revision, managed_artifact e reading_scope_class não fazem parte do shape mínimo obrigatório nativo de codex.codex/agents/*.toml só pode ser emitido quando for opcional, compatível com a configuração suportada pelo runtime Codex e explicitamente separado do shape mínimo nativocodex, essa metadata é convenção interna opcional do protocolo, nunca requisito nativo do runtime Codex, e deve ser omitida quando houver risco de incompatibilidade com o runtimecodex usa também AGENTS.md como instrução de workspace do runtime CodexAGENTS.md do target codex deve nascer do template interno reference/templates/codex/AGENTS.md; nunca criar ou manter um AGENTS.md final no repo Sentinel como source paralela.codex/config.toml do target codex deve nascer do template interno reference/templates/codex/config.toml; nunca criar ou manter uma .codex/config.toml final no repo Sentinel como source paralela.codex/config.toml deve preservar [agents].max_depth = 1; essa profundidade é limite controlado para permitir subagents diretos do root/main somente quando explicitamente autorizados pelo humano (orchestrator e owners sibling/root-level mediados pelo root/main após ROUTE_PACKET) e bloquear nested owner threads abaixo do orchestrator, não autorização para spawn automático ou ampliação arbitrária da cadeia de roteamentotarget; não fixar .agent.md quando target=codexQuando target=codex, a semântica de handoff Sentinel é runtime-native:
Use stnl_spec_manager, Use stnl_project_context, or Use stnl_project_agent_specializer means run that skill/workflow from root/main unless the human also explicitly requests a custom subagent by exact agent name.Use orchestrator, Use planner, Use coder-frontend, Use validation-runner, or another materialized .codex/agents/*.toml name.orchestrator custom subagent is the Sentinel routing controller only inside Explicit Subagent Invocation Mode and owns gate routing and specialist handoffs when explicitly requested.Use orchestrator, routing is parent-mediated: the orchestrator must return a compact ROUTE_PACKET naming the next canonical owner and must not spawn downstream Sentinel owners directly.ROUTE_PACKET, spawns the named owner as a native custom subagent by exact custom agent name, waits for the compact owner result, and returns to orchestrator for the next routing decision.orchestrator must be a minimal, task-scoped routing payload containing only task, repo, SPEC path when applicable, mode, objective, active decisions, and instruction to read applicable AGENTS.md, developer instructions, Sentinel docs/templates, and allowed repository docs/codebase.AGENTS.md, .codex/agents/*.toml, Sentinel source docs/templates, and allowed repo documentation/codebase, not in a full contract pasted into the prompt.ROUTE_PACKET must be compact: STATUS: ROUTE_READY | BLOCKED | TERMINAL, CURRENT_GATE, NEXT_OWNER, REASON, PAYLOAD, and BLOCKER only when real.ROUTE_PACKET must not include full artifacts, full contracts, SPEC/checklist/logs/diffs, or broad transcript history; if a rich current-round handoff is needed, return a compact handoff summary or identifier, not a required file path.ROUTE_PACKET or explicit human request for that exact custom agent name, that is a contract violation.SUBAGENT_AUTH_REQUIRED; include the needed agent, short reason, and the minimum prompt preserving objective/context so the human can rerun with Use <agent>.SUBAGENT_AUTH_REQUIRED for tasks a Sentinel skill/workflow can execute safely in root/main.codex exec, codex, shell, subprocesses, scripts, local CLI calls, or local continuation of another Sentinel role.orchestrator.orchestrator is absent when explicitly requested, root/main cannot spawn the owner named in a valid ROUTE_PACKET, depth/config blocks routing, or the named custom owner agent is unavailable, stop with ROUTING_RUNTIME_BLOCKED.ROUTING_RUNTIME_BLOCKED must include attempted owner, current gate, missing runtime capability or config, and minimum DEV action needed.orchestrator for the next route decision.AGENTS.md Local Notes must stay compact and stable. They may include target repo shape, docs entrypoints, command/gap notes, and local constraints, but must not duplicate the Sentinel contract, SPEC contents, checklists, logs, diffs, or large artifacts.Todo agent Sentinel materializado deve retornar ao parent/root/orchestrator somente o mínimo necessário para decidir o próximo gate.
Formato default de retorno:
STATUS: DONE | BLOCKED | PARTIAL | FAILEDOWNER: <agent-name>GATE: <current gate or next gate>FILES_CHANGED: <paths or none>NEXT_OWNER: <agent-name or none>VALIDATIONS: <command: pass/fail/not-run + short reason>BLOCKER: <only if real blocker>NOTES: <max 3 short bullets>Regras globais:
EXECUTION BRIEF, VALIDATION PACK ou EXECUTION PACKAGE, return compact handoff summary/status without requiring a pathorchestrator devem manter a main chat focused on routing/status deltasmodel e effortTodo agent gerenciado materializado pela skill deve receber model operacional explícito.
Regras comuns:
modeldeveloper_instructions como substituto do campo operacional modelmodel_policy é override opcional avançado; ausência de model_policy não impede materialização quando allowed_models, target e role class bastam para resolver a escolhaallowed_models existir, todo model materializado deve vir dessa listaallowed_models trouxer um único modelo, usar esse modelo em todos os agents e ajustar apenas model_reasoning_effort em codex conforme a roleallowed_models trouxer múltiplos modelos, interpretar a ordem como mais forte/mais capaz primeiro e mais econômico/objetivo por último, salvo model_policy explícita compatívelallowed_models nem hardcodar modelos comerciais específicos na skillallowed_models nem model_policy fornecerem base concreta suficiente para serializar model, bloquear com falta de input de resolução de modelo; não omitir model e não herdar picker/default implícitoResolução default sem model_policy:
router, planning, proof-design, execution-package-design e semantic-review usam o modelo mais forte disponível dentro de allowed_modelsexecutor e design-contributor podem usar modelo mais econômico quando a role e o pacote forem objetivos; com lista ordenada, usar o último modelo seguro da listaproof-execution, closure e sync podem usar modelo mais econômico quando a função for objetiva e o contrato estiver delimitadoEffort por target:
codex deve serializar model_reasoning_effort em todo .codex/agents/*.toml gerenciadohigh: router, planning, proof-design, execution-package-design, semantic-reviewmedium: executor, design-contributorlow: proof-execution, closure, syncvscode e GitHub custom agents devem serializar model no frontmatter .agent.mdvscode e GitHub custom agents não devem serializar reasoning_effort, thinking_effort, model_reasoning_effort ou equivalente no frontmatter; qualquer guidance de effort para esse target deve ser texto não operacional e apenas quando necessáriotemplates/agents/*.agent.md devem ficar com no máximo 28.000 caracteres antes de qualquer especialização local.agent.md gerenciado para VS Code/GitHub continua respeitando o limite documentado de 30.000 caracteres no prompt Markdown do agent; se a especialização não couber, bloquear ou reduzir conteúdo local especializável, nunca remover blocos protocol-fixed ou hardening obrigatóriohandoffs em VS Code/GitHub é suporte opcional futuro; não implementar por default sem uso Sentinel claro e gate segurohooks não devem ser gerados por default; se algum dia forem mencionados, devem permanecer opt-in explícito porque executam comandoscodex devem preferir comentário/header TOML, como # Sentinel managed artifact: true, em vez de campo runtime desconhecido; se essa marca não puder ser preservada com segurança, registrar follow-up e não improvisar chave operacionalSeguir o padrão do projeto não significa copiar dívida técnica.
Todo specialized deve preservar contratos, comportamento público, interoperabilidade, schema, APIs, rotas, fluxos e compatibilidade. Código novo deve usar a melhor prática segura compatível com a versão atual da stack, framework e bibliotecas já usadas no projeto.
Padrões existentes só devem ser seguidos quando forem:
Padrões claramente ruins, frágeis, duplicados, inseguros, acidentais ou legados não devem ser propagados em código novo apenas porque existem no repo.
Essa política não autoriza:
Aplicação por role:
orchestrator: impedir que a rodada vire refactor oportunista, rotear/fatiar quando a solução correta exigir mudança maior, e não tratar legado acidental como source of truthplanner: diferenciar contrato real, padrão intencional e legado acidental; nunca planejar "faça igual ao arquivo X" sem qualificar se aquilo é contrato ou referênciavalidation-eval-designer: validar comportamento e contrato sem exigir copiar desordem existente; identificar falta de harness ou decisão para melhorar sem quebrarexecution-package-designer: declarar OWNED_PATHS, contratos preservados e limites contra refactor amplo; permitir implementação local melhor quando segura; bloquear quando a melhoria correta exigir escopo maiorcoder-backend, coder-frontend, coder-ios: executar apenas o pacote autorizado, escrever código novo com boa prática compatível com a stack atual, não copiar dívida técnica sem necessidade, e bloquear quando a solução segura exigir path ou contrato fora do pacotevalidation-runner: provar contrato, build, test, lint e typecheck conforme disponível; não transformar preferência estética em falha; apontar dívida nova óbvia quando afetar qualidade ou contratoreviewer: reprovar propagação desnecessária de dívida técnica e refactor amplo escondido; separar blocker real de preferência estéticafinalizer: registrar follow-up quando a solução ideal exigir refactor fora do escopo; não transformar dívida descoberta em alteração escondidaresync: atualizar docs apenas quando houver decisão real consolidada; não documentar acidente local como novo padrão canônicotarget como source of truth do artifact especializadoAntes de gerar ou revisar specializeds, a skill deve construir um modelo factual intermediário normalizado a partir de docs/**.
Esse modelo pode ser transitório e não precisa virar artifact persistido no repo alvo, mas a etapa é obrigatória. A geração e o quality gate devem operar sobre ele, não sobre improviso textual.
O modelo intermediário deve capturar, no mínimo:
resyncForma mínima sugerida por claim do modelo:
claimclassevidence_refsscopeaffected_agentsconfidencenotesRegras:
Toda afirmação operacional ou contextual relevante deve ser classificada em uma destas classes factuais antes de entrar nos specializeds:
confirmed_fact
scoped_pattern
project_example
open_tbd
documented_exception
manual_check
Regras operacionais:
project_example nunca pode virar regra globalscoped_pattern nunca pode ser promovido a convenção global sem evidência adicional forteopen_tbd deve preservar seu conteúdo semântico específico; não pode virar texto genérico esvaziadodocumented_exception não pode desaparecer quando for relevante para um agent impactadomanual_check deve permanecer claramente marcado como checagem, não como fato já provadoall, always, must, the project uses, the project never, the standard is ou equivalentes só pode ser usada quando a classificação e a evidência sustentarem esse grau de certezatargetvscode: output de agents em .github/agents/*.agent.mdcodex: output de agents em .codex/agents/*.toml, runtime config em .codex/config.toml e output complementar em AGENTS.mdvscode: <agent>.agent.mdcodex: <agent>.tomlvscode: basename do arquivo sem .agent.md == frontmatter.name == referência em orchestrator.agentsvscode, frontmatter.name é ID lógico canônico operacional em kebab-case; nunca usar title-case, display label ou versão humanizada nesse campotemplates/agents/*.agent.md e no bundle instalado reference/agents/*.agent.md, frontmatter.name também deve ser exatamente o basename sem .agent.md; labels humanos pertencem somente ao heading Markdown, descrição ou corpoagent-contract-shape como referência de governança do shape especializadovscode, manter frontmatter operacional especializado compatível com o contrato canônico e com a materialização local:
namedescriptiontargettoolsagents no orchestratormodelbase_agent_versionspecialization_revisionmanaged_artifact: truecodex, preservar o shape Sentinel obrigatório adotado para o runtime:
namedescriptionmodelmodel_reasoning_effortsandbox_modedeveloper_instructionscodex, o shape Sentinel materializado adiciona obrigatoriamente model, model_reasoning_effort e sandbox_mode como campos suportados pelo runtime e obrigatórios por política Sentinelcodex, developer_instructions é o lugar obrigatório para carregar a missão especializada, role class, ownership, gates, sequencing, handoffs, disciplina de superfície, limites de leitura e regras operacionais derivadas dos base agents e do modelo factual intermediáriovscode, specialization_revision começa em 1 na primeira materialização gerenciada do repo alvovscode, managed_artifact: true é a marca de overwrite seguro e da deleção segura de artifacts gerenciadosvscode, managed_artifact: true também significa que update é reconstrução gerenciada a partir do template/base agent canônico atual, não patch incremental do corpo antigocodex, qualquer marca de gerenciamento do Sentinel é convenção interna opcional e não faz parte do shape mínimo obrigatório do runtime; se for serializada, deve ser compatível com Codex e claramente distinguida de requisito nativocodex, comentário/header gerenciado equivalente como # Sentinel managed artifact: true tem a mesma força: o TOML deve ser re-renderizado a partir do base agent/template atual, preservando somente inputs locais permitidos pelo contratoreading_scope_class somente como hint compatível com o contrato base; nunca usá-lo para expandir a classe permitidavscode, tools no frontmatter operacional é obrigatório nos agents especializados materializados e é a source of truth operacionalcodex, tools não é obrigatório nem deve ser serializado no TOML controlado; a política de tools e least privilege deve ser preservada semanticamente em developer_instructions e em sandbox_mode## Tools no corpo deve ser removido por default quando tools existir como metadata operacional suportada pelo target## Tools só pode permanecer por ordem humana explícita e com justificativa humana clara## Tools permanecer como exceção explícita, ele nunca pode ser tratado como source of truth, requisito operacional, critério de validação ou base para drift detectionvscode materializado deve conter name, description, target, tools, base_agent_version, specialization_revision e managed_artifact: truevscode materializado deve conter modelvscode materializado deve conter reasoning_effort, thinking_effort, model_reasoning_effort ou equivalente no frontmatter operacionalvscode materializado deve serializar name a partir da mesma fonte de verdade usada para o nome físico do arquivo; exemplo: .github/agents/planner.agent.md deve conter name: plannerorchestrator em vscode deve conter adicionalmente agentsagents no frontmatter operacional é reservado ao orchestrator em vscode e deve listar apenas os frontmatter.name canônicos dos subagents realmente materializados no output de agents do mesmo targetcodex, agents não é campo obrigatório do TOML do orchestrator; o conjunto de subagents e o roteamento devem aparecer em developer_instructions e no AGENTS.md gerado, salvo suporte explícito do runtime para campo equivalente opcionalcodex, o AGENTS.md deve explicitar que a main/root Codex session é a human-visible workspace entrypoint, não spawna custom subagents automaticamente, trata Use stnl_* como skill/workflow no root/main e só cria custom subagent quando o humano pedir por exact custom agent name; não depende de full-history fork, envia somente payload mínimo/task-scoped quando houver autorização explícita, bloqueia com SUBAGENT_AUTH_REQUIRED quando a tarefa exigir subagent sem autorização explícita, e bloqueia emulação de handoff por prompt com contrato completo, codex exec, shell, subprocesso, script, local CLI call ou continuação localcodex, o orchestrator deve explicitar em developer_instructions que é o routing controller do fluxo Sentinel no Codex somente quando explicitamente invocado, é route decision owner e não spawn executor dos downstream owners em Codex visual mode, retorna ROUTE_PACKET compacto para root/main, never use codex exec, never use shell/subprocess/script/local continuation to simulate handoff, never accept full Sentinel contract prompt replay as native handoff, never absorb downstream Sentinel roles locally, reporta ROUTING_RUNTIME_BLOCKED quando há autorização explícita mas a runtime não cria a agent thread nativa necessária, quando root/main não consegue spawnar o owner nomeado no ROUTE_PACKET, em limitação de runtime/UI/depth ou agente ausente, e não absorve papéis especialistascodex, todo agent não-orchestrator deve explicitar em developer_instructions: must not spawn downstream Sentinel agents, must not call codex exec for handoff, must not use shell/subprocess/script to perform handoff, return owned artifact/status/formal handoff signal to root/main for parent-mediated orchestrator routing, e que "handoff to X" means a formal signal for root/main-mediated orchestrator routing, not direct spawningcodex, todo .codex/agents/*.toml e o AGENTS.md devem carregar Compact Agent Return Contract, instruindo que subagent returns sejam compactos, gate-oriented, sem despejar contrato/SPEC/checklist/logs/diffs/artifacts completos no chat, e que detalhes expandam somente em blocker, falha, evidência crítica de validação ou pedido humano explícitomodel na metadata operacional é obrigatório como string única; lista priorizada só deve ser usada quando o target suportar explicitamente esse shape, houver justificativa operacional clara e todos os itens respeitarem allowed_modelsagent_version deve ser removido da metadata operacional final por default; não faz parte do shape endurecido preservado por esta skill nem do shape mínimo de codextargetsurface discipline, delta-only communication, no operational narration, no artifact dump into main chat, e delegate-first quando o papel exigir issovscode contém apenas:
namedescriptiontargettoolsagents no orchestratormodelbase_agent_versionspecialization_revisionmanaged_artifact: truereading_scope_class apenas quando fizer sentido e continuar compatível com o contratocodex final normalizado contém .codex/agents/*.toml, .codex/config.toml e AGENTS.mdcodex contém obrigatoriamente:
namedescriptionmodelmodel_reasoning_effortsandbox_modedeveloper_instructionssandbox_mode é obrigatório por política Sentinel no TOML Codex final, não por fazer parte do shape mínimo nativo Codex.codex/config.toml final normalizado deve ser gerado a partir do template interno, conter comentário gerenciado, conter [agents], conter max_threads = 6 e conter exatamente max_depth = 1codex pode conter campos opcionais adicionais somente quando forem suportados pelo runtime e não confundidos com requisito nativo mínimocodex, quando existirem, devem ser claramente classificadas como internas e removíveis sem quebrar o custom agent TOML mínimovscode, o corpo especializado final deve preservar headings e seções canônicas do base agent, inclusive ## Handoff, sem variantes frouxas de naming ou shapecodex, developer_instructions deve preservar a semântica operacional dessas seções e deve preservar headings Markdown quando eles forem marcadores protocol-fixed exigidos por gateConsistency without legacy propagation: se a fonte trouxer uma linha isolada Consistency without legacy propagation:, reparar essa linha para ## Consistency without legacy propagation; se o heading canônico já existir, remover somente essa linha legada com : para não duplicar o marcadormodel, model_reasoning_effort, sandbox_mode, não pode adicionar campos TOML e não pode mexer em metadata operacional fora do marcador fixo## Consistency without legacy propagation e zero ocorrências da linha legada Consistency without legacy propagation:Agents materializados são artifacts gerenciados, não documentos locais autoritativos do contrato Sentinel.
Quando um artifact existente indicar managed_artifact: true em vscode ou marca gerenciada equivalente em codex:
reference/MANIFEST.mdalready currentbase_agent_version, specialization_revision, model ou metadata nunca é update suficiente quando o corpo canônico mudoualready current somente quando a comparação final provar que nenhum arquivo gerenciado mudou e que todos os snippets protocol-fixed do template/base agent atual aparecem no artifact final do targetÁreas de customização local:
## Project specialization em agents VS Code/GitHub ou Local Notes compactas em AGENTS.md CodexCritério prático: depois de qualquer update gerenciado, comparar o artifact final contra o template/base agent atual e falhar o quality gate se status antigos, headings antigos, handoffs obsoletos ou blocos protocol-fixed antigos sobreviverem fora de slots permitidos.
Os blocos abaixo são parte fixa do protocolo, não são conteúdo local do projeto e não podem ser resumidos, removidos, enfraquecidos, reescritos do zero prático ou substituídos por paráfrase incompleta durante a especialização:
Terminal handoff contract, No other terminal handoff is valid, exigência de status terminal explícito READY ou BLOCKED, evidência real de mudança aplicada para READY, e rejeição de handoff ausente, implícito, ambíguo, intermediário, narrativo, log operacional, promessa ou diff parcialPartial-edit blocking, BLOCKED obrigatório quando houve edição parcial sem conclusão segura, motivo objetivo, arquivos tocados, parcialidade restante, e decisão inspectable/reusable-or-discard/reexecuteInvalid terminal formsEXECUTOR_HANDOFF_INVALID, rejeição forte de handoff ausente, implícito, ambíguo, intermediário, narrativo, log operacional, promessa, diff parcial ou READY sem evidência aplicada, e bloqueio da rodada sem chamar validation-runnerEntry evidence gate, exigência de valid executor READY handoff com evidência aplicada, e preservação de que output inválido não é validation targetclosure ledger, DONE: yes ou DONE: no, racional da decisão de DONE, resync: yes ou resync: no, racional da decisão de resync, delta factual quando resync for necessário, e Invalid closure formsREADY/BLOCKED) e verdict do runner (PASS/PARTIAL/FAIL/BLOCKED), preservando o verdict como input e sem transformar DONE em obrigatório; obrigatória é a decisão explícita DONE: yes ou DONE: noConsistency without legacy propagation, Do not copy fragile, duplicated, insecure, accidental, or legacy project patterns into new code just because they exist. e This policy does not authorize broad refactorsEstratégia obrigatória de especialização:
vscode, os marcadores protocol-fixed devem permanecer no corpo final do agent materializadocodex, os marcadores protocol-fixed devem permanecer em developer_instructionsConsistency without legacy propagation deve permanecer como heading canônico exato ## Consistency without legacy propagation; nunca substituir por Consistency without legacy propagation:, título solto, bullet, resumo ou heading de outro nívelConsistency without legacy propagation:, a geração deve reparar somente esse marcador para ## Consistency without legacy propagation antes da validação final: ou contiver zero/mais de uma ocorrência do heading canônicoreference/agents/*.agent.md instalado e artifact final materializado do target; se a fonte contém um bloco protocol-fixed e o artifact final não contém as frases sentinela correspondentes, a rodada deve falharO quality gate final deve validar os artifacts materializados finais contra esses invariantes protocol-fixed. Validar só frontmatter, shape, model, tools, ausência de TODO ou referências a agents ausentes não basta.
allowed_models e model_policyallowed_models; quando presente, ela é a lista autorizada e ordenada de modelos que podem ser materializadosmodel_policy granular e compatível como override avançado, não como requisito diárioagents: mapa por agent lógico, por exemplo coder-backendroles: mapa por role fina, por exemplo specialist_executor, proof_execution, closurereasoning_defaultcoding_defaultexecution_defaultallowed_models for fornecido, toda escolha de model para specializeds deve ficar restrita a essa listamodel fora de allowed_modelsmodel_policy for fornecido, ele tem precedência sobre heurística implícita, mas nunca substitui a obrigação de serializar o campo final modelmodel_policy.agents[agent_name]model_policy.roles[fine_role]round_coordinator: orchestratorcut_planning: plannerproof_design: validation-eval-designerexecution_package_design: execution-package-designerspecialist_executor: coder-backend, coder-frontend, coder-iosux_direction: designersemantic_review: reviewerproof_execution: validation-runnerclosure: finalizersync: resyncreasoning_default: orchestrator, planner, validation-eval-designer, execution-package-designer, reviewer, e designer quando materializado como contributor de direção UX/designcoding_default: coder-backend, coder-frontend, coder-iosexecution_default: validation-runner, finalizer, resyncmodel_policy indicar valor fora de allowed_models, a skill deve bloquear ou escolher alternativa segura explicitando isso no outputallowed_models existir, aplicar a política interna por role class:
allowed_models tiver apenas um modelo, todos os agents usam esse modeloallowed_models nem model_policy com valores concretos de modelo, bloquear a materialização e reportar falta de input de resolução; não omitir model e não deixar o runtime usar picker/default implícitomodel só deve ser usada quando o target suportar explicitamente esse shape, houver justificativa operacional real, ordem explícita e todos os itens estiverem contidos em allowed_models quando essa entrada existirstnl_project_context ou, em greenfield, por stnl_project_foundation.target; se omitido, assumir vscode; se for desconhecido, bloquear antes de escrever.docs/**, com prioridade para docs/INDEX.md, docs/core/*, docs/TBDS.md quando existir, e os units ou features relevantes.reference/MANIFEST.md; depois ler apenas os templates/base agents canônicos, os templates reference/templates/codex/AGENTS.md e reference/templates/codex/config.toml quando target=codex, e as referências agent-contract-shape, agent-specialization-quality-gate, execution-lifecycle e status-gates que estiverem listados no manifest e forem necessários para a rodada.target, classificando cada artifact local como:
managed and currentmanaged but driftedmanaged but obsoleteunmanaged / ambiguousmodel operacional de cada agent, aplicando model_policy quando existir, respeitando allowed_models quando essa entrada existir, e bloqueando se não houver base concreta para serializar model.target; antes de escrever o artifact final, aplicar a normalização protocol-fixed limitada que preserva ## Consistency without legacy propagation e repara somente a variante legada com :.target=codex, gerar ou atualizar .codex/config.toml a partir do template interno e gerar ou atualizar AGENTS.md do repo alvo a partir do template interno e do conjunto final de agents materializados.orchestrator por último, para que ele reflita apenas o conjunto final realmente materializado e respeite o budget de router.NEEDS_FIX, reparar somente os arquivos sinalizados, reexecutar o gate e concluir apenas quando o conjunto estiver consistentemente validado ou honestamente bloqueado.docs/**O discovery deve ser suficiente para montar o modelo factual intermediário sem virar scan amplo por inércia.
Leitura mínima esperada:
docs/INDEX.mddocs/core/* relevantes para boundaries, stack, runtime, regras e testingdocs/TBDS.md quando existirdocs/units/* e docs/features/* apenas nos recortes que realmente alimentam a decisão do conjunto de agents ou a especialização dos artifactsDurante o discovery:
validation-eval-designer ou validation-runner entrarem no conjunto, ler docs/core/TESTING.md se ele existir e mapear comandos canônicos, suites, manual paths aceitos, confiança do harness, gaps e pré-requisitos para o modelo factual intermediário, qualificando a força semântica pelo tipo de base (stnl_project_context: observado/factual; stnl_project_foundation: declarado/estratégico até observação)security, performance, migration/schema ou observability/release safetyDecidir por evidência factual do projeto alvo, não por completude estética.
Se a especialização puder prosseguir honestamente, o conjunto local normalmente precisa de uma espinha dorsal coerente:
orchestratorplannerfinalizerAdicionar resync quando o projeto mantém shared canonical docs fora da feature e essa sync local fizer sentido.
stnl_project_context, resync costuma fazer sentido, mas ainda depende de evidência real de documentação canônica viva e recorrente fora do fluxo imediato da featurestnl_project_foundation, resync não é default e não deve ser materializado só porque docs/** existestnl_project_foundation, só materializar resync quando houver evidência concreta de shared canonical docs contínuas cross-feature/cross-round, com necessidade real de factual sync fora da feature e updates documentais transversais previsíveisstnl_project_foundation, não considerar sinal suficiente por si só: existência de docs/core/*, existência de docs/TBDS.md, organização inicial de features/units, ou simples possibilidade futura de driftresyncresync; ausência desse agent nesse estágio não é falha do conjunto localcoder-backend quando houver APIs, serviços, domínio, persistência, jobs, integrações, auth, runtime server-side ou equivalentescoder-backend quando o projeto for genuinamente sem camada server-side relevantecoder-frontend apenas quando houver front-end web, web app, browser client UI, pages, screens, design system, ou outra superfície client-side tradicional realcoder-frontend em projetos sem front-endcoder-ios apenas quando houver boundary nativo iOS real no workflow local, centrado em Swift e SwiftUI, com superfície materializada em navegação do app, state/view models, async/await, networking, persistência local, integrações do app, ou testes iOSUIKit interop como evidência complementar para coder-ios, não como centro default do papel; ele só entra quando o repo já o materializa ou quando o cut exigir compatibilidade realcoder-ios em projetos sem app iOS nativo real, e não presumir que todo mobile pertence a coder-frontendDepois de decidir o conjunto final de agents, montar uma lista de stack quality guardrails ativas a partir da superfície real do repo e dos agents materializados. Essa lista deve ser aplicada antes de serializar qualquer artifact final, tanto para vscode quanto para codex.
Regras:
stnl_frontend_quality quando houver front-end web/browser, UI client-side, design system, componentes, telas ou coder-frontend materializadostnl_backend_quality quando houver API, serviços, domínio, jobs, integrações, auth, runtime server-side ou coder-backend materializadostnl_backend_sql_quality quando houver persistência, data access, query, ORM, NoSQL, cache, migrations, transaction, indexes ou package/cut que toque essa superfíciestnl_mobile_ios_swift_quality somente quando houver superfície nativa iOS real reconhecida no repo, centrada em Swift/SwiftUI/UIKit, ou quando coder-ios for materializadocoder-ios não for materializado, remover stnl_mobile_ios_swift_quality dos agents finais especializados; notas como "native iOS is out of scope" podem permanecer, mas a guardrail iOS não pode aparecer como lente ativa, opção de ativação, proof obligation, review ou closurestnl_mobile_ios_swift_quality dos templates/base agents canônicos nem das skills fonte oficiaiscoder-ios materializado, preservar a guardrail iOS e não podar referências necessárias ao workflow nativo iOS.github/agents/*.agent.md, às developer_instructions de .codex/agents/*.toml, ao AGENTS.md Codex quando ele listar agents, e a qualquer lista operacional do orchestratordesignerClassificar designer em um destes níveis:
REQUIRED
Tipo: APPDEFAULT
Tipo: FETipo: FS com frontend relevanteDEFAULT se houver evidência explícita de que a UI é meramente utilitária, sem complexidade de fluxo, sem componentização relevante, e sem preocupação recorrente com responsividade, acessibilidade ou consistência visualON_DEMAND
Tipo: BEdesigner só entra por gatilho explícito no cut ou no workflow local:
Regra de desempate:
APP ou FE, na ausência de evidência forte para excluir, preferir DEFAULT => materializarTipo: APP com navegação, componentes próprios e superfície visual principal do produto -> REQUIRED
designer no projeto é obrigatórioTipo: FE com múltiplas telas, componentes reutilizáveis e fluxo de usuário relevante -> DEFAULT
Tipo: FE administrativo simples, com UI utilitária e baixo risco de UX -> DEFAULT
Tipo: FS com backend dominante, mas frontend relevante no produto -> DEFAULT
Tipo: BE sem UI real no repo -> ON_DEMAND
ON_DEMAND
Nota operacional:
designer no projeto não implica acioná-lo em todo roundDEFAULT, ausência de evidência forte para excluir não é justificativa válida para omissãoTratar validation-eval-designer e validation-runner como um par por padrão.
Materializar o par quando houver evidência de pelo menos um destes sinais:
Evitar materializar só um deles sem justificativa forte e explicitada.
Se o projeto for tão simples que a separação de design de validação e run de validação não se sustente por evidência, não inventar versões cosméticas desses agents. Nesses casos, bloquear ou reduzir o conjunto com justificativa factual clara, sem deixar handoffs quebrados.
Materializar execution-package-designer sempre que o conjunto local materializar qualquer coder (coder-backend, coder-frontend ou coder-ios) junto com validation-eval-designer.
Esse agent ocupa a etapa canônica entre validation-eval-designer e os coders. Ele:
EXECUTION BRIEF e VALIDATION PACKEXECUTION PACKAGEorchestratorNão materializar execution-package-designer como ornamento quando o conjunto local não tiver coders executores. Se coders existirem sem package designer, o conjunto fica incoerente porque obriga coders baratos a reinterpretar arquitetura, boundaries e proof.
Materializar reviewer quando o workflow local se beneficia de review técnico cut-scoped além da proof do runner, especialmente em mudanças estruturais, boundary-sensitive, refactors relevantes, impacto transversal ou alteração importante de contratos internos.
O reviewer não substitui validation-runner, não substitui finalizer e não deve ser inventado como ornamento para cuts triviais.
A skill deve preservar, nos specializeds materializados, o suporte a trilhas condicionais de security, performance, migration/schema e observability/release safety sem criar novos agents obrigatórios nem novos status.
Regras:
orchestrator explicitar a trilha ativa no handoff e no desenho da rodada, sem transformar o router em analista pesado ou executor dessa trilhavalidation-eval-designer converter a trilha ativa em obrigações cut-scoped de prova dentro do VALIDATION PACK, sem virar registry genérico de riscoreviewer verificar se risco estrutural material dessas trilhas foi ignorado, sem transformá-lo em especialista dedicado nem em substituto do runnerVALIDATION PACK, validation-runner e reviewerA skill deve materializar de forma explícita a diferença entre falta de testes em mudança simples/local e falta de testes em mudança com risco relevante.
Regras:
NEEDS_DEV_DECISION_HARNESSVALIDATION PACK, mas não bastam sozinhos para marcar o cut como execution-ready quando a prova crítica da superfície de risco continua sem cobertura mínimavalidation-eval-designer para atualizar o VALIDATION PACK; se a decisão alterar materialmente o cut, deve voltar primeiro ao planner para atualizar o EXECUTION BRIEF e só depois ao validation-eval-designervalidation-eval-designer para registrar no VALIDATION PACK a limitação aceita, a prova faltante, a evidência substituta, o risco residual e que a escolha foi decisão explícita do DEVplanner para recortar o novo cut e depois regenerar o VALIDATION PACKNão omitir um agent se essa omissão deixar outros agents com referências quebradas ou exigir distorção do contrato canônico para compensar.
Antes de remover um agent canônico do conjunto local:
targettarget contra:
docs/**agent-contract-shapeagent-specialization-quality-gatestatus-gatesdocs/core/TESTING.md, com força factual condicionada à origem da base documentaltarget, tools, agents e model em vscode, ou developer_instructions em codex## Handoff## Tools do corpo por default quando tools já existir na metadata operacional suportada pelo target, salvo exceção humana explícita e justificadaagent_version, salvo instrução humana explícita em sentido contráriovscode, incrementar specialization_revision; em codex, só incrementar metadata equivalente se ela existir como convenção interna opcional compatíveltarget, tiver shape compatível e indicar managed_artifact: true ou marca gerenciada equivalente, tratar como artifact gerenciado e reconstruir com overwrite seguro a partir do template/base agent canônico atualDeletar apenas quando houver evidência suficiente de que o artifact local gerenciado se tornou obsoleto.
Casos típicos:
orchestrator aponta para um agent que não deve mais existirRegras: