Guides pratiques de rédaction et de pipeline

Procédures pas à pas orientées tâches pour rédiger des artefacts Apothem et piloter le pipeline de plans. Chaque guide répond à une question concrète unique.

Pour les recettes de première configuration — ajouter un environnement, modifier le profil, piloter l'installateur — consultez plutôt la section Recettes pratiques.

Pipeline de la suite de planificationCopy Anchor Link

Comment affiner du contenu brut en une spécification ?Copy Anchor Link

Invoquez /plan-spec avec le contenu brut en entrée. Le rôle Forge exécute six phases de transformation (Découverte, Considération méticuleuse, Cartographie de la puissance, Vérification de la préservation, Application de l'expertise, Balayage de résolution des questions) et émet la spécification consolidée à .apothem/plans/{suite}/_spec/spec.md. Voir src/apothem/commands/plan-spec.md pour le protocole complet.

Comment générer une suite de planification à partir d'une spécification ?Copy Anchor Link

Invoquez /plan-generate .apothem/plans/{suite}/_spec/spec.md une fois que /plan-spec a écrit la spécification. Le générateur émet les fichiers d'infrastructure canoniques ainsi que les fichiers phases/NN-kebab-topic/PHASE.md propres à chaque phase. Voir src/apothem/commands/plan-generate.md.

Comment relire un plan généré ?Copy Anchor Link

Invoquez /plan-review path/to/plan-suite/. Le relecteur applique les neuf techniques de planification et émet des fiches de score. Les fiches de score en échec bloquent l'exécution à SHARED+ tant qu'elles ne sont pas résolues. Voir src/apothem/commands/plan-review.md.

Comment exécuter un plan ?Copy Anchor Link

Invoquez /plan-execute path/to/plan-suite/ [phase-id]. Sans phase-id, la prochaine phase en attente s'exécute. Avec un identifiant précis, seule cette phase s'exécute. Voir src/apothem/commands/plan-execute.md.

Comment vérifier l'état d'un plan ?Copy Anchor Link

Invoquez /plan-status path/to/plan-suite/ [--verbose]. Rapport en lecture seule. Voir src/apothem/commands/plan-status.md.

Rédaction d'artefactsCopy Anchor Link

Comment ajouter une nouvelle règle ?Copy Anchor Link

1. Choisissez un nom de fichier en kebab-case sous src/apothem/rules/, par exemple src/apothem/rules/my-new-rule.md.
2. Rédigez le frontmatter (name, description, pathFilter, alwaysApply).
3. Rédigez le corps avec les sections canoniques : Purpose, Obligations, Seriousness Scaling, Anti-Patterns, Enforcement, Bindings.
4. Exécutez python scripts/dev/validate_ecosystem.py --check frontmatter-cohort pour vérifier.

Le chargeur de règles fonctionne par glob : il prend en compte chaque fichier correspondant à src/apothem/rules/*.md, de sorte qu'aucune entrée de registre n'est nécessaire ; déposer le fichier au nom canonique dans ce répertoire suffit à l'enregistrer.

Comment ajouter un nouveau travailleur délégué ?Copy Anchor Link

Choisissez un nom de fichier en kebab-case sous le répertoire indiqué ci-dessous, en utilisant la forme my-worker.md :

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

Puis :

1. Rédigez le frontmatter — y compris name, version, updated, description, tools, disallowedTools, maxTurns et effort.

2. Rédigez le system prompt comme corps.

La cohorte de travailleurs délégués est chargée par glob depuis src/apothem/agents/*.md, de sorte que le fichier au nom canonique est pris en compte dès son placement ; il n'existe aucune table de registre à modifier.

Comment ajouter un nouveau hook ?Copy Anchor Link

1. Rédigez un message de contexte sous src/apothem/hooks/messages/<event>-<scope>.md.
2. Câblez le hook dans settings.json.
3. Mettez à jour le pipeline de hooks.
4. Exécutez python scripts/dev/validate_ecosystem.py.

Portails de qualitéCopy Anchor Link

Comment exécuter les portails de qualité locaux ?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

Le pipeline de CI exécute le même ensemble en parallèle.

Comment vérifier le frontmatter d'une seule classe d'artefacts ?Copy Anchor Link

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