Spécification du schéma d'artefacts

Modèles de frontmatter YAML par classe et champs requis pour tous les artefacts de l'écosystème Apothem.

Source de vérité. Le contrat lisible par machine et appliqué par le portail de conformité est constitué des JSON Schemas par classe sous src/apothem/schemas/ (agent.schema.json, command.schema.json, skill.schema.json, …). Les schémas de skill et de commande déclarent additionalProperties: false, de sorte qu'ils rejettent les clés inconnues ; les schémas d'agent, d'output-style et de plan déclarent additionalProperties: true. Cette page et frontmatter-schema.mdx sont les deux projections lisibles par un humain de ces schémas : cette page porte les modèles et exemples détaillés par classe, frontmatter-schema l'index concis des clés requises. Lorsqu'une page contredit les JSON Schemas, ce sont les schémas qui l'emportent.

Vue d'ensembleCopy Anchor Link

Tous les artefacts de l'arbre des sources d'Apothem (sous src/apothem/ et la surface de configuration racine) doivent inclure un bloc de frontmatter YAML (entre des délimiteurs ---) contenant des champs obligatoires et optionnels propres à leur type d'artefact. Ce document définit le schéma canonique de chaque type.

Règles universelles :

• Le frontmatter est conforme à YAML 1.2
• Toutes les valeurs de chaîne utilisent des guillemets doubles, et une chaîne vide s'écrit ""
• Ordre des champs : les champs obligatoires d'abord, les champs optionnels regroupés par pertinence
• Les commentaires dans le frontmatter utilisent # suivi d'un espace : # comment
• Les valeurs de chemin doivent être relatives (sans / initial) et utiliser des barres obliques (/) pour la compatibilité multiplateforme

Convention de versionnage (classes d'artefacts versionnées : commandes, assistants, skills, CLAUDE.md) :

• version est sémantique (MAJOR.MINOR.PATCH). Incrémentez MAJOR pour les changements incompatibles de schéma ou de contrat ; MINOR pour les changements additifs compatibles (nouveaux champs optionnels, sections supplémentaires, anti-modèles supplémentaires) ; PATCH pour un changement de comportement qui corrige une directive existante sans rompre le contrat.
• Les corrections de fautes de frappe, les corrections de liens, la mise en forme et les modifications de commentaires ou de documentation seules laissent version inchangée. Seul un changement de comportement l'incrémente.
• updated est la date ISO 8601 (YYYY-MM-DD) de la modification la plus récente. Elle doit changer à chaque incrément de version, et elle change aussi lors d'une correction de faute de frappe ou de lien qui n'incrémente pas la version.
• Les nouveaux artefacts démarrent à v0.Y.Z. La promotion vers vX.Y.Z indique que le contrat de l'artefact est suffisamment stable pour constituer un engagement public.
• Les suites de planification sont hors de cette convention. Une correction de faute de frappe dans une suite de planification incrémente le numéro PATCH de la version de la suite (vX.Y.Z vers vX.Y.(Z+1)) et ajoute une ligne au tableau Revision History. Le guide du développeur décrit la règle des suites de planification dans sa section sur les révisions des suites de planification.

Schéma : règlesCopy Anchor Link

Motif de chemin : src/apothem/rules/*.md

Objectif : Mandats comportementaux et directives opérationnelles.

Champs obligatoiresCopy Anchor Link

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

Champs optionnelsCopy Anchor Link

Les règles ne portent aucun champ de frontmatter optionnel et, contrairement aux autres classes d'artefacts, aucun champ version / updated / scope / portability non plus. Les quatre champs obligatoires ci-dessus constituent le contrat complet de frontmatter des règles, appliqué par frontmatter_grep.

ExempleCopy 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
...

Schéma : commandesCopy Anchor Link

Motif de chemin : src/apothem/commands/*.md

Objectif : Définitions de commandes slash (/plan-execute, /freshify, etc.).

Champs obligatoiresCopy 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"
---

Champs optionnelsCopy Anchor Link

Les commandes ne portent aucun champ de frontmatter optionnel : les huit champs obligatoires ci-dessus constituent le contrat complet de frontmatter des commandes, appliqué par command.schema.json (additionalProperties: false).

ExempleCopy 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
...

Schéma : assistantsCopy Anchor Link

Motif de chemin :

src/apothem/agents/*.md

Objectif : Définitions d'assistants persistants (aussi appelés travailleurs délégués) pour l'exploration parallèle, l'audit et les portails de qualité.

Champs obligatoiresCopy 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"
---

Champs optionnelsCopy 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"

ExempleCopy 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...

Schéma : skillsCopy Anchor Link

Motif de chemin : src/apothem/skills/*/SKILL.md

Objectif : Définitions de techniques réutilisables, avec signaux de détection et procédures d'exécution.

Champs obligatoiresCopy 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"
---

Champs optionnelsCopy Anchor Link

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

ExempleCopy 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
...

Schéma : hooksCopy Anchor Link

Motif de chemin : le bloc hooks de settings.json, ainsi que les implémentations Python sous src/apothem/hooks/.

Objectif : Déclarer des validateurs déclenchés par des événements et des gestionnaires de gestion d'état que l'hôte invoque à des points bien définis du cycle de vie.

Schéma du fichier de settingsCopy Anchor Link

La clé de premier niveau hooks associe des noms d'événements à des tableaux de blocs 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>"
        }
      ]
    }
  ]
}

La forme -m apothem.hooks.dispatch est destinée au développement depuis un checkout des sources avec PYTHONPATH=src.

Événements requisCopy Anchor Link

Le modèle Claude Code enregistre quatre événements : SessionStart, PreToolUse, PostToolUse et Stop. scripts/dev/validate_hooks.py vérifie dans settings.json les cinq événements du tableau ci-dessous, un ensemble différent, et signale chacun de ceux qu'il ne trouve pas comme un avertissement, et non comme un échec. PostToolUse est enregistré mais ne fait pas partie des cinq. PreCompact et PostCompact font partie des cinq mais ne sont pas enregistrés sur Claude Code (référence des hooks), de sorte que le vérificateur avertit à leur sujet sur Claude Code.

Les valeurs de timeout reprennent les budgets canoniques des événements de hook : le tableau ci-dessous les reproduit pour la commodité du lecteur ; la source canonique fait foi.

dispatch.py accepte aussi UserPromptSubmit et Notification dans sa liste d'autorisation d'événements, pour assurer la compatibilité avec les évolutions futures ; aucun des deux n'est câblé dans les modèles livrés. Pour les activer, ajoutez un bloc de matcher suivant le même motif sous forme exec.

Couche PythonCopy Anchor Link

Chaque commande de hook passe par le même répartiteur Python :

ValidationCopy Anchor Link

scripts/dev/validate_hooks.py applique le contrat des hooks :

• settings.json s'analyse comme du JSON et déclare chacun des cinq événements du tableau ; un événement manquant est un avertissement, et non un échec.
• Les trois scripts Python existent et s'analysent comme du Python valide.
• Tous les fichiers de message référencés par des arguments --context-file existent.
• Aucun chemin utilisateur absolu codé en dur (C:\Users\..., etc.) n'apparaît dans src/apothem/hooks/**.py.
• Les artefacts shell sous src/apothem/hooks/ et scripts/ se limitent aux stubs approuvés de localisation / d'amorçage.

Schéma : CLAUDE.mdCopy Anchor Link

Chemin : CLAUDE.md (racine)

Objectif : Instructions Claude Code à portée de projet.

Frontmatter YAML obligatoireCopy 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"
---

SectionsCopy Anchor Link

CLAUDE.md est rédigé en sections de prose, décrites dans CLAUDE.md. Aucun validateur n'exige une liste fixe de sections : scripts/dev/validate_ecosystem.py vérifie les clés de frontmatter ci-dessus.

Liste de contrôle de validationCopy Anchor Link

Chaque artefact doit satisfaire les vérifications suivantes :

Validation du frontmatterCopy Anchor Link

• Le YAML est syntaxiquement valide (aucune erreur d'analyse)
• Tous les champs obligatoires du type d'artefact sont présents
• name suit la convention kebab-case
• version est sémantique (MAJOR.MINOR.PATCH)
• updated est au format de date ISO 8601 (YYYY-MM-DD)
• description est une chaîne non vide, sur une seule ligne
• Les champs optionnels correspondent aux valeurs d'énumération attendues (le cas échéant)
• Aucune faute de frappe dans les noms de champs (utilisez les noms canoniques du schéma)
• Aucun espace superflu ni problème de mise en forme

Validation du contenuCopy Anchor Link

• Le contenu commence sur une nouvelle ligne après le --- de fermeture ; dans les fichiers de la famille Markdown, la ligne d'en-tête SPDX canonique est le premier contenu après celui-ci
• Aucune référence interne au plan (conformité CM-7)
• Les références croisées se résolvent (si d'autres artefacts sont listés)
• Les liens utilisent des chemins relatifs avec des barres obliques

Validation de la portabilitéCopy Anchor Link

• Aucun chemin absolu codé en dur (utilisez des chemins relatifs)
• Aucune syntaxe propre à Windows dans les artefacts de portée universelle
• Les séparateurs de chemin utilisent des barres obliques
• Les variables d'environnement utilisent un format indépendant de la plateforme (${VAR} ou natif à l'outil)

NotesCopy Anchor Link

• La cohérence comme sécurité : un frontmatter canonique permet la validation automatisée, l'outillage et la vérification entre artefacts. Les écarts se cumulent rapidement.
• Déclaration de portabilité : tous les artefacts ne peuvent pas être universels. Déclarez explicitement les contraintes : mieux vaut documenter une réserve que livrer un bogue silencieux.
• Kebab-case pour les noms : facile à utiliser dans les URL, les scripts et les contextes de ligne de commande. Évitez les espaces, les traits de soulignement et le camelCase dans les noms.
• Hygiène des incréments de version : toute modification qui change le comportement doit incrémenter version et updated ensemble. Les corrections de fautes de frappe, les corrections de liens et les changements de mise en forme laissent la version inchangée ; les nouvelles sections optionnelles ou les nouveaux anti-modèles incrémentent MINOR ; les réorganisations structurelles ou les changements de contrat incrémentent MAJOR.