@relipa/ai-flow-kit 0.1.2 → 0.1.4-beta.0

package/custom/skills/gate-review/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: gate-review
+description: Generate a checkbox review file for a gate output and verify it when APPROVED is received. Called at every gate pause point in both dev and tester workflows.
+keywords: gate review, checkbox, review file, approved, mandatory review
+---
+
+# Gate Review — Mandatory Checkbox Protocol
+
+> **Purpose:** Prevent blind approval. Every gate output gets a review file with one checkbox per key section. Developer checks off items in VSCode. APPROVED is only accepted after all items are checked.
+
+---
+
+## When to invoke this skill
+
+This skill is invoked in **two modes** at every gate pause point:
+
+| Mode | When | What AI does |
+|------|------|-------------|
+| `generate` | Immediately after AI finishes gate output | Write `.aiflow/review/gate-N-[ticket].md` |
+| `verify` | When developer types `APPROVED` | Run `ak review check`, interpret result, proceed or block |
+
+---
+
+## File Naming Rules
+
+**Standard gates (Dev and Tester):**
+
+```
+.aiflow/review/gate-[N]-[ticket-id].md
+```
+
+**Tester Gate 2 sub-phases only:**
+
+Tester Gate 2 produces multiple review files — one per sub-phase. Use a letter suffix instead of the base gate number alone:
+
+```
+.aiflow/review/gate-2a-[ticket-id].md   ← first sub-phase
+.aiflow/review/gate-2b-[ticket-id].md   ← second sub-phase
+.aiflow/review/gate-2c-[ticket-id].md   ← third sub-phase
+(and so on)
+```
+
+> **IMPORTANT:** Do NOT use `gate-2-[ticket].md` for Tester Gate 2 sub-phases. Always use the lettered form (`gate-2a`, `gate-2b`, etc.) so each sub-phase has its own distinct review file and the `ak review check` command can target the correct file.
+
+---
+
+## Mode 1: GENERATE — Write Review File
+
+### Step 1: Extract checklist items from gate output
+
+Read the output you just created. For each **top-level section** in the output, create one checklist item — a one-line summary of what that section contains. The summary must be specific enough to identify the content without opening the output file.
+
+**Extraction rules:**
+- One item per top-level section (H2 heading or named block)
+- Format: `**[Section name]**: [one-line summary of actual content]`
+- Maximum 12 items per gate. If more than 12 sections, group related ones.
+- The summary is the actual content, not a description of the category. ✅ "Scope: Auth module + User management (payment OUT of scope)" not ❌ "Scope: the scope section"
+
+**Examples by gate:**
+
+Dev Gate 1 (requirement.md has 4 sections → 4 items):
+```
+- [ ] **Requirements Summary**: Add batch export endpoint returning signed S3 URL, triggered by POST /exports
+- [ ] **Proposed Solution**: New ExportService + S3Adapter; reuse existing AuthMiddleware for permissions
+- [ ] **Impact Analysis**: Medium — touches ExportController, UserService (permission check added)
+- [ ] **Effort Estimate**: M (3–4 days)
+```
+
+Tester Gate 1 (test-analysis.md):
+```
+- [ ] **Scope**: Auth module + User management only; payment and notifications OUT of scope
+- [ ] **Functional Analysis**: Login, logout, session management, password reset, role-based access (3 roles)
+- [ ] **Risk Areas**: High — session token handling; Medium — email format validation
+- [ ] **Test Approach**: 60% automation (Playwright), 40% manual; ~18 TCs estimated
+- [ ] **Effort Estimate**: M (2–3 days)
+```
+
+### Step 2: Write the review file
+
+**File path:** `.aiflow/review/gate-[N]-[ticket-id].md`
+
+For Tester Gate 2 sub-phases, use the lettered form: `.aiflow/review/gate-2a-[ticket-id].md`, `.aiflow/review/gate-2b-[ticket-id].md`, etc.
+
+Where `[ticket-id]` comes from `.aiflow/context/current.json` → `ticketId` field. If ticketId is unavailable, use `unknown`.
+
+**File template:**
+
+```markdown
+# Gate [N] Review — [TICKET-ID]
+> Status: PENDING | Generated: YYYY-MM-DD
+
+## How to review
+- Toggle `[ ]` → `[x]` for each item you have read and agree with
+- Add a comment under any item you want changed: `<!-- your comment here -->`
+- Type `APPROVED` in chat when done
+
+---
+
+## Checklist
+
+- [ ] **[Section]**: [one-line summary]
+- [ ] **[Section]**: [one-line summary]
+(... one per section, max 12)
+
+---
+
+## Review Notes
+<!-- Optional: overall notes -->
+```
+
+### Step 3: Display gate pause message
+
+After writing the file, display in chat:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+⏸️  GATE [N] PAUSED — REVIEW REQUIRED
+
+📋 Open in VSCode: [.aiflow/review/gate-[N]-[ticket-id].md](.aiflow/review/gate-[N]-[ticket-id].md)
+
+  • Toggle [ ] → [x] for each item you agree with
+  • Add <!-- comment --> under any item needing changes
+  • Type APPROVED when all items are addressed
+
+⚠️  APPROVED will not be accepted until all checkboxes are checked.
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+---
+
+## Mode 2: VERIFY — Check Review File on APPROVED
+
+When the developer types `APPROVED`, run this before accepting:
+
+### Step 1: Run CLI check
+
+```bash
+ak review check --gate [N] --ticket [ticket-id]
+```
+
+For Tester Gate 2 sub-phases, pass the lettered gate identifier:
+
+```bash
+ak review check --gate 2a --ticket [ticket-id]
+ak review check --gate 2b --ticket [ticket-id]
+```
+
+### Step 2: Interpret result
+
+**Exit code 0 — all checked:**
+- Gate proceeds normally
+- Run telemetry: `ak gate [N] approved --ticket [ticket-id]`
+- Continue to next gate
+
+**Exit code 1 — file missing:**
+```
+  ✗ Review file not found for gate N, ticket PROJ-33
+```
+AI response:
+> "The review file wasn't found. Let me regenerate it."
+Then re-run Mode 1 (generate) and display the gate pause message again.
+
+**Exit code 1 — items with comments (need revision):**
+```
+  Items with comments (need AI revision):
+    • **Risk Areas**: High — session token handling
+      Comment: "Missing: SQL injection risk on login form"
+```
+AI response:
+1. Read each comment
+2. Update the specific section in the gate output file
+3. Rewrite only the flagged items in the review file (keep already-checked `[x]` items as-is)
+4. Display updated gate pause message
+
+**Exit code 1 — unchecked items, no comment:**
+```
+  Items unchecked (no comment):
+    • **Scope**: Auth module only
+```
+AI response:
+> "Item(s) are unchecked without a comment. Please either:
+> - Check `[x]` if you agree with the content, or
+> - Add `<!-- your comment -->` on the next line if you want changes."
+Do NOT re-generate. Wait for developer to update the file.
+
+---
+
+## Mandatory Rules
+
+- ❌ **NEVER** accept `APPROVED` without first running `ak review check`
+- ❌ **NEVER** re-generate already-checked `[x]` items when doing a partial revision
+- ✅ **ALWAYS** create `.aiflow/review/` directory if it doesn't exist (use `mkdir -p`)
+- ✅ **ALWAYS** use the ticket ID from `.aiflow/context/current.json` in the file name
+- ✅ **ALWAYS** keep review items specific to the actual content — not generic category names
+- ✅ **ALWAYS** use lettered suffixes (`gate-2a`, `gate-2b`, …) for Tester Gate 2 sub-phases — never plain `gate-2`

package/custom/skills/generate-test-report/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: generate-test-report
+description: Use when TESTER needs to generate the final test summary report at Gate 4 after all test execution is complete. Aggregates results from evidence/ and bugs/ directories, verifies acceptance criteria coverage, and produces a Go/No-Go recommendation.
+keywords: test report, summary, sign-off, go no-go, gate 4, evidence, bug summary, coverage
+---
+
+# Generate Test Report — Gate 4
+
+> **Phạm vi:** Gate 4 — Báo cáo & Sign-off trong workflow 4-gate (`docs/workflow.md`)
+> **Chỉ chạy sau khi Gate 3 đã được TESTER gõ `APPROVED`.**
+
+---
+
+## Điều kiện vào Gate 4
+
+- ✅ Gate 3 APPROVED — tất cả critical/high bugs đã resolved và re-tested
+- ✅ Đã có đầy đủ: `evidence/`, `bugs/`, `test-plan/test-cases/`, `test-plan/checklist.md`
+- ✅ `test-plan/impact-analysis.md` tồn tại (kể cả khi không có PR — file ghi "chưa có dev artifacts")
+
+---
+
+## Quy trình tạo Test Report
+
+### Bước 1 — Thu thập kết quả
+
+Đọc toàn bộ:
+- `evidence/*/result.md` → đếm Pass / Fail / Blocked per TC
+- `bugs/BUG-*.md` → đếm bugs theo severity, trạng thái resolved/unresolved
+- `test-plan/test-cases/*.md` → danh sách TC ID và module
+
+Tổng hợp per module theo format template (R1/R2 tracking từ testcase files).
+
+### Bước 2 — Kiểm tra coverage
+
+- So sánh TC đã thực thi với checklist `test-plan/checklist.md`
+- Verify acceptance criteria từ `test-plan/test-analysis.md` (Gate 1) — từng item đã cover chưa?
+- Tính % hoàn thành: `(Tổng passed / Total test cases) × 100`
+- **Verify regression scope từ `test-plan/impact-analysis.md`**: đọc "Đề xuất Regression TCs" — những regression TCs đó đã được execute chưa? Nếu chưa → flag trong report (không block Go/No-Go nhưng phải ghi nhận rõ).
+
+### Bước 3 — Đánh giá Exit Criteria & Go/No-Go
+
+| Điều kiện | Go | No-Go |
+|---|---|---|
+| Critical bugs | 0 unresolved | Còn ≥ 1 |
+| High bugs | 0 unresolved hoặc có deferred plan | Còn unresolved không có plan |
+| Coverage | ≥ 100% acceptance criteria covered | Còn AC chưa test |
+| Pass rate | Đạt ngưỡng exit criteria | Dưới ngưỡng |
+
+**Conditional Go:** Pass nhưng còn Medium/Low bugs chưa fix — ghi rõ điều kiện deferred.
+
+### Bước 4 — Viết Test Report
+
+**Dùng template:** `templates/test-report.md`
+
+Điền đầy đủ:
+- **Project Information:** lấy từ ticket context
+- **Test Execution Summary:** per module, R1/R2 stats, % hoàn thành
+- **Bug Summary:** tổng hợp từ `bugs/`
+- **Coverage:** acceptance criteria đã cover
+- **Sign-off Decision:** Go / No-Go / Conditional Go + lý do cụ thể
+
+Output: `test-plan/test-report.md`
+
+---
+
+## Gate 4 Display
+
+```
+⏸️ GATE 4: TEST REPORT READY
+
+Overall: [Pass / Fail / Conditional]
+Passed: [N/total] | Bugs unresolved: [N Critical / N High / N Medium / N Low]
+Coverage: [N]% acceptance criteria covered
+
+Recommendation: [Go / No-Go / Conditional go]
+[Nếu Conditional: điều kiện cụ thể]
+
+→ Review: [test-plan/test-report.md](test-plan/test-report.md)
+→ Type APPROVED to sign off and submit to Backlog/Jira
+→ Type NO-GO: [reason] to reject release
+```
+
+---
+
+## Xử lý phản hồi của TESTER
+
+**`APPROVED`** → Done. Hướng dẫn TESTER copy nội dung lên Backlog/Jira ticket.
+
+**`NO-GO: [reason]`** → Ghi nhận lý do vào test-report.md. List những gì cần fix trước khi release.
+
+---
+
+## Mandatory Rules
+
+- ❌ KHÔNG generate report khi còn critical bug chưa resolved
+- ❌ KHÔNG tự quyết Go/No-Go thay TESTER — chỉ đưa ra recommendation
+- ✅ PHẢI verify từng acceptance criteria từ Gate 1 trước khi kết luận coverage
+- ✅ PHẢI trích dẫn TC ID cụ thể khi claim "requirement X đã covered"
+- ✅ Bugs deferred PHẢI có justification rõ ràng trong report

package/custom/skills/generate-test-report/templates/test-report.md

@@ -0,0 +1,58 @@
+# SUMMARY TEST REPORT
+
+## Project Information
+
+| Property | Value | Property | Value |
+| :--- | :--- | :--- | :--- |
+| **Project Name** | [Project Name] | **Author/Created By** | [Author Name] |
+| **Project Code** | [Project Code] | **Reviewer** | [Reviewer Name] |
+| **Created At** | [Creation Date] | **Report Date** | [Report Date] |
+| **Last updated at** | [Update Date] | | |
+
+---
+
+## Test Execution Summary
+
+| No | Module Code | Written By | Created Date | R1 Passed | R1 Failed | R1 UnTest | R1 Pending | R2 Passed | R2 Failed | R2 UnTest | R2 Pending | Blocked | Total Test Cases | Tổng Passed | % Hoàn thành | Updated Date | Sprint | Creator | Reviewer / Approver |
+|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
+| 1 | [Module Code] | [Author] | [Date] | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0% | [Date] | [Sprint] | [Creator] | [Reviewer] |
+| 2 | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... |
+
+---
+
+## Bug Summary
+
+| Severity | Total | Resolved | Unresolved | Deferred |
+|---|---|---|---|---|
+| Critical | 0 | 0 | 0 | 0 |
+| High | 0 | 0 | 0 | 0 |
+| Medium | 0 | 0 | 0 | 0 |
+| Low | 0 | 0 | 0 | 0 |
+| **Total** | **0** | **0** | **0** | **0** |
+
+**Deferred bugs justification:**
+- [BUG-ID]: [Lý do defer và sprint xử lý]
+
+---
+
+## Acceptance Criteria Coverage
+
+| # | Acceptance Criteria | TC IDs | Status |
+|---|---|---|---|
+| 1 | [AC từ Gate 1] | [TC_001, TC_002] | ✅ Covered |
+| 2 | [AC từ Gate 1] | [TC_003] | ✅ Covered |
+| 3 | [AC từ Gate 1] | - | ❌ Not covered |
+
+**Coverage:** [N/N] acceptance criteria covered ([N]%)
+
+---
+
+## Sign-off Decision
+
+| Item | Value |
+|---|---|
+| **Overall Result** | Pass / Fail / Conditional |
+| **Recommendation** | Go / No-Go / Conditional Go |
+| **Conditions** (nếu Conditional) | [Mô tả điều kiện cụ thể] |
+| **Sign-off By** | [TESTER Name] |
+| **Sign-off Date** | [Date] |