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

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-beta.0",
+  "version": "0.1.3",
   "description": "All-in-one AI Flow Kit for team development with Claude AI - skills, templates, and MCP adapters",
   "author": "Example Team",
   "publishConfig": {

package/scripts/create-score-excel.js

@@ -193,9 +193,9 @@ function buildRow(email, u) {
 }
 
 // ── Excel writer ───────────────────────────────────────────────────────────
-async function writeExcel(rows, outputPath) {
+async function writeExcel(rows, outputPath, sheetLabel, fromLabel, toLabel) {
   const workbook = new ExcelJS.Workbook();
-  const sheet = workbook.addWorksheet('Score 18-24.05.2026');
+  const sheet = workbook.addWorksheet(`Score ${sheetLabel}`);
 
   sheet.columns = [
     { key: 'no',           width: 5  },
@@ -220,7 +220,7 @@ async function writeExcel(rows, outputPath) {
   };
 
   // Title row
-  sheet.addRow(['AI Flow Kit — Weekly Score Report: 18/05/2026 – 24/05/2026']);
+  sheet.addRow([`AI Flow Kit — Weekly Score Report: ${fromLabel} – ${toLabel}`]);
   sheet.mergeCells('A1:N1');
   const title = sheet.getCell('A1');
   title.font      = { bold: true, size: 13, color: { argb: 'FF1F3864' } };
@@ -296,7 +296,7 @@ const CANONICAL_USERS = [
   'nguyenlt@relipasoft.com',
   'thuongvv@relipasoft.com',
   'yenvtb@relipasoft.com',
-  'tructth@relipasoft.com',
+  'tructh@relipasoft.com',
   'thainq@relipasoft.com',
   'tuoittx@relipasoft.com',
   'hungdv@relipasoft.com',
@@ -323,8 +323,21 @@ const EMPTY_USER = (email) => ({
 
 // ── Main ───────────────────────────────────────────────────────────────────
 (async () => {
-  const logFile    = path.join(__dirname, '..', 'tellog', 'log_18-05-2026_24-05-2026');
-  const outputFile = path.join(__dirname, '..', 'tellog', 'log_18-05-2026_24-05-2026_new.xlsx');
+  // Usage: node create-score-excel.js [log-file-stem]
+  // e.g.:  node create-score-excel.js log_08-06-2026_14-06-2026
+  const stem = process.argv[2] || 'log_18-05-2026_24-05-2026';
+
+  // Derive display dates from stem: log_DD-MM-YYYY_DD-MM-YYYY → DD/MM/YYYY – DD/MM/YYYY
+  const dateMatch = stem.match(/log_(\d{2}-\d{2}-\d{4})_(\d{2}-\d{2}-\d{4})/);
+  const [fromLabel, toLabel] = dateMatch
+    ? [dateMatch[1].replace(/-/g, '/'), dateMatch[2].replace(/-/g, '/')]
+    : ['?', '?'];
+  const sheetLabel = dateMatch
+    ? `${dateMatch[1].slice(0,5).replace(/-/g,'.')}-${dateMatch[2].slice(0,5).replace(/-/g,'.')}.${dateMatch[1].slice(6,10)}`
+    : stem;
+
+  const logFile    = path.join(__dirname, '..', 'tellog', stem);
+  const outputFile = path.join(__dirname, '..', 'tellog', `${stem}.xlsx`);
 
   const rawUsers = parseLog(logFile);
 
@@ -350,5 +363,5 @@ const EMPTY_USER = (email) => ({
     return buildRow(email, u);
   });
 
-  await writeExcel(rows, outputFile);
+  await writeExcel(rows, outputFile, sheetLabel, fromLabel, toLabel);
 })();

package/scripts/detect.js

@@ -64,6 +64,16 @@ class TaskDetector {
                 antiKeywords: ['code'],
                 icon: '📖',
                 description: 'Writing documentation'
+            },
+            'testing': {
+                keywords: [
+                    'test', 'testing', 'unit test', 'integration test', 'e2e',
+                    'qa', 'quality assurance', 'coverage', 'spec', 'assert',
+                    'mock', 'stub', 'test case', 'test suite', 'automated test'
+                ],
+                antiKeywords: [],
+                icon: '🧪',
+                description: 'Writing tests and QA'
             }
         };
     }

package/scripts/guide.js

@@ -181,6 +181,14 @@ function showCommands() {
                 ['aiflow detect "<description>"', '', 'Auto-detect task type'],
             ]
         },
+        {
+            group: 'QA Execute Flow',
+            items: [
+                ['aiflow execute <TICKET-ID>', '', 'Execute tests from ticket (taskType: execute)'],
+                ['aiflow execute <TC-FILE>', '', 'Execute tests from TC file path'],
+                ['aiflow execute', '', 'Execute tests — manual (AI asks for TC file)'],
+            ]
+        },
         {
             group: 'Task management',
             items: [
@@ -279,6 +287,7 @@ function showPromptGuide() {
         ['refactor',         'Improving code without changing behavior'],
         ['impact-analysis',  'Analyzing the impact of changes'],
         ['documentation',    'Writing docs, README, API reference'],
+        ['testing',          'Writing tests, test coverage, QA'],
     ];
 
     for (const [type, when] of types) {

package/scripts/prompt.js

@@ -215,6 +215,42 @@ AI must:
 5. Display "GATE 1: Impact report complete" → wait for **APPROVED**
 
 **Do NOT make any code changes.** Implementation needs a separate ticket.
+`,
+    },
+    'testing': {
+        header: 'Testing',
+        instruction: 'Write tests for the feature or scenario described below.',
+        skillWorkflow: `
+## STRICT GATE WORKFLOW — Testing
+
+### GATE 1 — AI Analyze Requirement
+**INVOKE:** \`read-study-requirement\` skill
+AI must:
+1. Load ticket context + read source code thoroughly
+2. Understand what needs to be tested (unit, integration, e2e)
+3. If unclear → ask ONE question at a time
+4. Output \`plan/[ticket-id]/requirement.md\` with:
+   - Test scope and strategy
+   - Test cases to cover (happy path + edge cases + failure cases)
+   - Source code references
+   - Effort estimate
+5. Display "GATE 1: Test plan ready" → wait for **APPROVED**
+
+### GATE 2 — Implementation Plan
+**INVOKE:** \`generate-spec\` skill, then \`superpowers:writing-plans\`
+- Create detailed TDD test implementation plan.
+- Output \`plan/[ticket-id]/plan.md\`.
+- Display: "GATE 2 PAUSED: type APPROVED to start coding".
+
+### GATE 3 — Write Tests (TDD)
+Only runs after Gate 2 APPROVED.
+**INVOKE:** \`superpowers:test-driven-development\`
+- Write failing tests first → confirm FAIL → implement → confirm PASS.
+
+### GATE 4 — AI Self-Review (wait for APPROVED)
+**INVOKE:** \`superpowers:verification-before-completion\`
+All tests must PASS. Check coverage meets requirements.
+Display: "GATE 4 PAUSED: type APPROVED or BUG: [description]"
 `,
     },
     'documentation': {

package/scripts/scaffold-playwright.js

@@ -0,0 +1,106 @@
+'use strict';
+
+const fs = require('fs-extra');
+const path = require('path');
+const chalk = require('chalk');
+
+const PKG_DIR = path.join(__dirname, '..');
+const HARNESS_SRC = path.join(PKG_DIR, 'custom', 'harness', 'playwright');
+
+const HARNESS_FILES = [
+  'playwright.config.ts',
+  '.env.example',
+  'tests/e2e/pages/BasePage.ts',
+  'tests/e2e/fixtures/test.ts',
+  'tests/e2e/auth.setup.ts',
+  'tests/e2e/support/auth.ts',
+];
+
+const GITIGNORE_LINES = [
+  '# Playwright',
+  'playwright-report/',
+  'test-results/',
+  'tests/e2e/.auth/',
+  '.env',
+];
+
+const MCP_CONFIG = {
+  playwright: {
+    command: 'npx',
+    args: ['-y', '@playwright/mcp@latest', '--isolated', '--browser', 'chromium', '--headless'],
+  },
+};
+
+/**
+ * Scaffold Playwright E2E harness into a target project directory.
+ * @param {string} [targetDir]  Destination directory (defaults to process.cwd())
+ * @param {{ force?: boolean, silent?: boolean }} [opts]
+ * @returns {Promise<{ copied: string[], skipped: string[], mcpUpdated: boolean }>}
+ */
+async function scaffoldPlaywright(targetDir, opts) {
+  if (targetDir === undefined) targetDir = process.cwd();
+  var force = opts && opts.force ? true : false;
+  var silent = opts && opts.silent ? true : false;
+  var log = silent ? function () {} : console.log;
+
+  var result = { copied: [], skipped: [], mcpUpdated: false };
+
+  // ── Harness files ─────────────────────────────────────────────
+  for (var i = 0; i < HARNESS_FILES.length; i++) {
+    var relPath = HARNESS_FILES[i];
+    var src = path.join(HARNESS_SRC, relPath);
+    var dest = path.join(targetDir, relPath);
+    var exists = await fs.pathExists(dest);
+
+    if (!force && exists) {
+      log(chalk.gray('  ↷ Skipped (already exists): ' + relPath));
+      result.skipped.push(relPath);
+      continue;
+    }
+
+    await fs.ensureDir(path.dirname(dest));
+    await fs.copy(src, dest, { overwrite: true });
+    log(chalk.green('  ✓ ' + (exists ? 'Overwrote' : 'Created') + ': ' + relPath));
+    result.copied.push(relPath);
+  }
+
+  // ── .mcp.json ─────────────────────────────────────────────────
+  var mcpFile = path.join(targetDir, '.mcp.json');
+  var mcpConfig = { mcpServers: {} };
+  if (await fs.pathExists(mcpFile)) {
+    mcpConfig = await fs.readJson(mcpFile).catch(function () { return { mcpServers: {} }; });
+  }
+  if (!mcpConfig.mcpServers) mcpConfig.mcpServers = {};
+
+  if (!force && mcpConfig.mcpServers.playwright) {
+    log(chalk.gray('  ↷ Skipped .mcp.json playwright entry (already exists)'));
+  } else {
+    mcpConfig.mcpServers.playwright = MCP_CONFIG.playwright;
+    await fs.writeJson(mcpFile, mcpConfig, { spaces: 2 });
+    log(chalk.green('  ✓ Updated .mcp.json with playwright MCP server'));
+    result.mcpUpdated = true;
+  }
+
+  // ── .gitignore ────────────────────────────────────────────────
+  var gitignoreFile = path.join(targetDir, '.gitignore');
+  var gitignoreContent = '';
+  if (await fs.pathExists(gitignoreFile)) {
+    gitignoreContent = await fs.readFile(gitignoreFile, 'utf-8');
+  }
+  var missingLines = GITIGNORE_LINES.filter(function (line) {
+    return !gitignoreContent.includes(line);
+  });
+  if (missingLines.length > 0) {
+    var addition = '\n' + missingLines.join('\n') + '\n';
+    await fs.appendFile(gitignoreFile, addition);
+    log(chalk.green('  ✓ Updated .gitignore'));
+  }
+
+  return result;
+}
+
+module.exports = {
+  scaffoldPlaywright: scaffoldPlaywright,
+  HARNESS_FILES: HARNESS_FILES,
+  MCP_CONFIG: MCP_CONFIG,
+};

package/scripts/task.js

@@ -189,7 +189,7 @@ async function resumeTask(taskId) {
     await fs.writeJson(statePath, taskState, { spaces: 2 });
 
     console.log(chalk.green(`✓ Resumed task: ${taskId}`));
-    console.log(`  ${chalk.white('Gate:')}   ${taskState.currentGate} (${gateLabel(taskState.currentGate)})`);
+    console.log(`  ${chalk.white('Gate:')}   ${taskState.currentGate} (${gateLabel(taskState.currentGate, taskState.taskType)})`);
     console.log(`  ${chalk.white('Title:')}  ${ctx.title.substring(0, 70)}`);
     if (taskState.notes) console.log(`  ${chalk.white('Note:')}   ${taskState.notes}`);
     console.log(chalk.gray('\n  Open Claude to resume: claude'));
@@ -355,10 +355,11 @@ async function nextGate(taskId) {
     const summaryContent = await generateMarkdownSummary(taskState);
     await fs.writeFile(summaryPath, summaryContent, 'utf-8');
 
-    const gateLabels = { 1: 'Analyze', 2: 'Plan', 3: 'Code', 4: 'Review', 5: 'PR' };
+    const taskType = existing.taskType || 'feature';
     console.log(chalk.green(`✓ Gate ${currentGate} approved for ${resolvedId}.`));
     console.log(chalk.gray(`  Summary saved to: plan/${resolvedId}/task-summary.md`));
-    console.log(chalk.white(`\n  Next: Gate ${nextGateNum} — ${gateLabels[nextGateNum] || 'Done'}`));
+    const nextLabel = gateLabel(nextGateNum, taskType);
+    console.log(chalk.white(`\n  Next: Gate ${nextGateNum} — ${nextLabel}`));
     console.log(chalk.cyan(`\n  To continue in a fresh session (Recommended to avoid context pollution):`));
     console.log(chalk.gray(`    1. Open a NEW chatbox or terminal session.`));
     console.log(chalk.gray(`    2. Run: aiflow task resume ${resolvedId} (to load context).`));
@@ -418,21 +419,24 @@ async function detectCurrentGate(taskId) {
 }
 
 async function generateMarkdownSummary(taskState) {
+    const taskType = taskState.taskType || 'feature';
+    const maxGate  = taskType === 'testing' ? 4 : 5;
     const lines = [];
     lines.push(`# Task Summary: ${taskState.taskId}`);
     lines.push(`**Title:** ${taskState.title}`);
+    lines.push(`**Type:** ${taskType}`);
     lines.push(`**Status:** ${taskState.status}`);
-    lines.push(`**Current Gate:** ${taskState.currentGate} (${gateLabel(taskState.currentGate)})`);
+    lines.push(`**Current Gate:** ${taskState.currentGate} (${gateLabel(taskState.currentGate, taskType)})`);
     lines.push(`**Updated At:** ${new Date().toLocaleString()}`);
     lines.push(``);
     lines.push(`## Gate History`);
     lines.push(`| Gate | Status | Approved At |`);
     lines.push(`|------|--------|-------------|`);
-    for (let i = 1; i <= 5; i++) {
+    for (let i = 1; i <= maxGate; i++) {
         const approvedAt = taskState.gateApprovals && taskState.gateApprovals[String(i)];
         const status = approvedAt ? '✅ Approved' : (i === taskState.currentGate ? '⏳ In Progress' : '⚪ Pending');
         const timeStr = approvedAt ? new Date(approvedAt).toLocaleString() : '-';
-        lines.push(`| Gate ${i} (${gateLabel(i)}) | ${status} | ${timeStr} |`);
+        lines.push(`| Gate ${i} (${gateLabel(i, taskType)}) | ${status} | ${timeStr} |`);
     }
     lines.push(``);
     lines.push(`---`);
@@ -440,7 +444,16 @@ async function generateMarkdownSummary(taskState) {
     return lines.join('\n');
 }
 
-function gateLabel(n) {
+function gateLabel(n, taskType) {
+    if (taskType === 'testing') {
+        const labels = {
+            1: 'Phân tích & Confirm',
+            2: 'Lập kế hoạch Test',
+            3: 'Thực thi & Evidence',
+            4: 'Báo cáo & Sign-off',
+        };
+        return labels[n] || `Gate ${n}`;
+    }
     const labels = {
         1: 'AI Analyze Requirement',
         2: 'Implementation Plan',
@@ -494,6 +507,7 @@ module.exports.createOrActivateTaskState = async function createOrActivateTaskSt
         ...existing,
         taskId,
         title:         ctx.title || '',
+        taskType:      ctx.taskType || existing.taskType || 'feature',
         status:        'active',
         createdAt:     existing.createdAt || now,
         updatedAt:     now,