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

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

@@ -7,6 +7,7 @@ You have superpowers. When a ticket context exists in `.aiflow/context/current.j
 - **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.
+- **PROJECT CONVENTIONS:** Before writing any output file (plan, requirement, summary), read `custom/rules/project-conventions.md`. These rules override upstream skill defaults.
 
 ---
 
@@ -28,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 `aiflow gate 1 start --ticket [ticket-id]` when starting this gate (auto-start or when developer types "start"/"Gate 1").
-> Run `aiflow 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 `ak gate 1 approved --ticket [ticket-id]` immediately when APPROVED is received.
 
 ---
 
@@ -38,11 +39,12 @@ DO NOT just check format — **understand the content and propose solutions**.
 **INVOKE:** `generate-spec` skill, then `superpowers:writing-plans`
 
 - 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.
 
-> **Telemetry:** Run `aiflow gate 2 start --ticket [ticket-id]` when starting this gate.
-> Run `aiflow 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 `ak gate 2 approved --ticket [ticket-id]` immediately when APPROVED is received.
 
 ---
 
@@ -55,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 `aiflow gate 3 start --ticket [ticket-id]` when starting this gate.
+> **Telemetry:** Run `ak gate 3 start --ticket [ticket-id]` when starting this gate.
 
 ---
 
@@ -73,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 `aiflow gate 4 start --ticket [ticket-id]` when starting this gate.
-> Run `aiflow 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 `ak gate 4 approved --ticket [ticket-id]` immediately when APPROVED is received.
 
 ---
 
@@ -85,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 `aiflow gate 5 start --ticket [ticket-id]` when starting this gate.
+> **Telemetry:** Run `ak gate 5 start --ticket [ticket-id]` when starting this gate.

package/custom/templates/tools/gemini.md

@@ -1,12 +1,22 @@
-# Gemini AI System Instructions
-
-You are an expert AI assistant specialized in this project's stack. Follow the Gate Workflow and Team Rules strictly.
-
-> **Important:** When starting a session, always read `.aiflow/context/current.json` to load ticket context and check the `plan/` directory for existing progress.
-
-If no instructions are automatically followed, wait for the developer to type **"start"** or **"Gate 1"** to start the analysis.
-
-## Interaction Rules:
-- **COLLABORATIVE SKILLS:** When a skill (like `read-study-requirement`) says to "ask one question at a time", you MUST stop and wait for the developer's reply before proceeding.
-- **NEVER BATCH QUESTIONS:** Only ask one question per message.
-- **WAIT FOR APPROVAL:** Do not move to the next Gate until you receive "APPROVED".
+# Gemini AI System Instructions
+
+You are an expert AI assistant specialized in this project's stack. Follow the Gate Workflow and Team Rules strictly.
+
+> **Important:** When starting a session, always read `.aiflow/context/current.json` to load ticket context and check the `plan/` directory for existing progress.
+
+If no instructions are automatically followed, wait for the developer to type **"start"** or **"Gate 1"** to start the analysis.
+
+## Interaction Rules:
+- **COLLABORATIVE SKILLS:** When a skill (like `read-study-requirement`) says to "ask one question at a time", you MUST stop and wait for the developer's reply before proceeding.
+- **NEVER BATCH QUESTIONS:** Only ask one question per message.
+- **WAIT FOR APPROVAL:** Do not move to the next Gate until you receive "APPROVED".
+- **PROJECT CONVENTIONS:** Before writing any output file (plan, requirement, summary), read `custom/rules/project-conventions.md`. These rules override upstream skill defaults.
+
+## Telemetry Command (detect once, use everywhere)
+
+Before the first gate, run this to detect the correct `ak` command for your environment:
+```bash
+command -v ak >/dev/null 2>&1 && echo "USE: ak" || echo "USE: ak.cmd"
+```
+Use whichever prints (e.g. `ak` on native Linux/Mac/Windows, `ak.cmd` on WSL without ak installed).
+All `ak gate ...` examples below assume the detected command. Substitute accordingly.

package/docs/common/CHANGELOG.md

@@ -7,6 +7,24 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [0.0.9] - 2026-05-21
+
+### Added
+
+- **`figma-desktop` adapter** — New MCP preset using the official `@figma/mcp-server` package (Figma Inc.). Requires Figma Desktop app installed and open. No API token needed — authenticates via Desktop session. Run `ak init -a figma-desktop` to set up. See [`custom/mcp-presets/figma-desktop.json`](../../custom/mcp-presets/figma-desktop.json).
+- **Next.js App Router support in `figma-to-component` skill** — Detects App Router projects (via `nextjs-app-router` in `CLAUDE.md` or presence of `app/` directory). Defaults to Server Component (`export default async function`); adds `'use client'` directive only when the design has interactive states (hover, click handlers, form inputs).
+- **Angular support in `figma-to-component` skill** — Detects Angular projects (via `angular` in `CLAUDE.md` or presence of `angular.json`). Generates standalone `@Component` class with `@Input() className` and computed `hostClasses` getter. Uses Tailwind if `tailwind.config.*` exists, otherwise CSS-in-component.
+- **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.
+
+### 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.
+
+---
+
 ## [0.0.8-beta.1] - 2026-05-14
 
 ### Fixed

package/docs/common/workflows/figma.md

@@ -0,0 +1,105 @@
+# Figma → Component Workflow
+
+Generate UI components directly from Figma designs using the `figma-to-component` skill.
+
+---
+
+## Prerequisites
+
+Choose one adapter based on your setup:
+
+### Option A — REST API (recommended, no Desktop required)
+
+```bash
+ak init -a figma
+# Prompts for FIGMA_API_TOKEN
+```
+
+Get your token: [figma.com/settings](https://www.figma.com/settings) → Security → Personal access tokens → Create new token (File content: read).
+
+### Option B — Official Figma MCP (requires Figma Desktop app)
+
+```bash
+ak init -a figma-desktop
+# No token needed — uses Desktop app session
+```
+
+Requirements: Figma Desktop app installed and the target file open before invoking the skill.
+
+---
+
+## Getting a Figma Node URL
+
+1. Open your file in Figma (browser or Desktop)
+2. Right-click on a frame or component → **Copy link to selection**
+3. The URL looks like:
+   ```
+   https://www.figma.com/design/FILEKEY/FileName?node-id=123-456
+   ```
+   - `FILEKEY` — the file identifier (between `/design/` and the next `/`)
+   - `node-id=123-456` — the specific frame or component to generate
+
+You can also link to the entire file (no `node-id`) to let the skill list available frames.
+
+---
+
+## Trigger the Skill
+
+Paste the Figma URL into Claude Code with a generation request:
+
+```
+Generate component from this Figma frame:
+https://www.figma.com/design/XXXXX/App?node-id=123-456
+```
+
+```
+Implement the UserCard UI from Figma:
+https://www.figma.com/design/XXXXX/App?node-id=78-910
+```
+
+```
+Read Figma and generate component following my project conventions:
+https://www.figma.com/design/XXXXX/App?node-id=42-0
+```
+
+---
+
+## What to Expect
+
+The skill outputs in this order:
+
+1. **Design Summary** — layout structure, color palette, typography scale used in the design
+2. **Component file** — complete code for your detected framework (React, Next.js App Router, Vue 3, or Angular)
+3. **Usage example** — how to import and use the component
+4. **Notes** — anything that couldn't be mapped 1:1 from Figma (custom fonts, unsupported effects, etc.)
+
+**Framework auto-detection order:**
+1. Read `CLAUDE.md` for framework identifier (`nextjs-app-router`, `reactjs`, `vue-nuxt`, `angular`)
+2. Scan project files (`app/` dir → App Router, `angular.json` → Angular, `nuxt.config.*` → Vue)
+3. Fallback → Next.js / React
+
+---
+
+## Review Checklist
+
+After the component is generated, verify:
+
+- [ ] Layout matches Figma (flex direction, alignment, gap)
+- [ ] Colors are correct (Tailwind class or arbitrary value)
+- [ ] Typography matches (size, weight, line-height)
+- [ ] Spacing correct (padding, margin, gap)
+- [ ] Interactive states handled (`'use client'` in App Router, variants in React/Vue/Angular)
+- [ ] Images use correct component (`next/image` for Next.js, `<img>` for others)
+- [ ] `className` / `class` prop exposed for external overrides
+
+---
+
+## Troubleshooting
+
+| Problem | Fix |
+|---|---|
+| `get_figma_data` tool not found | Run `ak init -a figma` to configure the MCP |
+| "Invalid API token" | Token expired — create a new one at figma.com/settings |
+| Wrong node generated | Check the `node-id` in the URL matches your selection in Figma |
+| Figma Desktop MCP not responding | Ensure Figma Desktop app is open with the file loaded |
+| Component uses wrong framework | Add framework to `CLAUDE.md` (e.g. `nextjs-app-router`) |

package/package.json

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

package/scripts/hooks/block-git-write.js

@@ -1,52 +1,52 @@
-#!/usr/bin/env node
-/**
- * PreToolUse hook for ai-flow-kit
- *
- * Hard-blocks AI from running git-write operations (commit/add/push/tag) via the
- * Bash tool. The developer always controls commits manually in their own terminal.
- *
- * Stdin payload (from Claude Code):
- *   { tool_name: "Bash", tool_input: { command: "..." }, ... }
- *
- * Exit codes:
- *   0 — allow (stdout empty)
- *   2 — block (stderr message is fed back to Claude as feedback)
- *
- * Override (for the kit's own maintenance scripts):
- *   export AIFLOW_ALLOW_GIT_WRITE=1
- */
-
-let raw = '';
-process.stdin.setEncoding('utf-8');
-process.stdin.on('data', (chunk) => { raw += chunk; });
-process.stdin.on('end', () => {
-    try {
-        if (process.env.AIFLOW_ALLOW_GIT_WRITE === '1') process.exit(0);
-
-        const payload = raw ? JSON.parse(raw) : {};
-        if (payload.tool_name !== 'Bash') process.exit(0);
-
-        const command = (payload.tool_input && payload.tool_input.command) || '';
-        if (!command) process.exit(0);
-
-        // Match `git <subcommand>` where subcommand is a write operation.
-        // Tolerates leading args (e.g. `git -C path commit`, `git --no-pager add`).
-        // Captures occurrences inside compound shells: `&&`, `||`, `;`, `|`, `$(...)`, backticks, newline.
-        const BLOCK_RE = /(^|[\s;&|`(){}])git(\s+-[^\s]+)*\s+(commit|add|push|tag|reset|rebase|revert|cherry-pick|am|merge)\b/i;
-        const match = command.match(BLOCK_RE);
-        if (!match) process.exit(0);
-
-        const verb = match[3].toLowerCase();
-        process.stderr.write(
-            `[aiflow] BLOCKED: \`git ${verb}\` is not allowed for AI.\n` +
-            `Reason: ai-flow-kit forbids AI-driven commits/pushes. The developer manages git state manually.\n` +
-            `If this is a legitimate maintenance task (running the kit's own CI), set AIFLOW_ALLOW_GIT_WRITE=1 in the environment.\n` +
-            `Otherwise, finish the task without committing; the developer will run \`git ${verb}\` themselves at Gate 5.\n`
-        );
-        process.exit(2);
-    } catch (err) {
-        // On parsing error, fail open (don't block) but log to stderr for visibility.
-        process.stderr.write(`[aiflow] block-git-write hook error: ${err.message}\n`);
-        process.exit(0);
-    }
-});
+#!/usr/bin/env node
+/**
+ * PreToolUse hook for ai-flow-kit
+ *
+ * Hard-blocks AI from running git-write operations (commit/add/push/tag) via the
+ * Bash tool. The developer always controls commits manually in their own terminal.
+ *
+ * Stdin payload (from Claude Code):
+ *   { tool_name: "Bash", tool_input: { command: "..." }, ... }
+ *
+ * Exit codes:
+ *   0 — allow (stdout empty)
+ *   2 — block (stderr message is fed back to Claude as feedback)
+ *
+ * Override (for the kit's own maintenance scripts):
+ *   export AIFLOW_ALLOW_GIT_WRITE=1
+ */
+
+let raw = '';
+process.stdin.setEncoding('utf-8');
+process.stdin.on('data', (chunk) => { raw += chunk; });
+process.stdin.on('end', () => {
+    try {
+        if (process.env.AIFLOW_ALLOW_GIT_WRITE === '1') process.exit(0);
+
+        const payload = raw ? JSON.parse(raw) : {};
+        if (payload.tool_name !== 'Bash') process.exit(0);
+
+        const command = (payload.tool_input && payload.tool_input.command) || '';
+        if (!command) process.exit(0);
+
+        // Match `git <subcommand>` where subcommand is a write operation.
+        // Tolerates leading args (e.g. `git -C path commit`, `git --no-pager add`).
+        // Captures occurrences inside compound shells: `&&`, `||`, `;`, `|`, `$(...)`, backticks, newline.
+        const BLOCK_RE = /(^|[\s;&|`(){}])git(\s+-[^\s]+)*\s+(commit|add|push|tag|reset|rebase|revert|cherry-pick|am|merge)\b/i;
+        const match = command.match(BLOCK_RE);
+        if (!match) process.exit(0);
+
+        const verb = match[3].toLowerCase();
+        process.stderr.write(
+            `[aiflow] BLOCKED: \`git ${verb}\` is not allowed for AI.\n` +
+            `Reason: ai-flow-kit forbids AI-driven commits/pushes. The developer manages git state manually.\n` +
+            `If this is a legitimate maintenance task (running the kit's own CI), set AIFLOW_ALLOW_GIT_WRITE=1 in the environment.\n` +
+            `Otherwise, finish the task without committing; the developer will run \`git ${verb}\` themselves at Gate 5.\n`
+        );
+        process.exit(2);
+    } catch (err) {
+        // On parsing error, fail open (don't block) but log to stderr for visibility.
+        process.stderr.write(`[aiflow] block-git-write hook error: ${err.message}\n`);
+        process.exit(0);
+    }
+});