@relipa/ai-flow-kit 0.1.5 → 0.1.6

package/scripts/docs-branch.js

@@ -0,0 +1,264 @@
+const fs = require('fs-extra');
+const path = require('path');
+const chalk = require('chalk');
+const { execSync } = require('child_process');
+const { confirm } = require('@inquirer/prompts');
+const { resolveDocsRepoPath, DOC_REPOS } = require('./docs-repo');
+
+// Implements the branch + Merge Request half of docs/internal/Docs-Management-Flow.md:
+// PM reviews & merges into `main`; every other role updates docs on a
+// `feature/<functionId>/<taskId>` branch created from `main`, then submits a MR.
+//
+// Safety model (mirrors the rest of the kit's "AI drafts — human approves" rule,
+// see scripts/hooks/block-git-write.js): AI must never call these with --yes until
+// the developer has explicitly approved the plan in chat. Without --yes and without
+// an interactive TTY, both commands only print the plan and make no changes.
+
+const PROJECT_DIR = process.cwd();
+
+function sh(cmd, cwd) {
+    return execSync(cmd, { cwd, encoding: 'utf-8' }).trim();
+}
+
+// Same as sh(), but swallows stderr — for existence checks expected to fail often/normally.
+function shQuiet(cmd, cwd) {
+    return execSync(cmd, { cwd, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+}
+
+function isKnownRepoName(name) {
+    return DOC_REPOS.some((r) => r.name === name);
+}
+
+function resolveRepo(repoName) {
+    if (!isKnownRepoName(repoName)) {
+        console.log(chalk.red(`✗ Repo không hợp lệ: "${repoName}". Chỉ chấp nhận: ${DOC_REPOS.map((r) => r.name).join(', ')}`));
+        return null;
+    }
+    const repoPath = resolveDocsRepoPath(PROJECT_DIR, repoName);
+    if (!fs.pathExistsSync(repoPath) || !fs.pathExistsSync(path.join(repoPath, '.git'))) {
+        console.log(chalk.red(`✗ ${repoName}/ không tồn tại hoặc không phải git repo tại ${repoPath}.`));
+        console.log(chalk.gray(`  Hãy clone repo này vào thư mục root trước.`));
+        return null;
+    }
+    return repoPath;
+}
+
+function branchName(functionId, taskId) {
+    return `feature/${functionId}/${taskId}`;
+}
+
+function currentBranch(repoPath) {
+    return sh('git rev-parse --abbrev-ref HEAD', repoPath);
+}
+
+function hasUncommittedChanges(repoPath) {
+    return sh('git status --porcelain', repoPath).length > 0;
+}
+
+function localBranchExists(repoPath, name) {
+    try {
+        shQuiet(`git rev-parse --verify refs/heads/${name}`, repoPath);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+function remoteBranchExists(repoPath, name) {
+    try {
+        return shQuiet(`git ls-remote --heads origin ${name}`, repoPath).length > 0;
+    } catch {
+        return false;
+    }
+}
+
+// Prints the plan and gates on explicit approval — either an interactive "y"
+// (developer running the command directly) or a pre-confirmed --yes flag
+// (AI, only after the developer approved the same plan in chat).
+async function ensureApproval(planLines, opts) {
+    console.log(chalk.yellow('\n📋 Kế hoạch thực hiện:'));
+    planLines.forEach((l) => console.log(chalk.gray(`  • ${l}`)));
+
+    if (opts.yes) return true;
+
+    if (!process.stdin.isTTY) {
+        console.log(chalk.red('\n✗ Cần xác nhận trước khi thực hiện.'));
+        console.log(chalk.gray('  AI: hỏi user đồng ý trong chat trước, rồi chạy lại lệnh này kèm --yes.'));
+        console.log(chalk.gray('  Người dùng: chạy lại lệnh này trong terminal để được hỏi xác nhận trực tiếp.'));
+        return false;
+    }
+
+    return confirm({ message: '\nTiếp tục thực hiện các bước trên?', default: false });
+}
+
+async function createBranch(options) {
+    const repoName = options.repo || 'AK-Docs';
+    const repoPath = resolveRepo(repoName);
+    if (!repoPath) { process.exitCode = 1; return null; }
+
+    if (!options.functionId || !options.taskId) {
+        console.log(chalk.red('✗ Cần cả --function-id và --task-id (hoặc tham số vị trí <functionId> <taskId>).'));
+        process.exitCode = 1;
+        return null;
+    }
+
+    const base = options.base || 'main';
+    const branch = branchName(options.functionId, options.taskId);
+
+    if (localBranchExists(repoPath, branch)) {
+        console.log(chalk.green(`✓ Branch ${branch} đã tồn tại trong ${repoName} — checkout.`));
+        execSync(`git checkout ${branch}`, { cwd: repoPath, stdio: 'inherit' });
+        return { repoPath, repoName, branch, created: false };
+    }
+
+    if (hasUncommittedChanges(repoPath)) {
+        console.log(chalk.red(`✗ ${repoName} đang có thay đổi chưa commit — xử lý (commit/stash) trước khi tạo branch mới.`));
+        process.exitCode = 1;
+        return null;
+    }
+
+    const ok = await ensureApproval([
+        `Repo: ${repoName}`,
+        `git checkout ${base} && git pull origin ${base} --ff-only`,
+        `git checkout -b ${branch}`,
+        `git push -u origin ${branch}`,
+    ], options);
+    if (!ok) { process.exitCode = 1; return null; }
+
+    try {
+        console.log(chalk.cyan(`\n⟳ Cập nhật ${base} mới nhất...`));
+        execSync(`git checkout ${base}`, { cwd: repoPath, stdio: 'inherit' });
+        execSync(`git pull origin ${base} --ff-only`, { cwd: repoPath, stdio: 'inherit' });
+
+        console.log(chalk.cyan(`⟳ Tạo branch ${branch}...`));
+        execSync(`git checkout -b ${branch}`, { cwd: repoPath, stdio: 'inherit' });
+        execSync(`git push -u origin ${branch}`, { cwd: repoPath, stdio: 'inherit' });
+
+        console.log(chalk.green(`\n✓ Đã tạo và đẩy branch ${branch} từ ${base} (repo ${repoName}).`));
+        return { repoPath, repoName, branch, created: true };
+    } catch (err) {
+        console.log(chalk.red(`\n✗ Lỗi khi tạo branch: ${err.message}`));
+        process.exitCode = 1;
+        return null;
+    }
+}
+
+function detectProvider(repoPath) {
+    let remoteUrl = '';
+    try { remoteUrl = sh('git remote get-url origin', repoPath); } catch { /* no remote */ }
+    if (/gitlab/i.test(remoteUrl)) return { provider: 'gitlab', remoteUrl };
+    if (/github/i.test(remoteUrl)) return { provider: 'github', remoteUrl };
+    return { provider: 'unknown', remoteUrl };
+}
+
+function hasCli(bin) {
+    try {
+        execSync(`${bin} --version`, { stdio: 'ignore' });
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+function webUrlFromRemote(remoteUrl) {
+    const sshMatch = remoteUrl.match(/^git@([^:]+):(.+?)(\.git)?$/);
+    if (sshMatch) return `https://${sshMatch[1]}/${sshMatch[2]}`;
+    return remoteUrl.replace(/\.git$/, '');
+}
+
+function openMergeRequest(repoPath, { branch, base, title, description }) {
+    const { provider, remoteUrl } = detectProvider(repoPath);
+
+    if (provider === 'gitlab' && hasCli('glab')) {
+        execSync(
+            `glab mr create --source-branch "${branch}" --target-branch "${base}" ` +
+            `--title ${JSON.stringify(title)} --description ${JSON.stringify(description || '')} --yes`,
+            { cwd: repoPath, stdio: 'inherit' }
+        );
+        return;
+    }
+    if (provider === 'github' && hasCli('gh')) {
+        execSync(
+            `gh pr create --base "${base}" --head "${branch}" ` +
+            `--title ${JSON.stringify(title)} --body ${JSON.stringify(description || '')}`,
+            { cwd: repoPath, stdio: 'inherit' }
+        );
+        return;
+    }
+
+    if (!remoteUrl) {
+        console.log(chalk.yellow('\n⚠ Không tìm thấy remote "origin" — hãy tự tạo Merge Request thủ công.'));
+        return;
+    }
+
+    const webBase = webUrlFromRemote(remoteUrl);
+    let url;
+    if (provider === 'gitlab') {
+        url = `${webBase}/-/merge_requests/new?merge_request%5Bsource_branch%5D=${encodeURIComponent(branch)}` +
+              `&merge_request%5Btarget_branch%5D=${encodeURIComponent(base)}` +
+              `&merge_request%5Btitle%5D=${encodeURIComponent(title)}`;
+    } else if (provider === 'github') {
+        url = `${webBase}/compare/${encodeURIComponent(base)}...${encodeURIComponent(branch)}?expand=1&title=${encodeURIComponent(title)}`;
+    } else {
+        url = webBase;
+    }
+    console.log(chalk.yellow(`\n⚠ Không tìm thấy 'glab'/'gh' CLI — mở link sau để tạo Merge Request thủ công:`));
+    console.log(chalk.cyan(`  ${url}\n`));
+}
+
+async function submitDocs(options) {
+    const repoName = options.repo || 'AK-Docs';
+    const repoPath = resolveRepo(repoName);
+    if (!repoPath) { process.exitCode = 1; return null; }
+
+    if (!options.title) {
+        console.log(chalk.red('✗ Cần --title (tiêu đề commit / Merge Request).'));
+        process.exitCode = 1;
+        return null;
+    }
+
+    const base = options.base || 'main';
+    const branch = currentBranch(repoPath);
+    if (branch === base) {
+        console.log(chalk.red(`✗ Đang ở nhánh ${base} — tạo branch feature trước bằng "ak docs branch <functionId> <taskId>".`));
+        process.exitCode = 1;
+        return null;
+    }
+
+    const dirty = hasUncommittedChanges(repoPath);
+    if (!dirty && !remoteBranchExists(repoPath, branch)) {
+        console.log(chalk.yellow(`Không có thay đổi để submit và branch ${branch} chưa từng được push.`));
+        process.exitCode = 1;
+        return null;
+    }
+    if (!dirty) {
+        console.log(chalk.yellow('Không có thay đổi mới để commit — sẽ chỉ đảm bảo branch đã push và mở Merge Request.'));
+    }
+
+    const planLines = [`Repo: ${repoName}, branch: ${branch} → ${base}`];
+    if (dirty) planLines.push('git add -A', `git commit -m ${JSON.stringify(options.title)}`);
+    planLines.push(`git push -u origin ${branch}`, `Mở Merge Request: "${options.title}" (${branch} → ${base})`);
+
+    const ok = await ensureApproval(planLines, options);
+    if (!ok) { process.exitCode = 1; return null; }
+
+    try {
+        if (dirty) {
+            execSync('git add -A', { cwd: repoPath, stdio: 'inherit' });
+            execSync(`git commit -m ${JSON.stringify(options.title)}`, { cwd: repoPath, stdio: 'inherit' });
+        }
+        execSync(`git push -u origin ${branch}`, { cwd: repoPath, stdio: 'inherit' });
+
+        console.log(chalk.cyan('\n⟳ Mở Merge Request...'));
+        openMergeRequest(repoPath, { branch, base, title: options.title, description: options.description || '' });
+
+        console.log(chalk.green(`\n✓ Đã submit ${branch} → ${base} (repo ${repoName}). Chờ PM review.`));
+        return { repoPath, repoName, branch };
+    } catch (err) {
+        console.log(chalk.red(`\n✗ Lỗi khi submit: ${err.message}`));
+        process.exitCode = 1;
+        return null;
+    }
+}
+
+module.exports = { createBranch, submitDocs, branchName, currentBranch, hasUncommittedChanges };

package/scripts/hooks/figma-rate-limit.js

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+/**
+ * PreToolUse hook: throttle mcp__figma__* calls to stay under Figma's Tier-1 REST
+ * budget (10/min on a Starter-plan Full seat). Sleeps instead of blocking, so the
+ * tool call always proceeds — just never faster than the budget allows.
+ *
+ * Budget is counted in "units" ≈ underlying Figma REST calls
+ * (verified against figma-developer-mcp v0.13.2):
+ *   get_figma_data        → 1 unit  (one /v1/files/:key[/nodes] call)
+ *   download_figma_images → 3 units (fills map + PNG render + SVG render, worst case)
+ * Override with FIGMA_RATE_LIMIT_UNITS (default 6/60s — safety margin under 10/min).
+ */
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const WINDOW = 60; // seconds
+const MAX_UNITS = parseInt(process.env.FIGMA_RATE_LIMIT_UNITS || '6', 10) || 6;
+const STATE = path.join(
+    os.tmpdir(),
+    `figma-mcp-rate-limit-${typeof process.getuid === 'function' ? process.getuid() : 'user'}.log`
+);
+
+function readStdin() {
+    return new Promise((resolve) => {
+        let data = '';
+        process.stdin.setEncoding('utf8');
+        process.stdin.on('data', (c) => (data += c));
+        process.stdin.on('end', () => resolve(data));
+        process.stdin.on('error', () => resolve(data));
+    });
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+function readStamps() {
+    try {
+        return fs
+            .readFileSync(STATE, 'utf8')
+            .split('\n')
+            .map((l) => parseInt(l, 10))
+            .filter((n) => Number.isFinite(n))
+            .sort((a, b) => a - b);
+    } catch {
+        return [];
+    }
+}
+
+(async () => {
+    let tool = '';
+    try {
+        tool = JSON.parse(await readStdin()).tool_name || '';
+    } catch {
+        /* no/invalid stdin — treat as 1 unit */
+    }
+    const units = tool.includes('download_figma_images') ? 3 : 1;
+
+    let slept = 0;
+    for (;;) {
+        const now = Math.floor(Date.now() / 1000);
+        const recent = readStamps().filter((t) => t > now - WINDOW);
+        // recent.length === 0 escape hatch: a single oversized call must never deadlock
+        if (recent.length + units <= MAX_UNITS || recent.length === 0) {
+            for (let i = 0; i < units; i++) recent.push(now);
+            fs.writeFileSync(STATE, recent.join('\n') + '\n');
+            break;
+        }
+        const wait = Math.max(1, recent[0] + WINDOW - now + 1);
+        await sleep(wait * 1000);
+        slept += wait;
+    }
+
+    if (slept > 0) {
+        console.log(
+            JSON.stringify({
+                systemMessage: `Figma rate-limit guard: delayed ${slept}s to stay under ${MAX_UNITS} calls/min`,
+            })
+        );
+    }
+    process.exit(0);
+})();

package/scripts/hooks/session-start.js

@@ -210,16 +210,27 @@ function buildContextPrompt(ctx, taskState) {
         }
         lines.push(`- Gate ${currentGate}: 🔄 IN PROGRESS`);
         lines.push('');
-        lines.push(`**DO NOT restart from Gate 1.** Resume directly at Gate ${currentGate} (${gateLabel(currentGate)}).`);
+        const isGenDoc = ctx.taskType === 'gen-doc';
+        lines.push(`**DO NOT restart from Gate 1.** Resume directly at Gate ${currentGate} (${gateLabel(currentGate, ctx.taskType)}).`);
         lines.push('');
 
-        if (currentGate === 2) {
+        if (isGenDoc && currentGate >= 3) {
+            lines.push(`This is a **gen-doc** task (2-gate flow). The document workflow is complete.`);
+            lines.push(`Expected output: \`plan/${ctx.taskId}/output.md\` (or path in requirement.md).`);
+            lines.push('DO NOT start Gate 3, DO NOT create plan.md, DO NOT run TDD.');
+        } else if (currentGate === 2) {
             lines.push('Gate 1 is already APPROVED. The requirement document is at:');
             lines.push(`  AK-Docs/04.Coding/01.Requirements/[functionId]/${ctx.taskId}.md`);
             lines.push(`  ([functionId] — look it up in AK-Docs/04.Coding/00.Overview/_Index.md or the folder containing ${ctx.taskId}.md)`);
             lines.push('');
-            lines.push('Proceed to Gate 2: create the implementation plan.');
-            lines.push(buildModeInstruction(mode, 2));
+            if (isGenDoc) {
+                lines.push('This is a **gen-doc** task. DO NOT create plan.md or run TDD.');
+                lines.push('Proceed to Gate 2: read the approved requirement.md and generate the output document immediately.');
+                lines.push('After generating, self-review + create task-summary.md, then run `ak gate 2 approved`.');
+            } else {
+                lines.push('Proceed to Gate 2: create the implementation plan.');
+            }
+            lines.push(buildModeInstruction(mode, 2, ctx.taskType));
         } else if (currentGate === 3) {
             lines.push('Gates 1 and 2 are already APPROVED. Plans are at:');
             lines.push(`  AK-Docs/04.Coding/01.Requirements/[functionId]/${ctx.taskId}.md`);
@@ -265,6 +276,14 @@ function buildContextPrompt(ctx, taskState) {
         }
 
         lines.push('');
+        if (ctx.taskType === 'gen-doc') {
+            lines.push('**This is a gen-doc task (2-gate flow):**');
+            lines.push('- Gate 1: Create requirement.md → wait for APPROVED');
+            lines.push('- Gate 2 (after APPROVED): Generate output document immediately + self-review + task-summary.md');
+            lines.push('- NO plan.md, NO TDD, NO Gate 3/4/5');
+            lines.push('');
+        }
+
         lines.push('DO NOT wait for the developer to ask. START NOW.');
         lines.push('If you have not started automatically, begin as soon as the developer types **"start"**.');
         lines.push('(If a later ticket switch does not seem to trigger this — e.g. `ak use` was run in another terminal while this chat was already open — the developer can run **`/coding`** to load it manually.)');
@@ -274,7 +293,11 @@ function buildContextPrompt(ctx, taskState) {
     return lines.join('\n');
 }
 
-function gateLabel(n) {
+function gateLabel(n, taskType = '') {
+    if (taskType === 'gen-doc') {
+        if (n === 2) return 'Generate Document';
+        if (n >= 3) return 'Done';
+    }
     const labels = {
         1: 'AI Analyze Requirement',
         2: 'Implementation Plan',
@@ -285,9 +308,21 @@ function gateLabel(n) {
     return labels[n] || `Gate ${n}`;
 }
 
-function buildModeInstruction(mode, gate) {
+function buildModeInstruction(mode, gate, taskType = '') {
     if (mode !== 'fast') return '';
 
+    if (gate === 2 && taskType === 'gen-doc') {
+        return [
+            '',
+            '**MODE: fast — Gate 2 (gen-doc):**',
+            '- Re-read `AK-Docs/04.Coding/01.Requirements/[functionId]/[ticketId].md` → generate output document immediately',
+            '- Save to `AK-Docs/04.Coding/02.Plans/[functionId]/[ticketId].md` (or the custom path/format noted in the requirement doc)',
+            '- Self-review + create `AK-Docs/04.Coding/02.Plans/[functionId]/[ticketId]-summary.md`',
+            '- Submit AK-Docs via MR (show title/description, wait for explicit confirmation, then `ak docs submit --title "..." --description "..." --yes`)',
+            '- Run `ak gate 2 approved` immediately — NO extra approval prompt for this step',
+        ].join('\n');
+    }
+
     const instructions = {
         2: [
             '**MODE: fast** — Gate 2 fast track:',

package/scripts/init.js

@@ -214,10 +214,20 @@ async function setupSuperpowersHook(_projectDir, claudeDir) {
     const hookBlockGitDest = path.join(hooksDir, 'block-git-write.js');
     await fs.copy(hookBlockGitSrc, hookBlockGitDest, { overwrite: true });
 
+    const hookFigmaRateSrc  = path.join(PKG_DIR, 'scripts', 'hooks', 'figma-rate-limit.js');
+    const hookFigmaRateDest = path.join(hooksDir, 'figma-rate-limit.js');
+    await fs.copy(hookFigmaRateSrc, hookFigmaRateDest, { overwrite: true });
+
+    // Hooks are CommonJS (.js + require). In an ESM project ("type": "module" in the
+    // project's package.json) Node would treat them as ES modules and crash on require().
+    // A nested package.json pins the interpretation for the kit-owned dirs only.
+    await fs.writeJson(path.join(hooksDir, 'package.json'), { type: 'commonjs' }, { spaces: 2 });
+
     // Copy telemetry module so hooks can require('../telemetry/record')
     const telemetrySrc  = path.join(PKG_DIR, 'scripts', 'telemetry');
     const telemetryDest = path.join(claudeDir, 'telemetry');
     await fs.copy(telemetrySrc, telemetryDest, { overwrite: true });
+    await fs.writeJson(path.join(telemetryDest, 'package.json'), { type: 'commonjs' }, { spaces: 2 });
 
     const settingsFile = path.join(claudeDir, 'settings.json');
     let settings = {};
@@ -273,8 +283,26 @@ async function setupSuperpowersHook(_projectDir, claudeDir) {
         ]
     });
 
+    // Throttle Figma MCP calls to stay under Figma's Tier-1 REST budget (anti-429).
+    // Sleeps when the 60s window is full — may hold a call up to ~60s, hence timeout 120.
+    settings.hooks.PreToolUse = settings.hooks.PreToolUse.filter(
+        h => !(h._aiflowKitFigmaRateLimit)
+    );
+    settings.hooks.PreToolUse.push({
+        _aiflowKitFigmaRateLimit: true,
+        matcher: 'mcp__figma__.*',
+        hooks: [
+            {
+                type: 'command',
+                command: `node "${hookFigmaRateDest.replace(/\\/g, '/')}"`,
+                timeout: 120,
+                statusMessage: 'Figma rate-limit guard: checking call budget…',
+            }
+        ]
+    });
+
     await fs.writeJson(settingsFile, settings, { spaces: 2 });
-    console.log(chalk.green(`✓ Superpowers hooks (SessionStart, SessionEnd, PreToolUse:block-git-write) configured`));
+    console.log(chalk.green(`✓ Superpowers hooks (SessionStart, SessionEnd, PreToolUse:block-git-write, PreToolUse:figma-rate-limit) configured`));
 }
 
 async function verifySuperpowersSkills(versionDir) {

package/scripts/prompt.js

@@ -281,6 +281,51 @@ Write documentation based on approved outline.
 **INVOKE:** \`superpowers:verification-before-completion\`
 Verify docs match code. No outdated examples.
 Display: "GATE 3: Documentation complete. Type APPROVED."
+`,
+    },
+    'gen-doc': {
+        header: 'Generate Document',
+        instruction: 'Generate a document from source code / feature analysis as described below.',
+        skillWorkflow: `
+## STRICT GATE WORKFLOW — Generate Document (2-Gate)
+
+> ⚡ gen-doc uses a **2-gate flow**: Gate 1 (Requirement) → APPROVED → Gate 2 (Generate + Auto Review).
+> Gate 2 runs immediately after APPROVED — no plan.md, no TDD, no extra coding gates.
+
+> gen-doc reuses the same \`AK-Docs/04.Coding/\` folders as the standard Dev workflow (see \`custom/rules/project-conventions.md\`) — only Gate 1–2, no separate section.
+
+### GATE 1 — AI Analyze & Plan Document
+**INVOKE:** \`read-study-requirement\` skill
+1. Load ticket context + read source code / files to understand scope
+2. Confirm \`functionId\` (BẮT BUỘC — see "functionId & ticketId" in \`project-conventions.md\`; if it can't be derived for an ad-hoc task, ask directly) and ensure AK-Docs is on branch \`feature/[functionId]/[ticketId]\` (create via \`ak docs branch [functionId] [ticketId] --yes\` only after explicit user confirmation)
+3. Understand the document goal, target audience, and output format
+4. If unclear → ask ONE question at a time, wait for reply
+5. Output \`AK-Docs/04.Coding/01.Requirements/[functionId]/[ticketId].md\` with:
+   - Document scope and target audience
+   - Content outline (sections to cover)
+   - Source references (files, features, flows to analyze)
+   - Output format: Markdown or Excel (note template path if applicable)
+   - Effort estimate
+6. Display "GATE 1: Document plan ready" → wait for **APPROVED**
+
+> **Telemetry:** Run \`ak gate 1 start --ticket [ticket-id]\` when starting.
+> Run \`ak gate 1 approved --ticket [ticket-id]\` immediately when APPROVED is received.
+
+### GATE 2 — Generate Document + Auto Review (runs immediately after APPROVED)
+
+**DO NOT create plan.md. DO NOT run TDD. Proceed directly to document generation.**
+
+1. Re-read \`AK-Docs/04.Coding/01.Requirements/[functionId]/[ticketId].md\` (the approved outline)
+2. Read source code, trace data flows, analyze features as needed
+3. Generate the output document:
+   - **Markdown:** Save to \`AK-Docs/04.Coding/02.Plans/[functionId]/[ticketId].md\` (or the custom path/format noted in the requirement doc — still write a short pointer + summary into this file)
+4. Self-review: verify content completeness against the approved requirement outline
+5. Create \`AK-Docs/04.Coding/02.Plans/[functionId]/[ticketId]-summary.md\` with a brief summary of what was generated
+6. Submit AK-Docs via Merge Request: show the commit/MR title+description, wait for explicit user confirmation, then run \`ak docs submit --title "..." --description "..." --yes\` — PM reviews & merges into \`main\` (never merge it yourself)
+7. Run: \`ak gate 2 approved --ticket [ticket-id]\` to close the task
+8. Display: \`GATE 2 DONE: Document generated at [path]\`
+
+**Do NOT wait for extra approval before generating the document — only the branch/MR confirmations above gate on the user; run the gate 2 approved command immediately after.**
 `,
     },
 };

package/scripts/task.js

@@ -331,17 +331,22 @@ async function nextGate(taskId) {
     const nextGateNum = currentGate + 1;
 
     // Save context snapshot if current task is active
+    let taskType = null;
     if (await fs.pathExists(CURRENT_FILE)) {
         const ctx = await fs.readJson(CURRENT_FILE).catch(() => null);
         if (ctx && ctx.taskId === resolvedId) {
+            taskType = ctx.taskType || null;
             await fs.writeJson(path.join(taskDir, 'context.json'), ctx, { spaces: 2 });
         }
     }
 
+    const isGenDoc = taskType === 'gen-doc';
+    const maxGate = isGenDoc ? 2 : 5;
+
     const taskState = {
         ...existing,
         taskId:        resolvedId,
-        status:        'pending',
+        status:        nextGateNum > maxGate ? 'done' : 'pending',
         updatedAt:     now,
         pausedAt:      now,
         currentGate:   nextGateNum,
@@ -354,20 +359,26 @@ async function nextGate(taskId) {
 
     // Generate cumulative task-summary.md (task-internal state — lives in .aiflow/, not gate docs)
     const summaryPath = path.join(TASKS_DIR, resolvedId, 'task-summary.md');
-    const summaryContent = await generateMarkdownSummary(taskState);
+    const summaryContent = await generateMarkdownSummary(taskState, taskType);
     await fs.writeFile(summaryPath, summaryContent, 'utf-8');
 
-    const taskType = existing.taskType || 'feature';
     console.log(chalk.green(`✓ Gate ${currentGate} approved for ${resolvedId}.`));
     console.log(chalk.gray(`  Summary saved to: .aiflow/tasks/${resolvedId}/task-summary.md`));
-    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).`));
-    console.log(chalk.gray(`    3. Type "start" or "continue from the current plan".`));
-    console.log(chalk.yellow(`       (Note: Gate 3 progress is saved via [x] checkboxes in the Gate 2 plan doc (AK-Docs/04.Coding/02.Plans/).`));
-    console.log(chalk.yellow(`        The AI will automatically resume the exact task you left off.)`));
+
+    if (isGenDoc && currentGate >= maxGate) {
+        console.log(chalk.green('\n  ✅ Document workflow complete. Task is done.'));
+    } else {
+        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).`));
+        console.log(chalk.gray(`    3. Type "start" or "continue from the current plan".`));
+        if (!isGenDoc) {
+            console.log(chalk.yellow(`       (Note: Gate 3 progress is saved via [x] checkboxes in the Gate 2 plan doc (AK-Docs/04.Coding/02.Plans/).`));
+            console.log(chalk.yellow(`        The AI will automatically resume the exact task you left off.)`));
+        }
+    }
     console.log();
 }
 
@@ -466,9 +477,9 @@ async function detectCurrentGate(taskId) {
     return 1;
 }
 
-async function generateMarkdownSummary(taskState) {
-    const taskType = taskState.taskType || 'feature';
-    const maxGate  = taskType === 'testing' ? 4 : 5;
+async function generateMarkdownSummary(taskState, taskType = null) {
+    taskType = taskType || taskState.taskType || 'feature';
+    const maxGate = taskType === 'testing' ? 4 : (taskType === 'gen-doc' ? 2 : 5);
     const lines = [];
     lines.push(`# Task Summary: ${taskState.taskId}`);
     lines.push(`**Title:** ${taskState.title}`);
@@ -492,7 +503,7 @@ async function generateMarkdownSummary(taskState) {
     return lines.join('\n');
 }
 
-function gateLabel(n, taskType) {
+function gateLabel(n, taskType = null) {
     if (taskType === 'testing') {
         const labels = {
             1: 'Phân tích & Confirm',
@@ -502,6 +513,10 @@ function gateLabel(n, taskType) {
         };
         return labels[n] || `Gate ${n}`;
     }
+    if (taskType === 'gen-doc') {
+        if (n === 2) return 'Generate Document';
+        if (n >= 3) return 'Done';
+    }
     const labels = {
         1: 'AI Analyze Requirement',
         2: 'Implementation Plan',

package/scripts/use.js

@@ -234,7 +234,7 @@ async function loadFromBacklog(issueKey, options = {}) {
       options.cto != null ||
       options.commentsTo != null ||
       options["comments-to"] != null;
-    
+
     if (loadComments) {
       console.log(chalk.gray("  ℹ Comments requested..."));
     }
@@ -349,13 +349,13 @@ async function fetchBacklogComments(domain, apiKey, issueKey) {
       if (minId) {
         url += `&minId=${minId}`;
       }
-      
+
       const batch = await backlogGet(url);
       if (!batch || batch.length === 0) break;
-      
+
       all.push(...batch);
       if (batch.length < 100) break;
-      
+
       // Use the last ID as minId for the next batch
       minId = batch[batch.length - 1].id;
     }
@@ -467,7 +467,7 @@ async function loadFromJira(issueKey, options = {}) {
       options.cto != null ||
       options.commentsTo != null ||
       options["comments-to"] != null;
-    
+
     if (loadComments) {
       console.log(chalk.gray("  ℹ Comments requested..."));
     }
@@ -709,6 +709,7 @@ async function manualContext(prefillId = "") {
       { name: td("🔍 Investigation",    "Analysis", "Investigate, analyze root cause"),                   value: "investigation" },
       { name: td("📊 Impact Analysis",  "Analysis", "Assess scope and risk of changes"),                  value: "impact-analysis" },
       { name: td("📖 Documentation",    "Document", "Write docs, README, API reference"),                 value: "documentation" },
+      { name: td("📝 Generate Doc 2 Gate", "Document", "Generate new documentation"),                      value: "gen-doc" },
     ],
     default: existing.taskType || undefined,
   });