@relipa/ai-flow-kit 0.0.9-beta.1 → 0.0.9

package/README.md

@@ -128,6 +128,16 @@ aiflow init --framework spring-boot,reactjs --adapter backlog,jira
 
 **Supported Adapters:** `backlog`, `jira`, `google-sheets`, `figma`, `figma-desktop`
 
+**Figma adapters:**
+
+| Adapter | Command | Auth | Requirement |
+|---------|---------|------|-------------|
+| `figma` | `ak init -a figma` | Personal Access Token (`figd_...`) | None — REST API |
+| `figma-desktop` | `ak init -a figma-desktop` | Desktop session (no token needed) | Figma Desktop app installed & open |
+
+> The `figma-desktop` adapter uses the official `@figma/mcp-server` package from Figma Inc. and is the recommended option if you already use Figma Desktop.
+> See [Figma workflow guide](docs/common/workflows/figma.md) for usage with the `figma-to-component` skill.
+
 ---
 
 ### `aiflow sync-skills`

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

@@ -29,8 +29,8 @@ AI actively reads ticket + source code to understand the requirement:
 
 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 `ak gate 1 approved --ticket [ticket-id]` immediately when APPROVED is received.
+> **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.
 
 ---
 
@@ -43,8 +43,8 @@ DO NOT just check format — **understand the content and propose solutions**.
 - Display: "GATE 2 PAUSED: type APPROVED to start coding".
 - CODE WILL NOT BE GENERATED until "APPROVED" is received.
 
-> **Telemetry:** Run `ak gate 2 start --ticket [ticket-id]` when starting this gate.
-> Run `ak gate 2 approved --ticket [ticket-id]` immediately when APPROVED is received.
+> **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.
 
 ---
 
@@ -57,7 +57,7 @@ Only runs after Gate 2 has been APPROVED.
 - Write tests FIRST — run to confirm FAIL -> implement -> PASS.
 - Bug fix EXTRA: `superpowers:systematic-debugging` + `investigate-bug` skill first.
 
-> **Telemetry:** Run `ak gate 3 start --ticket [ticket-id]` when starting this gate.
+> **Telemetry:** Run `ak gate 3 start --ticket [ticket-id]` when starting this gate. Run as-is — do NOT append shell redirects.
 
 ---
 
@@ -75,8 +75,8 @@ Then: "GATE 4 PAUSED: type APPROVED or BUG: [description]"
 - Coding bug -> fix -> repeat Gate 4.
 - Requirement bug -> return to Gate 1.
 
-> **Telemetry:** Run `ak gate 4 start --ticket [ticket-id]` when starting this gate.
-> Run `ak gate 4 approved --ticket [ticket-id]` immediately when APPROVED is received.
+> **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.
 
 ---
 
@@ -87,4 +87,4 @@ Only runs after Gate 4 has been APPROVED.
 **INVOKE:** `superpowers:requesting-code-review`
 Guide on creating a Pull Request with the ticket link.
 
-> **Telemetry:** Run `ak gate 5 start --ticket [ticket-id]` when starting this gate.
+> **Telemetry:** Run `ak gate 5 start --ticket [ticket-id]` when starting this gate. Run as-is — do NOT append shell redirects.

package/docs/common/CHANGELOG.md

@@ -7,7 +7,7 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
-## [0.0.9] - 2026-05-21
+## [0.0.9] - 2026-05-25
 
 ### Added
 
@@ -17,11 +17,24 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 - **4-tier framework detection in `figma-to-component` skill** — Detection order: (1) `CLAUDE.md` identifier → (2) project file scan (`app/` dir, `angular.json`, `nuxt.config.*`) → (3) fallback to Next.js/React. Previously only supported React and Vue.
 - **Figma workflow guide** — New developer guide at [`docs/common/workflows/figma.md`](figma.md) covering prerequisites (REST API vs Desktop), how to get node URLs, trigger commands, expected output format, review checklist, and troubleshooting table.
 - **MCP presets documentation** — Added full Figma REST API and Figma Desktop sections to [`custom/mcp-presets/README.md`](../../custom/mcp-presets/README.md), including a side-by-side comparison table.
+- **`ak gate N start|approved` auto-syncs task state** — Calling `ak gate 1 start --ticket PROJ-33` now automatically advances `currentGate` in `task-state.json`, removing the need to always call `ak task next` for gate tracking. `approved` records the approval timestamp and advances to the next gate. Uses `Math.max()` guard to never regress gate progress.
+- **Session telemetry enrichment** — `session.start` now captures the active AI model name and user email from config. `session.stop` records model, input/output token counts, and a prompt summary extracted from the session transcript (`transcript_path` in hookData).
+- **`project-conventions.md`** — New mandatory override file at `custom/rules/project-conventions.md`. Enforces that Gate 2 plans are always saved to `plan/[ticket-id]/plan.md` (overriding the skill default `docs/superpowers/plans/`). Includes a checklist and path table for all Gate outputs.
+- **Gate workflow: explicit plan output path** — Gate 2 instruction in `gate-workflow.md` now explicitly states that the plan must be saved to `plan/[ticket-id]/plan.md`, with a note that the `writing-plans` skill default path is overridden.
+- **WSL clipboard support in `ak prompt`** — `ak prompt` now correctly copies output to the Windows clipboard when running inside WSL using `powershell.exe Set-Clipboard`. Previously fell through to `xclip`/`xsel` which are unavailable on WSL without extra setup.
+- **`appscript.js`** — Google Apps Script source for the self-hosted telemetry backend. Receives HMAC-signed events from the `ak` CLI, validates them, and appends rows to Google Sheets.
+- **Telemetry `record()` returns result object** — `record()` now returns `{ok: true}` on success or `{ok: false, reason, error}` on failure, enabling `ak gate` and `ak telemetry log` to display ✓ / ⚠ feedback per event.
+- **`ak init` remembers previous framework selection** — Re-running `ak init` in an already-configured project now pre-selects the previously chosen frameworks (read from `.aiflow/state.json`) instead of falling back to auto-detection. A "Previously selected: ..." hint is shown above the checkbox list.
 
 ### Fixed
 
 - **Critical: `figma-to-component` skill used non-existent tool names** — The skill referenced `figma_get_file_nodes`, `figma_get_file_styles`, `figma_get_file_components`, and `figma_get_image` — none of which exist in `figma-developer-mcp` or any other MCP package, causing the skill to silently fail on every run. Replaced with the correct tools: `get_figma_data(fileKey, nodeId, depth=2)` and `download_figma_images(fileKey, nodes, localPath)`.
 - **Figma API token verification using wrong auth header** — `verifyFigma()` in `scripts/init.js` was sending `Authorization: Bearer <token>`, which is only valid for OAuth tokens. Figma Personal Access Tokens (`figd_...`) require `X-Figma-Token: <token>`. This caused every PAT to be rejected as invalid during `ak init -a figma` even when the token was correct.
+- **Critical: `currentGate` not advancing after gate transitions** — `task-state.json` was not updating `currentGate` when the AI called `ak gate N start`, so resuming a task always restarted from the wrong gate. Added dedicated `updateTaskGateState()` and fixed `createOrActivateTaskState()` to use `Math.max()`.
+- **Duplicate `session.start` telemetry event** — `session-start.js` was calling `record()` before reading stdin, causing the event to fire twice in some hook configurations. Fixed by moving `record()` inside the `stdin.on('end')` handler.
+- **Short command aliases not resolving for telemetry** — `task` and `memory` subcommand short aliases (`t st`, `t ls`, `mem s`, etc.) were not being resolved before telemetry pre-processing, causing `unknown` in the command column. Fixed alias resolution in the pre-hook telemetry mapping.
+- **`ak telemetry log` silent on failure** — `ak telemetry log --event X` previously swallowed all errors silently (no output). Now shows ✓ on success and ⚠ with reason (`disabled`, `opted-out`, `no-url`) on skip/failure.
+- **Gate telemetry blocked by bash redirect error** — AI was appending `2>$null` (PowerShell syntax) to `ak gate` commands when following "run silently" instructions, causing bash to fail with `/usr/bin/bash: $null: ambiguous redirect`. Added explicit "do NOT append shell redirects" instruction to `gate-workflow.md` for all gate telemetry commands.
 
 ---
 

package/docs/common/QUICK_START.md

@@ -352,6 +352,45 @@ aiflow use PROJ-88
 claude                                # AI auto-starts: map dependencies → assess risk → output report
 ```
 
+### Figma Design → Code
+
+Turn a Figma design into a React / Next.js / Vue / Angular component automatically.
+
+**Step 1: Set up Figma MCP adapter (one-time)**
+
+Choose one option:
+
+| Option | Command | Requirement |
+|--------|---------|-------------|
+| Figma Desktop (recommended) | `ak init -a figma-desktop` | Figma Desktop app installed and open |
+| Figma REST API | `ak init -a figma` | Figma Personal Access Token (`figd_...`) |
+
+```bash
+# Option A: Figma Desktop — no API token needed, uses Desktop session
+ak init -a figma-desktop
+
+# Option B: Figma REST API — requires Personal Access Token
+ak init -a figma
+# Enter your token when prompted (Settings → Security → Personal access tokens)
+```
+
+**Step 2: Get the Figma node URL**
+
+In Figma Desktop or web, right-click the frame/component → **Copy link to selection**.
+
+URL format: `https://www.figma.com/design/<fileKey>/...?node-id=<nodeId>`
+
+**Step 3: Trigger the skill in Claude**
+
+```
+Generate component from this Figma frame:
+https://www.figma.com/design/abc123/MyDesign?node-id=12:34
+```
+
+Claude uses the `figma-to-component` skill and auto-detects your framework (Next.js App Router, React, Vue, Angular).
+
+> Full guide: [docs/common/workflows/figma.md](./workflows/figma.md)
+
 ---
 
 ## All Commands

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relipa/ai-flow-kit",
-  "version": "0.0.9-beta.1",
+  "version": "0.0.9",
   "description": "All-in-one AI Flow Kit for team development with Claude AI - skills, templates, and MCP adapters",
   "author": "Example Team",
   "publishConfig": {

package/scripts/init.js

@@ -903,9 +903,22 @@ async function init(options) {
 
         // ── Auto-detect or prompt for framework if not supplied ──────
         if (frameworks.length === 0) {
+            const stateFilePath = path.join(aiflowDir, 'state.json');
+            let previousFrameworks = [];
+            if (await fs.pathExists(stateFilePath)) {
+                const savedState = await fs.readJson(stateFilePath);
+                previousFrameworks = savedState.frameworks || [];
+            }
+
             const detected = await detectFramework(projectDir);
             const hint = chalk.gray('  Space to select/unselect · Enter to confirm · Leave empty to skip');
-            if (detected) {
+            if (previousFrameworks.length > 0) {
+                const labels = previousFrameworks
+                    .map(v => FRAMEWORK_CHOICES.find(c => c.value === v)?.name || v)
+                    .join(', ');
+                console.log(chalk.cyan(`\n  Previously selected: ${chalk.bold(labels)}`));
+                console.log(hint);
+            } else if (detected) {
                 const label = FRAMEWORK_CHOICES.find(c => c.value === detected)?.name || detected;
                 console.log(chalk.cyan(`\n  Detected framework: ${chalk.bold(label)}`));
                 console.log(hint);
@@ -917,7 +930,9 @@ async function init(options) {
                 message: 'Select framework(s):',
                 choices: FRAMEWORK_CHOICES.map(c => ({
                     ...c,
-                    checked: c.value === detected,
+                    checked: previousFrameworks.length > 0
+                        ? previousFrameworks.includes(c.value)
+                        : c.value === detected,
                 })),
             });
             frameworks = chosen;