# 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 IT staff and programmers

## 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**: High contrast - green/white/amber text on black background
- **No Effects**: No shadows, gradients, borders, or decorative elements

### Layout Structure
1. **Center**: ASCII art of "McDonald's" logo as main visual element
2. **Below**: Halloween event information and activity details
3. **Overall**: Terminal/command-line interface aesthetic

### 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 dependencies
- **Compatibility**: Modern browsers (Chrome, Firefox, Safari, Edge)

## 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 (desktop version)
- ⏳ Create McDonald's ASCII art (mobile version)
- ⏳ 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 for responsive design
- ⏳ Structure content sections (logo, event info, activities)
- ⏳ Add accessibility attributes (ARIA labels, alt text)
- **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**
- ⏳ Insert Halloween event details (date TBD, time TBD, location)
- ⏳ List activities and schedule
- ⏳ Add RSVP or contact information
- **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.