cc-workspace 4.0.0

package/global-skills/cycle-retrospective/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: cycle-retrospective
+description: >
+  Post-cycle learning and knowledge capture. Analyzes QA findings, teammate
+  reports, and implementation patterns to improve repo CLAUDE.md files,
+  service profiles, and project constitution. Run after a successful cycle
+  (dispatch → QA → merge). Use when user says "retro", "rétrospective",
+  "capitalise", "lessons learned", "what did we learn", "améliore les docs".
+argument-hint: "[feature-name]"
+context: fork
+disable-model-invocation: true
+model: haiku
+allowed-tools: Read, Write, Glob, Grep, Task
+---
+
+# Cycle Retrospective — Continuous Learning
+
+After a complete cycle (dispatch → QA → merge), capture lessons learned
+and propagate improvements to project documentation.
+
+## Phase 1: Gather data
+
+1. Read `./workspace.md` for the service map
+2. Find the most recent completed plan in `./plans/` (status ✅ or all tasks ✅)
+3. Read the plan including:
+   - QA report section (findings, patterns)
+   - Cross-service check results
+   - Session log (blockers, escalations, re-dispatches)
+
+## Phase 2: Analyze patterns
+
+Spawn parallel Explore subagents (Task, Haiku) to categorize findings:
+
+### Recurring QA findings
+- Group QA findings by category (🔴 bugs, 🟡 smells, 🟠 dead code, 🔵 missing tests, 🟣 UX violations)
+- Identify patterns: same type of issue across multiple cycles?
+- Flag findings that could have been prevented by a rule or convention
+
+### Teammate friction
+- Parse session log for escalations — what decisions weren't covered by the plan?
+- Parse for re-dispatches — what went wrong on first attempt?
+- Parse for idle time — were tasks too large or poorly scoped?
+
+### Cross-service gaps
+- Were there contract mismatches? Missing env vars? Schema drift?
+- Could these have been caught earlier by a convention?
+
+## Phase 3: Generate improvements
+
+For each finding category, generate concrete improvement suggestions:
+
+### CLAUDE.md updates (per repo)
+For each impacted repo, suggest additions to its CLAUDE.md:
+- New conventions discovered during implementation
+- Common pitfalls to document
+- Test patterns that should be standard
+- Architecture decisions made during this cycle
+
+Format:
+```markdown
+### Suggested additions for [repo]/CLAUDE.md
+
+#### Conventions (new)
+- [convention discovered]
+
+#### Pitfalls (new)
+- [pitfall encountered]
+
+#### Patterns (new)
+- [pattern to follow]
+```
+
+### Constitution updates
+If a finding reveals a gap in the project constitution:
+```markdown
+### Suggested constitution rule
+**[Rule number]. [Rule name].** [Description based on what went wrong]
+Triggered by: [QA finding or escalation that revealed the gap]
+```
+
+### Service profiles updates
+If repo conventions changed, note what needs updating in service-profiles.md.
+
+## Phase 4: Write retrospective
+
+Create `./plans/retro-{date}.md`:
+
+```markdown
+# Retrospective — [Feature name] — [DATE]
+
+## Cycle summary
+- **Feature**: [name]
+- **Services**: [list]
+- **QA findings**: 🔴[n] 🟡[n] 🟠[n] 🔵[n] 🟣[n]
+- **Escalations**: [n]
+- **Re-dispatches**: [n]
+
+## Recurring patterns
+| Pattern | Occurrences | Category | Preventable? |
+|---------|------------|----------|-------------|
+| [pattern] | [n] | [category] | [yes/no + how] |
+
+## Suggested improvements
+
+### CLAUDE.md updates
+[per-repo suggestions]
+
+### Constitution updates
+[if any]
+
+### Process improvements
+[if any — e.g., "add X to plan template", "add Y to QA checklist"]
+
+## Actions
+- [ ] Update [repo]/CLAUDE.md with [changes]
+- [ ] Update constitution with rule [N]
+- [ ] Update service-profiles.md
+- [ ] Update plan template with [addition]
+```
+
+## Phase 5: Present and confirm
+
+Present the retrospective to the user. Ask:
+"Rétrospective terminée. [N] améliorations suggérées. Appliquer les changements aux CLAUDE.md ?"
+
+If user confirms, spawn teammates to apply the CLAUDE.md updates to each repo.
+Do NOT auto-apply constitution changes — those require human review.
+
+## Anti-patterns
+- NEVER fabricate findings — only report what's in the actual plan and QA data
+- NEVER modify repo code — only documentation files (CLAUDE.md, service-profiles)
+- NEVER auto-apply constitution changes without user approval
+- Keep suggestions actionable and specific — "improve error handling" is too vague

package/global-skills/dispatch-feature/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: dispatch-feature
+description: >
+  Orchestrate multi-service feature implementation. Clarifies ambiguities
+  before planning, writes a persistent markdown plan, spawns teammates
+  in dependency waves with full context including constitution and UX standards.
+  Use whenever the user describes a feature, says "implémente", "nouvelle feature",
+  "dispatch", "lance le dev", "lance les teammates", or provides a spec.
+argument-hint: "[feature description]"
+context: fork
+allowed-tools: Read, Write, Glob, Grep, Task, Teammate, SendMessage
+---
+
+# Dispatch Feature — Clarify, Plan, Delegate, Track
+
+You produce ZERO code in repos. You clarify, plan, delegate, track.
+You CAN write in orchestrator/ (plans, workspace.md, constitution.md).
+
+## Mode detection
+
+Before any phase, check which mode was selected:
+
+| Mode | Behavior |
+|------|----------|
+| **A — Complet** | Run all phases 0-5 (default) |
+| **B — Plan rapide** | Skip Phase 0 (Clarify). Start at Phase 2 with specs as-is. |
+| **C — Go direct** | Skip Phases 0-2. Dispatch immediately from user specs. |
+| **D — Single-service** | Phases 0-2, then spawn ONE teammate. No waves. |
+
+If no mode specified, use Mode A.
+
+## Phase 0: Clarify
+
+Run through this checklist SILENTLY. Only ask for items you cannot deduce:
+
+**Must-know** (block if missing):
+- **Who** — which user type uses this feature?
+- **What** — exact expected behavior (input → output)?
+- **Where** — which services are impacted?
+- **Data** — which entities/fields?
+
+**Should-know** (ask if ambiguous):
+- Error handling? Permissions? Trigger mechanism? Dependencies?
+
+**Rules**: max 5 questions at once, formulated as concrete choices.
+Skip clarify if: bug with log provided, or user says "go"/"autonome".
+
+## Phase 1: Load context
+
+1. Read `./workspace.md`
+2. Read `./plans/service-profiles.md`
+3. Read `./constitution.md` (project-specific rules)
+4. Auto-discover repos: scan `../` for directories with `.git/` not in workspace.md
+   → If new repos found: mention them, ask if relevant to this feature
+
+> **v4.0 change**: The `constitution-en` rule is now scoped to orchestrator/ only.
+> Teammates do NOT receive it automatically. You MUST include the full 12 universal
+> principles + project-specific rules in every spawn prompt.
+
+## Phase 2: Write the plan
+
+Create `./plans/{feature-name}.md` using `./plans/_TEMPLATE.md`.
+Include: context, clarification answers, services impacted, dependency waves,
+detailed tasks per service, API contract (exact shapes), and autonomous choices if applicable.
+
+### Dependency waves
+
+- **Wave 1**: Producers — API backend, data/analytics, auth (define contracts)
+- **Wave 2**: Consumers — Frontend, integrations (depend on wave 1 contracts)
+- **Wave 3**: Infra/config — Gateway routes, deployment (after code exists)
+
+Independent services go in the same wave. Save. **Present plan, wait for approval.**
+
+## Phase 3: Spawn teammates (Agent Teams)
+
+Use the **Teammate** tool to spawn teammates. Each teammate is an independent
+Agent Teams session with its own context window.
+
+### Teammate spawn template
+
+For EVERY teammate, include in the spawn prompt:
+1. Project-specific rules from `workspace constitution.md` (translated to English)
+2. Their tasks from the plan
+3. API contract (if applicable)
+4. Instruction to read repo CLAUDE.md first
+5. Instruction to escalate architectural decisions not in the plan
+
+See @references/spawn-templates.md for the full templates per service type
+(backend, frontend, infra, explore).
+
+> **Constitution in spawn prompts**: The 12 universal principles are NO LONGER
+> auto-injected into teammate sessions (v4.0 — rule scoped to orchestrator/).
+> You MUST include ALL 12 principles + project-specific rules in every spawn prompt.
+> See @references/spawn-templates.md for templates with the full constitution.
+
+### Frontend teammates — extra context
+
+Before their tasks, inject:
+- The UX standards (content of `references/frontend-ux-standards.md`)
+- The exact API contract shapes for TypeScript interfaces
+
+### API teammates — extra context
+
+Inject:
+- The API contract they must implement (exact shapes)
+- Note that frontend will build types from these shapes
+
+### Isolation
+
+**Agent Teams teammates** (Teammate tool) get automatic worktree isolation —
+no manual setup needed. Each teammate runs in its own git worktree.
+
+**Task subagents** (Task tool, used for lightweight Explore/Haiku scans) do NOT
+get automatic isolation. This is fine because Explore subagents are read-only.
+If a Task subagent needs to write code, add `isolation: worktree` to its config.
+
+Never mix: one teammate per repo per wave. No two teammates editing the same repo.
+
+### Wave execution
+
+1. Spawn all wave 1 teammates in parallel
+2. Wait for ALL wave 1 to report back
+3. Collect wave 1 results, update the API contract if needed
+4. Spawn wave 2 teammates with validated contracts from wave 1
+5. Repeat for wave 3 if applicable
+6. Use **SendMessage** to clarify or redirect teammates mid-wave if needed
+
+## Phase 4: Collect and update
+
+On each teammate report:
+1. Update `./plans/{feature-name}.md` — statuses ✅ or ❌
+2. Note dead code found
+3. If a teammate failed → analyze, correct plan, re-dispatch
+4. **Session log** entry: `[HH:MM] teammate-[service]: [status], [N] files, tests [pass/fail]`
+5. If current wave done → launch next wave
+
+## Phase 5: Post-implementation
+
+1. Run `cross-service-check`
+2. Run `qa-ruthless`
+3. Update plan with all results
+4. Present final status to user
+
+## Mode D: Single-service
+
+For targeted fixes or single-repo work:
+1. Identify the ONE service to touch
+2. Skip waves — spawn a single teammate
+3. No cross-service-check (unless user requests it)
+4. QA scoped to that service only
+5. Merge prep for that service only
+
+> **Context note**: This skill runs with `context: fork`. After it completes,
+> its internal context is discarded. The plan file on disk is the source of truth.
+> QA and cross-service-check will reload the plan from disk.
+
+## Session recovery
+
+If resuming after crash:
+1. Read `./workspace.md` for project context
+2. List `./plans/` for active plans
+3. Read active plan — statuses and session log tell you where you are
+4. Resume at last incomplete step
+5. If no mode was selected before crash, default to Mode A
+
+## Anti-patterns
+
+See @references/anti-patterns.md for the full list of anti-patterns and common mistakes.

package/global-skills/dispatch-feature/references/anti-patterns.md

@@ -0,0 +1,31 @@
+# Dispatch Anti-Patterns
+
+Reference file for dispatch-feature. Loaded on-demand when Claude needs reminders.
+
+## NEVER do these
+
+1. **NEVER write code in repos** — not even examples. You CAN write in orchestrator/
+   (plans, workspace.md, constitution.md). For repo code: delegate without exception.
+2. **NEVER skip clarify on ambiguous requests** — if in doubt, ask
+3. **NEVER spawn one teammate for multiple repos** — one teammate = one repo = one wave
+4. **NEVER skip the plan file** — everything is tracked on disk
+5. **NEVER dispatch without approval** unless user explicitly said "autonome" or "go"
+6. **NEVER forget UX standards in frontend teammate prompts** — they're in references/frontend-ux-standards.md
+7. **NEVER launch wave 2 before wave 1 reports back** — contracts must be validated first
+8. **NEVER let a teammate guess on architectural decisions** — they must escalate to you
+9. **ALWAYS include the full constitution in spawn prompts** — the 12 universal principles
+   + project-specific rules. Since v4.0, the constitution rule is scoped to orchestrator/
+   only. Teammates do NOT receive it automatically.
+10. **NEVER keep code details in your context** — summarize to 3 lines in the plan, then compact
+11. **NEVER assume repos are listed in workspace.md** — scan `../` at feature start for
+    any new `.git` repos that may have appeared since last configuration
+
+## Common mistakes to watch for
+
+| Mistake | Detection | Correction |
+|---------|-----------|-----------|
+| Teammate implements without reading CLAUDE.md | Report doesn't mention repo conventions | Re-dispatch with explicit instruction |
+| Frontend teammate skips empty/error states | QA UX audit finds 🟣 violations | Re-dispatch with UX standards reminder |
+| Plan has vague tasks like "implement feature" | Each task should have a clear input→output | Rewrite plan with specific tasks |
+| API contract has `{}` placeholder | Frontend can't build types | Complete the contract shapes before wave 2 |
+| Two teammates on same repo in same wave | Git conflicts guaranteed | Split into separate waves |

package/global-skills/dispatch-feature/references/frontend-ux-standards.md

@@ -0,0 +1,73 @@
+# Frontend UX Standards
+
+Ce document est injecté dans le prompt de chaque teammate frontend.
+Il définit le niveau de qualité UX minimum attendu.
+
+## Les 4 états obligatoires
+
+Chaque composant qui affiche des données DOIT implémenter :
+
+### Loading state
+- Skeleton loader qui reproduit la forme du contenu attendu
+- Pas de spinner générique plein écran — le skeleton donne un aperçu de la structure
+- Le skeleton est animé (pulse) pour indiquer l'activité
+- Durée max avant timeout : configurable, défaut 10s → bascule sur error state
+
+### Empty state
+- Illustration ou icône contextuelle (pas un message texte seul)
+- Message clair qui explique pourquoi c'est vide
+- Call-to-action pour créer le premier élément ou modifier les filtres
+- Exemple : "Aucun budget défini. Créez votre premier budget pour commencer le suivi."
+
+### Error state
+- Message d'erreur compréhensible par l'utilisateur (pas le message technique)
+- Bouton "Réessayer" qui retente l'action
+- Si l'erreur persiste, afficher un message secondaire avec un lien support
+- Les erreurs réseau et les erreurs serveur ont des messages différents
+
+### Success state
+- Le contenu s'affiche avec une transition fluide depuis le skeleton
+- Si c'est une action (création, modification), feedback toast/notification
+- L'état succès est le seul qui ne nécessite pas d'élément UI supplémentaire
+
+## Responsive
+
+- **Mobile first** : construire la version mobile en premier
+- Breakpoints Quasar : `$breakpoint-xs` (0-599), `$breakpoint-sm` (600-1023),
+  `$breakpoint-md` (1024-1439), `$breakpoint-lg` (1440+)
+- Les tableaux de données sur mobile : basculer en vue carte/liste, pas de scroll horizontal
+- Les formulaires sur mobile : champs empilés, clavier natif approprié (inputmode)
+- Les actions principales : accessibles avec le pouce (zone basse de l'écran)
+
+## Interactions
+
+- **Debounce** sur les inputs de recherche/filtre : 300ms
+- **Optimistic updates** pour les actions rapides (toggle, suppression)
+  avec rollback en cas d'erreur API
+- **Confirmation** pour les actions destructives (suppression, reset)
+  via dialog Quasar, pas window.confirm()
+- **Transitions** entre les états : fade 150ms par défaut
+- **Disabled state** clair sur les boutons pendant le traitement (pas de double submit)
+
+## Accessibilité (minimum)
+
+- Tous les éléments interactifs ont un `aria-label` descriptif
+- Navigation au clavier fonctionnelle (tab order logique, focus visible)
+- Contraste minimum WCAG AA (4.5:1 texte, 3:1 grands textes)
+- Les icônes sans texte ont un `aria-label` ou un tooltip
+- Les formulaires ont des labels associés (pas de placeholder comme seul label)
+
+## Formulaires
+
+- Validation inline au blur (pas seulement au submit)
+- Messages d'erreur sous le champ concerné, en rouge, avec icône
+- Bouton submit disabled tant que le formulaire est invalide
+- Auto-focus sur le premier champ à l'ouverture
+- Préserver les données saisies en cas d'erreur serveur
+
+## Design system
+
+- Utiliser les composants Quasar natifs en priorité (QTable, QForm, QDialog...)
+- Ne pas réinventer un composant qui existe dans Quasar
+- Les couleurs, spacing, et typographie suivent le thème Quasar du projet
+- Les icônes viennent d'un set unique (Material Icons ou celui configuré)

package/global-skills/dispatch-feature/references/spawn-templates.md

@@ -0,0 +1,109 @@
+# Teammate Spawn Templates
+
+Reference file for dispatch-feature. Loaded on-demand, not at skill activation.
+
+> **v4.0**: The constitution rule is scoped to orchestrator/ only. Teammates do NOT
+> receive the 12 universal principles automatically. Every spawn template below includes
+> a "Universal principles" section that you MUST fill with the full 12 principles from
+> `~/.claude/rules/constitution-en.md` (or the FR version from constitution.md).
+
+## Backend/API teammate spawn template
+
+```
+You are teammate-[service]. Read the CLAUDE.md in your repo first.
+
+## Universal principles (non-negotiable)
+[paste all 12 universal principles from the constitution — they are NOT auto-injected
+into teammates since v4.0. Copy them from ~/.claude/rules/constitution-en.md]
+
+## Project rules (non-negotiable)
+[paste project-specific rules from workspace constitution.md, translated to English]
+
+## API contract
+[paste the exact request/response shapes this service must implement]
+[note: frontend will build TypeScript interfaces from these shapes]
+
+## Your tasks
+[paste tasks from plan for this service]
+
+## Instructions
+1. Read the repo CLAUDE.md first — follow its conventions
+2. Implement the tasks above following the full constitution (12 principles above + project rules)
+3. Use the LSP tool for code navigation (go-to-definition, find-references)
+4. Run the existing test suite — report pass/fail
+5. List any dead code created or exposed by your changes
+6. Commit on branch feature/[name] with conventional commits
+7. If you hit an architectural decision NOT covered by the plan: STOP and
+   report the dilemma instead of guessing
+8. Report back: files created/modified, tests pass/fail, dead code found, blockers
+```
+
+## Frontend teammate spawn template
+
+```
+You are teammate-[service]. Read the CLAUDE.md in your repo first.
+
+## Universal principles (non-negotiable)
+[paste all 12 universal principles from the constitution — they are NOT auto-injected
+into teammates since v4.0. Copy them from ~/.claude/rules/constitution-en.md]
+
+## Project rules (non-negotiable)
+[paste project-specific rules from workspace constitution.md, translated to English]
+
+## UX Standards (non-negotiable)
+[paste full content of frontend-ux-standards.md]
+
+## API contract (TypeScript interfaces)
+[paste exact response shapes from wave 1 — teammate builds TS interfaces from these]
+
+## Your tasks
+[paste tasks from plan for this service]
+
+## Instructions
+1. Read the repo CLAUDE.md first — follow its conventions
+2. Implement the tasks following the full constitution (12 principles + project rules) and UX standards
+3. Use the LSP tool for code navigation
+4. Every new component MUST handle 4 states: skeleton loader, empty+CTA, error+retry, success
+5. Run the existing test suite — report pass/fail
+6. List any dead code (unused components, composables, store actions, CSS)
+7. Commit on branch feature/[name] with conventional commits
+8. If you hit an architectural decision NOT covered by the plan: STOP and escalate
+9. Report back: files created/modified, tests pass/fail, dead code found, UX compliance, blockers
+```
+
+## Infra/Config teammate spawn template
+
+```
+You are teammate-[service]. Read the CLAUDE.md in your repo first.
+
+## Universal principles (non-negotiable)
+[paste all 12 universal principles from the constitution — they are NOT auto-injected
+into teammates since v4.0. Copy them from ~/.claude/rules/constitution-en.md]
+
+## Project rules (non-negotiable)
+[paste project-specific rules from workspace constitution.md, translated to English]
+
+## Your tasks
+[paste tasks — typically: gateway routes, deployment configs, env vars]
+
+## Instructions
+1. Read the repo CLAUDE.md first
+2. Implement the configuration changes following the full constitution
+3. Verify consistency with other services (env vars, routes, schemas)
+4. No code changes — only configuration
+5. Commit on branch feature/[name]
+6. If you hit an architectural decision NOT covered by the plan: STOP and escalate
+7. Report back: files modified, consistency check results, blockers
+```
+
+## Explore/Haiku subagent template (read-only)
+
+```
+You are an explorer scanning [target]. Read-only — do NOT modify any files.
+
+## Task
+[specific read-only investigation task]
+
+## Report format
+[what to extract and how to format the findings]
+```

package/global-skills/hooks/notify-user.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+# notify-user.sh
+# Notification hook: sends desktop notification when Claude needs attention.
+# Works on macOS (osascript), Linux (notify-send), and falls back to terminal bell.
+set -euo pipefail
+
+INPUT=$(cat)
+
+MESSAGE=$(echo "$INPUT" | jq -r '.message // "Claude Code needs your attention"' 2>/dev/null) || MESSAGE="Claude Code needs your attention"
+TITLE="Claude Code Orchestrator"
+
+# Sanitize message for safe shell interpolation (strip quotes, backslashes, special chars)
+SAFE_MESSAGE=$(printf '%s' "$MESSAGE" | tr -d '"\\\n' | head -c 200)
+SAFE_TITLE=$(printf '%s' "$TITLE" | tr -d '"\\\n')
+
+# Try macOS notification — use positional args to avoid injection
+if command -v osascript &>/dev/null; then
+    osascript -e 'on run argv' \
+              -e 'display notification (item 1 of argv) with title (item 2 of argv)' \
+              -e 'end run' \
+              -- "$SAFE_MESSAGE" "$SAFE_TITLE" 2>/dev/null || true
+# Try Linux notification
+elif command -v notify-send &>/dev/null; then
+    notify-send -- "$SAFE_TITLE" "$SAFE_MESSAGE" 2>/dev/null || true
+fi
+
+# Always ring terminal bell as fallback
+printf '\a' 2>/dev/null || true
+
+exit 0

package/global-skills/hooks/permission-auto-approve.sh

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+# permission-auto-approve.sh
+# PermissionRequest hook: auto-approves Read/Glob/Grep to reduce friction.
+# Uses hookSpecificOutput JSON with decision.behavior: "allow".
+set -euo pipefail
+
+INPUT=$(cat)
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null) || true
+
+if echo "$TOOL_NAME" | grep -qE '^(Read|Glob|Grep)$'; then
+    cat << 'EOF'
+{"hookSpecificOutput":{"hookEventName":"PermissionRequest","decision":{"behavior":"allow","toolNames":["Read","Glob","Grep"]}}}
+EOF
+fi
+
+exit 0

package/global-skills/hooks/session-start-context.sh

@@ -0,0 +1,85 @@
+#!/usr/bin/env bash
+# session-start-context.sh
+# SessionStart hook: injects active plan context and repo status.
+# Stdout on exit 0 is added as context visible to Claude.
+set -euo pipefail
+
+cat > /dev/null
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+OUTPUT=""
+
+# Find active plans (plans with pending ⏳ or in-progress 🔄 tasks)
+if [ -d "$PROJECT_DIR/plans" ]; then
+    ACTIVE_PLANS=$(find "$PROJECT_DIR/plans" -name '*.md' \
+        ! -name '_TEMPLATE.md' \
+        ! -name 'service-profiles.md' \
+        -exec grep -l '⏳\|🔄' {} \; 2>/dev/null \
+        | sort | tail -5)
+
+    if [ -n "$ACTIVE_PLANS" ]; then
+        FIRST_PLAN=""
+        OUTPUT+="[Session context] Active plans with pending tasks:\n"
+        while IFS= read -r plan; do
+            PLAN_NAME=$(basename "$plan")
+            [ -z "$FIRST_PLAN" ] && FIRST_PLAN="$PLAN_NAME"
+            TODO=$(grep -c '⏳' "$plan" 2>/dev/null || echo "0")
+            WIP=$(grep -c '🔄' "$plan" 2>/dev/null || echo "0")
+            DONE=$(grep -c '✅' "$plan" 2>/dev/null || echo "0")
+            OUTPUT+="  - $PLAN_NAME (⏳ $TODO pending, 🔄 $WIP in progress, ✅ $DONE done)\n"
+        done <<< "$ACTIVE_PLANS"
+        OUTPUT+="\nRead these plans to resume where you left off.\n"
+
+        # Export active plan name to Claude's environment if supported
+        if [ -n "${CLAUDE_ENV_FILE:-}" ] && [ -n "$FIRST_PLAN" ]; then
+            echo "ACTIVE_PLAN=$FIRST_PLAN" >> "$CLAUDE_ENV_FILE"
+        fi
+    fi
+fi
+
+# Check workspace.md exists
+if [ ! -f "$PROJECT_DIR/workspace.md" ]; then
+    OUTPUT+="[WARNING] No workspace.md found. Run setup-workspace.sh first.\n"
+fi
+
+# First-session detection
+if [ -f "$PROJECT_DIR/workspace.md" ]; then
+    if grep -q '\[UNCONFIGURED\]' "$PROJECT_DIR/workspace.md" 2>/dev/null; then
+        OUTPUT+="[FIRST SESSION] workspace.md is not yet configured. Run: claude --agent workspace-init\n"
+        OUTPUT+="Sibling repos detected:\n"
+        PARENT_DIR="$(cd "$PROJECT_DIR/.." 2>/dev/null && pwd)"
+        if [ -n "$PARENT_DIR" ] && [ -d "$PARENT_DIR" ]; then
+            for dir in "$PARENT_DIR"/*/; do
+                [ -d "$dir" ] || continue
+                dir_name=$(basename "$dir")
+                [ "$dir_name" = "$(basename "$PROJECT_DIR")" ] && continue
+                [ -d "$dir/.git" ] && OUTPUT+="  - $dir_name\n"
+            done
+        fi
+        OUTPUT+="\n"
+    fi
+fi
+
+# Auto-discovery: detect new repos not in workspace.md
+if [ -f "$PROJECT_DIR/workspace.md" ] && ! grep -q '\[UNCONFIGURED\]' "$PROJECT_DIR/workspace.md" 2>/dev/null; then
+    PARENT_DIR="$(cd "$PROJECT_DIR/.." 2>/dev/null && pwd)"
+    NEW_REPOS=""
+    if [ -n "$PARENT_DIR" ] && [ -d "$PARENT_DIR" ]; then
+        for dir in "$PARENT_DIR"/*/; do
+            [ -d "$dir" ] || continue
+            dir_name=$(basename "$dir")
+            [ "$dir_name" = "$(basename "$PROJECT_DIR")" ] && continue
+            if [ -d "$dir/.git" ] && ! grep -q "$dir_name" "$PROJECT_DIR/workspace.md" 2>/dev/null; then
+                NEW_REPOS+="  - $dir_name\n"
+            fi
+        done
+    fi
+    if [ -n "$NEW_REPOS" ]; then
+        OUTPUT+="[Auto-discovery] New repos detected (not in workspace.md):\n$NEW_REPOS\n"
+    fi
+fi
+
+if [ -n "$OUTPUT" ]; then
+    echo -e "$OUTPUT"
+fi
+
+exit 0

package/global-skills/hooks/subagent-start-context.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# subagent-start-context.sh
+# SubagentStart hook: injects active plan + constitution reference into each subagent.
+# Stdout is added as additionalContext for the subagent.
+set -euo pipefail
+
+cat > /dev/null
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+OUTPUT=""
+
+# Inject active plan context
+if [ -d "$PROJECT_DIR/plans" ]; then
+    ACTIVE_PLAN=$(find "$PROJECT_DIR/plans" -name '*.md' \
+        ! -name '_TEMPLATE.md' \
+        ! -name 'service-profiles.md' \
+        ! -name 'retro-*.md' \
+        -exec grep -l '⏳\|🔄' {} \; 2>/dev/null \
+        | sort | head -1)
+
+    if [ -n "$ACTIVE_PLAN" ]; then
+        PLAN_NAME=$(basename "$ACTIVE_PLAN")
+        OUTPUT+="[Subagent context] Active plan: $PLAN_NAME\n"
+        OUTPUT+="Read $ACTIVE_PLAN for your assigned tasks.\n"
+    fi
+fi
+
+# Remind about constitution
+if [ -f "$PROJECT_DIR/constitution.md" ]; then
+    OUTPUT+="[Project constitution] Non-negotiable rules in $PROJECT_DIR/constitution.md — read and follow.\n"
+fi
+
+OUTPUT+="[Reminder] Report back: files changed, tests pass/fail, dead code found, blockers.\n"
+
+echo -e "$OUTPUT"
+exit 0