Skip to content

AGENTS.md

Latest commit

 

History

History
142 lines (111 loc) · 4.79 KB

AGENTS.md

File metadata and controls

142 lines (111 loc) · 4.79 KB
Raw

AI Agent Instructions

Repository Scope

Storefront extension for logistics-first commerce, order intake, storefront configuration, products, checkout flows, and commerce-to-logistics workflows.

Allowed Work

  • Bug fixes for storefront configuration, product, checkout, order intake, and commerce logistics workflows.
  • Small backend, Ember engine, test, and documentation updates that follow existing Storefront patterns.
  • API validation, resource, and schema updates when paired with documentation/spec checks.

Restricted Work

  • Large rewrites of checkout, order intake, or marketplace flows without explicit approval.
  • Gateway, payment, or customer data handling changes without human review.
  • API behavior changes without checking fleetbase/postman and fleetbase/fleetbase.io.

Global Agent Rules

  • Do not merge pull requests.
  • Do not publish packages.
  • Do not rotate, expose, modify, or invent secrets.
  • Do not change production credentials or deployment configuration unless explicitly requested.
  • Do not perform large rewrites unless explicitly requested.
  • Prefer small, reviewable changes.
  • Preserve existing architecture and conventions.
  • Follow the repository's existing naming, formatting, and test patterns.
  • Add or update tests where practical.
  • If tests are not added, explain why in the PR.
  • Run available lint/test/build commands before finalizing the PR.
  • Include command output or a clear summary of validation performed.
  • If the issue is ambiguous, comment with questions instead of guessing.

Local Setup

  • pnpm install
  • composer install

Test Commands

  • Frontend lint: pnpm lint
  • Frontend tests: pnpm test or pnpm test:ember
  • Frontend build: pnpm build
  • Backend lint: composer test:lint
  • Backend static analysis: composer test:types
  • Backend tests: composer test:unit or composer test

Pull Request Rules

  • Work on a dedicated branch for each task.
  • Keep changes small and reviewable.
  • Stage only files related to the task.
  • Do not include unrelated local changes in commits.
  • Use clear PR titles and descriptions that explain what changed and why.
  • Link the related issue when one exists.
  • Include validation commands and a concise summary of results.
  • Explain any skipped tests, missing coverage, or known follow-up work.
  • Call out documentation and API reference impact using the PR template.
  • Do not merge the PR after opening it.

Documentation Rules

Some changes require documentation updates in fleetbase/fleetbase.io.

Some API-related changes additionally require updates to API specification files in fleetbase/postman.

Update or create documentation when a change affects:

  • user-facing behavior
  • configuration
  • installation steps
  • environment variables
  • API behavior
  • request/response schemas
  • authentication behavior
  • extension behavior
  • permissions or IAM behavior
  • billing, invoicing, wallets, or gateway behavior
  • developer workflows
  • CLI commands
  • mobile app workflows
  • onboarding flows
  • breaking changes
  • deprecated behavior

If API behavior changes, the agent must determine whether corresponding specification updates are needed in fleetbase/postman.

Examples include:

  • new endpoints
  • modified endpoints
  • payload changes
  • validation changes
  • authentication changes
  • response schema changes
  • enum changes
  • new query parameters
  • deprecated API behavior

If API specification files are updated in fleetbase/postman, the agent should also determine whether a documentation PR or regeneration step is required in fleetbase/fleetbase.io.

If documentation should be updated but cannot be updated in the same PR, the agent must:

  1. mention this clearly in the PR description;
  2. add a needs-docs label if available;
  3. reference the expected documentation area in fleetbase/fleetbase.io;
  4. reference any required specification updates in fleetbase/postman.

Escalation Rules

Stop and request human clarification when:

  • the requested behavior is ambiguous or conflicts with existing architecture;
  • the change would alter public APIs, authentication, permissions, billing, financial records, or production configuration;
  • secrets, credentials, signing assets, deployment settings, or release automation are involved;
  • the safest implementation requires a large rewrite or broad cross-repository coordination;
  • tests fail for reasons that are not clearly related to the change;
  • documentation or API specification ownership is unclear.

Recommended Labels

Use these labels when they are available:

  • type:bug
  • type:feature
  • type:docs
  • type:refactor
  • type:chore
  • agent:ready
  • agent:approved
  • agent:blocked
  • agent:in-progress
  • needs-docs
  • needs-api-spec
  • needs-human-review
  • needs-product-decision
  • priority:p0
  • priority:p1
  • priority:p2
  • priority:p3
  • module:storefront