Centralize agent instructions in SPEC - #4912
Conversation
Move the full coding-agent contract and repository guidance from `AGENTS.md` into `SPEC.md`, and reduce `AGENTS.md` to a simple pointer to the canonical instructions. Add lightweight `CLAUDE.md`, `GEMINI.md`, and `.github/copilot-instructions.md` files so different assistants consistently bootstrap through the same repo-specific guidance.
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughSummary by CodeRabbit
WalkthroughThe PR defines the project contract in ChangesAgent guidance and project contract
Estimated code review effort: 2 (Simple) | ~10 minutes Possibly related PRs
Suggested labels: Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ 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 |
coderabbitai
Bot
added
documentation
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@SPEC.md`:
- Line 15: Update the documentation edit rule near the prohibition on
docs/src/content/docs/code-reference/ so it applies only to generated subfolders
or explicitly permits hand-written pages such as architecture.mdx, while
preserving the instruction to avoid modifying generated content directly.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 4f6f22f4-4821-4c43-bb51-5ab1fdb3ae0b
📒 Files selected for processing (5)
.github/copilot-instructions.mdAGENTS.mdCLAUDE.mdGEMINI.mdSPEC.md
Narrowed rule ChrisTitusTech#3 to specify exact auto-generated subdirectories (tweaks/ and features/) rather than the entire code-reference/ directory, and clarified that other hand-written pages (e.g. architecture.mdx) may be edited directly.
![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: a85b26270b
ℹ️ About Codex in GitHub
Codex has been enabled to automatically 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 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
Drop the old `docs-old` Hugo ignore rules from `.gitignore`, reflecting that the archived docs build artifacts no longer need special handling there.
Add .env.local and .env.*.local patterns to prevent local environment files from being committed.
Update `SPEC.md` to run Pester in CI mode and tighten repository hygiene instructions around ignored files. The git guidance now points contributors to the actual `.gitignore` files and clarifies that `docs/public/` contains tracked static assets rather than generated output.
|
@coderabbitai is this ok now? |
|
Tip For best results, initiate chat on the files or code changes. 🧩 Analysis chain🏁 Script executed: #!/bin/bash
set -euo pipefail
printf '%s\n' '=== Relevant instruction files ==='
fd -a -t f '^(SPEC\.md|AGENTS\.md|CLAUDE\.md|GEMINI\.md|copilot-instructions\.md)$' . \
-E .git -E node_modules -E dist -E build | sort
printf '%s\n' '=== Current instruction file contents ==='
for file in AGENTS.md SPEC.md CLAUDE.md GEMINI.md .github/copilot-instructions.md; do
if [ -f "$file" ]; then
printf '\n--- %s ---\n' "$file"
cat -n "$file"
fi
done
printf '%s\n' '=== PR changed files ==='
gh pr view 4912 --repo ChrisTitusTech/winutil --json files \
--jq '.files[] | "\(.path): +\(.additions)/-\(.deletions)"'
printf '%s\n' '=== Open CodeRabbit review threads ==='
gh api graphql \
-F owner='ChrisTitusTech' \
-F name='winutil' \
-F number=4912 \
-f query='
query($owner: String!, $name: String!, $number: Int!) {
repository(owner: $owner, name: $name) {
pullRequest(number: $number) {
reviewThreads(first: 100) {
nodes {
isResolved
comments(first: 20) {
nodes { author { login } body path line originalLine }
}
}
}
}
}
}' \
--jq '.data.repository.pullRequest.reviewThreads.nodes[]
| select(.isResolved == false)
| select(any(.comments.nodes[]; .author.login == "coderabbitai"))
| .comments.nodes[]
| select(.author.login == "coderabbitai")
| {path, line, originalLine, body}'Length of output: 19886
I found no unresolved CodeRabbit review threads. You are interacting with an AI system. |
|
I like the idea of keeping the small compatibility files so every agent gets pointed in the right direction! The only change I’d make is keeping To me, they serve different purposes:
So I’d keep the flow basically:
That keeps the responsibilities pretty clear. |
Move repository working instructions into `AGENTS.md` and refocus `SPEC.md` on the stable WinUtil project contract. This separates agent-specific guidance from architecture, build, runtime, docs, testing, and release details so both documents have clearer ownership.
|
@mewclouds ok i change that. let me no if this is better |
There was a problem hiding this comment.
Actionable comments posted: 2
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
SPEC.md (1)
11-18: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick winState the exact supported PowerShell runtime.
Replace
Windows PowerShell / PowerShellwith the supported edition/version contract, such as Windows PowerShell 5.1, PowerShell 7.x, or both. The code callspowershell.exe, uses WPF UI features, installs/loads PowerShell 7 separately, and depends on Pester/Script Analyzer behavior.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@SPEC.md` around lines 11 - 18, Update the Stack section’s Language entry to explicitly state the supported PowerShell edition and version contract, replacing the ambiguous “Windows PowerShell / PowerShell” wording. Align it with the runtime invoked by powershell.exe, WPF requirements, and separately installed PowerShell 7 dependencies; leave the other stack entries unchanged.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@AGENTS.md`:
- Around line 32-35: Update the Pester installation instructions in AGENTS.md to
remove -SkipPublisherCheck from the default Install-Module command; only retain
it if the documentation also specifies an explicit package-signature or
integrity verification step.
- Around line 41-43: Update the Script Analyzer command documented in AGENTS.md
to exclude the generated root winutil.ps1 file, either with an explicit file
filter or by limiting scanning to the source directories scripts, functions,
config, and tools; preserve recursive analysis and the existing project
settings.
---
Outside diff comments:
In `@SPEC.md`:
- Around line 11-18: Update the Stack section’s Language entry to explicitly
state the supported PowerShell edition and version contract, replacing the
ambiguous “Windows PowerShell / PowerShell” wording. Align it with the runtime
invoked by powershell.exe, WPF requirements, and separately installed PowerShell
7 dependencies; leave the other stack entries unchanged.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 633f9b64-1e75-4356-bd90-744a4eb18b52
📒 Files selected for processing (2)
AGENTS.mdSPEC.md
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 8458792e5e
ℹ️ About Codex in GitHub
Codex has been enabled to automatically 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 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
Expand AGENTS.md with context on why -SkipPublisherCheck is needed for Pester installation, why winutil.ps1 should be deleted before running ScriptAnalyzer, and clarify that the source-of-truth rule applies only to compiled-script behavior — repository metadata files are edited directly.
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@AGENTS.md`:
- Around line 32-35: Update the Pester installation instructions in AGENTS.md to
avoid making -SkipPublisherCheck the default behavior: remove that switch from
the standard Install-Module command, or add explicit trusted-source and package
signature/hash verification steps before using it. Preserve the pinned Pester
5.8.0 installation guidance.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
Expands the explanation for why -SkipPublisherCheck is needed (catalog-signed vs Authenticode-signed), clarifies it does not skip download integrity, and adds -Repository PSGallery to pin the trusted source explicitly.
mewclouds
left a comment
mewclouds
left a comment
There was a problem hiding this comment.
Thanks for the changes. Well done as usual 😄
3 participants
Type of Change
Description
This pull request updates the repository’s agent and contributor instructions for clarity, accuracy, and maintainability, and introduces dedicated instruction files for coding agents (Claude, Gemini, Copilot). The most important changes are summarized below. Also updated all reference from hugo to astro.
Major improvements to agent instructions and repo guidance:
AGENTS.md:SPEC.md) and agent operating instructions, with repeated references toSPEC.mdfor architecture, build, and config details.SPEC.mdfor details.SPEC.md.Addition of agent-specific instruction files:
CLAUDE.md,GEMINI.md, and.github/copilot-instructions.mdfiles, each directing coding agents to readAGENTS.mdfor operating instructions before proceeding. [1] [2] [3]Project contract and repo structure clarification:
SPEC.md:AGENTS.mdcovers agent behavior and points here for project facts.These changes ensure all contributors and coding agents follow the correct workflow, operate only on source files, and keep documentation and generated artifacts in sync with the project’s architecture and process.
Issue related to PR