From d2cf5e944c1b930a563eefe898b2a4714e43097d Mon Sep 17 00:00:00 2001 From: snowprint Date: Sat, 4 Oct 2025 18:08:42 +0800 Subject: [PATCH 01/11] docs(claude): define agent workflow and responsibilities - Clarify primary agent handles all main development work - Define specialist agents as consultants for specific stages - Add workflow principle: primary does work, specialists consult - Specify when to invoke each specialist agent - Add development workflow process - Update project status tracking Prevents over-delegation to specialist agents. --- CLAUDE.md | 116 ++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 103 insertions(+), 13 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index b3c533a..41972cb 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -2,6 +2,67 @@ 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. **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 + +2. **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 + +3. **test-engineer** + - **When**: User requests test creation or test strategy + - **Role**: Design and implement comprehensive tests + - **Not for**: General debugging or code fixes + +4. **ux-expert** + - **When**: User asks for UX evaluation or design guidance + - **Role**: Usability analysis and accessibility recommendations + - **Not for**: Implementation or coding + +5. **product-manager** + - **When**: User needs requirements definition or prioritization + - **Role**: Create user stories, prioritize features + - **Not for**: Technical implementation + +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 + +**Primary Agent does the work → Specialist agents provide expert consultation when needed** + +Do NOT delegate routine tasks to specialists. Only invoke specialist agents when: +- 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 @@ -98,15 +159,16 @@ All team members must maintain good version control practices: 4. **Security**: Never commit credentials, API keys, or sensitive data -### DevOps Engineer Special Responsibilities +### DevOps Responsibilities -The DevOps engineer must: -- Monitor repository health and commit quality -- Enforce branch protection and workflow compliance -- Scan for accidentally committed secrets -- Maintain clean commit history -- Tag releases appropriately -- Document deployment procedures +**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. @@ -121,11 +183,39 @@ See `.claude/git-workflow.md` for agent-specific guidelines. See `.claude/time-recording-policy.md` for complete guidelines. -## Next Steps +## Development Workflow + +### Standard Development Process + +1. **Implementation** (Primary Agent) + - Write code based on requirements + - Follow design guidelines + - Commit changes with proper messages + +2. **Review** (code-reviewer agent - if needed) + - Invoke after completing logical work units + - Review for quality, security, performance + +3. **Testing** (test-engineer agent - if requested) + - Create test cases when user asks + - Validate functionality + +4. **Deployment** (devops-engineer agent - if needed) + - Setup deployment pipeline + - Configure hosting + +### Current Project Status 1. ✅ Create project README with setup instructions 2. ✅ Set up Git repository and workflow documentation -3. Implement main Halloween event page (index.html) -4. Test responsive behavior on various devices -5. Validate HTML5 compliance -6. Deploy to hosting platform +3. ⏳ Implement main Halloween event page (index.html) +4. ⏳ Test responsive behavior on various devices +5. ⏳ Validate HTML5 compliance +6. ⏳ Deploy to hosting platform + +## 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. -- 2.39.5 From e7d6b398639fb2e25ee9152743c81240faba0aea Mon Sep 17 00:00:00 2001 From: snowprint Date: Sat, 4 Oct 2025 18:12:45 +0800 Subject: [PATCH 02/11] docs(workflow): add detailed step-by-step development process - Define 5 phases: Setup, Implementation, QA, Testing, Deployment - Break down each phase into specific steps with owners - Mark Phase 1 (Project Setup) as complete - Set current phase to Phase 2 (Design & Implementation) - Add progress tracking section - Specify next immediate action: Design ASCII Art Logo - Include workflow rules and sequential completion requirements Provides clear roadmap for project completion. --- CLAUDE.md | 198 ++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 177 insertions(+), 21 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 41972cb..f777261 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -185,33 +185,187 @@ See `.claude/time-recording-policy.md` for complete guidelines. ## Development Workflow -### Standard Development Process +### Step-by-Step Process for This Project -1. **Implementation** (Primary Agent) - - Write code based on requirements - - Follow design guidelines - - Commit changes with proper messages +#### Phase 1: Project Setup ✅ COMPLETE -2. **Review** (code-reviewer agent - if needed) - - Invoke after completing logical work units - - Review for quality, security, performance +**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 -3. **Testing** (test-engineer agent - if requested) - - Create test cases when user asks - - Validate functionality +**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 -4. **Deployment** (devops-engineer agent - if needed) - - Setup deployment pipeline - - Configure hosting +**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 -### Current Project Status +--- -1. ✅ Create project README with setup instructions -2. ✅ Set up Git repository and workflow documentation -3. ⏳ Implement main Halloween event page (index.html) -4. ⏳ Test responsive behavior on various devices -5. ⏳ Validate HTML5 compliance -6. ⏳ Deploy to hosting platform +#### 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 2 - Design & Implementation + +**Next Immediate Step**: Step 2.1 - Design ASCII Art Logo + +**Action Required**: Create McDonald's ASCII art for the webpage + +### 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 + +## Progress Tracking + +**Overall Progress**: 25% (Phase 1 complete, Phase 2-5 pending) + +**Current Phase**: Phase 2 - Design & Implementation +**Current Step**: Step 2.1 - Design ASCII Art Logo +**Next Action**: Create McDonald's ASCII art + +**Last Updated**: 2025-10-04 08:50:35 UTC / 2025-10-04 16:50:35 GMT+8 + +--- ## Quick Reference @@ -219,3 +373,5 @@ See `.claude/time-recording-policy.md` for complete guidelines. **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. -- 2.39.5 From c8f3d970334bec53d50c157d8c6b3da9b49f222d Mon Sep 17 00:00:00 2001 From: snowprint Date: Sat, 4 Oct 2025 18:16:24 +0800 Subject: [PATCH 03/11] docs(workflow): add Phase 0 for PRD creation with Spec-Kit standards - Add Phase 0: Requirements Definition (before implementation) - Require product-manager agent to create PRD in specs/prd.md - Follow Spec-Kit documentation standards - Create specs/ directory for specification documents - Mark product-manager as REQUIRED first step - Update workflow principle to include mandatory PRD phase - Block Phase 2 implementation until PRD is complete Current status: Phase 0 in progress, awaiting PRD creation. --- CLAUDE.md | 76 +++++++++++++++++++++++++++++++++++++------------- specs/.gitkeep | 17 +++++++++++ 2 files changed, 74 insertions(+), 19 deletions(-) create mode 100644 specs/.gitkeep diff --git a/CLAUDE.md b/CLAUDE.md index f777261..2818198 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -19,31 +19,32 @@ As the primary Claude agent, you handle ALL general development tasks: Specialist agents in `.claude/agents/` are invoked ONLY for specific workflow stages: -1. **minimalist-geek-webpage-builder** +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 -2. **code-reviewer** +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 -3. **test-engineer** +4. **test-engineer** - **When**: User requests test creation or test strategy - **Role**: Design and implement comprehensive tests - **Not for**: General debugging or code fixes -4. **ux-expert** +5. **ux-expert** - **When**: User asks for UX evaluation or design guidance - **Role**: Usability analysis and accessibility recommendations - **Not for**: Implementation or coding -5. **product-manager** - - **When**: User needs requirements definition or prioritization - - **Role**: Create user stories, prioritize features - - **Not for**: Technical implementation - 6. **devops-engineer** - **When**: User needs CI/CD, infrastructure, or deployment help - **Role**: DevOps strategy and configuration @@ -56,9 +57,10 @@ Specialist agents in `.claude/agents/` are invoked ONLY for specific workflow st ### Workflow Principle -**Primary Agent does the work → Specialist agents provide expert consultation when needed** +**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 @@ -100,14 +102,21 @@ Do NOT delegate routine tasks to specialists. Only invoke specialist agents when ## 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 -├── index.html # Main Halloween event page -└── README.md # Project documentation +├── 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 @@ -187,6 +196,22 @@ See `.claude/time-recording-policy.md` for complete guidelines. ### 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** @@ -341,11 +366,13 @@ See `.claude/time-recording-policy.md` for complete guidelines. --- -### Current Phase: Phase 2 - Design & Implementation +### Current Phase: Phase 0 - Requirements Definition -**Next Immediate Step**: Step 2.1 - Design ASCII Art Logo +**Next Immediate Step**: Step 0.1 - Create PRD -**Action Required**: Create McDonald's ASCII art for the webpage +**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 @@ -355,13 +382,24 @@ See `.claude/time-recording-policy.md` for complete guidelines. 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**: 25% (Phase 1 complete, Phase 2-5 pending) +**Overall Progress**: 20% (Phase 1 complete, Phase 0 in progress) -**Current Phase**: Phase 2 - Design & Implementation -**Current Step**: Step 2.1 - Design ASCII Art Logo -**Next Action**: Create McDonald's ASCII art +**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 diff --git a/specs/.gitkeep b/specs/.gitkeep new file mode 100644 index 0000000..2344ce4 --- /dev/null +++ b/specs/.gitkeep @@ -0,0 +1,17 @@ +# Specs Directory + +This directory contains product specifications following Spec-Kit standards. + +## Contents + +- `prd.md` - Product Requirements Document (to be created by product-manager agent) + +## Spec-Kit Standards + +All specification documents in this directory follow Spec-Kit format: +- Structured markdown +- Clear sections for vision, requirements, user stories +- Success metrics and acceptance criteria +- Maintained by Product Manager + +**Created**: 2025-10-04 08:50:35 UTC / 2025-10-04 16:50:35 GMT+8 -- 2.39.5 From b6a192e7ebf43846ee2118867e5aa50fd58ff750 Mon Sep 17 00:00:00 2001 From: snowprint Date: Sat, 4 Oct 2025 18:19:22 +0800 Subject: [PATCH 04/11] docs(constitution): add Spec-Kit standards to documentation requirements - Add Spec-Kit compliance as core documentation standard - Require PRD creation in Phase 0 before implementation - Define PRD location (specs/prd.md) and ownership (Product Manager) - Establish PRD as workflow gate blocking implementation - Include structured format requirements - Clarify document ownership by role Spec-Kit standards now part of agent constitution. --- .claude/constitution.md | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/.claude/constitution.md b/.claude/constitution.md index 276e9d7..57bb487 100644 --- a/.claude/constitution.md +++ b/.claude/constitution.md @@ -47,6 +47,11 @@ - Record in both UTC and GMT+8 (Asia/Shanghai) - Format: `YYYY-MM-DD HH:MM:SS UTC` and `YYYY-MM-DD HH:MM:SS GMT+8` - Use system time or explicitly state "To be determined" if unknown +- **Spec-Kit Standards**: Follow Spec-Kit documentation framework + - PRD (Product Requirements Document) in `specs/prd.md` + - Structured markdown format + - Product Manager owns specification documents + - PRD required before implementation begins ### Efficiency - Deliver minimal viable solutions that fully address requirements @@ -70,6 +75,37 @@ - Highlight key decisions and their rationale - Offer next steps or follow-up recommendations +## Documentation Standards + +### Spec-Kit Compliance + +All projects must follow **Spec-Kit** documentation framework: + +1. **Requirements Phase (Phase 0)** + - Product Manager creates PRD before any implementation + - PRD location: `specs/prd.md` + - Must include: vision, objectives, requirements, user stories, success metrics + +2. **Structured Format** + - Use markdown with clear sections + - Maintain version history + - Link related documents + +3. **Ownership** + - Product Manager: PRD and product specifications + - Primary Agent: Technical documentation + - DevOps Engineer: Infrastructure and deployment docs + +4. **Workflow Gate** + - PRD completion blocks implementation work + - No coding until requirements are documented + - Ensures alignment before development + +### Time Recording +- Dual timezone format (UTC + GMT+8) +- Never fabricate timestamps +- Use "TBD" for unknown dates + ## Ethical Boundaries ### Security First -- 2.39.5 From 9c57194a0462f3ab5c14dc99a4b4dea277cb08e6 Mon Sep 17 00:00:00 2001 From: snowprint Date: Sat, 4 Oct 2025 18:24:11 +0800 Subject: [PATCH 05/11] feat(requirements): add tagline with blinking cursor - Add "i'm lovin' IT" tagline below McDonald's ASCII logo - Implement blinking cursor animation after tagline - Update layout structure in CLAUDE.md - Add detailed tagline requirements in project-spec.md - Specify CSS animation for cursor blink (1s interval) - Update Step 2.1 to include tagline implementation New visual element: centered tagline with terminal-style cursor. --- CLAUDE.md | 7 +++++-- project-spec.md | 17 ++++++++++++++++- 2 files changed, 21 insertions(+), 3 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 2818198..1e77517 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -84,8 +84,9 @@ Do NOT delegate routine tasks to specialists. Only invoke specialist agents when ### 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 +2. **Tagline**: Below logo, empty line, then centered "i'm lovin' IT" with blinking cursor +3. **Below**: Halloween event information and activity details +4. **Overall**: Terminal/command-line interface aesthetic ### Technical Requirements - **Responsive**: Must work seamlessly on both web (desktop) and mobile devices @@ -245,6 +246,8 @@ See `.claude/time-recording-policy.md` for complete guidelines. **Step 2.1: Design ASCII Art Logo** - ⏳ Create McDonald's ASCII art (desktop version) - ⏳ Create McDonald's ASCII art (mobile version) +- ⏳ 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) diff --git a/project-spec.md b/project-spec.md index c3e1d69..841ee7e 100644 --- a/project-spec.md +++ b/project-spec.md @@ -14,6 +14,7 @@ Single-page website for McDonald's IT department Halloween event announcement, f ### FR-2: Visual Branding - ASCII art McDonald's logo as primary visual element +- Tagline "i'm lovin' IT" centered below logo with blinking cursor - Terminal/command-line aesthetic throughout - Maintain brand recognition while adhering to geek style @@ -70,6 +71,8 @@ Single-page website for McDonald's IT department Halloween event announcement, f | [ASCII LOGO] | | McDonald's | | | +| i'm lovin' IT_ | +| | | 🎃 Halloween Event | | | | Date: [TBD] | @@ -82,6 +85,9 @@ Single-page website for McDonald's IT department Halloween event announcement, f | • Spooky Debugging Challenge | | | +----------------------------------+ + +Note: The underscore (_) after "IT" represents +a blinking cursor animation (CSS keyframes) ``` ### ASCII Art Requirements @@ -91,6 +97,13 @@ Single-page website for McDonald's IT department Halloween event announcement, f - Uses only standard ASCII characters - Maintains McDonald's brand recognition +### Tagline Requirements +- Text: "i'm lovin' IT" (lowercase, with apostrophe) +- Position: Centered, one line below ASCII logo +- Blinking cursor: Underscore character after "IT" +- Animation: CSS @keyframes for cursor blink (1s interval) +- Style: Same monospace font, terminal green color + ## Content Requirements ### Event Details @@ -117,6 +130,7 @@ Single-page website for McDonald's IT department Halloween event announcement, f - No image files (ASCII art only) - No web fonts (system fonts only) - No backend/server-side code required +- CSS animations allowed (for blinking cursor effect) ## Success Criteria @@ -125,7 +139,8 @@ Single-page website for McDonald's IT department Halloween event announcement, f 3. Passes HTML5 validation 4. Achieves WCAG 2.1 AA contrast ratios 5. Works without JavaScript enabled -6. Receives positive feedback from IT staff +6. Blinking cursor animation works smoothly +7. Receives positive feedback from IT staff ## Out of Scope -- 2.39.5 From 17730359b82383fd3a7cde43b393258769330231 Mon Sep 17 00:00:00 2001 From: snowprint Date: Sat, 4 Oct 2025 19:03:04 +0800 Subject: [PATCH 06/11] docs(requirements): add complete event details and specifications MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Event Details: - Date: October 31, 2025, 18:00-21:00 GMT+8 - Location: MITA Building 2F Pantry - Organizer: Jessi Pan (jessi.pan@cn.mcd.com) - Attendees: 300 China IT team members Features Added: - Countdown timer (JavaScript, GMT+8 timezone) - Bilingual content (English/Chinese alternating lines) - Halloween emojis and ASCII art decorations - Golden Arches M in ASCII logo - Programmer humor and tech references - Browser title: "2025 MITA Halloween" - Favicon: 🎃 emoji - Footer: McDonald's IT Academy Activities: - Cosplay encouraged - Bug debugging games - Lucky draw prizes - Food and drinks provided Design: - Terminal green (#00FF00) primary color - Amber (#FFBF00) for key information - Meta description added for SEO Updated CLAUDE.md and project-spec.md with complete requirements. --- CLAUDE.md | 50 ++++++++++++++++++------- project-spec.md | 97 ++++++++++++++++++++++++++++++++++--------------- 2 files changed, 104 insertions(+), 43 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 1e77517..b972b24 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -71,7 +71,13 @@ Do NOT delegate routine tasks to specialists. Only invoke specialist agents when **Purpose**: A minimalist, geek-style webpage to announce Halloween day activities for McDonald's IT department. -**Target Audience**: McDonald's IT staff and programmers +**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 @@ -79,20 +85,28 @@ Do NOT delegate routine tasks to specialists. Only invoke specialist agents when - **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 +- **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. **Center**: ASCII art of "McDonald's" logo as main visual element -2. **Tagline**: Below logo, empty line, then centered "i'm lovin' IT" with blinking cursor -3. **Below**: Halloween event information and activity details -4. **Overall**: Terminal/command-line interface aesthetic +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 dependencies +- **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 @@ -244,8 +258,10 @@ See `.claude/time-recording-policy.md` for complete guidelines. #### 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 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 @@ -255,9 +271,11 @@ See `.claude/time-recording-policy.md` for complete guidelines. **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) +- ⏳ 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 @@ -271,9 +289,13 @@ See `.claude/time-recording-policy.md` for complete guidelines. - **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 +- ⏳ 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 diff --git a/project-spec.md b/project-spec.md index 841ee7e..614a2f7 100644 --- a/project-spec.md +++ b/project-spec.md @@ -54,8 +54,8 @@ Single-page website for McDonald's IT department Halloween event announcement, f ### Color Palette - Background: `#000000` (pure black) -- Primary Text: `#00FF00` (terminal green) or `#FFFFFF` (white) -- Accent: `#FFBF00` (amber) for highlights +- Primary Text: `#00FF00` (terminal green) +- Accent: `#FFBF00` (amber) for key information (dates, times, contact) - No gradients, shadows, or transparency ### Typography @@ -63,31 +63,42 @@ Single-page website for McDonald's IT department Halloween event announcement, f - Base Font Size: 16px (desktop), 14px (mobile) - Line Height: 1.6 - Letter Spacing: Normal (monospace default) +- Chinese Font Support: System default monospace with Chinese fallback ### Layout ``` +----------------------------------+ +| 🎃👻🦇 2025 MITA Halloween 🦇👻🎃 | | | | [ASCII LOGO] | | McDonald's | +| [Halloween ASCII Art] | | | | i'm lovin' IT_ | | | -| 🎃 Halloween Event | +| [COUNTDOWN TIMER] | +| XX Days XX:XX:XX | | | -| Date: [TBD] | -| Time: [TBD] | -| Location: IT Department | +| Date: October 31, 2025 | +| 日期：2025年10月31日 | +| Time: 18:00 - 21:00 GMT+8 | +| 时间：18:00 - 21:00 | +| Location: MITA 2F Pantry | +| 地点：MITA大椂2F Pantry | | | -| Activities: | -| • Costume Contest | -| • Code & Candy | -| • Spooky Debugging Challenge | +| Activities / 活动: | +| • Cosplay / Cosplay装扮 | +| • Bug Debugging / 调试游戏 | +| • Lucky Draw / 现场抽奖 | | | +| Organizer: Jessi Pan | +| jessi.pan@cn.mcd.com | +| | +| McDonald's IT Academy | +----------------------------------+ -Note: The underscore (_) after "IT" represents -a blinking cursor animation (CSS keyframes) +Note: _ = blinking cursor (CSS animation) + Countdown updates in real-time (JS) ``` ### ASCII Art Requirements @@ -95,7 +106,10 @@ a blinking cursor animation (CSS keyframes) - Approximately 40-60 characters wide (desktop) - Scaled version for mobile (20-30 characters) - Uses only standard ASCII characters -- Maintains McDonald's brand recognition +- Include Golden Arches M shape if possible +- Maintains McDonald's brand recognition (note the apostrophe) +- Add Halloween ASCII decorations (pumpkins, ghosts, bats) +- Include Halloween emojis: 🎃👻🦇 ### Tagline Requirements - Text: "i'm lovin' IT" (lowercase, with apostrophe) @@ -104,33 +118,55 @@ a blinking cursor animation (CSS keyframes) - Animation: CSS @keyframes for cursor blink (1s interval) - Style: Same monospace font, terminal green color +### Countdown Timer Requirements +- Target: October 31, 2025 18:00:00 GMT+8 +- Display: Days, Hours, Minutes, Seconds +- Update: Real-time (JavaScript) +- Timezone: GMT+8 (Asia/Shanghai) +- Style: Terminal green, monospace font + +### Bilingual Content Requirements +- Language: English and Chinese (Simplified) +- Format: Alternating lines (English first, Chinese second) +- Example: + ``` + Date: October 31, 2025 + 日期：2025年10月31日 + ``` + ## Content Requirements ### Event Details -- Event name: "McDonald's IT Halloween Event" -- Date: TBD (To be confirmed by McDonald's IT) -- Time: TBD (To be confirmed by McDonald's IT) -- Location: McDonald's IT Department (specific location TBD) +- Event name: "2025 MITA Halloween" +- 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 +- Contact: jessi.pan@cn.mcd.com +- Expected Attendees: 300 (China IT team) -### Activities (Example - to be confirmed) -1. Costume Contest - Best tech-themed costume wins -2. Code & Candy - Solve coding challenges for treats -3. Spooky Debugging Challenge - Find the bugs, win prizes -4. Halloween Trivia - Tech and pop culture questions +### Activities +1. Cosplay - Encouraged, dress up in Halloween costumes +2. Bug Debugging Games - Interactive debugging challenges +3. Lucky Draw - On-site raffle with prizes +4. Food & Drinks - Provided by event organizers -### Call to Action -- RSVP instructions -- Contact information -- Dress code (optional costumes) +### Special Notes +- Costumes encouraged (Halloween theme) +- Food and beverages will be provided +- Lucky draw prizes available +- Contact Jessi Pan for questions ## Technical Constraints - No external CSS files - No external JavaScript libraries -- No image files (ASCII art only) +- No image files (ASCII art and emojis only) - No web fonts (system fonts only) - No backend/server-side code required - CSS animations allowed (for blinking cursor effect) +- Vanilla JavaScript allowed (for countdown timer) +- Emoji favicon allowed (🎃) ## Success Criteria @@ -138,9 +174,12 @@ a blinking cursor animation (CSS keyframes) 2. ASCII art is legible on iPhone SE (375px width) 3. Passes HTML5 validation 4. Achieves WCAG 2.1 AA contrast ratios -5. Works without JavaScript enabled +5. Countdown timer works correctly in GMT+8 timezone 6. Blinking cursor animation works smoothly -7. Receives positive feedback from IT staff +7. Bilingual content displays correctly +8. Halloween decorations enhance geek aesthetic +9. Programmer humor resonates with IT audience +10. Receives positive feedback from MITA team ## Out of Scope -- 2.39.5 From 325eeaf0636340235922b2c01a24bd6fe17f5122 Mon Sep 17 00:00:00 2001 From: snowprint Date: Sat, 4 Oct 2025 19:20:25 +0800 Subject: [PATCH 07/11] feat(spec): complete implementation plan for Halloween event page MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Created comprehensive planning documentation following Spec-Kit standards: Phase 0 - Research: - Analyzed 10 technical decisions (HTML5, ASCII art, countdown, responsive design) - Resolved edge cases (post-countdown, post-event, JS disabled, small screens) - Documented rationale and alternatives for each decision Phase 1 - Design: - Defined 4 data entities (Event, Countdown, VisualTheme, Content) - Created JSON schema contract for page content validation - Mapped 35 functional requirements to implementation approach - Generated quickstart testing checklist with 10 test categories Technical decisions: - Single-file HTML architecture (no external dependencies) - Pure CSS animations (blinking cursor) - JavaScript countdown with GMT+8 timezone handling - Responsive ASCII art (desktop/mobile versions) - WCAG 2.1 AA compliance (21:1 contrast ratio) Constitution compliance: PASS - No violations detected - Follows user-centric, professional excellence principles - Minimal technical stack aligns with simplicity requirement Artifacts created: - spec.md: 35 functional requirements - plan.md: Implementation strategy and phases - research.md: 10 technical research decisions - data-model.md: 4 entity definitions with validation - contracts/page-content.schema.json: JSON Schema - quickstart.md: Comprehensive testing checklist Ready for: /tasks command to generate tasks.md 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .../contracts/page-content.schema.json | 364 ++++++++++++ specs/001-mcdonald-s-it/data-model.md | 364 ++++++++++++ specs/001-mcdonald-s-it/plan.md | 528 ++++++++++++++++++ specs/001-mcdonald-s-it/quickstart.md | 442 +++++++++++++++ specs/001-mcdonald-s-it/research.md | 345 ++++++++++++ specs/001-mcdonald-s-it/spec.md | 171 ++++++ 6 files changed, 2214 insertions(+) create mode 100644 specs/001-mcdonald-s-it/contracts/page-content.schema.json create mode 100644 specs/001-mcdonald-s-it/data-model.md create mode 100644 specs/001-mcdonald-s-it/plan.md create mode 100644 specs/001-mcdonald-s-it/quickstart.md create mode 100644 specs/001-mcdonald-s-it/research.md create mode 100644 specs/001-mcdonald-s-it/spec.md diff --git a/specs/001-mcdonald-s-it/contracts/page-content.schema.json b/specs/001-mcdonald-s-it/contracts/page-content.schema.json new file mode 100644 index 0000000..bddcb29 --- /dev/null +++ b/specs/001-mcdonald-s-it/contracts/page-content.schema.json @@ -0,0 +1,364 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "https://mcdonald-s-it-halloween.schema.json", + "title": "McDonald's IT Halloween Event Page Content Schema", + "description": "Schema defining the structure and validation rules for the Halloween 2025 event page content", + "type": "object", + "required": ["meta", "theme", "event", "countdown", "ascii"], + "properties": { + "meta": { + "type": "object", + "description": "Page metadata for browser and SEO", + "required": ["title", "description", "favicon"], + "properties": { + "title": { + "type": "string", + "const": "2025 MITA Halloween", + "description": "Browser tab title" + }, + "description": { + "type": "string", + "minLength": 50, + "maxLength": 160, + "description": "Meta description for SEO", + "default": "McDonald's China IT Halloween 2025 - Join 300 MITA developers for cosplay, debugging games, and lucky draw at MITA Building 2F Pantry" + }, + "favicon": { + "type": "string", + "pattern": "^data:image", + "description": "Data URI for favicon (pumpkin emoji)" + }, + "lang": { + "type": "string", + "enum": ["en", "zh-CN"], + "default": "en", + "description": "Primary page language" + } + } + }, + "theme": { + "type": "object", + "description": "Visual design theme configuration", + "required": ["backgroundColor", "primaryColor", "accentColor", "fontFamily"], + "properties": { + "backgroundColor": { + "type": "string", + "pattern": "^#[0-9A-Fa-f]{6}$", + "const": "#000000", + "description": "Pure black background" + }, + "primaryColor": { + "type": "string", + "pattern": "^#[0-9A-Fa-f]{6}$", + "const": "#00FF00", + "description": "Terminal green for main text" + }, + "accentColor": { + "type": "string", + "pattern": "^#[0-9A-Fa-f]{6}$", + "const": "#FFBF00", + "description": "Amber for key information" + }, + "fontFamily": { + "type": "string", + "pattern": "monospace", + "description": "Monospace font stack" + }, + "fontSize": { + "type": "object", + "properties": { + "base": { + "type": "string", + "pattern": "^[0-9]+(px|rem|em)$", + "default": "16px" + }, + "heading": { + "type": "string", + "pattern": "^[0-9]+(px|rem|em)$", + "default": "20px" + }, + "small": { + "type": "string", + "pattern": "^[0-9]+(px|rem|em)$", + "default": "14px" + } + } + } + } + }, + "event": { + "type": "object", + "description": "Halloween event details", + "required": ["title", "date", "startTime", "endTime", "timezone", "location", "organizer", "activities"], + "properties": { + "title": { + "type": "string", + "const": "2025 MITA Halloween" + }, + "date": { + "type": "string", + "format": "date", + "const": "2025-10-31", + "description": "Event date in ISO format" + }, + "startTime": { + "type": "string", + "pattern": "^([01]?[0-9]|2[0-3]):[0-5][0-9]$", + "const": "18:00", + "description": "Event start time in 24h format" + }, + "endTime": { + "type": "string", + "pattern": "^([01]?[0-9]|2[0-3]):[0-5][0-9]$", + "const": "21:00", + "description": "Event end time in 24h format" + }, + "timezone": { + "type": "string", + "const": "GMT+8", + "description": "Event timezone" + }, + "location": { + "type": "string", + "const": "MITA Building 2F Pantry", + "description": "Physical event location" + }, + "organizer": { + "type": "object", + "required": ["name", "email"], + "properties": { + "name": { + "type": "string", + "const": "Jessi Pan" + }, + "email": { + "type": "string", + "format": "email", + "const": "jessi.pan@cn.mcd.com" + } + } + }, + "activities": { + "type": "array", + "minItems": 3, + "maxItems": 5, + "items": { + "type": "string", + "minLength": 3 + }, + "description": "List of event activities" + }, + "notes": { + "type": "array", + "items": { + "type": "string", + "minLength": 5 + }, + "description": "Additional event information" + }, + "audience": { + "type": "object", + "properties": { + "department": { + "type": "string", + "const": "MITA" + }, + "count": { + "type": "integer", + "const": 300 + }, + "description": { + "type": "string", + "const": "McDonald's China IT team members" + } + } + } + } + }, + "countdown": { + "type": "object", + "description": "Countdown timer configuration", + "required": ["targetDateTime", "timezone"], + "properties": { + "targetDateTime": { + "type": "string", + "format": "date-time", + "const": "2025-10-31T10:00:00Z", + "description": "Target datetime in UTC (18:00 GMT+8)" + }, + "eventEndDateTime": { + "type": "string", + "format": "date-time", + "const": "2025-10-31T13:00:00Z", + "description": "Event end datetime in UTC (21:00 GMT+8)" + }, + "timezone": { + "type": "string", + "const": "GMT+8", + "description": "Display timezone" + }, + "updateInterval": { + "type": "integer", + "minimum": 1000, + "maximum": 1000, + "default": 1000, + "description": "Update interval in milliseconds" + }, + "messages": { + "type": "object", + "properties": { + "before": { + "type": "string", + "description": "Message to show before event" + }, + "active": { + "type": "string", + "const": "🎃 EVENT STARTING NOW! 🎃", + "description": "Message when event starts" + }, + "ended": { + "type": "string", + "const": "👻 EVENT COMPLETED - Thanks for joining! 👻", + "description": "Message after event ends" + }, + "noJs": { + "type": "string", + "const": "Enable JavaScript for live countdown", + "description": "Fallback message when JS disabled" + } + } + } + } + }, + "ascii": { + "type": "object", + "description": "ASCII art content", + "required": ["logo", "decorations"], + "properties": { + "logo": { + "type": "object", + "required": ["desktop", "mobile"], + "properties": { + "desktop": { + "type": "string", + "minLength": 50, + "description": "McDonald's ASCII logo for desktop (with Golden Arches)" + }, + "mobile": { + "type": "string", + "minLength": 20, + "description": "McDonald's ASCII logo for mobile (simplified)" + } + } + }, + "tagline": { + "type": "object", + "properties": { + "text": { + "type": "string", + "const": "i'm lovin' IT" + }, + "cursor": { + "type": "string", + "enum": ["_", "|", "█"], + "default": "_" + } + } + }, + "decorations": { + "type": "array", + "minItems": 1, + "items": { + "type": "string", + "description": "Halloween-themed ASCII art or emoji" + }, + "description": "Halloween decorations (pumpkins, ghosts, bats)" + } + } + }, + "content": { + "type": "object", + "description": "Bilingual content pairs", + "properties": { + "pairs": { + "type": "array", + "items": { + "type": "object", + "required": ["section", "english", "chinese"], + "properties": { + "section": { + "type": "string", + "enum": ["date", "time", "location", "organizer", "activities", "notes"] + }, + "english": { + "type": "string", + "minLength": 5 + }, + "chinese": { + "type": "string", + "minLength": 3 + }, + "order": { + "type": "integer", + "minimum": 1 + } + } + } + } + } + }, + "accessibility": { + "type": "object", + "description": "Accessibility configuration", + "properties": { + "wcagLevel": { + "type": "string", + "enum": ["AA", "AAA"], + "const": "AA", + "description": "WCAG compliance level" + }, + "contrastRatios": { + "type": "object", + "properties": { + "primaryOnBackground": { + "type": "number", + "minimum": 21, + "description": "Green (#00FF00) on black (#000000)" + }, + "accentOnBackground": { + "type": "number", + "minimum": 12, + "description": "Amber (#FFBF00) on black (#000000)" + } + } + }, + "ariaLabels": { + "type": "object", + "description": "ARIA labels for screen readers" + } + } + }, + "performance": { + "type": "object", + "description": "Performance requirements", + "properties": { + "maxFileSize": { + "type": "integer", + "maximum": 51200, + "description": "Maximum file size in bytes (50KB)" + }, + "maxLoadTime": { + "type": "integer", + "maximum": 1000, + "description": "Maximum load time in milliseconds" + }, + "targetFrameRate": { + "type": "integer", + "const": 60, + "description": "Target frame rate for animations" + } + } + } + }, + "additionalProperties": false +} diff --git a/specs/001-mcdonald-s-it/data-model.md b/specs/001-mcdonald-s-it/data-model.md new file mode 100644 index 0000000..2b1a3ca --- /dev/null +++ b/specs/001-mcdonald-s-it/data-model.md @@ -0,0 +1,364 @@ +# Data Model: McDonald's IT Halloween Event Page + +**Feature**: Halloween event announcement webpage +**Date**: 2025-10-04 +**Status**: Complete + +## Overview + +This document defines the data entities and their relationships for the Halloween event page. While this is a static page with no backend storage, defining the data model helps structure the HTML content and JavaScript logic. + +## Entities + +### 1. Event + +Represents the Halloween event information. + +**Purpose**: Store and display all event details + +**Fields**: +| Field | Type | Required | Default | Description | +|-------|------|----------|---------|-------------| +| `title` | String | Yes | - | Event title: "2025 MITA Halloween" | +| `date` | Date | Yes | - | Event date: October 31, 2025 | +| `startTime` | Time | Yes | - | Event start: 18:00 GMT+8 | +| `endTime` | Time | Yes | - | Event end: 21:00 GMT+8 | +| `timezone` | String | Yes | "GMT+8" | Timezone for event | +| `location` | String | Yes | - | "MITA Building 2F Pantry" | +| `organizer` | Object | Yes | - | Organizer details | +| `organizer.name` | String | Yes | - | "Jessi Pan" | +| `organizer.email` | String | Yes | - | "jessi.pan@cn.mcd.com" | +| `activities` | Array | Yes | - | List of activities | +| `notes` | Array | Yes | - | Additional information | + +**Validation Rules**: +- `date` must be valid ISO date format +- `startTime` must be before `endTime` +- Times must be in 24-hour format (HH:MM) +- `organizer.email` must be valid email format +- `activities` must contain at least 1 item + +**Example**: +```json +{ + "title": "2025 MITA Halloween", + "date": "2025-10-31", + "startTime": "18:00", + "endTime": "21:00", + "timezone": "GMT+8", + "location": "MITA Building 2F Pantry", + "organizer": { + "name": "Jessi Pan", + "email": "jessi.pan@cn.mcd.com" + }, + "activities": [ + "Cosplay (encouraged)", + "Bug Debugging Games", + "Lucky Draw" + ], + "notes": [ + "Costumes encouraged", + "Food and drinks provided" + ] +} +``` + +**State Transitions**: None (static data) + +--- + +### 2. Countdown + +Represents the countdown timer state and logic. + +**Purpose**: Calculate and display time remaining until event + +**Fields**: +| Field | Type | Required | Default | Description | +|-------|------|----------|---------|-------------| +| `targetDateTime` | DateTime | Yes | - | Oct 31 2025 18:00:00 GMT+8 (in UTC: 10:00:00 UTC) | +| `currentDateTime` | DateTime | Yes | - | User's current time (updated every second) | +| `timeRemaining` | Object | No | null | Calculated time remaining | +| `timeRemaining.days` | Integer | No | 0 | Days remaining | +| `timeRemaining.hours` | Integer | No | 0 | Hours remaining (0-23) | +| `timeRemaining.minutes` | Integer | No | 0 | Minutes remaining (0-59) | +| `timeRemaining.seconds` | Integer | No | 0 | Seconds remaining (0-59) | +| `status` | Enum | Yes | "before" | Current event status | + +**Status Values**: +- `before`: Current time is before event start (show countdown) +- `active`: Event has started, current time is between start and end (show "EVENT STARTING NOW!") +- `ended`: Event has ended, current time is after event end (show "EVENT COMPLETED") + +**Validation Rules**: +- `targetDateTime` must be a valid Date object +- All time values must be >= 0 +- `status` must be one of: "before", "active", "ended" +- `timeRemaining` is null when status is not "before" + +**Calculation Logic**: +```javascript +// Convert GMT+8 to UTC for calculation +// Oct 31 2025 18:00 GMT+8 = Oct 31 2025 10:00 UTC +const targetDate = new Date('2025-10-31T10:00:00Z'); +const eventEnd = new Date('2025-10-31T13:00:00Z'); // 21:00 GMT+8 + +function updateCountdown() { + const now = new Date(); + + if (now >= eventEnd) { + return { status: 'ended', timeRemaining: null }; + } + + if (now >= targetDate) { + return { status: 'active', timeRemaining: null }; + } + + const diff = targetDate - now; + const days = Math.floor(diff / (1000 * 60 * 60 * 24)); + const hours = Math.floor((diff % (1000 * 60 * 60 * 24)) / (1000 * 60 * 60)); + const minutes = Math.floor((diff % (1000 * 60 * 60)) / (1000 * 60)); + const seconds = Math.floor((diff % (1000 * 60)) / 1000); + + return { + status: 'before', + timeRemaining: { days, hours, minutes, seconds } + }; +} +``` + +**State Transitions**: +``` +before → active (when current time >= targetDateTime) +active → ended (when current time >= eventEnd) +``` + +--- + +### 3. VisualTheme + +Represents the visual design configuration. + +**Purpose**: Define and apply consistent styling across the page + +**Fields**: +| Field | Type | Required | Default | Description | +|-------|------|----------|---------|-------------| +| `backgroundColor` | Color | Yes | "#000000" | Pure black background | +| `primaryColor` | Color | Yes | "#00FF00" | Terminal green for main text | +| `accentColor` | Color | Yes | "#FFBF00" | Amber for key information | +| `fontFamily` | String | Yes | See below | Monospace font stack | +| `fontSize` | Object | Yes | - | Font sizes for different elements | +| `fontSize.base` | String | Yes | "16px" | Base font size | +| `fontSize.heading` | String | Yes | "20px" | Heading size | +| `fontSize.small` | String | Yes | "14px" | Small text size | +| `asciiArt` | Object | Yes | - | ASCII art content | +| `asciiArt.logoDesktop` | String | Yes | - | McDonald's logo for desktop | +| `asciiArt.logoMobile` | String | Yes | - | McDonald's logo for mobile | +| `asciiArt.decorations` | Array | Yes | - | Halloween ASCII decorations | + +**Font Stack**: +```css +"Courier New", Monaco, Consolas, "Liberation Mono", Menlo, monospace +``` + +**Validation Rules**: +- All color values must be valid hex format (#RRGGBB) +- `backgroundColor` must be #000000 (black) +- `primaryColor` and `accentColor` must meet WCAG AA contrast ratio with background +- `fontFamily` must include at least one monospace fallback +- ASCII art strings must contain only ASCII characters (0-127) + +**Example**: +```json +{ + "backgroundColor": "#000000", + "primaryColor": "#00FF00", + "accentColor": "#FFBF00", + "fontFamily": "\"Courier New\", Monaco, Consolas, Menlo, monospace", + "fontSize": { + "base": "16px", + "heading": "20px", + "small": "14px" + }, + "asciiArt": { + "logoDesktop": "[Multi-line ASCII art]", + "logoMobile": "[Simplified ASCII art]", + "decorations": ["🎃", "👻", "🦇"] + } +} +``` + +**State Transitions**: None (static configuration) + +--- + +### 4. Content (Bilingual) + +Represents bilingual text content structure. + +**Purpose**: Store and display English/Chinese content pairs + +**Fields**: +| Field | Type | Required | Default | Description | +|-------|------|----------|---------|-------------| +| `section` | String | Yes | - | Content section identifier | +| `english` | String | Yes | - | English text | +| `chinese` | String | Yes | - | Chinese text (Simplified) | +| `order` | Integer | Yes | - | Display order | + +**Example Content Pairs**: +```json +[ + { + "section": "date", + "english": "Date: October 31, 2025", + "chinese": "日期：2025年10月31日", + "order": 1 + }, + { + "section": "time", + "english": "Time: 18:00 - 21:00 (6:00 PM - 9:00 PM)", + "chinese": "时间：18:00 - 21:00", + "order": 2 + }, + { + "section": "location", + "english": "Location: MITA Building 2F Pantry", + "chinese": "地点：MITA大厦2楼茶水间", + "order": 3 + }, + { + "section": "organizer", + "english": "Organizer: Jessi Pan (jessi.pan@cn.mcd.com)", + "chinese": "组织者：Jessi Pan (jessi.pan@cn.mcd.com)", + "order": 4 + } +] +``` + +**Display Pattern**: +```html +

{english}

+

{chinese}

+``` + +--- + +## Relationships + +``` +Event (1) + ├── has timezone (1) → Countdown + └── has theme (1) → VisualTheme + +Countdown (1) + └── uses targetDateTime from Event + +VisualTheme (1) + └── styles all Content + +Content (many) + └── derived from Event +``` + +## HTML Representation + +The data model maps to HTML structure as follows: + +```html +
+ +
+ 
[McDonald's ASCII Logo]
+ 
[McDonald's ASCII Logo Simplified]
+

i'm lovin' IT_

+
+ + +
+
+ 0d + 0h + 0m + 0s +
+
+ + +
+

Date: {Event.date}

+

日期：{Event.date}

+ +
+ + +
+

Activities:

+

活动：

+
    +
  • {activity}
    • +
  • {activity_zh}
    • +
+
+ + +
+ 
{decoration}
+
+
+``` + +## JavaScript Data Structure + +```javascript +const eventData = { + event: { + title: "2025 MITA Halloween", + date: "2025-10-31", + startTime: "18:00", + endTime: "21:00", + timezone: "GMT+8", + location: "MITA Building 2F Pantry", + organizer: { + name: "Jessi Pan", + email: "jessi.pan@cn.mcd.com" + }, + activities: ["Cosplay", "Bug Debugging Games", "Lucky Draw"], + notes: ["Costumes encouraged", "Food and drinks provided"] + }, + + countdown: { + targetDateTime: new Date('2025-10-31T10:00:00Z'), // GMT+8 = UTC+8 + eventEnd: new Date('2025-10-31T13:00:00Z'), + status: 'before', + timeRemaining: null + }, + + theme: { + backgroundColor: "#000000", + primaryColor: "#00FF00", + accentColor: "#FFBF00", + fontFamily: '"Courier New", Monaco, Consolas, Menlo, monospace' + } +}; +``` + +## Validation Contract + +All data must conform to the schema defined in `/contracts/page-content.schema.json`. + +See: [page-content.schema.json](./contracts/page-content.schema.json) + +## Notes + +- This is a static page, so data is hardcoded in HTML/JS +- No database or API calls required +- Data updates only via code changes +- Countdown is the only dynamic data (calculated client-side) + +## Next Steps + +- Create contracts/page-content.schema.json (JSON Schema validation) +- Create quickstart.md (testing checklist) +- Update CLAUDE.md (agent context) diff --git a/specs/001-mcdonald-s-it/plan.md b/specs/001-mcdonald-s-it/plan.md new file mode 100644 index 0000000..e68c97b --- /dev/null +++ b/specs/001-mcdonald-s-it/plan.md @@ -0,0 +1,528 @@ +# Implementation Plan: McDonald's IT Halloween Event Page + +**Branch**: `001-mcdonald-s-it` | **Date**: 2025-10-04 | **Spec**: [spec.md](./spec.md) +**Input**: Feature specification from `/specs/001-mcdonald-s-it/spec.md` + +## Execution Flow (/plan command scope) +``` +1. Load feature spec from Input path ✅ + → Feature spec loaded successfully +2. Fill Technical Context ✅ + → Project Type: Single-file web page (static HTML) + → Structure Decision: Single HTML file with inline CSS/JS +3. Fill Constitution Check section ✅ + → Based on .claude/constitution.md +4. Evaluate Constitution Check section ✅ + → No violations - simple, focused implementation + → Update Progress Tracking: Initial Constitution Check ✅ +5. Execute Phase 0 → research.md ✅ + → No NEEDS CLARIFICATION in tech context +6. Execute Phase 1 → data-model.md, contracts/, quickstart.md, CLAUDE.md ✅ +7. Re-evaluate Constitution Check section ✅ + → No new violations after design + → Update Progress Tracking: Post-Design Constitution Check ✅ +8. Plan Phase 2 → Describe task generation approach ✅ +9. STOP - Ready for /tasks command ✅ +``` + +**IMPORTANT**: The /plan command STOPS at step 9. Phases 2-4 are executed by other commands: +- Phase 2: /tasks command creates tasks.md +- Phase 3-4: Implementation execution (manual or via tools) + +## Summary + +Create a minimalist, geek-style Halloween event announcement webpage for McDonald's China IT team (MITA). The page features ASCII art, a countdown timer to the Oct 31 2025 event, and bilingual (English/Chinese) content. Design emphasizes terminal aesthetics with black background, monospace fonts, and no decorative effects. Must be responsive, self-contained (single HTML file), and load under 1 second. + +**Technical Approach**: Single self-contained HTML5 file with inline CSS for styling and minimal JavaScript for countdown timer. Pure static page requiring no server-side processing or external dependencies. Responsive design using CSS media queries for cross-device compatibility. + +## Technical Context + +**Language/Version**: HTML5, CSS3, JavaScript ES6+ +**Primary Dependencies**: None (self-contained single file) +**Storage**: N/A (static page, no data persistence) +**Testing**: Manual browser testing (Chrome, Firefox, Safari, Edge), HTML5 validation, WCAG 2.1 AA compliance check +**Target Platform**: Modern web browsers (latest 2 versions), responsive design for desktop (1024px+), tablet (768-1023px), mobile (320-767px) +**Project Type**: Single-file static webpage +**Performance Goals**: Load time < 1 second, file size < 50KB, 60fps animations +**Constraints**: + - Single self-contained HTML file only + - No external dependencies (CSS/JS/images/fonts) + - No frameworks or libraries + - WCAG 2.1 AA compliance required + - Countdown must use GMT+8 timezone + - ASCII art must be legible on all screen sizes +**Scale/Scope**: Single page, ~300 target users, static content only + +**User Provided Context**: $ARGUMENTS + +## Constitution Check +*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.* + +Based on `.claude/constitution.md`: + +### User-Centric Service ✅ +- Requirements clearly defined in spec.md +- User stories and acceptance criteria documented +- Focus on MITA IT team needs (programmer aesthetic, bilingual content) + +### Professional Excellence ✅ +- Following web standards (HTML5, CSS3, WCAG 2.1 AA) +- Single-file architecture aligns with deployment simplicity requirement +- No over-engineering - minimal technical stack appropriate for static page + +### Clear Communication ✅ +- Spec provides comprehensive requirements (35 functional requirements) +- Technical decisions documented with rationale +- Edge cases identified and defaults specified + +### Collaborative Mindset ✅ +- Respects existing CLAUDE.md workflow +- Builds on established project structure (specs/ directory) +- Follows Spec-Kit documentation standards + +### Continuous Improvement ✅ +- Identified 2 edge cases for future consideration +- Design allows for easy updates (single file) +- Performance metrics defined for validation + +### Spec-Kit Compliance ✅ +- Following Spec-Kit framework +- Specification in `specs/001-mcdonald-s-it/spec.md` +- Product requirements clearly documented +- Implementation plan follows structured format + +**Constitution Status**: ✅ PASS - No violations detected + +## Project Structure + +### Documentation (this feature) +``` +specs/001-mcdonald-s-it/ +├── spec.md # Feature specification +├── plan.md # This file (/plan command output) +├── research.md # Phase 0 output (/plan command) +├── data-model.md # Phase 1 output (/plan command) +├── quickstart.md # Phase 1 output (/plan command) +├── contracts/ # Phase 1 output (/plan command) +│ └── page-content.schema.json +└── tasks.md # Phase 2 output (/tasks command - NOT created by /plan) +``` + +### Source Code (repository root) +``` +test-project/ +├── index.html # Main Halloween event page (self-contained) +├── README.md # Project documentation +├── CLAUDE.md # Agent workflow and project guidance +└── specs/ # Specification documents + └── 001-mcdonald-s-it/ # This feature +``` + +**Structure Decision**: Single-file static webpage architecture selected because: +1. No backend/API required (static content only) +2. No data persistence needed +3. Simplifies deployment (single file to host) +4. Meets performance requirement (< 1 second load, < 50KB) +5. Aligns with minimalist design philosophy +6. Easy to maintain and update + +## Phase 0: Outline & Research + +### Research Tasks Completed + +**1. HTML5 Semantic Markup Best Practices** +- **Decision**: Use semantic HTML5 elements (`
`, `
`, `
`, `