Context
The new Guided Review is great for orienting a reviewer through a big diff. But its section overviews are written by an agent that only sees the diff — it has no idea about my project's conventions, the vocabulary my team uses, or the design docs that explain why the code is shaped the way it is. I use a spec-driven workflow (GSD) whose docs carry exactly the "why this changeset exists / what it implies" context the guide is trying to reconstruct from scratch, and I'd love to point the guide at that context so the chapters speak my project's language instead of guessing.
Right now there's no way to do that. The guide methodology is the hardcoded GUIDE_REVIEW_PROMPT constant in packages/server/guide/guide-review.ts, and buildCommand only reads engine/model/effort knobs from config — there's no profile or skill hook. The source even calls this out next to composeGuideMarkerPrompt:
guide has no custom-profile concept, so there is no "replace the methodology" branch.
This is the one gap between guide and code review. #897 asked for exactly this on the review side and you shipped it in #955 — custom reviews as Agent Skills, SKILL.md read live from the global skill folders, becoming the review prompt. The guide just never got wired into that mechanism (review-skill-loader.ts / resolveRequestedReviewProfile have no guide equivalent).
Why CLAUDE.md isn't enough
The guide runs as a claude -p subprocess in the repo, so CLAUDE.md is loaded ambiently and the prompt does permit an optional skim of CLAUDE.md/AGENTS.md. But the guide prompt aggressively de-emphasizes it — "Do NOT explore the repository," "stop after a third exploratory tool call," research budget ~90% the diff itself. So project context only lands if it happens to already be in CLAUDE.md and the model decides a section's "why" depends on it. It's incidental, not something I can steer per-project at the doc I actually want.
Proposal
Extend the #955 custom-review-skill mechanism to Guided Review: a "Guide context" (or guide-skill) selector on the Agents tab, same source model as custom reviews (built-in / project / global SKILL.md).
One difference from review: a custom review fully replaces the default prompt. A custom guide should append, not replace, since guide output is schema-constrained. So the natural shape is:
GUIDE_REVIEW_PROMPT
+ <user's project context / guide instructions>
+ user message (diff + changed files)
i.e. keep the organizer methodology and the schema contract intact, and inject the user's context as an extra section the model must honor while chaptering. Concretely that's a small change in buildCommand: resolve a config.guideProfileId (or reuse the existing skill loader), read the SKILL.md body, and splice it in where GUIDE_REVIEW_PROMPT + "\n\n---\n\n" + userMessage is composed — mirroring the marker/codex/claude branches the review path already has.
That gives project-aware section overviews ("this follows our GSD phase-17 replication contract" instead of "this appears to change replication") without touching the coverage/schema guarantees.
Happy to take this myself and open a PR if you're open to it — the review side (#955) already established the whole pattern, so this is mostly plumbing an existing mechanism into the guide path.
Context
The new Guided Review is great for orienting a reviewer through a big diff. But its section overviews are written by an agent that only sees the diff — it has no idea about my project's conventions, the vocabulary my team uses, or the design docs that explain why the code is shaped the way it is. I use a spec-driven workflow (GSD) whose docs carry exactly the "why this changeset exists / what it implies" context the guide is trying to reconstruct from scratch, and I'd love to point the guide at that context so the chapters speak my project's language instead of guessing.
Right now there's no way to do that. The guide methodology is the hardcoded
GUIDE_REVIEW_PROMPTconstant inpackages/server/guide/guide-review.ts, andbuildCommandonly reads engine/model/effort knobs fromconfig— there's no profile or skill hook. The source even calls this out next tocomposeGuideMarkerPrompt:This is the one gap between guide and code review. #897 asked for exactly this on the review side and you shipped it in #955 — custom reviews as Agent Skills,
SKILL.mdread live from the global skill folders, becoming the review prompt. The guide just never got wired into that mechanism (review-skill-loader.ts/resolveRequestedReviewProfilehave no guide equivalent).Why CLAUDE.md isn't enough
The guide runs as a
claude -psubprocess in the repo, soCLAUDE.mdis loaded ambiently and the prompt does permit an optional skim ofCLAUDE.md/AGENTS.md. But the guide prompt aggressively de-emphasizes it — "Do NOT explore the repository," "stop after a third exploratory tool call," research budget ~90% the diff itself. So project context only lands if it happens to already be inCLAUDE.mdand the model decides a section's "why" depends on it. It's incidental, not something I can steer per-project at the doc I actually want.Proposal
Extend the #955 custom-review-skill mechanism to Guided Review: a "Guide context" (or guide-skill) selector on the Agents tab, same source model as custom reviews (built-in / project / global
SKILL.md).One difference from review: a custom review fully replaces the default prompt. A custom guide should append, not replace, since guide output is schema-constrained. So the natural shape is:
i.e. keep the organizer methodology and the schema contract intact, and inject the user's context as an extra section the model must honor while chaptering. Concretely that's a small change in
buildCommand: resolve aconfig.guideProfileId(or reuse the existing skill loader), read theSKILL.mdbody, and splice it in whereGUIDE_REVIEW_PROMPT + "\n\n---\n\n" + userMessageis composed — mirroring the marker/codex/claude branches the review path already has.That gives project-aware section overviews ("this follows our GSD phase-17 replication contract" instead of "this appears to change replication") without touching the coverage/schema guarantees.
Happy to take this myself and open a PR if you're open to it — the review side (#955) already established the whole pattern, so this is mostly plumbing an existing mechanism into the guide path.