Skip to content

copilot-instructions.md

Latest commit

 

History

History
282 lines (195 loc) · 7.85 KB

copilot-instructions.md

File metadata and controls

282 lines (195 loc) · 7.85 KB

GitHub Copilot Instructions – Menu Repository

This extends the global instructions from the specs repository.

⚠️ CRITICAL RULES (Read First!)

Before ANY git commit, you MUST:

  1. Split changes into logical commits - One commit = One feature/fix
  2. If you need "and" to describe the commit, SPLIT IT
  3. Never commit all changes in one big commit
  4. Follow branch naming: <type>/<short-description>
  5. Never commit directly to main

Example of BAD vs GOOD:

  • ❌ feat: add menu display, Docker setup, and mobile testing
  • ✅ Split into:
    • feat: add menu display page with category navigation
    • feat: add VND currency formatter with unit tests
    • feat: add Docker development configuration
    • feat: add mobile testing support

Repository Context

  • Repository: menu
  • Purpose: Next.js public-facing menu website for customers to view restaurant menus
  • Tech Stack: Next.js 16, React 18, TypeScript, Tailwind CSS 3.4, Static Export
  • Deployment: Vercel with static export
  • Spec Version: v1.1-specs

🚀 "Continue Work" Trigger

When the user says "continue work", "tiếp tục", or "next task":

Step 1: Read Local Progress

Read docs/CURRENT_WORK.md in this repository to understand:

  • Current sprint and focus
  • Which stories are assigned to this repo
  • Current status of each story (🔴 Not Started / 🟡 In Progress / ✅ Done)
  • Any blockers or notes from previous session

Step 2: Identify Next Task

From CURRENT_WORK.md:

  1. If any story is 🟡 In Progress → continue that story
  2. Otherwise, pick the first 🔴 Not Started story
  3. If all stories are ✅ Done → report completion and suggest next sprint

Step 3: Load Specifications

  1. Check the "Spec References" section in CURRENT_WORK.md for the spec link
  2. Fetch and read the relevant specification section
  3. Also check docs/SPEC_LINKS.md for additional context if needed

Step 4: Implement

  1. Follow the spec exactly
  2. Apply code standards from this file (see below)
  3. Mobile-first, Vietnamese locale (vi-VN), VND formatting

Step 5: Update Progress

After implementation, update docs/CURRENT_WORK.md:

  • Change story status from 🔴 to 🟡 (in progress) or ✅ (done)
  • Add notes about what was implemented
  • Add any blockers or follow-up items
  • Update "Last Updated" timestamp

Step 6: Git Workflow

  1. Create/use feature branch: feat/<story-description>
  2. Commit with conventional message
  3. Run npm run lint && npm run test
  4. Create PR when story is complete

Step 7: Post Event to Slack

After completing a story, post an event to #agent-events (channel ID: C0A1VSFQ9SS):

✅ STORY_DONE from menu: [Story Title]
---
Details: [What UI/features were implemented]
Affected: [api, specs]
Action: [Any API needs or spec updates required]
Spec: [Link to relevant spec section]

Use slack_post_message with channel_id C0A1VSFQ9SS.

Step 8: Report

Tell the user:

  • What story you worked on
  • What was implemented
  • Current status
  • What's next
  • Event posted to Slack

🔄 "Sync Events" Trigger

When the user says "sync events", "check events", or "đồng bộ":

  1. Read recent messages from #agent-events (channel ID: C0A1VSFQ9SS) using slack_get_channel_history
  2. Filter for events affecting this repo (look for "menu" in Affected field)
  3. Report relevant events to user with recommended actions
  4. If API_READY from api → integrate new endpoints
  5. If SCHEMA_UPDATED from contracts → update type imports

Key Spec Files

Spec File Sections Purpose
design/wireframes-ux-flow.md Lines 200-400 Customer menu views
architecture/api-specification.md Lines 400-600 Menu public endpoints
research/vietnam-market-strategy.md Mobile section 4G optimization, <2s TTI
planning/sprint-0.5-menu-demo.md Stories 1.1, 1.2, 3.1, 4.1-4.2 Current sprint tasks

Also check docs/SPEC_LINKS.md for curated links with line numbers.

Build & Test Commands

npm install          # Install dependencies
npm run dev          # Start development server (localhost:3000)
npm run test         # Run tests
npm run lint         # Lint code
npm run build        # Build for production (static export)
npm run start        # Preview production build
vercel --prod        # Deploy to Vercel

Project Structure

app/
├── [tenant]/
│   └── menu/
│       └── page.tsx      # Dynamic menu page
├── layout.tsx            # Root layout with vi-VN locale
└── page.tsx              # Landing/redirect

components/
├── menu/
│   ├── MenuItem.tsx      # Menu item card
│   ├── CategoryNav.tsx   # Category tabs/sections
│   └── MenuSkeleton.tsx  # Loading state
└── ui/                   # Shared UI components

lib/
├── api/
│   └── menu-client.ts    # API client
└── utils/
    └── currency.ts       # formatVND()

Code Standards

Next.js Patterns

  • Use App Router (app/ directory)
  • Server Components by default, Client Components only when needed
  • Dynamic routes for tenant: app/[tenant]/menu/page.tsx
  • Static export for Vercel deployment

Tailwind CSS

  • Use design tokens from tailwind.config.js
  • Mobile-first: start with mobile styles, add md: for larger screens
  • Vietnamese-friendly: ensure proper text wrapping for Vietnamese characters

Performance

  • Target <2s TTI on 4G networks
  • Lazy load images with next/image
  • Minimize client-side JavaScript
  • Use static generation where possible

Vietnamese Localization

  • Default locale: vi-VN
  • Currency: VND with format 75.000₫ (use formatVND() utility)
  • All customer-facing text in Vietnamese

Git Workflow

CRITICAL: Follow docs/GIT_WORKFLOW.md:

Never Commit Directly to Main

  • Always create a new branch for changes
  • If currently on main, checkout to a new branch before committing
  • Branch naming: <type>/<short-description>

Branch Naming Types

Type Description
feat New feature
fix Bug fix
chore Maintenance, dependencies, tooling
docs Documentation only
refactor Code refactoring
test Adding or updating tests

Logical Commits

  • Group related changes into logical commits
  • Each commit should represent a single logical change
  • Use conventional commit format:
<type>: <short description>

- Detail 1
- Detail 2

Commit Granularity Principle

Each commit should answer ONE question: "What single feature/fix does this add?"

Rule of thumb: If you need "and" to describe the commit, split it.

  • ❌ Add docs and config files → Split
  • ✅ Add GitHub PR template and CODEOWNERS → OK (same purpose: GitHub config)

Pull Request Workflow

After committing:

  1. Push the branch to origin
  2. Create a PR to main branch
  3. If PR already exists, update the title and description
  4. Do not wait for confirmation - push and create PR automatically

Testing Requirements

  • Component tests with React Testing Library
  • Test mobile viewports (375px, 414px)
  • Test Vietnamese text rendering

Dependencies

  • Requires: api repo for menu data endpoints
  • Requires: contracts repo for shared TypeScript types (@localstore/contracts)
  • Deployment: Independent to Vercel

Related Documentation