halloween-test/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Agent Workflow

### Primary Agent (You)

As the primary Claude agent, you handle ALL general development tasks:
- Writing and modifying code (HTML, CSS, JavaScript)
- Reading and analyzing files
- Implementing features and fixing bugs
- Answering questions and providing guidance
- General project management and coordination

**You are the main worker. Specialist agents are consultants only.**

### Specialist Agents (Consultants)

Specialist agents in `.claude/agents/` are invoked ONLY for specific workflow stages:

1. **product-manager** ⭐ REQUIRED FIRST
   - **When**: At project start (Phase 0) - MANDATORY
   - **Role**: Create PRD in `specs/prd.md` following Spec-Kit standards
   - **Deliverable**: Product Requirements Document with vision, requirements, user stories, success metrics
   - **Blocks**: All implementation work until PRD is complete

2. **minimalist-geek-webpage-builder**
   - **When**: User explicitly requests geek-style webpage creation
   - **Role**: Design consultation and implementation guidance
   - **Not for**: General HTML/CSS questions or minor tweaks

3. **code-reviewer**
   - **When**: After completing a logical chunk of work
   - **Role**: Review code quality, security, and best practices
   - **Not for**: Writing code or making changes

4. **test-engineer**
   - **When**: User requests test creation or test strategy
   - **Role**: Design and implement comprehensive tests
   - **Not for**: General debugging or code fixes

5. **ux-expert**
   - **When**: User asks for UX evaluation or design guidance
   - **Role**: Usability analysis and accessibility recommendations
   - **Not for**: Implementation or coding

6. **devops-engineer**
   - **When**: User needs CI/CD, infrastructure, or deployment help
   - **Role**: DevOps strategy and configuration
   - **Not for**: Application code or Git basics

7. **scrum-master**
   - **When**: User needs sprint planning or agile process help
   - **Role**: Facilitate agile ceremonies and remove blockers
   - **Not for**: Technical decisions or coding

### Workflow Principle

**Phase 0: Product Manager creates PRD (REQUIRED) → Phase 1+: Primary Agent does the work → Specialist agents provide expert consultation when needed**

Do NOT delegate routine tasks to specialists. Only invoke specialist agents when:
- **ALWAYS**: Product Manager for PRD at project start (Phase 0)
- User explicitly requests specialist expertise
- You've completed work that needs expert review
- Complex decisions require domain-specific knowledge

## Project Overview

**Project Name**: McDonald's IT Halloween Event Page

**Purpose**: A minimalist, geek-style webpage to announce Halloween day activities for McDonald's IT department.

**Target Audience**: McDonald's China IT team (MITA) - 300 programmers and technical staff

**Event Details**:
- **Date**: October 31, 2025 (Halloween)
- **Time**: 18:00 - 21:00 (6:00 PM - 9:00 PM) GMT+8
- **Location**: MITA Building 2F Pantry
- **Organizer**: Jessi Pan (jessi.pan@cn.mcd.com)

## Design Requirements

### Visual Style
- **Aesthetic**: Extreme minimalist geek style, inspired by Homebrew (macOS package manager)
- **Background**: Pure black (#000000)
- **Typography**: Monospace fonts only (Courier New, Monaco, Consolas, Menlo)
- **Color Scheme**: Terminal green (#00FF00) primary, amber (#FFBF00) for key info
- **No Effects**: No shadows, gradients, borders, or decorative elements
- **Humor**: Programmer jokes and tech references encouraged

### Layout Structure
1. **Header**: Browser title "2025 MITA Halloween" with 🎃 favicon
2. **Center**: ASCII art of McDonald's logo (with Golden Arches M if possible)
3. **Tagline**: Below logo, empty line, then centered "i'm lovin' IT" with blinking cursor
4. **Countdown**: Real-time countdown to event (GMT+8 timezone)
5. **Event Info**: Bilingual content (English first, Chinese second, alternating lines)
6. **Activities**: Cosplay encouragement, bug debugging games, lucky draw
7. **Footer**: "McDonald's IT Academy"
8. **Decorations**: Halloween emojis and ASCII art (pumpkins, ghosts, bats)
9. **Overall**: Terminal/command-line interface aesthetic with programmer humor

### Technical Requirements
- **Responsive**: Must work seamlessly on both web (desktop) and mobile devices
- **Cross-device**: ASCII art must remain legible on all screen sizes
- **Performance**: Single-file HTML with inline CSS, minimal JavaScript for countdown
- **Compatibility**: Modern browsers (Chrome, Firefox, Safari, Edge)
- **Countdown**: JavaScript countdown timer using GMT+8 timezone
- **Bilingual**: Chinese-English content display

## Technology Stack

- Pure HTML5 (semantic markup)
- Inline CSS (no external stylesheets)
- Vanilla JavaScript (only if necessary)
- No frameworks or libraries

## File Structure

This project follows **Spec-Kit** standards for documentation:

```
test-project/
├── .claude/
│   ├── agents/              # AI agent configurations
│   └── constitution.md      # Agent system principles
├── specs/                   # Spec-Kit documentation (PRD, specs)
│   └── prd.md              # Product Requirements Document
├── CLAUDE.md               # This file
├── CHANGELOG.md            # Version history
├── CONTRIBUTING.md         # Contribution guidelines
├── README.md               # Project overview
├── project-spec.md         # Technical specifications
└── index.html              # Main Halloween event page
```

## Development Guidelines

### Code Style
- Clean, semantic HTML5
- Well-commented code for maintainability
- Consistent indentation (2 spaces)
- UTF-8 character encoding

### Design Principles
- Mobile-first responsive design
- Accessibility considerations (WCAG 2.1 AA)
- Fast load time (< 1 second)
- Self-contained single file for easy deployment

### ASCII Art Guidelines
- Use standard ASCII characters for maximum compatibility
- Center alignment
- Provide mobile-optimized version if needed
- Test on multiple screen sizes

## Project Metadata

**Created**: 2025-10-04 08:50:35 UTC / 2025-10-04 16:50:35 GMT+8  
**Last Updated**: 2025-10-04 08:50:35 UTC / 2025-10-04 16:50:35 GMT+8  
**Status**: In Development

## Version Control

**Repository**: `ssh://gitea@git.shihong.me:2222/snowprint/halloween-test.git`

### Git Workflow Requirements

All team members must maintain good version control practices:

1. **Commit Conventions**: Use conventional commit format
   - `feat(scope): description` for new features
   - `fix(scope): description` for bug fixes
   - `docs(scope): description` for documentation

2. **Branch Strategy**:
   - `main` - production-ready code (protected)
   - `feature/*` - new features
   - `fix/*` - bug fixes
   - `hotfix/*` - urgent fixes

3. **Code Review**: All changes require review before merging to main

4. **Security**: Never commit credentials, API keys, or sensitive data

### DevOps Responsibilities

**Primary agent handles**: Basic Git operations (commit, push, branch, merge)

**DevOps specialist consulted for**:
- CI/CD pipeline setup
- Infrastructure as code
- Deployment automation
- Complex repository management
- Security scanning and monitoring

See `.claude/git-workflow.md` for agent-specific guidelines.

## Time Recording Standards

**Critical Policy**: All timestamps must be recorded accurately.

- **Never fabricate dates or times**
- **Always use dual timezone format**: UTC and GMT+8
- **Format**: `YYYY-MM-DD HH:MM:SS UTC` / `YYYY-MM-DD HH:MM:SS GMT+8`
- **Unknown dates**: Use "TBD" (To Be Determined)

See `.claude/time-recording-policy.md` for complete guidelines.

## Development Workflow

### Step-by-Step Process for This Project

#### Phase 0: Requirements Definition ⏳ IN PROGRESS

**Step 0.1: Create PRD (Product Requirements Document)**
- ⏳ Invoke product-manager agent
- ⏳ Define product vision and objectives
- ⏳ Identify target users and use cases
- ⏳ List functional and non-functional requirements
- ⏳ Define success metrics and acceptance criteria
- ⏳ Create user stories
- ⏳ Output to `specs/prd.md` (Spec-Kit standard)
- **Owner**: product-manager agent (REQUIRED)
- **Status**: Not started
- **Blocker**: Must complete before Phase 1

---

#### Phase 1: Project Setup ✅ COMPLETE

**Step 1.1: Initialize Documentation**
- ✅ Create CLAUDE.md with project requirements
- ✅ Create README.md with project overview
- ✅ Create project-spec.md with detailed specifications
- ✅ Create CONTRIBUTING.md with Git workflow
- ✅ Create CHANGELOG.md for version tracking
- **Owner**: Primary Agent
- **Completed**: 2025-10-04 08:50:35 UTC / 16:50:35 GMT+8

**Step 1.2: Setup Version Control**
- ✅ Initialize Git repository
- ✅ Configure remote repository
- ✅ Create .gitignore file
- ✅ Initial commit and push
- **Owner**: Primary Agent
- **Completed**: 2025-10-04 08:50:35 UTC / 16:50:35 GMT+8

**Step 1.3: Establish Policies**
- ✅ Create agent constitution
- ✅ Define time recording policy
- ✅ Document Git workflow for agents
- **Owner**: Primary Agent
- **Completed**: 2025-10-04 08:50:35 UTC / 16:50:35 GMT+8

---

#### Phase 2: Design & Implementation ⏳ IN PROGRESS

**Step 2.1: Design ASCII Art Logo**
- ⏳ Create McDonald's ASCII art with Golden Arches M (desktop)
- ⏳ Create McDonald's ASCII art (mobile version)
- ⏳ Add Halloween ASCII art (pumpkins, ghosts, bats)
- ⏳ Add Halloween emojis (🎃👻🦇)
- ⏳ Add "i'm lovin' IT" tagline below logo (centered)
- ⏳ Implement blinking cursor after tagline (CSS animation)
- ⏳ Test legibility on different screen sizes
- **Owner**: Primary Agent
- **Consultant**: minimalist-geek-webpage-builder (if needed)
- **Status**: Not started

**Step 2.2: Implement HTML Structure**
- ⏳ Create index.html with semantic HTML5
- ⏳ Add meta tags (title: "2025 MITA Halloween", favicon: 🎃)
- ⏳ Add meta description: "McDonald's China IT Halloween 2025 - Join 300 MITA developers for cosplay, debugging games, and lucky draw at MITA Building 2F Pantry"
- ⏳ Structure sections (logo, countdown, event info, activities, footer)
- ⏳ Add bilingual content (English/Chinese alternating lines)
- ⏳ Add accessibility attributes (ARIA labels, lang attributes)
- **Owner**: Primary Agent
- **Status**: Not started

**Step 2.3: Implement CSS Styling**
- ⏳ Add inline CSS for terminal aesthetic
- ⏳ Implement black background with high-contrast text
- ⏳ Style with monospace fonts
- ⏳ Create responsive breakpoints (mobile/tablet/desktop)
- ⏳ Ensure no shadows, gradients, or decorative effects
- **Owner**: Primary Agent
- **Status**: Not started

**Step 2.4: Add Event Content**
- ⏳ Add countdown timer (JavaScript, GMT+8, target: Oct 31 2025 18:00)
- ⏳ Insert event details (Oct 31 2025, 18:00-21:00, MITA 2F Pantry)
- ⏳ List activities (Cosplay encouraged, bug debugging games, lucky draw)
- ⏳ Add organizer (Jessi Pan, jessi.pan@cn.mcd.com)
- ⏳ Add notes (costumes encouraged, food/drinks provided)
- ⏳ Add footer (McDonald's IT Academy)
- ⏳ Include programmer humor and tech references
- **Owner**: Primary Agent
- **Consultant**: product-manager (for content prioritization if needed)
- **Status**: Not started

**Step 2.5: Commit Implementation**
- ⏳ Review changes locally
- ⏳ Commit with message: `feat(page): implement Halloween event page`
- ⏳ Push to remote repository
- **Owner**: Primary Agent
- **Status**: Not started

---

#### Phase 3: Quality Assurance ⏳ PENDING

**Step 3.1: Code Review**
- ⏳ Invoke code-reviewer agent
- ⏳ Review for code quality, security, performance
- ⏳ Address any findings
- ⏳ Commit fixes if needed
- **Owner**: code-reviewer agent (consultant)
- **Status**: Pending Phase 2 completion

**Step 3.2: UX Evaluation**
- ⏳ Invoke ux-expert agent (optional)
- ⏳ Evaluate usability and accessibility
- ⏳ Check WCAG 2.1 AA compliance
- ⏳ Implement UX improvements if needed
- **Owner**: ux-expert agent (consultant)
- **Status**: Pending Phase 2 completion

**Step 3.3: Responsive Testing**
- ⏳ Test on desktop (1024px+)
- ⏳ Test on tablet (768-1023px)
- ⏳ Test on mobile (320-767px)
- ⏳ Verify ASCII art legibility on all sizes
- ⏳ Test on multiple browsers (Chrome, Firefox, Safari, Edge)
- **Owner**: Primary Agent
- **Status**: Pending Phase 2 completion

**Step 3.4: HTML5 Validation**
- ⏳ Validate HTML5 compliance
- ⏳ Fix any validation errors
- ⏳ Verify semantic markup
- **Owner**: Primary Agent
- **Status**: Pending Phase 2 completion

**Step 3.5: Performance Check**
- ⏳ Verify page load time < 1 second
- ⏳ Check file size < 50KB
- ⏳ Ensure no external dependencies
- **Owner**: Primary Agent
- **Status**: Pending Phase 2 completion

---

#### Phase 4: Testing (Optional) ⏳ PENDING

**Step 4.1: Create Test Cases**
- ⏳ Invoke test-engineer agent (if user requests)
- ⏳ Design test cases for functionality
- ⏳ Create accessibility tests
- ⏳ Document test results
- **Owner**: test-engineer agent (consultant)
- **Status**: Optional - only if requested

---

#### Phase 5: Deployment ⏳ PENDING

**Step 5.1: Prepare for Deployment**
- ⏳ Final review of index.html
- ⏳ Update CHANGELOG.md with release notes
- ⏳ Create Git tag for v1.0.0
- **Owner**: Primary Agent
- **Status**: Pending Phase 3 completion

**Step 5.2: Deploy to Hosting**
- ⏳ Choose hosting platform (GitHub Pages, Netlify, etc.)
- ⏳ Upload index.html
- ⏳ Verify live site functionality
- ⏳ Test on production environment
- **Owner**: Primary Agent
- **Consultant**: devops-engineer (for complex deployment)
- **Status**: Pending Phase 5.1 completion

**Step 5.3: Documentation Update**
- ⏳ Update README.md with deployment URL
- ⏳ Document deployment process
- ⏳ Mark project as complete in CLAUDE.md
- **Owner**: Primary Agent
- **Status**: Pending Phase 5.2 completion

---

### Current Phase: Phase 0 - Requirements Definition

**Next Immediate Step**: Step 0.1 - Create PRD

**Action Required**: Invoke product-manager agent to create Product Requirements Document

**Critical**: PRD must be completed before proceeding to implementation. This follows Spec-Kit standards.

### Workflow Rules

1. **Complete steps sequentially** - Don't skip ahead
2. **Primary agent does the work** - Specialists consult only when specified
3. **Commit after each major step** - Maintain clean Git history
4. **Update this document** - Mark steps complete with timestamps
5. **Ask user for confirmation** - Before moving to next phase

## Spec-Kit Compliance

This project follows **Spec-Kit** documentation standards:

- **PRD Location**: `specs/prd.md`
- **Owner**: Product Manager agent
- **Required Before**: Any implementation work
- **Format**: Structured markdown with sections for vision, requirements, user stories, success metrics

## Progress Tracking

**Overall Progress**: 20% (Phase 1 complete, Phase 0 in progress)

**Current Phase**: Phase 0 - Requirements Definition  
**Current Step**: Step 0.1 - Create PRD  
**Next Action**: Invoke product-manager agent to create PRD in specs/prd.md

**Blocker**: Cannot proceed to Phase 2 (Implementation) without completed PRD

**Last Updated**: 2025-10-04 08:50:35 UTC / 2025-10-04 16:50:35 GMT+8

---

## Quick Reference

**Primary Agent (You)**: Does all the actual work
**Specialist Agents**: Provide expert consultation only when specifically needed

**Remember**: You are capable and should handle most tasks directly. Don't over-delegate.

**Workflow**: Follow the step-by-step process above. Complete each step before moving to the next.