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

package/custom/templates/shared/gate-workflow.md

@@ -5,12 +5,30 @@
 
 You have superpowers. When a ticket context exists in `.aiflow/context/current.json`:
 - **Consult the "AI Skill Registry"** below to find instructions for each skill (`SKILL.md`).
-- **AUTO-START Gate 1 immediately** — do NOT wait for the developer to ask.
-- Read instructions and follow the gate sequence below — NO EXCEPTIONS.
+- **AUTO-START Gate 1 immediately** — do NOT wait to be asked.
+- Read the context, **check `taskType`**, and follow the matching workflow — NO EXCEPTIONS.
 - **PROJECT CONVENTIONS:** Before writing any output file (plan, requirement, summary), read `custom/rules/project-conventions.md`. These rules override upstream skill defaults.
 
+### Workflow Selection
+
+Read `.aiflow/context/current.json` → check the `taskType` field:
+
+| `taskType` value | Workflow to follow |
+|---|---|
+| `testing` | **[TESTER] 4-Gate Testing Workflow** (below) |
+| `execute` | **[EXECUTE] Executing Flow** (below) |
+| `feature`, `bug-fix`, `refactor`, `investigation`, `documentation` | **[DEV] 5-Gate Development Workflow** (below) |
+| `create-spec` | **[BA] 4-Gate Spec Creation Workflow** (below) |
+| `create-testcase` | **[QA] 4-Gate TestCase Creation Workflow** (below) |
+
+If `taskType` is missing or unrecognized, default to the DEV workflow and ask ONE clarifying question.
+
 ---
 
+## [DEV] 5-Gate Development Workflow
+
+> **For:** `feature` · `bug-fix` · `refactor` · `investigation` · `documentation`
+
 ### GATE 1 — AI Analyze Requirement (auto-start)
 
 **INVOKE:** `read-study-requirement` skill
@@ -24,14 +42,20 @@ AI actively reads ticket + source code to understand the requirement:
    - Requirements summary, source code analysis
    - Proposed solution and approach
    - Impact analysis, effort estimate, testing plan
-6. Display "GATE 1: Requirement doc ready" → wait for **APPROVED**
+6. **INVOKE** `gate-review` skill (generate mode) — write `.aiflow/review/gate-1-[ticket-id].md`
+7. Display gate pause message from `gate-review` skill — wait for **APPROVED**
+
+**When APPROVED received:**
+→ **INVOKE** `gate-review` skill (verify mode) — run `ak review check --gate 1 --ticket [ticket-id]`
+→ If passed: run `ak gate 1 approved --ticket [ticket-id]` → proceed to Gate 2
+→ If blocked: follow gate-review skill response protocol
 
 > **Tip:** If auto-start doesn't trigger, the developer can start this gate by typing: **"start"**, **"Gate 1"** or **"Analyze ticket"**.
 
 DO NOT just check format — **understand the content and propose solutions**.
 
 > **Telemetry:** Run `ak gate 1 start --ticket [ticket-id]` when starting this gate (auto-start or when developer types "start"/"Gate 1"). Run as-is — do NOT append shell redirects like `2>$null` or `>/dev/null`.
-> Run `ak gate 1 approved --ticket [ticket-id]` immediately when APPROVED is received. Run as-is — do NOT append shell redirects.
+> Run `ak gate 1 approved --ticket [ticket-id]` after gate-review verify passes (see When APPROVED received block above). Run as-is — do NOT append shell redirects.
 
 ---
 
@@ -41,11 +65,16 @@ DO NOT just check format — **understand the content and propose solutions**.
 
 - Create a detailed TDD implementation plan based on the approved requirement.
 - Output `plan/[ticket-id]/plan.md` with the detailed TDD implementation plan.
-- Display: "GATE 2 PAUSED: type APPROVED to start coding".
-- CODE WILL NOT BE GENERATED until "APPROVED" is received.
+- **INVOKE** `gate-review` skill (generate mode) — write `.aiflow/review/gate-2-[ticket-id].md`
+- Display gate pause message from `gate-review` skill — CODE WILL NOT BE GENERATED until all items checked and APPROVED received.
+
+**When APPROVED received:**
+→ **INVOKE** `gate-review` skill (verify mode) — run `ak review check --gate 2 --ticket [ticket-id]`
+→ If passed: run `ak gate 2 approved --ticket [ticket-id]` → proceed to Gate 3
+→ If blocked: follow gate-review skill response protocol
 
 > **Telemetry:** Run `ak gate 2 start --ticket [ticket-id]` when starting this gate. Run as-is — do NOT append shell redirects.
-> Run `ak gate 2 approved --ticket [ticket-id]` immediately when APPROVED is received. Run as-is — do NOT append shell redirects.
+> Run `ak gate 2 approved --ticket [ticket-id]` after gate-review verify passes (see When APPROVED received block above). Run as-is — do NOT append shell redirects.
 
 ---
 
@@ -72,12 +101,21 @@ Mandatory order:
 3. Tick `custom/rules/review-checklist.md`
 4. Create `plan/[ticket-id]/summary.md`
 
-Then: "GATE 4 PAUSED: type APPROVED or BUG: [description]"
-- Coding bug -> fix -> repeat Gate 4.
-- Requirement bug -> return to Gate 1.
+Then:
+- **INVOKE** `gate-review` skill (generate mode) — write `.aiflow/review/gate-4-[ticket-id].md`
+- Display gate pause message from `gate-review` skill. Also accepts `BUG: [description]` (bypasses review check — goes directly to fix cycle).
+
+**When APPROVED received:**
+→ **INVOKE** `gate-review` skill (verify mode) — run `ak review check --gate 4 --ticket [ticket-id]`
+→ If passed: run `ak gate 4 approved --ticket [ticket-id]` → proceed to Gate 5
+→ If blocked: follow gate-review skill response protocol
+
+**When BUG: [description] received (no review check needed):**
+- Coding bug → fix → repeat Gate 4 (re-generate review file)
+- Requirement bug → return to Gate 1
 
 > **Telemetry:** Run `ak gate 4 start --ticket [ticket-id]` when starting this gate. Run as-is — do NOT append shell redirects.
-> Run `ak gate 4 approved --ticket [ticket-id]` immediately when APPROVED is received. Run as-is — do NOT append shell redirects.
+> Run `ak gate 4 approved --ticket [ticket-id]` after gate-review verify passes (see When APPROVED received block above). Run as-is — do NOT append shell redirects.
 
 ---
 
@@ -89,3 +127,375 @@ Only runs after Gate 4 has been APPROVED.
 Guide on creating a Pull Request with the ticket link.
 
 > **Telemetry:** Run `ak gate 5 start --ticket [ticket-id]` when starting this gate. Run as-is — do NOT append shell redirects.
+
+---
+
+## [TESTER] 4-Gate Testing Workflow
+
+> **For:** `testing`
+> **Interaction Rules:** Ask ONE clarifying question at a time — wait for TESTER reply before proceeding. NEVER batch questions.
+
+### GATE 1 — Phân tích & Confirm (auto-start)
+
+**INVOKE:** `test-analysis` skill
+
+1. Read `.aiflow/context/current.json` — ticket title, description, acceptance criteria
+2. Fetch linked docs if URLs present in description (`ak fetch-links <url>`)
+3. Analyze scope, functional flows, non-functional requirements, risks
+4. Ask clarifying questions — **ONE at a time**, wait for reply
+5. Write `test-plan/test-analysis.md`
+6. **INVOKE** `gate-review` skill (generate mode) — write `.aiflow/review/gate-1-[ticket-id].md`
+7. Display gate pause message from `gate-review` skill — wait for **APPROVED**
+
+> **Tip:** TESTER can trigger with: **"start"**, **"Gate 1"** or **"Analyze ticket"**.
+
+```
+⏸️ GATE 1: TEST ANALYSIS READY
+→ Review: [test-plan/test-analysis.md](test-plan/test-analysis.md)
+→ Type APPROVED to proceed to Gate 2
+```
+
+**When APPROVED received:**
+→ **INVOKE** `gate-review` skill (verify mode) — `ak review check --gate 1 --ticket [ticket-id]`
+→ If passed: `ak gate 1 approved --ticket [ticket-id]` → Gate 2
+→ If blocked: follow gate-review skill response protocol
+
+> **Telemetry:** Run `ak gate 1 start --ticket [ticket-id]` when starting this gate. Run as-is — do NOT append shell redirects.
+> Run `ak gate 1 approved --ticket [ticket-id]` after gate-review verify passes (see When APPROVED received block above). Run as-is — do NOT append shell redirects.
+
+---
+
+### GATE 2 — Lập Kế Hoạch Test (4 phases, each needs APPROVED)
+
+Only runs after Gate 1 APPROVED.
+
+> **Rule:** TESTER must approve each phase before AI moves to the next. Never merge phases.
+
+> **Telemetry:** Run `ak gate 2 start --ticket [ticket-id]` when starting Phase 2a. Run as-is — do NOT append shell redirects.
+
+#### Phase 2a — Scenarios & Checklist
+
+**INVOKE:** `generate-testcase` skill (Phase 2a)
+
+- If TESTER declared `PR: <url>` → **INVOKE** `pr-impact-analysis` skill (Dev Artifacts Check) first
+- Generate test scenarios/checklist TABLE covering: Happy Path, Negative, Validation, Boundary, Edge Cases, State Transitions, Role-based, Accessibility, Compatibility, Data Integrity, Integration, Exploratory
+- Save `test-plan/checklist.md`
+- **INVOKE** `gate-review` skill (generate mode) — write `.aiflow/review/gate-2a-[ticket-id].md`
+- Display gate pause message from `gate-review` skill — wait for **APPROVED**
+
+```
+⏸️ GATE 2a: SCENARIOS READY
+→ Type APPROVED to generate test cases
+```
+
+**When APPROVED received:**
+→ **INVOKE** `gate-review` skill (verify mode) — `ak review check --gate 2a --ticket [ticket-id]`
+→ If passed: `ak gate 2a approved --ticket [ticket-id]` → Phase 2b
+→ If blocked: follow gate-review skill response protocol
+
+#### Phase 2b — Generate Test Cases
+
+**INVOKE:** `generate-testcase` skill (Phase 2b)
+
+- Generate detailed test cases TABLE from Phase 2a checklist: `TC_ID | Scenario | Preconditions | Test Steps | Test Data | Expected Result`
+- TC_ID format: `TC_[Module]_[NNN]` (e.g. `TC_Login_001`)
+- Expected result ONLY from ticket/spec — never from PR/dev description
+- Save `test-plan/test-cases/`
+- **INVOKE** `gate-review` skill (generate mode) — write `.aiflow/review/gate-2b-[ticket-id].md`
+- Display gate pause message from `gate-review` skill — wait for **APPROVED**
+
+```
+⏸️ GATE 2b: TEST CASES READY
+→ Type APPROVED to proceed to review
+```
+
+**When APPROVED received:**
+→ **INVOKE** `gate-review` skill (verify mode) — `ak review check --gate 2b --ticket [ticket-id]`
+→ If passed: `ak gate 2b approved --ticket [ticket-id]` → Phase 2c
+→ If blocked: follow gate-review skill response protocol
+
+#### Phase 2c — Review & Optimize
+
+**INVOKE:** `generate-testcase` skill (Phase 2c)
+
+- Self-review: check duplicates, problematic TCs (vague steps, unmeasurable expected result), missing TCs, coverage gaps, accessibility/compatibility coverage
+- Output `test-plan/review-report.md` with action items
+- **INVOKE** `gate-review` skill (generate mode) — write `.aiflow/review/gate-2c-[ticket-id].md`
+- Display gate pause message from `gate-review` skill — wait for **APPROVED**
+
+```
+⏸️ GATE 2c: REVIEW COMPLETE
+→ Type APPROVED to finalize and generate scripts
+```
+
+**When APPROVED received:**
+→ **INVOKE** `gate-review` skill (verify mode) — `ak review check --gate 2c --ticket [ticket-id]`
+→ If passed: `ak gate 2c approved --ticket [ticket-id]` → Phase 2d
+→ If blocked: follow gate-review skill response protocol
+
+#### Phase 2d — Coverage Check & Playwright Scripts
+
+**INVOKE:** `coverage-check` skill
+
+- Apply all action items from Phase 2c
+- Generate coverage matrix (requirement → TC IDs)
+- Export final test case set to `test-plan/test-cases/final-testcases.md`
+- **INVOKE** `automation-testing` skill → generate Playwright scripts to `test-plan/test-scripts/`
+- **INVOKE** `gate-review` skill (generate mode) — write `.aiflow/review/gate-2d-[ticket-id].md`
+- Display gate pause message from `gate-review` skill — wait for **APPROVED**
+
+```
+⏸️ GATE 2: TEST PLAN READY
+Test cases: [N] total ([N] manual / [N] automation)
+Coverage: [N]% requirements covered
+Scripts: [N] Playwright specs generated
+→ Type APPROVED to proceed to Gate 3 (execution)
+```
+
+**When APPROVED received:**
+→ **INVOKE** `gate-review` skill (verify mode) — `ak review check --gate 2d --ticket [ticket-id]`
+→ If passed: `ak gate 2 approved --ticket [ticket-id]` → Gate 3
+→ If blocked: follow gate-review skill response protocol
+
+> **Telemetry:** Run `ak gate 2 approved --ticket [ticket-id]` after gate-review verify passes (see When APPROVED received block above). Run as-is — do NOT append shell redirects.
+
+---
+
+### GATE 3 — Thực Thi & Evidence
+
+Only runs after Gate 2 APPROVED.
+
+**Step 3.1 — Dev Artifacts Check (Gate 3 entry)**
+
+**INVOKE:** `pr-impact-analysis` skill — check for new commits since Gate 2. If delta found → propose TC additions → TESTER approves delta only before proceeding.
+
+**Step 3.2 — Execute Playwright**
+
+```bash
+BASE_URL=<url> npx playwright test --headed
+```
+
+**Step 3.3 — Organize Evidence**
+
+**INVOKE:** `evidence-aggregation` skill
+
+- Parse `test-results/results.json`
+- Create `evidence/TC_[ID]-[scenario]/` with screenshots + traces
+- Generate `result.md` per TC
+- Auto-draft `bugs/BUG-NNN-*.md` for failed TCs
+
+**Re-test loop** — when TESTER types `RETEST: [TC_ID]`:
+
+**INVOKE:** `retest-orchestration` skill
+- Re-run Dev Artifacts Check (detect new commits in dev fix)
+- Re-execute: `npx playwright test --grep "TC_ID_pattern" --headed`
+- Update evidence (create `run-N/` subfolder — never delete prior evidence)
+- Update bug status (RESOLVED / Still OPEN)
+
+**INVOKE** `gate-review` skill (generate mode) — write `.aiflow/review/gate-3-[ticket-id].md` — summarize execution results + bug list
+Display gate pause message from `gate-review` skill — wait for **APPROVED**
+
+```
+⏸️ GATE 3: EXECUTION COMPLETE
+Passed: [N] | Failed: [N] | Blocked: [N]
+Bugs: [N Critical] [N High] [N Medium] [N Low]
+→ Type APPROVED when all critical/high bugs resolved
+→ Type RETEST: [TC_ID] to re-execute
+→ Type PR: [url] to declare new dev PRs
+```
+
+**When APPROVED received:**
+→ **INVOKE** `gate-review` skill (verify mode) — `ak review check --gate 3 --ticket [ticket-id]`
+→ If passed: `ak gate 3 approved --ticket [ticket-id]` → Gate 4
+→ If blocked: follow gate-review skill response protocol
+
+> **Telemetry:** Run `ak gate 3 start --ticket [ticket-id]` when starting this gate. Run as-is — do NOT append shell redirects.
+
+---
+
+### GATE 4 — Báo Cáo & Sign-off
+
+Only runs after Gate 3 APPROVED.
+
+**INVOKE:** `generate-test-report` skill
+
+1. Aggregate results from `evidence/*/result.md`
+2. Summarize bugs from `bugs/BUG-*.md` by severity
+3. Verify acceptance criteria coverage from Gate 1
+4. Determine Go / No-Go: 0 unresolved Critical = Go
+5. Write `test-plan/test-report.md`
+
+- **INVOKE** `gate-review` skill (generate mode) — write `.aiflow/review/gate-4-[ticket-id].md` — summarize test report + go/no-go decision
+- Display gate pause message from `gate-review` skill. Also accepts `NO-GO: [reason]` (bypasses review check).
+
+```
+⏸️ GATE 4: TEST REPORT READY
+Decision: [GO / NO-GO]
+Passed: [N/total] | Bugs unresolved: [N]
+Coverage: [N]% acceptance criteria
+→ Type APPROVED to sign off
+→ Type NO-GO: [reason] to reject release
+```
+
+**When APPROVED received:**
+→ **INVOKE** `gate-review` skill (verify mode) — `ak review check --gate 4 --ticket [ticket-id]`
+→ If passed: `ak gate 4 approved --ticket [ticket-id]` → sign off complete
+→ If blocked: follow gate-review skill response protocol
+
+**When NO-GO: [reason] received (no review check needed):** reject release per reason.
+
+> **Telemetry:** Run `ak gate 4 start --ticket [ticket-id]` when starting this gate. Run as-is — do NOT append shell redirects.
+> Run `ak gate 4 approved --ticket [ticket-id]` after gate-review verify passes (see When APPROVED received block above). Run as-is — do NOT append shell redirects.
+
+---
+
+## [EXECUTE] Executing Flow
+
+> **For:** `execute`
+> **Entry points:** `ak execute TICKET-ID` · `ak execute ./path/to/testcases.md` · `ak execute` (manual)
+> **Interaction Rules:** Ask ONE clarifying question at a time — wait for TESTER reply before proceeding.
+
+### GATE 1 — Pre-flight & Work Plan (auto-start)
+
+**INVOKE:** `execute-flow` skill (from `custom/skills/execute-flow/SKILL.md`)
+
+Pre-flight checks (stop and report if any fail):
+0. **MCP Playwright is configured** — check `~/.claude/settings.json` (global user-level) for a `playwright` key in `mcpServers`. This is global — set once, works across all repos.
+   - If missing: ask TESTER "MCP Playwright chưa cấu hình. Tự động cài vào global settings (~/.claude/settings.json)? [Y/n]"
+   - If Y: read and update `~/.claude/settings.json` by merging the playwright entry into `mcpServers`, then instruct TESTER to **restart Claude Code** before retrying. Stop here.
+   - If n: show manual install instructions (add `playwright` to `mcpServers` in `~/.claude/settings.json`). Stop here.
+1. TC file is parseable — Section 3 has at least one TC row
+2. `ak-test/{repo}/` directory exists (or offer to scaffold it)
+3. `BASE_URL` env var is set
+4. `ak-test/{repo}/playwright.config.ts` exists (or offer to create from template)
+
+Then display work plan:
+
+- **INVOKE** `gate-review` skill (generate mode) — write `.aiflow/review/gate-1-[ticket-id].md`
+- Display gate pause message from `gate-review` skill — wait for **APPROVED**
+
+```
+⏸️ GATE 1: EXECUTE FLOW READY
+TC file: [path](path)
+Repo: [repo]
+Screen: [ScreenID] — [Screen Name]
+BASE_URL: [url]
+→ Type APPROVED to sync scripts (Gate 2)
+```
+
+**When APPROVED received:**
+→ **INVOKE** `gate-review` skill (verify mode) — `ak review check --gate 1 --ticket [ticket-id]`
+→ If passed: `ak gate 1 approved --ticket [ticket-id]` → Gate 2
+→ If blocked: follow gate-review skill response protocol
+
+> **Telemetry:** Run `ak gate 1 start --ticket [ticket-id]` when starting. Run `ak gate 1 approved --ticket [ticket-id]` when APPROVED.
+
+---
+
+### GATE 2 — Script Sync
+
+Only runs after Gate 1 APPROVED.
+
+**INVOKE:** `script-sync` skill (from `custom/skills/script-sync/SKILL.md`)
+
+Hash-based TC↔script sync — for each TC in the file:
+- **New TC** (no matching `@tc-hash` in spec): generate Playwright test using MCP (`browser_navigate` → `browser_snapshot` → `browser_generate_locator`). Never fabricate selectors.
+- **Changed TC** (hash mismatch): update the existing test block only.
+- **Unchanged TC** (hash matches): skip — do not touch.
+- **Manual/Blocked TC**: mark `⏭️ Untest` / `⏳ Pending` — no script generated.
+
+Output: `ak-test/{repo}/scripts/{screenId}/{ScreenID}.spec.ts` (1 file per screen, all TCs inside)
+
+- **INVOKE** `gate-review` skill (generate mode) — write `.aiflow/review/gate-2-[ticket-id].md`
+- Display gate pause message from `gate-review` skill — wait for **APPROVED**
+
+```
+⏸️ GATE 2: SCRIPT SYNC COMPLETE
+✅ New: [N] | 🔄 Updated: [N] | ⏭️ Skipped: [N] | ⚠️ Manual: [N]
+→ Type APPROVED to execute (Gate 3)
+```
+
+**When APPROVED received:**
+→ **INVOKE** `gate-review` skill (verify mode) — `ak review check --gate 2 --ticket [ticket-id]`
+→ If passed: `ak gate 2 approved --ticket [ticket-id]` → Gate 3
+→ If blocked: follow gate-review skill response protocol
+
+---
+
+### GATE 3 — Execute & Evidence
+
+Only runs after Gate 2 APPROVED.
+
+**Step 3.1 — Determine run number**
+
+Check `ak-test/{repo}/results/{screenId}/` — next run is `run-{N+1}`.
+
+**Step 3.2 — Execute Playwright**
+
+```bash
+BASE_URL=<url> npx playwright test scripts/{screenId}/{ScreenID}.spec.ts
+```
+
+**Step 3.3 — Organize evidence** into `ak-test/{repo}/results/{screenId}/run-{N}/`:
+- Per-TC folder `{TC_ID}-{scenario}/` with `step-NN-{desc}.png`, `trace.zip`, `result.md`
+- Auto-draft `bugs/BUG-NNN-{slug}.md` for failed TCs
+
+**Step 3.4 — Update TC file** R1/R2 columns:
+- `✅ Pass` · `❌ Fail` · `⏭️ Untest` · `⏳ Pending`
+
+**Re-test loop** — when TESTER types `RETEST: [TC_ID]`:
+- Re-run Dev Artifacts Check if PR was declared
+- Re-execute only the specified TCs
+- Create new `run-{N}/` — never delete prior runs
+- Update R1/R2 columns
+
+**INVOKE** `gate-review` skill (generate mode) — write `.aiflow/review/gate-3-[ticket-id].md`
+Display gate pause message from `gate-review` skill — wait for **APPROVED**
+
+```
+⏸️ GATE 3: EXECUTION COMPLETE
+Run: run-{N} | Passed: [N] | Failed: [N] | Untest: [N] | Pending: [N]
+→ Type APPROVED when all Critical/High bugs resolved
+→ Type RETEST: [TC_ID] to re-execute specific TCs
+→ Type PR: [url] to declare a dev fix PR
+```
+
+**When APPROVED received:**
+→ **INVOKE** `gate-review` skill (verify mode) — `ak review check --gate 3 --ticket [ticket-id]`
+→ If passed: `ak gate 3 approved --ticket [ticket-id]` → Gate 4
+→ If blocked: follow gate-review skill response protocol
+
+> **Telemetry:** Run `ak gate 3 start --ticket [ticket-id]` when starting. Run as-is — do NOT append shell redirects.
+
+---
+
+### GATE 4 — Report & Bug Logging
+
+Only runs after Gate 3 APPROVED.
+
+**Step 4.1** — Generate `ak-test/{repo}/results/{screenId}/run-{N}/testreport.md`:
+- Per-module rows with Pass/Fail/Untest/Pending counts, R1/R2 columns, % completion
+- Go/No-Go: 0 unresolved Critical = Go
+
+**Step 4.2** — Bug logging: for each `❌ Fail` TC, ask TESTER ONE at a time:
+> "BUG-NNN — [TC_ID]: [title]. Log to Jira? (Y/N/edit)"
+
+Wait for reply before moving to next bug.
+
+- **INVOKE** `gate-review` skill (generate mode) — write `.aiflow/review/gate-4-[ticket-id].md`
+- Display gate pause message from `gate-review` skill — wait for **APPROVED**
+
+```
+⏸️ GATE 4: REPORT READY
+Decision: [GO / NO-GO]
+Bugs logged: [N] | Skipped: [N]
+→ Review: [ak-test/{repo}/results/{screenId}/run-{N}/testreport.md](ak-test/{repo}/results/{screenId}/run-{N}/testreport.md)
+→ Type APPROVED to sign off
+```
+
+**When APPROVED received:**
+→ **INVOKE** `gate-review` skill (verify mode) — `ak review check --gate 4 --ticket [ticket-id]`
+→ If passed: `ak gate 4 approved --ticket [ticket-id]` → sign off complete
+→ If blocked: follow gate-review skill response protocol
+
+> **Telemetry:** Run `ak gate 4 start --ticket [ticket-id]` when starting. Run `ak gate 4 approved --ticket [ticket-id]` when APPROVED.

package/docs/common/CHANGELOG.md

@@ -7,6 +7,58 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [0.1.3] - 2026-06-18
+
+### Added
+
+- **`execute` task type — 4-Gate Executing Flow** — New end-to-end test execution workflow for QA testers. Activated when `taskType: "execute"` in context. Orchestrated by the new `execute-flow` skill across 4 gates:
+  - **Gate 1 — Pre-flight & Work Plan**: Validates TC file, `ak-test/{repo}/` directory, `BASE_URL` env var, and `playwright.config.ts` before any scripts are touched.
+  - **Gate 2 — Script Sync**: Hash-based TC↔script sync via the new `script-sync` skill. Each TC is hashed as `SHA1(TC_ID + "|" + Steps + "|" + Expected Result)[:8]` and compared against the `@tc-hash` comment in the spec file. New TCs get scripts generated via MCP browser tools; changed TCs update their existing block; unchanged TCs are skipped entirely.
+  - **Gate 3 — Execute & Evidence**: Runs `npx playwright test` and organizes evidence into `ak-test/{repo}/results/{screenId}/run-{N}/` with per-TC folders (screenshots, trace.zip, result.md). Auto-drafts bug files for failed TCs. Supports `RETEST: [TC_ID]` loop.
+  - **Gate 4 — Report & Bug Logging**: Generates `testreport.md` with Go/No-Go decision; logs each failed TC to Jira/Backlog one-by-one with interactive confirm per bug.
+
+- **`execute-flow` skill** (`custom/skills/execute-flow/SKILL.md`) — 4-gate execute flow orchestrator. Handles 3 entry points: `ak execute TICKET-ID` (ticket with `taskType: "execute"`), `ak execute ./path/to/testcases.md` (direct TC file), and `ak execute` (manual — AI asks for TC file). Output structure: `ak-test/{repo}/scripts/{screenId}/{ScreenID}.spec.ts` for scripts; `ak-test/{repo}/results/{screenId}/run-{N}/` for evidence.
+
+- **`script-sync` skill** (`custom/skills/script-sync/SKILL.md`) — Hash-based TC↔Playwright script sync engine. Called from execute-flow Gate 2. Never fabricates selectors — uses MCP browser tools (`browser_navigate` → `browser_snapshot` → `browser_generate_locator`) for any new/changed TC. Produces one `.spec.ts` per screen with all TCs inside, using `screenId` (lowercase) for directory paths and `{ScreenID}.spec.ts` (uppercase) for the filename.
+
+- **`playwright.config.ts` template** for execute-flow (`custom/skills/execute-flow/templates/playwright.config.ts`) — Default config for each `ak-test/{repo}` repo with HTML + JSON reporters, screenshot-on-failure, and trace-on-failure. AI offers to scaffold this file during Gate 1 pre-flight if it doesn't exist.
+
+- **`execute` entry in `gate-workflow.md` Workflow Selection table** — `gate-workflow.md` (single source of truth for all AI agent instruction files) now routes `taskType: "execute"` to the `[EXECUTE] Executing Flow` section. Distributed to all agents (Claude, Gemini, Cursor, Copilot) via `ak init` / `ak up`.
+
+- **`▶️ Execute Test` option in `ak use` type selector** — Both the `promptForTaskType()` shared function (Backlog/Jira loaders) and the `manualContext()` manual entry flow now include `execute` as a selectable type. Users can run `ak use --manual` or `ak use TICKET-ID` and choose "Execute Test" to route the AI to the execute-flow.
+
+- **`ak execute` command** (`ak ex` alias) — New top-level CLI entry point that bypasses `ak use`. Accepts a ticket ID, a TC file path, or no argument (AI asks interactively). Documented in README, QUICK_START, cli-reference, and `ak guide --commands`.
+
+- **`test-analysis` skill** (`custom/skills/test-analysis/SKILL.md`) — Gate 1 analysis skill for the [TESTER] workflow. Reads ticket context, fetches linked docs, analyzes scope and risk, asks clarifying questions one at a time, and writes `test-plan/test-analysis.md`.
+
+- **`coverage-check` skill** (`custom/skills/coverage-check/SKILL.md`) — Gate 2d skill that applies review action items, generates a requirement→TC coverage matrix, exports the final test case set to `test-plan/test-cases/final-testcases.md`, and invokes `automation-testing` to generate Playwright scripts.
+
+- **`evidence-aggregation` skill** (`custom/skills/evidence-aggregation/SKILL.md`) — Parses `test-results/results.json`, organizes screenshots and traces into `evidence/TC_[ID]-[scenario]/` folders, generates per-TC `result.md`, and auto-drafts `bugs/BUG-NNN-*.md` for failed TCs.
+
+- **`retest-orchestration` skill** (`custom/skills/retest-orchestration/SKILL.md`) — Handles the `RETEST: [TC_ID]` loop in Gate 3. Re-runs dev artifacts check (detect new commits), re-executes only specified TCs, creates `run-N/` subfolders (never deletes prior evidence), and updates bug status.
+
+- **`pr-impact-analysis` skill** (`custom/skills/pr-impact-analysis/SKILL.md`) — Checks for new commits/PRs between gates to ensure TC coverage stays current with dev changes.
+
+- **`log-bug` skill** (`custom/skills/log-bug/SKILL.md`) — Logs a failed TC as a bug ticket in Jira/Backlog with structured fields (severity, steps, expected/actual, evidence link).
+
+- **Playwright harness scaffold** — `ak scaffold playwright` (via `scripts/scaffold-playwright.js`) creates the `ak-test/{repo}/` directory structure with `playwright.config.ts`, `tests/e2e/fixtures/test.ts`, `tests/e2e/pages/BasePage.ts`, `tests/e2e/support/auth.ts`, and `.env.example`. Covered by 90-line Jest test suite in `tests/scaffold-playwright.test.js`.
+
+- **Playwright MCP preset** (`custom/mcp-presets/playwright.json`) — MCP configuration preset for browser automation tools used by `script-sync` during TC→script generation.
+
+- **`test-patterns.md` rules file** (`custom/rules/test-patterns.md`) — Team-level Playwright patterns and conventions referenced by `automation-testing` and `script-sync` skills.
+
+- **`generate-testcase` skill — Phase 2a/2b/2c structure** — Skill rewritten with explicit phased execution: Phase 2a (scenarios & checklist), Phase 2b (generate detailed TC table), Phase 2c (review & optimize). TC_ID format: `TC_[Module]_[NNN]`. Gate pauses after each phase.
+
+- **`automation-testing` skill — MCP browser integration** — Updated to document MCP tool sequence (`browser_navigate` → `browser_snapshot` → `browser_generate_locator`) for generating reliable Playwright locators without fabricating selectors.
+
+### Fixed
+
+- **`execute-flow` Gate 1 pre-flight missing `playwright.config.ts` check** — Original Gate 1 had 3 checks; spec required 4. Added explicit check for `ak-test/{repo}/playwright.config.ts` with offer to scaffold from template.
+- **`screenId` casing ambiguity in execute-flow/script-sync** — Directory paths use lowercase `screenId` (e.g. `ad10`); spec file names remain uppercase `{ScreenID}.spec.ts` (e.g. `AD10.spec.ts`). Both skills now explicitly document this distinction with examples to prevent AI from using wrong case.
+- **`--reporter` CLI flag overriding config reporters** — Gate 3 run command previously included `--reporter=json,html` which overrides (not appends) reporters defined in `playwright.config.ts`, causing the HTML report to be replaced entirely. Removed the flag; reporters are now defined solely in `playwright.config.ts`.
+
+---
+
 ## [0.1.2] - 2026-06-13
 
 ### Added

package/docs/common/QUICK_START.md

@@ -358,6 +358,31 @@ aiflow use PROJ-88
 claude                                # AI auto-starts: map dependencies → assess risk → output report
 ```
 
+### Execute Tests (QA Tester)
+
+Run existing test cases with Playwright — sync scripts, execute, collect evidence, and generate report.
+
+**Entry point 1: from a ticket** (ticket `type` must be `"execute"`)
+
+```bash
+aiflow use PROJ-44        # loads ticket with taskType "execute"
+claude                    # AI auto-starts execute-flow Gate 1 (pre-flight check)
+```
+
+**Entry point 2: from a TC file**
+
+```bash
+ak execute ./testcases/AD10.md        # AI starts execute-flow with this TC file
+```
+
+**Entry point 3: manual**
+
+```bash
+ak execute                            # AI asks: "TC file ở đâu?"
+```
+
+Output lands in `ak-test/{repo}/results/{screenId}/run-{N}/` — never deleted between runs.
+
 ### Figma Design → Code
 
 Turn a Figma design into a React / Next.js / Vue / Angular component automatically.
@@ -414,6 +439,11 @@ ak g -f                                        # architecture diagram  (ak guide
 ak g -c                                        # command reference  (ak guide --commands)
 ak sync                                        # sync aiflow instruction files  (ak sync-skills)
 
+# Execute flow (QA Tester)
+ak execute PROJ-44                             # execute từ ticket (taskType phải là "execute")
+ak execute ./testcases/AD10.md                 # execute từ TC file
+ak execute                                     # execute manual (AI hỏi TC file)
+
 # Per task
 ak use PROJ-33                                 # load context (Fast Mode, default) — alias: ak u PROJ-33
 ak use PROJ-33 PROJ-10 docs/arch.md            # multi-target: primary + supplementary (v0.1.0+)

package/docs/common/cli-reference.md

@@ -17,13 +17,13 @@ ak <alias> --help                # Also works with aliases
 | Full command | Short | Full command | Short |
 |---|---|---|---|
 | `ak init` | `ak i` | `ak use` | `ak u` |
-| `ak prompt` | `ak p` | `ak detect` | `ak d` |
-| `ak task` | `ak t` | `ak context` | `ak ctx` |
-| `ak checkpoint` | `ak cp` | `ak validate` | `ak vl` |
-| `ak memory` | `ak mem` | `ak guide` | `ak g` |
-| `ak remove` | `ak rm` | `ak update` | `ak up` |
-| `ak sync-skills` | `ak sync` | `ak doctor` | `ak dr` |
-| `ak telemetry` | `ak tel` | | |
+| `ak execute` | `ak ex` | `ak prompt` | `ak p` |
+| `ak detect` | `ak d` | `ak task` | `ak t` |
+| `ak context` | `ak ctx` | `ak checkpoint` | `ak cp` |
+| `ak validate` | `ak vl` | `ak memory` | `ak mem` |
+| `ak guide` | `ak g` | `ak remove` | `ak rm` |
+| `ak update` | `ak up` | `ak sync-skills` | `ak sync` |
+| `ak doctor` | `ak dr` | `ak telemetry` | `ak tel` |
 
 | `task` sub-command | Short | `memory` sub-command | Short |
 |---|---|---|---|
@@ -156,6 +156,47 @@ $ aiflow use PROJ-33 PROJ-10 docs/arch.md
 ✓ Auto-resolved 2 link(s) from description
 ```
 
+## execute (alias: `ex`)
+
+Execute test cases via the 4-gate Executing Flow. Syncs Playwright scripts, runs them, collects evidence, and generates a test report.
+
+```bash
+ak execute PROJ-44                           # from ticket (taskType must be "execute")
+ak execute ./testcases/AD10.md               # from TC file
+ak execute                                   # manual — AI asks for TC file
+```
+
+**Arguments:**
+- `[target]` — Optional. A ticket ID (`PROJ-44`), a path to a TC file (`./testcases/AD10.md`), or omitted for manual entry.
+
+**What it does (4 gates):**
+1. **Gate 1 — Pre-flight:** Parse TC file, verify `ak-test/{repo}/` and `playwright.config.ts` exist, check `BASE_URL`
+2. **Gate 2 — Script Sync:** Hash-based sync — gen new TCs, update changed, skip unchanged. Uses Playwright MCP for real selectors (never fabricates).
+3. **Gate 3 — Execute & Evidence:** Run Playwright, organize evidence into `run-{N}/`, update TC file R1/R2 columns (`✅ Pass` · `❌ Fail` · `⏭️ Untest` · `⏳ Pending`)
+4. **Gate 4 — Report & Bug Logging:** Generate `testreport.md`, confirm each bug with TESTER before logging to Jira
+
+**Output structure:**
+```
+ak-test/{repo}/
+├── scripts/{screenId}/{ScreenID}.spec.ts
+└── results/{screenId}/run-{N}/
+    ├── {TC_ID}-{scenario}/  (screenshots, trace.zip, result.md)
+    ├── bugs/BUG-NNN-{slug}.md
+    └── testreport.md
+```
+
+**Example:**
+```bash
+$ ak execute ./testcases/AD10.md
+⏸️ GATE 1: EXECUTE FLOW READY
+TC file: testcases/AD10.md
+Repo: repo-fe | Screen: AD10 — Create Product
+BASE_URL: http://localhost:3000
+→ Type APPROVED to sync scripts (Gate 2)
+```
+
+---
+
 ## fetch-links
 
 Fetch a single Backlog/Jira URL and print a `SupplementaryContext` JSON object to stdout. Intended for AI runtime use inside the `read-study-requirement` skill — when AI encounters a link in the ticket description that wasn't already resolved by `ak use`, it can call this command and integrate the JSON output.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relipa/ai-flow-kit",
-  "version": "0.1.2",
+  "version": "0.1.4-beta.0",
   "description": "All-in-one AI Flow Kit for team development with Claude AI - skills, templates, and MCP adapters",
   "author": "Example Team",
   "publishConfig": {
@@ -65,4 +65,4 @@
       "<rootDir>/tests/**/*.test.js"
     ]
   }
-}
+}