From 1db3677b3006fc57a5cfb9fe7ba63b209b5c17f4 Mon Sep 17 00:00:00 2001 From: Jeroen Schweitzer Date: Wed, 4 Mar 2026 23:01:13 +0100 Subject: [PATCH] chore(meta): reframe worktree boundaries as team identity Replace worktree-centric language with team-centric framing across CLAUDE.md and skills. Agents now identify by $WORKTREE_TEAM env var instead of resolving git internals. This prevents agents from following .git pointers back to the main repo and crossing boundaries. - CLAUDE.md: rename section to "Team boundaries", reference $WORKTREE_TEAM - sprint-start: add TEAM BOUNDARY rule to agent spawn prompt - sprint-plan: replace "worktree-relative paths" with "relative paths only" - pr-review: replace "worktree" with "team directory", note cross-dir reading is a main-team privilege only Co-Authored-By: Claude Opus 4.6 --- .claude/skills/pr-review/SKILL.md | 18 +++---- .../pr-review/references/reviewer-profiles.md | 48 ++++++++++--------- .claude/skills/sprint-plan/SKILL.md | 11 ++--- .claude/skills/sprint-start/SKILL.md | 4 ++ CLAUDE.md | 13 ++--- 5 files changed, 51 insertions(+), 43 deletions(-) diff --git a/.claude/skills/pr-review/SKILL.md b/.claude/skills/pr-review/SKILL.md index c69a5c049..c0b9d9d74 100644 --- a/.claude/skills/pr-review/SKILL.md +++ b/.claude/skills/pr-review/SKILL.md @@ -63,35 +63,35 @@ 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 worktree (see below). +2. Read source files directly from the team directory (see below). For large diffs (>1000 lines of source), provide **source files** rather than raw diff to reviewers — cleaner context, better reviews. -**IMPORTANT — use worktree paths for ALL agents.** This project uses git -worktrees. Each team branch is checked out at: +**IMPORTANT — use team directory paths for ALL agents.** Each team branch +is checked out in its own directory at: ``` /var/mnt/data/projects/settled-reach// ``` -For example, the `copy` branch lives at: +For example, the `copy` team directory is at: ``` /var/mnt/data/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 +from the team directory 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: +team directory. Example instruction for agents: ``` -Read the changed files from the branch worktree. The branch is checked +Read the changed files from the team directory. The branch is checked out at: /var/mnt/data/projects/settled-reach// For example, to read `content/dialogue/the-terminal/kael-davan.yaml`, @@ -99,8 +99,8 @@ use: /var/mnt/data/projects/settled-reach//content/dialogue/the-terminal ``` 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). +directory (they're identical to main, but using the team directory path +keeps agents grounded in the correct location). ### 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 8f9773fce..4ece25389 100644 --- a/.claude/skills/pr-review/references/reviewer-profiles.md +++ b/.claude/skills/pr-review/references/reviewer-profiles.md @@ -2,20 +2,24 @@ Use `model: sonnet` for all reviewers — sufficient for review, saves cost. -**All agents read from worktree paths.** Each branch is checked out at: +**All reviewer agents read from team directories.** Each team branch is +checked out in its own directory at: `/var/mnt/data/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. +Tell every reviewer agent to read source files from the team directory +using the Read tool. Include the directory 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 directory. + +Note: cross-directory reading is only permitted for review agents spawned +from the `main` team. Team agents must stay within their own directory. ## Code reviews (`server`, `client`, `ci`) **Hoshe (Code Quality)** - `subagent_type`: `hoshe`, `model`: `sonnet` -- Prompt: Provide the worktree path, list of changed files, and commit log. - Tell Hoshe to read source files from the worktree, then review for: +- Prompt: Provide the team directory path, list of changed files, and commit log. + Tell Hoshe to read source files from the team directory, then review for: - Correctness and bug risks - Error handling gaps - Test coverage (are new features tested?) @@ -25,8 +29,8 @@ can read directly from the worktree. **Tyre (Architecture)** - `subagent_type`: `tyre`, `model`: `sonnet` -- Prompt: Provide the worktree path, list of changed files, and commit log. - Tell Tyre to read the relevant `decisions/*.md` files from the worktree +- Prompt: Provide the team directory path, list of changed files, and commit log. + Tell Tyre to read the relevant `decisions/*.md` files from the team directory first, then review for: - Architectural consistency with project decisions - API/interface design quality @@ -38,8 +42,8 @@ can read directly from the worktree. **Hoshe (QA)** - `subagent_type`: `hoshe`, `model`: `sonnet` -- 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: +- Prompt: Provide the team directory path, list of changed files, and commit log. + Tell Hoshe to read the changed files from the team directory, then review for: - Formatting consistency (markdown, file naming, frontmatter) - Broken references or links - Spelling and grammar @@ -48,9 +52,9 @@ can read directly from the worktree. **Paula (Narrative Depth)** - `subagent_type`: `paula`, `model`: `sonnet` -- Prompt: Provide the worktree path, list of changed files, commit log, and +- Prompt: Provide the team directory 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: + files from the team directory 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? @@ -59,9 +63,9 @@ can read directly from the worktree. **Miri (World Consistency)** - `subagent_type`: `miri`, `model`: `sonnet` -- Prompt: Provide the worktree path, list of changed files, commit log, and +- Prompt: Provide the team directory 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: + files from the team directory 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 @@ -72,8 +76,8 @@ can read directly from the worktree. **Hoshe (QA)** - `subagent_type`: `hoshe`, `model`: `sonnet` -- 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: +- Prompt: Provide the team directory path, list of changed files, and commit log. + Tell Hoshe to read the changed files from the team directory, then review for: - File format and naming conventions - Asset organization and directory structure - Missing or broken references in scene/resource files @@ -81,7 +85,7 @@ can read directly from the worktree. **Araminta (Art Direction)** - `subagent_type`: `araminta`, `model`: `sonnet` -- Prompt: Provide the worktree path, list of changed files, and commit log. +- Prompt: Provide the team directory 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 @@ -94,8 +98,8 @@ can read directly from the worktree. **Hoshe (QA)** - `subagent_type`: `hoshe`, `model`: `sonnet` -- 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: +- Prompt: Provide the team directory path, list of changed files, and commit log. + Tell Hoshe to read the changed files from the team directory, then review for: - File format and naming conventions - Audio asset organization and directory structure - Missing or broken references @@ -103,8 +107,8 @@ can read directly from the worktree. **Ozzie (Player Experience)** - `subagent_type`: `ozzie`, `model`: `sonnet` -- 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 +- Prompt: Provide the team directory path, list of changed files, and commit log. + Tell Ozzie to read all files from the team directory using the Read tool, then review for: - Emotional impact — does the audio enhance the moment? - Atmosphere and tone — does it feel like the Commonwealth? diff --git a/.claude/skills/sprint-plan/SKILL.md b/.claude/skills/sprint-plan/SKILL.md index ec0618a48..891e14358 100644 --- a/.claude/skills/sprint-plan/SKILL.md +++ b/.claude/skills/sprint-plan/SKILL.md @@ -124,13 +124,12 @@ Create `docs/sprints/sprint-N/` and write one file per team. Read the template at `references/briefing-template.md` in this skill directory for the exact file structure. -**IMPORTANT — worktree-relative paths:** This project uses git worktrees. -Each team branch is checked out in its own worktree, and each worktree -contains the full repo (`server/`, `client/`, `docs/`, etc.). All file -paths in briefings must be relative to the worktree/git root. Example: +**IMPORTANT — relative paths only:** Each team works in its own directory +containing the full repo (`server/`, `client/`, `docs/`, etc.). All file +paths in briefings must be relative to the working directory. Example: `server/src/bridge/types.rs`, not `/absolute/path/to/server/src/...` or -paths that navigate outside the git root (`../sibling-worktree/...`). -Agents must stay within the git root they are running in. +paths that navigate outside (`../sibling-dir/...`). +Agents must stay within their team's working directory. Key requirements per file: - **server.md**: Carry-overs, new tickets, dependency chain, key decisions, notes diff --git a/.claude/skills/sprint-start/SKILL.md b/.claude/skills/sprint-start/SKILL.md index 541ccd0ec..fe613cc54 100644 --- a/.claude/skills/sprint-start/SKILL.md +++ b/.claude/skills/sprint-start/SKILL.md @@ -289,6 +289,10 @@ Task( Branch: `{team}` RULES: + - TEAM BOUNDARY: Your team is `{team}` ($WORKTREE_TEAM). Stay + within the current working directory. Do NOT navigate to + parent or sibling directories. Do NOT follow .git pointers + to other directories. - GIT: Do NOT run any git commands (commit, push, pull, merge, checkout, branch, stash, tag, etc.). All git operations are handled by the team lead. diff --git a/CLAUDE.md b/CLAUDE.md index ae65dd053..7d92e3df6 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -27,14 +27,15 @@ See [docs/DEVOPS.md](docs/DEVOPS.md) for build, test, lint, and CI procedures. A ## Agent Instructions -### Worktree boundaries +### Team boundaries -This project uses **git worktrees** in a shared parent directory (`settled-reach/`). Each team branch (`server`, `client`, `copy`, `audio`, `visual`, `ci`) has its own worktree. The worktree root IS the git root. +**Your team identity is `$WORKTREE_TEAM`.** All work must stay within the current working directory. -- **All work must remain within the git root** unless explicitly instructed otherwise. -- All file paths are relative to the worktree root (e.g. `server/src/bridge/types.rs`). -- Do not navigate to or access sibling worktrees (`../client/`, `../copy/`, etc.) unless explicitly instructed. -- **Exception — stale git lock files:** Worktree index locks live in the shared `.git` directory (e.g. `main/.git/worktrees/copy/index.lock`). If a `git` command fails with `index.lock: File exists`, you may remove the lock file for **your own worktree only**. Never touch lock files belonging to other worktrees. +- All file paths are relative to the current working directory (e.g. `server/src/bridge/types.rs`). +- **Do NOT navigate to parent or sibling directories** (`../`, `../client/`, etc.) unless explicitly instructed. Do NOT use absolute paths to reach other team directories. +- **Do NOT write auto-memory files for other teams.** If `$WORKTREE_TEAM` is `server`, do not write to memory paths containing `client`, `main`, etc. +- For context: each team has its own directory via git worktrees, sharing a parent directory (`settled-reach/`). The `.git` file points to a shared git directory — do not follow it to determine your working root. +- **Exception — stale git lock files:** If a `git` command fails with `index.lock: File exists`, you may remove the lock file for **your own team only** (e.g. `main/.git/worktrees/$WORKTREE_TEAM/index.lock`). Never touch lock files belonging to other teams. ### Database