docs(contrib): add AGENTS.md and Copilot repository instructions#14
docs(contrib): add AGENTS.md and Copilot repository instructions#14
Conversation
- Add concise contributor guide (AGENTS.md) with structure, commands, style, testing, and PR rules - Add .github/copilot-instructions.md with repo-aware guidance referencing AGENTS.md and CLAUDE.md - Encourage TDD per CLAUDE.md; document task-run commands and safety practices
|
Note Other AI code review bot(s) detectedCodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review. WalkthroughTwo new documentation files, Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~2 minutes Poem
Note 🔌 MCP (Model Context Protocol) integration is now available in Early Access!Pro users can now connect to remote MCP servers under the Integrations page to get reviews and chat conversations that understand additional development context. 📜 Recent review detailsConfiguration used: CodeRabbit UI 📒 Files selected for processing (1)
🚧 Files skipped from review as they are similar to previous changes (1)
✨ Finishing Touches🧪 Generate unit tests
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. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
There was a problem hiding this comment.
Pull Request Overview
This PR adds comprehensive contributor documentation and GitHub Copilot integration guidelines to improve developer onboarding and tool alignment. The changes establish clear conventions for project structure, development workflow, and coding standards while providing AI assistance that's grounded in the project's TDD methodology and design principles.
Key changes:
- Adds AGENTS.md as a concise contributor quick-reference guide covering build commands, coding style, and PR workflow
- Introduces .github/copilot-instructions.md to align AI assistance with project conventions and encourage TDD practices
Reviewed Changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| AGENTS.md | Comprehensive contributor guide covering project structure, development commands, coding standards, and workflow guidelines |
| .github/copilot-instructions.md | GitHub Copilot configuration providing context-aware assistance aligned with project design and TDD methodology |
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
![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
🔭 Outside diff range comments (1)
AGENTS.md (1)
1-46: Missing.wtp.ymlin Tooling/Config SectionThe guide references a
.wtp.ymlin the “Tooling/config” list, but that file is not present in the repository. All other items verified successfully (module path, Go version, directory layout, Taskfile tasks,.golangci.ymlrules,testifydependency, andgetWorktreeNameFromPathhelper).• AGENTS.md (Tooling/config): remove the
.wtp.ymlentry or
add the missing.wtp.ymlto the repo, as intended for project hooks.
• No other discrepancies found.
🧹 Nitpick comments (6)
.github/copilot-instructions.md (3)
21-25: Tighten repetitive “Do/Don’t” phrasing in Domain RulesRemoves repetitive sentence starts and keeps guidance crisp without changing meaning.
## Domain Rules (Do/Don’t) -- Do preserve worktree naming rules: main is `@`; others are paths relative to `base_dir` (see `CLAUDE.md`). -- Do keep hooks safe and deterministic; stream output; filter env like `WTP_SHELL_INTEGRATION` where applicable. -- Do keep CLI UX consistent with README examples and autocompletion behavior. -- Don’t introduce breaking changes to path/name resolution without updating docs and tests. +- Preserve worktree naming rules: main is `@`; others are paths relative to `base_dir` (see `CLAUDE.md`). +- Keep hooks safe and deterministic; stream output; filter env like `WTP_SHELL_INTEGRATION` where applicable. +- Maintain CLI UX consistency with README examples and autocompletion behavior. +- Avoid introducing breaking changes to path/name resolution without updating docs and tests.
30-30: Strengthen wording (“deep” → “foundational or architectural”)Small clarity/style upgrade per LanguageTool hint.
-- Reference `AGENTS.md` for contributor workflow; deep design questions should cite `CLAUDE.md` sections. +- Reference `AGENTS.md` for contributor workflow; foundational or architectural design questions should cite `CLAUDE.md` sections.
27-31: Make “run dev before commit” explicit (aligns with team convention)Reflects the project learning to always run
go tool task devbefore committing.## Answering Guidelines - Prefer TDD: write/describe failing tests first, then minimal code, then refactor (see `CLAUDE.md`). - When proposing changes, include exact commands to build/test and mention affected files/paths. +- Before committing or submitting suggestions, run `go tool task dev` to ensure formatting, linting, and tests pass locally. - Reference `AGENTS.md` for contributor workflow; foundational or architectural design questions should cite `CLAUDE.md` sections.AGENTS.md (3)
18-18: Fix list indentation (markdownlint MD005/MD007)One bullet has an extra leading space; align with the rest.
- - Dev cycle: `go tool task dev` (runs fmt, lint, test). +- Dev cycle: `go tool task dev` (runs fmt, lint, test).
29-29: Clarify E2E framework pathUse the explicit path to reduce ambiguity for newcomers.
-- Unit tests live next to code; E2E scenarios under `test/e2e` (see `framework/`). +- Unit tests live next to code; E2E scenarios under `test/e2e` (see `test/e2e/framework/`).
33-39: Make CLI help/completion updates explicit in PR checklistCodifies a recurring expectation from team learnings.
## Commit & PR Guidelines - Conventional Commits: `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`, `style:` (see `git log`). - Branch naming: `feature/...`, `fix/...`, `hotfix/...` aligns with worktree paths. - Before opening a PR: format, lint, tests green, update docs if needed. +- When adding/changing commands, update CLI help text and shell completion (see `cmd/wtp/*.go`) and README examples. - PR description: what/why/how, testing notes, related issues (e.g., `Closes #123`). - Add CLI output or screenshots when UX changes.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
.github/copilot-instructions.md(1 hunks)AGENTS.md(1 hunks)
🧰 Additional context used
🧠 Learnings (7)
📓 Common learnings
Learnt from: CR
PR: satococoa/wtp#0
File: CLAUDE.md:0-0
Timestamp: 2025-07-24T14:15:20.744Z
Learning: Applies to README.md : Update README.md documentation and examples when adding new features.
Learnt from: CR
PR: satococoa/wtp#0
File: CLAUDE.md:0-0
Timestamp: 2025-07-24T14:15:20.744Z
Learning: Applies to docs/**/* : Update documentation for architectural changes.
📚 Learning: 2025-07-24T14:15:20.744Z
Learnt from: CR
PR: satococoa/wtp#0
File: CLAUDE.md:0-0
Timestamp: 2025-07-24T14:15:20.744Z
Learning: Before committing any changes, always run 'go tool task dev' to ensure code is formatted, linted, and tested.
Applied to files:
.github/copilot-instructions.mdAGENTS.md
📚 Learning: 2025-07-24T14:15:20.744Z
Learnt from: CR
PR: satococoa/wtp#0
File: CLAUDE.md:0-0
Timestamp: 2025-07-24T14:15:20.744Z
Learning: Applies to cmd/wtp/*.go : Update command help text when adding new features.
Applied to files:
.github/copilot-instructions.mdAGENTS.md
📚 Learning: 2025-07-24T14:15:20.744Z
Learnt from: CR
PR: satococoa/wtp#0
File: CLAUDE.md:0-0
Timestamp: 2025-07-24T14:15:20.744Z
Learning: Applies to README.md : Update README.md documentation and examples when adding new features.
Applied to files:
.github/copilot-instructions.mdAGENTS.md
📚 Learning: 2025-07-24T14:15:20.744Z
Learnt from: CR
PR: satococoa/wtp#0
File: CLAUDE.md:0-0
Timestamp: 2025-07-24T14:15:20.744Z
Learning: Applies to cmd/wtp/completion.go : The getWorktreeNameFromPath() function in cmd/wtp/completion.go must implement worktree naming logic: return '@' for main worktree, relative path from base_dir for non-main worktrees, and fall back to directory name if path calculation fails.
Applied to files:
.github/copilot-instructions.mdAGENTS.md
📚 Learning: 2025-07-24T14:15:20.744Z
Learnt from: CR
PR: satococoa/wtp#0
File: CLAUDE.md:0-0
Timestamp: 2025-07-24T14:15:20.744Z
Learning: Use Go as the implementation language for all core logic, not shell scripts.
Applied to files:
.github/copilot-instructions.md
📚 Learning: 2025-07-24T14:15:20.744Z
Learnt from: CR
PR: satococoa/wtp#0
File: CLAUDE.md:0-0
Timestamp: 2025-07-24T14:15:20.744Z
Learning: Applies to docs/**/* : Update documentation for architectural changes.
Applied to files:
AGENTS.md
🪛 LanguageTool
.github/copilot-instructions.md
[style] ~25-~25: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...examples and autocompletion behavior. - Don’t introduce breaking changes to path/n...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~30-~30: Consider a different adjective to strengthen your wording.
Context: ...e AGENTS.md for contributor workflow; deep design questions should cite `CLAUDE.md...
(DEEP_PROFOUND)
🪛 markdownlint-cli2 (0.17.2)
AGENTS.md
18-18: Inconsistent indentation for list items at the same level
Expected: 0; Actual: 1
(MD005, list-indent)
18-18: Unordered list indentation
Expected: 0; Actual: 1
(MD007, ul-indent)
🔇 Additional comments (3)
.github/copilot-instructions.md (2)
1-36: Well-scoped contributor guidanceClear, actionable, and consistent with repository conventions. Nice work.
1-36: Sanity Check Passed: All referenced tasks, files, and env hints exist
- Configuration files present:
- Taskfile.yml
- .golangci.yml
- CLAUDE.md
- AGENTS.md
- Taskfile.yml defines all tasks mentioned in the instructions:
- dev, build, test, lint, fmt, test-e2e, install
WTP_E2E_BINARYis referenced in:
- AGENTS.md (usage hint)
- test/e2e/framework/framework.go (env lookup)
- Taskfile.yml (override in test-e2e task)
- README.md is present at the repo root
- No Go files matching
*completion*.gowere found; if CLI autocompletion is supported, please confirm where it’s implemented or update the instructions accordingly.AGENTS.md (1)
1-46: Comprehensive and practical — great additionThis is a solid quick-start for contributors, aligned with TDD and repo conventions.
| # Repository Guidelines | ||
|
|
||
| ## Project Structure & Modules | ||
| - Root module: `github.com/satococoa/wtp` (Go 1.24). |
There was a problem hiding this comment.
💡 Verification agent
🧩 Analysis chain
Avoid hardcoding the Go version to prevent drift
Prefer reading the version from go.mod or phrasing it generically.
-- Root module: `github.com/satococoa/wtp` (Go 1.24).
+- Root module: `github.com/satococoa/wtp` (Go version per `go.mod`).If you want to keep an explicit version here, verify it matches go.mod:
🏁 Script executed:
#!/usr/bin/env bash
set -euo pipefail
awk '/^module /{print "module:",$2} /^go [0-9]/{print "go:",$2}' go.modLength of output: 137
Align Go version in AGENTS.md with go.mod
To avoid drift, reference the Go version directly from go.mod rather than hardcoding it. Update line 4 in AGENTS.md as follows:
- Root module: `github.com/satococoa/wtp` (Go 1.24).
+ Root module: `github.com/satococoa/wtp` (Go version per go.mod).You’ve verified that go.mod currently specifies Go 1.24.4:
$ awk '/^go /{print $2}' go.mod
1.24.4If you prefer an explicit version, you can instead write:
- Root module: `github.com/satococoa/wtp` (Go 1.24).
+ Root module: `github.com/satococoa/wtp` (Go 1.24.4).🤖 Prompt for AI Agents
In AGENTS.md at line 4, the Go version is hardcoded as 1.24, which can become
outdated. Update this line to dynamically reference the exact Go version
specified in go.mod (currently 1.24.4) to keep the documentation consistent.
Replace the static version with the precise version from go.mod or adjust the
text to explicitly state the full version number 1.24.4.
1 participant
This PR adds contributor guidelines and repository-specific Copilot instructions.
What
AGENTS.md: concise contributor guide (structure, build/test/lint/dev commands, style, testing, PR rules)..github/copilot-instructions.md: Copilot guidance grounded in project design and TDD (referencesAGENTS.mdandCLAUDE.md).Why
How to verify
AGENTS.md.go tool task dev.Notes
CLAUDE.mdremains the source for deeper design decisions;AGENTS.mdlinks to it.Summary by CodeRabbit