diff --git a/agents/onboarder.md b/agents/onboarder.md index 209d1d7..f9d2b63 100644 --- a/agents/onboarder.md +++ b/agents/onboarder.md @@ -11,6 +11,9 @@ effort: medium ## ROLE 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. +Two modes. No `MODE:` line in the brief → the generator below (PHASES 1-6). +`MODE: split` → only § MODE: split at the end of this file runs. + --- ## INPUTS (passed by orchestrator) @@ -167,6 +170,85 @@ PLACEHOLDERS : - A command the permission rules refuse is reported in your final message with the rule that stopped it, never rerun through a wrapper script, alias, env file, `make` target or another shell (a brief that orders the refused form is wrong: report it, do not comply). - 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). +- NO destructive writes: never overwrite CLAUDE.md if it exists without asking (print path + STOP, let orchestrator decide). MODE: split edits it by design, row by row, on the approved TABLE. - Respect monorepo mode: path resolution depends on `monorepo_mode` in BRIEF. - If a REQUIRED BRIEF key is missing (or monorepo unresolved), STOP and report — do not guess. Null OPTIONAL keys are normal on first dispatch: placeholder, don't stop. + +--- + +## MODE: split (dispatched by `/onboard split`) + +INPUTS: `PROJECT_ROOT` (absolute; written as a literal path in every +command below, never through a variable), `TABLE` = the approved rows, one +per line, ` | | ` (heading without `## `). No +BRIEF; PHASES 1-6 do not run. `PR` below stands for +`bash ~/.claude/lib/project-rules.sh -C `. + +S0 — PREFLIGHT (no write before every row passes): +- `git -C status --porcelain` is empty, else STOP. +- gitignore: `git -C check-ignore -q .claude/rules/probe.md` + rc 0 means the rules would be ignored → append the negation (portable, + lands after any `.claude/*` line): + `printf '!.claude/rules/\n' >> /.gitignore` + then re-run `check-ignore`; still rc 0 → STOP: "ignore form cannot be + negated (BDR-003: use the `.claude/*` file form)", and `git -C + checkout -- .gitignore`. Remember whether this step + appended (`GITIGNORE_TOUCHED`): `.gitignore` enters the later `add`, + `checkout` and `commit` only then (a repo with no `.gitignore` is rc 1 + here and never names it: a missing pathspec is a fatal git error). +- per row: `PR sections CLAUDE.md` lists `## ` exactly once; + `/.claude/rules/.md` does not exist; every glob of + `` passes `PR matches ''` (rc 0). Any failure → STOP + with the row and the reason (nothing written yet besides the gitignore + line, which the STOP reverts). + +S1 — EXTRACT, per row (single quotes around the heading): +```bash +bash ~/.claude/lib/project-rules.sh -C extract CLAUDE.md '' .claude/rules/.md '' +``` +rc ≠ 0 (should not happen after S0) → ROLLBACK: `git -C +reset -q`, `git -C checkout -- CLAUDE.md` (plus +`.gitignore` when S0 appended to it), delete every +`.claude/rules/.md` this run wrote (literal paths, one `rm` per +row), then STOP with the row and the lib's message. + +S2 — POINTER. If CLAUDE.md has no `## Path-scoped rules` section, append: +```markdown + +## Path-scoped rules +Project rules live in `.claude/rules/.md` and load on Read of a file +matching their `paths:` (never at session start): , . +``` +Else add the new names to its list. Collapse runs of blank lines left by +the extraction (never more than one). + +S3 — CHECK, COMMIT, VERIFY TRACKED. +```bash +bash ~/.claude/lib/project-rules.sh -C check +``` +rc ≠ 0 → ROLLBACK as in S1, STOP with the culprit lines. rc 0 → +```bash +git -C add CLAUDE.md .claude/rules # + .gitignore when S0 appended +git -C commit -m "" +``` +`` follows the project's commit convention (its CLAUDE.md commit +rules: allowed types and scopes); with none, `chore: split CLAUDE.md +section(s) into .claude/rules/`. Commit rc ≠ 0 (a hook refused it, e.g. +the gitflow pre-commit on a protected branch, or gitleaks) → ROLLBACK as +in S1, STOP with the hook's output verbatim. rc 0 → verify each row in +the commit, not in the index: +```bash +git -C cat-file -e HEAD:.claude/rules/.md # per row +``` +A row `cat-file` cannot find → `STOP: not in HEAD after commit + (commit kept)`; the orchestrator never re-dispatches on it. + +OUTPUT: +``` +SPLIT DONE: rule(s) — .md (), … +CLAUDE.md: → lines +CHECK : project-rules: rule(s) ok +COMMIT : — all rules in HEAD +``` +or `STOP: — (rollback done, nothing committed)`, or +`STOP: not in HEAD after commit (commit kept)`. diff --git a/skills/onboard/SKILL.md b/skills/onboard/SKILL.md index a4f10b8..a0e3fd4 100644 --- a/skills/onboard/SKILL.md +++ b/skills/onboard/SKILL.md @@ -1,8 +1,8 @@ --- name: onboard effort: xhigh -description: 'Use when bringing an existing repo into the claude-config framework — needs archetype detection, config install, full multi-axis audit (debt/SEO/GEO/UI-UX/perf/security/a11y/docs), and prioritized backlog. Multi-agent orchestrator. Do NOT use for repos created via /init-project. Triggers: "onboard", "onboard project", "audit existing repo", "setup existing project".' -argument-hint: '[optional hints: "Python FastAPI" | "Next.js monorepo" | "force-archetype:wordpress"]' +description: 'Use when bringing an existing repo into the claude-config framework — needs archetype detection, config install, full multi-axis audit (debt/SEO/GEO/UI-UX/perf/security/a11y/docs), and prioritized backlog. Multi-agent orchestrator. Default flow: do NOT use it for repos created via /init-project. Triggers: "onboard", "onboard project", "audit existing repo", "setup existing project". `split` mode (any repo): "onboard split", "split the project instructions", "découpe le fichier CLAUDE", "path-scoped rules".' +argument-hint: '[split | optional hints: "Python FastAPI" | "Next.js monorepo" | "force-archetype:wordpress"]' allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Agent, Skill --- @@ -21,6 +21,13 @@ $ARGUMENTS --- +## MODE DISPATCH +`$ARGUMENTS` whose first token is `split` → jump to § SPLIT MODE (end of +this file); STEP 0 to FINAL OUTPUT do not run. Anything else → the flow +below, unchanged. + +--- + ## STEP 0 — PLUGIN CHECK + AUTO-ACTIVATE Run `$HOME/.claude/lib/plugin-gate.md` with hint "onboarding existing project + $ARGUMENTS" (dispatch plugin-probe → checkpoint → dispatch plugin-advisor → gates in this loop, BDR-077). @@ -198,7 +205,7 @@ Ne pas redemander ce qui est déjà dans : 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. +Après réponses : **mettre à jour le brouillon CLAUDE.md** avec les infos obtenues, et les placeholders `` des `.claude/rules/*.md` émis en PHASE 5b (Docker, tests, CI : leurs réponses vont dans la règle, pas dans CLAUDE.md). --- @@ -1034,11 +1041,11 @@ Pour démarrer : lire .claude/tasks/TODO.md, choisir une tâche P0, lancer le /s --- ## RULES -- NO skipping STEP 0, 1, 2 — ils sont obligatoires. +- NO skipping STEP 0, 1, 2 — ils sont obligatoires (split mode runs its own steps, § SPLIT MODE). - NO audit agressif : chaque subagent doit recevoir "AUDIT-ONLY, no file modifications". - STEP 1 doit proposer un override `force-archetype:` 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. +- Si `CLAUDE.md` existe : le lire, ne pas l'écraser sans fusion après STEP 3 (default flow; split mode edits it on the approved table). - 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 : graphify proposé seulement si `graphify-gate.sh` imprime une ligne (≥ 200 fichiers code, pas de graphe — BDR-097) ; l'utilisateur décide, jamais de build sans oui explicite. @@ -1079,3 +1086,94 @@ NEXT STEPS : 3. GSD (multi-session) : `gsd init` à la main, voir docs gsd-pi 4. .onboard-audit/ peut être supprimé (raw data consommée en synthèse) ``` + +--- + +## SPLIT MODE — `/onboard split` (BDR-125 phase 0) + +Move the path-bound sections of an existing project `CLAUDE.md` into +`.claude/rules/.md` path rules (loaded on Read of a matching file), +so the always-on context of that project shrinks. Judgment here, writes by +the onboarder, `lib/project-rules.sh` as the only glob oracle. The MODEL +GATE above has run. `mcp__model-router__route(phase="plan")` first. +`` below is the project root as a literal absolute path. + +S1 — PRECONDITIONS. `CLAUDE.md` at ``, else print `nothing to split — +run /onboard` and stop. `git -C status --porcelain` empty (whole +tree) and the current branch is `develop` (or `main` when no `develop` +exists), else stop and say why: the split branches off develop, and an +in-flight feature branch or dirty file would be classified on one version +and extracted on another. `.claude/rules/` already holding rules → list +them, continue (new rules add to them). + +S2 — BASELINE. `claude -p "/context"` from `` (refused → ask the user +to run `! claude -p "/context"`); note the `Memory files` total and the +project CLAUDE.md row. + +S3 — BRANCH. `cd && bash ~/.claude/lib/gitflow.sh start chore +claude-md-split`. A project without gitflow (no `develop`): +`git -C switch -c chore/claude-md-split`, and say so. Everything +after this step reads the branched file. + +S4 — CLASSIFY. `bash ~/.claude/lib/project-rules.sh -C sections +CLAUDE.md` lists every `##` section with its size. For each one decide: +- always-on: project overview, stack, build/test/lint commands, folder + structure, conventions that apply everywhere, exceptions to global rules, + workflow expectations, key dependencies, anything needed before a file is + read (how to run the project), even when it names a folder; +- path-scoped: one module or folder, Docker, migrations, CI, a tool's + gotchas, a vendored or machine-owned area. Propose `` (kebab, the + section's subject) and globs (a folder → `dir/**`, a tool → its config + files; never a brace glob `*.{ts,tsx}`: one glob per extension, the + oracle does no brace expansion) and verify EVERY proposed glob with + `bash ~/.claude/lib/project-rules.sh -C matches ''` (rc 0) + before showing it. A heading containing `'` or `|` is not split by this + mode (say so; the user renames it first). + +S5 — GATE (mandatory stop). Print the table, then end the turn: + +``` +SPLIT — CLAUDE.md ( chars, sections) on chore/claude-md-split +| # | section | chars | verdict | rule file | paths | +| 1 | Stack | 420 | keep | | | +| 2 | Docker | 1,340 | move | docker.md | ["Dockerfile*", "docker-compose*"] | +... +Moves sections, chars (

% of the file). Approve, edit a row, or "keep everything". +``` +"keep everything" ends the mode with no change (`bash +~/.claude/lib/gitflow.sh delete chore/claude-md-split`). An edited row's +globs are re-verified with `matches` before they enter the TABLE. The +approved rows are the TABLE handed to the onboarder, verbatim. + +S6 — EXECUTE. `mcp__model-router__route(phase="orchestrate")` with the +dispatch: `Agent(subagent_type="onboarder")`, prompt = `MODE: split`, +`PROJECT_ROOT: `, `TABLE:` the approved rows, one per line as +` | | ` (LRN-126: every field crosses the +prompt). It pre-flights every row, then extracts, writes the pointer +section, secures the gitignore negation, runs `check`, commits (message +per the project's commit convention), and verifies every rule is in +`HEAD`. Two STOP shapes come back: +- `STOP: — (rollback done, nothing committed)`: the tree is + back to the branch tip; fix the row, re-dispatch the WHOLE table. +- `STOP: not in HEAD after commit (commit kept)`: never + re-dispatch (the headings are gone from CLAUDE.md); show the user the + hash and `git -C show --stat `, the user decides. + +S7 — AFTER. `claude -p "/context"` again from ``; append to that +project's `.claude/memory/journal.md` under today's date: `CLAUDE.md +split: sections → .claude/rules/ (), always-on → +`. Tell the user the proof step: a fresh session in that project +that Reads one file per rule, then `jq -c 'select(.memory_type=="Project" +and (.file_path|contains("/.claude/rules/")))' +~/.claude/logs/instructions-loaded.jsonl | tail`. Never `finish`: the +merge is the user's signal. + +FINAL OUTPUT: +``` +SPLIT COMPLETE: +RULES : files under .claude/rules/ () +CLAUDE.md: → +CONTEXT : → (Memory files) +BRANCH : chore/claude-md-split () — merge on your signal +PROOF : pending — fresh session + the jq filter above +```