byteratio/kanban-plans

Suivi de plan via le kanban local

Le kanban existe pour que les sessions Claude, à travers différents projets et jours, puissent conserver l'état du plan entre les sessions : revendiquer des plans, les déplacer entre les statuts, laisser des notes. Plusieurs instances de Claude peuvent partager un même tableau — regroupez toujours votre travail sous un slug de projet afin que les plans de différents dépôts n'entrent pas en collision.

Lorsque vous travaillez sur un plan non trivial dans un projet sur une machine où le kanban est en cours d'exécution, vous devriez interagir avec lui au fur et à mesure.

Le tableau

Source : https://github.com/hechtch/kanban — une SPA Angular associée à une API Go sur SQLite. Il s'exécute localement ; il n'y a pas d'instance hébergée.

git clone https://github.com/hechtch/kanban.git
cd kanban
make container-build && make container-run   # CONTAINER_RUNTIME=podman si vous utilisez podman

make container-run publie -p 8000:8000 et monte ~/.kanban/data pour la persistance, de sorte qu'un seul conteneur sert à la fois l'interface utilisateur et l'API sur le port 8000.

Mode	IU pour l'humain	Base de l'API Agent
Conteneur (make container-run)	http://localhost:8000/board	http://localhost:8000/api/agent
Développement (make run)	http://localhost:4200/board	http://localhost:8000/api/agent

L'API agent est sur le port 8000 dans les deux modes — seul le lien de l'IU humaine diffère, car make run sert le serveur de développement Angular séparément sur le port 4200. Utilisez le lien de l'IU du conteneur sur le port 8000 sauf si vous savez que l'utilisateur exécute make run.

Si l'utilisateur a déployé le tableau ailleurs (derrière un proxy inverse, un port publié différent), il vous indiquera l'URL de base — utilisez la sienne plutôt que la valeur par défaut et conservez le suffixe /api/agent.

Est-ce que ça tourne ?

KB=http://localhost:8000/api/agent
curl -sS http://localhost:8000/api/health
# {"status":"ok"}

Si cela échoue, le kanban ne tourne pas. Ne le démarrez pas vous-même — il écrit dans ~/.kanban/data/kanban.db et un second processus se battant pour cette base de données est pire que l'absence de suivi. Informez l'utilisateur que le tableau est arrêté, proposez la ligne make container-run ci-dessus, et poursuivez le travail réel sans suivi.

Spécification canonique — lisez ceci pour tout détail sur les points d'API

L'API fournit une spécification OpenAPI 3.1 complète générée à partir des gestionnaires Go typés. C'est la source de vérité pour les chemins, les formes des requêtes/réponses, les codes de statut et les règles de validation — en cas de doute, récupérez-la plutôt que de deviner ou de vous fier à une documentation obsolète :

• Spécification (JSON) : http://localhost:8000/api/openapi.json
• Spécification (YAML) : http://localhost:8000/api/openapi.yaml
• Swagger UI (pour les humains) : http://localhost:8000/api/docs

Le reste de ce fichier vous donne le workflow agent (slugs, conventions, recettes) afin que vous n'ayez pas à apprendre l'API à partir de zéro. Pour les détails de points d'API non couverts ici, lisez la spécification.

Les réponses incluent un champ d'URL $schema pointant vers le schéma JSON de la réponse (convention de Huma). Ignorez-le sauf si vous validez les réponses par rapport au schéma.

Convention de fichier de plan que cette compétence suppose

Le tableau suit des plans, et un plan est un fichier markdown dans le dépôt :

• plans/<sujet>.md — un fichier par plan en cours discret, décrivant le pourquoi et le quoi. Utilisez des cases à cocher (- [ ] / - [x]) pour les tâches actionnables et affinez-les sur place au fur et à mesure du travail.
• plans/done/<sujet>.md — où le fichier déplace une fois que le travail est livré ou abandonné, avec un en-tête court "Livré dans — " en haut.
• CHANGELOG.md — le journal public "ce qui a changé", associé à plans/done/ qui porte le pourquoi.

Si un dépôt n'utilise pas encore cette disposition, créez plans/ et créez le fichier avant de le revendiquer sur le tableau — la règle de slug ci-dessous dépend du nom de fichier.

La règle du slug

Tout est indexé par slug, jamais par ID numérique. Ne stockez jamais task.id dans vos invites ou votre code.

• Slug du plan = le nom du fichier plan moins .md, en minuscules. plans/photo-import.md → photo-import.
• Slug du projet = le nom du dépôt ou de l'initiative en kebab-case. ~/projects/photo-organizer → photo-organizer. (Pour un projet nommé "Photo Organizer", le serveur dérive automatiquement photo-organizer à partir du nom ; vous pouvez aussi passer un slug explicite.)
• Format (appliqué côté serveur) : ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$. Les mauvais slugs retournent 400. Minuscules, tirets entre les mots, pas de soulignements ni de majuscules.

Le corps de la tâche EST le plan

Lorsque vous revendiquez un plan pour la première fois, envoyez le markdown du plan comme champ body. La base de données kanban est canonique à partir de ce moment — ne synchronisez pas les modifications vers le fichier en cours de route. Le fichier plans/<slug>.md sur le disque est la graine (utilisée une fois) ; plans/done/<slug>.md est l'instantané d'archivage que vous écrivez lorsque le travail est livré.

Si vous refaites un PUT plus tard avec un nouveau body, votre version gagne. Les humains peuvent aussi corriger des fautes de frappe dans la vue rendue à /task/<task_id> dans l'IU ; les deux modifications aboutissent dans la même colonne.

Revendiquer un plan est ce qui le rend "à Claude"

Il n'y a pas de champ d'assignation à définir. Le tableau le dérive : une tâche portant un plan_slug — ce qui est exactement ce que PUT /plans/<slug> crée — s'affiche sous Claude dans le filtre d'assignation de la barre latérale et reçoit une pastille Claude sur la carte. Les tâches créées manuellement par l'humain n'ont pas de plan_slug et restent sous vous.

Revendiquer un plan via cette API est donc un acte visible. Ne revendiquez pas un travail que l'humain fait lui-même juste pour laisser une note dessus.

Statuts

Cinq colonnes du tableau, fixes :

todo  →  doing  →  blocked  →  awaiting_merge  →  done

Plus backlog (hors tableau, 6e optionnelle).

• blocked — le travail ne peut pas avancer ; expliquez pourquoi dans une note.
• awaiting_merge — le code est écrit et poussé, en attente d'une fusion de PR ou d'une fusion manuelle. Différent de done car le travail n'a pas encore été livré.
• Basculez vers done uniquement lorsque la branche est effectivement fusionnée dans la branche principale. Ne faites pas de transition automatique.

'waiting' n'est pas un statut valide — il a été renommé 'blocked' lors d'une migration.

Branche Git

Les plans (et toute tâche) peuvent porter un champ git_branch — la branche sur laquelle le travail est en cours. Définissez-le lorsque vous créez une branche de fonctionnalité afin que l'humain puisse le voir sur la carte :

curl -sS -X PUT $KB/plans/photo-import \
  -H 'Content-Type: application/json' \
  -d '{"git_branch":"feat/photo-import"}'

Effacez avec {"git_branch": null}. La branche s'affiche comme une pastille monospace sur la carte.

Modèle et effort suggérés

Chaque tâche peut porter un model et un effort — une indication pour l'agent qui reprendra le travail ensuite. L'humain les définit à partir du ticket (ou vous pouvez le faire, lorsque vous connaissez le poids d'un plan), et ils s'affichent comme une pastille fable / xhigh sur la carte. Respectez-les : lorsque vous reprenez un plan dont la tâche indique sonnet / high, c'est le niveau que le propriétaire souhaite y consacrer ; un plan d'audit fable / xhigh veut le grand modèle avec un effort élevé.

curl -sS -X PUT $KB/plans/security-audit \
  -H 'Content-Type: application/json' \
  -d '{"model":"fable","effort":"xhigh"}'

• model est un raccourci libre — fable, opus, sonnet, haiku sont les valeurs courantes ; le serveur met en minuscules et supprime les espaces, et rejette tout ce qui dépasse 40 caractères.
• effort doit être l'un de low, medium, high, xhigh, max (les niveaux d'effort de raisonnement de Claude Code) ; toute autre valeur retourne 422.
• Les deux sont optionnels et indépendants ; effacez avec null. Absent signifie "aucune préférence — utiliser la valeur par défaut de la session".

Projets : archivage et balises par défaut

Un projet porte deux champs au-delà du nom et de la couleur, tous deux configurables via le même appel PUT $KB/projects/<slug> (création ou mise à jour) :

• archived — le projet est terminé. Ses plans disparaissent de la barre latérale et du tableau (repliés dans une section "archivé(e)" que l'humain peut développer), mais rien n'est supprimé et chaque point d'API les retourne toujours. Définissez-le lorsque le travail d'un projet a été livré :

  curl -sS -X PUT $KB/projects/photo-organizer \
    -H 'Content-Type: application/json' -d '{"archived":true}'
  

• tags — balise chaque tâche du projet. Le serveur les fusionne dans les tags de chaque tâche à la lecture, de sorte qu'un plan sous un projet balisé ["infra"] revienne balisé infra sans avoir jamais été balisé individuellement. Remplace l'ensemble complet, comme les balises de tâche :

  curl -sS -X PUT $KB/projects/photo-organizer \
    -H 'Content-Type: application/json' -d '{"tags":["media","infra"]}'
  

  Parce que la fusion a lieu à la lecture, supprimer une balise du projet la supprime de toutes les tâches d'un coup. Ne définissez pas la balise d'un projet sur ses tâches individuellement — le serveur supprime les balises héritées de l'ensemble propre de la tâche, donc vous écririez une opération sans effet.

Workflow par session

KB=http://localhost:8000/api/agent

# 1. Assurez-vous que votre projet existe (idempotent — 201 la première fois, 200 ensuite).
curl -sS -X PUT $KB/projects/photo-organizer \
  -H 'Content-Type: application/json' \
  -d '{"name":"Photo Organizer","color":"#d4654a"}'

# 2. Revendiquez le plan + envoyez son corps actuel + placez-le sous votre projet.
#    Le premier PUT crée avec status=todo ; les PUT suivants patchent.
BODY=$(jq -Rs . < plans/photo-import.md)
curl -sS -X PUT $KB/plans/photo-import \
  -H 'Content-Type: application/json' \
  -d "{\"title\":\"Photo Import\",\"project_slug\":\"photo-organizer\",\"body\":$BODY}"

# 3. Créez une branche de fonctionnalité et informez le kanban.
git checkout -b feat/photo-import
curl -sS -X PUT $KB/plans/photo-import \
  -H 'Content-Type: application/json' \
  -d '{"git_branch":"feat/photo-import"}'

# 4. Basculez vers doing avec une note. Les PUT de statut sont idempotents — même statut
#    sans note est une opération sans effet ; avec une note, écrit une entrée d'activité.
curl -sS -X PUT $KB/plans/photo-import/status \
  -H 'Content-Type: application/json' \
  -d '{"status":"doing","note":"début de la phase 2"}'

# 5. Laissez des notes au fur et à mesure (moins coûteux qu'un changement de statut).
curl -sS -X POST $KB/plans/photo-import/notes \
  -H 'Content-Type: application/json' \
  -d '{"text":"phase 2 terminée ; exécution des tests"}'

# 6. Lorsque la PR est ouverte, passez à awaiting_merge.
curl -sS -X PUT $KB/plans/photo-import/status \
  -H 'Content-Type: application/json' \
  -d '{"status":"awaiting_merge","note":"PR #123 ouverte"}'

# 7. Une fois fusionné, basculez vers done et archivez le fichier.
curl -sS -X PUT $KB/plans/photo-import/status \
  -H 'Content-Type: application/json' \
  -d '{"status":"done","note":"fusionné dans v0.3.0"}'
# puis `git mv plans/photo-import.md plans/done/photo-import.md`

Mentionnez le lien de l'IU humaine lorsque vous venez de créer ou de déplacer un plan — http://localhost:8000/board (ou :4200 en mode développement).

Règles et pièges

• L'énumération des statuts est fixe : todo, doing, blocked, awaiting_merge, done, backlog. N'en inventez pas de nouveaux.
• Un project_slug inconnu retourne 422 unknown project_slug "X" — créez le projet avant d'assigner. Pas de création automatique silencieuse.
• project_slug: "" supprime le projet, équivalent à project_id: null.
• L'upsert est un véritable upsert — PUT /plans/:slug avec {} est votre appel "revendiquer si absent, patcher si présent". Réexécuter ne duplique pas ; seul le premier appel écrit une entrée d'activité create.
• Un PUT de statut identique est une opération sans effet sauf si vous passez une note. Utilisez cela à votre avantage — vous pouvez réessayer en toute sécurité.
• Le journal d'activité est en ajout seulement et visible à $KB/plans/<slug>/activity. Utilisez les notes pour laisser des traces ("Phase 2 terminée ; début de la Phase 3") plutôt que de narrer dans le corps.
• Le corps est du markdown rendu à /task/<task_id> dans l'IU. Utilisez du markdown standard : titres, listes (y compris - [ ] / - [x]), blocs de code, liens. Les tableaux et les citations sont également rendus.

Quand ne pas s'en soucier

• Corrections de bugs ponctuelles, refactorisations, ajustements de documentation. Le kanban suit des plans — des initiatives en plusieurs étapes qui s'étendent sur plusieurs sessions ou portent un contexte significatif. Un travail en un seul commit n'a pas besoin de ticket.
• Si le dépôt kanban est lui-même le projet sur lequel vous travaillez, il documente ses propres conventions dans son CLAUDE.md — lisez-le à la place et ignorez ce fichier.
• Si la vérification de santé échoue, le tableau ne tourne pas. N'essayez pas de le démarrer ; contentez-vous de continuer et informez l'utilisateur.