Refactor AGENTS structure and relocate docs

[satococoa]

Summary

• replace the old AGENTS content with a concise overview covering essentials, commands, docs, and links
• delete the redundant docs/testing-guidelines.md and consolidate testing guidance into docs/agents/code-and-tests.md
• add new agent docs for dev commands and workflow to keep instructions modular and maintainable

Testing

• Not run (not requested)

Summary by CodeRabbit

• Documentation
  • Streamlined and reorganized contributor guidelines to focus on essential information
  • Added new documentation for development commands and coding/testing conventions
  • Consolidated and simplified architecture documentation to reflect current implementation
  • Removed redundant testing guidelines

[coderabbitai]

📝 Walkthrough

Walkthrough

Documentation restructuring consolidates and simplifies project guidance files. AGENTS.md and docs/architecture.md are condensed to lean overviews, while docs/testing-guidelines.md is removed entirely. New documentation files for code conventions and dev commands are introduced.

Changes

Cohort / File(s)	Summary
Documentation Consolidation AGENTS.md, docs/architecture.md	Content significantly condensed from detailed multi-section guidelines to concise, high-level overviews. AGENTS.md retains only essentials and docs links; docs/architecture.md shifts from verbose technical narratives to repository layout and current implementation structure.
Removed Testing Guidance docs/testing-guidelines.md	Comprehensive testing guidelines document deleted entirely, removing sections on philosophy, test categories, naming conventions, anti-patterns, patterns, code-review checklists, and migration guides.
New Agent Documentation docs/agents/code-and-tests.md, docs/agents/dev-commands.md	Two new documentation files introduced: code-and-tests.md outlines coding/testing conventions; dev-commands.md maps developer commands to go tool task invocations.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• docs(contrib): add AGENTS.md and Copilot repository instructions #14: Directly conflicts with AGENTS.md changes; PR adds comprehensive content while main PR significantly reduces it.
• docs: unify AI agent documentation in AGENTS.md #24: Modifies the same documentation files (AGENTS.md and testing-guidelines.md) as primary documentation updates.
• docs: clarify automation guidance #38: Related to dev command/automation documentation changes paralleling the dev-commands.md addition.

Suggested labels

codex

Poem

📚 A rabbit tidies the warren's scrolls,
Trimming the verbose, keeping essentials whole,
AGENTS shrinks sleek, architecture refined,
Old testing tomes filed away—new guides aligned,
Lean docs hop forward, clear and concise! 🐰✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'Refactor AGENTS structure and relocate docs' directly matches the PR's primary objectives: simplifying AGENTS.md and reorganizing documentation files across multiple locations.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch codex/refactor-agentsmd-structure

---

No actionable comments were generated in the recent review. 🎉

🧹 Recent nitpick comments

docs/agents/dev-commands.md (1)

1-9: Consider adding brief descriptions for each command.

While the command names are self-explanatory, adding a one-line description of what each command does or when to use it would improve clarity and align better with the learning that documentation should be comprehensive.

📝 Example enhancement with descriptions

 # Dev Commands
 
-- Build: `go tool task build`
-- Install: `go tool task install`
-- Test: `go tool task test`
-- Lint: `go tool task lint`
-- Format: `go tool task fmt`
-- E2E: `go tool task test-e2e`
-- Full local check: `go tool task dev`
+- **Build**: `go tool task build` — Compile the wtp binary
+- **Install**: `go tool task install` — Install wtp to $GOPATH/bin
+- **Test**: `go tool task test` — Run unit tests
+- **Lint**: `go tool task lint` — Run golangci-lint on the codebase
+- **Format**: `go tool task fmt` — Format code with goimports
+- **E2E**: `go tool task test-e2e` — Run end-to-end tests
+- **Full local check**: `go tool task dev` — Run all checks (format, lint, test, build)

Based on learnings: "Documentation for agents should be clear and comprehensive"

AGENTS.md (1)

9-15: Remove duplicate command listing.

The commands are listed both inline here and in the linked docs/agents/dev-commands.md. This creates unnecessary duplication and maintenance burden. Since you're already linking to the detailed dev commands documentation, consider removing this inline listing.

♻️ Proposed refactor to eliminate duplication

 ## Essentials
 - Toolchain: Go 1.24
 - Package manager: Go modules (`go`)
 - Project task runner: `go tool task`
-- Non-standard project commands:
-  - `go tool task build`
-  - `go tool task test`
-  - `go tool task lint`
-  - `go tool task fmt`
-  - `go tool task test-e2e`
-  - `go tool task dev`
 
 ## Docs
 - [Dev commands](docs/agents/dev-commands.md)

Alternatively, if you prefer to keep a quick reference inline, remove the separate dev-commands.md file instead.

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Copilot]

Pull request overview

This PR refactors the AGENTS documentation by replacing the comprehensive single-file guide with a modular structure. The main AGENTS.md file now serves as a brief entry point with links to specialized documentation files.

Changes:

• Replaced 121-line AGENTS.md with a concise 21-line overview that links to modular docs
• Deleted 394-line docs/testing-guidelines.md and created simplified 20-line docs/agents/code-and-tests.md
• Added new modular documentation files: dev-commands.md (18 lines), workflow.md (13 lines)

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
AGENTS.md	Replaced comprehensive guide with concise overview linking to modular docs
docs/testing-guidelines.md	Deleted extensive testing guidelines (394 lines)
docs/agents/dev-commands.md	New file documenting Task commands and dev workflow
docs/agents/code-and-tests.md	New file with condensed coding conventions and testing basics
docs/agents/workflow.md	New file documenting Git/PR workflow and config management

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The testing guidance is significantly reduced compared to the deleted testing-guidelines.md. The existing E2E tests follow detailed conventions (Given-When-Then structure, User Stories, Business Value documentation) that are no longer documented anywhere. Consider adding a reference to at least one example test that demonstrates the expected E2E test structure, or include key points about:

• Test pyramid ratios (70% unit, 30% E2E)
• E2E tests requiring Given-When-Then comments and business value documentation
• Unit tests avoiding excessive documentation
• When to use table-driven tests

Without this guidance, future contributors may not understand why existing E2E tests have extensive documentation or how to write new tests consistently.

Suggested change

	- Prefer unit tests for fast feedback (table-driven, mocked git interactions).
	- Use E2E tests in `test/e2e` for real git workflow validation.
	- Unit test naming: `TestFunction_Condition`.
	- E2E naming: `TestUserAction_WhenCondition_ShouldOutcome`.
	- Aim for a test pyramid of roughly **70% unit tests** and **30% E2E** by count.
	- Prefer unit tests for fast feedback (table-driven where it reduces duplication, mocked git interactions).
	- Use E2E tests in `test/e2e` for real git workflow validation; use existing tests there as examples of structure and documentation.
	- Unit test naming: `TestFunction_Condition`.
	- E2E naming: `TestUserAction_WhenCondition_ShouldOutcome`.
	- E2E tests must document:
	- a short “Business value” / user story comment explaining why the flow matters, and
	- Given / When / Then comments that outline the scenario steps.
	- Keep unit tests focused and readable; avoid extensive prose documentation unless the behavior is unusually subtle.
	- Use table-driven tests when validating multiple input/output combinations or edge cases for the same behavior; prefer simple tests for one-off scenarios.

[Copilot]

Several important sections from the original AGENTS.md are not present in the new modular documentation:

1. Core Design Decisions (Why Go vs Shell, Configuration format, Hook system design, Worktree naming convention) - This provides valuable context for understanding architectural choices
2. Shell Integration Architecture (v1.2.0 details about command structure and user experience matrix) - Important for understanding the shell integration design
3. Project Structure & Modules - Helps contributors understand the codebase organization

Consider either:

• Adding these sections to docs/architecture.md or a new docs/agents/design-decisions.md file
• Or documenting in the PR description why these sections are intentionally removed (if they're outdated or no longer needed)

The refactoring should preserve important historical and architectural context that helps contributors understand the "why" behind implementation choices.

Suggested change

	- [Architecture](docs/architecture.md)
	- [Architecture](docs/architecture.md)
	- Core design decisions (e.g., Go vs shell, configuration format, hook system design, worktree naming convention)
	- Shell integration architecture (including v1.2.0 command structure and user experience matrix)
	- Project structure and modules (high-level overview of packages and responsibilities)