Especificação do schema de artefatos

Templates de frontmatter YAML por classe e campos obrigatórios para todos os artefatos do ecossistema Apothem.

Fonte da verdade. O contrato legível por máquina, imposto pelo conformity gate, são os JSON Schemas por classe em src/apothem/schemas/ (agent.schema.json, command.schema.json, skill.schema.json, …). Os schemas de skill e de comando declaram additionalProperties: false, de modo que rejeitam chaves desconhecidas; os schemas de agente, de output-style e de plano declaram additionalProperties: true. Esta página e frontmatter-schema.mdx são as duas projeções legíveis por humanos desses schemas — esta página traz os templates e exemplos práticos por classe, e frontmatter-schema, o índice conciso de chaves obrigatórias. Quando uma página divergir dos JSON Schemas, os schemas prevalecem.

Visão geralCopy Anchor Link

Todos os artefatos na árvore de código-fonte do Apothem (sob src/apothem/ e na superfície de configuração raiz) devem incluir um bloco de frontmatter YAML (entre delimitadores ---) com campos obrigatórios e opcionais específicos do seu tipo de artefato. Este documento define o schema canônico de cada tipo.

Regras universais:

• O frontmatter está em conformidade com YAML 1.2
• Todos os valores de string usam aspas duplas, e uma string vazia é escrita como ""
• Ordem dos campos: campos obrigatórios primeiro, campos opcionais agrupados por relevância
• Comentários no frontmatter usam # seguido de espaço: # comment
• Valores de caminho devem ser relativos (sem / inicial) e usar barras normais (/) para compatibilidade entre plataformas

Convenção de versionamento (classes de artefato versionadas — comandos, auxiliares, skills, CLAUDE.md):

• version é semântica (MAJOR.MINOR.PATCH). Incremente MAJOR para mudanças incompatíveis de schema ou de contrato; MINOR para mudanças aditivas compatíveis (novos campos opcionais, seções adicionais, antipadrões adicionais); PATCH para uma mudança de comportamento que corrige uma diretiva existente sem quebrar o contrato.
• Correções de erro de digitação, correções de link, formatação e edições somente de comentário ou somente de documentação deixam version inalterada. Somente uma mudança de comportamento a incrementa.
• updated é a data ISO 8601 (YYYY-MM-DD) da edição mais recente. Ela deve mudar a cada incremento de version, e também muda em uma correção de digitação ou de link que não incrementa a versão.
• Artefatos novos começam em v0.Y.Z. A promoção para vX.Y.Z indica que o contrato do artefato é estável o bastante para ser um compromisso público.
• As suítes de planejamento estão fora desta convenção. Uma correção de digitação em uma suíte de planejamento incrementa o número PATCH da versão da suíte (vX.Y.Z para vX.Y.(Z+1)) e acrescenta uma linha no Histórico de revisões. O guia do desenvolvedor descreve a regra das suítes de planejamento na sua seção de revisões da suíte de planejamento.

Schema: regrasCopy Anchor Link

Padrão de caminho: src/apothem/rules/*.md

Propósito: Mandatos comportamentais e diretivas operacionais.

Campos obrigatóriosCopy Anchor Link

---
name: "kebab-case-identifier"
description: "One-line description"
pathFilter: "**/*.py, **/*.toml"
alwaysApply: true | false
---

Campos opcionaisCopy Anchor Link

As regras não têm campos opcionais de frontmatter e — ao contrário das outras classes de artefato — também não têm os campos version / updated / scope / portability. Os quatro campos obrigatórios acima são o contrato completo de frontmatter de regras imposto por frontmatter_grep.

ExemploCopy Anchor Link

---
name: "operational-mandates"
description: "Behavioral definitions for CM-1 through CM-10: violation indicators and recovery actions"
pathFilter: ""
alwaysApply: true
---

# Rule: Operational Mandates
...

Schema: comandosCopy Anchor Link

Padrão de caminho: src/apothem/commands/*.md

Propósito: Definições de comandos de barra (/plan-execute, /freshify etc.).

Campos obrigatóriosCopy Anchor Link

---
name: "command-name"
version: "MAJOR.MINOR.PATCH"
updated: "YYYY-MM-DD"
description: "What this command does"
argument-hint: "[argument-pattern]"
disable-model-invocation: true | false
portability: "universal"
allowed-tools: "Read, Glob, Grep"
---

Campos opcionaisCopy Anchor Link

Os comandos não têm campos opcionais de frontmatter — os oito campos obrigatórios acima são o contrato completo de frontmatter de comandos imposto por command.schema.json (additionalProperties: false).

ExemploCopy Anchor Link

---
name: "plan-execute"
version: "X.Y.Z"
updated: "2026-04-20"
description: "Executes a specific phase from a Master Plan Suite with conformity checking and quality gates"
argument-hint: "[path/to/plan-suite/] [phase-id] [--dry-run]"
disable-model-invocation: true
portability: "universal"
allowed-tools: "Read, Glob, Grep"
---

# /plan-execute — Execute a Specific Phase
...

Schema: auxiliaresCopy Anchor Link

Padrão de caminho:

src/apothem/agents/*.md

Propósito: Definições persistentes de auxiliares (também chamados de trabalhadores delegados) para exploração paralela, auditoria e portões de qualidade.

Campos obrigatóriosCopy Anchor Link

---
name: "agent-name"
version: "MAJOR.MINOR.PATCH"
updated: "YYYY-MM-DD"
description: "What this agent specializes in"
tools: "Tool1, Tool2, Tool3"
disallowedTools: "Write, Edit"
maxTurns: 20
effort: "high" | "medium" | "low"
---

Campos opcionaisCopy Anchor Link

permissionMode: "default"       # Permission handling
memory: user | project | local  # Persistent-memory scope; omit for none
pattern: "Research" | "Audit" | "Implementation" | "Quality"  # Agent team pattern
portability: "universal"

ExemploCopy Anchor Link

---
name: "codebase-explorer"
version: "X.Y.Z"
updated: "2026-04-20"
description: "Deep codebase exploration — find patterns, trace dependencies, discover conventions, map architecture"
tools: "Read, Glob, Grep, Bash"
disallowedTools: "Write, Edit, TodoWrite"
maxTurns: 20
effort: "high"
permissionMode: "default"
portability: "universal"
---

You are a codebase exploration specialist...

Schema: skillsCopy Anchor Link

Padrão de caminho: src/apothem/skills/*/SKILL.md

Propósito: Definições de técnicas reutilizáveis com sinais de detecção e procedimentos de execução.

Campos obrigatóriosCopy Anchor Link

---
name: "skill-name"
version: "MAJOR.MINOR.PATCH"
updated: "YYYY-MM-DD"
description: "What this skill teaches"
archetype: "workflow-template"
userInvocable: true | false
disable-model-invocation: true | false
allowed-tools: "Read, Glob, Grep"
---

Campos opcionaisCopy Anchor Link

argument-hint: "[args...]"                           # Usage pattern if userInvocable

ExemploCopy Anchor Link

---
name: "ecosystem-audit"
version: "X.Y.Z"
updated: "2026-04-20"
description: "Comprehensive blind audit of the apothem ecosystem"
archetype: "audit-template"
userInvocable: true
disable-model-invocation: false
allowed-tools: "Read, Glob, Grep, Agent, TodoWrite"
argument-hint: "[--focus area] [--fix]"
---

## Purpose
...

Schema: hooksCopy Anchor Link

Padrão de caminho: o bloco hooks do settings.json mais as implementações em Python sob src/apothem/hooks/.

Propósito: Declarar validadores acionados por eventos e manipuladores de gerenciamento de estado que o host invoca em pontos bem definidos do ciclo de vida.

Schema do arquivo de configuraçõesCopy Anchor Link

A chave de nível superior hooks mapeia nomes de eventos para arrays de blocos de matcher:

"hooks": {
  "<EventName>": [
    {
      "matcher": "<pattern>",
      "hooks": [
        {
          "type": "command",
          "command": "${PYTHON_BIN}",
          "args": ["${HARNESS_ROOT}/.apothem/support/hooks/dispatch.py", "<EventName>", "<message-name>"],
          "timeout": <seconds>,
          "statusMessage": "<short human-readable label>"
        }
      ]
    }
  ]
}

A forma -m apothem.hooks.dispatch serve ao desenvolvimento a partir de um checkout do código-fonte com PYTHONPATH=src.

Eventos obrigatóriosCopy Anchor Link

O template do Claude Code registra quatro eventos: SessionStart, PreToolUse, PostToolUse e Stop. scripts/dev/validate_hooks.py verifica em settings.json os cinco eventos da tabela abaixo, um conjunto diferente, e relata cada um que não encontra como aviso, e não como falha. PostToolUse está registrado, mas não é um dos cinco. PreCompact e PostCompact estão entre os cinco, mas não são registrados no Claude Code (referência de hooks), de modo que, no Claude Code, o verificador emite um aviso sobre ambos.

Os valores de timeout espelham os orçamentos canônicos dos eventos de hook — a tabela abaixo os reproduz para conveniência do leitor; a fonte canônica prevalece.

dispatch.py também aceita UserPromptSubmit e Notification na sua lista de permissões de eventos, para compatibilidade futura; nenhum dos dois está conectado nos templates distribuídos. Adicione um bloco de matcher com o mesmo padrão em forma exec para habilitá-los.

Camada PythonCopy Anchor Link

Todo comando de hook passa pelo mesmo despachante Python:

ValidaçãoCopy Anchor Link

scripts/dev/validate_hooks.py impõe o contrato de hooks:

• settings.json é analisado como JSON e declara cada um dos cinco eventos da tabela; um evento ausente é um aviso, não uma falha.
• Os três scripts Python existem e são analisados como Python válido.
• Todos os arquivos de mensagem referenciados pelos argumentos --context-file existem.
• Nenhum caminho absoluto de usuário fixo no código (C:\Users\... etc.) aparece em src/apothem/hooks/**.py.
• Os artefatos de shell sob src/apothem/hooks/ e scripts/ limitam-se aos stubs aprovados de localizador / bootstrap.

Schema: CLAUDE.mdCopy Anchor Link

Caminho: CLAUDE.md (raiz)

Propósito: Instruções do Claude Code com escopo de projeto.

Frontmatter YAML obrigatórioCopy Anchor Link

---
name: "CLAUDE"
version: "MAJOR.MINOR.PATCH"
updated: "YYYY-MM-DD"
description: "Project-scoped Claude Code instructions for the Apothem source repository"
scope: "project"
portability: "project-local"
---

SeçõesCopy Anchor Link

O CLAUDE.md é redigido em seções de prosa, descritas em CLAUDE.md. Nenhum validador exige uma lista fixa de seções: scripts/dev/validate_ecosystem.py verifica as chaves de frontmatter acima.

Lista de verificação de validaçãoCopy Anchor Link

Todo artefato deve satisfazer estas verificações:

Validação do frontmatterCopy Anchor Link

• O YAML é sintaticamente válido (sem erros de análise)
• Todos os campos obrigatórios do tipo de artefato estão presentes
• name segue a convenção kebab-case
• version é semântica (MAJOR.MINOR.PATCH)
• updated está no formato de data ISO 8601 (YYYY-MM-DD)
• description é uma string não vazia, de uma única linha
• Os campos opcionais correspondem aos valores de enum esperados (se aplicável)
• Nenhum erro de digitação nos nomes dos campos (use os nomes canônicos do schema)
• Nenhum espaço em branco extra nem problema de formatação

Validação do conteúdoCopy Anchor Link

• O conteúdo começa em uma nova linha após o --- de fechamento; nos arquivos da família Markdown, a linha SPDX canônica do cabeçalho é o primeiro conteúdo depois dele
• Nenhuma referência interna de planos (conformidade com CM-7)
• As referências cruzadas se resolvem (se listarem outros artefatos)
• Os links usam caminhos relativos com barras normais

Validação de portabilidadeCopy Anchor Link

• Nenhum caminho absoluto fixo no código (use relativos)
• Nenhuma sintaxe específica do Windows em artefatos de escopo universal
• Os separadores de caminho usam barras normais
• As variáveis de ambiente usam um formato independente de plataforma (${VAR} ou nativo da ferramenta)

NotasCopy Anchor Link

• Consistência como segurança: O frontmatter canônico viabiliza validação automatizada, ferramentas e verificação entre artefatos. Os desvios se acumulam rapidamente.
• Declaração de portabilidade: Nem todos os artefatos podem ser universais. Declare as restrições explicitamente — é melhor documentar uma ressalva do que distribuir um bug silencioso.
• Kebab-case para nomes: Fácil de usar em URLs, scripts e contextos de linha de comando. Evite espaços, sublinhados e camelCase em nomes.
• Higiene do incremento de versão: Toda edição que altera o comportamento deve incrementar version e updated juntos. Correções de erro de digitação, correções de link e mudanças de formatação deixam a versão inalterada; novas seções opcionais ou antipadrões incrementam MINOR; reorganização estrutural ou mudanças de contrato incrementam MAJOR.