L’essentiel pour utiliser Planning with Files, la skill qui garde le plan de l’agent sur disque dans trois fichiers Markdown. Le plan survit à /clear, à la compaction et aux plantages : la session suivante reprend à la bonne phase.

Installation

# Claude Code — plugin complet (skill + hooks + slash commands)
/plugin marketplace add OthmanAdi/planning-with-files
/plugin install planning-with-files@planning-with-files
 
# Codex, Cursor et 60+ autres agents (standard Agent Skills)
npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g

Seul le plugin Claude Code apporte les slash commands et les hooks automatiques.

Les trois fichiers

FichierRôle
task_plan.mdPhases et cases à cocher. C’est le point de reprise après /clear.
findings.mdNotes de recherche et décisions, ajoutées au fil de l’eau.
progress.mdJournal de session et résultats de tests.

Pour plusieurs tâches en parallèle : un dossier .planning/AAAA-MM-JJ-slug/ par tâche, avec les mêmes trois fichiers.

Commandes (plugin Claude Code)

Taper la forme courte, l’autocomplétion trouve la commande complète /planning-with-files:<verbe>.

CommandeCe qu’elle fait
/planCrée les trois fichiers et démarre la session planifiée.
/pwfAlias court de /plan. Options : --autonomous, --gated.
/statusRapport d’un coup d’œil : phase en cours et avancement.
/plan-doctorAuto-diagnostic : une ligne PASS/WARN/FAIL par mécanisme (injection, attestation, installation, latence).
/plan-attestVerrouille task_plan.md par empreinte SHA-256 : un plan modifié à ton insu est refusé. --show / --clear.
/plan-goalTravaille jusqu’à ce que le plan soit terminé, en s’appuyant sur /goal de Claude Code.
/plan-loopCadence de reprise sur /loop, toutes les 10 minutes par défaut.
/plan-de, -es, -ar, -zh, -zhtDémarre le plan en allemand, espagnol, arabe ou chinois.

Modes

ModeActivationEffet
Standard/planLe plan est réinjecté à chaque tour et rappelé après les écritures.
Autonome/pwf --autonomousMoins de rappels à chaque appel d’outil, attestation activée par défaut. Pour les longues tâches sans supervision.
Gated/pwf --gatedL’agent ne peut pas s’arrêter tant que le plan n’est pas terminé.

Variables d’environnement utiles

VariableEffet
PLANNING_DISABLED=1Ignore le plan pour cette session (utile en CI ou pour une tâche ponctuelle dans le même dossier).
PLAN_ID=<slug>Attache le terminal à un plan précis de .planning/.
PWF_INJECT=smartN’injecte que l’essentiel : objectif, prochaine étape, phase en cours, trois dernières décisions.

Les règles que suit l’agent

  1. Plan d’abord : ne jamais démarrer une tâche complexe sans task_plan.md.
  2. Règle des 2 actions : sauvegarder les découvertes dans findings.md toutes les deux lectures ou recherches.
  3. Noter toutes les erreurs pour ne pas les répéter.
  4. Ne jamais retenter à l’identique un échec : changer d’approche.

Conseils d’utilisation

  • À réserver aux tâches longues : recherche, refonte, tout ce qui demande plus de cinq appels d’outils ou plusieurs sessions. Pour une petite correction, c’est inutile.
  • Garder la compaction automatique activée : le hook PreCompact sauvegarde l’avancement juste avant.
  • Relire task_plan.md avant chaque décision importante, ou demander à l’agent de le faire.
  • Les fichiers sont ignorés par git par défaut. Les committer si tu veux garder une trace des décisions.
  • Si le plan semble ignoré, lancer /plan-doctor avant toute autre hypothèse.

Sources