gandalf/secubox-deb

Fork 0

mirror of https://github.com/CyberMind-FR/secubox-deb.git synced 2026-06-29 01:59:26 +00:00

Table of Contents

Multi-Agent Worktree Workflow

🟢 ROOT — Vue d'ensemble

Pourquoi
Layout sur disque
Branche → préfixe (dérivé du label issue)

🔴 BOOT — Quick start
🔵 MESH — Référence des sous-commandes

start --issue <N>
list
sync [<N>]
finish
clean <N>
Codes de sortie

🟣 MIND — Prompt pour agents GPT / Gemini / Copilot
🟠 WALL — Pièges courants
🟢 ROOT — Sources de vérité

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

Multi-Agent Worktree Workflow

Un agent · une issue · une branche · un worktree.

Le helper scripts/agent-worktree.sh (livré dans SecuBox-Deb depuis PR #85) lie chaque tâche non-triviale à une issue GitHub, une branche dédiée, et un git worktree isolé sous ~/CyberMindStudio/secubox-deb-worktrees/. Cela permet à plusieurs agents (Claude Code, GPT, Gemini, Copilot, ou un humain) de travailler simultanément sur le même dépôt sans collision d'état git.

🟢 ROOT — Vue d'ensemble

Pourquoi

Sans isolation, deux sessions d'agent qui partagent le même checkout doivent jongler avec git stash / git checkout à chaque changement de contexte. Les worktrees git résolvent ce problème : un seul .git/ partagé, plusieurs dossiers de travail indépendants chacun sur sa propre branche.

Ce workflow ajoute par-dessus :

traçabilité : chaque branche est nommée d'après une issue GitHub (feature/<#>-<slug>)
discipline de cycle : start → code → finish → clean, refusée à chaque étape si l'état est mauvais
dogfooding multi-agent : la doctrine est codifiée dans CLAUDE.md, le script fonctionne pareil pour tout agent qui sait exécuter du shell

Layout sur disque

~/CyberMindStudio/
├── secubox-deb/secubox-deb/              ← checkout principal (master / travail humain)
└── secubox-deb-worktrees/                ← racine des worktrees agents
    ├── 80-apt-tier-manifest-helper/      ← worktree pour issue #80
    ├── 83-multi-agent-worktree-workflow/
    └── 92-eye-remote-led-fix/

Branche → préfixe (dérivé du label issue)

Label GitHub	Préfixe
`bug`, `fix`	`fix/`
`documentation`	`docs/`
`infra`, `chore`	`chore/`
tout autre / défaut	`feature/`

Le slug est dérivé du titre de l'issue : minuscules, ASCII-folded (iconv //TRANSLIT), tirets, 40 caractères max.

🔴 BOOT — Quick start

# 1. Créer une issue GitHub (label déterminera le préfixe de branche)
gh issue create --title "Fix HyperPixel init on cold boot" --label "bug"
# → returns #92

# 2. Démarrer le worktree
bash scripts/agent-worktree.sh start --issue 92
# → branch:   fix/92-fix-hyperpixel-init-on-cold-boot
# → worktree: ~/CyberMindStudio/secubox-deb-worktrees/92-fix-hyperpixel-init-on-cold-boot
# → next:     cd <path>

# 3. Travailler dans le worktree
cd ~/CyberMindStudio/secubox-deb-worktrees/92-fix-hyperpixel-init-on-cold-boot
# ... edit, test, commit (avec "(ref #92)" dans chaque message)

# 4. Pousser et ouvrir la PR
bash scripts/agent-worktree.sh finish
# → git push -u origin <branch>
# → gh pr create avec titre = titre de l'issue, body = "Closes #92"

# 5. Après que la PR est mergée par un humain
bash scripts/agent-worktree.sh clean 92
# → git worktree remove + git branch -d

🔵 MESH — Référence des sous-commandes

`start --issue <N>`

Crée la branche et le worktree associés à l'issue <N>.

Précondition	Sortie si violée
`gh auth status` OK	2
Working tree propre dans le checkout courant	3
Pas déjà dans un worktree sous `WORKTREE_ROOT`	3
Issue existe sur GitHub	2
Branche n'existe pas déjà localement	3
Path de worktree libre	3

Options : --dry-run (affiche sans agir), --verbose.

Effet de bord : commentaire automatique sur l'issue (Worktree created at <path>, branch <branch>).

`list`

Affiche tous les worktrees enregistrés, décorés ainsi :

[primary] master  /home/.../secubox-deb  ahead:0 behind:20 clean
fix/92-fix-hyperpixel-init   /home/.../92-fix-hyperpixel-init   ahead:3 behind:0 dirty

Tag [primary] pour le checkout principal (hors WORKTREE_ROOT). ahead/behind calculé contre origin/master. État clean/dirty selon git diff HEAD.

`sync [<N>]`

Rebase le worktree courant (ou celui de l'issue <N>) sur origin/master.

sync         # depuis le worktree courant
sync 92      # résolution par numéro d'issue depuis n'importe où

Conflit de rebase → git rebase --abort, code de sortie 3, résolution manuelle laissée à l'humain.

`finish`

À exécuter depuis l'intérieur d'un worktree. Pousse la branche et ouvre la PR.

Précondition	Sortie
Working tree propre	3
Branche d'agent valide (`feature/`, `fix/`, `docs/`, `chore/`)	1
Au moins 1 commit ahead de `origin/master`	3

Le titre de la PR est récupéré via gh issue view <N> --json title. Le body contient Closes #<N>. Le worktree n'est pas supprimé — laissé en place pour d'éventuelles corrections de review.

`clean <N>`

Après que la PR a été mergée, supprime worktree et branche locale.

Précondition	Sortie
Worktree existe pour l'issue	2
Working tree du worktree propre	3
PR mergée (sauf `--force`)	3

Codes de sortie

Code	Sens
0	Succès
1	Erreur générique / usage
2	Précondition (issue manquante, gh non auth)
3	Mauvais état (dirty, conflit, PR non mergée)
4	Réseau (gh API, git push)

🟣 MIND — Prompt pour agents GPT / Gemini / Copilot

Le bloc ci-dessous est conçu pour être collé tel quel comme system prompt (ou première instruction utilisateur) à un agent non-Claude (GPT-5, Gemini, Copilot, agents OpenAI Codex…) afin qu'il suive correctement la doctrine multi-agent de SecuBox-Deb.

ℹ️ Pour Claude Code : la doctrine est déjà chargée via CLAUDE.md, aucun prompt à coller. Pour Anthropic API en standalone, utiliser ce prompt aussi.

You are an autonomous coding agent working on the SecuBox-Deb repository
(https://github.com/CyberMind-FR/secubox-deb). It is a Debian-based
cybersecurity appliance, ARM64-first, targeting ANSSI CSPN certification.

This repository enforces a strict multi-agent workflow. You MUST follow it
for any non-trivial task — that means: any feature, any bug fix, any
documentation work that will become a pull request, any task touching
3 or more files, or any task expected to take more than 30 minutes.

You may SKIP this workflow only for:
  - Single-file edits to .claude/HISTORY.md, .claude/WIP.md, .claude/TODO.md
  - Read-only exploration or answering questions
  - Administrative master commits (tags, version bumps)

============================================================
THE MANDATORY CYCLE
============================================================

For every qualifying task:

1. ENSURE A GITHUB ISSUE EXISTS
   - If one already exists for the work, note the issue number <N>.
   - If not, create one BEFORE writing any code:
       gh issue create --title "<concise task title>" \
                       --body "<context, tasks, files>" \
                       --label "<bug|enhancement|documentation>"
     The label determines the branch prefix:
       bug / fix         -> fix/
       documentation     -> docs/
       infra / chore     -> chore/
       anything else     -> feature/

2. CREATE THE WORKTREE
   From the primary checkout (~/CyberMindStudio/secubox-deb/secubox-deb):
       bash scripts/agent-worktree.sh start --issue <N>
   This creates a branch named "<prefix>/<N>-<slug>" and a worktree at
   ~/CyberMindStudio/secubox-deb-worktrees/<N>-<slug>/.
   The script will refuse if:
     - the working tree is dirty (exit 3)
     - gh is not authenticated (exit 2)
     - the issue does not exist (exit 2)
     - the same issue already has a worktree (exit 3)
   In any of these cases, DO NOT retry blindly. Read the error and fix
   the underlying state (commit, stash, authenticate, or pick a different
   issue number).

3. WORK IN THE WORKTREE
       cd ~/CyberMindStudio/secubox-deb-worktrees/<N>-<slug>
   All edits, builds, tests, and commits happen here. Every commit MUST
   include "(ref #<N>)" in its message and end with the project
   Co-Authored-By line found in CLAUDE.md.

4. SYNC IF MASTER MOVES (optional)
   If origin/master advances while you are working:
       bash scripts/agent-worktree.sh sync
   On rebase conflict the script aborts cleanly (exit 3) — resolve the
   conflict manually before re-running.

5. FINISH — OPEN THE PR
       bash scripts/agent-worktree.sh finish
   This pushes the branch, fetches the issue title from GitHub, and opens
   a PR with body "Closes #<N>". The worktree is intentionally NOT
   deleted at this stage — leave it in place for review feedback fixes.

6. WAIT FOR HUMAN VALIDATION
   You do not merge your own PR. A human reviews and merges.

7. CLEAN UP AFTER MERGE
       bash scripts/agent-worktree.sh clean <N>
   This removes the worktree and deletes the local branch. The script
   refuses if the PR is not merged (exit 3, use --force only if you know
   what you are doing).

============================================================
PARALLELISM
============================================================

Two agents (or two sessions of the same agent) may run in parallel on
two different issues — each has its own worktree, its own branch, its
own working tree. The script will refuse to create a second worktree
for an issue that already has one, so collisions are impossible by
construction.

============================================================
EXIT CODE CONTRACT
============================================================

The script communicates errors through exit codes — use them to decide
how to recover:

  0  success
  1  generic / usage error (your CLI invocation was wrong)
  2  precondition failed (auth, issue lookup) — fix and retry
  3  bad state (dirty, conflict, non-merged PR) — fix the state
  4  network or remote error (gh API down, push refused) — retry later

============================================================
COMMANDS REFERENCE
============================================================

  bash scripts/agent-worktree.sh --help
  bash scripts/agent-worktree.sh start  --issue <N> [--dry-run] [-v]
  bash scripts/agent-worktree.sh list   [--verbose]
  bash scripts/agent-worktree.sh sync   [<N>]
  bash scripts/agent-worktree.sh finish [--dry-run]
  bash scripts/agent-worktree.sh clean  <N> [--force]

============================================================
WHEN IN DOUBT
============================================================

  - Read the wiki: https://github.com/CyberMind-FR/secubox-deb/wiki/Multi-Agent-Worktree
  - Read the spec: docs/superpowers/specs/2026-05-12-multi-agent-worktree-workflow-design.md
  - Read the doctrine section "🌿 Multi-Agent Worktree Workflow — Obligatoire" in CLAUDE.md

Never delete a worktree, branch, or PR you did not create. Never force-push
master. Never bypass the script for a task that qualifies for the cycle.

🟠 WALL — Pièges courants

Symptôme	Cause probable	Remède
`start: working tree is dirty` (exit 3)	Modifications non commitées dans le checkout principal	`git stash` ou commit avant `start`
`start: gh not authenticated` (exit 2)	Token expiré	`gh auth login`
`start: issue #X not found` (exit 2)	Numéro d'issue erroné, ou repo wrong	Vérifier `gh issue list`
`finish: branch has no commits ahead` (exit 3)	Tu n'as rien committé dans le worktree	Faire au moins un commit
`finish: not on an agent branch` (exit 1)	Tu n'es pas dans un worktree créé par `start`	`cd` dans le bon dossier
`clean: PR is 'OPEN', refusing` (exit 3)	PR pas encore mergée	Attendre le merge, ou `--force` à tes risques
Slug trop court (titre 100% non-ASCII)	iconv ne peut pas translit	Fallback automatique `<prefix>/<N>-issue`
Deux issues avec slugs identiques	Préfixe `<N>-` les distingue	Aucune action requise

🟢 ROOT — Sources de vérité

Script : scripts/agent-worktree.sh
Bibliothèque : scripts/lib/agent-worktree-lib.sh
Tests : scripts/tests/test-agent-worktree.sh (26 cas)
Spec : docs/superpowers/specs/2026-05-12-multi-agent-worktree-workflow-design.md
Doctrine CLAUDE.md : section ## 🌿 Multi-Agent Worktree Workflow — Obligatoire
Help opérationnel : bash scripts/agent-worktree.sh --help

Page maintenue par CyberMind · Gérald Kerma · 2026-05-12

SecuBox | FR | DE | 中文 | v2.2.4-pre1

Projet

Soutenir

🔴 BOOT — Démarrer

Multiboot ⭐
Live-USB-VirtualBox run-vbox.sh
Live-USB-QEMU run-qemu.sh
Live-USB | FR | DE | 中文
Installation | FR | DE | 中文
ARM-Installation | FR | DE | 中文
ESPRESSObin | FR | DE | 中文
Eye-Remote 📡
Android-ToolBox 📱 one-tap R3
Browser-Extension 🧩 cartographie
QEMU-ARM64 🖥️

🟢 ROOT — Configuration

Configuration | FR | DE | 中文
Troubleshooting | FR | DE | 中文

🟣 MIND — Modules

Anti-Track 🛡️ bloque · empoisonne · anonymise
ThreatMesh 🛰️ blocklist souveraine (feeds + mesh, sans CAPI) | FR
MODULES-EN 🇬🇧
MODULES-FR 🇫🇷
MODULES-DE 🇩🇪
MODULES-ZH 🇨🇳

🔵 MESH — Référence

API-Reference | FR | DE | 中文
UI-COMPARISON

🟠 WALL — Matériel

🤖 Workflow Agents

Multi-Agent-Worktree — un agent · une issue · une branche

Liens

SecuBox-Deb · Licence : CMSD-1.0 (Source-Disclosed) Contact : CyberMind · Gérald Kerma · Notre-Dame-du-Cruet, Savoie Hardware-Matrix · Acknowledgments · Wiki v2.5.0