Refactor AGENTS structure and relocate docs

AGENTS.md

@@ -1,121 +1,21 @@
-# Repository Guidelines
-
-## Document Purpose
-- Single source of truth for AI assistants contributing to `wtp`.
-- Consolidates design decisions, workflow expectations, and coding standards previously split across `AGENTS.md` and `CLAUDE.md`.
-
-## Project Structure & Modules
-- Root module: `github.com/satococoa/wtp/v2` (Go 1.24).
-- CLI entrypoint: `cmd/wtp`.
-- Internal packages: `internal/{git,config,hooks,command,errors,io,testutil}`.
-- Tests: unit tests alongside packages (`*_test.go`), end-to-end tests in `test/e2e`.
-- Tooling/config: `.golangci.yml`, `.goreleaser.yml`, `Taskfile.yml`, `.wtp.yml` (project hooks), `docs/`.
-
-## Build, Test, and Dev Commands
-- Build: `go tool task build` (or `task build`) → outputs `./wtp`.
-- Install: `go tool task install` → installs to `GOBIN`/`GOPATH/bin`.
-- Test (unit + race + coverage): `go tool task test` → writes `coverage.out`.
-- Lint: `go tool task lint` (golangci-lint).
-- Format: `go tool task fmt` (golangci-lint fmt → gofmt + goimports).
-- E2E tests: `go tool task test-e2e` (uses built binary; override with `WTP_E2E_BINARY=/abs/path/wtp`).
-- Direct build (no Task): `go build -o wtp ./cmd/wtp`.
-- Dev cycle: `go tool task dev` (runs clean, fmt, lint, test, build).
-
-## Coding Style & Naming
-- Follow standard Go style (tabs, gofmt) and idioms; package names are short and lowercase.
-- Imports: keep groups tidy; `goimports` organizes, local prefix follows module path.
-- Linting: adhere to rules in `.golangci.yml` (vet, staticcheck, gosec, mnd, lll=120, etc.).
-- Errors: wrap with context; avoid ignoring errors.
-- Files/identifiers: `snake_case.go`, exported items documented when non-trivial.
-
-## 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.
-- PR description: what/why/how, testing notes, related issues (e.g., `Closes #123`).
-- Add CLI output or screenshots when UX changes.
-
-## Security & Configuration Tips
-- Project hooks are defined in `.wtp.yml`. Keep commands deterministic and safe; avoid destructive steps by default.
-- Do not commit secrets; use example files (e.g., `.env.example`) and copy in hooks.
-
-## TDD Workflow
-### Development Cycle Expectations
-- Run `go tool task dev` before committing; it runs clean, fmt, lint, test, and build.
-- Keep the repository in a buildable state; never commit failing tests or lint errors.
-- Update README/CLI help when user-facing behavior changes.
-
-### RED → GREEN → REFACTOR Example
-1. **RED**: write an end-to-end or unit test that captures the desired behavior. Example: add a failing E2E test for `wtp prune` that asserts a detached worktree is removed.
-2. **GREEN**: implement the minimum code to satisfy that test. Keep the change small and focused on the behavior under test.
-3. **REFACTOR**: clean up duplication, rename helpers, and harden edge cases while keeping tests green.
-
-### Quick Testing Tips
-- Use `go run ./cmd/wtp <args>` for rapid feedback instead of building binaries.
-- Run commands from inside a worktree to mimic real usage (e.g., `go run ../cmd/wtp add feature/new-feature`).
-
-### Testing Strategy
-- Unit tests target 70% of coverage: fast feedback, mocked git interactions, table-driven cases.
-- E2E tests cover 30%: real git workflows in `test/e2e` exercising command plumbing.
-- See `docs/testing-guidelines.md` for extended advice on fixtures, naming, and reliability.
-
-### Guidelines for New Commands
-- Start with tests: design executor behavior through failing tests.
-- Prefer existing command builders; add new ones when patterns diverge.
-- Mock git operations in unit tests; rely on E2E suites for real git interactions.
-- Document new workflows with realistic scenarios in `test/e2e`.
-
-## Core Design Decisions
-### Why Go Instead of Shell Script?
-1. **Cross-platform compatibility**: native support for Windows without WSL.
-2. **Better error handling**: types and structured errors instead of brittle shell parsing.
-3. **Unified shell completion**: one implementation for all supported shells.
-4. **Easier testing**: standard Go testing beats shell-script harnesses.
-5. **Single binary distribution**: simplifies packaging for brew, scoop, etc.
-
-### Configuration Format (Why YAML?)
-- Human-readable and writable.
-- Expressive enough for arrays, maps, and nested structures used by hooks.
-- Well-supported in the Go ecosystem.
-- Familiar syntax for developers accustomed to CI/CD tooling.
-
-### Hook System Design
-- Post-create hooks handle both file copying (e.g., `.env`) and command execution.
-- Captures the common 90% of project bootstrap needs without over-engineering.
-- Hooks are declared in `.wtp.yml`, keeping repository-specific automation explicit.
-
-### Worktree Naming Convention
-1. **Main worktree**: always rendered as `@`.
-2. **Non-main worktrees**: display the path relative to `base_dir` (e.g., `.worktrees/feat/hoge` → `feat/hoge`).
-3. **Fallback**: directory name is used if path resolution fails so that UX remains consistent.
-
-**Implementation Notes**
-- `getWorktreeNameFromPath()` in `cmd/wtp/remove.go` resolves display names.
-- Shared across shell completion, user-facing errors, and command parsing.
-- Ensures commands such as `wtp remove feat/foo` and `wtp cd feat/foo` share the same identifier.
-
-## Shell Integration Architecture (v1.2.0)
-### "Less is More" Approach
-- Completion and shell integration are separated for clarity and maintainability.
-- Homebrew and direct installs can compose the pieces they need.
-
-### Command Structure
-- **`wtp cd <worktree>`**: outputs the absolute worktree path with no side effects.
-- **`wtp completion <shell>`**: generates pure completion scripts via `urfave/cli`.
-- **`wtp hook <shell>`**: emits shell functions that intercept `wtp cd` for seamless navigation (bash, zsh, fish).
-- **`wtp shell-init <shell>`**: convenience command that combines completion and hook output.
-
-### User Experience Matrix
-| Installation Method | Tab Completion | cd Functionality |
-|---------------------|----------------|------------------|
-| Homebrew            | Automatic      | `eval "$(wtp hook <shell>)"` |
-| `go install`        | `eval "$(wtp completion <shell>)"` | `eval "$(wtp hook <shell>)"` |
-
-### Migration Notes
-- `wtp cd` no longer depends on `WTP_SHELL_INTEGRATION=1`; the command itself only prints paths.
-- Existing completion scripts from v1.1.x still work but omit cd helpers unless users add hooks.
-- Future Homebrew enhancements may lazy-load integration by wrapping `wtp shell-init` on first use.
-
-## Additional References
-- Architecture overview: `docs/architecture.md`.
-- Testing deep dive: `docs/testing-guidelines.md`.
+# AGENTS
+
+`wtp` is a Go CLI that simplifies `git worktree` workflows for creating, listing, moving, and removing worktrees.
+
+## 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)
+- [Code and tests](docs/agents/code-and-tests.md)
+- [Workflow](docs/agents/workflow.md)
+- [Architecture](docs/architecture.md)

docs/agents/code-and-tests.md

@@ -0,0 +1,20 @@
+# Code and Tests
+
+## Go Conventions
+- Package names are short and lowercase.
+- Keep imports tidy; rely on `goimports` with the module local prefix.
+- Follow lint rules in `.golangci.yml`.
+- Wrap errors with context; do not ignore errors.
+- Use `snake_case.go` filenames.
+
+## TDD Flow
+1. RED: add a failing unit or E2E test for the behavior.
+2. GREEN: implement the minimum change to pass.
+3. REFACTOR: improve touched code while tests stay green.
+
+## Testing Expectations
+- 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`.
+- Update README or CLI help when user-facing behavior changes.

docs/agents/dev-commands.md

@@ -0,0 +1,18 @@
+# Dev Commands
+
+Use Task commands as the default interface for local development.
+
+- 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`
+
+Fast feedback loop:
+- `go run ./cmd/wtp <args>`
+
+Notes:
+- `go tool task test` writes `coverage.out`.
+- `go tool task test-e2e` uses the built binary and supports `WTP_E2E_BINARY=/abs/path/wtp`.

docs/agents/workflow.md

@@ -0,0 +1,13 @@
+# Workflow
+
+## Git and PR
+- Conventional Commits: `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`, `style:`.
+- Branch naming: `feature/...`, `fix/...`, `hotfix/...`.
+- Before opening a PR, run: format, lint, tests.
+- Include test notes and related issues in PR descriptions (for example `Closes #123`).
+- Add CLI output or screenshots when UX changes.
+
+## Config and Secrets
+- Project hooks are defined in `.wtp.yml`.
+- Never commit secrets.
+- Prefer example files (for example `.env.example`) for hook-based setup.