Grammaire canonique — six verbes pour chaque entité

brainclaw expose une surface CRUD uniforme sur 17 entités : plan, step, claim, session, handoff, decision, constraint, trap, candidat, runtime_note, séquence, message_inbox, instruction, affectation, agent_run, action, cross_project_link.

Six verbes. Chaque entité. Aucune invention d’outil par entité.

# Lire les chemins
bclaw_find    entity=plan filter={status: "in_progress"}
bclaw_get     entity=handoff id=hnd_abc123
bclaw_context kind=memory path="src/auth/"

# Écrire les chemins
bclaw_create     entity=decision data={text: "...", author: "..."}
bclaw_update     entity=plan id=pln_xyz patch={priority: "high"}
bclaw_remove     entity=trap id=trp_xyz
bclaw_transition entity=plan id=pln_xyz to=done

Exemple concret — capturer et agir sur une décision

Un flux typique de bout en bout sur le cycle de vie d’un petit refactoring :

# 1. Planifier le travail
bclaw_create entity=plan data={
  text: "Remplacer l'authentification REST par un middleware JWT verify",
  author: "claude-code",
  priority: "high",
  related_paths: ["src/auth/"]
}
# → { id: "pln_abc", short_label: "pln#42" }

# 2. Décomposer en étapes
bclaw_add_step planId=pln_abc data={text: "Shape de la pull request — esquisser la signature du point de terminaison"}
bclaw_add_step planId=pln_abc data={text: "Intégrer le middleware dans src/server/auth.ts"}
bclaw_add_step planId=pln_abc data={text: "Migrer les tests pour utiliser des jetons signés"}

# 3. Revendiquer le périmètre avant l'édition
bclaw_work intent=execute scope="src/auth/" task="Middleware JWT"
# → claim clm_abc, worktree à ~/.brainclaw/worktrees/<hash>/feat_src-auth/

# 4. Pendant l'édition — capturer une décision et un piège
bclaw_create entity=decision data={
  text: "Le secret JWT est lu depuis l'environnement au démarrage, et non à chaque requête",
  author: "claude-code",
  outcome: "approved",
  plan_id: "pln_abc"
}
bclaw_create entity=trap data={
  text: "La rotation des jetons force un redémarrage du serveur — un déploiement progressif est requis",
  severity: "medium",
  related_paths: ["src/auth/middleware.ts"]
}

# 5. Marquer l'étape comme terminée au fur et à mesure
bclaw_complete_step planId=pln_abc stepId=stp_xyz

# 6. Transférer le travail lorsque l'on fait une pause
#    (les handoffs sont créés via le CLI / session-end, pas via le verbe bclaw_create)
brainclaw handoff "Middleware câblé, 2/3 tests réussis. Le test de rotation de jeton échoue en raison d'un décalage d'horloge local." \
  --plan pln_abc \
  --pre-condition "npm install fresh" \
  --post-condition "Tous les src/auth/*.test.ts réussissent"

# 7. Libérer le claim et faire passer le plan à l'état terminé
bclaw_release_claim id=clm_abc planStatus=done
# ou, séparément :
bclaw_transition entity=plan id=pln_abc to=done

Pourquoi c’est important

• Apprentissage unique — les agents qui connaissent la grammaire fonctionnent sur chaque entité sans documentation spécifique. Nouvelle entité ? Les mêmes six verbes.
• Mises à jour de type schéma — EntityRegistry.updatable déclare les champs patchables par entité. Les patchs contre des champs non listés sont rejetés à la frontière de dispatch, de sorte que bclaw_update entity=plan id=… patch={cursed_field: 1} renvoie une erreur de validation claire plutôt que de supprimer silencieusement le champ (c’est la raison pour laquelle bclaw_update n’est pas un Object.assign sur l’enregistrement brut).
• Transitions de type cycle de vie — EntityRegistry.transitions déclare les transitions de statut valides. Les invalides lèvent une erreur à l’exécution : essayer de faire passer un plan de dropped à in_progress renvoie InvalidTransitionError au lieu de corrompre le cycle de vie.
• Filtrage de lecture par défaut — bclaw_find exclut par défaut les enregistrements provenance.kind="legacy" et les enregistrements auto_reflect avec une confiance inférieure à 0,6. On peut outrepasser cela via filter={includeLegacy: true, minAutoReflectConfidence: 0.3} lorsque vous avez besoin de la longue traîne.

Au-delà des six verbes

Deux points d’entrée façade couvrent la boucle quotidienne sans nécessiter de penser verbe par verbe — voir bclaw_work et bclaw_context pour le modèle complet.

Pour l’orchestration multi-agents, la façade de coordination ajoute trois intentions supplémentaires :

• bclaw_coordinate intent=assign — envoie une tâche à un agent cible (claim + affectation + message_inbox)
• bclaw_coordinate intent=review — ouvre une boucle d’examen avec délégation multi-tours
• bclaw_coordinate intent=ideate — ouvre une boucle d’idéation avec des portes de critique

Voir coordination loops pour la sémantique du moteur de boucle.

Routage inter-projets

Chaque appel à la grammaire canonique, bclaw_context, et bclaw_coordinate accepte un argument optionnel project: <name> qui route l’opération vers un projet lié (cross_project_links depuis brainclaw link list OU un enfant de chaîne de stockage de l’espace de travail) :

bclaw_get entity=trap id=trp_xyz project=brainclaw-site
bclaw_update entity=plan id=pln_abc patch={priority: "high"} project=brainclaw-cloud

L’identité reste sourcée par l’appelant ; les écritures + l’audit atterrissent dans le projet cible. Les noms de projets inconnus lèvent une erreur — pas de repli silencieux. Le CLI expose le même que --project <name>. Lisez la fonctionnalité d’intégration MCP pour la liste complète des surfaces.