codex-genesis-harness 0.1.7 → 0.1.8

package/.codex/skills/genesis-spec-propagation/SKILL.md

@@ -1,534 +1,82 @@
 ---
 name: genesis-spec-propagation
-description: "Automated specification propagation across project phases. Detects spec changes and automatically cascades updates to all affected downstream phases, preventing stale contracts, misaligned tests, and late-stage rework."
+description: "Automated specification propagation across project phases. Use after spec changes to update affected tests, contracts, client expectations, E2E scenarios, docs, and migration guidance."
 ---
 
-# genesis-spec-propagation
+# Genesis Spec Propagation
 
 ## Purpose
-
-Automate cascade propagation of spec changes across all project phases. When Phase 1 API changes, automatically detect affected phases (2-5), update downstream tests, contracts, client SDK types, and E2E scenarios, and generate migration guides for breaking changes. Reduces 45+ min manual update work to 5 min automated propagation.
+Prevent downstream phase drift after a spec change by identifying affected phases, updating dependent artifacts, and validating alignment.
 
 ## When to use
-
-### Auto-Triggers
-✅ After `/spec-change` command completes → Detects impact, auto-updates downstream phases
-✅ After `/contract-update` for API/DB schema → Propagates to dependent contracts
-✅ After SPEC_CHANGELOG.md entry created → Identifies affected phases (from notes)
-✅ Before release/deployment → Validates all phases still aligned
+- After `/spec-change` or a contract/spec edit.
+- When API, database, UI, auth, config, or integration shape changes.
+- Before starting downstream work that depends on an updated upstream phase.
+- When `spec-impact-engine` reports affected phases.
 
 ## When NOT to use
-
-- For documentation-only changes with no structural impact (field descriptions, examples only)
-- When changing a single isolated file with no cross-phase dependencies
-- For internal refactoring that preserves all public contracts
+- Pure prose edits that do not alter behavior, schemas, routes, or phase dependencies.
+- One-off implementation bugs where no public or phase contract changed.
+- Cosmetic docs edits with no downstream dependency.
 
 ## Inputs required
-
-- Path to changed spec file (e.g., `contracts/api/response.json`)
-- Current `.codebase/PHASE_DEPENDENCY_MAP.md`
-- Current `SPEC_CHANGELOG.md`
-- Old vs new spec content (for diff analysis)
+- Changed spec or contract files.
+- Impact report from `spec-impact-engine` when available.
+- `.codebase/PHASE_DEPENDENCY_MAP.md` or equivalent dependency notes.
+- Current tests, fixtures, and docs for affected phases.
 
 ## Outputs required
-
-- Updated downstream phase files (tests, contracts, SDK types, E2E scenarios)
-- `SPEC_CHANGE_PROPAGATION.md` investigation log
-- `SPEC_CHANGELOG.md` entry (auto-appended)
-- Migration guide (for breaking changes only)
-- Cross-phase validation report
+- Updated downstream phase specs, mocks, tests, contracts, and E2E scenarios.
+- Migration guide for breaking changes.
+- Propagation summary in `.codebase` or observability logs.
+- Verification evidence for affected phases.
 
 ## Required tests
-
-- Each downstream phase's tests must pass after auto-update
-- Cross-phase type consistency check (Phase 3 types ⊆ Phase 4 client types)
-- Syntax validation of all updated files (JSON, TS, MD)
-- Contract alignment test (Phase 3 response schema ⊂ Phase 4 type definitions)
+- Run affected unit/integration/E2E checks where executable tests exist.
+- Run `scripts/run-evals.sh` after changing propagation skill behavior.
+- Validate all updated contracts and fixtures.
 
 ## Required fixtures
-
-- `fixtures/spec-propagation/` with before/after contract files
-- Sample `SPEC_CHANGE_PROPAGATION.md` showing format
-- Sample migration guide for a breaking field removal
+- Update affected request/response, UI, agent, pipeline, or render fixtures.
+- Add expected-output fixtures for generated migration or impact reports.
 
 ## Required contract updates
-
-- Update `contracts/api/*/response.json` when response schema changes
-- Update `.codebase/API_CONTRACTS.md` with change record
-- Update `SPEC_CHANGELOG.md` with propagation result
+- Update `contracts/` before dependent tests or implementation.
+- Mark breaking changes explicitly and include migration instructions.
+- Keep `.codebase/API_CONTRACTS.md` and phase docs aligned.
 
 ## Required codebase map updates
-
-- `.codebase/CURRENT_STATE.md`: Mark spec propagation complete
-- `.codebase/PHASE_DEPENDENCY_MAP.md`: Update if phase dependencies change
-- `.codebase/KNOWN_PROBLEMS.md`: Document any propagation failures
+- Update `.codebase/CURRENT_STATE.md` with propagation status.
+- Update `.codebase/TEST_MATRIX.md` if validation coverage changes.
+- Update `.codebase/RECOVERY_POINTS.md` for unresolved propagation risks.
 
 ## Token saving rules
-
-- Cache PHASE_DEPENDENCY_MAP.md at session start (rarely changes)
-- Show before/after diffs, not full file content
-- Report "Phase 2,3,4,5 affected" summary, not full impact text
-- When validating: report only failing checks, not passing ones
-- Reuse dependency graph across multiple operations in same session
+- Read the impact report and phase dependency map before full specs.
+- Load only affected phase files.
+- Report failing or changed checks, not all passing detail.
 
 ## Acceptance criteria
-
-- All downstream phases identified (no phase missed)
-- All affected files updated (mocks, types, assertions, E2E)
-- All updated files syntactically valid
-- Cross-phase validation passes
-- SPEC_CHANGELOG.md entry created
-- Migration guide present for all breaking changes
-- Pre-commit gate passes
+- Every impacted downstream artifact is updated or explicitly marked non-applicable.
+- Breaking changes have migration guidance.
+- Affected verification passes.
+- `.codebase` records propagation status and remaining risks.
 
 ## Common mistakes
-
-- Missing a downstream phase (only updating Phase 2 but not Phase 4 client SDK)
-- Auto-updating Phase 5 E2E tests without semantic review (may require manual design)
-- Forgetting to run tests in each updated phase after auto-update
-- Treating non-breaking changes as breaking (causes unnecessary migration guides)
-- Committing breaking changes without human approval
+- Updating Phase 1 contracts without Phase 2-5 dependent tests.
+- Auto-updating E2E expectations without semantic review.
+- Omitting migration notes for breaking changes.
+- Treating low severity as no-op without documenting why.
 
 ## Recovery workflow
-
-If propagation breaks tests or introduces inconsistencies:
-1. Run `git revert <propagation-commit>` to restore pre-propagation state
-2. Identify which phase update caused the failure
-3. Manually review the spec change requirements
-4. Re-run propagation with `--dry-run` to preview changes first
-5. Apply updates phase-by-phase, testing after each
-6. Document edge case in `observability/` for future automation improvement
-
----
-
-## 3-Phase Propagation Workflow
-
-### Phase 1: Change Detection (5 min)
-
-**Input**: Spec change location (e.g., `contracts/api/response.json`)
-
-**Process**:
-1. **Identify Change Type**
-   - Breaking change? (field removed, type changed, required added)
-   - Feature change? (new field, new endpoint, new validation rule)
-   - Non-impact change? (doc update, example update, no structural change)
-
-2. **Parse Change Impact**
-   - Old spec vs new spec comparison
-   - Breaking: List removed/changed fields, endpoints, validations
-   - Feature: List added fields, endpoints, optional extensions
-
-3. **Identify Affected Phases** (using PHASE_DEPENDENCY_MAP.md)
-   ```
-   Phase 1 API spec change → 
-     Phase 2 tests need API response type updates
-     Phase 3 backend implementation affected
-     Phase 4 client SDK needs updates
-     Phase 5 integration tests need new scenarios
-   ```
-
-4. **Record in SPEC_CHANGELOG.md** (auto-append if not done)
-   ```
-   - 2026-05-31T14:32:00Z | BREAKING | API response field 'user.avatar' removed
-     Affected: Phase 2 (test mocks), Phase 3 (API contract), Phase 4 (client SDK), Phase 5 (e2e tests)
-   ```
-
-**Output**: Change detection report (type, impact, affected phases)
-
----
-
-### Phase 2: Downstream Impact Analysis (10 min)
-
-**Input**: Change detection report + PHASE_DEPENDENCY_MAP.md
-
-**Process**:
-
-1. **Build Dependency Graph**
-   ```
-   Phase 1 (API Contract)
-     ├─→ Phase 2 (Tests)
-     ├─→ Phase 3 (Backend Implementation)
-     └─→ Phase 4 (Client SDK)
-   
-   Phase 2 (Tests)
-     ├─→ Phase 3 (Implementation must pass tests)
-     └─→ Phase 5 (E2E tests)
-   
-   Phase 3 (Backend Implementation)
-     ├─→ Phase 4 (Client SDK)
-     └─→ Phase 5 (E2E tests)
-   ```
-
-2. **Trace Propagation Path** (DFS from change point)
-   - Direct dependents: Phase 2, 3, 4
-   - Transitive dependents: Phase 5
-   - List order of updates needed (topological sort)
-
-3. **Identify Update Type Per Phase**
-   - Phase 2: Update mocks, test data, assertions
-   - Phase 3: Update API handler, response builder, validation
-   - Phase 4: Update client method signatures, serialization
-   - Phase 5: Add new scenarios, update expectations
-
-4. **Check for Conflicts**
-   - Does this breaking change conflict with Phase 3 implementation?
-   - Does Phase 4 client have workarounds we need to update?
-   - Are there Phase 5 tests that would break?
-
-5. **Estimate Manual Work**
-   - Breaking change: 2-4 hours (requires design decisions)
-   - Feature change: 30-60 minutes
-   - Non-impact: 5-10 minutes
-
-**Output**: Impact analysis (affected phases, update type per phase, conflict flags, time estimate)
-
----
-
-### Phase 3: Automatic Phase Updates (15 min)
-
-**Input**: Impact analysis + affected contract files
-
-**Process**:
-
-1. **Update Phase 2 (Tests)**
-   - Read current test files (e.g., `tests/api-mocks.test.js`)
-   - Update mock data to match new API spec
-   - Update assertions to match new field types/presence
-   - Update test descriptions for new scenarios
-   - Output: Updated test file + change summary
-
-2. **Update Phase 3 (Backend Implementation)**
-   - Read current API contract (`contracts/api/response.json`)
-   - Update response schema to match API spec
-   - Add migration notes (if breaking change)
-   - Update backend handler docstring
-   - Output: Updated contract + handler docs
-
-3. **Update Phase 4 (Client SDK)**
-   - Read current client types (`types/api.ts`)
-   - Update interface definitions
-   - Update serialization logic if needed
-   - Add deprecation warnings for removed fields
-   - Output: Updated types + deprecation notice
-
-4. **Update Phase 5 (E2E Tests)**
-   - Read current e2e scenarios (`playwright/e2e/scenarios.md`)
-   - Add new test scenarios for new fields
-   - Update assertions for changed fields
-   - Output: Updated scenarios + new test cases
-
-5. **Generate Migration Guide** (for breaking changes only)
-   - What changed & why
-   - Migration steps for downstream consumers
-   - Backward compatibility period (if any)
-   - Rollback procedure
-
-**Automatic Updates**: Use text replacement templates to update files systematically
-**Manual Review Point**: Breaking changes require human approval before commit
-
-**Output**: Updated phase files + migration guide (if needed)
-
----
-
-## Implementation Strategy
-
-### Change Detection Logic
-
-```javascript
-// Pseudocode: Detect spec change type
-function analyzeSpecChange(oldSpec, newSpec) {
-  const changes = {
-    breaking: [],
-    feature: [],
-    nonImpact: []
-  };
-  
-  // Check for removed/modified fields (BREAKING)
-  for (const field in oldSpec.properties) {
-    if (!newSpec.properties[field]) {
-      changes.breaking.push(`Removed field: ${field}`);
-    } else if (oldSpec.properties[field].type !== newSpec.properties[field].type) {
-      changes.breaking.push(`Changed type: ${field}`);
-    }
-  }
-  
-  // Check for new fields (FEATURE)
-  for (const field in newSpec.properties) {
-    if (!oldSpec.properties[field]) {
-      changes.feature.push(`Added field: ${field}`);
-    }
-  }
-  
-  // Check for non-structural changes (NON-IMPACT)
-  if (oldSpec.description !== newSpec.description) {
-    changes.nonImpact.push(`Updated description`);
-  }
-  
-  return changes;
-}
-```
-
-### Phase Dependency Mapping
-
-**File**: `.codebase/PHASE_DEPENDENCY_MAP.md`
-
-```
-# Phase Dependency Map
-
-## Direct Dependencies
-- Phase 1 (Contracts) → Phase 2, 3, 4
-- Phase 2 (Tests) → Phase 3, 5
-- Phase 3 (Implementation) → Phase 4, 5
-- Phase 4 (SDK) → Phase 5
-- Phase 5 (E2E) → Release
-
-## Change Impact Rules
-- API contract change → Tests, Backend, Client, E2E
-- DB schema change → Backend, Migrations, Tests
-- UI spec change → Frontend, E2E tests
-- Breaking change → Higher priority, requires review
-```
-
-### Auto-Update Templates
-
-**Pattern 1: Mock Data Update**
-```javascript
-// OLD
-const mockUser = { id: 1, name: 'John', avatar: '/avatar.png' };
-
-// AUTO-UPDATED (after avatar field removed)
-const mockUser = { id: 1, name: 'John' };
-```
-
-**Pattern 2: Type Definition Update**
-```typescript
-// OLD
-interface User {
-  id: number;
-  name: string;
-  avatar: string; // URL to user avatar
-}
-
-// AUTO-UPDATED
-interface User {
-  id: number;
-  name: string;
-  // avatar field removed in API v2
-}
-```
-
-**Pattern 3: Assertion Update**
-```javascript
-// OLD
-expect(response.avatar).toBeDefined();
-
-// AUTO-UPDATED (if field removed)
-expect(response).not.toHaveProperty('avatar');
-```
-
----
-
-## Validation Workflow (After Auto-Update)
-
-### Pre-Commit Validation (MANDATORY)
-
-1. **Syntax Check**: All updated files are valid JSON/JS/TS
-2. **Contract Alignment**: Updated contracts match actual changes
-3. **Test Consistency**: Updated tests still make sense semantically
-4. **Type Safety**: Types defined in Phase 4 match Phase 3 API contract
-5. **Cross-Phase Validation**:
-   - Phase 3 types ⊆ Phase 4 client types ✓
-   - Phase 2 test data matches Phase 3 API contract ✓
-   - Phase 5 tests reference existing Phase 4 client methods ✓
-
-### Validation Checklist
-
-```markdown
-## Spec Propagation Validation
-
-- [ ] Change detection correct? (type identified)
-- [ ] Affected phases identified? (no missing phases)
-- [ ] Phase 2 tests updated?
-  - [ ] Mocks match new spec
-  - [ ] Assertions updated
-  - [ ] No broken assertions
-- [ ] Phase 3 contract updated?
-  - [ ] Schema matches API spec
-  - [ ] Docstrings accurate
-- [ ] Phase 4 SDK updated?
-  - [ ] Types match API contract
-  - [ ] No type mismatches
-- [ ] Phase 5 E2E updated?
-  - [ ] Scenarios reference updated SDK
-  - [ ] No broken references
-- [ ] Cross-phase validation passes?
-  - [ ] All files are syntactically valid
-  - [ ] No circular dependencies
-  - [ ] Migration guide complete (if breaking)
-- [ ] SPEC_CHANGELOG.md entry added?
-```
-
----
-
-## Auto-Trigger Integration
-
-### Hook: PreToolUse for `/spec-change`
-
-**Location**: `.instructions.md` (PreToolUse Hook #5)
-
-```yaml
-BEFORE /spec-change executes:
-  1. Verify change is documented
-  2. Confirm change type (breaking/feature/non-impact)
-  3. Preview affected phases
-
-AFTER /spec-change completes successfully:
-  → Activate genesis-spec-propagation skill
-  
-  1. Change Detection (5 min)
-     - Analyze spec difference
-     - Identify breaking vs feature
-     - Map affected phases
-     - Record in SPEC_CHANGELOG.md
-  
-  2. Impact Analysis (10 min)
-     - Build dependency graph
-     - Trace propagation paths
-     - Identify update types
-     - Estimate effort
-  
-  3. Auto-Update (15 min)
-     - Update Phase 2 tests
-     - Update Phase 3 backend contract
-     - Update Phase 4 client SDK
-     - Update Phase 5 E2E tests
-     - Generate migration guide
-  
-  4. Validation (5 min)
-     - Syntax check all files
-     - Cross-phase validation
-     - Run affected test suites
-     - Confirm all phases aligned
-  
-  5. Completion (2 min)
-     - Create SPEC_CHANGE_PROPAGATION.md log
-     - Update CURRENT_STATE.md
-     - Ready for commit
-  
-  **CRITICAL**: No breaking change commits without review
-  **CRITICAL**: All downstream phases must be updated
-  **Non-optional**: Part of /spec-change completion criteria
-```
-
----
-
-## Integration with Other Skills
-
-| Skill | Integration Point |
-|-------|-------------------|
-| **genesis-research** | Research best practices for API changes |
-| **genesis-api-contract** | Generate new API contracts after change |
-| **genesis-ui-ux-test** | Update test scenarios based on spec |
-| **genesis-harness-engineering** | Orchestrate multi-phase updates |
-| **genesis-docs** | Auto-update API docs after propagation |
-| **genesis-release** | Use SPEC_CHANGELOG for release notes |
-| **spec-impact-engine** | Base dependency tracking |
-
----
-
-## Token Efficiency Rules
-
-### Cache Aggressively
-- Cache PHASE_DEPENDENCY_MAP.md (rarely changes)
-- Cache contract templates (reusable)
-- Cache update patterns (pattern matching)
-
-### Summarize, Don't Repeat
-- When reporting changes: "Phase 2,3,4,5 affected" not full text
-- When proposing updates: Show before/after, not full file
-- When validating: Report issues only, not passing checks
-
-### Reuse Analysis
-- Store dependency graph in session memory (use across operations)
-- Reuse contract analysis within same session
-- Link to previous propagation logs (avoid re-analyzing)
-
-**Target**: 40-50 min for medium change with caching (vs 45+ min manual)
-
----
-
-## Success Criteria
-
-✅ **Automated**: /spec-change auto-triggers propagation (zero manual steps)
-✅ **Complete**: All affected phases updated (2-5 scanned)
-✅ **Validated**: Cross-phase consistency verified before commit
-✅ **Documented**: SPEC_CHANGELOG.md + migration guides complete
-✅ **Reversible**: Rollback procedure documented for breaking changes
-✅ **Efficient**: 25-30 min execution vs 45+ min manual (40% time savings)
-✅ **Enforced**: Pre-commit gate prevents misaligned phases
-
----
-
-## Output Artifacts
-
-### Per Spec Change
-
-1. **SPEC_CHANGE_PROPAGATION.md** (Investigation log)
-   - Change detected
-   - Affected phases
-   - Updates applied
-   - Validation results
-   - Migration guide (if breaking)
-
-2. **Updated Contract Files**
-   - Phase 2: `tests/api-mocks.test.js` (updated mocks)
-   - Phase 3: `contracts/api/response.json` (updated schema)
-   - Phase 4: `types/api.ts` (updated types)
-   - Phase 5: `playwright/e2e/scenarios.md` (updated scenarios)
-
-3. **SPEC_CHANGELOG.md Entry** (auto-append)
-   ```
-   - 2026-05-31T14:32:00Z | BREAKING | API field change
-     Auto-updated phases: 2, 3, 4, 5 | Migration guide: /docs/migration-v2-to-v3.md
-   ```
-
-4. **Migration Guide** (for breaking changes)
-   - What changed & why
-   - Impact for consumers
-   - Migration steps
-   - Timeline & deadlines
-   - Rollback procedure
-
----
-
-## Recovery & Rollback
-
-### If Propagation Breaks Tests
-
-1. **Identify Breaking Phase**: Which phase fails?
-2. **Root Cause**: Is it auto-update error or actual incompatibility?
-3. **Recover**:
-   - If auto-update error: Revert change, fix pattern, re-run propagation
-   - If incompatibility: Manual review + design decision needed
-4. **Document**: Add to RECOVERY_POINTS.md with solution
-
-### Rollback to Previous Spec State
-
-```bash
-# If propagation introduced bugs:
-git revert <propagation-commit>
-
-# Verify all phases revert correctly
-npm test
-
-# Then manually review the spec change requirement
-```
-
----
-
-## Related Documentation
-
-- [PHASE_DEPENDENCY_MAP.md](.codebase/PHASE_DEPENDENCY_MAP.md) - Phase dependencies
-- [SPEC_CHANGELOG.md](.codebase/SPEC_CHANGELOG.md) - Change history
-- [Contract Management](contracts/README.md) - Contract structures
-- [Database Schema Evolution](docs/schema-evolution.md) - Migration patterns
+1. Re-read the impact report and dependency map.
+2. Restore the last known aligned contracts/fixtures if propagation fails.
+3. Re-apply changes one affected phase at a time.
+4. Record unresolved risk in `.codebase/RECOVERY_POINTS.md`.
+
+## Workflow references
+- `checklists/spec-change-detection.md`: impact classification checklist.
+- `checklists/phase-update-verification.md`: downstream update checklist.
+- `playbooks/feature-change-propagation.md`: additive change workflow.
+- `playbooks/breaking-change-propagation.md`: breaking change workflow.
+- `templates/migration-guide-template.md`: migration guide shape.
+- `observability/propagation-tracking.md`: tracking and metrics format.

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