chore(workflow): add AI-assisted workflow commands and configurations

Add comprehensive workflow commands for AI-assisted development: - Claude commands: analyze, clarify, plan - Kilocode workflows: full feature development lifecycle - Opencode commands: specification and implementation workflows - Roo MCP configuration for tool integration Update .gitignore to exclude .astro build cache directories. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-10-07 01:06:10 +08:00
parent cf0f779ad4
commit c2d4c8d0a0
122 changed files with 5376 additions and 107 deletions
--- a/specs/001-users-pukpuk-dev/plan.md
+++ b/specs/001-users-pukpuk-dev/plan.md
@@ -1,64 +1,219 @@

-# Implementation Plan: Website Migration to Astro (v2)
+# Implementation Plan: [FEATURE]

-**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` and `PRD.md`.
+**Branch**: `[###-feature-name]` | **Date**: [DATE] | **Spec**: [link]
+**Input**: Feature specification from `/specs/[###-feature-name]/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 file system structure or 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 all other agents).
+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 `enchun.tw` to a modern stack using Astro (SSR mode) for the frontend and Payload CMS for the backend, deployed on Cloudflare. The project will create a fast, static website with a secure, role-based admin area for content management using Auth.js, styled with Tailwind CSS. E-commerce functionality is explicitly out of scope.
+[Extract from feature spec: primary requirement + technical approach from research]

 ## Technical Context
-**Language/Version**: Astro (JavaScript/TypeScript)
-**Primary Dependencies**: Astro, Payload CMS, Auth.js (`astro-auth`), Tailwind CSS
-**Storage**: N/A (handled by Payload CMS)
-**Testing**: Vitest (unit), Playwright (e2e)
-**Target Platform**: Cloudflare Pages (SSR) & Cloudflare Workers
-**Project Type**: Monorepo (pnpm workspaces)
-**Performance Goals**: Google Lighthouse score of 95+
-**Constraints**: Adherence to WCAG 2.1 AA standards.
-**Scale/Scope**: Migration of existing content (~50 blog posts, ~20 portfolio items).
+**Language/Version**: [e.g., Python 3.11, Swift 5.9, Rust 1.75 or NEEDS CLARIFICATION]  
+**Primary Dependencies**: [e.g., FastAPI, UIKit, LLVM or NEEDS CLARIFICATION]  
+**Storage**: [if applicable, e.g., PostgreSQL, CoreData, files or N/A]  
+**Testing**: [e.g., pytest, XCTest, cargo test or NEEDS CLARIFICATION]  
+**Target Platform**: [e.g., Linux server, iOS 15+, WASM or NEEDS CLARIFICATION]
+**Project Type**: [single/web/mobile - determines source structure]  
+**Performance Goals**: [domain-specific, e.g., 1000 req/s, 10k lines/sec, 60 fps or NEEDS CLARIFICATION]  
+**Constraints**: [domain-specific, e.g., <200ms p95, <100MB memory, offline-capable or NEEDS CLARIFICATION]  
+**Scale/Scope**: [domain-specific, e.g., 10k users, 1M LOC, 50 screens or NEEDS CLARIFICATION]

 ## Constitution Check
-No specific constitutional requirements found as the constitution file is a template.
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
+
+[Gates determined based on constitution file]

 ## Project Structure
-**Structure Decision**: Monorepo with `frontend/`, `backend/`, and `packages/shared/` as per `PRD.md`.
+
+### 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)
+<!--
+  ACTION REQUIRED: Replace the placeholder tree below with the concrete layout
+  for this feature. Delete unused options and expand the chosen structure with
+  real paths (e.g., apps/admin, packages/something). The delivered plan must
+  not include Option labels.
+-->
 ```
-/
-├── backend/          # Payload CMS on Cloudflare Workers
-├── frontend/         # Astro (SSR) on Cloudflare Pages
-├── packages/
-│   └── shared/       # Shared TypeScript utilities, Tailwind config
-└── pnpm-workspace.yaml
+# [REMOVE IF UNUSED] Option 1: Single project (DEFAULT)
+src/
+├── models/
+├── services/
+├── cli/
+└── lib/
+
+tests/
+├── contract/
+├── integration/
+└── unit/
+
+# [REMOVE IF UNUSED] Option 2: Web application (when "frontend" + "backend" detected)
+backend/
+├── src/
+│   ├── models/
+│   ├── services/
+│   └── api/
+└── tests/
+
+frontend/
+├── src/
+│   ├── components/
+│   ├── pages/
+│   └── services/
+└── tests/
+
+# [REMOVE IF UNUSED] Option 3: Mobile + API (when "iOS/Android" detected)
+api/
+└── [same as backend above]
+
+ios/ or android/
+└── [platform-specific structure: feature modules, UI flows, platform tests]
 ```

+**Structure Decision**: [Document the selected structure and reference the real
+directories captured above]
+
 ## Phase 0: Outline & Research
-Completed. Decisions are reflected in the Technical Context.
+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
-Completed. Artifacts `data-model.md`, `contracts/`, and `quickstart.md` are still valid.
+*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 opencode`
+     **IMPORTANT**: Execute it exactly as specified above. Do not add or remove any arguments.
+   - 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
-**Task Generation Strategy**:
- **Workspace Setup**: Initialize pnpm monorepo.
- **Backend Setup**: Configure Payload CMS collections (`Users`, `BlogPosts`, etc.) for Cloudflare.
- **Frontend Setup**: Configure Astro (SSR) with Tailwind CSS.
- **Authentication**: Integrate Auth.js (`astro-auth`) for `/admin/*` routes.
- **Component & Page Creation**: Build all pages and components as per the `PRD.md` and corrected `route-structure.md`.
- **Content Migration**: Script the import of existing content into Payload.
- **SEO & Redirects**: Implement the 301 redirect map.
- **Testing**: Write contract, integration, and unit tests for the new structure.
- **Deployment**: Configure Cloudflare Pages & Workers deployment.
+*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
+- Generate tasks from Phase 1 design docs (contracts, data model, quickstart)
+- Each contract → contract test task [P]
+- Each entity → model creation task [P] 
+- Each user story → integration test task
+- Implementation tasks to make tests pass
+
+**Ordering Strategy**:
+- TDD order: Tests before implementation 
+- Dependency order: Models before services before UI
+- Mark [P] for parallel execution (independent files)
+
+**Estimated Output**: 25-30 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] |

-**Estimated Output**: 30-40 numbered, ordered tasks in `tasks.md`.

 ## Progress Tracking
- [X] Phase 0: Research complete
- [X] Phase 1: Design complete
- [X] Phase 2: Task planning complete (approach described)
- [ ] Phase 3: Tasks generated
+*This checklist is updated during execution flow*
+
+**Phase Status**:
+- [ ] Phase 0: Research complete (/plan command)
+- [ ] Phase 1: Design complete (/plan command)
+- [ ] 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**:
+- [ ] Initial Constitution Check: PASS
+- [ ] Post-Design Constitution Check: PASS
+- [ ] All NEEDS CLARIFICATION resolved
+- [ ] Complexity deviations documented
+
+---
+*Based on Constitution v2.1.1 - See `/memory/constitution.md`*
--- a/specs/001-users-pukpuk-dev/research.md
+++ b/specs/001-users-pukpuk-dev/research.md
@@ -14,7 +14,7 @@

 ## Performance Goals

-**Decision**: Aim for a Google Lighthouse score of 90+ for Performance, Accessibility, Best Practices, and SEO.
+**Decision**: Aim for a Google Lighthouse score of 95+ 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.

@@ -30,7 +30,7 @@

 ## 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.
+**Decision**: The initial scope is to migrate the existing content from the old site to the new Astro and Payload CMS setup. This includes approximately 35 blog posts and portfolio items combined.

 **Rationale**: This is based on the analysis of the existing sitemap and CMS structure.

--- a/specs/001-users-pukpuk-dev/spec.md
+++ b/specs/001-users-pukpuk-dev/spec.md
@@ -7,6 +7,15 @@

 ---

+## Clarifications
+
+### Session 2025-10-06
+- Q: What is the expected number of blog posts and portfolio items to be migrated? → A: 35
+- Q: What are the possible states for blog posts? → A: published, draft, schedule publish
+- Q: How will the system handle concurrent edits to the same content item? → A: Last write wins
+- Q: What are the specific security measures for user authentication and data protection? → A: SSL/TLS certificates, input validation, regular security audits
+- Q: What is the expected daily traffic volume for the website? → A: 500-2000 visitors per day
+
 ## User Scenarios & Testing *(mandatory)*

 ### Primary User Story
@@ -26,6 +35,7 @@ As a public visitor, I want to browse a fast, well-structured, and informative w
 - 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).
+- Concurrent edits to the same content item are resolved by "last write wins" (latest save overwrites previous changes).

 ---

@@ -42,13 +52,19 @@ As a public visitor, I want to browse a fast, well-structured, and informative w
 - **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).
+- **FR-011**: The system MUST implement security measures including SSL/TLS certificates, input validation, and regular security audits for authentication and data protection.

 ### 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.
+- **Blog Post**: Represents a single article. Attributes: title, slug, content, author, category, publication date, state (draft, published, scheduled), SEO metadata. Lifecycle: Can transition from draft to scheduled to published.
 - **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.

+Expected data volume: Approximately 35 blog posts and portfolio items combined.
+
+### Non-Functional Requirements
+- Scalability: Expected daily traffic of 500-2000 visitors.
+
 ---

 ## Review & Acceptance Checklist
@@ -61,7 +77,7 @@ As a public visitor, I want to browse a fast, well-structured, and informative w
 - [X] All mandatory sections completed

 ### Requirement Completeness
- [ ] No [NEEDS CLARIFICATION] markers remain
+- [X] No [NEEDS CLARIFICATION] markers remain
 - [X] Requirements are testable and unambiguous
 - [X] Success criteria are measurable
 - [X] Scope is clearly bounded
--- a/specs/001-users-pukpuk-dev/tasks.md
+++ b/specs/001-users-pukpuk-dev/tasks.md
@@ -12,7 +12,7 @@ This task list is aligned with the official `PRD.md` and excludes all e-commerce
 - [X] **T001**: Initialize a pnpm monorepo with `pnpm-workspace.yaml`.
 - [X] **T002**: Create `frontend/`, `backend/`, and `packages/shared/` directories.
 - [X] **T003**: Initialize the Astro project in `frontend/` configured for SSR (Server-Side Rendering).
- [X] **T004**: Initialize the Payload CMS project in `backend/` configured for Cloudflare Workers.
+- [X] **T004**: Initialize the Payload CMS project in `backend/` configured for self-hosted Coolify platform.
 - [X] **T005**: Configure Tailwind CSS in the `packages/shared/` directory to be used by the `frontend` app.
 - [X] **T006**: Install all necessary dependencies across the workspace.

@@ -22,24 +22,23 @@ This task list is aligned with the official `PRD.md` and excludes all e-commerce
 - [X] **T008**: **[P]** Create the `BlogPosts` collection in Payload CMS.
 - [X] **T009**: **[P]** Create the `PortfolioItems` collection in Payload CMS.
 - [X] **T010**: **[P]** Create the `Categories` collection in Payload CMS.
- [X] **T011**: Configure Payload to use Auth.js for authentication.
+- [X] **T011**: Configure Payload to use Payload CMS default authentication.

 ## Phase 3: Frontend Development (Astro)

- **T012**: Integrate Auth.js (`astro-auth`) with the Astro project.
- **T013**: Implement the authentication check for all `/admin/*` routes in `frontend/src/middleware.ts`.
- **T014**: **[P]** Create the main site layout (`Layout.astro`) with shared Header and Footer components.
- **T015**: **[P]** Create the secure admin layout (`AdminLayout.astro`).
- **T016**: **[P]** Create the static page `frontend/src/pages/about.astro`.
- **T017**: **[P]** Create the static page `frontend/src/pages/solutions.astro`.
+- [X] **T012**: Integrate Payload CMS authentication with the Astro project.
+- [X] **T013**: Implement the authentication check for all `/admin/*` routes in `frontend/src/middleware.ts`.
+- [X] **T014**: **[P]** Create the main site layout (`Layout.astro`) with shared Header and Footer components.
+- [X] **T015**: **[P]** Create the secure admin layout (`AdminLayout.astro`).
+- **T016**: **[P]** Create the static page `frontend/src/pages/about-enchun.astro`.
+- **T017**: **[P]** Create the static page `frontend/src/pages/marketing-solutions.astro`.
 - **T018**: **[P]** Create the static page `frontend/src/pages/teams.astro`.
- **T019**: **[P]** Create the static page `frontend/src/pages/marketing-class.astro`.
- **T020**: **[P]** Create the contact page at `frontend/src/pages/contact.astro`.
- **T021**: Create the blog listing page at `frontend/src/pages/blog/index.astro`.
- **T022**: Create the dynamic blog post page at `frontend/src/pages/blog/[slug].astro`.
- **T023**: Create the blog category page at `frontend/src/pages/blog/category/[category-slug].astro`.
- **T024**: Create the portfolio listing page at `frontend/src/pages/portfolio/index.astro`.
- **T025**: Create the dynamic portfolio item page at `frontend/src/pages/portfolio/[slug].astro`.
+- **T019**: **[P]** Create the contact page at `frontend/src/pages/contact-us.astro`.
+- **T020**: Create the blog listing page at `frontend/src/pages/news.astro`.
+- **T021**: Create the dynamic blog post page at `frontend/src/pages/xing-xiao-fang-da-jing/[slug].astro`.
+- **T022**: Create the blog category page at `frontend/src/pages/wen-zhang-fen-lei/[slug].astro`.
+- **T023**: Create the portfolio listing page at `frontend/src/pages/website-portfolio.astro`.
+- **T024**: Create the dynamic portfolio item page at `frontend/src/pages/webdesign-profolio/[slug].astro`.
 - **T026**: Implement the login page at `frontend/src/pages/admin/login.astro`.
 - **T027**: Implement the protected dashboard at `frontend/src/pages/admin/dashboard.astro`.
 - **T028**: Implement the embedded Payload CMS view at `frontend/src/pages/admin/cms.astro`.
@@ -52,9 +51,9 @@ This task list is aligned with the official `PRD.md` and excludes all e-commerce

 ## Phase 5: Testing & Deployment

- **T032**: **[P]** Write integration tests for the Auth.js login and protected route flow.
+- **T032**: **[P]** Write integration tests for the Payload CMS authentication login and protected route flow.
 - **T033**: **[P]** Write integration tests for the contact form submission.
 - **T034**: **[P]** Write unit tests for critical shared utilities or components.
 - **T035**: Configure and test the deployment pipeline for the Astro frontend to Cloudflare Pages.
- **T036**: Configure and test the deployment pipeline for the Payload CMS backend to Cloudflare Workers.
+- **T036**: Configure and test the deployment pipeline for the Payload CMS backend to Coolify.
 - **T037**: Perform a final SEO and accessibility audit.