Add test coverage checklist, report template, and stack matrix for ecommerce project

- Created a test coverage checklist to ensure comprehensive testing of backend and frontend components. - Added a test report template to standardize reporting on test execution results and gaps. - Introduced a test stack matrix to guide the selection of testing tools and frameworks for backend and frontend. - Established a skill for repairing failing tests, including a failure triage checklist and a test repair template. - Documented recommended MCP stack for ecommerce development with FastAPI and React/Next.js. - Developed a detailed README outlining the project structure, agent capabilities, and recommended workflows. - Compiled a comprehensive workflow guide detailing step-by-step commands for project setup, testing, and SEO implementation.
2026-05-20 18:09:24 +03:00
parent 5699670ea0
commit 2817cf8dc6
96 changed files with 2987 additions and 2888 deletions
@@ -0,0 +1,42 @@
+---
+name: ecommerce-brief-preparation
+description: 'Turn a rough ecommerce request into a normalized implementation brief. Use for clarifying requirements, asking targeted questions, and creating .ai/STORE-BRIEF.md before code generation.'
+argument-hint: 'Describe the store idea, constraints, and anything you already know'
+---
+# Ecommerce Brief Preparation
+
+## When to use
+- Starting a new ecommerce project from a rough or incomplete idea.
+- Normalizing a user request before scaffolding code.
+- Creating a single source of truth for storefront, backend, admin panel, and design decisions.
+
+## Goal
+- Ask only the high-impact questions that unblock architecture, UX, catalog, auth, cart, admin, integrations, and visual direction.
+- Convert the user's request into a structured file named .ai/STORE-BRIEF.md based on [STORE-BRIEF.md](./assets/store-brief-template.md).
+- Record explicit decisions, assumptions, and unresolved risks.
+
+## Required workflow
+1. Parse the initial user request.
+2. Use [discovery question bank](./assets/discovery-question-bank.md) to ask only the questions that materially affect implementation.
+3. Decide whether the target is monorepo or split repos.
+4. Normalize the result into .ai/STORE-BRIEF.md.
+5. If the project is split across repos, create a repo-local .ai/STORE-BRIEF.md for the current repo and document the counterpart repo responsibilities.
+6. Do not scaffold application code in this step unless the user explicitly asks for both steps in one run.
+
+## Output requirements for .ai/STORE-BRIEF.md
+- Project summary and business context.
+- Repo mode and delivery assumptions.
+- Storefront scope.
+- Admin panel or back office scope.
+- Auth and cart decisions.
+- Data model outline.
+- Integrations.
+- Visual direction and asset status.
+- Development questions answered.
+- Assumptions and open risks.
+- AGENTS.md creation plan.
+- Implementation phases for the build step.
+
+## References
+- [discovery question bank](./assets/discovery-question-bank.md)
+- [STORE-BRIEF template](./assets/store-brief-template.md)
@@ -0,0 +1,44 @@
+# Discovery Question Bank
+
+Ask only the questions that materially change implementation. Prefer short batches.
+
+## Product and business
+- What does the store sell and to whom.
+- Is this B2C, B2B, or mixed.
+- What market or country is the primary target.
+
+## Repository and delivery mode
+- Is the target a monorepo or split repos.
+- If split repos, which repo is being worked on now.
+
+## Storefront scope
+- Which pages are mandatory at launch.
+- Is customer auth required, optional, or excluded.
+- Is checkout needed, or is the target lead capture or quote request.
+- Should there be wishlist, favorites, recently viewed, reviews, blog, or CMS pages.
+
+## Cart and order model
+- Is guest cart required.
+- Should the cart persist across devices.
+- Are pricing, promos, or SSR constraints strong enough to require cookie or server-backed cart.
+
+## Admin and operations
+- Which admin modules are mandatory: catalog, orders, users, content, promos, settings, dashboards, roles.
+- Which staff roles are needed.
+- Are audit logs, bulk actions, import or export flows required.
+
+## Catalog and data
+- Which entities exist: categories, brands, collections, attributes, variants, bundles.
+- Are stock tracking, preorder, backorder, or dynamic pricing needed.
+
+## Integrations
+- Payments, delivery, CRM, ERP, analytics, email, storage, search.
+
+## Design and assets
+- What visual direction, brand tone, and references exist.
+- Are production-ready assets available.
+- If not, should external image-generation prompts be prepared.
+
+## Technical constraints
+- Preferred frontend stack if different from Next.js.
+- Localization, SEO, multi-currency, or compliance requirements.
@@ -0,0 +1,69 @@
+# STORE-BRIEF.md Template
+
+## 1. Project Summary
+- Store name or working title
+- Business model
+- Target audience
+- Market or geography
+
+## 2. Delivery Mode
+- Monorepo or split repos
+- Current repo scope
+- Assumptions about paired repo responsibilities when applicable
+
+## 3. Technical Stack
+- Backend stack
+- Frontend stack
+- Database
+- Hosting or infrastructure assumptions
+
+## 4. Storefront Scope
+- Required pages
+- Catalog behavior
+- Search, filters, sorting
+- Auth and account needs
+- Cart and checkout or lead flow
+
+## 5. Admin or Back Office Scope
+- Required modules
+- Roles and permissions
+- Operational workflows
+
+## 6. Data and Domain Model
+- Core entities
+- Relationships
+- Inventory, pricing, promotions, order states
+
+## 7. Integrations
+- Payments
+- Delivery
+- CRM or ERP
+- Analytics
+- Media or storage
+
+## 8. UX and Visual Direction
+- Brand tone
+- UI direction
+- Motion expectations
+- Mobile-first expectations
+
+## 9. Assets and Content
+- Existing assets
+- Missing assets
+- External image prompt needs
+
+## 10. Clarified Answers
+- List the questions asked and the confirmed decisions
+
+## 11. Assumptions and Risks
+- Assumptions used for implementation
+- Open issues that can affect scope or architecture
+
+## 12. AGENTS.md Plan
+- What AGENTS.md should include for this repo or monorepo
+
+## 13. Build Phases
+- Phase 1: contracts and schema
+- Phase 2: storefront
+- Phase 3: admin panel or back office
+- Phase 4: polish, assets, QA
@@ -0,0 +1,35 @@
+---
+name: ecommerce-build-from-brief
+description: 'Build a full ecommerce project from .ai/STORE-BRIEF.md. Use for generating the FastAPI backend, React or Next.js frontend, admin panel, AGENTS.md, and delivery plan from a normalized brief file.'
+argument-hint: 'Optionally mention which parts to build first if .ai/STORE-BRIEF.md already exists'
+---
+# Ecommerce Build From Brief
+
+## When to use
+- Building a new ecommerce project after requirements have been normalized.
+- Continuing implementation from an approved .ai/STORE-BRIEF.md.
+- Generating storefront, backend, and admin scope from a single source of truth.
+
+## Preconditions
+- .ai/STORE-BRIEF.md should exist.
+- If it is missing, create it first using the ecommerce brief preparation workflow unless the user explicitly wants both steps in one run.
+
+## Required workflow
+1. Read .ai/STORE-BRIEF.md first.
+2. Create or update `AGENTS.md` from the brief before application code.
+3. Before any serious backend or frontend modification, create a timestamped snapshot under .backup/ and keep that folder append-only.
+4. Validate that the brief covers the sections in [build checklist](./assets/build-checklist.md).
+5. Establish a scalable folder structure for backend and frontend before adding large amounts of code.
+6. Build backend contracts and schema first.
+7. Build storefront flows next.
+8. Build admin panel or back office after the storefront contracts are stable.
+9. Finish with QA states, responsive behavior, motion, and asset handling.
+
+## Constraints
+- Do not contradict .ai/STORE-BRIEF.md without surfacing the conflict.
+- Do not skip admin scope unless the brief explicitly excludes it.
+- Do not leave core commerce flows as placeholders when the brief already defines them.
+- Keep models, services, config, routing, UI, and integration code in dedicated folders instead of mixing layers.
+
+## References
+- [build checklist](./assets/build-checklist.md)
@@ -0,0 +1,17 @@
+# Build Checklist
+
+Before implementation, confirm that .ai/STORE-BRIEF.md contains enough detail for:
+
+- Repo mode and current repo responsibilities.
+- Backend stack and database choice.
+- Frontend stack and rendering assumptions.
+- Storefront pages and flows.
+- Auth model and cart model.
+- Admin modules and staff roles.
+- Catalog entities and filtering model.
+- Order or lead flow.
+- Integrations and external dependencies.
+- Visual direction and asset status.
+- AGENTS.md plan.
+
+If one of these is materially missing, ask a focused follow-up question or record the implementation assumption before building.
@@ -0,0 +1,61 @@
+---
+name: ecommerce-code-review
+description: 'Perform a strict full-project code review for an ecommerce codebase. Use for harsh review of Python, React, architecture, performance, dependency hygiene, modern language features, and configuration-aware quality rules based on pyproject, package.json, and installed versions.'
+argument-hint: 'Describe whether to review the whole project or focus on backend, frontend, performance, architecture, or dependency quality'
+---
+# Ecommerce Code Review
+
+## When to use
+- Reviewing a whole ecommerce project before release.
+- Auditing an existing codebase for quality, maintainability, performance, dependency issues, and outdated patterns.
+- Enforcing strong standards for Python backend and React frontend code.
+
+## Goal
+- Produce a harsh, technically defensible review.
+- Prefer findings over praise.
+- Create or update .ai/CODE-REVIEW.md with prioritized findings, risks, and remediation steps.
+
+## Review stance
+- Be strict.
+- Prefer root-cause findings over stylistic nitpicks.
+- Check current project configuration before judging the code.
+- Use current framework and language capabilities when the installed version supports them.
+- If version-specific guidance matters, verify it against official documentation or authoritative up-to-date sources.
+
+## Required workflow
+1. Read `pyproject.toml`, `package.json`, `tsconfig.json`, lint configs, and other relevant project configs when they exist.
+2. Detect the configured Python quality toolchain using [python quality matrix](./assets/python-quality-matrix.md).
+3. Detect the React, Next.js, and TypeScript setup using [react review matrix](./assets/react-review-matrix.md).
+4. Review the codebase against [project review checklist](./assets/project-review-checklist.md).
+5. Classify issues with [severity rubric](./assets/severity-rubric.md).
+6. Write or update .ai/CODE-REVIEW.md using [code review template](./assets/code-review-template.md).
+7. Keep the final report findings-first, with concrete fixes and explicit assumptions.
+
+## Python review expectations
+- Respect the configured checker in `pyproject.toml`.
+- If `mypy` is configured, review against `mypy --strict` expectations unless the project explicitly relaxes rules.
+- If `ty` is configured, review against `ty` expectations and the project's chosen strictness.
+- If `ruff` is configured, review import hygiene, complexity, unsafe patterns, and style issues that matter for maintainability.
+- If `deptry` is configured, review dependency hygiene, unused packages, misplaced dev dependencies, and import consistency.
+- If the project is missing these checks and the user is building new code, recommend adding a coherent baseline.
+- Prefer modern Python features only when supported by the configured Python version.
+
+## React review expectations
+- Code should be readable, explicit, and easy for a human developer to modify.
+- Prefer clear component boundaries, descriptive prop names, predictable state flow, and minimal incidental abstraction.
+- Avoid clever patterns that obscure behavior.
+- Review hooks usage, render stability, accessibility, data fetching boundaries, loading and error states, and app-structure clarity.
+- When the installed React or Next.js version supports newer language or framework features, check whether their use would simplify or strengthen the code.
+- Do not force trendy APIs if they reduce clarity or conflict with the current architecture.
+
+## Outputs
+- .ai/CODE-REVIEW.md.
+- Findings ordered by severity.
+- Explicit follow-up plan.
+
+## References
+- [project review checklist](./assets/project-review-checklist.md)
+- [severity rubric](./assets/severity-rubric.md)
+- [python quality matrix](./assets/python-quality-matrix.md)
+- [react review matrix](./assets/react-review-matrix.md)
+- [code review template](./assets/code-review-template.md)
@@ -0,0 +1,52 @@
+# CODE-REVIEW.md Template
+
+## 1. Review Scope
+- Reviewed repository or area
+- Config files inspected
+- Runtime and toolchain assumptions
+
+## 2. Executive Summary
+- Overall quality assessment
+- Highest-risk areas
+- Biggest maintainability concerns
+
+## 3. Findings
+
+### Critical
+- Findings
+
+### High
+- Findings
+
+### Medium
+- Findings
+
+### Low
+- Findings
+
+## 4. Python Quality Notes
+- Type system and strictness
+- Tooling alignment
+- Dependency hygiene
+- Modern Python usage
+
+## 5. React and Frontend Notes
+- Readability and maintainability
+- State and effects
+- Performance-sensitive areas
+- Modern framework usage
+
+## 6. Configuration and Tooling Notes
+- pyproject quality rules
+- frontend config quality
+- gaps and inconsistencies
+
+## 7. Testing and Risk Gaps
+- Missing tests
+- weak assertions
+- release risks
+
+## 8. Recommended Fix Order
+- Immediate blockers
+- short-term fixes
+- structural cleanup
@@ -0,0 +1,50 @@
+# Project Review Checklist
+
+## Architecture and maintainability
+- Module boundaries are clear.
+- Cross-layer dependencies are controlled.
+- The code does not hide business logic in the wrong layer.
+- Naming is precise and stable.
+- Public interfaces are coherent.
+
+## Python backend
+- Type coverage and strictness align with project configuration.
+- Async and I/O boundaries are explicit and safe.
+- Data validation and domain modeling are coherent.
+- Error handling is consistent.
+- Dependency usage is justified and clean.
+- Imports, complexity, and dead code align with configured linters.
+- Modern Python features are used when they improve the code and match the configured interpreter version.
+
+## React or Next.js frontend
+- Components are readable and easy to modify.
+- State ownership is clear.
+- Derived state and side effects are not overcomplicated.
+- Data fetching and caching strategy are coherent.
+- Accessibility, loading states, empty states, and error states are covered.
+- Expensive renders, unstable props, and unnecessary abstractions are avoided.
+- Newer framework features are used where they meaningfully improve code quality and are supported by the installed version.
+
+## Performance and optimization
+- Hot paths are identified.
+- No obvious over-fetching or over-rendering.
+- Expensive work is not repeated without reason.
+- Assets and bundles are handled sensibly.
+
+## Dependency and configuration hygiene
+- Dependencies match actual imports and usage.
+- Dev and runtime dependencies are separated properly.
+- Tooling configuration is coherent.
+- The code follows the quality rules implied by the configuration files.
+
+## Security and reliability
+- Sensitive flows are validated.
+- Auth and permission checks are consistent.
+- Dangerous defaults are avoided.
+- Error handling does not leak implementation details.
+
+## Testing and verification
+- Tests cover high-risk business flows.
+- Assertions are meaningful.
+- Cleanup and fixture behavior are reliable.
+- Gaps in test coverage are identified honestly.
@@ -0,0 +1,26 @@
+# Python Quality Matrix
+
+## Configuration detection
+- Read `pyproject.toml` first.
+- Detect the configured Python version.
+- Detect `mypy`, `ty`, `ruff`, `deptry`, `pytest`, and formatter configuration.
+
+## Review rules
+- If `mypy` is configured, check the actual options before judging missing annotations or strictness violations.
+- If `ty` is configured, use its configured expectations and error model.
+- If both exist, respect whichever toolchain the project clearly treats as authoritative, and flag inconsistent duplication.
+- If `ruff` is configured, review for meaningful rule violations, not cosmetic churn.
+- If `deptry` is configured, verify dependency placement, unused dependencies, and hidden transitive reliance.
+
+## Modern Python usage
+- Use modern typing syntax only when the configured Python version supports it.
+- Prefer `typing.Self`, `typing.TypeAliasType`, `typing.override`, `collections.abc` imports, `match`, `enum.StrEnum`, dataclass slots, and other newer features only when they improve clarity and compatibility.
+- Do not suggest a newer language feature that the configured interpreter cannot run.
+
+## Common harsh checks
+- Weak or missing type boundaries.
+- Hidden `Any` spread.
+- Async misuse.
+- Leaky ORM or transport models.
+- Overly dynamic code that defeats static analysis.
+- Wrong dependency classification.
@@ -0,0 +1,28 @@
+# React Review Matrix
+
+## Configuration detection
+- Read `package.json`, `tsconfig.json`, ESLint config, framework config, and build setup.
+- Detect React version, Next.js version, TypeScript version, and testing setup.
+
+## Readability rules
+- Components should be easy to scan.
+- Props should be explicit and well named.
+- Business logic should not be buried in JSX noise.
+- Avoid deeply nested conditional rendering when a clearer structure would help.
+- Prefer predictable state flow over clever abstractions.
+
+## Modern React usage
+- Use modern React and framework features only when the installed version supports them and they improve maintainability.
+- Check whether newer APIs such as `useEffectEvent`, transitions, server components, or framework-native data loading would simplify the code.
+- Do not insist on `useMemo` or `useCallback` unless they are justified.
+- Avoid stale patterns if the installed version provides a clearer and safer replacement.
+
+## Harsh review checks
+- Unclear ownership of state.
+- Effect misuse.
+- Derived state bugs.
+- Excessive prop drilling when a better structure exists.
+- Over-componentization that hurts readability.
+- Poor separation between UI, data, and business rules.
+- Missing loading, empty, and error states.
+- Avoidable render churn and unstable object creation in hot paths.
@@ -0,0 +1,24 @@
+# Severity Rubric
+
+## Critical
+- Likely to cause broken behavior, data loss, security issues, or severe production instability.
+- Major architecture flaw affecting core flows.
+
+## High
+- Strong risk of bugs, regressions, maintainability collapse, or significant performance issues.
+- Serious mismatch with configured quality rules.
+
+## Medium
+- Clear quality issue or missed optimization that should be fixed, but not an immediate release blocker.
+
+## Low
+- Smaller maintainability issues, cleanup, or polish items.
+
+## Finding format
+- Severity
+- Area
+- Location
+- Problem
+- Why it matters
+- Recommended fix
+- Confidence or assumptions when relevant
@@ -0,0 +1,57 @@
+---
+name: ecommerce-seo-implementation
+description: 'Implement SEO directly in an ecommerce codebase. Use for applying .ai/SEO-PLAN.md in code: metadata, schema markup, canonicals, sitemap, robots, internal linking, page templates, and crawl or index rules.'
+argument-hint: 'Describe whether to apply the full SEO plan or only specific SEO areas such as metadata, schema, category SEO, or technical SEO'
+---
+# Ecommerce SEO Implementation
+
+## When to use
+- Applying an existing .ai/SEO-PLAN.md to a real ecommerce codebase.
+- Implementing SEO directly in frontend, backend, routing, templates, schema, metadata, and technical platform behavior.
+- Converting SEO recommendations into production-ready code and content structure.
+
+## Goal
+- Execute SEO changes in code, not just describe them.
+- Use .ai/SEO-PLAN.md as the source of truth when it exists.
+- If .ai/SEO-PLAN.md is missing, derive the minimum required context from .ai/STORE-BRIEF.md or ask to prepare the SEO strategy first.
+
+## Preconditions
+- Prefer having .ai/SEO-PLAN.md.
+- If .ai/SEO-PLAN.md is absent but the user explicitly wants implementation now, create a compact implementation assumption set from .ai/STORE-BRIEF.md and state the risk.
+
+## Required workflow
+1. Read .ai/SEO-PLAN.md first when it exists.
+2. Read .ai/STORE-BRIEF.md and AGENTS.md if they exist to align implementation with the product scope and repo rules.
+3. Before serious backend or frontend edits, create a timestamped snapshot under .backup/ and keep that folder append-only.
+4. Audit the current codebase against [implementation checklist](./assets/implementation-checklist.md).
+5. Map required changes by page type using [page type SEO matrix](./assets/page-type-seo-matrix.md).
+6. Implement technical SEO behavior using [technical execution map](./assets/technical-execution-map.md).
+7. Apply metadata, canonicals, robots policy, sitemap generation, schema markup, internal linking, and template-level SEO content where appropriate.
+8. Validate that SEO changes do not create index bloat, duplicate pages, or structured data inconsistencies.
+9. Report what was implemented, what remains manual, and what should be measured after deployment.
+
+## What this skill should implement
+- Metadata systems for homepage, category, collection, brand, product, article, and utility pages.
+- Canonical and noindex rules for filters, sort states, pagination, search results, cart, account, and utility routes.
+- XML sitemap generation and robots policy.
+- Structured data for organization, website, breadcrumbs, item lists, products, articles, FAQs, and local business when applicable.
+- Breadcrumbs and internal linking modules.
+- Category and product template support for SEO copy, FAQs, and content blocks when the architecture allows it.
+- Image SEO basics: alt text support, responsive image behavior, and index-safe media handling.
+- Performance-sensitive SEO work where it is practical within the current codebase.
+
+## Constraints
+- Do not generate spammy or keyword-stuffed copy.
+- Do not index low-value filter combinations by default.
+- Do not implement fake ratings, fake reviews, or misleading schema.
+- Do not add SEO code that conflicts with the project routing or rendering model.
+
+## Outputs
+- Implemented code changes in the project.
+- Optional update to .ai/SEO-PLAN.md when implementation assumptions change.
+- Clear summary of completed SEO work, remaining gaps, and validation steps.
+
+## References
+- [implementation checklist](./assets/implementation-checklist.md)
+- [page type SEO matrix](./assets/page-type-seo-matrix.md)
+- [technical execution map](./assets/technical-execution-map.md)
@@ -0,0 +1,20 @@
+# SEO Implementation Checklist
+
+Before changing code, confirm the current project has or needs:
+
+- Metadata generation by page type.
+- Canonical tags and noindex controls.
+- XML sitemap generation.
+- robots.txt policy.
+- Open Graph and social metadata.
+- Structured data by page type.
+- Breadcrumb markup and UI breadcrumbs.
+- Internal linking modules.
+- Category intro content or SEO content blocks.
+- Product content sections such as FAQs, specs, care, compatibility, or shipping info.
+- Search result and filter route indexation rules.
+- Pagination or infinite-scroll SEO handling.
+- Image component support for alt text, size hints, and optimized delivery.
+- Performance-sensitive rendering for money pages.
+
+If any item is missing, decide whether to implement it now, defer it, or document it as blocked by architecture.
@@ -0,0 +1,31 @@
+# Page Type SEO Matrix
+
+## Homepage
+- Brand-level title and description.
+- Organization and WebSite schema.
+- Clear links to priority categories and collections.
+
+## Category and collection pages
+- Unique title, meta description, H1, and intro copy strategy.
+- Breadcrumbs.
+- ItemList schema when appropriate.
+- Canonical rules for filters and sort states.
+- Internal links to related categories and featured products.
+
+## Brand pages
+- Brand-specific copy and linked collections.
+- Canonical protection against overlap with categories or collections.
+
+## Product pages
+- Product schema with real offer data.
+- Rich metadata with variant-aware handling.
+- FAQ or support content blocks when relevant.
+- Internal links to related products and parent categories.
+
+## Editorial or guide pages
+- Article schema when relevant.
+- Strong internal links into commercial pages.
+- Intent-aligned headings and content sections.
+
+## Utility pages
+- Cart, account, checkout, login, internal search, and thin utilities should usually be noindex.
@@ -0,0 +1,29 @@
+# Technical Execution Map
+
+## Metadata layer
+- Define where titles, descriptions, canonicals, Open Graph, and robots directives are generated.
+- Prefer centralized page-type SEO configuration over scattered hardcoded tags.
+
+## Routing and index control
+- Ensure low-value routes can emit noindex or canonical rules.
+- Align filtered routes, sorted routes, search routes, and pagination with the SEO policy.
+
+## Structured data layer
+- Use JSON-LD generated from real page data.
+- Keep schema close to the page data source to reduce drift.
+
+## Sitemap and robots
+- Generate sitemaps only for valuable indexable URLs.
+- Exclude duplicates, noindex pages, and thin utility pages.
+
+## Internal linking systems
+- Breadcrumbs, related content blocks, category cross-links, product recommendations, and editorial links should be intentional and reusable.
+
+## Performance-sensitive work
+- Protect LCP, INP, and CLS while adding SEO features.
+- Avoid heavy client-only SEO logic for key landing pages.
+
+## Validation
+- Check for duplicate titles or duplicate canonicals.
+- Check that schema matches visible content.
+- Check that robots and sitemap policy are coherent.
@@ -0,0 +1,56 @@
+---
+name: ecommerce-seo-review
+description: 'Review implemented ecommerce SEO and produce a structured findings report. Use for auditing metadata, schema, canonicals, sitemaps, robots rules, internal linking, indexation, Core Web Vitals risks, and content-template SEO after changes are shipped.'
+argument-hint: 'Describe whether to review the whole site or specific page types such as categories, products, metadata, or technical SEO'
+---
+# Ecommerce SEO Review
+
+## When to use
+- After applying SEO changes in code.
+- After launching a new ecommerce site or a major SEO release.
+- When you need a structured list of SEO gaps, risks, regressions, and missed opportunities.
+
+## Goal
+- Audit the current project state against .ai/SEO-PLAN.md, .ai/STORE-BRIEF.md, and the live codebase.
+- Produce .ai/SEO-REVIEW.md with prioritized findings, risks, and next actions.
+- Focus on practical issues that affect crawling, indexation, relevance, page quality, internal linking, and performance.
+
+## Preconditions
+- Prefer having .ai/SEO-PLAN.md when the project has already gone through the SEO strategy step.
+- If .ai/SEO-PLAN.md is missing, review the current site from code and documented assumptions instead of blocking.
+
+## Required workflow
+1. Read .ai/SEO-PLAN.md first when it exists.
+2. Read .ai/STORE-BRIEF.md and AGENTS.md if they exist.
+3. Audit the codebase against [SEO review checklist](./assets/seo-review-checklist.md).
+4. Score issues using [severity rubric](./assets/severity-rubric.md).
+5. Write or update .ai/SEO-REVIEW.md using [SEO review template](./assets/seo-review-template.md).
+6. Group findings into critical, high, medium, and low priority.
+7. Separate confirmed issues from assumptions or areas that require runtime validation.
+8. End with a remediation plan ordered by business impact and engineering cost.
+
+## Review coverage
+- Metadata systems and missing or duplicate titles and descriptions.
+- Canonical logic, noindex logic, and index-bloat risks.
+- Sitemap and robots policy.
+- Schema markup accuracy and visible-content alignment.
+- Category, product, brand, collection, and editorial template SEO.
+- Internal linking and breadcrumbs.
+- Search, filter, sort, pagination, cart, account, and utility route handling.
+- Performance and Core Web Vitals risks visible from the codebase.
+- Content depth and thin-page risks where they are inferable from templates and data flow.
+
+## Constraints
+- Do not claim runtime behavior that cannot be confirmed from code.
+- Clearly mark assumptions, unknowns, and items that need browser or production validation.
+- Prefer actionable findings over generic SEO advice.
+
+## Outputs
+- .ai/SEO-REVIEW.md.
+- A prioritized findings list.
+- A short remediation plan with quick wins and structural fixes.
+
+## References
+- [SEO review checklist](./assets/seo-review-checklist.md)
+- [severity rubric](./assets/severity-rubric.md)
+- [SEO review template](./assets/seo-review-template.md)
@@ -0,0 +1,40 @@
+# SEO Review Checklist
+
+## Metadata
+- Titles are unique on strategic page types.
+- Meta descriptions are present where useful and not duplicated at scale.
+- Open Graph and social metadata are present for key public pages.
+
+## Crawl and indexation
+- Canonicals exist where duplication risk is real.
+- Noindex is applied to low-value routes such as cart, account, internal search, and thin utility pages when appropriate.
+- Filter, sort, and pagination behavior aligns with the SEO plan.
+- Sitemap generation excludes noindex and low-value URLs.
+- robots.txt does not accidentally block important content.
+
+## Structured data
+- JSON-LD exists where intended.
+- Schema matches visible content.
+- Product, offer, breadcrumb, article, FAQ, and organization schema are used correctly.
+- There are no fake reviews, misleading offers, or invalid structured data assumptions.
+
+## Page templates
+- Category and collection templates support unique SEO fields and meaningful content.
+- Product templates support strong metadata, support content, and structured data.
+- Brand and editorial pages have distinct intent and do not cannibalize key landing pages.
+
+## Internal linking
+- Breadcrumbs exist where expected.
+- Important categories are linked from strong pages.
+- Product and editorial pages support relevant internal links.
+- Strategic landing pages are not orphaned.
+
+## Performance-sensitive SEO
+- Key pages are not overloaded with client-only SEO logic.
+- There are obvious protections against large layout shifts and heavy above-the-fold payloads.
+- Media and fonts do not create avoidable search-quality regressions.
+
+## Unknowns to flag
+- Runtime rendering behavior.
+- Search Console or analytics data not visible in code.
+- Production-only redirects, robots headers, CDN behavior, and sitemap deployment details.
@@ -0,0 +1,53 @@
+# SEO-REVIEW.md Template
+
+## 1. Review Scope
+- Reviewed area
+- Inputs used: .ai/SEO-PLAN.md, .ai/STORE-BRIEF.md, AGENTS.md, codebase files
+- Limits of the review
+
+## 2. Executive Summary
+- Overall SEO implementation quality
+- Biggest risks
+- Biggest missed opportunities
+
+## 3. Findings
+
+### Critical
+- List critical findings
+
+### High
+- List high-priority findings
+
+### Medium
+- List medium-priority findings
+
+### Low
+- List low-priority findings
+
+## 4. Page-Type Notes
+- Homepage
+- Categories and collections
+- Product pages
+- Brand pages
+- Editorial or support pages
+- Utility pages
+
+## 5. Technical SEO Notes
+- Metadata system
+- Canonicals and noindex
+- Sitemap and robots
+- Structured data
+- Internal linking
+- Performance-sensitive SEO
+
+## 6. Unknowns and Runtime Validation
+- Items that require browser validation
+- Items that require production or Search Console data
+
+## 7. Remediation Plan
+- Quick wins
+- Medium lifts
+- Structural fixes
+
+## 8. Suggested Next Validation Steps
+- What to test after fixes are applied
@@ -0,0 +1,26 @@
+# Severity Rubric
+
+## Critical
+- Likely to block crawling or indexation of important commercial pages.
+- Likely to create large-scale duplicate or canonical errors.
+- Likely to break structured data trust on strategic templates.
+
+## High
+- Likely to materially reduce rankings, CTR, or discoverability on important page groups.
+- Affects high-value categories, product templates, or core internal-link systems.
+
+## Medium
+- Noticeable quality gap or missed opportunity, but not a severe blocker.
+- Often template-level improvements, partial metadata gaps, or incomplete linking coverage.
+
+## Low
+- Nice-to-have improvements, polish items, or issues with limited SEO impact.
+
+## Finding format
+- Severity
+- Area
+- Affected page type or module
+- What is wrong
+- Why it matters
+- Recommended fix
+- Validation note if runtime confirmation is still needed
@@ -0,0 +1,53 @@
+---
+name: ecommerce-seo-strategy
+description: 'Plan and improve ecommerce SEO across technical SEO, information architecture, category strategy, product pages, schema markup, metadata, internal linking, Core Web Vitals, and measurement. Use for SEO audits, SEO planning, and organic growth work on online stores.'
+argument-hint: 'Describe the store, market, target pages, and whether this is a new build or an existing site'
+---
+# Ecommerce SEO Strategy
+
+## When to use
+- Planning SEO for a new ecommerce site before build.
+- Auditing an existing storefront that needs stronger organic visibility.
+- Defining technical SEO, content architecture, schema, metadata, and internal linking.
+- Improving category, product, brand, collection, blog, and help content for search intent.
+
+## Goal
+- Maximize sustainable organic visibility for the site.
+- Produce implementation-ready SEO decisions instead of vague advice.
+- Create or update .ai/SEO-PLAN.md when the task is substantial.
+
+## Important constraint
+- Do not promise a number one ranking. Search performance depends on competition, domain authority, backlinks, history, and market conditions.
+- Optimize for the strongest possible technical and content foundation, measurable growth, and durable search coverage.
+
+## Required workflow
+1. Read .ai/STORE-BRIEF.md if it exists. If not, gather enough business and market context from the user or repository.
+2. Determine the market, audience, geography, revenue model, and search intent mix.
+3. Build a keyword and intent map using [keyword intent framework](./assets/keyword-intent-framework.md).
+4. Define search landing pages and information architecture for home, categories, subcategories, collections, brands, products, guides, FAQs, and support content.
+5. Review or propose technical SEO using [technical SEO checklist](./assets/technical-seo-checklist.md).
+6. Review or propose structured data using [schema markup map](./assets/schema-markup-map.md).
+7. Review or propose internal linking using [internal linking playbook](./assets/internal-linking-playbook.md).
+8. Define measurement using [SEO measurement framework](./assets/seo-measurement-framework.md).
+9. Create or update .ai/SEO-PLAN.md using [SEO plan template](./assets/seo-plan-template.md) when the work is broad enough.
+10. Prioritize recommendations into quick wins, medium lifts, and structural work.
+
+## Coverage expectations
+- Technical SEO: crawlability, indexability, canonicals, noindex strategy, redirects, sitemaps, robots, rendering, structured data, image SEO, faceted navigation, pagination behavior, hreflang when needed, page speed and Core Web Vitals.
+- Commercial SEO: category taxonomy, filter landing page policy, product detail optimization, collection and brand pages, price and availability signals, review strategy, seasonal and campaign landing pages.
+- Content SEO: metadata, headings, copy structure, FAQs, guides, comparison pages, supporting content clusters, entity coverage, and user intent alignment.
+- UX signals that affect SEO: mobile-first layouts, performance, layout stability, media optimization, readable content hierarchy, and clean navigation.
+- Measurement: rankings are not enough; include index coverage, impressions, CTR, non-brand traffic, landing page performance, conversions, and page group health.
+
+## Outputs
+- .ai/SEO-PLAN.md for broad SEO work.
+- Specific code or content implementation tasks when the user wants execution.
+- Clear prioritization by business impact and engineering cost.
+
+## References
+- [SEO plan template](./assets/seo-plan-template.md)
+- [keyword intent framework](./assets/keyword-intent-framework.md)
+- [technical SEO checklist](./assets/technical-seo-checklist.md)
+- [schema markup map](./assets/schema-markup-map.md)
+- [internal linking playbook](./assets/internal-linking-playbook.md)
+- [SEO measurement framework](./assets/seo-measurement-framework.md)
@@ -0,0 +1,18 @@
+# Internal Linking Playbook
+
+## Core principles
+- Link from high-authority pages to priority commercial pages.
+- Use consistent anchor language tied to real user phrasing.
+- Keep internal links helpful for users, not mechanically stuffed.
+
+## Required link systems
+- Global navigation to top categories and collections.
+- Breadcrumbs on category, collection, brand, and product pages.
+- Related products and related categories modules.
+- Editorial links from guides, FAQs, and comparison content to money pages.
+- Cross-links between complementary categories when intent overlaps.
+
+## Priority rules
+- Important categories should be reachable in few clicks.
+- New seasonal or campaign pages need fast internal linking support.
+- Orphan pages are not acceptable for strategic landing pages.
@@ -0,0 +1,27 @@
+# Keyword Intent Framework
+
+## Intent buckets
+- Transactional: buy-now, price, delivery, in-stock, order intent.
+- Commercial investigation: best, compare, review, top, versus, alternatives.
+- Informational: how to choose, how to use, care guides, ingredient guides, compatibility guides.
+- Navigational and brand: brand, collection, store name, product line, branded queries.
+
+## Mapping rules
+- Homepage should target broad category and brand-level demand, not all keywords.
+- Category and subcategory pages should target the highest-volume commercial and transactional themes.
+- Product pages should target explicit product, variant, model, SKU, brand, and long-tail modifiers.
+- Guide and FAQ pages should support commercial pages and capture informational demand.
+
+## Output fields
+- Keyword theme
+- Primary intent
+- Suggested landing page type
+- Funnel stage
+- Priority
+- Required content blocks
+- Internal link targets
+
+## Ecommerce caution points
+- Do not create indexable pages for every low-value filter combination.
+- Avoid cannibalization between category pages, collection pages, and blog content.
+- Prefer strong category and brand hubs over thin near-duplicate pages.
@@ -0,0 +1,19 @@
+# Schema Markup Map
+
+## By page type
+- Homepage: Organization, WebSite, SearchAction when appropriate.
+- Category or collection pages: ItemList and BreadcrumbList when the page meaningfully lists products.
+- Product pages: Product, Offer, AggregateRating, Review when the data is real and visible.
+- FAQ sections: FAQPage only when the content is actually presented to users.
+- Editorial pages: Article or BlogPosting where appropriate.
+- Store or contact pages: LocalBusiness when location data exists and is accurate.
+
+## Requirements
+- Only mark up data that is visible and truthful.
+- Keep price, availability, brand, SKU, and rating data synchronized with visible content.
+- Validate JSON-LD output after implementation.
+
+## Ecommerce cautions
+- Do not fabricate ratings or reviews.
+- Do not mark every accordion as FAQPage unless it truly qualifies.
+- Keep structured data aligned with canonical URLs and page intent.
@@ -0,0 +1,25 @@
+# SEO Measurement Framework
+
+## Primary KPIs
+- Non-brand clicks and impressions.
+- Organic sessions by landing page group.
+- Organic conversion rate.
+- Revenue or lead value from organic traffic.
+- Indexed page quality by page type.
+
+## Secondary KPIs
+- CTR on major page templates.
+- Average position for priority keyword groups.
+- Core Web Vitals on category and product pages.
+- Share of traffic landing on strategic commercial pages versus weak informational pages.
+
+## Monitoring dimensions
+- By page type: homepage, category, collection, brand, product, content, help.
+- By market or locale.
+- By device.
+- By branded versus non-branded traffic.
+
+## Reporting approach
+- Separate quick wins from structural improvements.
+- Measure before and after major releases.
+- Track technical fixes, content launches, and internal linking changes as distinct interventions.
@@ -0,0 +1,84 @@
+# SEO-PLAN.md Template
+
+## 1. Business Context
+- Site or brand name
+- Market and geography
+- Audience segments
+- Revenue model and priority categories
+
+## 2. SEO Objectives
+- Primary growth goals
+- Non-brand traffic goals
+- Conversion goals from organic traffic
+- Constraints and dependencies
+
+## 3. Search Intent Model
+- Transactional intents
+- Commercial investigation intents
+- Informational intents
+- Brand and navigational intents
+
+## 4. Keyword and Page Mapping
+- Homepage target themes
+- Category pages
+- Subcategory or collection pages
+- Brand pages
+- Product pages
+- Editorial or guide pages
+- FAQ and support pages
+
+## 5. Information Architecture
+- Planned taxonomy
+- URL rules
+- Faceted navigation policy
+- Canonicalization rules
+- Pagination or infinite scroll handling
+
+## 6. On-Page SEO Requirements
+- Title patterns
+- Meta description patterns
+- Heading rules
+- Intro copy rules for category pages
+- Product page content blocks
+- FAQ and support content rules
+
+## 7. Structured Data Plan
+- Required schema types by page type
+- Required properties
+- Validation notes
+
+## 8. Technical SEO Plan
+- Indexing and crawl rules
+- Robots and sitemaps
+- Redirect policy
+- Performance and Core Web Vitals goals
+- Image optimization rules
+- Renderability and JavaScript considerations
+
+## 9. Internal Linking Strategy
+- Global navigation
+- Breadcrumbs
+- Related products
+- Category cross-links
+- Editorial to commercial links
+
+## 10. Content Expansion Plan
+- High-priority landing pages
+- Cluster content ideas
+- Seasonal and campaign opportunities
+
+## 11. Measurement and Reporting
+- KPIs
+- Dashboard inputs
+- Search Console tracking
+- Analytics events or goals
+
+## 12. Priority Roadmap
+- Quick wins
+- Medium lifts
+- Structural work
+
+## 13. Risks and Assumptions
+- Market competition risks
+- Platform constraints
+- Content or asset gaps
@@ -0,0 +1,32 @@
+# Technical SEO Checklist
+
+## Crawl and indexation
+- Confirm indexable money pages and noindex low-value or duplicate pages.
+- Define robots policy for search, cart, account, internal filters, and thin utility pages.
+- Ensure XML sitemaps exist for key page groups and exclude noindex URLs.
+
+## Canonicalization and duplication
+- Define canonicals for categories, filtered states, sorting states, pagination, and product variants.
+- Prevent duplicate content across collection pages, brand pages, and promotional landings.
+
+## Rendering and architecture
+- Ensure key content is available in server-rendered or reliably rendered HTML.
+- Confirm crawlers can see titles, headings, main content, structured data, and internal links.
+
+## Performance and Core Web Vitals
+- Optimize LCP, INP, and CLS on category and product pages.
+- Control image size, font loading, script weight, and third-party bloat.
+- Avoid layout shifts from banners, lazy media, and client-only widgets.
+
+## Media and assets
+- Use descriptive image filenames where practical.
+- Provide alt text with functional accuracy, not keyword stuffing.
+- Generate responsive image variants and preload only what is truly critical.
+
+## Navigation and page discovery
+- Ensure deep categories and products are reachable through internal links.
+- Use breadcrumbs and clear taxonomy-based navigation.
+
+## International and local SEO when relevant
+- Use hreflang carefully only when multiple locales truly exist.
+- Align locale routing, canonicals, translated metadata, and sitemap structure.
@@ -0,0 +1,28 @@
+---
+name: ecommerce-store-evolution
+description: 'Extend or refactor an existing ecommerce project with FastAPI, React, Next.js, admin panel, catalog changes, AGENTS.md updates, and safer rollout planning.'
+argument-hint: 'Describe the current project and the features or refactor you need'
+---
+# Ecommerce Store Evolution
+
+## When to use
+- Extending an existing online store.
+- Adding a new admin module, catalog flow, account area, or backend capability.
+- Refactoring a commerce codebase without losing its current conventions.
+
+## Procedure
+1. Audit the existing repo and compare it with [extension checklist](./assets/extension-checklist.md).
+2. Create or update AGENTS.md if the repo lacks clear delivery rules.
+3. Before serious backend or frontend edits, create a timestamped snapshot under .backup/ and never modify or delete older backup entries.
+4. Preserve stable patterns and change only what is necessary.
+5. Write a small implementation plan using [rollout plan template](./assets/rollout-plan-template.md).
+6. Implement backend and frontend changes with regression awareness.
+
+## Architecture rule
+- New backend code should go into the proper layers such as routers, models, schemas, services, repositories, config, and tests.
+- New frontend code should go into the proper layers such as app or routes, pages, features, entities, shared components, api or services, hooks, config, styles, and tests.
+- If the current project is too flat or mixed, improve the structure incrementally instead of adding more chaos.
+
+## References
+- [extension checklist](./assets/extension-checklist.md)
+- [rollout plan template](./assets/rollout-plan-template.md)
@@ -0,0 +1,10 @@
+# Extension Checklist
+
+- What already exists in the storefront.
+- What already exists in the admin panel or back office.
+- Current auth model and role system.
+- Current cart behavior and checkout assumptions.
+- Current backend modules, migrations, and API style.
+- Current design system or UI conventions.
+- Which parts can be extended safely versus which parts need refactoring.
+- Which gaps must be documented in AGENTS.md.
@@ -0,0 +1,18 @@
+# Rollout Plan Template
+
+## Goal
+- What business or UX capability is being added or changed.
+
+## Existing constraints
+- Current architecture limits.
+- Current data contract limits.
+
+## Change plan
+- Backend changes.
+- Frontend storefront changes.
+- Admin or back office changes.
+- Migration or seed changes.
+
+## Verification
+- Manual flows to verify.
+- High-risk regressions to watch.
@@ -0,0 +1,26 @@
+---
+name: ecommerce-store-foundation
+description: 'Create a new ecommerce project with FastAPI, React, Next.js, PostgreSQL, storefront, admin panel, back office, and AGENTS.md. Use for greenfield online stores in monorepos or split repos.'
+argument-hint: 'Describe the store, repo mode, design direction, and must-have features'
+---
+# Ecommerce Store Foundation
+
+## When to use
+- Building a new online store from scratch.
+- Scaffolding a new FastAPI and React commerce stack.
+- Setting up storefront plus admin panel or back office.
+- Creating AGENTS.md before implementation.
+
+## Procedure
+1. Run the discovery questions from [discovery checklist](./assets/discovery-checklist.md).
+2. Decide whether the target is a monorepo or split repos.
+3. Create AGENTS.md first using the matching template.
+4. Define entities, flows, roles, and integrations.
+5. Scaffold backend, then storefront, then admin.
+6. Finish with responsive polish, motion, content plan, and image prompt support.
+
+## Templates
+- Monorepo: [monorepo AGENTS template](./assets/monorepo-agents-template.md)
+- Split frontend repo: [split frontend AGENTS template](./assets/split-frontend-agents-template.md)
+- Split backend repo: [split backend AGENTS template](./assets/split-backend-agents-template.md)
+- Image prompts: [image prompt template](./assets/image-prompt-template.md)
@@ -0,0 +1,12 @@
+# Discovery Checklist
+
+- What does the store sell and in which market.
+- Is the delivery mode monorepo or split repos.
+- Does the storefront need customer accounts, guest checkout, or both.
+- Should anonymous carts live in localStorage, cookies, or server state.
+- Which admin roles are required.
+- Which catalog entities exist: categories, brands, attributes, variants, collections, bundles.
+- Which business flows matter: promos, delivery, pickup, preorder, lead capture, or full checkout.
+- Which external services are needed: payment, CRM, ERP, email, analytics, search, storage.
+- Which visual direction fits the brand and audience.
+- Which content and images already exist and which must be generated.
@@ -0,0 +1,17 @@
+# Image Prompt Template
+
+Use this template when the project needs visuals but the final assets do not exist yet.
+
+Prompt structure:
+- Brand and market context
+- Exact subject
+- Composition and camera distance
+- Aspect ratio and framing
+- Background and props
+- Lighting and mood
+- Material, texture, and styling details
+- Output quality cues
+- Negative constraints
+
+Example skeleton:
+Create a premium ecommerce hero image for a {brand type} store selling {product type}. Show {subject} in a {composition} composition, shot for a {aspect ratio} canvas. Use a {background style} background with {lighting style} lighting. Visual tone: {keywords}. Include room for headline text. Avoid watermarks, distorted hands, broken anatomy, cluttered backgrounds, oversaturated colors, and unreadable product details.
@@ -0,0 +1,30 @@
+# AGENTS.md Template For Monorepo
+
+## Product scope
+- Store type and target audience.
+- Required storefront pages and business flows.
+- Required admin or back office flows.
+
+## Repository structure
+- Root folders, package manager, environments, and local run commands.
+- Frontend and backend ownership boundaries.
+- Shared schema or contract locations.
+
+## Backend rules
+- FastAPI service boundaries.
+- Database stack, migrations, auth, and role model.
+- API naming and validation conventions.
+
+## Frontend rules
+- React framework choice.
+- Routing, layout structure, UI architecture, and data fetching strategy.
+- Responsive, accessibility, and animation expectations.
+
+## Admin rules
+- Admin modules, roles, dashboards, audit-sensitive actions, and content workflows.
+
+## Assets and content
+- Source asset folders, placeholder strategy, and external image prompt workflow.
+
+## Delivery rules
+- Definition of done, testing expectations, and how to handle missing requirements.
@@ -0,0 +1,20 @@
+# AGENTS.md Template For Split Backend Repo
+
+## Repo role
+- This repo owns FastAPI services, database models, auth, admin APIs, and integrations.
+- It serves the storefront and admin frontend repo through explicit contracts.
+
+## Backend scope
+- Catalog, taxonomy, auth, customers, carts, orders, content, settings, and admin operations.
+- Migrations, background jobs, storage, and integration boundaries.
+
+## Contract rules
+- Keep OpenAPI and schema naming stable.
+- Document any breaking change for the frontend repo before implementation.
+
+## Security and roles
+- Separate customer and staff permissions.
+- Apply RBAC for admin operations.
+
+## Delivery rules
+- Maintain migration safety and predictable local development.
@@ -0,0 +1,20 @@
+# AGENTS.md Template For Split Frontend Repo
+
+## Repo role
+- This repo owns the storefront and admin UI surface.
+- It consumes backend contracts from the paired backend repo.
+
+## Frontend scope
+- Storefront routes, account routes when needed, and admin routes or admin app.
+- Design system, responsive rules, motion rules, and accessibility baseline.
+
+## Data contract rules
+- Do not invent backend fields without documenting the contract.
+- Keep request and response assumptions aligned with the backend repo.
+
+## Asset workflow
+- Define source imagery, placeholder policy, and external generation prompt policy.
+
+## Delivery rules
+- Keep mobile storefront quality high.
+- Keep admin workflows efficient and reliable.
@@ -0,0 +1,47 @@
+---
+name: ecommerce-test-implementation
+description: 'Write automated tests for backend and frontend, then run them. Use for creating or extending pytest, frontend unit, integration, and UI tests in an ecommerce project and producing a test execution report.'
+argument-hint: 'Describe whether to cover the whole project or focus on backend, frontend, checkout, auth, catalog, admin, or other flows'
+---
+# Ecommerce Test Implementation
+
+## When to use
+- After building a new ecommerce project.
+- After adding or changing backend or frontend features.
+- When the project lacks automated tests for important commerce flows.
+
+## Goal
+- Add meaningful automated tests for backend and frontend.
+- Run the relevant test suites.
+- Produce or update .ai/TEST-REPORT.md with coverage notes, executed commands, and failures.
+
+## Required workflow
+1. Read project configuration first: `pyproject.toml`, `package.json`, and existing test config files.
+2. Detect the current test stack using [test stack matrix](./assets/test-stack-matrix.md).
+3. Identify the highest-risk flows using [test coverage checklist](./assets/test-coverage-checklist.md).
+4. Before serious backend or frontend edits, create a timestamped snapshot under .backup/ and leave older backup entries untouched.
+5. Add or update tests in the project's existing style where possible.
+6. If the project has no coherent test baseline, create a minimal sensible baseline rather than skipping tests.
+7. Run the relevant backend and frontend tests.
+8. Record results in .ai/TEST-REPORT.md using [test report template](./assets/test-report-template.md).
+9. If tests fail, stop pretending everything is fine and recommend running the test-repair workflow.
+
+## What to cover by default
+- Backend: API contracts, auth, permissions, catalog, cart, orders, admin endpoints, validation, and regression-prone business logic.
+- Frontend: page rendering, key user flows, empty/loading/error states, and critical UI interactions.
+- If the project already has UI or end-to-end tooling, cover the most important high-value flows with it.
+
+## Constraints
+- Do not add shallow tests that only restate implementation with no confidence gain.
+- Prefer high-signal tests over bloated low-value suites.
+- Respect the existing framework and test runner unless it is clearly absent or broken.
+
+## Outputs
+- Test code in the project.
+- .ai/TEST-REPORT.md.
+- Clear next step when failures exist: run the test-repair workflow.
+
+## References
+- [test stack matrix](./assets/test-stack-matrix.md)
+- [test coverage checklist](./assets/test-coverage-checklist.md)
+- [test report template](./assets/test-report-template.md)
@@ -0,0 +1,27 @@
+# Test Coverage Checklist
+
+## Backend
+- Auth and permission rules.
+- Catalog reads and writes.
+- Cart behavior.
+- Order creation and lifecycle.
+- Admin operations.
+- Input validation and error responses.
+- Critical business logic and edge cases.
+
+## Frontend
+- Key page rendering.
+- Empty, loading, and error states.
+- User interactions for catalog, cart, checkout, auth, and account.
+- Admin UI interactions when the repo contains admin code.
+
+## High-priority ecommerce flows
+- Add to cart.
+- Quantity updates and cart totals.
+- Checkout or lead flow.
+- Login and protected routes.
+- Admin create or edit flows.
+
+## Review quality
+- Assertions should verify behavior, not just implementation details.
+- Avoid fragile snapshot-heavy suites unless they truly add confidence.
@@ -0,0 +1,24 @@
+# TEST-REPORT.md Template
+
+## 1. Scope
+- Areas covered
+- Test frameworks used
+- Commands executed
+
+## 2. Added or Updated Tests
+- Backend tests
+- Frontend tests
+- UI or end-to-end tests if any
+
+## 3. Execution Results
+- Passing suites
+- Failing suites
+- Skipped or unrun suites
+
+## 4. Gaps
+- Areas still missing coverage
+- Risky flows still not tested
+
+## 5. Next Step
+- If failures exist, run the test-repair workflow.
+- If green, note whether more coverage is still recommended.
@@ -0,0 +1,20 @@
+# Test Stack Matrix
+
+## Backend
+- Prefer the existing Python test runner and fixtures setup.
+- If the project is FastAPI and already uses `pytest`, extend `pytest` rather than introducing another runner.
+- Respect async testing patterns already present in the project.
+
+## Frontend
+- Prefer the existing frontend test stack from `package.json`.
+- Typical unit and integration options: Vitest or Jest with Testing Library.
+- Typical UI or end-to-end options: Playwright when the project already uses it or clearly benefits from it.
+
+## If the project has no test stack
+- Backend default: `pytest`.
+- Frontend default for React and Next.js component testing: Vitest plus Testing Library when compatible with the project.
+- End-to-end tests should be added only if they materially improve coverage and the project can support them.
+
+## Execution principle
+- Run only the relevant suites for the change set when that is enough.
+- If the task is broad, run both backend and frontend suites or document what was not run.
@@ -0,0 +1,41 @@
+---
+name: ecommerce-test-repair
+description: 'Fix failing backend and frontend tests, then rerun them. Use for investigating test failures, repairing code or tests, and repeating the loop until suites pass or blockers are documented.'
+argument-hint: 'Describe whether to fix all current failures or only backend or frontend test failures'
+---
+# Ecommerce Test Repair
+
+## When to use
+- After the test-implementation step finds failures.
+- When backend or frontend automated tests are red.
+- When regressions appear after refactors, SEO changes, or feature work.
+
+## Goal
+- Analyze failing tests honestly.
+- Fix the underlying code or the tests, whichever is actually wrong.
+- Rerun the affected suites.
+- Produce or update .ai/TEST-REPAIR.md with failure analysis, fixes applied, rerun results, and remaining blockers.
+
+## Required workflow
+1. Read the latest .ai/TEST-REPORT.md if it exists.
+2. Inspect actual failing output rather than guessing.
+3. Before serious backend or frontend edits, create a timestamped snapshot under .backup/ and keep that folder append-only.
+4. Classify failures using [failure triage checklist](./assets/failure-triage-checklist.md).
+5. Fix root causes instead of patching symptoms when possible.
+6. Rerun the affected tests.
+7. Repeat until the suite is green or real blockers remain.
+8. Write or update .ai/TEST-REPAIR.md using [test repair template](./assets/test-repair-template.md).
+
+## Constraints
+- Do not weaken tests just to make them pass.
+- Do not rewrite assertions into meaninglessness.
+- Do not ignore failing tests without documenting the blocker.
+
+## Outputs
+- Code or test fixes.
+- Rerun results.
+- .ai/TEST-REPAIR.md.
+
+## References
+- [failure triage checklist](./assets/failure-triage-checklist.md)
+- [test repair template](./assets/test-repair-template.md)
@@ -0,0 +1,24 @@
+# Failure Triage Checklist
+
+## First classify the problem
+- Real product bug.
+- Broken or outdated test.
+- Environment or fixture problem.
+- Flaky timing or async issue.
+- Wrong assumptions after a refactor.
+
+## Backend-specific checks
+- Contract mismatch.
+- Validation error changes.
+- Permissions or auth regression.
+- Test data or fixture drift.
+
+## Frontend-specific checks
+- UI behavior changed intentionally or unintentionally.
+- Query selectors too brittle.
+- Async rendering not awaited correctly.
+- Mock data drift.
+
+## Repair rule
+- Fix the real source of truth issue first.
+- Only change tests when the implementation is correct and the test is outdated or wrong.
@@ -0,0 +1,28 @@
+# TEST-REPAIR.md Template
+
+## 1. Initial Failure State
+- Failing suites
+- Failing commands
+- Main error categories
+
+## 2. Root Cause Analysis
+- Backend causes
+- Frontend causes
+- Environment causes if any
+
+## 3. Fixes Applied
+- Code fixes
+- Test fixes
+- Config or fixture fixes
+
+## 4. Rerun Results
+- Commands rerun
+- Passing suites
+- Remaining failures
+
+## 5. Blockers
+- Anything still preventing green status
+
+## 6. Recommended Next Step
+- Whether to continue fixing
+- Whether to adjust architecture, fixtures, or test tooling