mcp-walmart-ads: Instructions file for Codex

Agent Instructions

Rules AI agents must follow when working in this repository.

---

Commit messages

Use Conventional Commits.

Header

• Format: <type>(optional scope): summary
• Use lowercase types (feat, fix, ci, chore, docs)
• Use scopes when relevant
• Write summaries in lowercase, imperative mood

Body

• Leave a blank line after the header
• Explain why, not what
• Use imperative, present tense
• Wrap lines at ~72 characters

The body is optional for trivial changes.

---

Release tags

• Use the bare version as the tag name — no v prefix (e.g. 0.1.0a4, not `v0.1.0a4``)
• Tags must be annotated (git tag -a) with a structured release-notes message
• CI verifies the tag against pyproject.toml and server.json before it publishes anything; a mismatch — a v prefix included — fails the build rather than being silently rewritten

---

Commits

When generating commits via a shell:

• Do not pass generated messages directly to git commit -m
• Write the commit message to a file or standard input
• Use git commit -F <file> or git commit -F -
• Disable shell expansion when writing commit messages

This avoids issues with backticks, quotes, and other shell-expanded characters in generated commit messages.

---

Code style

Follow existing project conventions.

• Match formatting, naming, and file structure already in use
• Wrap prose and Markdown at 100 columns, matching line-length in pyproject.toml; leave code blocks, tables, and URLs unwrapped
• Do not reformat unrelated code
• Prefer small, focused changes
• Avoid introducing new patterns without clear benefit

Language-specific rules

• Respect .editorconfig when present
• Do not disable lint rules without justification
• Prefer explicit, readable code over clever abstractions
• Ensure all changes pass ruff check ., ruff format --check ., pyright, and pytest

---

uv Workflow Rules

• Use uv exclusively for dependency management instead of pip
• Always prefix tool and script invocations with uv run so they execute inside the managed environment
• Do not manually create, activate, or delete .venv directories
• Bump the project version with uv run python scripts/bump_version.py <new-version> — it drives uv version and propagates the result to server.json, which carries the version twice; do not edit pyproject.toml directly
• Always commit pyproject.toml, uv.lock, and server.json together after a version bump