diff --git a/.claude/skills/pr-review/SKILL.md b/.claude/skills/pr-review/SKILL.md index 7e3bd642a..c1a64523c 100644 --- a/.claude/skills/pr-review/SKILL.md +++ b/.claude/skills/pr-review/SKILL.md @@ -63,23 +63,44 @@ If the diff is empty, report "No changes to review" and stop. Three-dot diff with pathspec exclusions is unreliable. Instead, either: 1. Use `git diff main...` (full diff) and filter in the prompt, or -2. Read source files directly from the branch: - `git show origin/:` +2. Read source files directly from the branch worktree (see below). For large diffs (>1000 lines of source), provide **source files** rather than -raw diff to reviewers — cleaner context, better reviews. Read files with -`git show origin/:` and include them in the prompt. +raw diff to reviewers — cleaner context, better reviews. -**IMPORTANT — agent tool access:** Not all reviewer agents have Bash access. -Agents that CAN read from branches themselves: **Hoshe, Tyre, Araminta**. -Agents that CANNOT (no Bash tool): **Paula, Miri, Ozzie, Gestalt, Gore, Nigel**. +**IMPORTANT — use worktree paths for ALL agents.** This project uses git +worktrees. Each team branch is checked out at: -For agents without Bash, you MUST read the source files yourself (via -`git show origin/:`) and **paste the file contents directly -into the agent prompt**. Do not tell these agents to read files — they can't. -For very large PRs, read the key files (new/heavily modified) and include -summaries or excerpts of minor changes. Also read and include the relevant -`decisions/*.md` files these agents need for context. +``` +/var/home/jeroenschweitzer/Projects/settled-reach// +``` + +For example, the `copy` branch lives at: +``` +/var/home/jeroenschweitzer/Projects/settled-reach/copy/content/dialogue/... +``` + +**All reviewer agents** (regardless of Bash access) should read source files +from the worktree path using the Read tool. This is more reliable than +`git show origin/:` because: +- All agents have Read access (no Bash dependency) +- Files are always the actual branch checkout (no stale cache) +- No risk of accidentally reading from main's working directory + +When constructing reviewer prompts, tell agents to read files from the +worktree path. Example instruction for agents: + +``` +Read the changed files from the branch worktree. The branch is checked +out at: /var/home/jeroenschweitzer/Projects/settled-reach// + +For example, to read `content/dialogue/the-terminal/kael-davan.yaml`, +use: /var/home/jeroenschweitzer/Projects/settled-reach//content/dialogue/the-terminal/kael-davan.yaml +``` + +Also tell agents to read relevant `decisions/*.md` files from the same +worktree (they're identical to main, but using the worktree path keeps +agents grounded in the correct directory). ### 4. Spawn reviewers in parallel diff --git a/.claude/skills/pr-review/references/reviewer-profiles.md b/.claude/skills/pr-review/references/reviewer-profiles.md index 21622ca0c..701bbafba 100644 --- a/.claude/skills/pr-review/references/reviewer-profiles.md +++ b/.claude/skills/pr-review/references/reviewer-profiles.md @@ -2,11 +2,20 @@ Use `model: sonnet` for all reviewers — sufficient for review, saves cost. +**All agents read from worktree paths.** Each branch is checked out at: +`/var/home/jeroenschweitzer/Projects/settled-reach//` + +Tell every reviewer agent to read source files from the worktree using the +Read tool. Include the worktree base path and a list of changed files in +every prompt. Do NOT rely on `git show` or paste file contents — agents +can read directly from the worktree. + ## Code reviews (`server`, `client`, `ci`) **Hoshe (Code Quality)** - `subagent_type`: `hoshe`, `model`: `sonnet` -- Prompt: Include source code and commit log. Ask Hoshe to review for: +- Prompt: Provide the worktree path, list of changed files, and commit log. + Tell Hoshe to read source files from the worktree, then review for: - Correctness and bug risks - Error handling gaps - Test coverage (are new features tested?) @@ -16,44 +25,43 @@ Use `model: sonnet` for all reviewers — sufficient for review, saves cost. **Tyre (Architecture)** - `subagent_type`: `tyre`, `model`: `sonnet` -- Prompt: Include source code and commit log. Tell Tyre to read the relevant - `decisions/*.md` files first, then review for: +- Prompt: Provide the worktree path, list of changed files, and commit log. + Tell Tyre to read the relevant `decisions/*.md` files from the worktree + first, then review for: - Architectural consistency with project decisions - API/interface design quality - Dependency and coupling concerns - Scalability implications - Whether the change respects non-negotiable baselines (D-010, D-012) -- Tyre can read files directly from the branch using `git show origin/:` ## Copy reviews (`copy`) **Hoshe (QA)** - `subagent_type`: `hoshe`, `model`: `sonnet` -- Prompt: Include the changed files and commit log. Ask Hoshe to review for: +- Prompt: Provide the worktree path, list of changed files, and commit log. + Tell Hoshe to read the changed files from the worktree, then review for: - Formatting consistency (markdown, file naming, frontmatter) - Broken references or links - Spelling and grammar - File organization and structure - Missing or orphaned files -**Paula (Narrative Depth)** — NO BASH ACCESS +**Paula (Narrative Depth)** - `subagent_type`: `paula`, `model`: `sonnet` -- Paula cannot read from branches. You must paste file contents and decision - files directly into the prompt. -- Prompt: Include full text of changed files, commit log, and relevant - `decisions/*.md` content. Ask Paula to review for: +- Prompt: Provide the worktree path, list of changed files, commit log, and + list of relevant `decisions/*.md` files to read. Tell Paula to read all + files from the worktree using the Read tool, then review for: - Narrative quality and character voice consistency - Whether dialogue and monologue feel authentic to the characters - Consequences and stakes — do choices carry weight? - Political and interpersonal depth - Emotional resonance — does the text make you feel something? -**Miri (World Consistency)** — NO BASH ACCESS +**Miri (World Consistency)** - `subagent_type`: `miri`, `model`: `sonnet` -- Miri cannot read from branches. You must paste file contents and decision - files directly into the prompt. -- Prompt: Include full text of changed files, commit log, and relevant - `decisions/*.md` content. Ask Miri to review for: +- Prompt: Provide the worktree path, list of changed files, commit log, and + list of relevant `decisions/*.md` files to read. Tell Miri to read all + files from the worktree using the Read tool, then review for: - Lore accuracy — do facts match established setting? - Internal consistency across files - IP originality — nothing should read as a copy from another franchise @@ -64,16 +72,18 @@ Use `model: sonnet` for all reviewers — sufficient for review, saves cost. **Hoshe (QA)** - `subagent_type`: `hoshe`, `model`: `sonnet` -- Prompt: Include the changed files and commit log. Ask Hoshe to review for: +- Prompt: Provide the worktree path, list of changed files, and commit log. + Tell Hoshe to read the changed files from the worktree, then review for: - File format and naming conventions - Asset organization and directory structure - Missing or broken references in scene/resource files - Import settings consistency -**Araminta (Art Direction)** — HAS BASH ACCESS +**Araminta (Art Direction)** - `subagent_type`: `araminta`, `model`: `sonnet` -- Prompt: Include the changed files and commit log. Tell Araminta to read - the style guide and relevant design docs first, then review for: +- Prompt: Provide the worktree path, list of changed files, and commit log. + Tell Araminta to read the style guide and relevant design docs from the + worktree first, then review for: - Visual consistency with the established style guide - Color palette adherence - UI pattern consistency (diegetic-first, clarity over beauty) @@ -84,17 +94,17 @@ Use `model: sonnet` for all reviewers — sufficient for review, saves cost. **Hoshe (QA)** - `subagent_type`: `hoshe`, `model`: `sonnet` -- Prompt: Include the changed files and commit log. Ask Hoshe to review for: +- Prompt: Provide the worktree path, list of changed files, and commit log. + Tell Hoshe to read the changed files from the worktree, then review for: - File format and naming conventions - Audio asset organization and directory structure - Missing or broken references - Import/bus configuration consistency -**Ozzie (Player Experience)** — NO BASH ACCESS +**Ozzie (Player Experience)** - `subagent_type`: `ozzie`, `model`: `sonnet` -- Ozzie cannot read from branches. You must paste file contents directly - into the prompt. -- Prompt: Include full text of changed files and commit log. Ask Ozzie to +- Prompt: Provide the worktree path, list of changed files, and commit log. + Tell Ozzie to read all files from the worktree using the Read tool, then review for: - Emotional impact — does the audio enhance the moment? - Atmosphere and tone — does it feel like the Commonwealth?