This commit is contained in:
parent
07de342fc2
commit
35fe877d58
32 changed files with 3822 additions and 200 deletions
209
AGENTS.md
209
AGENTS.md
|
|
@ -2,203 +2,26 @@
|
|||
|
||||
Sokko G est une webapp React + Vite + Sass centrée sur des toolboxes locales et des pages de jeu.
|
||||
|
||||
## Références projet
|
||||
## Portée
|
||||
|
||||
Avant de modifier un outil toolbox, le stockage IndexedDB, l'import/export ou les formats de données, lire :
|
||||
Les règles détaillées sont réparties par zone pour limiter le contexte chargé à chaque tâche :
|
||||
|
||||
- `docs/STORAGE_SCHEMA.md`
|
||||
- `docs/FEATURE_CHECKLIST.md`
|
||||
- `website/AGENTS.md` : application React, contenu éditable, serveur de développement, validation.
|
||||
- `website/src/features/toolboxes/AGENTS.md` : outils toolbox, stockage IndexedDB, import/export, hooks partagés.
|
||||
- `website/src/styles/AGENTS.md` : Sass, design system, composants visuels et patterns UI.
|
||||
- `docs/AGENTS.md` : documentation projet, schémas de stockage et checklists.
|
||||
- `tests/AGENTS.md` : validations de données et tests.
|
||||
|
||||
Avant de modifier le style, les composants UI, les layouts, les boutons, cards, panels, hovers, scrollbars ou notifications, lire :
|
||||
Lire le fichier d'instructions le plus proche du code modifié avant d'intervenir.
|
||||
|
||||
- `DESIGN_SYSTEM.md`
|
||||
## Règles globales
|
||||
|
||||
Après ce type de modification, mettre à jour ces documents si le format ou le workflow change.
|
||||
- Utiliser `rg`, `git status --short`, `git diff --stat` et les commandes ciblées avant les recherches larges.
|
||||
- Ne pas réintroduire de fallback massif type `DEFAULT_SITE_CONTENT` dans le code React.
|
||||
- Chaque nouveau fichier source ou test commence par un commentaire court `Rôle : ...` dans le style du langage.
|
||||
- Ne pas lancer automatiquement un serveur sur `5174` si `5173` répond déjà.
|
||||
- Avant de terminer une modification significative, lancer `npm run check`.
|
||||
|
||||
## Contenu éditable
|
||||
## Beads
|
||||
|
||||
Le contenu éditorial du site doit rester dans :
|
||||
|
||||
- `website/public/data/site.json`
|
||||
- `website/public/data/<gameId>/...`
|
||||
|
||||
Ne pas réintroduire de fallback massif type `DEFAULT_SITE_CONTENT` dans le code React. `site.json` est la source de vérité et `npm run check` doit échouer si le contenu requis est invalide.
|
||||
|
||||
## En-têtes de fichiers
|
||||
|
||||
Chaque nouveau fichier source ou test doit commencer par un commentaire court `Rôle : ...` décrivant ce qu'il gère.
|
||||
|
||||
- mettre cet en-tête à jour si la responsabilité du fichier change ;
|
||||
- garder l'intro concise, une à trois lignes maximum selon la complexité du fichier ;
|
||||
- quand un fichier existant est modifié, vérifier si son en-tête mérite d'être précisé au-delà de la ligne générique initiale ;
|
||||
- enrichir l'en-tête quand le fichier porte une logique transverse, un hook partagé, un format de données ou un comportement réutilisable ;
|
||||
- ne pas allonger mécaniquement les en-têtes des fichiers simples : la précision doit aider à comprendre la responsabilité réelle du fichier ;
|
||||
- utiliser `// Rôle : ...` dans les fichiers JS, JSX, MJS et SCSS.
|
||||
|
||||
## Hooks et comportements partagés
|
||||
|
||||
Quand un comportement est déjà couvert par un hook ou un helper partagé, privilégier son utilisation plutôt qu'une réimplémentation locale afin de garder une expérience homogène.
|
||||
|
||||
- pour la réorganisation par drag & drop, utiliser `useGroupedReorder` dès qu'il s'agit d'items, groupes, catégories, boundaries, parent/enfant ou listes horizontales/verticales ;
|
||||
- réserver `usePointerReorder` au moteur bas niveau ou aux cas DOM très spécifiques qui ne correspondent pas au modèle applicatif de `useGroupedReorder` ;
|
||||
- si une variation est nécessaire, vérifier d'abord si elle doit devenir une option du hook partagé ;
|
||||
- demander ou expliciter le choix uniquement quand la variation est réellement métier et pourrait alourdir le hook ;
|
||||
- éviter de dupliquer dans un outil une règle de reorder générique déjà prise en charge par le hook.
|
||||
|
||||
## Outils toolbox
|
||||
|
||||
Chaque outil toolbox doit rester dans son propre fichier dans :
|
||||
|
||||
```text
|
||||
website/src/features/toolboxes/modules/
|
||||
```
|
||||
|
||||
Quand un outil est ajouté ou modifié :
|
||||
|
||||
- déclarer l'outil dans `website/src/features/toolboxes/modules/index.jsx` ;
|
||||
- ajouter les textes dans `website/public/data/site.json` ;
|
||||
- mettre à jour la validation dans `tests/helpers/data-validation.mjs` ;
|
||||
- mettre à jour la structure IndexedDB dans `docs/STORAGE_SCHEMA.md` si nécessaire ;
|
||||
- vérifier l'affichage page toolbox et panneau latéral.
|
||||
|
||||
Quand la structure de données d'un outil change, ne pas prévoir de compatibilité legacy, de migration ou de tolérance d'anciens formats, sauf demande explicite. Le format documenté dans `docs/STORAGE_SCHEMA.md` doit rester le format cible strict.
|
||||
|
||||
## Style
|
||||
|
||||
Le style est en Sass dans `website/src/styles/`.
|
||||
|
||||
`DESIGN_SYSTEM.md` est la référence visuelle du projet et doit rester synchronisé avec les patterns réellement utilisés.
|
||||
|
||||
Privilégier :
|
||||
|
||||
- les tokens existants ;
|
||||
- les classes de boutons existantes ;
|
||||
- les patterns visuels déjà présents pour les cards, panels, badges, scrollbars et hovers.
|
||||
|
||||
Éviter les styles isolés qui ne réutilisent pas le thème.
|
||||
|
||||
## Serveur de développement
|
||||
|
||||
Si le port `5173` est déjà occupé, considérer qu'un `npm run dev` est probablement déjà en cours. Ne pas lancer automatiquement un nouveau serveur sur `5174` dans ce cas.
|
||||
|
||||
Quand une vérification navigateur est nécessaire après des modifications, utiliser l'instance déjà ouverte sur `http://localhost:5173` si elle répond.
|
||||
|
||||
## Validation
|
||||
|
||||
Avant de terminer une modification significative, lancer :
|
||||
|
||||
```bash
|
||||
npm run check
|
||||
```
|
||||
|
||||
Le check couvre la génération des index de listes, les tests et le build de production.
|
||||
|
||||
## Pré-push check
|
||||
|
||||
Quand l'utilisateur indique qu'il va push, faire une passe globale avant de conclure.
|
||||
|
||||
Vérifier et corriger si nécessaire :
|
||||
|
||||
- code mort, imports inutilisés, fonctions inutilisées, styles devenus obsolètes ;
|
||||
- duplication de code ou de style pouvant être factorisée sans complexifier le projet ;
|
||||
- composants qui utilisent des classes trop spécifiques alors qu'un pattern général existe déjà ;
|
||||
- incohérences entre boutons, badges, cards, panels, hovers, focus states et scrollbars ;
|
||||
- cohérence entre `website/public/data/site.json`, les validations et les textes utilisés ;
|
||||
- cohérence entre `docs/STORAGE_SCHEMA.md` et les normalisations IndexedDB réelles ;
|
||||
- import/export des toolboxes quand la structure de données a changé ;
|
||||
- champs inutiles persistés dans IndexedDB ou dans les exports ;
|
||||
- fichiers générés attendus, notamment les index de listes ;
|
||||
- optimisations simples de performance : recalculs au render, listeners non nettoyés, observers, effets CSS lourds appliqués en masse.
|
||||
|
||||
Utiliser en priorité :
|
||||
|
||||
```bash
|
||||
rg
|
||||
git status --short
|
||||
git diff --stat
|
||||
npm run check
|
||||
```
|
||||
|
||||
Après lecture du diff pré-push, proposer un exemple de message de commit en anglais, concis et représentatif des changements réellement présents.
|
||||
|
||||
Ne pas faire de refactor large sans bénéfice clair. Garder les corrections pré-push ciblées, vérifiables et faciles à relire.
|
||||
|
||||
<!-- BEGIN BEADS INTEGRATION v:1 profile:minimal hash:970c3bf2 -->
|
||||
## Beads Issue Tracker
|
||||
|
||||
This project uses **bd (beads)** for issue tracking. Run `bd prime` to see full workflow context and commands.
|
||||
|
||||
### Quick Reference
|
||||
|
||||
```bash
|
||||
bd ready # Find available work
|
||||
bd show <id> # View issue details
|
||||
bd update <id> --claim # Claim work
|
||||
bd close <id> # Complete work
|
||||
```
|
||||
|
||||
### Rules
|
||||
|
||||
- Use `bd` for ALL task tracking — do NOT use TodoWrite, TaskCreate, or markdown TODO lists
|
||||
- Run `bd prime` for detailed command reference and session close protocol
|
||||
- Use `bd remember` for persistent knowledge — do NOT use MEMORY.md files
|
||||
|
||||
**Architecture in one line:** issues live in a local Dolt DB; sync uses `refs/dolt/data` on your git remote; `.beads/issues.jsonl` is a passive export. See https://github.com/gastownhall/beads/blob/main/docs/SYNC_CONCEPTS.md for details and anti-patterns.
|
||||
|
||||
## Agent Context Profiles
|
||||
|
||||
The managed Beads block is task-tracking guidance, not permission to override repository, user, or orchestrator instructions.
|
||||
|
||||
- **Conservative (default)**: Use `bd` for task tracking. Do not run git commits, git pushes, or Dolt remote sync unless explicitly asked. At handoff, report changed files, validation, and suggested next commands.
|
||||
- **Minimal**: Keep tool instruction files as pointers to `bd prime`; use the same conservative git policy unless active instructions say otherwise.
|
||||
- **Team-maintainer**: Only when the repository explicitly opts in, agents may close beads, run quality gates, commit, and push as part of session close. A current "do not commit" or "do not push" instruction still wins.
|
||||
|
||||
## Session Completion
|
||||
|
||||
This protocol applies when ending a Beads implementation workflow. It is subordinate to explicit user, repository, and orchestrator instructions.
|
||||
|
||||
1. **File issues for remaining work** - Create beads for anything that needs follow-up
|
||||
2. **Run quality gates** (if code changed) - Tests, linters, builds
|
||||
3. **Update issue status** - Close finished work, update in-progress items
|
||||
4. **Handle git/sync by active profile**:
|
||||
```bash
|
||||
# Conservative/minimal/default: report status and proposed commands; wait for approval.
|
||||
git status
|
||||
|
||||
# Team-maintainer opt-in only, unless current instructions forbid it:
|
||||
git pull --rebase
|
||||
bd dolt push
|
||||
git push
|
||||
git status
|
||||
```
|
||||
5. **Hand off** - Summarize changes, validation, issue status, and any blocked sync/commit/push step
|
||||
|
||||
**Critical rules:**
|
||||
- Explicit user or orchestrator instructions override this Beads block.
|
||||
- Do not commit or push without clear authority from the active profile or the current user request.
|
||||
- If a required sync or push is blocked, stop and report the exact command and error.
|
||||
<!-- END BEADS INTEGRATION -->
|
||||
|
||||
<!-- BEGIN BEADS CODEX SETUP: generated by bd setup codex -->
|
||||
## Beads Issue Tracker
|
||||
|
||||
Use Beads (`bd`) for durable task tracking in repositories that include it. Use the `beads` skill at `.agents/skills/beads/SKILL.md` (project install) or `~/.agents/skills/beads/SKILL.md` (global install) for Beads workflow guidance, then use the `bd` CLI for issue operations.
|
||||
|
||||
### Quick Reference
|
||||
|
||||
```bash
|
||||
bd ready # Find available work
|
||||
bd show <id> # View issue details
|
||||
bd update <id> --claim # Claim work
|
||||
bd close <id> # Complete work
|
||||
bd prime # Refresh Beads context
|
||||
```
|
||||
|
||||
### Rules
|
||||
|
||||
- Use `bd` for all task tracking; do not create markdown TODO lists.
|
||||
- Run `bd prime` when Beads context is missing or stale. Codex 0.129.0+ can load Beads context automatically through native hooks; use `/hooks` to inspect or toggle them.
|
||||
- Keep persistent project memory in Beads via `bd remember`; do not create ad hoc memory files.
|
||||
|
||||
**Architecture in one line:** issues live in a local Dolt DB; sync uses `refs/dolt/data` on your git remote; `.beads/issues.jsonl` is a passive export. See https://github.com/gastownhall/beads/blob/main/docs/SYNC_CONCEPTS.md for details and anti-patterns.
|
||||
<!-- END BEADS CODEX SETUP -->
|
||||
Ce dépôt utilise Beads (`bd`) pour le suivi durable des tâches. Utiliser `bd prime` quand un workflow Beads est nécessaire, et ne pas commit/push/sync sans demande explicite.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue