Guias de autoria e pipeline

Tutoriais orientados a tarefas para criar artefatos do Apothem e operar o pipeline de planejamento. Cada guia responde a uma única pergunta concreta.

Para receitas de configuração inicial — adicionar um harness, editar o perfil, operar o instalador — consulte a seção Receitas práticas em vez disso.

Pipeline da suíte de planejamentoCopy Anchor Link

Como refinar conteúdo bruto em uma especificação?Copy Anchor Link

Invoque /plan-spec com o conteúdo bruto como entrada. O papel Forge executa seis fases de transformação (Descoberta, Consideração Meticulosa, Mapeamento de Potência, Verificação de Preservação, Aplicação de Expertise, Varredura de Resolução de Perguntas) e emite a especificação consolidada em .apothem/plans/{suite}/_spec/spec.md. Consulte src/apothem/commands/plan-spec.md para o protocolo completo.

Como gero uma suíte de planejamento a partir de uma especificação?Copy Anchor Link

Invoque /plan-generate .apothem/plans/{suite}/_spec/spec.md depois que /plan-spec tiver gravado a especificação. O gerador emite os arquivos de infraestrutura canônicos, além dos arquivos por fase phases/NN-kebab-topic/PHASE.md. Consulte src/apothem/commands/plan-generate.md.

Como reviso um plano gerado?Copy Anchor Link

Invoque /plan-review path/to/plan-suite/. O revisor aplica as nove técnicas de planejamento e emite scorecards. Scorecards reprovados bloqueiam a execução em SHARED+ até serem resolvidos. Consulte src/apothem/commands/plan-review.md.

Como executo um plano?Copy Anchor Link

Invoque /plan-execute path/to/plan-suite/ [phase-id]. Sem um phase-id, a próxima fase pendente é executada. Com um id específico, apenas essa fase é executada. Consulte src/apothem/commands/plan-execute.md.

Como verifico o status do plano?Copy Anchor Link

Invoque /plan-status path/to/plan-suite/ [--verbose]. Relatório somente leitura. Consulte src/apothem/commands/plan-status.md.

Criando artefatosCopy Anchor Link

Como adiciono uma nova regra?Copy Anchor Link

1. Escolha um nome de arquivo em kebab-case sob src/apothem/rules/, por exemplo src/apothem/rules/my-new-rule.md.
2. Escreva o frontmatter (name, description, pathFilter, alwaysApply).
3. Escreva o corpo com as seções canônicas: Purpose, Obligations, Seriousness Scaling, Anti-Patterns, Enforcement, Bindings.
4. Execute python scripts/dev/validate_ecosystem.py --check frontmatter-cohort para verificar.

O carregador de regras é baseado em glob: ele localiza todo arquivo que corresponda a src/apothem/rules/*.md, então nenhuma entrada de registro é necessária. Basta colocar o arquivo com o nome canônico nesse diretório para concluir o registro.

Como adiciono um novo trabalhador delegado?Copy Anchor Link

Escolha um nome de arquivo em kebab-case sob o diretório mostrado abaixo, usando a forma my-worker.md:

src/apothem/agents/
src/apothem/agents/my-worker.md

Depois:

1. Escreva o frontmatter — incluindo name, version, updated, description, tools, disallowedTools, maxTurns e effort.

2. Escreva o prompt de sistema como o corpo.

O cohort de trabalhadores delegados é carregado por glob a partir de src/apothem/agents/*.md, então o arquivo com o nome canônico é reconhecido ao ser colocado no diretório. Não há tabela de registro para editar.

Como adiciono um novo hook?Copy Anchor Link

1. Escreva uma mensagem de contexto em src/apothem/hooks/messages/<event>-<scope>.md.
2. Conecte o hook em settings.json.
3. Atualize o pipeline de hooks.
4. Execute python scripts/dev/validate_ecosystem.py.

Portões de qualidadeCopy Anchor Link

Como executo os portões de qualidade locais?Copy Anchor Link

python -m ruff check .
python -m ruff format --check .
python -m mypy
python -m pytest -q
python scripts/dev/validate_ecosystem.py
python scripts/dev/chaos_pass.py

O pipeline de CI executa o mesmo conjunto em paralelo.

Como verifico o frontmatter de uma única classe de artefato?Copy Anchor Link

python scripts/dev/validate_ecosystem.py --check frontmatter-cohort