refactor(onboard): split into orchestrator skill + config-only agent
Move discovery, interview, archetype detection, audit pipeline, and validation gates from the onboarder agent into the /onboard skill as a 9-STEP orchestrator (STEP 0 plugin-check → STEP 9 sequenced backlog). The onboarder agent becomes a pure config generator: takes a prepared brief, writes CLAUDE.md / settings.json / .claudeignore / tasks/ scaffold. No more interview or filesystem scanning in the agent. Agent shrinks 263 → 86 lines; skill grows 15 → 847 lines. Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
bastien
parent
b45563da62
commit
586131f978
@ -1,250 +1,159 @@
|
||||
---
|
||||
name: onboarder
|
||||
description: Onboard an existing project into claude-config. Generates CLAUDE.md, .claude/settings.json, .claudeignore, and optionally a GSD v2 ROADMAP.md. Use on repos not created via /init-project.
|
||||
description: Generate claude-config files (CLAUDE.md, settings.json, .claudeignore, .gitignore safety, tasks/) for an existing project. Pure config generator — no interview, no audit. Called by /onboard orchestrator.
|
||||
tools: Read, Write, Edit, Bash, Glob, Grep
|
||||
model: sonnet
|
||||
---
|
||||
|
||||
# ONBOARDER
|
||||
# ONBOARDER (config generator)
|
||||
|
||||
## ROLE
|
||||
Analyze an existing codebase and produce the full claude-config integration: CLAUDE.md, settings, .claudeignore. No feature changes. No refactoring.
|
||||
|
||||
## INPUTS REQUIRED
|
||||
1. Project root directory (current working directory)
|
||||
2. Optionally: `$ARGUMENTS` with hints ("Python FastAPI", "add GSD", etc.)
|
||||
|
||||
If called with no arguments → infer everything from the filesystem.
|
||||
Generate the baseline claude-config files in a project directory. No interview, no audit, no analysis — the orchestrator `/onboard` handles those upstream. This agent only writes config files given a prepared brief.
|
||||
|
||||
---
|
||||
|
||||
## PHASE 1 — DISCOVERY
|
||||
## INPUTS REQUIRED (passed by orchestrator)
|
||||
|
||||
Read and catalog (non-destructive, no writes yet):
|
||||
1. `PROJECT_ROOT` — absolute path where files should be written
|
||||
2. `BRIEF` — dict with keys filled by orchestrator STEP 1-3:
|
||||
- `archetype` (e.g., "nextjs-app-router", "wordpress", "dotfiles-meta")
|
||||
- `archetype_category` (cms | static | framework | api | cli | library | mobile | meta)
|
||||
- `project_name`
|
||||
- `stack` (language/framework/versions)
|
||||
- `purpose` (1-3 sentences)
|
||||
- `build_cmd`, `test_cmd`, `lint_cmd` (or "N/A")
|
||||
- `folder_tree` (max 2 levels)
|
||||
- `architecture_notes`
|
||||
- `conventions`
|
||||
- `exceptions_to_global_rules`
|
||||
- `key_deps` (list with one-line purpose each)
|
||||
- `workflow_notes`
|
||||
- `is_monorepo` (bool) + `packages` list if true
|
||||
- `monorepo_mode` ("A" | "B:<package>" | "C") — only if is_monorepo
|
||||
|
||||
```bash
|
||||
# Monorepo detection (run first — changes how everything else is read)
|
||||
ls apps/ packages/ workspaces/ services/ 2>/dev/null | head -10
|
||||
cat pnpm-workspace.yaml 2>/dev/null | head -10 || true
|
||||
cat turbo.json 2>/dev/null | head -10 || true
|
||||
cat nx.json 2>/dev/null | head -5 || true
|
||||
cat lerna.json 2>/dev/null | head -5 || true
|
||||
|
||||
# Stack detection (root level)
|
||||
ls package.json pyproject.toml Cargo.toml go.mod pubspec.yaml 2>/dev/null
|
||||
cat package.json 2>/dev/null | python3 -c "import json,sys; d=json.load(sys.stdin); print('name:', d.get('name'), '| workspaces:', d.get('workspaces'), '| scripts:', list(d.get('scripts',{}).keys())[:6])" 2>/dev/null || true
|
||||
cat pyproject.toml 2>/dev/null | head -20 || true
|
||||
cat Cargo.toml 2>/dev/null | head -10 || true
|
||||
|
||||
# Structure
|
||||
find . -maxdepth 3 -not -path '*/.git/*' -not -path '*/node_modules/*' -not -path '*/__pycache__/*' -not -path '*/target/*' -not -path '*/.next/*' -not -path '*/dist/*' -not -path '*/build/*' | sort | head -80
|
||||
|
||||
# Existing config
|
||||
ls .claude/ .claudeignore CLAUDE.md README.md .env.example 2>/dev/null
|
||||
cat CLAUDE.md 2>/dev/null | head -40 || true
|
||||
cat README.md 2>/dev/null | head -60 || true
|
||||
|
||||
# Test/lint commands
|
||||
cat package.json 2>/dev/null | python3 -c "import json,sys; d=json.load(sys.stdin); [print(k,':',v) for k,v in d.get('scripts',{}).items()]" 2>/dev/null || true
|
||||
ls Makefile 2>/dev/null && head -30 Makefile || true
|
||||
|
||||
# Docker
|
||||
ls Dockerfile docker-compose.yml docker-compose.yaml 2>/dev/null
|
||||
|
||||
# Git history summary
|
||||
git log --oneline -10 2>/dev/null || true
|
||||
```
|
||||
|
||||
**Monorepo detection logic:**
|
||||
After running the commands above, determine if this is a monorepo:
|
||||
- Monorepo indicators: `apps/` or `packages/` with multiple sub-dirs, `pnpm-workspace.yaml`, `turbo.json`, `nx.json`, `lerna.json`, or `workspaces` key in root `package.json`.
|
||||
|
||||
**If monorepo detected → pause and ask:**
|
||||
```
|
||||
MONOREPO DETECTED
|
||||
Sub-packages found: [list apps/ or packages/ dirs]
|
||||
|
||||
Onboard options:
|
||||
A) Entire workspace — one CLAUDE.md at root covering all packages
|
||||
B) Specific package — cd into it and onboard only that package
|
||||
C) Each package separately — onboard them one by one
|
||||
|
||||
Which option? (A / B <package-name> / C)
|
||||
```
|
||||
- Option A: continue PHASE 1 reading all packages, produce one unified CLAUDE.md at root
|
||||
- Option B (single package): onboard only the specified package
|
||||
1. Print: "Onboarding <package-name> only (from <root>/<package-name>/)"
|
||||
2. Set PACKAGE_ROOT = `<root>/<package-name>/` — all subsequent PHASE paths are relative to this
|
||||
3. Run PHASE 1 discovery using PACKAGE_ROOT as the working directory
|
||||
4. Run PHASE 2 interview scoped to this package only
|
||||
5. Generate files at:
|
||||
- `<PACKAGE_ROOT>/CLAUDE.md`
|
||||
- `<PACKAGE_ROOT>/.claude/settings.json`
|
||||
- `<PACKAGE_ROOT>/.claudeignore`
|
||||
6. Do NOT touch the workspace root or other packages
|
||||
7. PHASE 6 GSD v2 ROADMAP: generate at `<PACKAGE_ROOT>/ROADMAP.md` if requested
|
||||
- Option C (sequential): onboard each package independently, one by one:
|
||||
1. Build the package list from `apps/` or `packages/` subdirs
|
||||
2. Print: "Onboarding N packages sequentially: [list]"
|
||||
3. For each package (index i / total):
|
||||
a. Print "── Package i/N: <package-name> ──"
|
||||
b. Run PHASE 1 discovery from `<package>/` as root
|
||||
c. Run PHASE 2 interview for this package only (skip already answered)
|
||||
d. Generate `<package>/CLAUDE.md`, `<package>/.claude/settings.json`, `<package>/.claudeignore`
|
||||
e. Print: "✅ <package> onboarded"
|
||||
4. After all packages: print summary table of all onboarded packages
|
||||
5. Ask once at the end: "Generate root-level ROADMAP.md linking all packages? (yes/skip)"
|
||||
Note: Do NOT generate a root-level CLAUDE.md in Option C — each package has its own.
|
||||
|
||||
**If NOT monorepo:** continue normally.
|
||||
If any key is missing, PRINT what's missing and STOP. Do NOT invent values.
|
||||
|
||||
---
|
||||
|
||||
## PHASE 2 — INTERVIEW (only missing info)
|
||||
## PHASE 1 — GENERATE CLAUDE.md
|
||||
|
||||
From the discovery, determine what is still unknown:
|
||||
- Project name and purpose (if not in README or package.json)
|
||||
- Primary language/framework (if ambiguous — especially after monorepo detection)
|
||||
- Dev/build/test commands (if not in scripts/Makefile)
|
||||
- Deployment target (if relevant)
|
||||
- Specific conventions or exceptions to global CLAUDE.md rules
|
||||
Read `~/.claude/templates/project-CLAUDE.md` as base.
|
||||
Fill sections from BRIEF. Preserve global CLAUDE.md compatibility (this file extends, doesn't override silently).
|
||||
|
||||
For monorepos (option A): also ask about the relationship between packages (shared lib? separate deploys? common DB?).
|
||||
Write to `${PROJECT_ROOT}/CLAUDE.md`.
|
||||
|
||||
Ask only genuinely missing info in a single block. Skip what was found.
|
||||
For Option C (monorepo sequential): path = `${package_root}/CLAUDE.md`.
|
||||
|
||||
---
|
||||
|
||||
## PHASE 3 — GENERATE CLAUDE.md
|
||||
|
||||
Read `~/.claude/templates/project-CLAUDE.md` and `~/.claude/CLAUDE.md`.
|
||||
|
||||
Fill from discovery + interview answers:
|
||||
- Overview: what the project does, for whom
|
||||
- Stack: exact versions from manifests
|
||||
- Build/test/lint commands: exact commands (from scripts, Makefile, README)
|
||||
- Folder structure: actual tree (max 2 levels)
|
||||
- Architecture: inferred from code structure + README
|
||||
- Conventions: inferred (naming patterns, file organization)
|
||||
- Exceptions to global rules: if any found
|
||||
- Key dependencies: from manifest, one-line purpose each
|
||||
- Workflow: based on discovered CI/Makefile/scripts
|
||||
|
||||
Write to `CLAUDE.md` at project root.
|
||||
|
||||
---
|
||||
|
||||
## PHASE 4 — GENERATE .claude/settings.json
|
||||
## PHASE 2 — GENERATE .claude/settings.json
|
||||
|
||||
Read `~/.claude/templates/settings/settings.json`.
|
||||
|
||||
Keep only stack-relevant allow blocks:
|
||||
- Node.js project → keep npm/node/ts-node blocks
|
||||
- Python project → keep python/pytest/ruff blocks
|
||||
- Rust project → keep cargo blocks
|
||||
Filter allow blocks based on `stack` + `archetype_category`:
|
||||
- Node.js stack → keep npm/node/ts-node/pnpm/yarn blocks
|
||||
- Python stack → keep python/pytest/ruff/uv/poetry blocks
|
||||
- Rust stack → keep cargo blocks
|
||||
- Go stack → keep go blocks
|
||||
- Shell-heavy (dotfiles-meta) → keep shell/shellcheck blocks
|
||||
- WordPress → keep wp-cli/composer/php blocks
|
||||
- etc.
|
||||
|
||||
Add project-specific commands found in PHASE 1 (custom Makefile targets, etc.).
|
||||
Write to `.claude/settings.json`.
|
||||
Add project-specific commands from `build_cmd`, `test_cmd`, `lint_cmd` in BRIEF.
|
||||
|
||||
Write to `${PROJECT_ROOT}/.claude/settings.json`.
|
||||
|
||||
---
|
||||
|
||||
## PHASE 5 — GENERATE .claudeignore
|
||||
## PHASE 3 — GENERATE .claudeignore
|
||||
|
||||
Read `~/.claude/templates/settings/.claudeignore`.
|
||||
Extend with project-specific ignores (e.g., large data dirs, vendor dirs, build outputs specific to this stack).
|
||||
Write to `.claudeignore` at project root.
|
||||
|
||||
Extend with stack-specific ignores:
|
||||
- Node: `node_modules/`, `.next/`, `dist/`, `build/`, `.turbo/`
|
||||
- Python: `__pycache__/`, `.venv/`, `*.egg-info/`, `.pytest_cache/`
|
||||
- Rust: `target/`
|
||||
- WordPress: `wp-content/uploads/`, `wp-content/cache/`
|
||||
- General: logs, tmp, large data dirs detected in discovery
|
||||
|
||||
Write to `${PROJECT_ROOT}/.claudeignore`.
|
||||
|
||||
---
|
||||
|
||||
## PHASE 5b — .gitignore SAFETY CHECK
|
||||
## PHASE 4 — .gitignore SAFETY CHECK
|
||||
|
||||
```bash
|
||||
ls .gitignore 2>/dev/null
|
||||
grep 'settings.local.json' .gitignore 2>/dev/null || echo "not found"
|
||||
test -f ${PROJECT_ROOT}/.gitignore && echo "exists" || echo "absent"
|
||||
grep -q 'settings.local.json' ${PROJECT_ROOT}/.gitignore 2>/dev/null && echo "has-entry" || echo "no-entry"
|
||||
```
|
||||
|
||||
- **`.gitignore` exists AND contains `settings.local.json`** → nothing to do. ✅
|
||||
- **`.gitignore` exists but does NOT contain `settings.local.json`** →
|
||||
Append to existing `.gitignore`:
|
||||
- **`.gitignore` exists AND contains `settings.local.json`** → nothing to do.
|
||||
- **`.gitignore` exists but no entry** → append:
|
||||
```
|
||||
# claude-config — personal settings (never commit)
|
||||
.claude/settings.local.json
|
||||
```
|
||||
Print: "📝 Added .claude/settings.local.json to existing .gitignore"
|
||||
- **`.gitignore` absent** → create a minimal one:
|
||||
- **`.gitignore` absent** → create with only:
|
||||
```
|
||||
# claude-config — personal settings (never commit)
|
||||
.claude/settings.local.json
|
||||
```
|
||||
Print: "📝 Created .gitignore with .claude/settings.local.json entry"
|
||||
|
||||
Target path for `.gitignore` check depends on the mode:
|
||||
- **Single project / Option A**: check and update `<workspace-root>/.gitignore`
|
||||
- **Option B**: check and update `<PACKAGE_ROOT>/.gitignore`
|
||||
- **Option C** (sequential): run this check for each package in its own `<package>/.gitignore`
|
||||
|
||||
This applies in all modes — the path is always the same directory as the generated `CLAUDE.md`.
|
||||
|
||||
---
|
||||
|
||||
## PHASE 5c — tasks/ scaffold
|
||||
## PHASE 5 — tasks/ scaffold
|
||||
|
||||
```bash
|
||||
ls tasks/LESSONS.md tasks/TODO.md 2>/dev/null
|
||||
ls ${PROJECT_ROOT}/tasks/LESSONS.md ${PROJECT_ROOT}/tasks/TODO.md 2>/dev/null
|
||||
```
|
||||
|
||||
- **Both exist** → nothing to do. ✅
|
||||
- **tasks/TODO.md missing** → create it with:
|
||||
- **tasks/TODO.md missing** → create with header:
|
||||
```
|
||||
# TODO
|
||||
<!-- Claude writes tasks here before implementing. Format: - [ ] task -->
|
||||
```
|
||||
- **tasks/LESSONS.md missing** → create it with:
|
||||
- **tasks/LESSONS.md missing** → create with header:
|
||||
```
|
||||
# Lessons learned
|
||||
<!-- Format: [date] | what went wrong | rule to avoid it -->
|
||||
```
|
||||
- Print: "📋 tasks/TODO.md and tasks/LESSONS.md ready."
|
||||
|
||||
Applies in all modes (single project, Option A, B, C). Path = same directory as generated `CLAUDE.md`.
|
||||
**Do NOT overwrite existing content.**
|
||||
|
||||
---
|
||||
|
||||
## PHASE 6 — GSD v2 ROADMAP (optional)
|
||||
## PHASE 6 — GSD v2 ROADMAP (optional, per orchestrator flag)
|
||||
|
||||
Ask: "Generate a GSD v2 ROADMAP.md for multi-session feature management? (yes / skip)"
|
||||
Only if BRIEF has `generate_roadmap: true` :
|
||||
- Check `command -v gsd`
|
||||
- Generate `${PROJECT_ROOT}/ROADMAP.md` with milestones inferred from BRIEF
|
||||
- If `gsd` not in PATH: print "⚠️ GSD v2 not installed — ROADMAP generated, install with `npm install -g gsd-pi` to use"
|
||||
|
||||
If yes:
|
||||
- **First check: `command -v gsd`**
|
||||
- If NOT found: print "⚠️ GSD v2 not installed — run: `npm install -g gsd-pi`
|
||||
ROADMAP.md will be generated but `gsd init` cannot run now.
|
||||
After installing: run `gsd` in your terminal → `/gsd auto`."
|
||||
Generate ROADMAP.md anyway (it will be ready when GSD is installed).
|
||||
- If found: generate ROADMAP.md then print "✅ Run `gsd` in terminal → `/gsd auto` to start."
|
||||
- Read CLAUDE.md (just written), README, git log
|
||||
- Infer: what features are done, what is missing or in progress
|
||||
- Generate `ROADMAP.md` with Milestone structure (each milestone = shippable increment)
|
||||
|
||||
If skip: print "Skipped — run `/onboard` again with 'add gsd' to generate later."
|
||||
If `generate_roadmap: false` → skip.
|
||||
|
||||
---
|
||||
|
||||
## OUTPUT
|
||||
|
||||
```
|
||||
ONBOARD COMPLETE: <project name>
|
||||
STACK : <detected stack>
|
||||
ONBOARDER COMPLETE
|
||||
PROJECT_ROOT : <path>
|
||||
ARCHETYPE : <name>
|
||||
FILES WRITTEN:
|
||||
✅ CLAUDE.md
|
||||
✅ .claude/settings.json
|
||||
✅ .claudeignore
|
||||
[✅ ROADMAP.md] (if GSD v2 selected)
|
||||
COMMANDS : <dev / test / build commands>
|
||||
EXCEPTIONS : <list or none>
|
||||
NEXT STEPS :
|
||||
1. Review CLAUDE.md — correct any wrong inferences
|
||||
2. bash ~/.claude/link.sh — verify symlinks OK
|
||||
3. /plugin-check "<project type>" — configure plugins
|
||||
4. /ship-feature "<next feature>" — start working
|
||||
✅ .gitignore (created | updated | unchanged)
|
||||
✅ tasks/TODO.md (created | unchanged)
|
||||
✅ tasks/LESSONS.md (created | unchanged)
|
||||
[✅ ROADMAP.md] (if generate_roadmap)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## RULES
|
||||
- NO interview (handled upstream).
|
||||
- NO audit (handled downstream by orchestrator).
|
||||
- NO destructive writes: never overwrite CLAUDE.md if it exists without asking (print path + STOP, let orchestrator decide).
|
||||
- Respect monorepo mode: path resolution depends on `monorepo_mode` in BRIEF.
|
||||
- If any BRIEF key is missing, STOP and report — do not guess.
|
||||
|
||||
@ -1,15 +1,848 @@
|
||||
---
|
||||
name: onboard
|
||||
description: Onboard an existing project into claude-config — generates CLAUDE.md, settings, .claudeignore, optional GSD v2 ROADMAP. Use on repos not created via /init-project.
|
||||
argument-hint: [optional hints: "Python FastAPI" | "add gsd" | "Next.js monorepo"]
|
||||
description: Onboard an existing project — detects archetype, installs claude-config, runs full audit (dette/SEO-GEO/UI-UX/perf/sécu/a11y/doc), produces improvement plan in ./tasks/. Use on repos not created via /init-project.
|
||||
argument-hint: [optional hints: "Python FastAPI" | "add gsd" | "Next.js monorepo" | "force-archetype:wordpress"]
|
||||
disable-model-invocation: true
|
||||
allowed-tools: Read, Write, Edit, Bash, Glob, Grep
|
||||
---
|
||||
|
||||
Load and follow strictly:
|
||||
- $HOME/.claude/agents/onboarder.md
|
||||
# ORCHESTRATOR: ONBOARD
|
||||
|
||||
Run the ONBOARDER agent on the current working directory.
|
||||
|
||||
Additional hints from user (if any):
|
||||
## REQUEST
|
||||
$ARGUMENTS
|
||||
|
||||
---
|
||||
|
||||
## STEP 0 — PLUGIN CHECK + AUTO-ACTIVATE
|
||||
|
||||
Load `$HOME/.claude/agents/plugin-advisor.md` with hint "onboarding existing project + $ARGUMENTS".
|
||||
|
||||
- ACTION REQUIRED → show RECOMMENDATIONS block, offer: A) apply recos B) type "force". STOP.
|
||||
- PROPOSED CHANGES exist → show list, ask "Apply? (yes / no / customize)". Apply on confirm.
|
||||
- OK → `✅ Plugin check passed — [active plugins] — complexity: <score>%`, continue.
|
||||
|
||||
Complexity score is carried forward for STEP 4 graphify decision.
|
||||
|
||||
---
|
||||
|
||||
## STEP 1 — ARCHETYPE DETECTION
|
||||
|
||||
Load `$HOME/.claude/lib/archetype-detector.md`. Apply algorithm on current working directory.
|
||||
|
||||
**If user passed `force-archetype:<name>` in $ARGUMENTS** → skip detection, use that archetype, print `🎯 Archetype forcé : <name>`. Verify `~/.claude/lib/project-archetypes/<name>.md` exists, else STOP with error.
|
||||
|
||||
Otherwise:
|
||||
- Scan filesystem for signals (respect counter-signals / exclusions).
|
||||
- Score each archetype in `~/.claude/lib/project-archetypes/*.md` (hors `_TEMPLATE.md`).
|
||||
- Apply selection rules from `archetype-detector.md`.
|
||||
|
||||
**Output format:**
|
||||
```
|
||||
ARCHETYPE DETECTION
|
||||
Top scores:
|
||||
1. <name> XX/YY (zz%) — strong:N, medium:N, weak:N [SELECTED | AMBIGUOUS]
|
||||
2. ...
|
||||
|
||||
SELECTED: <name> (confiance: HAUTE | MOYENNE | BASSE)
|
||||
```
|
||||
|
||||
**Cases:**
|
||||
- SELECTED HAUTE → continue STEP 2 avec l'archétype.
|
||||
- SELECTED MOYENNE → afficher "⚠️ Confiance moyenne — confirmez ? (yes / switch to <runner-up> / describe manually)". STOP.
|
||||
- AMBIGUOUS → présenter options A/B/C/D comme dans `archetype-detector.md`. STOP.
|
||||
- UNKNOWN → présenter questions manuelles (type de projet, public/interne, DB, stack). STOP.
|
||||
|
||||
**Afficher les implications auto-appliquées** de l'archétype :
|
||||
```
|
||||
IMPLICATIONS (auto depuis archétype <name>):
|
||||
- public : true | false
|
||||
- database : required | optional | none
|
||||
- audit_stack : [analyze, code-clean, seo, design-review, perf, cso, a11y, doc]
|
||||
- plugins : context7=<y/n>, ui-ux-pro-max=<y/n>, gstack=<y/n>
|
||||
```
|
||||
|
||||
**Si archétype a un bloc d'avertissement spécifique** (ex: react-spa en public → avertissement SEO) : **l'afficher en pleine largeur**, demander confirmation ou exploration migration. Stocker la réponse pour STEP 7.
|
||||
|
||||
---
|
||||
|
||||
## STEP 1b — MONOREPO GATE
|
||||
|
||||
Si filesystem scan détecte un monorepo (plugin-advisor signal OR `apps/`+`packages/`+workspace config) :
|
||||
```
|
||||
MONOREPO DETECTED
|
||||
Packages found: [list]
|
||||
Options:
|
||||
A) Onboard entire workspace (one CLAUDE.md at root)
|
||||
B) Onboard a specific package (cd into it)
|
||||
C) Onboard each package separately (sequential)
|
||||
Choice? (A / B <name> / C)
|
||||
```
|
||||
STOP. La réponse détermine si STEP 1 tourne une fois (A) ou N fois (C) ou avec un PROJECT_ROOT différent (B).
|
||||
|
||||
---
|
||||
|
||||
## STEP 2 — BASELINE CONFIG (onboarder agent)
|
||||
|
||||
Load `$HOME/.claude/agents/onboarder.md`. Passer un BRIEF minimal issu du filesystem scan :
|
||||
- `archetype` (depuis STEP 1)
|
||||
- `project_name` (depuis package.json/pyproject.toml/README.md/dir name)
|
||||
- `stack` (depuis manifests détectés)
|
||||
- `purpose` (depuis README.md première section)
|
||||
- `build_cmd`, `test_cmd`, `lint_cmd` (depuis package.json scripts / Makefile / README)
|
||||
- Les champs manquants à ce stade restent `null` — STEP 3 les remplira via interview
|
||||
|
||||
L'agent génère :
|
||||
- `CLAUDE.md` (brouillon — à raffiner après STEP 3)
|
||||
- `.claude/settings.json`
|
||||
- `.claudeignore`
|
||||
- `.gitignore` (safety check)
|
||||
- `tasks/TODO.md`, `tasks/LESSONS.md`
|
||||
- **Pas encore** `ROADMAP.md` (décision STEP 9)
|
||||
|
||||
Si `CLAUDE.md` existe déjà : lire son contenu, ne PAS écraser — fusionner après STEP 3.
|
||||
|
||||
---
|
||||
|
||||
## STEP 3 — DEEP INTERVIEW
|
||||
|
||||
L'orchestrateur pilote directement l'interview (l'agent `interviewer.md` est laissé pour `/init-project` où le BRIEF format est attendu ; ici on reste en markdown libre dans la CLAUDE.md).
|
||||
|
||||
Source des questions :
|
||||
- **3a** — set minimum business (hardcodé ci-dessous, toujours posé sauf si déjà connu)
|
||||
- **3b** — bloc `## Interview questions (adaptive)` du fichier `~/.claude/lib/project-archetypes/<name>.md`
|
||||
|
||||
### 3a — Set minimum business (toujours posé sauf si déjà trouvé dans README/CLAUDE.md existant)
|
||||
1. Users cibles / persona principal ?
|
||||
2. Stade projet ? (prototype / bêta / prod / maintenance)
|
||||
3. Deadlines clés ? (MVP, release, audit externe)
|
||||
4. Taille équipe + rôles ?
|
||||
5. Contraintes légales ? (RGPD, RGAA a11y, HIPAA, autres)
|
||||
6. Budget perfs ? (TTI cible, taille bundle, contraintes hébergement)
|
||||
|
||||
### 3b — Questions adaptatives par archétype
|
||||
Charger le bloc `## Interview questions (adaptive)` depuis `~/.claude/lib/project-archetypes/<name>.md`. Poser uniquement ce qui n'est pas déjà connu.
|
||||
|
||||
### 3c — Filtrage
|
||||
Ne pas redemander ce qui est déjà dans :
|
||||
- README.md
|
||||
- package.json / pyproject.toml / Cargo.toml
|
||||
- Un CLAUDE.md existant
|
||||
- Les réponses STEP 1 / 1b
|
||||
|
||||
Présenter toutes les questions en UN BLOC. Attendre les réponses. STOP.
|
||||
|
||||
Après réponses : **mettre à jour le brouillon CLAUDE.md** avec les infos obtenues.
|
||||
|
||||
---
|
||||
|
||||
## STEP 3.5 — CTX7 DOC AUDIT (avant graphify)
|
||||
|
||||
Vérifier que le projet a les docs de ses fast-libs accessibles.
|
||||
|
||||
```bash
|
||||
command -v ctx7 &>/dev/null && ctx7 --version 2>/dev/null | head -1 || echo "ctx7-not-installed"
|
||||
ls .ctx7-cache/ 2>/dev/null
|
||||
```
|
||||
|
||||
### Détection fast-libs
|
||||
Parse manifests selon l'archétype :
|
||||
- **nextjs-app-router** → chercher : next, react, prisma, @supabase/*, drizzle-orm, next-auth, @clerk/*
|
||||
- **react-spa** → chercher : react, @tanstack/*, zustand, jotai
|
||||
- **rest-api-node** → chercher : fastify, @nestjs/*, prisma, drizzle-orm
|
||||
- **rest-api-python** → chercher : fastapi, pydantic, sqlalchemy (si ≥ 2.0)
|
||||
- **astro-static** → chercher : astro, @astrojs/*
|
||||
- **wordpress / cli-tool / library / dotfiles-meta / static-html** → souvent aucune fast-lib, audit léger
|
||||
|
||||
### Vérification cache
|
||||
Pour chaque fast-lib détectée :
|
||||
1. Existe un fichier `.ctx7-cache/<lib>.md` ?
|
||||
2. Fraîcheur < 7 jours ?
|
||||
|
||||
### Actions
|
||||
- **ctx7 installé + fast-libs détectées + cache manquant/obsolète** → proposer :
|
||||
```
|
||||
📚 DOC AUDIT ctx7
|
||||
Fast-libs détectées : [liste]
|
||||
Cache manquant/obsolète : [liste]
|
||||
|
||||
Pré-fetcher les docs maintenant ? (yes / skip)
|
||||
```
|
||||
Si yes :
|
||||
```bash
|
||||
mkdir -p .ctx7-cache
|
||||
ctx7 docs /vercel/next.js "app router middleware routing" > .ctx7-cache/nextjs-core.md
|
||||
# ... pour chaque lib détectée
|
||||
```
|
||||
Ajouter `.ctx7-cache/` au `.gitignore` si absent.
|
||||
|
||||
- **ctx7 non installé MAIS fast-libs détectées** → WARN :
|
||||
```
|
||||
⚠️ ctx7 non installé — risque de code utilisant des APIs obsolètes
|
||||
sur : [liste fast-libs]
|
||||
Install : `npm install -g ctx7 && ctx7 setup --claude`
|
||||
Ou continuer sans (non recommandé pour fast-libs).
|
||||
```
|
||||
Demander : `yes install now / continue without / skip audit`.
|
||||
|
||||
- **Pas de fast-lib** → skip silencieusement.
|
||||
|
||||
---
|
||||
|
||||
## STEP 4 — GRAPHIFY (si complexity ≥ 30% et pas déjà présent)
|
||||
|
||||
```bash
|
||||
command -v graphify &>/dev/null && echo "available" || echo "not-installed"
|
||||
test -f graphify-out/GRAPH_REPORT.md && echo "graph-exists"
|
||||
```
|
||||
|
||||
- **Pas installé** → skip avec message : `graphify non installé — skip audit architectural. Install : (voir graphify/SKILL.md)`
|
||||
- **Complexity < 30%** → skip silencieusement, projet trop petit pour justifier.
|
||||
- **Graphe déjà présent + récent** (fichier < 7j) → skip, réutiliser l'existant.
|
||||
- **Sinon** → run :
|
||||
```bash
|
||||
graphify . --output graphify-out 2>&1 | tail -20
|
||||
```
|
||||
Puis `test -f graphify-out/GRAPH_REPORT.md` pour valider.
|
||||
|
||||
Print : `🔗 Knowledge graph : graphify-out/GRAPH_REPORT.md (N nodes, M edges)`.
|
||||
|
||||
---
|
||||
|
||||
## STEP 4.5 — AUDIT WORKSPACE
|
||||
|
||||
Créer le dossier transitoire `.onboard-audit/` à la racine projet :
|
||||
|
||||
```bash
|
||||
mkdir -p .onboard-audit
|
||||
# Gitignore (ajout idempotent)
|
||||
grep -q '^\.onboard-audit/' .gitignore 2>/dev/null || \
|
||||
printf '\n# onboard audit raw outputs (consumed by /onboard STEP 7)\n.onboard-audit/\n' >> .gitignore
|
||||
```
|
||||
|
||||
Ce dossier contient les sorties brutes des audits (L3a+L3b). STEP 7 (L4) les synthétise vers `tasks/`. Peut être supprimé après L4 sans perte.
|
||||
|
||||
---
|
||||
|
||||
## STEP 5 — ANALYZE (read-only, general)
|
||||
|
||||
Spawn un subagent analyzer (isolé, pas de partage de contexte) :
|
||||
|
||||
```
|
||||
Agent(
|
||||
subagent_type="analyzer",
|
||||
description="Onboard — deep read-only analysis",
|
||||
prompt="""
|
||||
Read-only factual analysis of the project at <PROJECT_ROOT>.
|
||||
ARCHETYPE context: <archetype_name> — <category, public, database>.
|
||||
Focus areas (ordered) :
|
||||
1. Architecture risks (fragile couplings, missing abstractions, cycles)
|
||||
2. Dette technique visible (TODO/FIXME/HACK markers, commented code, god files)
|
||||
3. Patterns utilisés (bons et mauvais) — cite fichier:ligne
|
||||
4. Stale code suspects (last modified > 2 ans, no refs)
|
||||
5. Test coverage visible (quels modules testés, lesquels aveugles)
|
||||
6. Config drift (multiple configs pour même chose, values en dur)
|
||||
NO solutions. NO code changes. NO write outside the report.
|
||||
Write the report to `<PROJECT_ROOT>/.onboard-audit/analyze.md` with sections:
|
||||
## Summary (3 bullet points)
|
||||
## Architecture risks
|
||||
## Dette technique
|
||||
## Patterns (good + bad)
|
||||
## Stale code suspects
|
||||
## Test coverage blind spots
|
||||
## Config drift
|
||||
## Cross-references (vers graphify-out/GRAPH_REPORT.md si présent)
|
||||
Max 500 lignes. Priorise les éléments avec preuve concrète (fichier:ligne).
|
||||
"""
|
||||
)
|
||||
```
|
||||
|
||||
Attendre la fin. Vérifier que `.onboard-audit/analyze.md` existe et est non vide.
|
||||
|
||||
---
|
||||
|
||||
## STEP 6 — AUDIT DISPATCH selon archétype
|
||||
|
||||
Lire le bloc `audit_stack:` du fichier `~/.claude/lib/project-archetypes/<archetype>.md`.
|
||||
|
||||
**Mapping audit_stack entry → action :**
|
||||
|
||||
| Entry | Action | Livraison |
|
||||
|---|---|---|
|
||||
| `analyze` | Déjà fait en STEP 5 | L3a |
|
||||
| `code-clean` | Spawn subagent `code-cleaner` (audit-only) | L3a |
|
||||
| `cso` | Si gstack ON → Skill(cso). Sinon → Agent general-purpose avec checklist OWASP + deps audit | L3a |
|
||||
| `doc` | Spawn subagent `doc-syncer` (auto-mode OFF, report-only) | L3a |
|
||||
| `seo` | Subagents seo-analyzer + geo-analyzer en parallèle | L3b |
|
||||
| `design-review` | Si gstack ON → Skill design-review. Sinon → Agent ui-ux-pro-max context statique | L3b |
|
||||
| `perf` | Si gstack ON + URL → Lighthouse. Sinon → static bundle audit | L3b |
|
||||
| `a11y` | Si gstack ON + URL → axe-core. Sinon → Agent static a11y audit | L3b |
|
||||
|
||||
### STEP 6 dispatch (L3a portion)
|
||||
|
||||
Lancer EN PARALLÈLE (un seul message, plusieurs Agent calls) les audits correspondant aux entrées de `audit_stack:` qui sont en L3a (`code-clean`, `cso`, `doc`).
|
||||
|
||||
#### Dispatch code-cleaner (si `code-clean` dans audit_stack)
|
||||
```
|
||||
Agent(
|
||||
subagent_type="code-cleaner",
|
||||
description="Onboard — code-clean audit only",
|
||||
prompt="""
|
||||
AUDIT-ONLY mode — NO fixes, NO refactoring, NO file modifications.
|
||||
Target: <PROJECT_ROOT>. ARCHETYPE: <archetype>.
|
||||
Produce a report covering:
|
||||
1. Dead code (unused exports, unreachable branches, commented-out blocks)
|
||||
2. Style violations (per project linter config if present, else per global CLAUDE.md rules)
|
||||
3. Structural issues (god files, overly deep nesting, poor separation of concerns)
|
||||
4. Stale imports / unused deps (package.json vs actual imports, pyproject.toml vs imports)
|
||||
5. Duplicate code (copy-paste patterns)
|
||||
6. Outdated deps (if manifest present — list; do NOT run npm audit unless safe)
|
||||
Write the report to `<PROJECT_ROOT>/.onboard-audit/code-clean.md` with sections matching above.
|
||||
Each issue cite fichier:ligne. Prioritise par Sévérité (Critique/Haute/Moyenne/Basse).
|
||||
Max 500 lignes. Do NOT spawn sub-subagents (refactorer). Pure audit.
|
||||
"""
|
||||
)
|
||||
```
|
||||
|
||||
#### Dispatch security — `cso` (si `cso` dans audit_stack)
|
||||
|
||||
**Décision selon plugin state :**
|
||||
```bash
|
||||
# gstack actif ?
|
||||
bash $HOME/.claude/lib/toggle-external.sh list 2>/dev/null | grep -E "^gstack\s+(enabled|on)"
|
||||
```
|
||||
|
||||
- **gstack ON** → invoquer le skill cso via Skill tool :
|
||||
```
|
||||
Skill(skill="cso", args="comprehensive --report-only --output .onboard-audit/cso.md")
|
||||
```
|
||||
Note : le skill cso écrit son rapport lui-même ; on redirige via `--output` si supporté, sinon on capture la sortie et on écrit `.onboard-audit/cso.md` dans le skill parent.
|
||||
|
||||
- **gstack OFF** → fallback via Agent general-purpose :
|
||||
```
|
||||
Agent(
|
||||
subagent_type="general-purpose",
|
||||
description="Onboard — security audit fallback",
|
||||
prompt="""
|
||||
READ-ONLY security audit. No file modifications.
|
||||
Target: <PROJECT_ROOT>. ARCHETYPE: <archetype>. Stack: <stack>.
|
||||
Coverage (OWASP-aligned + supply chain):
|
||||
1. Secrets in repo (git grep for API_KEY, TOKEN, PASSWORD, .env committed)
|
||||
2. Dependencies with known vulns (npm audit / pip-audit / cargo audit if available, non-destructive)
|
||||
3. SQL injection risks (string-concat queries — grep for 'SELECT.*\\+' patterns)
|
||||
4. XSS risks (dangerouslySetInnerHTML, v-html, innerHTML, template render unsanitized)
|
||||
5. Authentication (hardcoded tokens, weak hash, missing rate limits)
|
||||
6. CORS / CSP misconfig
|
||||
7. Outdated runtime (Node <18, Python <3.9, PHP <8.1, etc.)
|
||||
8. .env.example exists? .env committed?
|
||||
9. Missing SECURITY.md
|
||||
10. Docker image base (scratch vs latest vs pinned) if Dockerfile present
|
||||
Write report to `<PROJECT_ROOT>/.onboard-audit/cso.md` with sections above,
|
||||
each issue cite fichier:ligne, sévérité Critique/Haute/Moyenne/Basse.
|
||||
Note en haut du rapport : "FALLBACK MODE — gstack cso skill not active, coverage limited."
|
||||
Max 500 lignes.
|
||||
"""
|
||||
)
|
||||
```
|
||||
|
||||
#### Dispatch doc-syncer (si `doc` dans audit_stack)
|
||||
```
|
||||
Agent(
|
||||
subagent_type="doc-syncer",
|
||||
description="Onboard — doc drift audit only",
|
||||
prompt="""
|
||||
REPORT-ONLY mode — NO edits, NO auto-sync.
|
||||
Target: full project at <PROJECT_ROOT>.
|
||||
Scope:
|
||||
1. README drift (build/test commands, install steps, usage examples vs actual code)
|
||||
2. CLAUDE.md drift (stack versions, commands)
|
||||
3. CHANGELOG.md freshness (last entry vs last commit date)
|
||||
4. INSTALL/CONFIGURE/USAGE/CONTRIBUTING drift if present
|
||||
5. Feature delta (feature added in code but not documented, feature documented but removed)
|
||||
6. Inline comments (JSDoc/docstring/rustdoc/godoc) coverage for public API
|
||||
Cross-reference with git log last 6 months.
|
||||
Write report to `<PROJECT_ROOT>/.onboard-audit/doc.md` with sections above,
|
||||
each drift cite file:line + commit-hash + date.
|
||||
Max 500 lignes.
|
||||
"""
|
||||
)
|
||||
```
|
||||
|
||||
### Après les 3 dispatches
|
||||
|
||||
Attendre la fin des 3 subagents. Vérifier que les 3 fichiers existent et sont non vides :
|
||||
```bash
|
||||
for f in .onboard-audit/{code-clean,cso,doc}.md; do
|
||||
[ -s "$f" ] && echo "OK $f" || echo "MISSING $f"
|
||||
done
|
||||
```
|
||||
|
||||
Si un subagent a échoué : afficher l'erreur, proposer à l'utilisateur :
|
||||
```
|
||||
⚠️ Audit <nom> a échoué : <erreur>
|
||||
Options :
|
||||
A) Retry
|
||||
B) Skip et continuer (rapport partiel en L4)
|
||||
C) Abort onboard
|
||||
```
|
||||
|
||||
### STEP 6 dispatch (L3b portion) — seo/geo + design + perf + a11y
|
||||
|
||||
Pré-check ressources navigateur :
|
||||
```bash
|
||||
# gstack actif ?
|
||||
bash $HOME/.claude/lib/toggle-external.sh list 2>/dev/null | grep -E "^gstack\s+(enabled|on)"
|
||||
# URL déployée fournie par l'utilisateur en STEP 3 ?
|
||||
echo "${BRIEF_deployed_url:-none}"
|
||||
# dev server launchable ?
|
||||
grep -E '"(dev|start|serve)":' package.json 2>/dev/null | head -3
|
||||
```
|
||||
|
||||
Lancer EN PARALLÈLE les audits présents dans `audit_stack:` de l'archétype (multiples Agent calls dans un seul message) :
|
||||
|
||||
#### Dispatch SEO+GEO (si `seo` dans audit_stack)
|
||||
|
||||
Le skill `/seo` appelle déjà seo-analyzer + geo-analyzer en parallèle, mais pour garder la cohérence "tout dans `.onboard-audit/`", on invoque les deux agents directement :
|
||||
|
||||
```
|
||||
Agent(
|
||||
subagent_type="seo-analyzer",
|
||||
description="Onboard — SEO audit (classical engines)",
|
||||
prompt="""
|
||||
AUDIT-ONLY mode — NO edits, NO auto-fixes. Target: <PROJECT_ROOT>.
|
||||
Classical search engines: Google, Bing, DuckDuckGo.
|
||||
Archetype: <archetype>. Public: <true/false>. Deployed URL (si fournie): <url or none>.
|
||||
Coverage:
|
||||
- meta (title, description, OG, Twitter Card)
|
||||
- robots.txt, sitemap.xml, canonical, hreflang
|
||||
- JSON-LD / Schema.org classical
|
||||
- Core Web Vitals (estimé si pas d'URL live)
|
||||
- headings hierarchy, alt attrs, images formats
|
||||
- i18n / lang attribute
|
||||
Si URL live fournie AND gstack actif: utiliser les outils live.
|
||||
Sinon: audit statique sur le code (HTML templates, Astro pages, Next Metadata API, etc.).
|
||||
Write report to `<PROJECT_ROOT>/.onboard-audit/seo.md`.
|
||||
Structure sections par catégorie, chaque issue cite fichier:ligne + sévérité.
|
||||
Max 500 lignes.
|
||||
"""
|
||||
)
|
||||
|
||||
Agent(
|
||||
subagent_type="geo-analyzer",
|
||||
description="Onboard — GEO audit (AI engines)",
|
||||
prompt="""
|
||||
AUDIT-ONLY mode — NO edits, NO auto-fixes. Target: <PROJECT_ROOT>.
|
||||
AI search engines: ChatGPT, Perplexity, Claude, Gemini, Google AI Overviews, Copilot.
|
||||
Archetype: <archetype>. Public: <true/false>. Deployed URL: <url or none>.
|
||||
Coverage:
|
||||
- AI crawler directives in robots.txt (GPTBot, ClaudeBot, PerplexityBot, etc.)
|
||||
- llms.txt / llms-full.txt presence and quality
|
||||
- Schema.org types GEO-optimised (QAPage, Speakable, HowTo, Person+Article, Organization graph)
|
||||
- Entity SEO (Wikidata QID, sameAs, @id consistency, Knowledge Panel signals)
|
||||
- Content shape for LLM extraction (Definition Lead, TL;DR, Q→A structure, citable stats, freshness)
|
||||
- AI visibility monitoring recommendations
|
||||
Write report to `<PROJECT_ROOT>/.onboard-audit/geo.md`.
|
||||
Max 500 lignes. Cite fichier:ligne, sévérité.
|
||||
"""
|
||||
)
|
||||
```
|
||||
|
||||
**SEO+GEO skip rules:**
|
||||
- Si archetype.public == false ET `seo` dans audit_stack → ne devrait pas arriver, mais si oui : skip silencieusement, `.onboard-audit/seo.md` et `geo.md` non créés.
|
||||
- Si projet a 0 contenu HTML/template (ex: React SPA public) → lancer quand même mais signaler en haut du rapport : "⚠️ SPA détectée — SEO intrinsèquement limité, voir archetype warning dans .onboard-audit/archetype-warnings.md".
|
||||
|
||||
#### Dispatch design-review (si `design-review` dans audit_stack)
|
||||
|
||||
**Cas gstack ON + URL live OU dev server launchable :**
|
||||
```
|
||||
Skill(
|
||||
skill="gstack:design-review",
|
||||
args="--url <url or http://localhost:PORT> --output .onboard-audit/design.md --audit-only"
|
||||
)
|
||||
```
|
||||
Si le skill ne supporte pas `--output`, capturer la sortie et écrire à la main vers `.onboard-audit/design.md`.
|
||||
|
||||
**Cas gstack OFF OU pas de site déployable (ex: react-spa sans dev server):**
|
||||
```
|
||||
Agent(
|
||||
subagent_type="general-purpose",
|
||||
description="Onboard — static design review fallback",
|
||||
prompt="""
|
||||
AUDIT-ONLY mode — NO edits. Static design review du code UI.
|
||||
Target: <PROJECT_ROOT>. Archetype: <archetype>.
|
||||
Context: ui-ux-pro-max plugin state = <active/inactive>.
|
||||
Si ui-ux-pro-max actif : lire ses guidelines depuis les skills ui-ux-pro-max.
|
||||
Coverage (static, depuis code uniquement) :
|
||||
1. Design system (tokens : colors, spacing, radius, typography) — présent ou absent ?
|
||||
Cohérence : toutes les couleurs sont-elles dans les tokens ou hardcodées dans les composants ?
|
||||
2. Composants réutilisables vs duplication (Button en 5 variantes dispersées ?)
|
||||
3. Dark mode support ? Responsive (breakpoints) ? État de l'a11y dans les composants ?
|
||||
4. Animations (présence, durées < 300ms, ease-out par défaut — cf. emil-design-eng si actif)
|
||||
5. État vide / loading / error dans les composants
|
||||
6. Typography hiérarchie (combien de tailles différentes ? trop ?)
|
||||
7. Couleurs : contrastes ratio (AA minimum = 4.5:1 pour texte)
|
||||
8. Interactions : focus visible, hover states, disabled states
|
||||
9. Micro-interactions (billboard design ? transform scale(0.97) on :active ?)
|
||||
Write report to `<PROJECT_ROOT>/.onboard-audit/design.md`.
|
||||
Note en haut : "STATIC MODE — gstack inactif ou pas de dev server ; audit limité au code."
|
||||
Max 500 lignes. Cite fichier:ligne.
|
||||
"""
|
||||
)
|
||||
```
|
||||
|
||||
**Skip rules:**
|
||||
- Si `design-review` pas dans audit_stack (backend, CLI, lib) → skip silencieusement.
|
||||
- Si archetype frontend mais pas de composants détectés (tout HTML pur) → noter "pure HTML — design review réduit aux sections 3-8".
|
||||
|
||||
#### Dispatch perf (si `perf` dans audit_stack)
|
||||
|
||||
**Cas gstack ON + URL live :**
|
||||
```
|
||||
Skill(
|
||||
skill="gstack:browse",
|
||||
args="--lighthouse --url <url or http://localhost:PORT> --output .onboard-audit/perf-lighthouse.json"
|
||||
)
|
||||
```
|
||||
Puis parser le JSON Lighthouse (scores perf/a11y/bp/seo/pwa + top opportunities) → écrire `.onboard-audit/perf.md`.
|
||||
|
||||
**Cas gstack OFF OU pas d'URL :**
|
||||
```
|
||||
Agent(
|
||||
subagent_type="general-purpose",
|
||||
description="Onboard — static perf audit",
|
||||
prompt="""
|
||||
AUDIT-ONLY mode — NO edits.
|
||||
Target: <PROJECT_ROOT>. Archetype: <archetype>.
|
||||
Static perf audit (pas de browser) :
|
||||
1. Bundle analyzers config présent ?
|
||||
- Next: `@next/bundle-analyzer` dans deps ?
|
||||
- Vite: `rollup-plugin-visualizer` ?
|
||||
- Webpack: `webpack-bundle-analyzer` ?
|
||||
Si NON, recommander l'install + usage.
|
||||
Si OUI et script existe, tenter execution NON-DESTRUCTIVE si safe (produit un HTML/rapport, pas de modif code).
|
||||
2. Dependencies taille — identifier les grosses deps (> 100kb) depuis package-lock.json / pnpm-lock.yaml.
|
||||
3. Images dans `public/` ou `assets/` : compter non-optimisées (PNG/JPG > 200kb sans WebP/AVIF variant).
|
||||
4. Polices web : Google Fonts via <link> (blocking) vs self-hosted ? font-display: swap ?
|
||||
5. Code splitting : dynamic imports () présents ? Chaque route a son chunk ?
|
||||
6. Lazy loading : `loading="lazy"` sur les <img> ? IntersectionObserver pour composants lourds ?
|
||||
7. React-specific: React.memo / useMemo / useCallback overuse ou sous-utilisé ?
|
||||
8. CSS: quantité totale, CSS-in-JS runtime cost, unused CSS ?
|
||||
9. SSR/SSG/ISR strategy (si Next/Astro) — cohérente avec le contenu ?
|
||||
10. Core Web Vitals estimés à partir du code (TTFB impossible, mais LCP/CLS inférables).
|
||||
Write report to `<PROJECT_ROOT>/.onboard-audit/perf.md`.
|
||||
Note "STATIC MODE" si sans browser.
|
||||
Max 500 lignes.
|
||||
"""
|
||||
)
|
||||
```
|
||||
|
||||
#### Dispatch a11y (si `a11y` dans audit_stack)
|
||||
|
||||
**Cas gstack ON + URL live :**
|
||||
```
|
||||
Skill(
|
||||
skill="gstack:browse",
|
||||
args="--axe --url <url> --output .onboard-audit/a11y-axe.json"
|
||||
)
|
||||
```
|
||||
Parser axe-core résultats (violations, incomplete, inapplicable, passes) → `.onboard-audit/a11y.md`.
|
||||
|
||||
**Cas statique :**
|
||||
```
|
||||
Agent(
|
||||
subagent_type="general-purpose",
|
||||
description="Onboard — static a11y audit",
|
||||
prompt="""
|
||||
AUDIT-ONLY mode — NO edits.
|
||||
Target: <PROJECT_ROOT>. Archetype: <archetype>.
|
||||
Static a11y audit (WCAG 2.1 AA + RGAA 4.1 France) :
|
||||
1. <html lang="…"> présent sur toutes les pages ?
|
||||
2. Landmarks (header/nav/main/footer/aside) utilisés ou encore div-soup ?
|
||||
3. Heading hierarchy (h1 unique, pas de saut h1→h3) — scanner tous les templates.
|
||||
4. Images : <img> ont tous un alt ? alt décoratif = "" ? alt redondant avec caption ?
|
||||
5. Formulaires : chaque <input> a un <label>, aria-label, ou aria-labelledby ?
|
||||
6. Boutons vs liens : <a> sans href, <div onClick>, <span role="button"> → red flags.
|
||||
7. Focus visible : outline:none sans :focus-visible alternative ? tabindex="-1" abusif ?
|
||||
8. Couleurs : contrastes (peut se vérifier depuis tokens si présents).
|
||||
9. Animations : prefers-reduced-motion respecté ?
|
||||
10. ARIA : live regions pour toasts/notifs, role="dialog" pour modals avec focus trap ?
|
||||
11. Keyboard : navigation sans souris possible sur features critiques (depuis revue statique event handlers) ?
|
||||
12. Screen reader affordances : visually-hidden class, aria-describedby ?
|
||||
Contexte France : RGAA 4.1 critères applicables + déclaration d'accessibilité obligatoire (sites publics > seuils).
|
||||
Write report to `<PROJECT_ROOT>/.onboard-audit/a11y.md`.
|
||||
Note "STATIC MODE" si pas d'axe-core.
|
||||
Max 500 lignes. Cite fichier:ligne.
|
||||
"""
|
||||
)
|
||||
```
|
||||
|
||||
### Après tous les dispatches L3b
|
||||
|
||||
Vérification :
|
||||
```bash
|
||||
for f in .onboard-audit/{seo,geo,design,perf,a11y}.md; do
|
||||
[ -f "$f" ] && echo "OK $f ($(wc -l < "$f") lignes)" || echo "— $f (skipped, archétype n'a pas cet audit)"
|
||||
done
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## STEP 7 — SYNTHÈSE dans `tasks/`
|
||||
|
||||
À partir des rapports bruts dans `.onboard-audit/`, générer 4 fichiers structurés dans `tasks/`.
|
||||
|
||||
Spawn un subagent synthétiseur (isolé, chargé uniquement du contenu de `.onboard-audit/`) :
|
||||
|
||||
```
|
||||
Agent(
|
||||
subagent_type="general-purpose",
|
||||
description="Onboard — synthèse vers tasks/",
|
||||
prompt="""
|
||||
Lire tous les fichiers de <PROJECT_ROOT>/.onboard-audit/ :
|
||||
- analyze.md, code-clean.md, cso.md, doc.md (toujours)
|
||||
- seo.md, geo.md, design.md, perf.md, a11y.md (si présents)
|
||||
Contexte : archetype=<archetype>, public=<bool>, stack=<stack>, brief_interview=<summary>.
|
||||
|
||||
Produire 4 fichiers dans <PROJECT_ROOT>/tasks/ :
|
||||
|
||||
═══ 1. tasks/ONBOARD_REPORT.md — synthèse exécutive ═══
|
||||
Structure :
|
||||
# Onboard Report — <project_name>
|
||||
## Profile
|
||||
- Archétype: <name> (<category>)
|
||||
- Stack: <lang+framework+db+hosting>
|
||||
- Public: <yes/no>
|
||||
- Taille: <lines of code / files count>
|
||||
## Scores par domaine (0-100, calculés depuis le nombre d'issues par sévérité)
|
||||
| Domaine | Score | Forces majeures | Problèmes majeurs |
|
||||
| analyze (dette) | 72 | bonne séparation MVC | god file src/foo.js |
|
||||
| code-clean | ... |
|
||||
| cso (sécu) | ...
|
||||
| doc | ...
|
||||
| seo (si public) | ...
|
||||
| geo (si public) | ...
|
||||
| design | ...
|
||||
| perf | ...
|
||||
| a11y | ...
|
||||
## Top 5 priorités (choisies depuis AUDIT_ISSUES par score sévérité × impact projet)
|
||||
1. [P0 Critique] <titre> — <domaine> — <impact en 1 phrase>
|
||||
2. ...
|
||||
## Prochaines étapes (pointeurs vers les 3 autres fichiers)
|
||||
|
||||
═══ 2. tasks/AUDIT_GOOD.md — ce qui va ═══
|
||||
Inventaire positif par domaine. Ce qu'il faut PROTÉGER en modifiant le reste.
|
||||
Structure:
|
||||
# Audit — Ce qui va
|
||||
## Dette technique
|
||||
- <pattern sain repéré> (ex: "services layer bien isolé de l'API")
|
||||
## Sécurité
|
||||
- <forces>
|
||||
## [domaine par domaine]
|
||||
|
||||
═══ 3. tasks/AUDIT_ISSUES.md — ce qui ne va pas ═══
|
||||
Listing par sévérité descendante (Critique → Basse).
|
||||
Structure:
|
||||
# Audit — Ce qui ne va pas
|
||||
## Critique
|
||||
### [domaine] <titre>
|
||||
- Fichier(s): path:line
|
||||
- Preuve: <extrait ou description concrète>
|
||||
- Impact: <une phrase>
|
||||
- Référence: .onboard-audit/<source>.md
|
||||
## Haute
|
||||
## Moyenne
|
||||
## Basse
|
||||
Ne pas inventer, ne citer QUE ce qui est dans .onboard-audit/.
|
||||
|
||||
═══ 4. tasks/AUDIT_PROPOSALS.md — propositions ═══
|
||||
Pour CHAQUE issue Critique et Haute du fichier ISSUES : proposer au minimum 2 options,
|
||||
avec tradeoffs. Pour les issues Moyennes : 1 option suffit.
|
||||
Structure:
|
||||
# Audit — Propositions d'amélioration
|
||||
## [P0 Critique] <titre issue>
|
||||
Contexte: <rappel court>
|
||||
Option A — <titre> :
|
||||
- Approche: <1-3 phrases>
|
||||
- Coût: <estimation S/M/L>
|
||||
- Risque: <faible/moyen/élevé>
|
||||
- Gain: <phrase>
|
||||
Option B — <titre> :
|
||||
...
|
||||
Option C (optionnel) :
|
||||
...
|
||||
**Recommandation**: Option <X> — <justification 1-2 phrases>
|
||||
## [P1 Haute] ...
|
||||
## [P2 Moyenne] ...
|
||||
|
||||
Règles de qualité :
|
||||
- Chaque fichier max 800 lignes (split si dépasse, jamais tronquer le contenu crucial)
|
||||
- Citer TOUTES les sources .onboard-audit/ utilisées (preuve traçable)
|
||||
- Pas de conseil générique — toujours relier à une preuve concrète
|
||||
- Radical honesty : si un audit révèle une faille structurelle majeure (ex: SPA public),
|
||||
le dire clairement en P0 Critique, ne pas édulcorer
|
||||
"""
|
||||
)
|
||||
```
|
||||
|
||||
Vérifier que les 4 fichiers `tasks/ONBOARD_REPORT.md`, `tasks/AUDIT_GOOD.md`, `tasks/AUDIT_ISSUES.md`, `tasks/AUDIT_PROPOSALS.md` existent et sont non vides.
|
||||
|
||||
---
|
||||
|
||||
## STEP 8 — VALIDATION GATE ★ MANDATORY STOP
|
||||
|
||||
Afficher à l'utilisateur :
|
||||
|
||||
```
|
||||
═══ ONBOARD — RAPPORT PRÊT ═══
|
||||
|
||||
Archétype: <name>
|
||||
Stack: <stack>
|
||||
Scores: dette:<X> · sécu:<X> · doc:<X> [· seo:<X> · geo:<X> · design:<X> · perf:<X> · a11y:<X>]
|
||||
|
||||
📂 Fichiers produits dans tasks/ :
|
||||
- ONBOARD_REPORT.md (synthèse exécutive)
|
||||
- AUDIT_GOOD.md (ce qui va)
|
||||
- AUDIT_ISSUES.md (ce qui ne va pas, par sévérité)
|
||||
- AUDIT_PROPOSALS.md (propositions avec options + tradeoffs)
|
||||
|
||||
TOP 5 PRIORITÉS :
|
||||
1. [P0 Critique] <titre>
|
||||
2. [P0 Critique] <titre>
|
||||
3. [P1 Haute] <titre>
|
||||
4. [P1 Haute] <titre>
|
||||
5. [P2 Moyenne] <titre>
|
||||
|
||||
Prochaine étape : générer tasks/TODO.md depuis AUDIT_PROPOSALS.md approuvé.
|
||||
|
||||
Options :
|
||||
A) Lire d'abord les 4 fichiers, je reviens te le dire (STOP)
|
||||
B) Tout est OK, génère TODO.md depuis toutes les propositions recommandées
|
||||
C) Je veux éditer AUDIT_PROPOSALS.md avant de générer TODO.md (indiquer ce à changer)
|
||||
D) Réduire le scope — ne garder que P0 Critique dans TODO.md
|
||||
E) Abort — je n'utilise pas le backlog auto
|
||||
|
||||
Choix ? (A / B / C / D / E)
|
||||
```
|
||||
|
||||
**STOP.** Attendre la réponse.
|
||||
|
||||
- **A** → stop ici, l'utilisateur relira et reviendra avec `/onboard continue`.
|
||||
- **B** → continuer STEP 9 avec toutes les recommandations.
|
||||
- **C** → demander les changements spécifiques, les appliquer dans AUDIT_PROPOSALS.md, puis re-présenter la gate.
|
||||
- **D** → continuer STEP 9 avec seulement les P0.
|
||||
- **E** → arrêter sans générer TODO.md, print "Onboard rapport figé dans tasks/ — tu peux t'en servir à la main ensuite."
|
||||
|
||||
---
|
||||
|
||||
## STEP 9 — BACKLOG → tasks/TODO.md
|
||||
|
||||
Lire `tasks/AUDIT_PROPOSALS.md` (avec les "Recommandations" sélectionnées par l'utilisateur). Pour chaque proposition recommandée, générer une entrée dans `tasks/TODO.md` :
|
||||
|
||||
Format :
|
||||
```
|
||||
# TODO — onboard backlog (<date>)
|
||||
|
||||
<!-- Généré par /onboard — une entrée par proposition approuvée.
|
||||
Format: - [ ] [Priorité] [/skill] — description — fichiers estimés -->
|
||||
|
||||
## P0 — Critique
|
||||
- [ ] [P0] [/hotfix] — <titre>
|
||||
Fichiers: <paths>
|
||||
Source: AUDIT_PROPOSALS.md § "<titre>"
|
||||
Option recommandée: <A/B/C>
|
||||
- [ ] [P0] [/bugfix] — <titre>
|
||||
Fichiers: ...
|
||||
|
||||
## P1 — Haute
|
||||
- [ ] [P1] [/feat] — <titre>
|
||||
- [ ] [P1] [/ship-feature] — <titre>
|
||||
|
||||
## P2 — Moyenne
|
||||
- [ ] [P2] [/code-clean] — <titre>
|
||||
- [ ] [P2] [/refactor] — <titre>
|
||||
|
||||
## P3 — Basse
|
||||
- [ ] [P3] [...] — ...
|
||||
|
||||
## Post-MVP (non-priorisé, backlog)
|
||||
- [ ] ...
|
||||
```
|
||||
|
||||
**Règles de sélection du skill recommandé :**
|
||||
|
||||
| Type de proposition | Skill |
|
||||
|---|---|
|
||||
| Typo, CSS, config, import manquant (1-2 fichiers, cause évidente) | `/hotfix` |
|
||||
| Bug avec investigation (plusieurs fichiers) | `/bugfix` |
|
||||
| Petite feature (1-5 fichiers) | `/feat` |
|
||||
| Grosse feature (design, multi-fichiers, architecture) | `/ship-feature` |
|
||||
| Dette technique (dead code, style, dupes) | `/code-clean` |
|
||||
| Refactoring sans changement de comportement | `/refactor` |
|
||||
| Audit SEO/GEO à re-lancer après corrections | `/seo` ou `/geo` |
|
||||
| Audit docs à re-sync après changement | `/doc` |
|
||||
|
||||
Ne PAS écraser `tasks/TODO.md` s'il contient déjà du contenu utilisateur : append avec un séparateur :
|
||||
```
|
||||
<contenu existant>
|
||||
|
||||
---
|
||||
# Onboard backlog (généré le YYYY-MM-DD)
|
||||
|
||||
<nouveau contenu>
|
||||
```
|
||||
|
||||
Print :
|
||||
```
|
||||
✅ tasks/TODO.md mis à jour — <N> tâches ajoutées (<P0>/<P1>/<P2>/<P3>)
|
||||
Pour démarrer : lire tasks/TODO.md, choisir une tâche P0, lancer le /skill indiqué.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
---
|
||||
|
||||
## RULES
|
||||
- NO skipping STEP 0, 1, 2 — ils sont obligatoires.
|
||||
- NO audit agressif : chaque subagent doit recevoir "AUDIT-ONLY, no file modifications".
|
||||
- STEP 1 doit proposer un override `force-archetype:<name>` si l'utilisateur sait déjà.
|
||||
- Monorepo : toujours demander le mode (A/B/C) avant STEP 2.
|
||||
- Si `CLAUDE.md` existe : le lire, ne pas l'écraser sans fusion après STEP 3.
|
||||
- STEP 3 : ne redemande jamais ce qui est déjà dans README ou manifests.
|
||||
- STEP 3.5 : si ctx7 absent + fast-libs, WARN mais ne bloque pas.
|
||||
- STEP 4 : skip si complexity < 30% ou graph récent déjà présent.
|
||||
- STEP 5-6 : subagents isolés (Agent tool avec subagent_type spécifique) — pas de contexte partagé entre les audits. Chaque subagent écrit son rapport dans `.onboard-audit/<name>.md`.
|
||||
- STEP 6 dispatches parallélisables : regrouper dans un seul message Agent multi-calls.
|
||||
- `.onboard-audit/` gitignoré automatiquement — ne jamais commiter.
|
||||
- Si un subagent échoue : proposer retry/skip/abort, ne pas auto-retry silencieusement.
|
||||
|
||||
---
|
||||
|
||||
## FINAL OUTPUT
|
||||
```
|
||||
ONBOARD COMPLETE: <project name>
|
||||
ARCHETYPE : <name> (confiance: <niveau>)
|
||||
STACK : <stack>
|
||||
CONFIG : ✅ CLAUDE.md, settings.json, .claudeignore, tasks/
|
||||
CTX7 CACHE : ✅ [libs] | ⚠️ not installed | — N/A
|
||||
GRAPHIFY : ✅ graphify-out/ | ⚠️ not installed | — skipped (simple)
|
||||
AUDITS :
|
||||
✅ dette technique (.onboard-audit/analyze.md + code-clean.md)
|
||||
✅ sécurité (.onboard-audit/cso.md)
|
||||
✅ docs drift (.onboard-audit/doc.md)
|
||||
✅ SEO + GEO (.onboard-audit/seo.md + geo.md) [si public]
|
||||
✅ design UI/UX (.onboard-audit/design.md) [si frontend]
|
||||
✅ performance (.onboard-audit/perf.md)
|
||||
✅ accessibilité (.onboard-audit/a11y.md) [si frontend]
|
||||
|
||||
SYNTHÈSE :
|
||||
✅ tasks/ONBOARD_REPORT.md (exécutif)
|
||||
✅ tasks/AUDIT_GOOD.md
|
||||
✅ tasks/AUDIT_ISSUES.md (par sévérité)
|
||||
✅ tasks/AUDIT_PROPOSALS.md (options + tradeoffs)
|
||||
✅ tasks/TODO.md (backlog priorisé avec skill recommandé)
|
||||
|
||||
NEXT STEPS :
|
||||
1. Ouvrir tasks/ONBOARD_REPORT.md — overview complète
|
||||
2. Démarrer par la première tâche P0 de tasks/TODO.md avec le skill indiqué
|
||||
3. /onboard add gsd — générer ROADMAP.md pour multi-session si besoin
|
||||
4. .onboard-audit/ peut être supprimé (raw data consommée en synthèse)
|
||||
```
|
||||
|
||||
Loading…
Reference in New Issue
Block a user