mygo/AGENTS.md

# AGENTS.md — MyGO

## Project Layout

- Server: Go backend in the repository root, with documentation in `docs/server/`
- Web: React client in `web/`, with documentation in `docs/web/`
- Documentation index: `docs/README.md`

## Agent Workflow

1. Read the task and identify the affected project
2. Read `docs/README.md` and the relevant project documentation for context
3. Explore existing code before writing new code
4. Implement following the relevant project conventions below
5. Run the verification commands for every affected project
6. Update the relevant project roadmap, decisions, architecture, or development documentation if anything changed

## Server — Go Backend

### Project Essentials

- Module: `github.com/dhao2001/mygo`, Go 1.26.2
- WebDisk (cloud drive) backend; roadmap in `docs/server/roadmap.md`
- CLI framework: `github.com/spf13/cobra`
- Go version pinned in `mise.toml`

### Repository Review

- Explicitly invoke `$mygo-api-repo-review` for repository-wide or scoped architecture, design, security, resilience, data-consistency, performance, and implementation audits.
- Repository reviews are read-only unless the user separately requests fixes.
- Use `diff`, `main`, or `full` review mode and optionally limit any mode with a target path, Go package, or logical component.

### Go Conventions

- **Format**: `go fmt ./...` before every commit
- **Imports**: stdlib / third-party / internal, blank-line separated
- **Errors**: wrap with `fmt.Errorf("context: %w", err)`
- **Context**: first param in I/O, storage, lifecycle funcs
- **Exported names**: doc-commented
- **`init()`**: only in cobra cmd files for flag registration
- **`cmd/`** is thin; business logic goes in `internal/`

### Documentation

| File | Read Before | Update After |
|------|-------------|--------------|
| `docs/server/architecture.md` | Adding new packages | Adding new packages |
| `docs/server/decisions.md` | Making technical decisions | Making technical decisions |
| `docs/server/roadmap.md` | Every server task | Completing a server feature |
| `docs/server/development.md` | Build/test/debug setup | Changing server workflow |

### Commands

```bash
go build ./...          # build all packages
go test ./...           # all tests
go vet ./...            # static analysis
go fmt ./...            # format
go mod tidy             # clean deps after add/remove
```

### Server DO / DON'T

- DO put business logic in `internal/`, keep `cmd/` thin
- DO add all Go module dependencies **before** writing code that uses them
- DON'T read `go.sum` entirely into context — use `grep` or other tools to search specific patterns if needed
- DON'T skip `go vet ./...` before finishing server work
- DON'T add, remove, or change Go module dependencies after debugging has started — ask for explicit permission first

## Web — React Client

### Project Essentials

- Source: `web/`
- Pure client-side rendered application; roadmap in `docs/web/roadmap.md`
- Stack: Node.js 24, Vite, React, TypeScript, React Router, TanStack Query, Tailwind CSS 4, and Ant Design
- Node.js version pinned in `mise.toml`

### Documentation

| File | Read Before | Update After |
|------|-------------|--------------|
| `docs/web/decisions.md` | Making Web technical decisions | Making Web technical decisions |
| `docs/web/roadmap.md` | Every Web task | Completing a Web feature or changing the Web plan |

### Commands

Run from `web/`:

```bash
npm ci                  # install locked dependencies
npm run dev             # start the development server
npm run check           # lint, type-check, and build
```

## Git Version Control

- DON'T create a commit unless the user explicitly asks for one.
- Before any commit, verify the work with the required project checks. For code changes, run the checks for every affected project; for docs-only changes, run the most relevant non-mutating checks if available.
- Create a commit only when all required checks pass and the current implementation area has no unresolved issues.
- If a known failing check or unresolved issue belongs to another module and is outside the current task, report it clearly before asking for commit approval.
- Before running `git commit`, write the complete commit message first, show it to the user, and ask for explicit approval. DON'T commit until the user approves that exact message.
- Never include `Co-authored-by`, generated-tool signatures, or external attribution trailers unless the user explicitly asks for them.

### Commit Message Format

Use Conventional Commits:

```text
<type>[optional scope][optional !]: <description title>

<body>
```

- Choose the most accurate `type`: `fix`, `feat`, `build`, `docs`, `refactor`, or `test`.
- Add `!` after `type` or `scope` when the change contains a breaking API change.
- Keep the title to one concise sentence describing the main change.
- Write the body as bullet points grouped by change category. Each bullet starts with a typed prefix such as `feat:`, `fix:`, `test:`, `docs:`, `refactor:`, or `build:`.
- Use as few as possible bullets.
- Use one blank line between the title and body.
- DON'T paste full code sentences into the message body; summarize behavior and intent.

Example:

```text
feat(middleware): add AdminRequired authorization middleware

- feat: AdminRequired gates admin endpoints by checking user IsAdmin flag. Placed after AuthRequired; fetches user from repository, returns 403 for non-admins.
- fix: soft-deleted users are rejected with 401 since FindByID excludes them.
- test: admin passes, non-admin forbidden, soft-deleted admin rejected, missing user ID.
```

## Shared DO / DON'T

- DO write all code, comments, and documentation in English
- DON'T commit without following the Git Version Control rules above

## Debugging Principles

When a test failure occurs, follow this strict order:

1. **Examine the test first** — ensure the test code correctly expresses the intended program behavior
2. **Fix the test if it's wrong** — if the test doesn't represent correct expected behavior, correct the test to match the intended behavior
3. **Fix the implementation if the test is correct** — only after confirming the test is valid, locate and fix the bug in the implementation
4. **Never weaken tests to gain passing status** — do not relax assertions, remove edge cases, or simplify test logic just to make tests pass. Tests exist to catch problems, not to produce a 100% pass rate
5. **Escalate after 6 rounds** — if a problem remains unresolved after 6 debugging attempts, stop and report the current state to the user for further investigation