diff --git a/AGENTS.md b/AGENTS.md index a46c3a5f76..bbc4f02e48 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -13,8 +13,16 @@ This is an Nx monorepo for an e-commerce platform built with Medusa.js. The proj - `medusa-be`: Medusa.js v2 backend - `medusa-demo`: Next.js demo frontend (reference implementation) - `medusa-fe`: Next.js frontend (reference implementation) + - `herbatika`: Next.js 16 storefront app - **libs/**: Shared libraries - `ui`: Component library built with Zag.js and Tailwind CSS + - `storefront-data`: TanStack Query + Medusa storefront data layer + +### Subtree Guidance +- When touching `apps/herbatika`, read `apps/herbatika/AGENTS.md` before editing. + It overrides the root frontend-demo server assumption with Herbatika's + `http://localhost:3001` runtime and routes work through the `libs/ui/skills` + and `libs/storefront-data/skills` workflows. ### Key Technologies - **Monorepo**: Nx @@ -83,6 +91,7 @@ This project includes MCP (Model Context Protocol) servers configuration to enha ### Important: Development Server Assumptions **NEVER ask to run `pnpm dev` or check if the dev server is running!** - Always assume the development server is already running on http://localhost:3000 (for frontend-demo) +- Exception: `apps/herbatika` uses `http://localhost:3001`; follow `apps/herbatika/AGENTS.md` for Herbatika work. - This saves time and avoids unnecessary communication - If you need to interact with the running application, use MCP tools (especially puppeteer-mcp) diff --git a/apps/herbatika/AGENTS.md b/apps/herbatika/AGENTS.md index 61aa8fc44a..255c7a3e51 100644 --- a/apps/herbatika/AGENTS.md +++ b/apps/herbatika/AGENTS.md @@ -1,31 +1,55 @@ -# Repository Guidelines +# Herbatika App Guidelines ## Scope & Precedence - This file applies to `apps/herbatika`. -- In this monorepo, the closest `AGENTS.md` wins (app/lib-level rules override broader ones). -- If work touches `libs/ui` or `libs/storefront-data`, follow their local `AGENTS.md` as source of truth. +- Root `AGENTS.md` still applies unless this file overrides it. +- If work starts from the repo root and touches Herbatika, read this file before editing `apps/herbatika`. +- If work touches `libs/ui` or `libs/storefront-data`, follow their local `AGENTS.md` as the source of truth for library code. +- Keep app-specific behavior in this app; promote behavior into a library only when the shared package has a real API/platform gap. ## Project Context - Stack: Next.js 16 e-shop (App Router), React 19, Tailwind v4 tokenized styling. - Main app code: `src/app`, `src/components`, `src/lib`, `src/styles/tokens`, `public`. +- Shared packages consumed by the app: `@techsio/ui-kit` and `@techsio/storefront-data`. - Design references: `local/screens/figma-2/`. +- You may read `local/` reference material, but do not edit ignored local workspace files unless the user explicitly asks. - Generated outputs must not be edited directly: `.next/`, `dist/`, `storybook-static/`. +## Skill Routing +- For app UI work that consumes `@techsio/ui-kit`, read `libs/ui/skills/ui-kit-workflow-orchestrator/SKILL.md` first. + - App usage normally routes to `component-usage-ux`, the exact component `*-usage` skill, `framework-consumer-integration`, `app-token-overrides`, and `app-ui-kit-audit`. + - Library authoring routes through `libs/ui/AGENTS.md` and the library authoring/token/storybook skills instead. +- For storefront data work involving `@techsio/storefront-data`, read `libs/storefront-data/skills/use-storefront-data-skills/SKILL.md` first. + - Pick the smallest relevant follow-up skill: setup, migration, catalog/product reads, auth, cart/checkout, SSR/query boundaries, cache/pagination, or release audit. +- Load only the relevant skill files for the task. Do not duplicate their full instructions in this app-level file. + ## UI & Token Guardrails - Use internal UI primitives/components first (`@techsio/ui-kit`), not native controls in app code. - Avoid raw `