cc-workspace 4.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vincent / Lota Cloud
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,382 @@
+# Claude Code Multi-Workspace Orchestrator v4.0
+
+Un systeme pour piloter des projets multi-services depuis Claude Code.
+L'orchestrateur (Opus) ne code jamais dans les repos. Il clarifie, planifie,
+delegue a des teammates qui travaillent en parallele dans chaque repo.
+
+> Claude Code v2.1.47+ / Opus 4.6 / Sonnet 4.6 (fevrier 2026).
+> 9 skills, 11 hooks, 3 agents, 3 rules.
+
+---
+
+## Installation
+
+### Prerequis
+
+- **Claude Code** v2.1.47+
+- **Node.js** 18+
+- **jq** (`brew install jq` sur macOS, `apt install jq` sur Linux)
+
+### 1. Setup du workspace
+
+```bash
+cd ~/projets/mon-workspace
+npx claude-orchestrator init . "Mon Projet"
+```
+
+Le CLI :
+- Installe skills/rules/agents dans `~/.claude/` (si version plus recente)
+- Cree `orchestrator/` avec plans/, templates/, hooks
+- Scanne les repos freres (dossiers avec `.git/`)
+- Genere `service-profiles.md`
+- workspace.md et constitution.md en mode `[UNCONFIGURED]`
+
+### 2. Initialisation (une seule fois)
+
+```bash
+cd orchestrator/
+claude --agent workspace-init
+```
+
+L'agent `workspace-init` :
+1. Diagnostique la structure (hooks, settings, templates)
+2. Scanne les repos freres, detecte les types de projet, verifie Claude Code readiness
+3. Propose de generer les CLAUDE.md manquants (optionnel)
+4. Configuration interactive de workspace.md (section par section)
+5. Configuration interactive de constitution.md (regles projet)
+6. Rapport final avec le statut de chaque check
+
+### 3. Sessions de travail
+
+```bash
+cd orchestrator/
+claude --agent team-lead
+
+# Le team-lead propose 4 modes :
+# A -- Complet (clarify -> plan -> validate -> dispatch -> QA)
+# B -- Plan rapide (specs -> plan -> dispatch)
+# C -- Go direct (dispatch immediat)
+# D -- Single-service (1 repo, pas de waves)
+```
+
+### Mise a jour
+
+```bash
+npx claude-orchestrator update
+```
+
+Met a jour les composants globaux (~/.claude/) si la version du package est superieure.
+Les fichiers du workspace (workspace.md, constitution.md, plans/) ne sont jamais ecrases.
+
+### Diagnostic
+
+```bash
+npx claude-orchestrator doctor
+```
+
+Verifie : version installee, skills, rules, agents, hooks, jq, structure orchestrator/.
+
+---
+
+## Structure resultante
+
+```
+mon-workspace/
+├── orchestrator/                    <- tu cd ici
+│   ├── .claude/
+│   │   ├── settings.json           <- env vars uniquement
+│   │   └── hooks/
+│   │       ├── block-orchestrator-writes.sh
+│   │       ├── session-start-context.sh
+│   │       ├── validate-spawn-prompt.sh
+│   │       └── ...                  <- 11 scripts
+│   ├── CLAUDE.md                    <- profil orchestrateur
+│   ├── workspace.md                 <- rempli par workspace-init
+│   ├── constitution.md              <- rempli par workspace-init
+│   ├── templates/
+│   │   ├── workspace.template.md
+│   │   ├── constitution.template.md
+│   │   └── claude-md.template.md    <- template pour les CLAUDE.md des repos
+│   └── plans/
+│       ├── _TEMPLATE.md
+│       └── service-profiles.md
+│
+├── repo-a/          (.git)          <- teammate worktree
+├── repo-b/          (.git)          <- teammate worktree
+└── repo-c/          (.git)          <- teammate worktree
+```
+
+---
+
+## Comment ca marche
+
+### Le probleme
+
+Tu as un projet avec 3-5 repos (API, frontend, infra, etc.). Quand tu
+demandes une feature a Claude Code, il essaie de tout faire lui-meme :
+il perd le contexte, il ne peut pas travailler dans plusieurs repos a la
+fois, et il devine au lieu de demander.
+
+### La solution
+
+L'orchestrateur (Opus) ne touche jamais au code des repos. Il clarifie le besoin,
+ecrit un plan en markdown, puis envoie des teammates (Sonnet) bosser en
+parallele dans chaque repo via Agent Teams.
+
+### Qui fait quoi
+
+| Role | Modele | Ce qu'il fait |
+|------|--------|---------------|
+| **Orchestrateur** | Opus 4.6 | Clarifie, planifie, delegue, verifie. Ecrit dans orchestrator/ uniquement. |
+| **Init** | Sonnet 4.6 | Diagnostic + configuration interactive du workspace. Se lance une fois. |
+| **Teammates** | Sonnet 4.6 | Implementent dans un worktree isole, testent, commitent. |
+| **Explorateurs** | Haiku | Read-only. Scannent, verifient la coherence. |
+| **QA** | Sonnet 4.6 | Mode hostile. Min 3 problemes trouves par service. |
+
+### Les 4 modes de session
+
+| Mode | Quand l'utiliser |
+|------|--------------------|
+| **A -- Complet** | Feature complexe, multi-service, besoin de clarification |
+| **B -- Plan rapide** | Specs claires, pas de questions |
+| **C -- Go direct** | Hotfix, correction rapide, specs evidentes |
+| **D -- Single-service** | Bug ou feature isolee dans un seul repo |
+
+### Le workflow dispatch-feature (Mode A)
+
+```
+CLARIFY  -> pose max 5 questions si ambiguite
+PLAN     -> ecrit le plan dans ./plans/, attend validation
+SPAWN    -> Wave 1 : API/data en parallele
+           Wave 2 : frontend avec le contrat API valide
+           Wave 3 : infra/config si applicable
+COLLECT  -> met a jour le plan avec les resultats
+VERIFY   -> cross-service-check + qa-ruthless
+REPORT   -> bilan final
+```
+
+### Securite -- ecriture path-aware
+
+L'orchestrateur peut ecrire dans `orchestrator/` (plans, workspace.md, constitution.md)
+mais jamais dans les repos freres. Le hook `block-orchestrator-writes.sh` detecte
+dynamiquement si le chemin cible est dans un repo (presence de `.git/`).
+
+Couches de protection :
+1. `disallowedTools: Bash` dans le frontmatter agent
+2. `allowed-tools` whitelist dans le frontmatter agent
+3. Hook `PreToolUse` path-aware dans le frontmatter agent
+4. Hook `block-orchestrator-writes.sh` dans .claude/hooks/
+
+---
+
+## Les 9 skills
+
+| Skill | Role | Declencheur |
+|-------|------|-------------|
+| **dispatch-feature** | 4 modes : Clarifier -> Planifier -> Deleguer -> Suivre | "Implemente X", "nouvelle feature" |
+| **qa-ruthless** | QA hostile + audit UX | "QA", "review", "teste" |
+| **cross-service-check** | Coherence inter-repos | "cross-service", "pre-merge" |
+| **incident-debug** | Diagnostic multi-couche | "Bug", "500", "ca marche pas" |
+| **plan-review** | Sanity check du plan (Haiku) | "Review plan" |
+| **merge-prep** | Conflits, PRs, ordre de merge | "Merge", "PR" |
+| **cycle-retrospective** | Capitalisation post-cycle (Haiku) | "Retro", "retrospective" |
+| **refresh-profiles** | Re-scanner les CLAUDE.md (Haiku) | "Refresh profiles" |
+| **bootstrap-repo** | Generer un CLAUDE.md (Haiku) | "Bootstrap", "init CLAUDE.md" |
+
+Tous utilisent `context: fork` -- le resultat d'un skill n'est pas dans le
+contexte quand le suivant demarre. Le plan sur disque est la source de verite.
+
+---
+
+## Les 3 agents
+
+| Agent | Modele | Usage |
+|-------|--------|-------|
+| **team-lead** | Opus 4.6 | `claude --agent team-lead` — orchestration multi-service |
+| **workspace-init** | Sonnet 4.6 | `claude --agent workspace-init` — diagnostic + config initiale |
+| **implementer** | Sonnet 4.6 | Subagent Task avec `isolation: worktree` — implementation isolee |
+
+---
+
+## Les 11 hooks
+
+Tous les hooks sont **non-bloquants** (exit 0 + warning). Aucun hook ne bloque la session.
+
+| Hook | Event | Effet |
+|------|-------|-------|
+| **block-orchestrator-writes** | `PreToolUse` Write\|Edit\|MultiEdit | Bloque ecriture dans les repos, autorise orchestrator/ |
+| **validate-spawn-prompt** | `PreToolUse` Teammate | Warning si contexte manquant (rules, UX, tasks) |
+| **session-start-context** | `SessionStart` | Injecte plans actifs + detection premiere session |
+| **user-prompt-guard** | `UserPromptSubmit` | Warning si demande de code dans un repo |
+| **subagent-start-context** | `SubagentStart` | Injecte plan actif + constitution |
+| **permission-auto-approve** | `PermissionRequest` | Auto-approve Read/Glob/Grep |
+| **track-file-modifications** | `PostToolUse` (async) | Log des fichiers modifies |
+| **teammate-idle-check** | `TeammateIdle` | Warning si taches restantes |
+| **task-completed-check** | `TaskCompleted` | Warning si tests echoues |
+| **worktree-create-context** | `WorktreeCreate` | Rappelle de lire CLAUDE.md du repo |
+| **notify-user** | `Notification` | Notification desktop |
+
+---
+
+## Les 3 templates
+
+| Template | Usage |
+|----------|-------|
+| `workspace.template.md` | Structure du fichier workspace.md (projet, service map, relations, rules, onboarding) |
+| `constitution.template.md` | Structure du fichier constitution.md (regles projet 13+) |
+| `claude-md.template.md` | Structure standardisee pour les CLAUDE.md des repos (stack, archi, regles, tests, anti-patterns) |
+
+---
+
+## Auto-decouverte des repos
+
+L'orchestrateur scanne automatiquement `../` pour trouver les repos freres :
+- Tout dossier avec `.git/` est un repo disponible
+- L'orchestrateur s'exclut lui-meme
+- Les nouveaux repos sont signales au demarrage
+- `/refresh-profiles` relit les CLAUDE.md de tous les repos
+
+---
+
+## Portabilite
+
+Le dossier `orchestrator/` est portable :
+1. Copie-le dans n'importe quel workspace
+2. `cd orchestrator && claude --agent workspace-init`
+3. Si `workspace.md` contient `[UNCONFIGURED]`, le flow de config se relance
+4. Les repos freres sont re-decouverts automatiquement
+
+---
+
+## La constitution
+
+### Globale (scopee au workspace)
+
+12 principes universels dans `~/.claude/rules/constitution-en.md`.
+Scopee aux fichiers orchestrateur (`workspace.md`, `plans/**`, etc.).
+**v4.0** : les teammates ne la recoivent plus automatiquement.
+L'orchestrateur l'inclut dans chaque spawn prompt.
+
+### Projet (a personnaliser)
+
+`constitution.md` dans orchestrator/. Contient **uniquement** les regles
+specifiques au projet (numerotees 13+).
+
+---
+
+## Recovery apres crash
+
+- `claude --resume` reprend la session avec l'agent team-lead
+- Le hook SessionStart injecte automatiquement les plans actifs
+- Le plan markdown sur disque est la source de verite
+
+| Emoji | Statut |
+|-------|--------|
+| ⏳ | TODO |
+| 🔄 | IN PROGRESS |
+| ✅ | DONE |
+| ❌ | BLOCKED/FAILED |
+
+---
+
+## Versioning et mise a jour
+
+Le package utilise le semver. La version installee est trackee dans `~/.claude/.orchestrator-version`.
+
+```bash
+npx claude-orchestrator version    # affiche la version du package et celle installee
+npx claude-orchestrator update     # met a jour si version superieure
+npx claude-orchestrator doctor     # diagnostic complet
+```
+
+A chaque `init` ou `update`, le CLI compare les versions :
+- **Version superieure** → override skills, rules, agents, hooks
+- **Meme version** → skip (sauf `--force`)
+- **Fichiers workspace** (workspace.md, constitution.md, plans/) → jamais ecrases
+
+---
+
+## Contenu du package
+
+```
+claude-orchestrator/
+├── package.json                       <- npm package, version semver
+├── bin/cli.js                         <- CLI (npx claude-orchestrator)
+├── README.md
+├── LICENSE
+│
+└── global-skills/                     <- composants installes dans ~/.claude/
+    ├── constitution.md                <- 12 principes (FR)
+    ├── templates/
+    │   ├── workspace.template.md
+    │   ├── constitution.template.md
+    │   └── claude-md.template.md
+    ├── dispatch-feature/
+    │   ├── SKILL.md
+    │   └── references/
+    │       ├── frontend-ux-standards.md
+    │       ├── spawn-templates.md
+    │       └── anti-patterns.md
+    ├── qa-ruthless/SKILL.md
+    ├── cross-service-check/SKILL.md
+    ├── incident-debug/SKILL.md
+    ├── plan-review/SKILL.md
+    ├── merge-prep/SKILL.md
+    ├── cycle-retrospective/SKILL.md
+    ├── refresh-profiles/SKILL.md
+    ├── bootstrap-repo/SKILL.md
+    ├── hooks/                         <- 11 scripts (warning-only)
+    ├── rules/                         <- 3 rules
+    └── agents/                        <- 3 agents (team-lead, implementer, workspace-init)
+```
+
+---
+
+## Idempotence
+
+Le setup est safe a relancer :
+- Ne reecrit pas `workspace.md` ni `constitution.md` si deja presents
+- Regenere toujours `service-profiles.md` (scan frais)
+- Regenere toujours `settings.json` et `block-orchestrator-writes.sh` (securite)
+- Les templates sont toujours copies
+- Les composants globaux ne sont mis a jour que si la version est superieure
+
+---
+
+## Changelog v3.5.0 -> v4.0
+
+| # | Feature | Detail |
+|---|---------|--------|
+| 1 | **Package NPX** | `npx claude-orchestrator init/update/doctor`. Versioning semver. |
+| 2 | **Orchestrator portable** | Toujours dans un sous-dossier `orchestrator/`. Plus de mode child/sibling. |
+| 3 | **Agent workspace-init** | Diagnostic + config interactive. Remplace la detection [UNCONFIGURED] du team-lead. |
+| 4 | **Template CLAUDE.md** | `claude-md.template.md` — structure standardisee pour les repos. |
+| 5 | **Auto-decouverte repos** | Scanne `../` pour les `.git/`. Pas de liste hardcodee. |
+| 6 | **4 modes de session** | Complet, Plan rapide, Go direct, Single-service. |
+| 7 | **Hooks warning-only** | Plus aucun hook bloquant (exit 2 -> exit 0). |
+| 8 | **verify-cycle-complete supprime** | Plus de blocage a la sortie. |
+| 9 | **Orchestrateur peut ecrire** | Dans orchestrator/ uniquement. Hook path-aware dynamique. |
+| 10 | **Constitution scopee** | `globs: ["*"]` -> fichiers orchestrateur seulement. |
+| 11 | **Limite 30 lignes supprimee** | L'orchestrateur adapte sa verbosite au contexte. |
+| 12 | **Templates structures** | workspace.template.md + constitution.template.md + claude-md.template.md. |
+
+---
+
+<details>
+<summary>Changelog v3.4.2 -> v3.5.0</summary>
+
+| # | Fix/Feature | Detail |
+|---|-------------|--------|
+| 1 | Dual-mode setup | `--mode child\|sibling`. Auto-detection. |
+| 2 | Fix frontmatter `invocation:` | Remplace par `disable-model-invocation`. |
+| 3 | `argument-hint` sur tous les skills | Autocompletion amelioree. |
+| 4 | Hook `SubagentStart` | Injecte plan actif + constitution. |
+| 5 | Hook `SubagentStop` (prompt Haiku) | Evalue completude. |
+| 6 | Hook `PermissionRequest` | Auto-approve Read/Glob/Grep. |
+| 7 | Hook `PostToolUse` async | Tracking fichiers modifies. |
+| 8 | `hookSpecificOutput` JSON | Migration du pattern. |
+| 9 | `$CLAUDE_PROJECT_DIR` | Remplace `jq .cwd`. |
+| 10 | `CLAUDE_ENV_FILE` dans SessionStart | Export plan actif. |
+| 11 | 14 hooks / 12 events | +4 hooks vs v3.4.2. |
+
+</details>