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

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

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

package/custom/rules/project-conventions.md

@@ -1,51 +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`
+# 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/skills/read-study-requirement/SKILL.md

@@ -35,6 +35,11 @@ When creating `plan/[ticket-id]/summary.md` during Gate 1:
 - Keep `summary.md` concise. Only include short bullet points tracking Gates.
 - Do not write verbose implementation details in `summary.md` at Gate 1.
 
+0. **Pre-flight — Sync with remote** (before reading any source file):
+   - Run `git status --porcelain` to check for uncommitted changes.
+   - Working tree clean → run `git pull --ff-only` to fetch the latest code.
+   - Uncommitted changes detected → SKIP pull and notify DEV: `⚠️ Uncommitted changes detected — skipping git pull. Analysing local state.`
+   - `git pull --ff-only` fails (branch diverged from remote) → notify DEV: `⚠️ Local branch diverged from remote — skipping pull. Resolve manually before next ticket.` Then continue with local state.
 1. Read `.aiflow/context/current.json` — ticket title, description, acceptance criteria
 2. Identify **directly affected files** from ticket text and file names only.
    DO NOT trace data flow or read unrelated source files.
@@ -77,15 +82,28 @@ When creating `plan/[ticket-id]/summary.md` during Gate 1:
 
 ### Step 1: Load Ticket & Read Source Code
 
+0. **Pre-flight — Sync with remote** (run BEFORE reading any source file):
+   - Run `git status --porcelain` first. Empty output = clean working tree.
+   - Clean working tree → run `git pull --ff-only` to pull the latest code from remote. This guarantees the analysis is based on current source, not stale local state.
+   - Uncommitted changes → SKIP pull and notify DEV: `⚠️ Uncommitted changes detected — skipping git pull. Analysing local state.`
+   - `git pull --ff-only` fails because the branch has diverged → notify DEV: `⚠️ Local branch diverged from remote — skipping pull. Resolve manually before next ticket.` Continue with local state.
+   - Repo has no remote tracking branch (detached HEAD or local-only branch) → skip silently and proceed.
 1. Read `.aiflow/context/current.json` — ticket info from Backlog/Jira
-2. Read `CLAUDE.md` — understand project architecture, tech stack, conventions
-3. Read related source files — trace data flow, identify patterns, dependencies
+2. **Supplementary Context:** If `current.json` has a `supplementaryContext[]` array, read each item and integrate it as supporting context for your analysis. Items may be:
+   - `[ticket]` — linked tickets (related features, dependencies, parent tickets)
+   - `[comment]` — specific comments from PM/QA/stakeholders
+   - `[file]` — architecture docs, business logic specs, API references
+   - `[text]` — any other supplementary information
+
+   If you encounter a backlog/jira URL in the ticket description that is **not** already in `supplementaryContext[]`, run `ak fetch-links <url>` and use the JSON output in your analysis without saving.
+3. Read `CLAUDE.md` — understand project architecture, tech stack, conventions
+4. Read related source files — trace data flow, identify patterns, dependencies
    - **If GitNexus MCP is available** (`.mcp.json` has `gitnexus` entry): invoke GitNexus MCP tools instead of reading files directly — one call returns full context without multi-file exploration:
      - `gitnexus: context("ClassName")` → 360° view of a symbol (dependencies, callers, methods)
      - `gitnexus: query("keyword or description")` → hybrid search across codebase
      - Saves ~50% of token cost at this step vs reading files manually
    - **If task is a Bug Fix:** Invoke `superpowers:systematic-debugging` to trace root cause before proposing fixes.
-4. Read ticket comments — additional context from PM/team
+5. Read ticket comments — additional context from PM/team
 
 Do this investigation **before** asking any questions. Come prepared.
 
@@ -310,6 +328,7 @@ Please review the requirement document.
 - ❌ **DO NOT** proceed past Step 2 if design is not confirmed by developer
 - ❌ **DO NOT** write code at any point in this skill
 - ❌ **DO NOT** skip impact analysis and effort estimate
+- ✅ **MUST** run `git status` + `git pull --ff-only` (Pre-flight) before reading source code, when working tree is clean
 - ✅ **MUST** read source code before Q&A begins
 - ✅ **MUST** save `plan/[ticket-id]/requirement.md`
 - ✅ **MUST** display Gate 1 prompt and wait for `APPROVED`

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

@@ -17,13 +17,14 @@ You have superpowers. When a ticket context exists in `.aiflow/context/current.j
 
 AI actively reads ticket + source code to understand the requirement:
 1. Read `.aiflow/context/current.json` — ticket info
-2. Read source code — architecture, related files, data flow
-3. If anything is unclear — ask ONE question at a time, wait for reply
-4. Output `plan/[ticket-id]/requirement.md` with:
+2. **Pre-flight: sync with remote** — run `git status --porcelain`; if working tree is clean, run `git pull --ff-only` to pull the latest source from remote. Skip the pull (with a `⚠️` notice to DEV) if there are uncommitted changes, the branch has diverged, or no remote tracking branch exists.
+3. Read source code — architecture, related files, data flow
+4. If anything is unclear — ask ONE question at a time, wait for reply
+5. Output `plan/[ticket-id]/requirement.md` with:
    - Requirements summary, source code analysis
    - Proposed solution and approach
    - Impact analysis, effort estimate, testing plan
-5. Display "GATE 1: Requirement doc ready" → wait for **APPROVED**
+6. Display "GATE 1: Requirement doc ready" → wait for **APPROVED**
 
 > **Tip:** If auto-start doesn't trigger, the developer can start this gate by typing: **"start"**, **"Gate 1"** or **"Analyze ticket"**.
 

package/custom/templates/tools/gemini.md

@@ -1,22 +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".
-- **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.
+# 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,36 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [0.1.0] - 2026-05-28
+
+### Added
+
+- **Multi-target `ak use`** — `ak use` now accepts variadic targets so multiple sources can be loaded in a single call. The first target becomes the primary context (drives Gate 1); the rest are appended to `current.json` as `supplementaryContext[]`. Targets can be ticket IDs, Backlog/Jira URLs, or local files.
+  ```bash
+  ak use PROJ-33 PROJ-10 docs/arch.md
+  # PROJ-33 = primary, PROJ-10 + docs/arch.md = supplementary
+  ```
+  Backward compatible: `ak use PROJ-33` (single target) behaves exactly as before.
+- **Auto link resolution** — When the primary ticket's description contains Backlog/Jira URLs, `ak use` now auto-fetches them and appends to `supplementaryContext[]`. AI no longer misses linked context. Capped at **5 auto-resolved links per `use`** to keep loads fast; per-link errors are caught and logged without aborting the command.
+- **Comment-aware link resolution** — Comment URLs are resolved to that **single comment** instead of fetching the whole ticket. Recognised patterns:
+  - Backlog: `https://*.backlog.com/view/PROJ-10#comment-456`
+  - Jira: `https://*.atlassian.net/browse/PROJ-10?focusedCommentId=456`
+- **`ak fetch-links <url>` command** — Standalone command that fetches a single Backlog/Jira URL and prints a `SupplementaryContext` JSON object to stdout. Used by the `read-study-requirement` skill at runtime when AI encounters a link in the ticket description that wasn't already resolved at `use` time.
+  ```bash
+  ak fetch-links "https://company.backlog.com/view/PROJ-10#comment-456"
+  ```
+- **`supplementaryContext[]` schema in `current.json`** — New top-level array; each item has shape `{ sourceType: 'ticket'|'comment'|'file'|'text', sourceUrl?, sourcePath?, ticketId?, commentId?, title?, description?, content?, author?, date? }`. Persisted across sessions and consumed by the SessionStart hook.
+- **SessionStart hook renders supplementary block** — `scripts/hooks/session-start.js` now emits a `**Supplementary Context (N source(s)):**` section in the AI context prompt, one line per item, content truncated at 1000 chars to keep token cost bounded.
+- **`read-study-requirement` skill integrates supplementary context** — Gate 1 instruction file (custom + installed `.claude/skills/`) now has an explicit step to read `supplementaryContext[]` and use `ak fetch-links` for any unresolved links found while analysing the ticket.
+- **`scripts/link-resolver.js` module** — New CommonJS module that owns all URL classification and HTTPS fetching for Backlog/Jira. Exports: `classifyLink`, `scanLinks`, `fetchBacklogTicket`, `fetchBacklogComment`, `fetchJiraTicket`, `fetchJiraComment`, `fetchLink`, `resolveLinks`. Accepts credentials as parameters to keep `use.js` free of circular imports.
+- **Jest test suite** — Added Jest 30 as a dev dependency with `testMatch: ["<rootDir>/tests/**/*.test.js"]` to scope discovery to project tests (skips `upstream/tests/`). Suite includes `tests/smoke.test.js` and 20 unit tests in `tests/link-resolver.test.js` covering URL classification, scan, dedup, per-adapter fetch paths, and `resolveLinks` error isolation.
+
+### Changed
+
+- **`use.js` exports as named const** — `module.exports` shifted from anonymous function to `useCommand` with a `loadCredentials` property attached, so other modules (CLI `fetch-links` handler) can reuse credential loading without re-implementing it. External call shape (`useCommand(targets, options)`) unchanged for backward compatibility.
+
+---
+
 ## [0.0.9] - 2026-05-25
 
 ### Added

package/docs/common/QUICK_START.md

@@ -76,6 +76,10 @@ aiflow use https://mycompany.backlog.com/view/PROJ-33
 # Load newest 5 comments
 aiflow use PROJ-33 --clast 5
 
+# Multi-target — primary ticket + supplementary sources (v0.1.0+)
+aiflow use PROJ-33 PROJ-10 docs/arch.md
+# PROJ-33 drives Gate 1; PROJ-10 + docs/arch.md become supplementary context
+
 # Manual input (no Backlog/Jira)
 aiflow use --manual
 
@@ -83,6 +87,8 @@ aiflow use --manual
 aiflow use --file task-description.txt
 ```
 
+> **Auto Link Resolution (v0.1.0+):** Backlog/Jira URLs in the primary ticket's description are auto-fetched and added to `supplementaryContext[]`. Comment links (`#comment-456`, `?focusedCommentId=456`) fetch **only that comment**. AI integrates these supplementary sources in Gate 1 analysis automatically.
+
 Output:
 ```
 ✓ Context loaded
@@ -410,12 +416,14 @@ ak sync                                        # sync aiflow instruction files
 
 # Per task
 ak use PROJ-33                                 # load context (Fast Mode, default) — alias: ak u PROJ-33
+ak use PROJ-33 PROJ-10 docs/arch.md            # multi-target: primary + supplementary (v0.1.0+)
 ak use PROJ-33 -F                              # Fast Mode explicit  (--fast)
 ak use PROJ-33 -U                              # Full Mode  (--full)
 ak use -f task.md                              # load from local file  (--file)
 ak use PROJ-33 -c                              # load with all comments  (--coms)
 ak use PROJ-33 --clast 5                       # newest 5 comments
 ak use -m                                      # manual input  (--manual)
+ak fetch-links "<backlog-or-jira-url>"         # fetch single link → JSON (used by AI runtime, v0.1.0+)
 ak p bug-fix                                   # generate prompt  (ak prompt)
 ak p feature -o p.md                           # save prompt to file  (--output)
 ak p -L vietnamese                             # Vietnamese prompt  (--lang)

package/docs/common/cli-reference.md

@@ -81,11 +81,12 @@ Initializing ai-flow-kit (v1.0.0)...
 
 ## use
 
-Load context from a ticket, file, or manual entry.
+Load context from one or more tickets, files, or manual entry. **Accepts variadic targets** (v0.1.0+) — the first target is the primary context (drives Gate 1); any additional targets are appended as `supplementaryContext[]`.
 
 ```bash
-ak use JIRA-123                              # load from Jira
-ak use BACKLOG-456                           # load from Backlog
+ak use JIRA-123                              # single target — load from Jira
+ak use BACKLOG-456                           # single target — load from Backlog
+ak use PROJ-33 PROJ-10 docs/arch.md          # multi-target — primary + supplementary (v0.1.0+)
 ak use BACKLOG-456 -F                        # fast mode  (--fast)
 ak use BACKLOG-456 -U                        # full mode  (--full)
 ak use -m                                    # manual entry  (--manual)
@@ -96,8 +97,10 @@ ak use BACKLOG-456 --cid 42                  # specific comment
 ak use 1.0.0                                 # switch between versions
 ```
 
+**Arguments:**
+- `[targets...]` — One or more targets. Each target can be a ticket ID (`PROJ-33`), a Backlog/Jira URL, or a local file path. First target = primary; rest = supplementary.
+
 **Options:**
-- `<id>` — Ticket ID or version number
 - `-m, --manual` — Manual context entry
 - `-f, --file <path>` — Load from file (JSON or plain text)
 - `-s, --save <name>` — Save as named context
@@ -110,11 +113,31 @@ ak use 1.0.0                                 # switch between versions
 - `-F, --fast` — Fast mode: AI skips Q&A, lite 3-section requirement doc (< 5 min Gate 1)
 - `-U, --full` — Full mode: force complete Gate 1 analysis with Q&A
 
+**Auto link resolution (v0.1.0+):** When the primary ticket description contains Backlog/Jira URLs, `ak use` auto-fetches them and appends to `supplementaryContext[]`. Comment URLs (`#comment-456` or `?focusedCommentId=456`) resolve to **that single comment only**. Capped at 5 auto-resolved links per `use`; per-link errors are logged without aborting the command.
+
+**`supplementaryContext[]` schema** (persisted in `.aiflow/context/current.json`):
+
+```json
+{
+  "sourceType": "ticket | comment | file | text",
+  "sourceUrl": "https://...",
+  "sourcePath": "docs/arch.md",
+  "ticketId": "PROJ-10",
+  "commentId": "456",
+  "title": "...",
+  "description": "...",
+  "content": "...",
+  "author": "...",
+  "date": "..."
+}
+```
+
 **What it does:**
-1. Fetches context from MCP adapter (if applicable)
-2. Parses and validates context
-3. Saves to `.aiflow/context/current.json` (including `mode` field for Gate 1 behaviour)
-4. Updates state tracking
+1. Loads the first target as primary context (fetches from MCP adapter / file / manual entry)
+2. Loads each remaining target as a supplementary item
+3. Scans the primary description for Backlog/Jira URLs and auto-resolves them
+4. Saves the merged context (including `mode` and `supplementaryContext[]`) to `.aiflow/context/current.json`
+5. Updates state tracking
 
 **Example:**
 ```bash
@@ -126,8 +149,37 @@ Fetching context from Jira...
 ✓ Saved to .aiflow/context/current.json
 
 Ready to prompt! Run: aiflow prompt bug-fix
+
+$ aiflow use PROJ-33 PROJ-10 docs/arch.md
+✓ Loaded primary: PROJ-33
+✓ Supplementary: PROJ-10 (ticket), docs/arch.md (file)
+✓ Auto-resolved 2 link(s) from description
 ```
 
+## fetch-links
+
+Fetch a single Backlog/Jira URL and print a `SupplementaryContext` JSON object to stdout. Intended for AI runtime use inside the `read-study-requirement` skill — when AI encounters a link in the ticket description that wasn't already resolved by `ak use`, it can call this command and integrate the JSON output.
+
+```bash
+ak fetch-links "https://company.backlog.com/view/PROJ-10"                   # full ticket
+ak fetch-links "https://company.backlog.com/view/PROJ-10#comment-456"        # single comment
+ak fetch-links "https://company.atlassian.net/browse/PROJ-10"                # Jira ticket
+ak fetch-links "https://company.atlassian.net/browse/PROJ-10?focusedCommentId=789"  # Jira comment
+```
+
+**Arguments:**
+- `<url>` — Backlog or Jira URL (ticket or comment)
+
+**What it does:**
+1. Loads stored credentials from `.aiflow/credentials.json`
+2. Classifies the URL (Backlog vs Jira, ticket vs comment)
+3. Fetches via the appropriate adapter API
+4. Prints the resulting `SupplementaryContext` JSON to stdout
+
+**Exit codes:**
+- `0` — Success, JSON written to stdout
+- `1` — URL not recognised as Backlog/Jira, or fetch failed (error message on stderr)
+
 ## task (alias: `t`)
 
 Manage multiple tasks — pause, switch, and resume while preserving gate progress.

package/docs/common/workflows/figma.md

@@ -1,105 +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`) |
+# 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`) |