pokemon-inventory/AGENTS.md

Agent Instructions

Mission

Build and maintain the Pokémon Inventory & Sales Reference Catalog according to the documentation in docs/.

The documentation is the source of truth. Do not invent requirements when an authoritative project rule exists.

Before changing code

1. Read the relevant documentation.
2. Identify affected domain modules and tests.
3. Preserve the Product → Inventory Item → Listing → Sale separation.
4. Check public/private data boundaries.
5. Check accessibility requirements.
6. Add or update automated tests with the change.

Architecture rules

• Use the modular-monolith architecture.
• Keep HTTP handling in routes.
• Keep application behavior in services.
• Keep business invariants in domain logic.
• Keep persistence in repositories.
• Keep external integrations behind provider/storage interfaces.
• Keep asynchronous work in the worker.
• Do not introduce microservices without an explicit architecture decision.
• Do not bypass the API from the browser.
• Do not put server-only business logic in shared browser packages.

Security

• The frontend is never the security boundary.
• Enforce authorization server-side.
• Use secure HttpOnly SameSite sessions.
• Never store authentication tokens in localStorage.
• Never commit credentials or secrets.
• Treat uploads, user input, and provider data as untrusted.

Domain rules

• Physical inventory copies are separate Inventory Item records.
• Provider mappings belong to Products, not physical copies.
• Sales are manual records; there is no checkout.
• Sold history is retained.
• Financial values use integer minor units.
• USD is the canonical stored/calculated currency.
• Public DTOs must never expose private financial, buyer, provider-debugging, or audit data.

Change discipline

Prefer small, focused changes. Avoid unrelated refactoring.

When a decision changes the architecture or requirements, update the relevant documentation before or with the implementation.

Vertical slice completion

Each vertical slice must be complete before it is committed and pushed:

• A new or changed Vue visual component must have a colocated Storybook story or an updated existing story covering its meaningful states.

• Stories must use representative fixture data and must not introduce production domain behavior solely for visual coverage.

• Visual slices must pass the web tests, production build, Storybook build, and Storybook interaction/accessibility runner before commit:

  npm run test --workspace=@pokemon-inventory/web
  npm run build --workspace=@pokemon-inventory/web
  npm run build-storybook --workspace=@pokemon-inventory/web
  npm run test-storybook
  

• Storybook stories must cover relevant loading, empty, error, selected, disabled, responsive, light/dark theme, and keyboard states when those states exist in the component.

• Backend-only slices do not require Storybook changes unless they alter a user-facing visual contract.

• The final commit gate includes the appropriate API/domain/integration tests plus all applicable web and Storybook checks.