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

package/bin/ak.js

@@ -1,4 +1,4 @@
 #!/usr/bin/env node
-
-process.env.AIFLOW_IS_AK = '1';
-require('./aiflow.js');
+
+process.env.AIFLOW_IS_AK = '1';
+require('./aiflow.js');

package/custom/mcp-presets/README.md

@@ -53,6 +53,72 @@ aiflow use BACKLOG-456
 # Loads task from your Backlog instance
 ```
 
+### Figma (`figma.json`)
+
+Connect to Figma via REST API to read design files and generate components.
+
+**When to use:** Default choice. Works anywhere — no Desktop app required.
+
+**Setup:**
+```bash
+aiflow init --adapter figma
+```
+
+**Required Environment Variables:**
+- `FIGMA_API_TOKEN` — Your Figma Personal Access Token
+
+**Get API Token:**
+1. Go to https://www.figma.com/settings → Security → Personal access tokens
+2. Create a new token with File content (read) scope
+3. Copy the token
+
+**Tools provided by `figma-developer-mcp`:**
+- `get_figma_data(fileKey, nodeId, depth)` — fetch node layout, styles, components
+- `download_figma_images(fileKey, nodes, localPath)` — export images
+
+**Usage:**
+```
+Generate component from Figma:
+https://www.figma.com/design/XXXXX/App?node-id=123-456
+```
+
+See: [Figma workflow guide](../../docs/common/workflows/figma.md)
+
+---
+
+### Figma Desktop (`figma-desktop.json`)
+
+Connect via the official Figma MCP server. Requires Figma Desktop app open.
+
+**When to use:** When your team prefers the official Figma tooling and has Desktop app licenses.
+**When NOT to use:** CI environments, headless servers, team members without Desktop licenses.
+
+**Setup:**
+```bash
+aiflow init --adapter figma-desktop
+```
+
+**Requirements:**
+- Figma Desktop app installed
+- A Figma file open in Desktop when invoking the skill
+- No API token needed — uses Desktop session
+
+**Tools provided by `@figma/mcp-server`:**
+- `get_figma_data(fileKey, nodeId)` — fetch design data for open file
+- `get_node_children(nodeId)` — traverse component tree
+- `get_local_components()` — list components in the open file
+
+| | `figma` (REST API) | `figma-desktop` (Official) |
+|---|---|---|
+| Needs Desktop app | No | Yes (must be open) |
+| Auth | API Token | Desktop session |
+| Works in CI | Yes | No |
+| Access scope | Full REST API | Currently open file |
+
+See: [Figma workflow guide](../../docs/common/workflows/figma.md)
+
+---
+
 ### Google Sheets (`google-sheets.json`)
 
 Connect to Google Sheets for loading task context.

package/custom/mcp-presets/figma-desktop.json

@@ -0,0 +1,9 @@
+{
+  "mcpServers": {
+    "figma": {
+      "command": "npx",
+      "args": ["-y", "@figma/mcp-server"],
+      "env": {}
+    }
+  }
+}

package/custom/rules/project-conventions.md

@@ -0,0 +1,51 @@
+# Project Conventions (Override Skill Defaults)
+
+> **MANDATORY:** These rules override ANY upstream skill default (including `writing-plans`, `generate-spec`, and all superpowers skills).
+> Read this file before writing any output file during the Gate Workflow.
+
+---
+
+## Plan Output Paths
+
+| Output | Path | Note |
+|--------|------|------|
+| Requirement doc | `plan/[ticket-id]/requirement.md` | Gate 1 output |
+| Implementation plan | `plan/[ticket-id]/plan.md` | Gate 2 output — **NOT** `docs/superpowers/plans/` |
+| Summary | `plan/[ticket-id]/summary.md` | Gate 4 output |
+
+> **Override:** The `writing-plans` skill defaults to `docs/superpowers/plans/<filename>.md`.
+> In this project, **always save plans to `plan/[ticket-id]/plan.md` instead.**
+>
+> The `[ticket-id]` comes from `.aiflow/context/current.json`.
+> If no ticket context exists, use a descriptive slug: `plan/<feature-name>/plan.md`.
+
+---
+
+## Execution Handoff Message
+
+When `writing-plans` skill says to announce the saved path, use the **actual path**:
+
+```
+Plan complete and saved to `plan/[ticket-id]/plan.md`. Two execution options: ...
+```
+
+Do NOT copy the hardcoded path from the skill template (`docs/superpowers/plans/`).
+
+---
+
+## Checklist Before Writing Any File
+
+Before saving any plan, requirement, or summary file, verify:
+
+- [ ] Output path follows the table above — NOT the skill's default path
+- [ ] `[ticket-id]` is read from `.aiflow/context/current.json`
+- [ ] Directory `plan/[ticket-id]/` exists or will be created
+- [ ] Announced path in the handoff message matches the actual saved path
+
+---
+
+## Other Conventions
+
+- **Review checklist:** `custom/rules/review-checklist.md`
+- **Code style:** `custom/rules/code-style.md`
+- **Naming:** `custom/rules/naming.md`

package/custom/templates/python.md

@@ -1,79 +1,79 @@
-# Python AI System Prompt
-
-You are an expert Python developer. Follow these rules to produce clean, idiomatic, and maintainable Python code without a specific framework.
-
----
-
-## Project Structure
-
-```
-project/
-├── main.py              # Entry point
-├── src/
-│   ├── service/         # Business logic
-│   ├── repository/      # Data access layer
-│   ├── model/           # Data classes / domain models
-│   └── util/            # Pure helper functions
-├── tests/               # Pytest suite
-├── requirements.txt
-└── pyproject.toml
-```
-
----
-
-## Python Rules
-
-- Use **type hints** on all function signatures and return types.
-- Follow **PEP 8** and keep functions small and single-purpose.
-- Use **dataclasses** or **NamedTuple** for value objects; avoid plain dicts for structured data.
-- Prefer **pathlib** over `os.path`; prefer `with` statements for file/resource handling.
-- Raise specific exceptions — never `raise Exception("message")`.
-
-```python
-# ✅ Good
-from dataclasses import dataclass
-
-@dataclass
-class UserRequest:
-    email: str
-    full_name: str
-
-def create_user(request: UserRequest) -> UserResponse:
-    if not request.email:
-        raise ValueError("email is required")
-    ...
-```
-
----
-
-## Testing Rules
-
-- Use **Pytest** for all tests.
-- Name test functions `test_<what>_<expected_outcome>`.
-- Use `pytest.raises` to assert exceptions.
-
-```python
-def test_create_user_raises_when_email_is_empty():
-    with pytest.raises(ValueError, match="email is required"):
-        create_user(UserRequest(email="", full_name="Test"))
-```
-
----
-
-## Naming Conventions
-
-| Element | Convention | Example |
-|---------|-----------|---------|
-| Module/package | snake_case | `user_service.py` |
-| Class | PascalCase | `UserService` |
-| Function/variable | snake_case | `find_by_id`, `user_id` |
-| Constant | UPPER_SNAKE_CASE | `MAX_RETRY` |
-
----
-
-## Common Anti-Patterns to Avoid
-
-- ❌ Bare `except:` — always catch a specific exception type
-- ❌ Mutable default arguments (`def f(x=[])`) — use `None` sentinel instead
-- ❌ Global state — pass dependencies explicitly
-- ❌ Returning `None` implicitly on error paths — raise or return a typed result
+# Python AI System Prompt
+
+You are an expert Python developer. Follow these rules to produce clean, idiomatic, and maintainable Python code without a specific framework.
+
+---
+
+## Project Structure
+
+```
+project/
+├── main.py              # Entry point
+├── src/
+│   ├── service/         # Business logic
+│   ├── repository/      # Data access layer
+│   ├── model/           # Data classes / domain models
+│   └── util/            # Pure helper functions
+├── tests/               # Pytest suite
+├── requirements.txt
+└── pyproject.toml
+```
+
+---
+
+## Python Rules
+
+- Use **type hints** on all function signatures and return types.
+- Follow **PEP 8** and keep functions small and single-purpose.
+- Use **dataclasses** or **NamedTuple** for value objects; avoid plain dicts for structured data.
+- Prefer **pathlib** over `os.path`; prefer `with` statements for file/resource handling.
+- Raise specific exceptions — never `raise Exception("message")`.
+
+```python
+# ✅ Good
+from dataclasses import dataclass
+
+@dataclass
+class UserRequest:
+    email: str
+    full_name: str
+
+def create_user(request: UserRequest) -> UserResponse:
+    if not request.email:
+        raise ValueError("email is required")
+    ...
+```
+
+---
+
+## Testing Rules
+
+- Use **Pytest** for all tests.
+- Name test functions `test_<what>_<expected_outcome>`.
+- Use `pytest.raises` to assert exceptions.
+
+```python
+def test_create_user_raises_when_email_is_empty():
+    with pytest.raises(ValueError, match="email is required"):
+        create_user(UserRequest(email="", full_name="Test"))
+```
+
+---
+
+## Naming Conventions
+
+| Element | Convention | Example |
+|---------|-----------|---------|
+| Module/package | snake_case | `user_service.py` |
+| Class | PascalCase | `UserService` |
+| Function/variable | snake_case | `find_by_id`, `user_id` |
+| Constant | UPPER_SNAKE_CASE | `MAX_RETRY` |
+
+---
+
+## Common Anti-Patterns to Avoid
+
+- ❌ Bare `except:` — always catch a specific exception type
+- ❌ Mutable default arguments (`def f(x=[])`) — use `None` sentinel instead
+- ❌ Global state — pass dependencies explicitly
+- ❌ Returning `None` implicitly on error paths — raise or return a typed result

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.
 
 ---
 
@@ -38,6 +39,7 @@ 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.
 

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-beta.1",
+  "version": "0.0.9-beta.0",
   "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);
+    }
+});