--- name: code-roadmap description: Orientation map for the start of a coding task. Reads your intent, matches it against the skills currently available in this session, and prints a recommended chain of skills plus a suggested execution mode and reflection level — as options with a WHY, never a forced path. Advisory only: it never launches a skill and never forces a choice. Triggers on "par où commencer", "quel skill pour X", "which skill", "how should I approach this", "route this", "roadmap", "what's the path for". NOT find-skills (that installs external skills), NOT setup-audit (that checks config health), NOT brainstorm (that does the research itself). argument-hint: "" allowed-tools: Bash --- # code-roadmap Orient at the start of a task: given an intent, print the most relevant chain of installed skills + a suggested execution mode + a suggested reflection level, as facts the user picks from. Then stop. ## HARD INVARIANTS - NEVER invoke a skill. This skill has no Skill tool on purpose — it orients, it does not execute. - NEVER force one executor. Present execution options with a WHY; the user picks. - ONLY SUGGEST the reflection/effort level (including ultracode). The user sets it; this skill cannot toggle effort. - For gaps, PROPOSE a creator or find-skills. Never build the skill here. - NEVER embed a fixed skill inventory. Read the live list every run. ## 1. Inventory = the live in-context list The skill inventory is the list the harness already injected into this session ("The following skills are available…", name + description each). Treat THAT as the single source of truth. Match the user's intent against those descriptions by SEMANTIC reasoning about the shape of the work — never substring grep (the word "review" must not blindly fire every skill with "review" in it). The description field is the routing signal; reason over it like a filter-then-pick. Because the inventory is read live, adding or removing a skill changes routing next session with zero edits here. There is no catalog to drift. ## 2. Optional freshness re-list (escape hatch, not the default) Run this ONLY when: the user says skills changed this session, an injected description was truncated mid-sentence, or project-local skills may exist. Otherwise skip it. ```bash for d in "$HOME"/.claude/skills/*/SKILL.md "$PWD"/.claude/skills/*/SKILL.md; do [ -f "$d" ] && awk -F': ' '/^name:/{n=$2} /^description:/{print n" — "substr($0,14,90); exit}' "$d"; done 2>/dev/null ``` Reconcile any result to the INJECTED display names (a skill's on-disk `name:` can differ from the harness display name). Use the scan only to detect added/removed skills, never to rename what you show the user. ## 3. Decompose intent into facets Parse the intent into 1-3 capability FACETS (predicates about the work, not skill names): - research — understand something external / explore options - planning — decide what/why or design the how before coding - execution — write or change code - quality — verify, review, harden, fix CI - code-intel — understand THIS repo's structure / impact / trace - creation — a needed capability does not exist yet - memory — persist or resume work across sessions - git — ship: commit / PR / merge For each active facet, pick the best-fitting skill by reading the injected descriptions. ## 4. Order the chain Assemble in the natural pipeline order: Context/research → Planning → Execution → Quality → Git. Memory is transversal (note it where a multi-session boundary appears). Index gate: code-intel skills that need a built index are eligible only if an index exists for this repo (check the project's CLAUDE.md GitNexus block or an index artifact on disk). If absent, prepend a note "index first (gitnexus-cli analyze)" instead of naming an index-dependent skill. ## 5. Two independent axes — suggest, never force Score the intent on 5 signals (0/1/2): S1 scope (files/lines), S2 independent surfaces (parallelisable units), S3 risk (blast radius), S4 ambiguity (valid designs / boundary-crossing), S5 repo unfamiliarity. REFLECTION (suggest one, driven by S4 → S3 → S5): | level | when | |-------|------| | trivial | S4=0 and S3≤1 — just do it | | standard | S4=1 or S5=1 | | deep | S4=2, or S3=2 with S4≥1 — design first (rfc if boundary-crossing, plan-mode if design settled + high risk, prd if the gap is a product spec) | | ultracode | when parallelising the thinking is worth it — only the USER can toggle this (effort menu); the skill ASKS, it cannot set it | EXECUTION (offer a MENU with WHY, driven by S2 → S1 → S3) — examples of the option set, choose from the live skills: | option | when | |--------|------| | direct edit | S1=0, S2=0, S3≤1 | | spec-driven exec (e.g. ship from a prd tasks.md / Accepted rfc) | a locked upstream spec already exists — execute it, don't re-spec | | structured impl (e.g. ship inline contract; +adversarial if S3≥1) | one feature-shaped change, no upstream spec | | multi-surface (e.g. ship, teams tier) | 2-3 independent surfaces | | test-first (e.g. tdd) | behaviour-critical / fragile | | refactor-scoped (e.g. clean-code) | cleanup, not new behaviour | | Agent Team | heterogeneous coordinating roles | The axes are independent: a hairy single-file algorithm = deep + solo; a mechanical 40-file codemod = trivial + fan-out. Present execution as options — never crown one as the default. ## 6. Harness modes are not skills ultracode (= effort xhigh + auto dynamic-workflow) and Agent Teams sit ABOVE the skill layer. Claude Code CANNOT change the effort level itself — exactly like high→max, only the user toggles it via the effort menu. So when a fan-out is warranted, do NOT emit a stray "set it yourself" note: ASK the user explicitly, e.g. "ce task justifie ultracode — active-le dans le menu effort (toi seul peux le faire), ou demande-moi de créer un workflow". Never present these as a skill to run, and never imply the skill/CC can flip the effort setting. ## 7. Gap protocol — when nothing installed fits the core task 1. Generic capability → propose `find-skills` (installing beats authoring). Bespoke / personal-ecosystem need → skip to building. 2. By output shape → propose the right creator: atomic single-file → skill-creator; phased with state → skill-workflow-creator; parallel merging roles → team-skill-creator; event-driven → hooks-creator; persona/subagent → agent-creator. Tie-break: parallel > phased > single-file. 3. PROPOSE only. This skill never authors the new skill and never does the underlying work. ## 8. Output contract Print, then STOP: ``` CHAÎNE CANONIQUE 1. — WHY (facet/signal) 2. — WHY ... RÉFLEXION (suggérée) : — WHY. (Si fan-out justifié : DEMANDE à l'utilisateur d'activer ultracode via le menu effort — CC ne peut pas le faire lui-même ; ou propose de créer un workflow.) EXÉCUTION (à toi de choisir) :