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

package/README.md

@@ -90,7 +90,8 @@ npm uninstall -g @relipa/ai-flow-kit
 | Command | Description |
 |---------|-------------|
 | `aiflow init` | Setup framework, adapters, and multi-AI rules. |
-| `aiflow use <ticket>` | Load ticket context (Backlog/Jira). |
+| `aiflow use <ticket...>` | Load context from one or more tickets/files. First target is primary; rest become supplementary. |
+| `aiflow fetch-links <url>` | Fetch a Backlog/Jira link and print SupplementaryContext JSON (used by AI at runtime). |
 | `aiflow task` | Manage multiple tasks — pause, switch, resume. |
 | `aiflow task next` | Finalize gate approval and prepare for fresh session. |
 | `aiflow prompt` | Generate tool-optimized prompts (`--env cursor`). |
@@ -128,6 +129,16 @@ aiflow init --framework spring-boot,reactjs --adapter backlog,jira
 
 **Supported Adapters:** `backlog`, `jira`, `google-sheets`, `figma`, `figma-desktop`
 
+**Figma adapters:**
+
+| Adapter | Command | Auth | Requirement |
+|---------|---------|------|-------------|
+| `figma` | `ak init -a figma` | Personal Access Token (`figd_...`) | None — REST API |
+| `figma-desktop` | `ak init -a figma-desktop` | Desktop session (no token needed) | Figma Desktop app installed & open |
+
+> The `figma-desktop` adapter uses the official `@figma/mcp-server` package from Figma Inc. and is the recommended option if you already use Figma Desktop.
+> See [Figma workflow guide](docs/common/workflows/figma.md) for usage with the `figma-to-component` skill.
+
 ---
 
 ### `aiflow sync-skills`
@@ -145,28 +156,25 @@ aiflow sync-skills
 
 ---
 
-### `aiflow use <ticket>`
+### `aiflow use <ticket...>`
 
-Load ticket context into `.aiflow/context/current.json`.
+Load ticket context into `.aiflow/context/current.json`. Accepts **one or more targets** (ticket ID, Backlog/Jira URL, or local file). The first target becomes the **primary context**; any additional targets are appended as **`supplementaryContext[]`** for AI to read alongside the primary.
 
 ```bash
-# Backlog
+# Single target (backward compatible)
 aiflow use PROJ-33
 aiflow use https://mycompany.backlog.com/view/PROJ-33
 
-# Jira
-aiflow use PROJ-123
+# Multiple targets — primary + supplementary
+aiflow use PROJ-33 PROJ-10 docs/arch.md
+# PROJ-33 drives Gate 1; PROJ-10 + docs/arch.md become supplementary context
 
-# Default: only load description
-aiflow use PROJ-33
+# Backlog / Jira ticket
+aiflow use PROJ-123
 
-# Load with all comments
+# Comments
 aiflow use PROJ-33 --with-comments
-
-# Load newest 5 comments
 aiflow use PROJ-33 --comments-last 5
-
-# Load comments from index 3 onwards
 aiflow use PROJ-33 --comments-from 3
 
 # Manual input
@@ -183,6 +191,44 @@ aiflow use PROJ-33 --full   # Full Mode: deep analysis with Q&A
 aiflow use PROJ-33 --save sprint-42-bug
 ```
 
+> **New in v0.1.0 — Auto Link Resolution:** When the primary ticket description contains Backlog/Jira URLs, `ak use` automatically fetches them and stores results in `supplementaryContext[]`. Comment links (`#comment-456` or `?focusedCommentId=456`) fetch **only that comment**. Capped at 5 auto-resolved links per `use` to keep loads fast.
+
+---
+
+### `aiflow fetch-links <url>`
+
+Fetch a single Backlog/Jira link and print a `SupplementaryContext` JSON object to stdout. Intended for AI runtime use inside the `read-study-requirement` skill when a link is found in the ticket description that wasn't already resolved at `use` time.
+
+```bash
+# Backlog ticket → full ticket JSON
+aiflow fetch-links "https://company.backlog.com/view/PROJ-10"
+
+# Backlog comment → that single comment only
+aiflow fetch-links "https://company.backlog.com/view/PROJ-10#comment-456"
+
+# Jira ticket / comment
+aiflow fetch-links "https://company.atlassian.net/browse/PROJ-10"
+aiflow fetch-links "https://company.atlassian.net/browse/PROJ-10?focusedCommentId=789"
+```
+
+Output schema:
+
+```json
+{
+  "sourceType": "ticket | comment",
+  "sourceUrl": "...",
+  "ticketId": "PROJ-10",
+  "commentId": "456",
+  "title": "...",
+  "description": "...",
+  "content": "...",
+  "author": "...",
+  "date": "..."
+}
+```
+
+Exits non-zero with a stderr message if the URL is not a recognised Backlog/Jira pattern or fetching fails.
+
 ---
 
 ### `aiflow task`
@@ -378,6 +424,56 @@ Then run `aiflow update` or `aiflow sync-skills` to apply.
 
 ---
 
+## Release Notes
+
+> Summary of major changes per version. See full details in [CHANGELOG.md](docs/common/CHANGELOG.md).
+
+### v0.1.0 — 2026-05-28
+- Multi-target `ak use` — load multiple tickets/files in a single call (primary + supplementary).
+- Auto link resolution — auto-fetch Backlog/Jira URLs found in the ticket description (capped at 5 links).
+- Comment-aware resolution — `#comment-456` links fetch only that specific comment.
+- New `ak fetch-links <url>` command for AI runtime use.
+- SessionStart hook renders the `supplementaryContext[]` block into the prompt.
+- Added Jest test suite (20+ unit tests for `link-resolver`).
+
+### v0.0.9 — 2026-05-25
+- New `figma-desktop` adapter (uses `@figma/mcp-server`, no token required).
+- `figma-to-component` skill supports Next.js App Router and Angular.
+- `ak gate N start|approved` auto-syncs `task-state.json`.
+- New `project-conventions.md` — enforces Gate 2 plan output at `plan/[ticket-id]/plan.md`.
+- WSL clipboard support in `ak prompt`.
+- Fixes: wrong Figma tool names, PAT verify using wrong auth header, `currentGate` not advancing.
+
+### v0.0.8 — 2026-05-14
+- New CLI alias `ak` (short for `aiflow`) + aliases for every sub-command.
+- Flexible comment loading options: `--coms`, `--cid`, `--clast`, `--cfrom`, `--cto`.
+- Fixed Backlog comment pagination (switched to `minId`-based).
+- v0.0.8-beta.1: Actually removed auto-commit + added PreToolUse hook blocking `git commit/add/push`.
+
+### v0.0.7 — 2026-05-08
+- `aiflow use --file` auto-generates `taskId` from filename + interactive `taskType` prompt.
+- Auto-generates `task-summary.md` at each gate transition.
+- Added NestJS and PHP Plain framework support.
+- New `aiflow sync-skills` command.
+- Marker-based update for `CLAUDE.md`, `GEMINI.md`, `.cursorrules`.
+- Auto-manages `.gitignore` for generated files.
+
+### v0.0.6 — 2026-04-29
+- **Fast Mode** enabled by default (reduced Q&A, single-session implementation).
+- New `aiflow task` command group (status/list/pause/switch/resume).
+- Integrated RTK token compression (60–90% savings).
+- `--file` loader supports plain-text input.
+
+### v0.0.5 — 2026-04-23
+- Telemetry MVP — opt-in tracking, HMAC-SHA256 signed payload, no prompt content logged.
+- New `aiflow gate <n> <action>` command for AI to call automatically on gate transitions.
+- Safe overwrite flow in `aiflow init` (backs up existing files before overwrite).
+
+### v0.0.1 — 2026-04-13
+- Initial release: `aiflow` CLI, 5-Gate workflow, 7 custom skills, support for Claude Code / Gemini / Copilot.
+
+---
+
 ## Troubleshooting
 
 **`aiflow` not found:**