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`*