mygo/AGENTS.md

AGENTS.md — MyGO

Project Layout

• Server: Go backend in the repository root
• Web: React client in web/
• Documentation index: docs/README.md

Agent Workflow

1. Identify the affected project and required outcome.
2. Read docs/README.md and the relevant project documents.
3. Explore the existing code before making changes.
4. Follow the project conventions below.
5. Run the verification commands for every affected project.
6. Update documentation when architecture, workflow, decisions, or feature status changes.

Documentation Routing

Change	Read	Update
Server packages or boundaries	docs/server/architecture.md	When the current architecture changes
Server design or dependency decision	docs/server/decisions.md	When a decision is accepted or superseded
Server build, test, review, or config workflow	docs/server/development.md	When the workflow changes
Server feature scope or status	docs/server/roadmap.md	When capability status changes
Web design or tooling decision	docs/web/decisions.md	When a decision is accepted or superseded
Web feature scope or status	docs/web/roadmap.md	When capability status changes
Repository documentation	docs/writing-guide.md	When documentation policy changes

Use the relevant decision index before making a significant architecture or dependency decision. Read only the ADRs relevant to the change.

Server — Go Backend

Essentials

• Module: github.com/dhao2001/mygo
• Go: 1.26.2, pinned in mise.toml
• CLI: Cobra
• Application code: internal/
• CLI composition: cmd/

Go Conventions

• Separate imports into standard library, third-party, and internal groups.
• Wrap errors with operation context: fmt.Errorf("operation: %w", err).
• Pass context.Context first in I/O, storage, and lifecycle functions.
• Add doc comments to exported names.
• Keep business logic in internal/; keep cmd/ focused on CLI composition and startup.
• Add required Go module dependencies before writing code that imports them.

Verification

go fmt ./...
go build ./...
go test ./...
go vet ./...

Run go mod tidy after adding or removing imports.

Repository Review

Invoke $mygo-api-repo-review for repository-wide or scoped architecture, design, security, resilience, data-consistency, performance, and implementation audits.

• diff: compare the workspace, including relevant untracked files, with HEAD.
• main: compare the workspace with the merge base of HEAD and local main.
• full: review the complete repository.

Reviews are read-only unless the user also requests fixes. A mode can target a path, Go package, or logical component.

Server Constraints

• Do not load the complete go.sum file into context. Use rg to find the required module or version entry.
• Dependency changes made after debugging begins require explicit user approval.
• Complete go vet ./... before finishing server code changes.

Web — React Client

Essentials

• Source: web/
• Node.js: 24, pinned in mise.toml
• Rendering: client-side Vite application
• Stack: React, TypeScript, React Router, TanStack Query, Tailwind CSS 4, and Ant Design

Verification

Run from web/:

npm ci
npm run check

Use $playwright-cli for browser inspection and debugging. Run the repository wrapper from web/:

mise exec -- npm run playwright:cli -- <command>

Do not invoke Playwright through a global installation or a floating npx package.

Git Version Control

• Place worktrees under .worktree/ and use a safe branch name, for example git worktree add -b feat/partly-upload .worktree/feat-partly-upload.
• Create a commit only when the user explicitly requests one.
• Run the required checks before proposing a commit. For documentation-only changes, run the relevant documentation checks.
• Resolve implementation issues in the affected area before proposing a commit. Report unrelated known failures separately.
• Write the complete commit message and obtain explicit approval for that exact message before running git commit.
• Commit messages contain no Co-authored-by, generated-tool signatures, or attribution trailers unless the user requests them.

Commit Message Format

Use Conventional Commits:

<type>[optional scope][optional !]: <description>

<body>

• Use fix, feat, build, docs, refactor, or test as the type.
• Add ! for a breaking API change.
• Keep the title concise.
• Write the body as a small set of bullets with typed prefixes such as feat:, fix:, test:, or docs:.
• Leave one blank line between the title and body.
• Summarize behavior and intent instead of copying code statements.

Shared Constraints

• Write code, comments, and repository documentation in English.
• Follow the commit authorization workflow above.

Debugging Principles

1. Confirm that the test expresses the intended behavior.
2. Correct the test when its expectation is wrong.
3. Correct the implementation when the test is valid.
4. Preserve intended assertions and edge-case coverage. Never weaken a valid test to make it pass.
5. Stop after six unsuccessful debugging rounds and report the current evidence.