chore: add worktree setup template + sync CHANGELOG#163
Conversation
Summary of ChangesHello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request introduces a valuable resource for developers by providing a comprehensive template for configuring persistent multi-agent worktree environments. This template streamlines the setup process for AI agents like Claude and Codex, ensuring consistency and adherence to architectural constraints. Additionally, the project's changelog has been synchronized to reflect this new addition, improving documentation. Highlights
Changelog
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
|
Caution Review failedPull request was closed or merged during review 📝 WalkthroughWalkthroughThis PR adds documentation for setting up a persistent multi-agent worktree environment, including agent role definitions, repository architecture constraints, and per-worktree configuration specifications. A changelog entry documents the new template resource. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes 🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: f2eb0cac54
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| path="$worktrees_dir/$name" | ||
| b=$(git -C "$path" rev-parse --abbrev-ref HEAD) | ||
| printf "%s | %s | %s\n" "$name" "${status[$name]}" "$path" | ||
| printf " AGENTS.md: %s\n" "$( [[ -f \"$path/AGENTS.md\" ]] && echo exists || echo missing )" |
There was a problem hiding this comment.
The file checks in the summary always evaluate to missing because " is used inside a command substitution that is already within double quotes, so the backslashes become part of the [[ -f ... ]] expression and the tested path includes literal quote characters. Running the generated setup-worktrees.sh shows AGENTS.md, CLAUDE.md, and .codex/agent.md as missing even when they were created, which breaks the script’s verification output and can cause false failure triage.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Pull request overview
Adds a new reference template under tooling/templates/ describing how to set up persistent multi-agent git worktrees (including a sample setup-worktrees.sh), and updates the root changelog to record the addition.
Changes:
- Added
tooling/templates/persistent-agent-worktree-setup.md(worktree setup template + embedded bash script). - Updated
CHANGELOG.mdto include the new template under [Unreleased] → Added.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 7 comments.
| File | Description |
|---|---|
| tooling/templates/persistent-agent-worktree-setup.md | New worktree setup template + sample script for generating per-worktree instruction files. |
| CHANGELOG.md | Documents the new template in the Unreleased “Added” section. |
| - Layer 1: Schema generation | ||
| - `eng/build/SchemaGenerator.cs` | ||
| - Layer 2: Roslyn source generator | ||
| - `src/qyl.servicedefaults.generator/` | ||
| - Layer 3: Runtime instrumentation | ||
| - `src/qyl.servicedefaults/` | ||
| - `src/qyl.collector/` | ||
|
|
||
| Layers must never be conflated. | ||
|
|
||
| ## Agent roles | ||
|
|
||
| `agent-collector` | ||
| - Role: OTLP collector maintainer | ||
| - Scope: `src/qyl.collector` | ||
| - Focus: OTLP ingestion, DuckDB batching, SSE streaming lifecycle | ||
| - Rules: minimal diffs; never modify generators or schema code |
There was a problem hiding this comment.
The “Architecture constraints” section references eng/build/SchemaGenerator.cs and src/qyl.* paths that do not exist in this repository. This makes the template inaccurate for users running it here; either generalize these constraints, or explicitly label this template as intended for a different repo layout and replace the paths with placeholders.
| - Layer 1: Schema generation | |
| - `eng/build/SchemaGenerator.cs` | |
| - Layer 2: Roslyn source generator | |
| - `src/qyl.servicedefaults.generator/` | |
| - Layer 3: Runtime instrumentation | |
| - `src/qyl.servicedefaults/` | |
| - `src/qyl.collector/` | |
| Layers must never be conflated. | |
| ## Agent roles | |
| `agent-collector` | |
| - Role: OTLP collector maintainer | |
| - Scope: `src/qyl.collector` | |
| - Focus: OTLP ingestion, DuckDB batching, SSE streaming lifecycle | |
| - Rules: minimal diffs; never modify generators or schema code | |
| This template assumes a three-layer architecture for telemetry-related code. Adapt the concrete paths and modules to match your repository layout. | |
| - Layer 1: Schema generation (build-time schema tools) | |
| - Layer 2: Source generator(s) (compile-time code generation) | |
| - Layer 3: Runtime instrumentation and collector services | |
| Layers must never be conflated: schema tools, generators, and runtime code live in separate modules or directories. | |
| ## Agent roles | |
| `agent-collector` | |
| `agent-collector` | |
| - Role: OTLP collector maintainer | |
| - Scope: Runtime collector / ingestion layer (e.g., your `collector` service or equivalent path) | |
| - Focus: OTLP ingestion, batching/persistence, streaming lifecycle | |
| - Rules: minimal diffs; never modify generator or schema layers |
|
|
||
| ## Execution rules | ||
|
|
||
| - Use only `bash`, `git`, and filesystem operations. |
There was a problem hiding this comment.
Execution rules say “Use only bash, git, and filesystem operations”, but the script relies on awk for parsing git worktree list --porcelain. Either allow awk explicitly in the rules, or rewrite the parsing to pure bash/git so the template is self-consistent.
| - Use only `bash`, `git`, and filesystem operations. | |
| - Use only `bash`, `git`, `awk`, and filesystem operations. |
| role_contents_common='\ | ||
| ## Repository architecture constraints | ||
|
|
||
| Layer 1: Schema generation | ||
| - `eng/build/SchemaGenerator.cs` | ||
| - NUKE build emits models, enums, scalars, and DuckDB DDL | ||
|
|
||
| Layer 2: Roslyn source generator | ||
| - `src/qyl.servicedefaults.generator/` | ||
| - 7 incremental pipelines that emit compile-time interceptors | ||
|
|
||
| Layer 3: Runtime instrumentation | ||
| - `src/qyl.servicedefaults/` | ||
| - `src/qyl.collector/` | ||
|
|
||
| Layers must never be conflated. | ||
| ' |
There was a problem hiding this comment.
role_contents_common is assigned as a multi-line single-quoted string that begins with a literal \ character (role_contents_common='\ …). That leading backslash will be written into every generated AGENTS.md and appears unintentional; remove it or switch to a heredoc-style assignment to avoid stray characters.
| cat > "$path/AGENTS.md" <<EOF_AGENTS | ||
| # AGENTS.md for $role | ||
|
|
||
| ${role_contents_common} | ||
|
|
||
| $(get_agent_section "$role") | ||
|
|
||
| ## Required verification | ||
| - dotnet build | ||
| - dotnet test | ||
| EOF_AGENTS | ||
|
|
||
| mkdir -p "$path/.codex" | ||
| printf 'Read and follow AGENTS.md in this worktree.\n' > "$path/CLAUDE.md" | ||
| printf 'Read and follow AGENTS.md in this worktree.\n' > "$path/.codex/agent.md" | ||
| } |
There was a problem hiding this comment.
The script overwrites AGENTS.md and CLAUDE.md in each worktree with minimal content. In this repository, CLAUDE.md/AGENTS.md are human-maintained and contain critical operational instructions, so following this template here would erase them on the worktree/* branches; consider writing to repo-specific filenames (e.g., WORKTREE_AGENTS.md) or appending a role section instead of replacing the files.
| mkdir -p "$worktrees_dir" | ||
| declare -A status | ||
|
|
There was a problem hiding this comment.
This template script uses declare -A status, which requires Bash 4+. On macOS (default /bin/bash is often 3.2), this will fail even though the template targets generic “bash”; consider avoiding associative arrays or explicitly documenting the required bash version.
|
|
||
| ### Added | ||
|
|
||
| - **`tooling/templates/persistent-agent-worktree-setup.md`**: Added a reusable prompt template for role-based Claude/Codex worktree setup with `AGENTS.md` as the single source of truth and thin `CLAUDE.md`/`.codex/agent.md` pointer files |
There was a problem hiding this comment.
The new changelog entry is a single very long line (likely >120 chars), which will trip markdownlint MD013 in this repo’s configuration. Please wrap it across multiple lines (e.g., break after the colon and indent continuation lines) to keep lint output clean.
| - **`tooling/templates/persistent-agent-worktree-setup.md`**: Added a reusable prompt template for role-based Claude/Codex worktree setup with `AGENTS.md` as the single source of truth and thin `CLAUDE.md`/`.codex/agent.md` pointer files | |
| - **`tooling/templates/persistent-agent-worktree-setup.md`**: | |
| Added a reusable prompt template for role-based Claude/Codex worktree | |
| setup with `AGENTS.md` as the single source of truth and thin | |
| `CLAUDE.md`/`.codex/agent.md` pointer files |
|
|
||
| ### Added | ||
|
|
||
| - **`tooling/templates/persistent-agent-worktree-setup.md`**: Added a reusable prompt template for role-based Claude/Codex worktree setup with `AGENTS.md` as the single source of truth and thin `CLAUDE.md`/`.codex/agent.md` pointer files |
There was a problem hiding this comment.
The changelog entry describes AGENTS.md as the single source of truth with thin CLAUDE.md pointers, but in this repository CLAUDE.md is the authoritative, auto-loaded instruction set and is explicitly human-maintained. Consider clarifying in the entry (and/or template) that this worktree setup is intended for other repos, or adjust the template so it doesn’t conflict with this repo’s established instruction model.
| - **`tooling/templates/persistent-agent-worktree-setup.md`**: Added a reusable prompt template for role-based Claude/Codex worktree setup with `AGENTS.md` as the single source of truth and thin `CLAUDE.md`/`.codex/agent.md` pointer files | |
| - **`tooling/templates/persistent-agent-worktree-setup.md`**: Added a reusable prompt template (for downstream repos) for role-based Claude/Codex worktree setup with `AGENTS.md` as the single source of truth and thin `CLAUDE.md`/`.codex/agent.md` pointer files; in this repository, `CLAUDE.md` remains the authoritative, auto-loaded instruction set |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces a new template for setting up a multi-agent worktree environment and updates the CHANGELOG accordingly. The template includes a comprehensive bash script to automate the process. My review focuses on the new script, where I've identified a correctness bug in the final summary report and a portability issue with the use of non-standard awk features. I've provided suggestions to fix these issues to improve the script's reliability and compatibility across different systems.
Note: Security Review has been skipped due to the limited scope of the PR.
| printf " AGENTS.md: %s\n" "$( [[ -f \"$path/AGENTS.md\" ]] && echo exists || echo missing )" | ||
| printf " CLAUDE.md: %s\n" "$( [[ -f \"$path/CLAUDE.md\" ]] && echo exists || echo missing )" | ||
| printf " .codex/agent.md: %s\n" "$( [[ -f \"$path/.codex/agent.md\" ]] && echo exists || echo missing )" |
There was a problem hiding this comment.
The file existence checks in the summary section are incorrect. The escaped quotes \" in [[ -f \"$path/...\" ]] cause the test to look for a file path that literally contains double quotes, which will always fail. This results in the script incorrectly reporting that files are missing even when they exist. The backslashes should be removed to correctly test the file paths.
| printf " AGENTS.md: %s\n" "$( [[ -f \"$path/AGENTS.md\" ]] && echo exists || echo missing )" | |
| printf " CLAUDE.md: %s\n" "$( [[ -f \"$path/CLAUDE.md\" ]] && echo exists || echo missing )" | |
| printf " .codex/agent.md: %s\n" "$( [[ -f \"$path/.codex/agent.md\" ]] && echo exists || echo missing )" | |
| printf " AGENTS.md: %s\n" "$( [[ -f \"$path/AGENTS.md\" ]] && echo exists || echo missing )"\n printf " CLAUDE.md: %s\n" "$( [[ -f \"$path/CLAUDE.md\" ]] && echo exists || echo missing )"\n printf " .codex/agent.md: %s\n" "$( [[ -f \"$path/.codex/agent.md\" ]] && echo exists || echo missing )" |
| git worktree list --porcelain | awk -v target="$target" ' | ||
| $1 == "worktree" {path = $2} | ||
| path == target {found = 1} | ||
| END {exit found ? 0 : 1} |
There was a problem hiding this comment.
The awk script uses the ternary operator ? :. This is a GNU awk (gawk) extension and is not portable to other awk implementations, such as the default one on macOS. To ensure the script runs correctly on different systems, it's best to use a standard if/else construct.
| END {exit found ? 0 : 1} | |
| END {if (found) exit 0; else exit 1} |
|
|
||
| if git worktree list --porcelain | awk -v branch="refs/heads/$branch" ' | ||
| $1 == "branch" && $2 == branch {found = 1} | ||
| END {exit found ? 0 : 1} |
There was a problem hiding this comment.
Similar to the other awk command in this script, the use of the ternary operator ? : here is a non-portable GNU awk extension. It should be replaced with a standard if/else to ensure compatibility with other awk implementations.
| END {exit found ? 0 : 1} | |
| END {if (found) exit 0; else exit 1} |
Adds
tooling/templates/persistent-agent-worktree-setup.mdas a reference template for persistent multi-agent worktree setups. Syncs local CHANGELOG edits.Summary by CodeRabbit
Documentation
Chores