diff --git a/.claude/memory/blockers.md b/.claude/memory/blockers.md new file mode 100644 index 0000000..e5f75b4 --- /dev/null +++ b/.claude/memory/blockers.md @@ -0,0 +1,36 @@ +--- +type: blockers_registry +entry_prefix: BLK +schema: + id: BLK-XXX + date: YYYY-MM-DD + friction: string (what was blocked) + real_cause: string (root cause, not symptom) + solution: string (workaround or fix) + status: [open | resolved | upstream] +rules: + - Open a blocker as soon as friction > 15 min wasted. Close it with a real cause, not "moved on". + - Link to upstream issue / PR / commit when applicable. + - If cause is a bug in a dependency, set status upstream with a pointer to the tracker. +--- + +# Blockers registry (BLK) + +## Index + +| ID | Date | Friction | Status | +|----|------|---------|--------| +| BLK-001 | 2026-04-22 | `rtk curl` breaks JSON pipelines | upstream | + +--- + +## BLK-001 — `rtk curl` returns compressed schema in pipes + +- **Date** : 2026-04-22 +- **Friction** : toute pipeline `rtk curl ... | python -c "json.load(sys.stdin)"` (ou `jq`, `awk`) échoue sans message clair. +- **Cause réelle** : `rtk curl` auto-compresse stdout indépendamment du TTY — documenté dans `.claude/tasks/rtk-upstream-issue.md`. +- **Solution** : + - Workaround court terme : `exclude_commands=["curl"]` dans `~/.config/rtk/config.toml`. + - Workaround alternatif : utiliser `rtk proxy`. + - Fix upstream : issue reportée, voir `.claude/tasks/rtk-upstream-issue.md`. +- **Statut** : upstream (bug chez `rtk`, workaround appliqué). diff --git a/.claude/memory/decisions.md b/.claude/memory/decisions.md new file mode 100644 index 0000000..1e5352a --- /dev/null +++ b/.claude/memory/decisions.md @@ -0,0 +1,51 @@ +--- +type: decisions_registry +entry_prefix: BDR +schema: + id: BDR-XXX + date: YYYY-MM-DD + title: string (<= 80 chars) + decision: string (what was chosen) + why: string (motivation, context) + alternatives: list of strings (what was rejected + why) + status: [proposed | accepted | deprecated | superseded] + supersedes: BDR-XXX (optional) +rules: + - Append-only. Never rewrite past entries - add a new one with status superseded if needed. + - One entry per non-trivial choice. Trivial = reversible in under 10 min with no cross-file impact. + - Capture why more carefully than what - the what rots, the why lasts. +--- + +# Decisions registry (BDR) + +## Index + +| ID | Date | Title | Status | +|----|------|-------|--------| +| BDR-001 | 2026-04-22 | --help helper uniforme via hook post-start (option C) | accepted | +| BDR-002 | 2026-04-23 | Restructurer tasks/ + memory + audits sous .claude/ | accepted | + +--- + +## BDR-001 — --help helper uniforme via hook post-start (option C) + +- **Date** : 2026-04-22 +- **Statut** : accepted +- **Décision** : tous les skills exposent `--help` via un snippet partagé injecté par le session-start hook, plutôt que dupliquer le helper dans chaque SKILL.md. +- **Pourquoi** : 25+ skills, maintenir le même helper dans chaque fichier = drift garanti. Un point d'injection = une seule source de vérité. +- **Alternatives rejetées** : + - Option A (copier le helper dans chaque SKILL.md) — refusée : entropie de maintenance. + - Option B (wrapper externe `/help `) — refusée : casse l'expérience "une commande = un skill". +- **Référence** : commit 3968a29. + +## BDR-002 — Restructurer tasks/ + memory + audits sous .claude/ + +- **Date** : 2026-04-23 +- **Statut** : accepted +- **Décision** : migrer `./tasks/` vers `.claude/tasks/`, créer `.claude/memory/` (5 registres BDR/LRN/BLK/journal/EVAL) et `.claude/audits/` pour les fichiers AUDIT_*. Adapter skills/agents/CLAUDE.md. Intégrer un rituel de capitalisation dans les skills de complétion (ship-feature, feat, bugfix, hotfix, commit-change) + créer un skill `/close` pour le rituel de fin de session. +- **Pourquoi** : regrouper tout le méta-projet (config IA + tâches + mémoire + audits) sous `.claude/` isole la gouvernance Claude du code réel. Alignement sur la doc officielle Claude Code memory. Sans intégration dans les skills, les registres resteraient vides (aspirational text). +- **Alternatives rejetées** : + - Laisser `./tasks/` à la racine — refusée : encombre le repo, mélange signal code / signal gouvernance. + - Utiliser `.claude/agent-memory/` pour tout — refusée : `agent-memory/` a un rôle distinct (déjà utilisé par d'autres outils). + - Rituel uniquement en texte aspirationnel dans CLAUDE.md — refusée : zéro garantie d'exécution, les registres resteraient vides. + - Hook `Stop` pour poser les 3 questions à chaque tour — refusée : trop bruyant. diff --git a/.claude/memory/evals.md b/.claude/memory/evals.md new file mode 100644 index 0000000..28aaf43 --- /dev/null +++ b/.claude/memory/evals.md @@ -0,0 +1,34 @@ +--- +type: evals_registry +entry_prefix: EVAL +schema: + id: EVAL-XXX + date: YYYY-MM-DD + output: string (what was produced) + method: string (how it was evaluated - manual read, test, benchmark, user feedback) + anomalies: list of strings (what was wrong, missing, surprising) + action: [keep | correct | deprecate] +rules: + - Log an eval whenever you validate the quality of something Claude produced (report, audit, plan, generated code). + - Action keep - the output is fit for purpose as-is. + - Action correct - needs revision; capture what. + - Action deprecate - the approach itself is flawed; link to the decision that replaces it. +--- + +# Evals registry (EVAL) + +## Index + +| ID | Date | Output | Action | +|----|------|--------|--------| +| EVAL-001 | 2026-04-23 | Plan de restructuration .claude/ (STEP 2 de ship-feature) | keep | + +--- + +## EVAL-001 — Plan de restructuration `.claude/` + +- **Date** : 2026-04-23 +- **Output** : plan 21 tâches pour migrer `tasks/` vers `.claude/tasks/` + créer `.claude/memory/` + `.claude/audits/` + intégrer CAPITALIZE dans 5 skills + créer `/close`. +- **Méthode** : relecture manuelle des 5 skills/agents impactés, vérification que rtk est path-agnostic, symlink `~/.claude/CLAUDE.md` → projet confirmé (un seul fichier à éditer). Radical-honesty check sur le ritual "session-close" : confirmé comme aspirationnel sans intégration dans les skills → scope élargi à Option D. +- **Anomalies** : aucune bloquante. Note : `tasks/LESSONS.md` était vide (101B, juste un header) — migration vers `learnings.md` symbolique. +- **Action** : keep — plan validé, prêt pour exécution. diff --git a/.claude/memory/journal.md b/.claude/memory/journal.md new file mode 100644 index 0000000..1ba9998 --- /dev/null +++ b/.claude/memory/journal.md @@ -0,0 +1,19 @@ +--- +type: journal +schema: + entry: one date heading per working session + body: 3-5 lines max - what was done, decided, blocked +rules: + - One heading per date (YYYY-MM-DD), not per session. + - Append at the end. Never edit past entries. + - Keep it terse. Details belong in decisions/learnings/blockers - this is a timeline only. +--- + +# Journal + +## 2026-04-23 + +- Restructuré l'arborescence : `tasks/` → `.claude/tasks/`, créé `.claude/memory/` (5 registres) + `.claude/audits/`. +- Adapté CLAUDE.md + skills `onboard`, `init-project` + agent `onboarder` + `lib/project-archetypes/dotfiles-meta.md`. +- Ajouté un step CAPITALIZE dans `ship-feature`, `bugfix`, `hotfix`, `feat`, `commit-change` + créé skill `/close` pour rituel de fin de session. +- Décision BDR-002 actée. diff --git a/.claude/memory/learnings.md b/.claude/memory/learnings.md new file mode 100644 index 0000000..01c0ee2 --- /dev/null +++ b/.claude/memory/learnings.md @@ -0,0 +1,32 @@ +--- +type: learnings_registry +entry_prefix: LRN +schema: + id: LRN-XXX + date: YYYY-MM-DD + pattern: string (what was observed, abstracted) + context: string (where/when it happened - concrete) + future_application: string (when to recall this) +rules: + - Capture learnings that apply beyond the current task. + - Abstract from the incident - the pattern is what is reusable, not the one-shot fact. + - Link to source (commit, file, PR) when possible. + - Replaces the previous LESSONS.md format. Old file was empty - no content to migrate. +--- + +# Learnings registry (LRN) + +## Index + +| ID | Date | Pattern | Applies to | +|----|------|---------|------------| +| LRN-001 | 2026-04-22 | `rtk` shape-compression breaks pipes | any pipeline chaining `rtk curl/cat/read` into `jq`, `python -c`, `awk` | + +--- + +## LRN-001 — `rtk` shape-compression breaks downstream parsers + +- **Date** : 2026-04-22 +- **Pattern** : quand un outil de tracking (`rtk`) intercepte stdout et retourne une représentation schématisée/compressée au lieu du payload brut, tout parseur en aval casse silencieusement — parce que l'utilisateur (ou le LLM) ne voit jamais la sortie `rtk`, seulement l'erreur du parseur. +- **Contexte** : `rtk curl` remplace la sortie JSON brute par une version tokenisée, indépendamment du TTY vs pipe. Les hooks Claude Code réécrivent `curl` → `rtk curl` automatiquement, donc impossible à prévoir sans connaître le hook. +- **Application future** : pour tout outil qui auto-réécrit des commandes standard, vérifier explicitement le comportement en pipe. Workaround documenté : `exclude_commands=["curl"]` dans `~/.config/rtk/config.toml`, ou `rtk proxy`. Voir `BLK-001`. diff --git a/tasks/TODO.md b/.claude/tasks/TODO.md similarity index 100% rename from tasks/TODO.md rename to .claude/tasks/TODO.md diff --git a/tasks/rtk-upstream-issue.md b/.claude/tasks/rtk-upstream-issue.md similarity index 100% rename from tasks/rtk-upstream-issue.md rename to .claude/tasks/rtk-upstream-issue.md diff --git a/tasks/LESSONS.md b/tasks/LESSONS.md deleted file mode 100644 index 88d5ecf..0000000 --- a/tasks/LESSONS.md +++ /dev/null @@ -1,4 +0,0 @@ -# Lessons - -| Date | What went wrong | Rule to avoid it | -|------|----------------|-----------------| diff --git a/templates/memory/blockers.md b/templates/memory/blockers.md new file mode 100644 index 0000000..e3ce195 --- /dev/null +++ b/templates/memory/blockers.md @@ -0,0 +1,34 @@ +--- +type: blockers_registry +entry_prefix: BLK +schema: + id: BLK-XXX + date: YYYY-MM-DD + friction: string (what was blocked) + real_cause: string (root cause, not symptom) + solution: string (workaround or fix) + status: [open | resolved | upstream] +rules: + - Open a blocker as soon as friction > 15 min wasted. Close it with a real cause, not "moved on". + - Link to upstream issue / PR / commit when applicable. + - If cause is a bug in a dependency, set status upstream with a pointer to the tracker. +--- + +# Blockers registry (BLK) + +## Index + +| ID | Date | Friction | Status | +|----|------|---------|--------| + + diff --git a/templates/memory/decisions.md b/templates/memory/decisions.md new file mode 100644 index 0000000..ac0780e --- /dev/null +++ b/templates/memory/decisions.md @@ -0,0 +1,39 @@ +--- +type: decisions_registry +entry_prefix: BDR +schema: + id: BDR-XXX + date: YYYY-MM-DD + title: string (<= 80 chars) + decision: string (what was chosen) + why: string (motivation, context) + alternatives: list of strings (what was rejected + why) + status: [proposed | accepted | deprecated | superseded] + supersedes: BDR-XXX (optional) +rules: + - Append-only. Never rewrite past entries - add a new one with status superseded if needed. + - One entry per non-trivial choice. Trivial = reversible in under 10 min with no cross-file impact. + - Capture why more carefully than what - the what rots, the why lasts. +--- + +# Decisions registry (BDR) + +## Index + +| ID | Date | Title | Status | +|----|------|-------|--------| + + diff --git a/templates/memory/evals.md b/templates/memory/evals.md new file mode 100644 index 0000000..80575df --- /dev/null +++ b/templates/memory/evals.md @@ -0,0 +1,35 @@ +--- +type: evals_registry +entry_prefix: EVAL +schema: + id: EVAL-XXX + date: YYYY-MM-DD + output: string (what was produced) + method: string (how it was evaluated - manual read, test, benchmark, user feedback) + anomalies: list of strings (what was wrong, missing, surprising) + action: [keep | correct | deprecate] +rules: + - Log an eval whenever you validate the quality of something Claude produced (report, audit, plan, generated code). + - Action keep - the output is fit for purpose as-is. + - Action correct - needs revision; capture what. + - Action deprecate - the approach itself is flawed; link to the decision that replaces it. +--- + +# Evals registry (EVAL) + +## Index + +| ID | Date | Output | Action | +|----|------|--------|--------| + + diff --git a/templates/memory/journal.md b/templates/memory/journal.md new file mode 100644 index 0000000..54e5468 --- /dev/null +++ b/templates/memory/journal.md @@ -0,0 +1,22 @@ +--- +type: journal +schema: + entry: one date heading per working session + body: 3-5 lines max - what was done, decided, blocked +rules: + - One heading per date (YYYY-MM-DD), not per session. + - Append at the end. Never edit past entries. + - Keep it terse. Details belong in decisions/learnings/blockers - this is a timeline only. +--- + +# Journal + + diff --git a/templates/memory/learnings.md b/templates/memory/learnings.md new file mode 100644 index 0000000..9808500 --- /dev/null +++ b/templates/memory/learnings.md @@ -0,0 +1,32 @@ +--- +type: learnings_registry +entry_prefix: LRN +schema: + id: LRN-XXX + date: YYYY-MM-DD + pattern: string (what was observed, abstracted) + context: string (where/when it happened - concrete) + future_application: string (when to recall this) +rules: + - Capture learnings that apply beyond the current task. + - Abstract from the incident - the pattern is what is reusable, not the one-shot fact. + - Link to source (commit, file, PR) when possible. +--- + +# Learnings registry (LRN) + +## Index + +| ID | Date | Pattern | Applies to | +|----|------|---------|------------| + +