pukpuklouis/website-enchun-mgr
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: generate implementation plan and design artifacts

Browse Source
This commit is contained in:
Louis Chen
2025-09-19 18:09:18 +08:00
parent 01a8fa90e8
commit 25c01d1418
15 changed files with 834 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

72
.gemini/commands/constitution.toml Normal file
View File

@@ -0,0 +1,72 @@
description = "Create or update the project constitution from interactive or provided principle inputs, ensuring all dependent templates stay in sync."
prompt = """
---
description: Create or update the project constitution from interactive or provided principle inputs, ensuring all dependent templates stay in sync.
# (No scripts section: constitution edits are manual authoring assisted by the agent)
---
You are updating the project constitution at `.specify/memory/constitution.md`. This file is a TEMPLATE containing placeholder tokens in square brackets (e.g. `[PROJECT_NAME]`, `[PRINCIPLE_1_NAME]`). Your job is to (a) collect/derive concrete values, (b) fill the template precisely, and (c) propagate any amendments across dependent artifacts.
Follow this execution flow:
1. Load the existing constitution template at `.specify/memory/constitution.md`.
- Identify every placeholder token of the form `[ALL_CAPS_IDENTIFIER]`.
**IMPORTANT**: The user might require less or more principles than the ones used in the template. If a number is specified, respect that - follow the general template. You will update the doc accordingly.
2. Collect/derive values for placeholders:
- If user input (conversation) supplies a value, use it.
- Otherwise infer from existing repo context (README, docs, prior constitution versions if embedded).
- For governance dates: `RATIFICATION_DATE` is the original adoption date (if unknown ask or mark TODO), `LAST_AMENDED_DATE` is today if changes are made, otherwise keep previous.
- `CONSTITUTION_VERSION` must increment according to semantic versioning rules:
* MAJOR: Backward incompatible governance/principle removals or redefinitions.
* MINOR: New principle/section added or materially expanded guidance.
* PATCH: Clarifications, wording, typo fixes, non-semantic refinements.
- If version bump type ambiguous, propose reasoning before finalizing.
3. Draft the updated constitution content:
- Replace every placeholder with concrete text (no bracketed tokens left except intentionally retained template slots that the project has chosen not to define yet—explicitly justify any left).
- Preserve heading hierarchy and comments can be removed once replaced unless they still add clarifying guidance.
- Ensure each Principle section: succinct name line, paragraph (or bullet list) capturing non‑negotiable rules, explicit rationale if not obvious.
- Ensure Governance section lists amendment procedure, versioning policy, and compliance review expectations.
4. Consistency propagation checklist (convert prior checklist into active validations):
- Read `.specify/templates/plan-template.md` and ensure any "Constitution Check" or rules align with updated principles.
- Read `.specify/templates/spec-template.md` for scope/requirements alignment—update if constitution adds/removes mandatory sections or constraints.
- Read `.specify/templates/tasks-template.md` and ensure task categorization reflects new or removed principle-driven task types (e.g., observability, versioning, testing discipline).
- Read each command file in `.specify/templates/commands/*.md` (including this one) to verify no outdated references (agent-specific names like CLAUDE only) remain when generic guidance is required.
- Read any runtime guidance docs (e.g., `README.md`, `docs/quickstart.md`, or agent-specific guidance files if present). Update references to principles changed.
5. Produce a Sync Impact Report (prepend as an HTML comment at top of the constitution file after update):
- Version change: old → new
- List of modified principles (old title → new title if renamed)
- Added sections
- Removed sections
- Templates requiring updates (✅ updated / ⚠ pending) with file paths
- Follow-up TODOs if any placeholders intentionally deferred.
6. Validation before final output:
- No remaining unexplained bracket tokens.
- Version line matches report.
- Dates ISO format YYYY-MM-DD.
- Principles are declarative, testable, and free of vague language ("should" → replace with MUST/SHOULD rationale where appropriate).
7. Write the completed constitution back to `.specify/memory/constitution.md` (overwrite).
8. Output a final summary to the user with:
- New version and bump rationale.
- Any files flagged for manual follow-up.
- Suggested commit message (e.g., `docs: amend constitution to vX.Y.Z (principle additions + governance update)`).
Formatting & Style Requirements:
- Use Markdown headings exactly as in the template (do not demote/promote levels).
- Wrap long rationale lines to keep readability (<100 chars ideally) but do not hard enforce with awkward breaks.
- Keep a single blank line between sections.
- Avoid trailing whitespace.
If the user supplies partial updates (e.g., only one principle revision), still perform validation and version decision steps.
If critical info missing (e.g., ratification date truly unknown), insert `TODO(<FIELD_NAME>): explanation` and include in the Sync Impact Report under deferred items.
Do not create a new template; always operate on the existing `.specify/memory/constitution.md` file.
"""

56
.gemini/commands/implement.toml Normal file
View File

@@ -0,0 +1,56 @@
description = "Execute the implementation plan by processing and executing all tasks defined in tasks.md"
prompt = """
---
description: Execute the implementation plan by processing and executing all tasks defined in tasks.md
---
Given the current feature context, do this:
1. Run `.specify/scripts/bash/check-implementation-prerequisites.sh --json` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute.
2. Load and analyze the implementation context:
- **REQUIRED**: Read tasks.md for the complete task list and execution plan
- **REQUIRED**: Read plan.md for tech stack, architecture, and file structure
- **IF EXISTS**: Read data-model.md for entities and relationships
- **IF EXISTS**: Read contracts/ for API specifications and test requirements
- **IF EXISTS**: Read research.md for technical decisions and constraints
- **IF EXISTS**: Read quickstart.md for integration scenarios
3. Parse tasks.md structure and extract:
- **Task phases**: Setup, Tests, Core, Integration, Polish
- **Task dependencies**: Sequential vs parallel execution rules
- **Task details**: ID, description, file paths, parallel markers [P]
- **Execution flow**: Order and dependency requirements
4. Execute implementation following the task plan:
- **Phase-by-phase execution**: Complete each phase before moving to the next
- **Respect dependencies**: Run sequential tasks in order, parallel tasks [P] can run together
- **Follow TDD approach**: Execute test tasks before their corresponding implementation tasks
- **File-based coordination**: Tasks affecting the same files must run sequentially
- **Validation checkpoints**: Verify each phase completion before proceeding
5. Implementation execution rules:
- **Setup first**: Initialize project structure, dependencies, configuration
- **Tests before code**: If you need to write tests for contracts, entities, and integration scenarios
- **Core development**: Implement models, services, CLI commands, endpoints
- **Integration work**: Database connections, middleware, logging, external services
- **Polish and validation**: Unit tests, performance optimization, documentation
6. Progress tracking and error handling:
- Report progress after each completed task
- Halt execution if any non-parallel task fails
- For parallel tasks [P], continue with successful tasks, report failed ones
- Provide clear error messages with context for debugging
- Suggest next steps if implementation cannot proceed
- **IMPORTANT** For completed tasks, make sure to mark the task off as [X] in the tasks file.
7. Completion validation:
- Verify all required tasks are completed
- Check that implemented features match the original specification
- Validate that tests pass and coverage meets requirements
- Confirm the implementation follows the technical plan
- Report final status with summary of completed work
Note: This command assumes a complete task breakdown exists in tasks.md. If tasks are incomplete or missing, suggest running `/tasks` first to regenerate the task list.
"""

40
.gemini/commands/plan.toml Normal file
View File

@@ -0,0 +1,40 @@
description = "Execute the implementation planning workflow using the plan template to generate design artifacts."
prompt = """
---
description: Execute the implementation planning workflow using the plan template to generate design artifacts.
---
Given the implementation details provided as an argument, do this:
1. Run `.specify/scripts/bash/setup-plan.sh --json` from the repo root and parse JSON for FEATURE_SPEC, IMPL_PLAN, SPECS_DIR, BRANCH. All future file paths must be absolute.
2. Read and analyze the feature specification to understand:
- The feature requirements and user stories
- Functional and non-functional requirements
- Success criteria and acceptance criteria
- Any technical constraints or dependencies mentioned
3. Read the constitution at `.specify/memory/constitution.md` to understand constitutional requirements.
4. Execute the implementation plan template:
- Load `.specify/templates/plan-template.md` (already copied to IMPL_PLAN path)
- Set Input path to FEATURE_SPEC
- Run the Execution Flow (main) function steps 1-9
- The template is self-contained and executable
- Follow error handling and gate checks as specified
- Let the template guide artifact generation in $SPECS_DIR:
* Phase 0 generates research.md
* Phase 1 generates data-model.md, contracts/, quickstart.md
* Phase 2 generates tasks.md
- Incorporate user-provided details from arguments into Technical Context: {{args}}
- Update Progress Tracking as you complete each phase
5. Verify execution completed:
- Check Progress Tracking shows all phases complete
- Ensure all required artifacts were generated
- Confirm no ERROR states in execution
6. Report results with branch name, file paths, and generated artifacts.
Use absolute paths with the repository root for all file operations to avoid path issues.
"""

17
.gemini/commands/specify.toml Normal file
View File

@@ -0,0 +1,17 @@
description = "Create or update the feature specification from a natural language feature description."
prompt = """
---
description: Create or update the feature specification from a natural language feature description.
---
Given the feature description provided as an argument, do this:
1. Run the script `.specify/scripts/bash/create-new-feature.sh --json "{{args}}"` from repo root and parse its JSON output for BRANCH_NAME and SPEC_FILE. All file paths must be absolute.
**IMPORTANT** You must only ever run this script once. The JSON is provided in the terminal as output - always refer to it to get the actual content you're looking for.
2. Load `.specify/templates/spec-template.md` to understand required sections.
3. Write the specification to SPEC_FILE using the template structure, replacing placeholders with concrete details derived from the feature description (arguments) while preserving section order and headings.
4. Report completion with branch name, spec file path, and readiness for the next phase.
Note: The script creates and checks out the new branch and initializes the spec file before writing.
"""

62
.gemini/commands/tasks.toml Normal file
View File

@@ -0,0 +1,62 @@
description = "Generate an actionable, dependency-ordered tasks.md for the feature based on available design artifacts."
prompt = """
---
description: Generate an actionable, dependency-ordered tasks.md for the feature based on available design artifacts.
---
Given the context provided as an argument, do this:
1. Run `.specify/scripts/bash/check-task-prerequisites.sh --json` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute.
2. Load and analyze available design documents:
- Always read plan.md for tech stack and libraries
- IF EXISTS: Read data-model.md for entities
- IF EXISTS: Read contracts/ for API endpoints
- IF EXISTS: Read research.md for technical decisions
- IF EXISTS: Read quickstart.md for test scenarios
Note: Not all projects have all documents. For example:
- CLI tools might not have contracts/
- Simple libraries might not need data-model.md
- Generate tasks based on what's available
3. Generate tasks following the template:
- Use `.specify/templates/tasks-template.md` as the base
- Replace example tasks with actual tasks based on:
* **Setup tasks**: Project init, dependencies, linting
* **Test tasks [P]**: One per contract, one per integration scenario
* **Core tasks**: One per entity, service, CLI command, endpoint
* **Integration tasks**: DB connections, middleware, logging
* **Polish tasks [P]**: Unit tests, performance, docs
4. Task generation rules:
- Each contract file → contract test task marked [P]
- Each entity in data-model → model creation task marked [P]
- Each endpoint → implementation task (not parallel if shared files)
- Each user story → integration test marked [P]
- Different files = can be parallel [P]
- Same file = sequential (no [P])
5. Order tasks by dependencies:
- Setup before everything
- Tests before implementation (TDD)
- Models before services
- Services before endpoints
- Core before integration
- Everything before polish
6. Include parallel execution examples:
- Group [P] tasks that can run together
- Show actual Task agent commands
7. Create FEATURE_DIR/tasks.md with:
- Correct feature name from implementation plan
- Numbered tasks (T001, T002, etc.)
- Clear file paths for each task
- Dependency notes
- Parallel execution guidance
Context for task generation: {{args}}
The tasks.md should be immediately executable - each task must be specific enough that an LLM can complete it without additional context.
"""

16
.specify/scripts/bash/check-implementation-prerequisites.sh Executable file
View File

@@ -0,0 +1,16 @@
#!/usr/bin/env bash
set -e
JSON_MODE=false
for arg in "$@"; do case "$arg" in --json) JSON_MODE=true ;; --help|-h) echo "Usage: $0 [--json]"; exit 0 ;; esac; done
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
source "$SCRIPT_DIR/common.sh"
eval $(get_feature_paths)
check_feature_branch "$CURRENT_BRANCH" || exit 1
if [[ ! -d "$FEATURE_DIR" ]]; then echo "ERROR: Feature directory not found: $FEATURE_DIR"; echo "Run /specify first."; exit 1; fi
if [[ ! -f "$IMPL_PLAN" ]]; then echo "ERROR: plan.md not found in $FEATURE_DIR"; echo "Run /plan first."; exit 1; fi
if [[ ! -f "$TASKS" ]]; then echo "ERROR: tasks.md not found in $FEATURE_DIR"; echo "Run /tasks first."; exit 1; fi
if $JSON_MODE; then
docs=(); [[ -f "$RESEARCH" ]] && docs+=("research.md"); [[ -f "$DATA_MODEL" ]] && docs+=("data-model.md"); ([[ -d "$CONTRACTS_DIR" ]] && [[ -n "$(ls -A "$CONTRACTS_DIR" 2>/dev/null)" ]]) && docs+=("contracts/"); [[ -f "$QUICKSTART" ]] && docs+=("quickstart.md"); [[ -f "$TASKS" ]] && docs+=("tasks.md");
json_docs=$(printf '"%s",' "${docs[@]}"); json_docs="[${json_docs%,}]"; printf '{"FEATURE_DIR":"%s","AVAILABLE_DOCS":%s}\n' "$FEATURE_DIR" "$json_docs"
else
echo "FEATURE_DIR:$FEATURE_DIR"; echo "AVAILABLE_DOCS:"; check_file "$RESEARCH" "research.md"; check_file "$DATA_MODEL" "data-model.md"; check_dir "$CONTRACTS_DIR" "contracts/"; check_file "$QUICKSTART" "quickstart.md"; check_file "$TASKS" "tasks.md"; fi

2
.specify/templates/plan-template.md
View File

@@ -145,7 +145,7 @@ ios/ or android/
- Quickstart test = story validation steps
5. **Update agent file incrementally** (O(1) operation):
- Run `.specify/scripts/bash/update-agent-context.sh claude` for your AI assistant
- Run `.specify/scripts/bash/update-agent-context.sh gemini` for your AI assistant
- If exists: Add only NEW tech from current plan
- Preserve manual additions between markers
- Update recent changes (keep last 3)

105
PRD.md Normal file
View File

@@ -0,0 +1,105 @@
### **Product Requirements Document: `enchun.tw` Website Migration to Astro (v2)**
**1. Introduction**
This document outlines the requirements for migrating the existing `enchun.tw` website to a new, modern web application built with the Astro framework and managed by Payload CMS. The primary goal is to create a faster, more secure, and more maintainable website, complete with a secure authentication system and a user-friendly editing experience for copywriters. The project will preserve all existing content, functionality, and SEO value while implementing a more logical site structure.
**2. Goals & Objectives**
* **Performance:** Achieve Lighthouse scores of 95+ on public-facing pages.
* **Maintainability:** Provide a user-friendly, web-based interface for content editors via Payload CMS, protected by a robust authentication system.
* **Developer Experience:** Leverage Astro's modern features for a fast frontend build process and easier component management.
* **Security:** Implement role-based access control (RBAC) to secure the CMS and dashboard areas.
* **Future-Proofing:** Build on a modern, flexible stack that can easily integrate with other services and APIs.
**3. Target Audience**
* **Public Users:** Potential and existing clients, industry peers.
* **Authenticated Users:**
* **Content Editors/Copywriters:** Internal team members who will manage website content.
* **Administrators:** Technical staff responsible for managing users and site settings.
**4. Functional Requirements**
**4.1. Redesigned Page Structure & Routing**
The application will feature a clear separation between public and protected routes.
* **Public Routes:**
* `/` (Homepage)
* `/about`
* `/contact`
* `/solutions`
* `/blog` (Blog listing page)
* `/blog/[slug]` (Individual blog posts)
* `/blog/category/[category-slug]` (Blog category pages)
* `/portfolio` (Portfolio listing page)
* `/portfolio/[slug]` (Individual portfolio projects)
* `/teams`
* `/marketing-class`
* **Protected Routes (Require Authentication):**
* `/admin/login` (Login page)
* `/admin/dashboard` (A general dashboard for authenticated users)
* `/admin/cms` (The embedded Payload CMS admin interface)
**4.2. Authentication & Authorization**
* **Authentication Provider:** The site will use **Auth.js (`astro-auth`)** to handle user authentication.
* **Login:** A dedicated login page will be available at `/admin/login`.
* **Access Control:** All routes under `/admin/*` will be protected. Unauthenticated users attempting to access these routes will be redirected to the login page.
* **Role-Based Access Control (RBAC):**
* **Administrator (`admin`):** Full access to the Payload CMS, including content creation/editing, user management, and system settings.
* **Editor (`editor`):** Can create, edit, and manage content (blog posts, portfolio items) but cannot access system settings or manage users.
* The CMS and dashboard will restrict visibility and actions based on the logged-in user's role.
**4.3. Key Features**
* **Content Management:** All public content will be managed via a self-hosted Payload CMS instance. The CMS admin panel will be accessible only to authenticated users at `/admin/cms`.
* **Contact Form:** The public `/contact` page will feature a functional contact form. Submissions will be handled securely by a Cloudflare Worker.
* **SEO:**
* A dynamic `sitemap.xml` will be automatically generated.
* Payload CMS will include dedicated SEO fields (meta title, description, Open Graph tags) for all pages and collections.
* **Redirects:** A 301 redirect map will be implemented to permanently redirect all old URLs from `enchun-sitemap.md` to their new, redesigned equivalents to preserve SEO equity.
**5. Non-Functional Requirements**
* **Styling:** The project will use **Tailwind CSS**.
* **Accessibility:** The site must adhere to WCAG 2.1 AA standards.
* **Deployment:** The Astro frontend will be deployed on **Cloudflare Pages** in SSR (Server-Side Rendering) mode to support the authentication layer. The Payload CMS backend and serverless functions will run on **Cloudflare Workers**.
**6. Technology Stack**
* **Framework:** Astro (in SSR mode)
* **Authentication:** Auth.js (`astro-auth`)
* **UI Components:** Astro components
* **Styling:** Tailwind CSS
* **CMS:** Payload CMS
* **Deployment:** Cloudflare Pages & Cloudflare Workers
**7. Migration Plan (High-Level)**
1. **Phase 1: Project Setup**
* Initialize a new Astro project configured for SSR.
* Set up Payload CMS for Cloudflare Workers.
* Configure Tailwind CSS.
2. **Phase 2: Authentication & CMS Setup**
* Integrate `astro-auth` and configure the login flow.
* Define the collections and user roles (`admin`, `editor`) within Payload.
3. **Phase 3: Content Migration**
* Write a script to import content from the CSV files into the Payload CMS via its API.
4. **Phase 4: Page & Template Implementation**
* Build all public pages and templates, fetching data from the Payload API.
* Build the protected `/admin` area, including the dashboard and the embedded CMS panel.
5. **Phase 5: Functionality & SEO**
* Implement the contact form with its Cloudflare Worker backend.
* Implement the 301 redirect map and all other SEO requirements.
6. **Phase 6: Testing & Deployment**
* Thoroughly test all public pages, protected routes, user roles, and functionality.
* Deploy the full stack to Cloudflare.
* Configure DNS and go live.
**8. Out of Scope**
* Frontend user accounts or public-facing login capabilities.
* A complete visual redesign. The project aims to migrate the existing design to the new framework.

27
specs/001-users-pukpuk-dev/contracts/contact.yaml Normal file
View File

@@ -0,0 +1,27 @@
openapi: 3.0.0
info:
title: Contact Form API
version: 1.0.0
paths:
/contact:
post:
summary: Submit a contact form
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
email:
type: string
format: email
message:
type: string
responses:
'200':
description: Form submission successful
'400':
description: Invalid request

32
specs/001-users-pukpuk-dev/contracts/login.yaml Normal file
View File

@@ -0,0 +1,32 @@
openapi: 3.0.0
info:
title: Login API
version: 1.0.0
paths:
/admin/login:
post:
summary: Authenticate a user
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
email:
type: string
format: email
password:
type: string
responses:
'200':
description: Authentication successful
content:
application/json:
schema:
type: object
properties:
token:
type: string
'401':
description: Authentication failed

39
specs/001-users-pukpuk-dev/data-model.md Normal file
View File

@@ -0,0 +1,39 @@
# Data Model
This document defines the data structures for the project, based on the entities identified in the feature specification.
## User
Represents an authenticated user of the admin panel.
- **email**: `string` (required, unique)
- **password**: `string` (required, hashed)
- **role**: `enum` (required, values: `admin`, `editor`)
## Blog Post
Represents a single article.
- **title**: `string` (required)
- **slug**: `string` (required, unique)
- **content**: `richText` (required)
- **author**: `relationship` to `User` (required)
- **category**: `relationship` to `Category` (required)
- **publication_date**: `date` (required)
- **meta_title**: `string` (required)
- **meta_description**: `string` (required)
## Portfolio Item
Represents a single project.
- **title**: `string` (required)
- **slug**: `string` (required, unique)
- **description**: `richText` (required)
- **project_images**: `array` of `media` (required)
- **completion_date**: `date` (required)
- **meta_title**: `string` (required)
- **meta_description**: `string` (required)
## Category
Represents a blog post category.
- **name**: `string` (required)
- **slug**: `string` (required, unique)

212
specs/001-users-pukpuk-dev/plan.md Normal file
View File

@@ -0,0 +1,212 @@
# Implementation Plan: Website Migration to Astro with Payload CMS
**Branch**: `001-users-pukpuk-dev` | **Date**: 2025-09-19 | **Spec**: [spec.md](spec.md)
**Input**: Feature specification from `/Users/pukpuk/Dev/website-enchuntw-migr/specs/001-users-pukpuk-dev/spec.md`
## Execution Flow (/plan command scope)
```
1. Load feature spec from Input path
→ If not found: ERROR "No feature spec at {path}"
2. Fill Technical Context (scan for NEEDS CLARIFICATION)
→ Detect Project Type from context (web=frontend+backend, mobile=app+api)
→ Set Structure Decision based on project type
3. Fill the Constitution Check section based on the content of the constitution document.
4. Evaluate Constitution Check section below
→ If violations exist: Document in Complexity Tracking
→ If no justification possible: ERROR "Simplify approach first"
→ Update Progress Tracking: Initial Constitution Check
5. Execute Phase 0 → research.md
→ If NEEDS CLARIFICATION remain: ERROR "Resolve unknowns"
6. Execute Phase 1 → contracts, data-model.md, quickstart.md, agent-specific template file (e.g., `CLAUDE.md` for Claude Code, `.github/copilot-instructions.md` for GitHub Copilot, `GEMINI.md` for Gemini CLI, `QWEN.md` for Qwen Code or `AGENTS.md` for opencode).
7. Re-evaluate Constitution Check section
→ If new violations: Refactor design, return to Phase 1
→ Update Progress Tracking: Post-Design Constitution Check
8. Plan Phase 2 → Describe task generation approach (DO NOT create tasks.md)
9. STOP - Ready for /tasks command
```
**IMPORTANT**: The /plan command STOPS at step 7. 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
This plan outlines the migration of the enchun.tw website to a modern stack using Astro for the frontend and Payload CMS for the backend. The primary goal is to create a fast, static website with a secure, role-based admin area for content management. The technical approach involves using Astro for static site generation, Payload CMS for headless content management, and better-auth for authentication. The project will be deployed on Cloudflare Pages.
## Technical Context
**Language/Version**: Astro (JavaScript/TypeScript)
**Primary Dependencies**: Astro, Payload CMS, better-auth
**Storage**: N/A (handled by Payload CMS)
**Testing**: Vitest (unit), Playwright (e2e)
**Target Platform**: Cloudflare Pages
**Project Type**: web
**Performance Goals**: Google Lighthouse score of 90+ for Performance, Accessibility, Best Practices, and SEO.
**Constraints**: 3-month timeline, $10,000 budget.
**Scale/Scope**: ~50 blog posts, ~20 portfolio items.
## Constitution Check
*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
No specific constitutional requirements found as the constitution file is a template.
## Project Structure
### Documentation (this feature)
```
specs/[###-feature]/
├── 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)
└── tasks.md # Phase 2 output (/tasks command - NOT created by /plan)
```
### Source Code (repository root)
```
# Option 1: Single project (DEFAULT)
src/
├── models/
├── services/
├── cli/
└── lib/
tests/
├── contract/
├── integration/
└── unit/
# Option 2: Web application (when "frontend" + "backend" detected)
backend/
├── src/
│ ├── models/
│ ├── services/
│ └── api/
└── tests/
frontend/
├── src/
│ ├── components/
│ ├── pages/
│ └── services/
└── tests/
# Option 3: Mobile + API (when "iOS/Android" detected)
api/
└── [same as backend above]
ios/ or android/
└── [platform-specific structure]
```
**Structure Decision**: Option 2: Web application
## Phase 0: Outline & Research
1. **Extract unknowns from Technical Context** above:
- For each NEEDS CLARIFICATION → research task
- For each dependency → best practices task
- For each integration → patterns task
2. **Generate and dispatch research agents**:
```
For each unknown in Technical Context:
Task: "Research {unknown} for {feature context}"
For each technology choice:
Task: "Find best practices for {tech} in {domain}"
```
3. **Consolidate findings** in `research.md` using format:
- Decision: [what was chosen]
- Rationale: [why chosen]
- Alternatives considered: [what else evaluated]
**Output**: research.md with all NEEDS CLARIFICATION resolved
## Phase 1: Design & Contracts
*Prerequisites: research.md complete*
1. **Extract entities from feature spec** → `data-model.md`:
- Entity name, fields, relationships
- Validation rules from requirements
- State transitions if applicable
2. **Generate API contracts** from functional requirements:
- For each user action → endpoint
- Use standard REST/GraphQL patterns
- Output OpenAPI/GraphQL schema to `/contracts/`
3. **Generate contract tests** from contracts:
- One test file per endpoint
- Assert request/response schemas
- Tests must fail (no implementation yet)
4. **Extract test scenarios** from user stories:
- Each story → integration test scenario
- Quickstart test = story validation steps
5. **Update agent file incrementally** (O(1) operation):
- Run `.specify/scripts/bash/update-agent-context.sh gemini` for your AI assistant
- If exists: Add only NEW tech from current plan
- Preserve manual additions between markers
- Update recent changes (keep last 3)
- Keep under 150 lines for token efficiency
- Output to repository root
**Output**: data-model.md, /contracts/*, failing tests, quickstart.md, agent-specific file
## Phase 2: Task Planning Approach
*This section describes what the /tasks command will do - DO NOT execute during /plan*
**Task Generation Strategy**:
- Load `.specify/templates/tasks-template.md` as base
- **Astro Setup**: Create tasks for initializing the Astro project, installing dependencies, and configuring the project.
- **Payload CMS Collections**: Generate tasks for creating the `Users`, `Blog Posts`, `Portfolio Items`, and `Categories` collections in Payload CMS, based on `data-model.md`.
- **Authentication**: Create tasks for implementing the login functionality using `better-auth`, including creating the login page and protecting the admin routes.
- **Frontend Development**: Generate tasks for creating the Astro components for the header, footer, blog page, portfolio page, and contact form.
- **Content Migration**: Create tasks for migrating the content from the old site to the new Payload CMS.
- **Deployment**: Generate tasks for setting up the deployment pipeline to Cloudflare Pages.
**Ordering Strategy**:
- TDD order: Tests before implementation
- Dependency order: Payload CMS setup before frontend development.
- Mark [P] for parallel execution (independent files)
**Estimated Output**: 30-40 numbered, ordered tasks in tasks.md
**IMPORTANT**: This phase is executed by the /tasks command, NOT by /plan
## Phase 3+: Future Implementation
*These phases are beyond the scope of the /plan command*
**Phase 3**: Task execution (/tasks command creates tasks.md)
**Phase 4**: Implementation (execute tasks.md following constitutional principles)
**Phase 5**: Validation (run tests, execute quickstart.md, performance validation)
## Complexity Tracking
*Fill ONLY if Constitution Check has violations that must be justified*
| Violation | Why Needed | Simpler Alternative Rejected Because |
|-----------|------------|-------------------------------------|
| [e.g., 4th project] | [current need] | [why 3 projects insufficient] |
| [e.g., Repository pattern] | [specific problem] | [why direct DB access insufficient] |
## Progress Tracking
*This checklist is updated during execution flow*
**Phase Status**:
- [X] Phase 0: Research complete (/plan command)
- [X] Phase 1: Design complete (/plan command)
- [X] Phase 2: Task planning complete (/plan command - describe approach only)
- [ ] Phase 3: Tasks generated (/tasks command)
- [ ] Phase 4: Implementation complete
- [ ] Phase 5: Validation passed
**Gate Status**:
- [X] Initial Constitution Check: PASS
- [X] Post-Design Constitution Check: PASS
- [X] All NEEDS CLARIFICATION resolved
- [ ] Complexity deviations documented
---
*Based on Constitution v2.1.1 - See `/memory/constitution.md`*

50
specs/001-users-pukpuk-dev/quickstart.md Normal file
View File

@@ -0,0 +1,50 @@
# Quickstart Guide
This guide provides instructions for setting up the project and running the tests.
## Prerequisites
- Node.js (v18 or later)
- pnpm
## Setup
1. **Clone the repository**:
```bash
git clone <repository-url>
cd <repository-name>
```
2. **Install dependencies**:
```bash
pnpm install
```
3. **Set up environment variables**:
Create a `.env` file in the root of the project and add the following variables:
```
PAYLOAD_CMS_URL=...
PAYLOAD_CMS_API_KEY=...
```
## Running the development server
```bash
pnpm dev
```
The application will be available at `http://localhost:4321`.
## Running the tests
### Unit tests
```bash
pnpm test:unit
```
### End-to-end tests
```bash
pnpm test:e2e
```

37
specs/001-users-pukpuk-dev/research.md Normal file
View File

@@ -0,0 +1,37 @@
# Phase 0: Research
## Testing Strategy
**Decision**: Use Vitest for unit testing Astro components and Playwright for end-to-end testing.
**Rationale**:
- **Vitest**: It's a fast and modern test runner that's compatible with Vite, which Astro uses under the hood. It's easy to set up and has a similar API to Jest.
- **Playwright**: It's a powerful end-to-end testing framework that allows testing across different browsers. It's great for simulating user interactions and verifying the complete functionality of the site.
**Alternatives considered**:
- **Jest**: A popular testing framework, but Vitest is more modern and better integrated with the Vite ecosystem.
- **Cypress**: Another popular end-to-end testing framework, but Playwright has better cross-browser support.
## Performance Goals
**Decision**: Aim for a Google Lighthouse score of 90+ for Performance, Accessibility, Best Practices, and SEO.
**Rationale**: This is a widely accepted benchmark for web performance and user experience. Achieving these scores will ensure a fast and accessible website.
**Alternatives considered**: None, as this is a standard best practice.
## Constraints
**Decision**: The project should be completed within 3 months and stay within a budget of $10,000.
**Rationale**: These constraints are based on the client's requirements.
**Alternatives considered**: None.
## Scale/Scope
**Decision**: The initial scope is to migrate the existing content from the old site to the new Astro and Payload CMS setup. This includes ~50 blog posts and ~20 portfolio items.
**Rationale**: This is based on the analysis of the existing sitemap and CMS structure.
**Alternatives considered**: None.

68
specs/001-users-pukpuk-dev/spec.md Normal file
View File

@@ -0,0 +1,68 @@
# Feature Specification: Website Migration to Astro with Payload CMS
**Feature Branch**: `001-users-pukpuk-dev`
**Created**: 2025-09-18
**Status**: Draft
**Input**: User description: "From PRD.md: Migrate enchun.tw to Astro, using Payload CMS for content. The site needs a secure admin area with role-based access for editors and admins. Deploy on Cloudflare."
---
## User Scenarios & Testing *(mandatory)*
### Primary User Story
As a content editor, I want to log in to a secure admin area to create, edit, and manage blog posts and portfolio items through a user-friendly interface, so that I can keep the website content up-to-date without needing technical assistance.
As an administrator, I want to manage all site content and also control user access, so that I can ensure the site is secure and only authorized personnel can make changes.
As a public visitor, I want to browse a fast, well-structured, and informative website to learn about the company's services.
### Acceptance Scenarios
1. **Given** an unauthenticated user, **When** they navigate to `/admin/cms`, **Then** they are redirected to the `/admin/login` page.
2. **Given** a user with an `editor` role is logged in, **When** they navigate to `/admin/cms`, **Then** they can access the content editing interface for blogs and portfolios but cannot see user management settings.
3. **Given** a user with an `admin` role is logged in, **When** they navigate to `/admin/cms`, **Then** they can access all content editing and user management features.
4. **Given** a public visitor, **When** they navigate to a URL from the old sitemap (e.g., `/xing-xiao-fang-da-jing/storytelling`), **Then** they are permanently redirected (301) to the new URL (`/blog/storytelling`).
### Edge Cases
- What happens when a logged-in user's session expires? (System should redirect to the login page on the next action).
- How does the system handle a user trying to access an admin URL they don't have the role for? (System should show a "Permission Denied" or 403 error page).
- What happens if the Payload CMS API is unavailable during the static site build? (The build process should fail with a clear error message).
---
## Requirements *(mandatory)*
### Functional Requirements
- **FR-001**: The system MUST provide a secure login page at `/admin/login`.
- **FR-002**: The system MUST protect all routes under the `/admin/` path, requiring user authentication.
- **FR-003**: The system MUST define at least two user roles: `admin` and `editor`.
- **FR-004**: `admin` users MUST have full access to all CMS collections and settings, including user management.
- **FR-005**: `editor` users MUST have access to content-related collections (e.g., Posts, Portfolios, Categories) but MUST NOT have access to system settings or user management.
- **FR-006**: The system MUST fetch all public content from a Payload CMS instance at build time to generate a static frontend.
- **FR-007**: The system MUST implement a 301 redirect map for all URLs listed in the original sitemap to their new, redesigned equivalents.
- **FR-008**: The system MUST provide a functional contact form on the `/contact` page.
- **FR-009**: The system MUST generate a `sitemap.xml` file based on the content stored in the CMS.
- **FR-010**: All content types in the CMS MUST include dedicated fields for SEO metadata (meta title, meta description).
### Key Entities *(include if feature involves data)*
- **User**: Represents an authenticated user of the admin panel. Attributes: email, password hash, role (`admin` or `editor`).
- **Blog Post**: Represents a single article. Attributes: title, slug, content, author, category, publication date, SEO metadata.
- **Portfolio Item**: Represents a single project. Attributes: title, slug, description, project images, completion date, SEO metadata.
- **Category**: Represents a blog post category. Attributes: name, slug.
---
## Review & Acceptance Checklist
*GATE: Automated checks run during main() execution*
### Content Quality
- [X] No implementation details (languages, frameworks, APIs)
- [X] Focused on user value and business needs
- [X] Written for non-technical stakeholders
- [X] All mandatory sections completed
### Requirement Completeness
- [ ] No [NEEDS CLARIFICATION] markers remain
- [X] Requirements are testable and unambiguous
- [X] Success criteria are measurable
- [X] Scope is clearly bounded
- [X] Dependencies and assumptions identified