📝 Add prompts for GitHub Copilot #4
Conversation
📝 WalkthroughWalkthroughThis pull request adds a comprehensive set of documentation files to Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes
Poem
Pre-merge checks and finishing touches✅ Passed checks (2 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (2)
.github/copilot-instructions.md (1)
1-27: High-level guide is well-structured and comprehensive; clarify adapter contract density.The Architecture/Flow section effectively grounds readers in the codebase. However, Line 26 packs the entire adapter contract into one long sentence. Consider splitting into separate bullet points for better scannability:
Editor adapters must implement: `editor_can_open`, `editor_open <path>` AI adapters must implement: `ai_can_start`, `ai_start <path> [args...]` All adapters must: check tool availability (`command -v`), emit errors via `log_error`, never silently fail, avoid side effects outside target directory AI tools must use subshell: `(cd ...)`This maintains conciseness while improving clarity. Alternatively, defer detailed contract to
.github/instructions/editor.instructions.mdand.github/instructions/ai.instructions.mdwith a brief summary here..github/instructions/completions.instructions.md (1)
1-55: Completion instructions are thorough, shell-aware, and practical.The file responsibilities are clearly mapped to three shells (lines 20-25), and the implementation pattern (lines 26-34) provides a clean mental model: commands, flags, branches, adapters. The testing guidance (lines 35-55) is shell-specific and practical, with example commands for each shell's setup requirements.
One clarification: Line 22 mentions "requires bash-completion v2+" — this is correct for the sourcing method shown at line 41, but worth noting explicitly that v1 is not supported, as this may surprise users on older systems.
Consider adding a version compatibility note in the "File Responsibilities" section:
- **`completions/gtr.bash`** - Bash completion (requires bash-completion v2+; v1 not supported)This upfront notice prevents confusion when users with v1 (or no bash-completion) encounter sourcing failures.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (7)
.github/copilot-instructions.md(1 hunks).github/instructions/ai.instructions.md(1 hunks).github/instructions/completions.instructions.md(1 hunks).github/instructions/editor.instructions.md(1 hunks).github/instructions/lib.instructions.md(1 hunks).github/instructions/sh.instructions.md(1 hunks).github/instructions/testing.instructions.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
.github/copilot-instructions.md
[uncategorized] ~40-~40: The official name of this software platform is spelled with a capital “H”.
Context: ...Create "npm install". Full matrix: see .github/instructions/testing.instructions.md`. ...
(GITHUB)
🔍 Remote MCP Exa, Linear
Based on the gathered information, I now have sufficient context to provide a comprehensive review summary. Let me synthesize the findings:
Summary of Relevant Context for PR Review
GitHub Copilot Instructions Implementation
The PR introduces repository custom instructions files that give GitHub Copilot additional context on how to understand the project and how to build, test and validate its changes. Custom instructions are currently only supported for Copilot Chat in VS Code and Visual Studio, and the .github/copilot-instructions.md file is automatically read on every Copilot chat or agent request.
Documentation Structure and Best Practices
The PR follows industry best practices by creating structured documentation files:
-
.github/copilot-instructions.md: Serves as the centerpiece for Copilot, providing background and institutional knowledge for the team, including project architecture, runtime components, and adapter contracts. -
Adapter Pattern Instructions: The PR documents adapter contracts for both AI tools and editors with clear function interfaces (
ai_can_start(),ai_start()for AI adapters;editor_can_open(),editor_open()for editors), following a consistent pattern across the codebase. -
Shell Scripting Guidelines: The documentation consolidates conventions for bash, fish, and shell scripts, specifying startup behavior, function-scoped variables, naming conventions, error handling, portability constraints, and quoting rules.
Git Worktree Context
Git worktrees enable working with multiple branches in parallel by creating separate working directories for each branch, commonly used with commands like git worktree add <path> <branch> and git worktree remove <path>. The project appears to be a git-worktree management tool (git-worktree-runner), and the documentation in this PR provides critical guidance for contributors on how to properly implement and test adapters that integrate with this tooling.
Key Review Considerations
- Completeness: All documentation maintains consistency across editor, AI adapter, completions, library, shell scripting, and testing instructions
- Contributor Clarity: Manual testing procedures and adapter contracts are clearly defined to guide implementation
- Error Handling: Emphasis on explicit failure modes and proper logging using
log_errorwith actionable guidance,,
🔇 Additional comments (11)
.github/copilot-instructions.md (4)
30-40: Manual testing subset is actionable and well-chosen.The examples at lines 30-37 provide a lean, practical quick-start. The reference to the full matrix in
testing.instructions.md(line 40) is helpful for progressive disclosure.
42-48: Common changes section is a valuable quick-reference; instructions are clear and actionable.The "Add command," "Add adapter," and "Modify core" subsections provide enough detail without overwhelming new contributors. References to line ranges and specific files make implementation guidance concrete. Well-aligned with the decomposed instruction files.
50-59: Patterns, gotchas, and debugging sections are thorough and help prevent common pitfalls.The debugging examples (line 59) are practical and span scoped tracing, function inspection, and variable inspection. These will accelerate troubleshooting. The Patterns section (lines 50-56) correctly emphasizes quoting and
set -eguards, which are critical for shell safety.
69-82: Documentation structure mapping is clear and provides good navigation.The structure at lines 69-82 is well-organized, explicitly listing which instruction files apply to which file patterns. This cross-referencing helps maintainers and contributors know where to find relevant guidance. The inclusion of README.md and CONTRIBUTING.md in the map is helpful for orientation.
.github/instructions/sh.instructions.md (1)
1-47: Comprehensive shell scripting guidelines with pragmatic POSIX/macOS focus.The shell conventions are well-established and follow proven practices for maintainability and cross-platform compatibility. The emphasis on:
- Strict mode (
set -e) with explicit guards (line 23)- Bash 3.2+ compatibility (line 15, pragmatic for macOS users)
- Quoting discipline (lines 44-47)
- Minimal external dependencies (lines 39-42)
This is solid guidance that will prevent common shell pitfalls. The debugging section (lines 32-38) provides practical tools for troubleshooting, and the reference to
sanitize_branch_name(line 47) reinforces DRY principles.Please verify that
sanitize_branch_nameis defined in the codebase (referenced at line 47). If it exists, this guidance is properly grounded; if not, provide a pointer or reference..github/instructions/testing.instructions.md (1)
1-91: Manual testing matrix is exhaustive, practical, and well-organized.The testing instructions span basic flows, edge cases (branch sanitization, remote/local/new branches), configuration, hooks, and adapters. The examples are concrete and verifiable:
- Lines 10-58: Progressive flow from basic create/remove through advanced scenarios (--force, --name)
- Lines 61-67: Environment verification commands (git --version, doctor, adapter)
- Lines 69-74: Adapter sourcing checks with expected success/failure patterns
- Lines 85-91: Measurable success criteria (exit codes, no quoting errors, hook atomicity)
The emphasis on
list --porcelainfor scripting stability (line 90) is particularly valuable for automation. This manual-testing-only approach is pragmatic given the tool's reliance on git and file-system behavior..github/instructions/completions.instructions.md (2)
57-92: Branch completion logic and adapter updates are concrete and well-differentiated by shell.Lines 57-63 correctly reference the
gtr list --porcelainoutput (tab-separated: path, branch, status), aligning with testing.instructions.md. The adapter update examples (lines 65-82) show shell-specific patterns:
- Bash (lines 69-72): arrays and case statements
- Zsh (lines 74-77): _arguments and _values
- Fish (lines 79-82): complete -c with conditions
This differentiation demonstrates understanding of each shell's completion model.
84-115: Synchronization requirements are well-emphasized; common pitfalls are actionable.The "Keep in Sync" section (lines 84-91) and "Common Pitfalls" section (lines 109-115) hammer home the critical insight: three files must stay synchronized. Line 111 ("Forgetting to update all three files") is the #1 risk for maintainability, and calling it out explicitly is excellent.
The pitfall about hardcoding adapter names (line 112) correctly suggests keeping them in sync with actual files in
adapters/{editor,ai}/, which ties back to the adapter contract pattern..github/instructions/lib.instructions.md (1)
1-28: Core library guidelines strike a good balance between flexibility and safety.The three sections (Modifying Core, Key Functions, Change Guidelines) provide appropriate constraints:
- Backwards compatibility (line 9) is critical for a library
- Quoting discipline (line 10) and log_error/log_info usage (line 11) prevent data corruption and improve observability
- Git version fallbacks (line 12) show pragmatism for older repos
- Key functions (lines 14-20) provide a mental model without over-prescribing implementation
- Change guidelines (lines 22-28) correctly emphasize adapter contract preservation, config namespacing (gtr.), and performance for directory scans
The reference to
lib/core.sh:97-100for Git version fallback is a concrete anchor point that will help contributors find patterns to emulate..github/instructions/ai.instructions.md (1)
1-42: AI adapter contract is clear, practical, and well-symmetrical with editor adapters.The template (lines 11-27) demonstrates:
- Availability checking via
command -v(line 16)- Proper error handling with
log_error+ install guidance (line 23)- Subshell isolation for directory change (line 26):
(cd "$path" && tool-cli "$@")- Quote discipline throughout
The contract (lines 32-42) correctly specifies:
- Two functions:
ai_can_start(0 = available),ai_start <path> [args...]- Quote requirements for path and arguments
- Side effects confined to worktree (line 37) — critical for safety
- Extra args after
--preserved for extensibility (line 38)- Fast startup preference, heavy init in hooks (line 39) — pragmatic for UX
This mirrors the editor adapter pattern closely, which is good for consistency and contributor familiarity.
.github/instructions/editor.instructions.md (1)
1-45: Editor adapter contract is clean, well-differentiated from AI adapters, and focused.The template (lines 11-27) demonstrates:
- Availability checking via
command -v(line 16)- Error handling with
log_error+ install guidance (line 22)- No subshell for editor (line 25): editor-cli opens the path directly
- Contrast with AI adapters (ai.instructions.md:26 uses
(cd ...)) — correct differentiation since editors don't need directory isolationThe contract (lines 35-45) correctly specifies:
- Two functions:
editor_can_open,editor_open <path>- Quote and PWD constraints (line 38): no subshell needed
- Lean scope (line 40): no project scans or prompts
- Clear naming (line 41): file = tool name
- Fail-clear behavior (line 44): no silent deferral to file browser
The update requirements (lines 29-33) are comprehensive and mirror those in ai.instructions.md, ensuring consistency for both adapter types.
Summary by CodeRabbit