codex-genesis-harness 0.1.7 → 0.1.9

package/.codex/skills/genesis-test-driven-development/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: genesis-test-driven-development
+description: Đảm bảo viết Test trước, Implement sau (Red -> Green -> Refactor). Bắt buộc phải có verification cycle ở mọi bước thay đổi logic.
+---
+
+# Genesis Test Driven Development
+
+## Purpose
+Bắt buộc tuân thủ nguyên tắc TDD (Test-Driven Development) nhằm giữ cho chất lượng codebase luôn ở mức cao nhất. Cụ thể, Agent phải chứng minh được test fail (Red) trước khi sửa code, sau đó pass (Green) sau khi implement, và cuối cùng là dọn dẹp mã (Refactor) để duy trì cấu trúc sạch sẽ.
+
+## When to use
+Bất cứ khi nào thêm tính năng mới (feature), sửa lỗi logic (bug fix), hoặc thay đổi luồng nghiệp vụ của ứng dụng/API.
+
+## When NOT to use
+Khi chỉ thay đổi tài liệu (README, docs), thay đổi cấu trúc thư mục không ảnh hưởng logic (như move file), cấu hình CI/CD, hoặc thuần tuý design UI không có logic nghiệp vụ phức tạp.
+
+## Inputs required
+- Lỗi cụ thể từ người dùng hoặc requirement chi tiết từ bản kế hoạch.
+- Khung test framework của dự án (Jest, Mocha, Playwright, v.v.).
+
+## Outputs required
+- Test file mới hoặc được cập nhật.
+- Kết quả chạy test báo lỗi (Red phase) phản ánh đúng phần logic chưa có hoặc bị hỏng.
+- Source code được implement hoặc chỉnh sửa.
+- Kết quả chạy test pass (Green phase).
+
+## Required tests
+Mọi chức năng, API endpoint hoặc module mới phải được bao phủ bởi Unit Test (và Integration Test nếu có tương tác giữa các service) trước khi code chính được hoàn thiện.
+
+## Required fixtures
+Các bài test bắt buộc phải sử dụng dữ liệu từ mục `fixtures/` thay vì hardcode trực tiếp trong nội dung test, nhằm đảm bảo tính tái sử dụng và dễ theo dõi.
+
+## Required contract updates
+Trong quá trình TDD, nếu nhận thấy cần thay đổi đầu vào (request) hoặc đầu ra (response) của API, hãy cập nhật ngay lập tức các file trong mục `contracts/` rồi mới tiến hành sửa test.
+
+## Required codebase map updates
+Đảm bảo thêm module test mới vào file `TEST_MATRIX.md` để hệ thống nắm được phạm vi kiểm thử (coverage).
+
+## Token saving rules
+Hạn chế chạy toàn bộ test suite lớn của dự án nhiều lần liên tiếp. Thay vào đó, hãy chạy riêng lẻ file test hoặc block test đang được implement (`npm test -- path/to/file.test.js`).
+
+## Acceptance criteria
+1. Quá trình Red -> Green -> Refactor được chứng minh bằng lịch sử dòng lệnh (CLI output).
+2. Codebase sau khi Refactor không bị trùng lặp mã (DRY).
+3. Test phải pass 100% khi chạy lẻ và chạy chung với toàn hệ thống.
+
+## Common mistakes
+- **Viết code trước, viết test sau**: Đi ngược lại với triết lý TDD, dẫn đến test thiếu chính xác hoặc "test để pass".
+- **Test không ý nghĩa (Trivial Tests)**: Viết test chỉ kiểm tra biến bằng chính nó (vd: `expect(true).toBe(true)`), không có giá trị bảo vệ logic.
+- **Bỏ quên Refactor**: Đạt được Green (test pass) nhưng bỏ lại source code rối rắm, lộn xộn.
+
+## Recovery workflow
+1. Nếu quá trình Refactor làm test đỏ (fail) trở lại, tuyệt đối KHÔNG đổi mã của bài test.
+2. Hãy khôi phục source code về trạng thái Green gần nhất bằng `git restore` hoặc undo các thay đổi.
+3. Tiến hành Refactor lại từng bước nhỏ hơn (baby steps).

package/.codex/skills/genesis-test-driven-development/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Genesis TDD"
+  short_description: "Đảm bảo tuân thủ TDD loop"
+  default_prompt: "Viết test (Red), implement (Green) và Refactor. Phải có test fail trước khi sửa code."
+policy:
+  allow_implicit_invocation: true

package/.codex/skills/genesis-upgrade-design/SKILL.md

@@ -74,8 +74,10 @@ If behavior changes unintentionally, restore the contract expectation, add a reg
 5. Verify and compare:
    - Run lint/typecheck/tests/build that are available for the project.
    - Start the dev server when visual validation requires it.
-   - Capture screenshots after changes and inspect important states and viewports.
-   - If reference screenshots or a target design are provided, compare against them before claiming completion.
+   - **Automated Visual Verification Loop**:
+     1. Use the `@modelcontextprotocol/server-puppeteer` tool to automatically navigate to the local dev server (e.g., `http://localhost:3000`) and capture a screenshot of the current UI.
+     2. **Target Matching**: If a reference design is provided, use your Vision capabilities to compare your screenshot against the target. Iterate and update the code until the UI matches 100%.
+     3. **Aesthetic Audit**: If no target design exists, analyze your screenshot for aesthetic flaws (alignment, spacing, typography, bad AI-generated slop, inconsistent styles) and autonomously update the code to fix them. Repeat the screenshot capture until the UI looks premium.
 
 ## Upgrade Heuristics
 

package/.codex/skills/genesis-upgrade-design/agents/openai.yaml

@@ -2,3 +2,5 @@ interface:
   display_name: "Genesis Upgrade Design"
   short_description: "— Nâng cấp UI/UX của giao diện Web có sẵn"
   default_prompt: "Use $genesis-upgrade-design to improve the existing frontend UI without changing behavior."
+policy:
+  allow_implicit_invocation: true

package/.codex/skills/genesis-using-git-worktrees/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: genesis-using-git-worktrees
+description: Tạo và quản lý môi trường phân lập an toàn qua git worktrees khi thực hiện các thay đổi kiến trúc mang tính rủi ro cao.
+---
+
+# Genesis Using Git Worktrees
+
+## Purpose
+Đảm bảo an toàn tuyệt đối cho nhánh làm việc chính bằng cách thử nghiệm và refactor hệ thống ở một thư mục làm việc phụ (git worktree) được cách ly hoàn toàn. Kỹ năng này giúp developer hoặc AI không sợ làm hỏng repo gốc, dễ dàng xoá bỏ nếu kế hoạch thất bại.
+
+## When to use
+Khi tiến hành refactor lớn, thay đổi thư viện cốt lõi, nâng cấp kiến trúc diện rộng, thử nghiệm framework mới, hoặc khi cần giữ nguyên bối cảnh (context) repo hiện tại để thực hiện một hotfix khẩn cấp sang một branch khác.
+
+## When NOT to use
+Khi chỉ thay đổi nhỏ cục bộ (minor changes, typos, text updates, unit test fixes) không đe doạ đến kiến trúc hoặc sự ổn định toàn hệ thống.
+
+## Inputs required
+- Yêu cầu thay đổi kiến trúc rủi ro cao từ `implementation_plan.md`.
+- Vị trí an toàn để tạo worktree (ví dụ: một cấp bên ngoài thư mục project hiện tại như `../project-refactor`).
+
+## Outputs required
+- Lệnh tạo worktree thành công (`git worktree add -b refactor-branch ../project-refactor`).
+- Chuyển hướng context của AI sang thư mục worktree mới để làm việc.
+- Dọn dẹp/xoá worktree sau khi hoàn tất hoặc merge thành công (`git worktree remove ...`).
+
+## Required tests
+Chạy toàn bộ Regression Tests và Smoke Tests trên worktree để chứng minh tính đúng đắn trước khi xem xét tích hợp (merge) lại vào nhánh chính của repository gốc.
+
+## Required fixtures
+N/A - Worktree dùng chung codebase repo gốc nhưng chia sẻ node_modules riêng rẽ hoặc tuỳ cấu hình. 
+
+## Required contract updates
+Trong môi trường worktree, hãy tuỳ ý chỉnh sửa hợp đồng (contracts) để thử nghiệm. Tuy nhiên trước khi merge, phải thông báo sự tương thích chéo.
+
+## Required codebase map updates
+Đừng quên đồng bộ `CURRENT_STATE.md` để phản ánh nhánh/worktree đang thao tác nhằm tránh lạc đường.
+
+## Token saving rules
+Quản lý tốt đường dẫn tương đối và tuyệt đối khi làm việc trong worktree để tránh nhầm lẫn với repo gốc, gây nhiễu cho luồng đọc file.
+
+## Acceptance criteria
+1. Không được phép chỉnh sửa các file thuộc cấu trúc nhánh chính khi mục tiêu là rủi ro. Mọi thay đổi đều phải thực hiện trên branch của worktree.
+2. Thử nghiệm trên worktree không được phá hỏng git index của repo gốc.
+3. Có quy trình merge an toàn hoặc gỡ bỏ (prune) sạch sẽ khi không còn sử dụng.
+
+## Common mistakes
+- **Tạo worktree sai chỗ**: Tạo worktree *bên trong* thư mục làm việc gốc (ví dụ: `./my-worktree`) dẫn đến việc hệ thống git bị bối rối hoặc bị scan bởi linter/watcher. Phải luôn tạo ở cấp thư mục cha (ví dụ: `../my-worktree`).
+- **Quên xoá worktree**: Làm rác hệ thống máy chủ, gây xung đột tài nguyên đĩa.
+- **Thực thi lệnh nhầm thư mục**: Quên đổi thư mục làm việc (CWD) sang thư mục worktree mới, tiếp tục đập phá nhánh gốc.
+
+## Recovery workflow
+1. Nếu worktree gặp lỗi nghiêm trọng không thể cứu vãn: Chạy lệnh `git worktree remove -f <path>` và `git worktree prune`.
+2. Trở lại repository gốc với trạng thái nguyên vẹn 100%.
+3. Tạo worktree mới và bắt đầu lại.

package/.codex/skills/genesis-using-git-worktrees/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Genesis Git Worktrees"
+  short_description: "Làm việc an toàn qua worktree"
+  default_prompt: "Tạo và sử dụng git worktrees để cách ly rủi ro khi thực hiện các thay đổi kiến trúc lớn."
+policy:
+  allow_implicit_invocation: true

package/.codex/skills/genesis-verification-before-completion/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: genesis-verification-before-completion
+description: Bắt buộc cung cấp bằng chứng (evidence) của quá trình kiểm định trước khi tuyên bố hoàn thành task.
+---
+
+# Genesis Verification Before Completion
+
+## Purpose
+Chấm dứt triệt để việc AI "ảo giác" (hallucinate) kết quả làm việc hoặc tuyên bố xong việc khi chưa chạy test thực tế trên hệ thống. Kỹ năng này đảm bảo chất lượng mã nguồn bằng cách yêu cầu đưa ra bằng chứng (evidence) cụ thể, có thể xác minh được.
+
+## When to use
+Sử dụng mỗi khi kết thúc một đầu mục công việc trong `task.md` hoặc trước khi thông báo với người dùng rằng toàn bộ kế hoạch (Implementation Plan) đã hoàn tất.
+
+## When NOT to use
+Không sử dụng khi task chỉ đơn thuần là trả lời câu hỏi lý thuyết, vẽ sơ đồ, hoặc hướng dẫn cấu trúc mà không hề chạm vào code/hệ thống thực tế.
+
+## Inputs required
+- Trạng thái công việc vừa thực hiện xong.
+- Scripts kiểm tra có sẵn của dự án (`verify.sh`, `npm test`, `run-evals.sh`, linter, v.v.).
+
+## Outputs required
+- Bằng chứng chạy lệnh (CLI output hoặc logs).
+- Trạng thái cụ thể của các bài test (Pass/Fail) và giải thích ngắn gọn ý nghĩa của output đó (vd: "Toàn bộ 45 unit tests đã pass").
+
+## Required tests
+Không tự ý viết thêm test ở bước này nếu không được yêu cầu. Tập trung vào việc **thực thi** (execute) các test suite đã được thiết lập bởi TDD ở các bước trước.
+
+## Required fixtures
+Xác nhận rằng mọi script kiểm thử đã tiêu thụ (consume) đúng các mock data hoặc fixtures được quy định trong cấu trúc dự án.
+
+## Required contract updates
+Nếu script verify phát hiện sự sai lệch giữa code và contract (ví dụ: JSON schema bị lỗi), báo cáo ngay lập tức để người dùng quyết định thay đổi code hay cập nhật contract.
+
+## Required codebase map updates
+N/A - Việc cập nhật map nên được thực hiện trong quá trình code, kiểm định chỉ đóng vai trò xác thực.
+
+## Token saving rules
+Nếu output của quá trình test hoặc linter quá dài (hàng nghìn dòng do log lỗi), hãy dùng các cờ (flags) để chỉ in ra summary (như `--silent` hoặc `tail -n 50`) để tránh tràn context.
+
+## Acceptance criteria
+1. Phải có bằng chứng rõ ràng (CLI stdout/stderr) chứng minh lệnh kiểm định đã thực sự được gọi trên Terminal.
+2. Không còn bất kỳ error hay warning nghiêm trọng nào bị bỏ sót chưa xử lý.
+3. Toàn bộ kịch bản kiểm thử (smoke, unit, integration) đã đạt chỉ tiêu 100% xanh (Green).
+
+## Common mistakes
+- **Báo cáo suông**: Viết dòng chữ "Đã kiểm tra và mã hoạt động tốt" nhưng không hề đính kèm CLI output hoặc không cung cấp bằng chứng đã chạy script nào.
+- **Bỏ qua Warning**: Chỉ nhìn thấy chữ "Pass" nhưng phớt lờ hàng loạt warning tiềm ẩn từ trình biên dịch (compiler) hoặc linter.
+- **Kiểm định sai thư mục**: Chạy test ở thư mục root trong khi package nằm ở thư mục con.
+
+## Recovery workflow
+1. Nếu verify thất bại ở những phút cuối: Đánh dấu lại tiến độ vào `task.md` (chưa xong).
+2. Tái sử dụng TDD loop (skill: `genesis-test-driven-development`) để khoanh vùng và xử lý lỗi.
+3. Không cố gắng che giấu lỗi bằng cách phớt lờ thông báo thất bại.

package/.codex/skills/genesis-verification-before-completion/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Genesis Verification"
+  short_description: "Bắt buộc kiểm định trước khi hoàn tất"
+  default_prompt: "Chạy các script kiểm định, smoke test và evaluation để đưa ra bằng chứng trước khi báo cáo hoàn tất."
+policy:
+  allow_implicit_invocation: true