@relipa/ai-flow-kit 0.0.9-beta.1 → 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,20 +17,21 @@ 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"**.
 
 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 +44,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 +58,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 +76,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 +88,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/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,7 +7,37 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
-## [0.0.9] - 2026-05-21
+## [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
 
@@ -17,11 +47,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

@@ -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
@@ -352,6 +358,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
@@ -371,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.