minecraft-modding-mcp: Instructions file for Codex

AGENTS.md

Purpose and Scope

• This file defines mandatory operating rules for agents working in this repository.
• When tradeoffs conflict, prioritize public API compatibility, verification evidence, and release safety.

Core Release Policy

• From version 1.0.0 onward, the public MCP tool surface follows semantic versioning. Breaking changes require a major version bump.
• Do not bump any version unless explicitly instructed by the user. Version bump timing is decided by the user.

Public MCP Contract (MUST)

• Treat the public contract as compatibility-bound: tool names, input parameter names/types/requiredness, and response envelope shape.
• Public MCP tool responses MUST use the standard envelope: { result?, error?, meta }.
• Input validation failures MUST map to ERR_INVALID_INPUT and MUST NOT be reported as ERR_INTERNAL.
• Do not add compatibility aliases for renamed public tools or parameters unless explicitly requested by the user and documented with a removal plan.

Change Coupling Rules (MUST)

• Any user-visible or public API change MUST update CHANGELOG.md and the relevant tests in the same change set.
• README.md, docs/README-ja.md, and docs/tool-reference.md MUST be updated in the same change set when the change touches something they already document — a tool, parameter, response field, error code, environment variable, or setup step. The Japanese overview needs an edit only where it already documents the item. All three are shipped in the package, so a stale statement there reaches users. A change with no counterpart in a file does not need an edit to it.
• Do not defer documentation or test updates to follow-up commits.

Verification Gate (MUST)

• Before claiming completion for production changes, run the verification appropriate to what actually changed — not reflexively the full matrix below, and never less than what the change touches.
• Run the checks of every row the change touches. When unsure whether something reads a changed file, run the broader check.
  • src/**, tsconfig.json, pnpm-lock.yaml, or the package.json fields type, dependencies, devDependencies, or packageManager: pnpm check and pnpm test.
  • tests/**, scripts/**, or the package.json scripts field: pnpm test, the whole suite: contract tests scan all of src/, tests/, and scripts/, so an edit can fail a test other than the edited one. pnpm check does not cover these; it type-checks only src/**/*.ts. Also run each changed scripts entry once, with representative arguments where it needs them, and stop a long-running one such as dev once it has started.
  • README.md, docs/**, CHANGELOG.md, .github/workflows/**, and any file or package.json field no other row names: only the test files that read it, run with pnpm test:file <path...> (pnpm test takes no file argument). Find them with grep -rlF '<base name>' tests --include='*.test.ts' and run every match; some tests build the path, so search the base name, not the full path. Also run pnpm check:changelog when CHANGELOG.md or the package.json version changed.
  • AGENTS.md, or only package.json fields that no test, src/ file, or script reads (description, keywords, author, license, repository, bugs, homepage): no pnpm check or test run; confirm that a changed package.json still parses with node -e "require('./package.json')".
• An edit that changes only comments runs no pnpm check or test, whichever row its path falls under. This applies even after a run on the earlier bytes; a hook-requested comment rewording is no exception. Directive comments (@ts-expect-error, @ts-ignore, /// <reference>, lint or coverage pragmas) count as code, not comments. One exception: some tests/contracts/ scanners also match comment text, such as tests/contracts/no-sdk-private-request-handler-access.test.ts. When a new comment contains a literal one of them forbids, run that scanner with pnpm test:file.
• A release commit is not covered by the narrower rows: Release Safety requires pnpm test on the Node major the publish workflow pins before the release commit is created.
• When MCP transport/tool registration or manual workflows change, also run pnpm test:manual:stdio-smoke when environment permits.
• For search, index, or performance-sensitive changes, also run pnpm test:perf.
• Keep a change when its concrete user or developer value outweighs implementation, verification, future maintenance, and compatibility costs. Pure cleanup that removes dead or duplicated code needs behavioral-equivalence evidence, not a minimum speed improvement. Do not add speculative complexity for an unproven benefit; when the balance is unclear, report a candidate rather than implement it.
• Support speed claims with representative before/after measurements proportionate to the claim and risk; record the workload, configuration, and results, including absolute as well as relative differences where useful. There is no fixed percentage threshold. Judge memory, timeout, and resource-correctness fixes against the actual failure or limit they address, not a latency percentage. Existing checks above remain required for the affected scope.
• Do not re-run a verification command solely to re-confirm a result already produced for the current, unchanged tree. If a later run — your own or a delegated worker's — reports an outcome that contradicts a fresh prior run with no tree change in between, diagnose the discrepancy before re-running the full suite again; a concurrent invocation sharing the same working tree is a common non-code cause.
• Do not claim "done", "fixed", or "passing" without fresh command output evidence.