chore: automate agent instruction mirroring #332
Conversation
- Move misc root markdown into docs/ - Fix critical action plan links - Add AGENTS key docs links - Convert agent mirror symlinks to regular files - Add repo-tracked hooks to re-hardlink after checkout/merge - Add docs CI diff check for mirror drift
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
ⓘ Your approaching your monthly quota for Qodo. Upgrade your plan PR Compliance Guide 🔍Below is a summary of compliance checks for this PR:
Compliance status legend🟢 - Fully Compliant🟡 - Partial Compliant 🔴 - Not Compliant ⚪ - Requires Further Human Verification 🏷️ - Compliance label |
||||||||||||||||||||||||
PR Compliance Guide 🔍Below is a summary of compliance checks for this PR:
Compliance status legend🟢 - Fully Compliant🟡 - Partial Compliant 🔴 - Not Compliant ⚪ - Requires Further Human Verification 🏷️ - Compliance label |
||||||||||||||||||||||||||||
ⓘ Your approaching your monthly quota for Qodo. Upgrade your plan PR Code Suggestions ✨Explore these optional code suggestions:
|
|||||||||||||||
PR Code Suggestions ✨Explore these optional code suggestions:
|
|||||||||||
|
| Severity | Issue | Location | Status |
|---|---|---|---|
| CRITICAL | CI diff handling breaks on file differences | .github/workflows/docs-ci.yml:46 |
Active |
| WARNING | Cross-platform hardlink failures (Windows/macOS) | scripts/ensure_agent_hardlinks.sh:23 |
Active |
| WARNING | Git hook output suppression hides errors | .githooks/post-checkout:8, .githooks/post-merge:8 |
Active |
| WARNING | Non-portable stat command (macOS/BSD) | scripts/ensure_agent_hardlinks.sh:26 |
Active |
| WARNING | chmod fails if expected files missing | scripts/install_git_hardlink_hooks.sh:19 |
Active |
| WARNING | core.hooksPath override breaks existing hooks | scripts/install_git_hardlink_hooks.sh:21 |
Active |
| WARNING | mise task hides all output including errors | mise.toml:46 |
Active |
| WARNING | CI error messages lack actionable guidance | .github/workflows/docs-ci.yml:45 |
Active |
Recommendation: Address critical CI issue and platform compatibility before merge
Review Details (19 files)
Files: Shell scripts, git hooks, CI workflows, documentation, build configs
Checked: Security, bugs, performance, error handling, cross-platform compatibility
Analysis Summary
This PR implements agent instruction mirroring automation using hardlinks and git hooks. While the overall design is sound and follows good practices, several critical issues prevent immediate merge.
What Works Well
✅ Robust Script Design:
- Proper bash safety flags (
set -euo pipefail) throughout - Comprehensive error handling and validation
- Clear error messages to stderr
- Well-structured shell script organization
✅ Good Integration:
- Tasks properly integrated into justfile and mise.toml
- CI validation added to catch mirror drift
- Documentation links fixed and updated consistently
- Follows established project patterns
✅ Automation:
- Git hooks ensure mirrors stay synced automatically
- CI validates mirrors match AGENTS.md
- Setup tasks handle initial bootstrap
Issues Found
🔴 CRITICAL (1 issue)
CI Diff Handling Breaks Build:
The diff command exits with status 1 when files differ, causing the entire CI job to fail without showing what changed. This prevents developers from seeing the actual differences and makes debugging difficult.
⚠️ WARNING (7 issues)
1. Cross-Platform Hardlink Failures:
Hardlinks dont work across filesystems, on Windows (without admin/developer mode), or some network filesystems. Script will silently fail on these platforms.
2. Git Hook Output Suppression:
Both post-checkout and post-merge hooks redirect all output to /dev/null, hiding critical error messages when hardlink creation fails.
3. Non-Portable stat Command:
stat -c is GNU-specific and fails on macOS/BSD systems where the flag is -f.
4. chmod File Existence Check:
chmod on missing files will cause script failure due to set -e. No validation before attempting to set permissions.
5. core.hooksPath Override:
Setting core.hooksPath globally without checking existing configuration may override other hook setups.
6. mise Task Output Suppression:
The prepare task redirects all output, making it impossible to debug failures during repository setup.
7. Unhelpful CI Error Messages:
CI validation fails without explaining what went wrong or how to fix it.
Confidence Assessment
Confidence: 95%
All issues are well-documented in active review comments. The implementation approach is correct, but execution details need refinement for cross-platform compatibility and better error handling.
Priority Actions
- Fix CI diff handling - Make it show differences without breaking the build
- Add cross-platform fallback - Copy files if hardlinking fails
- Improve error visibility - Redirect only stdout, keep stderr for errors
- Add platform detection - Use portable alternatives or conditional logic
There was a problem hiding this comment.
Pull request overview
This PR automates agent instruction mirroring by converting .github/copilot-instructions.md and .kilocode/rules/agents.md from symlinks to tracked files maintained as hardlinks to AGENTS.md. The automation includes git hooks to recreate hardlinks after checkout/merge and CI validation to prevent drift. Additionally, several documentation files are moved from the repository root into the docs/ directory with corresponding link updates throughout the codebase.
Key changes:
- Automated hardlink management via git hooks and setup scripts
- Documentation reorganization (research logs, plans, PR reports moved to docs/)
- Broken link fixes across multiple documentation files
- CI validation for agent instruction mirror synchronization
Reviewed changes
Copilot reviewed 15 out of 21 changed files in this pull request and generated 9 comments.
Show a summary per file
| File | Description |
|---|---|
scripts/ensure_agent_hardlinks.sh |
Script to create hardlinks from AGENTS.md to mirror locations |
scripts/install_git_hardlink_hooks.sh |
Script to configure git hooks for automatic hardlink maintenance |
.githooks/post-checkout, .githooks/post-merge |
Git hooks that recreate hardlinks after checkout/merge operations |
mise.toml |
Adds prepare task for repo bootstrap including hardlink setup |
justfile |
Adds commands for manual hardlink management and integrates into setup |
.github/workflows/docs-ci.yml |
Adds CI validation step to detect mirror drift |
.github/copilot-instructions.md, .kilocode/rules/agents.md |
Converted from symlinks to tracked copies of AGENTS.md |
docs/research/, docs/plans/ |
New homes for moved documentation files |
README.md, CLAUDE.md, AGENTS.md, docs/architecture.md, etc. |
Updated links to reflect moved documentation |
| # Show inode + link count for confirmation. | ||
| stat -c '%i %h %n' "$src" "$dst1" "$dst2" |
There was a problem hiding this comment.
The stat -c flag is GNU-specific and will fail on macOS/BSD systems where the flag is -f. This script should use portable alternatives or detect the OS.
Consider using ls -li which is portable across all Unix systems, or detect the platform and use the appropriate stat syntax.
| # Show inode + link count for confirmation. | |
| stat -c '%i %h %n' "$src" "$dst1" "$dst2" | |
| # Show inode + link count for confirmation (portable across Unix systems). | |
| ls -li "$src" "$dst1" "$dst2" |
| cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd | ||
| })" | ||
|
|
||
| "$repo_root/scripts/ensure_agent_hardlinks.sh" >/dev/null |
There was a problem hiding this comment.
The git hook redirects all output to /dev/null, which will hide error messages if the hardlink script fails. Users won't know why their hooks are failing. Consider redirecting only stdout (1>/dev/null) or capturing and logging errors to allow debugging while keeping the output quiet.
| "$repo_root/scripts/ensure_agent_hardlinks.sh" >/dev/null | |
| "$repo_root/scripts/ensure_agent_hardlinks.sh" 1>/dev/null |
| # Replace destination files with hard links to AGENTS.md. | ||
| # This is safe even if Git doesn't preserve hardlinks across clones: rerun anytime. | ||
| ln -f "$src" "$dst1" | ||
| ln -f "$src" "$dst2" |
There was a problem hiding this comment.
Hard links have limitations across filesystems and platforms. They don't work across different filesystems or on some network filesystems (like NFS). Windows has different requirements for hardlinks (requires admin or developer mode). Consider documenting these limitations in the PR description or README, or adding a fallback mechanism that copies files if hardlinking fails.
| # Replace destination files with hard links to AGENTS.md. | |
| # This is safe even if Git doesn't preserve hardlinks across clones: rerun anytime. | |
| ln -f "$src" "$dst1" | |
| ln -f "$src" "$dst2" | |
| # Replace destination files with hard links to AGENTS.md when possible. | |
| # If hardlinking fails (for example across filesystems), fall back to copying. | |
| if ! ln -f "$src" "$dst1"; then | |
| cp -f "$src" "$dst1" | |
| fi | |
| if ! ln -f "$src" "$dst2"; then | |
| cp -f "$src" "$dst2" | |
| fi |
| - name: Validate agent instruction mirrors | ||
| run: | | ||
| diff -u AGENTS.md .github/copilot-instructions.md | ||
| diff -u AGENTS.md .kilocode/rules/agents.md |
There was a problem hiding this comment.
The CI check validates that mirror files match AGENTS.md using diff, but this happens after checkout. If someone forgets to run the hardlink script locally, the CI will catch it. However, the error message from diff won't be very helpful to developers who don't understand the hardlink system. Consider adding a comment or documentation in the workflow explaining what this check does and how to fix failures (run just link-agents or ./scripts/ensure_agent_hardlinks.sh).
| echo "error: missing $hooks_path (expected repo-tracked hooks)" >&2 | ||
| exit 1 | ||
| fi | ||
|
|
There was a problem hiding this comment.
The chmod command attempts to set execute permissions on three files at once. If any of these files don't exist, the command will fail and the script will exit due to set -e. Consider adding existence checks before chmod or making the command more resilient to missing files.
| missing_file=0 | |
| for path in "$hooks_path/post-checkout" "$hooks_path/post-merge" "$repo_root/scripts/ensure_agent_hardlinks.sh"; do | |
| if [[ ! -e "$path" ]]; then | |
| echo "error: expected file '$path' to exist" >&2 | |
| missing_file=1 | |
| fi | |
| done | |
| if (( missing_file )); then | |
| exit 1 | |
| fi |
| fi | ||
|
|
||
| chmod +x "$hooks_path/post-checkout" "$hooks_path/post-merge" "$repo_root/scripts/ensure_agent_hardlinks.sh" | ||
|
|
There was a problem hiding this comment.
Setting core.hooksPath globally for the repository will override any existing hooks setup the user might have. This could interfere with other tools or workflows that rely on git hooks. Consider documenting this behavior or checking if hooks are already configured.
| existing_hooks_path="$(git -C "$repo_root" config --get core.hooksPath || true)" | |
| if [[ -n "${existing_hooks_path:-}" && "$existing_hooks_path" != ".githooks" ]]; then | |
| echo "warning: overriding existing git core.hooksPath='$existing_hooks_path' with '.githooks'" >&2 | |
| fi |
| diff -u AGENTS.md .github/copilot-instructions.md | ||
| diff -u AGENTS.md .kilocode/rules/agents.md | ||
There was a problem hiding this comment.
The diff commands will fail and cause the CI job to fail if the files differ. However, diff exits with status 1 when files differ (which is the expected case when someone forgets to sync mirrors). Consider either adding || true to allow the step to complete and show the difference, or adding a more descriptive error message. Alternatively, use diff -q first to check, then show detailed diff only if they differ.
| diff -u AGENTS.md .github/copilot-instructions.md | |
| diff -u AGENTS.md .kilocode/rules/agents.md | |
| set +e | |
| DIFF_FAILED=0 | |
| diff -u AGENTS.md .github/copilot-instructions.md || DIFF_FAILED=1 | |
| diff -u AGENTS.md .kilocode/rules/agents.md || DIFF_FAILED=1 | |
| if [ "$DIFF_FAILED" -ne 0 ]; then | |
| echo "::error::Agent instruction mirrors are out of sync. Please update .github/copilot-instructions.md and .kilocode/rules/agents.md to match AGENTS.md." | |
| exit 1 | |
| fi |
| pre-commit install | ||
| # Enable repo-tracked git hooks and ensure AGENTS mirrors are hardlinked. | ||
| ./scripts/install_git_hardlink_hooks.sh >/dev/null |
There was a problem hiding this comment.
The prepare task redirects output to /dev/null (>/dev/null), which will hide both stdout and any error messages. This makes debugging failures difficult. Consider redirecting only stdout (1>/dev/null) or removing the redirection entirely to show progress and errors.
| ./scripts/install_git_hardlink_hooks.sh >/dev/null | |
| ./scripts/install_git_hardlink_hooks.sh 1>/dev/null |
| cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd | ||
| })" | ||
|
|
||
| "$repo_root/scripts/ensure_agent_hardlinks.sh" >/dev/null |
There was a problem hiding this comment.
The git hook redirects all output to /dev/null, which will hide error messages if the hardlink script fails. Users won't know why their hooks are failing. Consider redirecting only stdout (1>/dev/null) or capturing and logging errors to allow debugging while keeping the output quiet.
|
| Severity | Issue | Location | Status |
|---|---|---|---|
| CRITICAL | CI diff handling breaks on file differences | .github/workflows/docs-ci.yml:46 |
Active |
| WARNING | Cross-platform hardlink failures (Windows/macOS) | scripts/ensure_agent_hardlinks.sh:23 |
Active |
| WARNING | Git hook output suppression hides errors | .githooks/post-checkout:8, .githooks/post-merge:8 |
Active |
| WARNING | Non-portable stat command (macOS/BSD) | scripts/ensure_agent_hardlinks.sh:26 |
Active |
| WARNING | chmod fails if expected files missing | scripts/install_git_hardlink_hooks.sh:19 |
Active |
| WARNING | core.hooksPath override breaks existing hooks | scripts/install_git_hardlink_hooks.sh:21 |
Active |
| WARNING | mise task hides all output including errors | mise.toml:46 |
Active |
| WARNING | CI error messages lack actionable guidance | .github/workflows/docs-ci.yml:45 |
Active |
Recommendation: Address critical CI issue and platform compatibility before merge
Review Details (19 files)
Files: Shell scripts, git hooks, CI workflows, documentation, build configs
Checked: Security, bugs, performance, error handling, cross-platform compatibility
Analysis Summary
This PR implements agent instruction mirroring automation using hardlinks and git hooks. While the overall design is sound and follows good practices, several critical issues prevent immediate merge.
What Works Well
✅ Robust Script Design:
- Proper bash safety flags (
set -euo pipefail) throughout - Comprehensive error handling and validation
- Clear error messages to stderr
- Well-structured shell script organization
✅ Good Integration:
- Tasks properly integrated into justfile and mise.toml
- CI validation added to catch mirror drift
- Documentation links fixed and updated consistently
- Follows established project patterns
✅ Automation:
- Git hooks ensure mirrors stay synced automatically
- CI validates mirrors match AGENTS.md
- Setup tasks handle initial bootstrap
Issues Found
🔴 CRITICAL (1 issue)
CI Diff Handling Breaks Build:
The diff command exits with status 1 when files differ, causing the entire CI job to fail without showing what changed. This prevents developers from seeing the actual differences and makes debugging difficult.
⚠️ WARNING (7 issues)
1. Cross-Platform Hardlink Failures:
Hardlinks dont work across filesystems, on Windows (without admin/developer mode), or some network filesystems. Script will silently fail on these platforms.
2. Git Hook Output Suppression:
Both post-checkout and post-merge hooks redirect all output to /dev/null, hiding critical error messages when hardlink creation fails.
3. Non-Portable stat Command:
stat -c is GNU-specific and fails on macOS/BSD systems where the flag is -f.
4. chmod File Existence Check:
chmod on missing files will cause script failure due to set -e. No validation before attempting to set permissions.
5. core.hooksPath Override:
Setting core.hooksPath globally without checking existing configuration may override other hook setups.
6. mise Task Output Suppression:
The prepare task redirects all output, making it impossible to debug failures during repository setup.
7. Unhelpful CI Error Messages:
CI validation fails without explaining what went wrong or how to fix it.
Confidence Assessment
Confidence: 95%
All issues are well-documented in active review comments. The implementation approach is correct, but execution details need refinement for cross-platform compatibility and better error handling.
Priority Actions
- Fix CI diff handling - Make it show differences without breaking the build
- Add cross-platform fallback - Copy files if hardlinking fails
- Improve error visibility - Redirect only stdout, keep stderr for errors
- Add platform detection - Use portable alternatives or conditional logic
User description
This makes agent instruction mirroring automatic and keeps docs links coherent after recent file moves.
Changes:
Notes:
PR Type
Enhancement, Other
Description
Convert agent instruction symlinks to hardlinked regular files
Add git hooks to automatically recreate hardlinks after checkout/merge
Fix broken documentation links to critical action plan
Add CI validation to prevent agent instruction mirror drift
Update documentation references and add Key Docs section to AGENTS.md
Diagram Walkthrough
File Walkthrough
2 files
Create hardlinks from AGENTS.md to mirror locationsInstall git hooks to maintain hardlinks automatically6 files
Git hook to recreate hardlinks after checkoutGit hook to recreate hardlinks after mergeConvert symlink to hardlinked regular fileConvert symlink to hardlinked regular fileAdd tasks for agent hardlinks and setup automationAdd prepare task for repo bootstrap with hooks1 files
Add CI validation for agent instruction mirrors6 files
Fix critical action plan links and add Key Docs sectionUpdate critical action plan link to new locationUpdate critical action plan link and agent referenceUpdate critical action plan link to new locationUpdate reference from docs/agents.md to AGENTS.mdUpdate agent guidelines reference to AGENTS.md4 files