@relipa/ai-flow-kit 0.1.5-beta.1 → 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/docs-repo.js

@@ -0,0 +1,49 @@
+const fs = require('fs-extra');
+const path = require('path');
+const chalk = require('chalk');
+const { execSync } = require('child_process');
+
+// AK-Docs (per-project docs) and Shared-Docs (cross-project templates) are
+// fixed-name folders living directly under the workspace root — the folder
+// opened in the editor, which contains one or more source repos plus these
+// two docs repos as siblings. `ak` is run from that root, so projectDir
+// (process.cwd()) already IS the root — see docs/internal/Project-Structure.md.
+const DOC_REPOS = [
+    { name: 'AK-Docs', purpose: 'tài liệu dự án (Requirements, Specs, Test Cases, Coding docs...)' },
+    { name: 'Shared-Docs', purpose: 'template dùng chung cho tất cả dự án (Spec, QA, Test Case, Test Report...)' },
+];
+
+function resolveDocsRepoPath(projectDir, repoName) {
+    return path.join(projectDir, repoName);
+}
+
+async function syncDocsRepo(projectDir, repoName, purpose) {
+    const repoPath = resolveDocsRepoPath(projectDir, repoName);
+
+    if (!(await fs.pathExists(repoPath))) {
+        console.log(chalk.yellow(`⚠ ${repoName}/ chưa tồn tại tại ${repoPath} (${purpose}). Hãy clone repo này vào thư mục root.`));
+        return;
+    }
+
+    if (!(await fs.pathExists(path.join(repoPath, '.git')))) {
+        console.log(chalk.yellow(`⚠ ${repoName}/ tồn tại tại ${repoPath} nhưng không phải git repo — bỏ qua pull.`));
+        return;
+    }
+
+    console.log(chalk.cyan(`\n⟳ Pulling latest ${repoName}...`));
+    try {
+        execSync('git pull', { cwd: repoPath, stdio: 'inherit' });
+        console.log(chalk.green(`✓ ${repoName} đã cập nhật mới nhất.`));
+    } catch (err) {
+        console.log(chalk.red(`✗ Không thể pull ${repoName}: ${err.message}`));
+    }
+}
+
+async function syncDocsRepos(projectDir) {
+    console.log(chalk.blue('\nĐồng bộ AK-Docs / Shared-Docs...'));
+    for (const repo of DOC_REPOS) {
+        await syncDocsRepo(projectDir, repo.name, repo.purpose);
+    }
+}
+
+module.exports = { syncDocsRepos, resolveDocsRepoPath, DOC_REPOS };

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,21 +210,32 @@ 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(`  04.Coding/01.Requirements/[functionId]/${ctx.taskId}.md`);
-            lines.push(`  ([functionId] — look it up in 04.Coding/00.Overview/_Index.md or the folder containing ${ctx.taskId}.md)`);
+            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(`  04.Coding/01.Requirements/[functionId]/${ctx.taskId}.md`);
-            lines.push(`  04.Coding/02.Plans/[functionId]/${ctx.taskId}.md`);
-            lines.push(`  ([functionId] — look it up in 04.Coding/00.Overview/_Index.md)`);
+            lines.push(`  AK-Docs/04.Coding/01.Requirements/[functionId]/${ctx.taskId}.md`);
+            lines.push(`  AK-Docs/04.Coding/02.Plans/[functionId]/${ctx.taskId}.md`);
+            lines.push(`  ([functionId] — look it up in AK-Docs/04.Coding/00.Overview/_Index.md)`);
             lines.push('');
             lines.push('Proceed to Gate 3: implement code following the plan (TDD).');
             lines.push(buildModeInstruction(mode, 3));
@@ -251,20 +262,28 @@ function buildContextPrompt(ctx, taskState) {
             lines.push('- Pre-flight: determine functionId first (from context / input UC Spec file / ask DEV to confirm) — see the DEV workflow Pre-flight step');
             lines.push('- Read ticket + identify changed files only (no deep source scan)');
             lines.push('- Skip Q&A unless there is a critical blocking ambiguity');
-            lines.push('- Output a lite requirement doc (Sections 1, 3, 5 only) to 04.Coding/01.Requirements/[functionId]/' + ctx.taskId + '.md');
+            lines.push('- Output a lite requirement doc (Sections 1, 3, 5 only) to AK-Docs/04.Coding/01.Requirements/[functionId]/' + ctx.taskId + '.md');
             lines.push('- Target: Gate 1 complete in < 5 minutes');
         } else {
             lines.push('Gate 1 process:');
-            lines.push('0. Pre-flight: determine functionId (from context / input UC Spec file / ask DEV to confirm) + ensure 04.Coding/ tree exists — see the DEV workflow Pre-flight step. DO NOT continue without functionId.');
+            lines.push('0. Pre-flight: determine functionId (from context / input UC Spec file / ask DEV to confirm) + ensure AK-Docs/04.Coding/ tree exists — see the DEV workflow Pre-flight step. DO NOT continue without functionId.');
             lines.push('1. Read the ticket context above');
             lines.push('2. Read CLAUDE.md — understand project architecture and conventions');
             lines.push('3. Read source code — identify related files, data flow, patterns');
             lines.push('4. If anything is unclear — ask ONE question at a time');
-            lines.push('5. Output 04.Coding/01.Requirements/[functionId]/' + ctx.taskId + '.md');
+            lines.push('5. Output AK-Docs/04.Coding/01.Requirements/[functionId]/' + ctx.taskId + '.md');
             lines.push('6. Display GATE 1 prompt and wait for APPROVED');
         }
 
         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

@@ -3,6 +3,7 @@ const path = require('path');
 const os = require('os');
 const chalk = require('chalk');
 const { input, checkbox, confirm } = require('@inquirer/prompts');
+const { syncDocsRepos } = require('./docs-repo');
 
 const PKG_DIR = path.join(__dirname, '..');
 const GLOBAL_AIFLOW_DIR = path.join(os.homedir(), '.aiflow');
@@ -213,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 = {};
@@ -272,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) {
@@ -752,7 +781,6 @@ async function ensureAiflowGitignored(projectDir) {
     const gitignorePath = path.join(projectDir, '.gitignore');
     const entries = [
         '.aiflow/',
-        'plan/',
         '.claude/',
         '.rules/',
         '.mcp.json',
@@ -1048,6 +1076,9 @@ async function init(options) {
     try {
         console.log(chalk.blue(`Initializing ai-flow-kit (v${PKG_VERSION})...`));
 
+        // ── Sync AK-Docs / Shared-Docs sibling repos ──────────────────
+        await syncDocsRepos(projectDir);
+
         // ── Auto-detect or prompt for framework if not supplied ──────
         if (frameworks.length === 0) {
             const stateFilePath = path.join(aiflowDir, 'state.json');