hevy-mcp AGENTS.md

Agent Instructions for hevy-mcp

Read this file before changing the repository. Keep this file focused on agent-only rules; use the linked documents and repository configuration as the source of truth for detailed commands and changing facts.

Learning more about Effect

This repository uses the Effect Typescript library.

Before writing any Effect code, first read node_modules/effect/AGENTS.md completely, and follow the links in the file when required.

If you need to learn more about particular Effect apis and concepts that the guide doesn't cover, search through the source code in node_modules/effect/src.

Start in a fresh worktree

1. Inspect the checkout before touching it:

   git status --short --branch
   

2. Fetch the current base and create a dedicated feature branch/worktree from it:

   git fetch origin main
   git worktree add -b <type>/<topic> ../hevy-mcp-<topic> origin/main
   

   Use a branch type such as feat, fix, docs, test, refactor, or chore. Preserve existing user changes; ask before proceeding if creating the worktree would risk them.

3. Implement and validate in the new worktree. The work is ready for review only when the branch is based on origin/main, is not main, and the original checkout remains untouched.

Never push directly to main. Use Conventional Commits (feat:, fix:, docs:, test:, refactor:, build:, ci:, chore:, or style:) and keep Git hooks enabled. Fix hook failures instead of bypassing them.

Git safety in tests

• Never write tests that invoke Git, execute git commands, or mutate Git repositories or Git configuration. Use pure logic and ordinary filesystem fixtures instead.
• Never create, configure, or persist test Git identities such as user.name, user.email, GIT_AUTHOR_*, or GIT_COMMITTER_*.

Source-of-truth pointers

• CONTRIBUTING.md owns development setup, Node policy, Worker operations, release policy, and the required validation baseline. Read the relevant section before that class of change.
• docs/test-lanes.md owns named test lanes. Prefer the pnpm run test:* aliases over copying raw Vitest selectors.
• repository/topology.json owns workspace boundaries and release bundles.
• package.json owns the current command names. Inspect it instead of copying command details into new documentation.
• Use the GitHub MCP server for GitHub operations. Use gh only when the GitHub MCP server cannot complete the operation because of a token problem.