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

package/README.md

@@ -1,497 +1,497 @@
-# AI Flow Kit
-
-**All-in-one package for software development teams using Claude AI.**
-
-Developers only need a single command to load ticket context → AI automatically understands the requirements, chooses the workflow, and follows team rules — no long prompts needed, no need to know the templates.
-
----
-
-## Problems Solved
-
-| Problem | Solution |
-|--------|-----------|
-| Multi-step, complex installation | `aiflow init` — 1 command to set up everything |
-| Need long prompts for AI to understand | `aiflow use PROJ-33` — AI automatically reads from ticket |
-| Too many templates, not sure which to use | AI auto-detects task type and selects the appropriate skill |
-| New plugins (superpowers, MCP...) require manual setup | Package auto-sets up hooks, skills, and MCP on init |
-| Missing investigation / bug reproduction flow | Skill `investigate-bug` (inherits systematic-debugging) |
-| Missing impact analysis flow | Skill `impact-analysis` |
-| Hard to resume tasks | **State Resumption**: Unified `plan/` docs, `task-summary.md` progress tracking, and intelligent session continuity (automatic Gate 3 resumption). |
-
-## Documentation & Guides
-
-> [!TIP]
-> After running `aiflow init`, documentation files are automatically copied to `.aiflow/docs/` in your project for easy access.
-
-- **[Quick Start Guide](https://github.com/example/ai-flow-kit/blob/main/docs/common/QUICK_START.md)** — Step-by-step instructions for developers.
-- **[Full Workflow (5 Gates)](https://github.com/example/ai-flow-kit/blob/main/docs/common/AIFLOW.md)** — In-depth look at the Gate process.
-- **[Troubleshooting](https://github.com/example/ai-flow-kit/blob/main/docs/common/troubleshooting.md)** — Common issues and fixes.
-- **[Integration Guide](https://github.com/example/ai-flow-kit/blob/main/docs/common/ai-integration.md)** — Advanced tool setup (Claude, Cursor, Gemini).
-- **[Changelog](https://github.com/example/ai-flow-kit/blob/main/docs/common/CHANGELOG.md)** — Version history and release notes.
-
----
-
-## Overview Flow
-
-```
-PM writes ticket on Backlog/Jira
-        │
-        ▼
-⛩️ GATE 1 — AI Analyze Requirement          [AI + DEV]
-  aiflow use PROJ-33   →   claude
-  AI loads ticket + reads source code
-  AI asks clarifying questions (max 1 in Fast mode)
-  AI outputs: plan/PROJ-33/requirement.md (Lite in Fast mode)
-  DEV reviews → "APPROVED"
-        │ APPROVED
-        ▼
-⛩️ GATE 2 — Implementation Plan             [AI + DEV]
-  AI creates detailed coding plan (TDD steps)
-  DEV reviews → "APPROVED"
-        │ APPROVED
-        ▼
-⛩️ GATE 3 — Code Generation (TDD)           [AI]
-  AI writes tests first → implement → tests pass
-  Verify implementation works
-        │ Code done
-        ▼
-⛩️ GATE 4 — AI Self-Review                  [AI + DEV]
-  AI runs: verification + impact-analysis + checklist
-  AI generates: plan/PROJ-33/task-summary.md
-  DEV reviews → "APPROVED" or "BUG: [description]"
-        │ APPROVED
-        ▼
-⛩️ GATE 5 — Peer Review & PR                [DEV + Peer]
-  Create Pull Request → peer review → merge
-        │
-        ▼
-       DONE
-```
-
----
-
-## Installation
-
-```bash
-# Stable version
-npm install -g @relipa/ai-flow-kit
-
-# Beta version (recommend for newest features)
-npm install -g @relipa/ai-flow-kit@beta
-
-# Uninstall
-npm uninstall -g @relipa/ai-flow-kit
-```
-
----
-
-## Commands
-
-| Command | Description |
-|---------|-------------|
-| `aiflow init` | Setup framework, adapters, and multi-AI rules. |
-| `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`). |
-| `aiflow sync-skills` | Manually synchronize AI Instruction files with local custom skills. |
-| `aiflow telemetry` | Manage telemetry tracking (enable/disable/status). |
-| `aiflow guide` | View integrated multi-AI integration guide. |
-
-### `aiflow init`
-
-Initial setup for the project. Run once per project.
-
-```bash
-# Single framework + adapter
-aiflow init --framework spring-boot --adapter backlog
-
-# Enable token savings tools
-aiflow init --with-rtk                     # RTK: compress bash outputs (60–90% reduction)
-# aiflow init --with-gitnexus               # GitNexus: code intelligence (waits for index)
-# aiflow init --with-gitnexus --no-wait     # GitNexus: index in background
-
-# Multiple frameworks and adapters
-aiflow init --framework spring-boot,reactjs --adapter backlog,jira
-```
-
-**What gets automatically set up:**
-- `.claude/skills/` — superpowers skills + team custom skills
-- `.claude/hooks/session-start.js` — SessionStart hook
-- `.claude/settings.json` — hook configuration
-- `.rules/` — team coding rules (based on framework language)
-- `CLAUDE.md` — framework-specific AI prompt
-- `.mcp.json` + Claude Desktop config — MCP adapter
-- `.aiflow/credentials.json` — save API credentials
-
-**Supported Frameworks:** `spring-boot`, `laravel`, `php`, `nestjs`, `reactjs`, `nextjs`, `vue-nuxt`, `nodejs-express`, `python`, `python-django`, `python-fastapi`
-
-**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`
-
-Synchronize AI instruction files (`CLAUDE.md`, `GEMINI.md`, etc.) and Skills without upgrading the package version. 
-
-```bash
-aiflow sync-skills
-```
-
-**Features:**
-- Intelligent marker-based updates (`<!-- aiflow-kit-start -->`)
-- Confirmation prompts before overwriting custom rules
-- English notifications and status reports
-
----
-
-### `aiflow use <ticket...>`
-
-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
-# Single target (backward compatible)
-aiflow use PROJ-33
-aiflow use https://mycompany.backlog.com/view/PROJ-33
-
-# 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
-
-# Backlog / Jira ticket
-aiflow use PROJ-123
-
-# Comments
-aiflow use PROJ-33 --with-comments
-aiflow use PROJ-33 --comments-last 5
-aiflow use PROJ-33 --comments-from 3
-
-# Manual input
-aiflow use --manual
-
-# Load from local file (JSON or plain text)
-aiflow use --file task.md      # Auto-generates taskId from filename & prompts for taskType
-
-# Modes (Fast is default)
-aiflow use PROJ-33          # Fast Mode: skip Q&A, target < 5 min
-aiflow use PROJ-33 --full   # Full Mode: deep analysis with Q&A
-
-# Save with custom name
-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`
-
-Manage multiple tasks — pause a task, switch to another, and resume later while keeping full progress.
-
-```bash
-aiflow task status                  # show active task and pending tasks
-aiflow task list                    # list all saved tasks
-aiflow task pause                   # pause current task (saves context + gate progress)
-aiflow task pause --note "waiting for API spec"   # pause with a note
-aiflow task switch PROJ-99          # pause current + switch to another task
-aiflow task resume PROJ-33          # resume a paused task (restores context + gate state)
-aiflow task reset  PROJ-33          # reset to Gate 1 (keeps ticket context, clears progress)
-aiflow task remove PROJ-33          # permanently delete all saved data for the task
-aiflow task next                    # approve current gate + prepare for fresh session
-aiflow task next --ticket PROJ-33   # same, but specify ticket explicitly
-```
-
-**Use case — switching tasks mid-flow:**
-
-```bash
-# Working on PROJ-33 at Gate 2...
-aiflow task pause               # pauses and saves PROJ-33 progress
-
-aiflow use PROJ-99              # loads urgent task (auto-pauses current)
-claude                          # AI starts Gate 1 for PROJ-99
-
-# Done with PROJ-99, resuming PROJ-33
-aiflow task resume PROJ-33      # restores context
-claude                          # AI resumes from Gate 2 automatically
-```
-
-Task state (context + gate progress) is saved in `.aiflow/tasks/<taskId>/`.
-
----
-
-### `aiflow doctor`
-
-Check if the setup is complete.
-
-```bash
-aiflow doctor
-```
-
-```
-✓ .claude/skills exists (42 skills)
-✓ .rules exists
-✓ CLAUDE.md exists
-✓ SessionStart hook configured
-✓ Version tracking active (v1.0.0)
-✨ Everything looks healthy!
-```
-
----
-
-### `aiflow update`
-
-Update skills, rules, and templates to the latest version.
-
-```bash
-aiflow update
-```
-
----
-
-### `aiflow validate <file>`
-
-Validate code output against team rules.
-
-```bash
-aiflow validate src/Payment.java --ruleset strict
-```
-
----
-
-### `aiflow memory`
-
-Save/search team knowledge.
-
-```bash
-aiflow memory save "payment-flow" "Payment flow description..."
-aiflow memory search "payment"
-aiflow memory list
-```
-
----
-
-## Available Skills
-
-### Custom skills (team-specific)
-
-| Skill | Trigger | Description |
-|-------|---------|-------|
-| `investigate-bug` | "fix bug", "error", "crash" | Investigate bugs via data flow, inherits `systematic-debugging` |
-| `impact-analysis` | "impact scope", "breaking change" | Analyze the impact when changing code |
-| `generate-spec` | "new feature", "spec", "design" | Write technical specs, integrates `brainstorming` |
-| `report-customer` | "customer report", "incident" | Write incident reports for Customer Service |
-| `figma-to-component` | "figma", "design", "generate component" | Read Figma design → generate React/Next.js App Router/Vue/Angular component. [Workflow guide](docs/common/workflows/figma.md) |
-
-### Superpowers skills (upstream, inherited from obra/superpowers)
-
-| Skill | Description |
-|-------|-------|
-| `systematic-debugging` | Core debugging methodology — NO FIX WITHOUT ROOT CAUSE |
-| `brainstorming` | Explore requirements before coding |
-| `writing-plans` | Create bite-sized implementation plans |
-| `executing-plans` | Execute plans with review checkpoints |
-| `test-driven-development` | RED→GREEN→REFACTOR |
-| `subagent-driven-development` | Dispatch subagents for independent tasks |
-| `requesting-code-review` | Review code before merging |
-| `verification-before-completion` | Verify before claiming done |
-| `using-git-worktrees` | Isolated workspace for feature work |
-| `finishing-a-development-branch` | Complete branch and merge options |
-
----
-
-## Framework Templates
-
-| Framework | Language | Rules applied |
-|-----------|---------|--------------|
-| `spring-boot` | Java 17+ | `rules/java/` |
-| `laravel` | PHP 8.1+ | `rules/php/` |
-| `php` | PHP 8.1+ (no framework) | `rules/php/` |
-| `nestjs` | TypeScript | `rules/javascript/` |
-| `reactjs` | TypeScript | `rules/javascript/` |
-| `nextjs` | TypeScript | `rules/javascript/` |
-| `vue-nuxt` | TypeScript | `rules/javascript/` |
-| `nodejs-express` | JavaScript/TypeScript | `rules/javascript/` |
-| `python` | Python (no framework) | — |
-| `python-django` | Python | — |
-| `python-fastapi` | Python | — |
-
----
-
-## Project Structure
-
-```
-ai-flow-kit/
-├── README.md                        # Main documentation
-├── bin/aiflow.js                    # CLI entry
-├── docs/
-│   ├── common/                      # Published with package
-│   │   ├── QUICK_START.md           # Quick start guide
-│   │   ├── AIFLOW.md                # Workflow (5 Gates) detail
-│   │   ├── CHANGELOG.md             # Version history
-│   │   ├── cli-reference.md         # Full CLI reference
-│   │   └── workflows/               # Per-task workflow guides
-│   └── project/                     # Project template files
-│       └── ARCHITECTURE.md          # Architecture doc template
-├── scripts/
-│   ├── init.js                      # Project initialization
-│   ├── update.js                    # Version management
-│   ├── doctor.js                    # Health check
-│   ├── use.js                       # Context loading (Backlog/Jira)
-│   ├── config.js                    # Config system
-│   ├── detect.js                    # Task type detection
-│   ├── validate.js                  # Code validation
-│   ├── memory.js                    # Knowledge management
-│   └── hooks/session-start.js       # SessionStart hook (Node.js)
-├── custom/
-│   ├── skills/                      # Team-specific AI skills
-│   ├── rules/java/                  # Java/Spring Boot rules
-│   ├── rules/php/                   # PHP/Laravel rules
-│   ├── rules/javascript/            # JS/TS rules
-│   ├── templates/                   # Framework tool templates
-│   ├── prompts/                     # Task prompt templates
-│   └── mcp-presets/                 # Backlog/Jira/Sheets config
-└── upstream/                        # obra/superpowers (inherited)
-```
-
----
-
-## Adding new frameworks / adapters
-
-**New Framework:** create `custom/templates/<name>.md` + `custom/rules/<lang>/`
-
-**New Adapter:** create `custom/mcp-presets/<name>.json`
-
-**Custom skill:** create `custom/skills/<name>/SKILL.md`
-
-Then run `aiflow update` or `aiflow sync-skills` to apply.
-
----
-
-## Usage Environments
-
-| Environment | Experience | Notes |
-|-----------|------------|---------|
-| Claude Code CLI (`claude`) | ⭐⭐⭐⭐⭐ | Full auto — skills, hook, automatically loaded context |
-| Claude Extension (VS Code) | ⭐⭐⭐ | `aiflow prompt <type>` → copy paste |
-| Antigravity / Cursor | ⭐⭐⭐ | `aiflow prompt <type>` → copy paste |
-
----
-
-## 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:**
-```bash
-npm install -g @relipa/ai-flow-kit
-```
-
-**Backlog load fails:**
-```bash
-aiflow doctor
-# Re-setup credentials
-aiflow init --adapter backlog
-```
-
-**Skills not loading in Claude:**
-```bash
-# Ensure init was run outside Claude terminal (session-start hook needs restart)
-aiflow doctor
-```
-
-See more: [docs/common/troubleshooting.md](./docs/common/troubleshooting.md)
+# AI Flow Kit
+
+**All-in-one package for software development teams using Claude AI.**
+
+Developers only need a single command to load ticket context → AI automatically understands the requirements, chooses the workflow, and follows team rules — no long prompts needed, no need to know the templates.
+
+---
+
+## Problems Solved
+
+| Problem | Solution |
+|--------|-----------|
+| Multi-step, complex installation | `aiflow init` — 1 command to set up everything |
+| Need long prompts for AI to understand | `aiflow use PROJ-33` — AI automatically reads from ticket |
+| Too many templates, not sure which to use | AI auto-detects task type and selects the appropriate skill |
+| New plugins (superpowers, MCP...) require manual setup | Package auto-sets up hooks, skills, and MCP on init |
+| Missing investigation / bug reproduction flow | Skill `investigate-bug` (inherits systematic-debugging) |
+| Missing impact analysis flow | Skill `impact-analysis` |
+| Hard to resume tasks | **State Resumption**: Unified `plan/` docs, `task-summary.md` progress tracking, and intelligent session continuity (automatic Gate 3 resumption). |
+
+## Documentation & Guides
+
+> [!TIP]
+> After running `aiflow init`, documentation files are automatically copied to `.aiflow/docs/` in your project for easy access.
+
+- **[Quick Start Guide](https://github.com/example/ai-flow-kit/blob/main/docs/common/QUICK_START.md)** — Step-by-step instructions for developers.
+- **[Full Workflow (5 Gates)](https://github.com/example/ai-flow-kit/blob/main/docs/common/AIFLOW.md)** — In-depth look at the Gate process.
+- **[Troubleshooting](https://github.com/example/ai-flow-kit/blob/main/docs/common/troubleshooting.md)** — Common issues and fixes.
+- **[Integration Guide](https://github.com/example/ai-flow-kit/blob/main/docs/common/ai-integration.md)** — Advanced tool setup (Claude, Cursor, Gemini).
+- **[Changelog](https://github.com/example/ai-flow-kit/blob/main/docs/common/CHANGELOG.md)** — Version history and release notes.
+
+---
+
+## Overview Flow
+
+```
+PM writes ticket on Backlog/Jira
+        │
+        ▼
+⛩️ GATE 1 — AI Analyze Requirement          [AI + DEV]
+  aiflow use PROJ-33   →   claude
+  AI loads ticket + reads source code
+  AI asks clarifying questions (max 1 in Fast mode)
+  AI outputs: plan/PROJ-33/requirement.md (Lite in Fast mode)
+  DEV reviews → "APPROVED"
+        │ APPROVED
+        ▼
+⛩️ GATE 2 — Implementation Plan             [AI + DEV]
+  AI creates detailed coding plan (TDD steps)
+  DEV reviews → "APPROVED"
+        │ APPROVED
+        ▼
+⛩️ GATE 3 — Code Generation (TDD)           [AI]
+  AI writes tests first → implement → tests pass
+  Verify implementation works
+        │ Code done
+        ▼
+⛩️ GATE 4 — AI Self-Review                  [AI + DEV]
+  AI runs: verification + impact-analysis + checklist
+  AI generates: plan/PROJ-33/task-summary.md
+  DEV reviews → "APPROVED" or "BUG: [description]"
+        │ APPROVED
+        ▼
+⛩️ GATE 5 — Peer Review & PR                [DEV + Peer]
+  Create Pull Request → peer review → merge
+        │
+        ▼
+       DONE
+```
+
+---
+
+## Installation
+
+```bash
+# Stable version
+npm install -g @relipa/ai-flow-kit
+
+# Beta version (recommend for newest features)
+npm install -g @relipa/ai-flow-kit@beta
+
+# Uninstall
+npm uninstall -g @relipa/ai-flow-kit
+```
+
+---
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `aiflow init` | Setup framework, adapters, and multi-AI rules. |
+| `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`). |
+| `aiflow sync-skills` | Manually synchronize AI Instruction files with local custom skills. |
+| `aiflow telemetry` | Manage telemetry tracking (enable/disable/status). |
+| `aiflow guide` | View integrated multi-AI integration guide. |
+
+### `aiflow init`
+
+Initial setup for the project. Run once per project.
+
+```bash
+# Single framework + adapter
+aiflow init --framework spring-boot --adapter backlog
+
+# Enable token savings tools
+aiflow init --with-rtk                     # RTK: compress bash outputs (60–90% reduction)
+# aiflow init --with-gitnexus               # GitNexus: code intelligence (waits for index)
+# aiflow init --with-gitnexus --no-wait     # GitNexus: index in background
+
+# Multiple frameworks and adapters
+aiflow init --framework spring-boot,reactjs --adapter backlog,jira
+```
+
+**What gets automatically set up:**
+- `.claude/skills/` — superpowers skills + team custom skills
+- `.claude/hooks/session-start.js` — SessionStart hook
+- `.claude/settings.json` — hook configuration
+- `.rules/` — team coding rules (based on framework language)
+- `CLAUDE.md` — framework-specific AI prompt
+- `.mcp.json` + Claude Desktop config — MCP adapter
+- `.aiflow/credentials.json` — save API credentials
+
+**Supported Frameworks:** `spring-boot`, `laravel`, `php`, `nestjs`, `reactjs`, `nextjs`, `vue-nuxt`, `nodejs-express`, `python`, `python-django`, `python-fastapi`
+
+**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`
+
+Synchronize AI instruction files (`CLAUDE.md`, `GEMINI.md`, etc.) and Skills without upgrading the package version. 
+
+```bash
+aiflow sync-skills
+```
+
+**Features:**
+- Intelligent marker-based updates (`<!-- aiflow-kit-start -->`)
+- Confirmation prompts before overwriting custom rules
+- English notifications and status reports
+
+---
+
+### `aiflow use <ticket...>`
+
+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
+# Single target (backward compatible)
+aiflow use PROJ-33
+aiflow use https://mycompany.backlog.com/view/PROJ-33
+
+# 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
+
+# Backlog / Jira ticket
+aiflow use PROJ-123
+
+# Comments
+aiflow use PROJ-33 --with-comments
+aiflow use PROJ-33 --comments-last 5
+aiflow use PROJ-33 --comments-from 3
+
+# Manual input
+aiflow use --manual
+
+# Load from local file (JSON or plain text)
+aiflow use --file task.md      # Auto-generates taskId from filename & prompts for taskType
+
+# Modes (Fast is default)
+aiflow use PROJ-33          # Fast Mode: skip Q&A, target < 5 min
+aiflow use PROJ-33 --full   # Full Mode: deep analysis with Q&A
+
+# Save with custom name
+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`
+
+Manage multiple tasks — pause a task, switch to another, and resume later while keeping full progress.
+
+```bash
+aiflow task status                  # show active task and pending tasks
+aiflow task list                    # list all saved tasks
+aiflow task pause                   # pause current task (saves context + gate progress)
+aiflow task pause --note "waiting for API spec"   # pause with a note
+aiflow task switch PROJ-99          # pause current + switch to another task
+aiflow task resume PROJ-33          # resume a paused task (restores context + gate state)
+aiflow task reset  PROJ-33          # reset to Gate 1 (keeps ticket context, clears progress)
+aiflow task remove PROJ-33          # permanently delete all saved data for the task
+aiflow task next                    # approve current gate + prepare for fresh session
+aiflow task next --ticket PROJ-33   # same, but specify ticket explicitly
+```
+
+**Use case — switching tasks mid-flow:**
+
+```bash
+# Working on PROJ-33 at Gate 2...
+aiflow task pause               # pauses and saves PROJ-33 progress
+
+aiflow use PROJ-99              # loads urgent task (auto-pauses current)
+claude                          # AI starts Gate 1 for PROJ-99
+
+# Done with PROJ-99, resuming PROJ-33
+aiflow task resume PROJ-33      # restores context
+claude                          # AI resumes from Gate 2 automatically
+```
+
+Task state (context + gate progress) is saved in `.aiflow/tasks/<taskId>/`.
+
+---
+
+### `aiflow doctor`
+
+Check if the setup is complete.
+
+```bash
+aiflow doctor
+```
+
+```
+✓ .claude/skills exists (42 skills)
+✓ .rules exists
+✓ CLAUDE.md exists
+✓ SessionStart hook configured
+✓ Version tracking active (v1.0.0)
+✨ Everything looks healthy!
+```
+
+---
+
+### `aiflow update`
+
+Update skills, rules, and templates to the latest version.
+
+```bash
+aiflow update
+```
+
+---
+
+### `aiflow validate <file>`
+
+Validate code output against team rules.
+
+```bash
+aiflow validate src/Payment.java --ruleset strict
+```
+
+---
+
+### `aiflow memory`
+
+Save/search team knowledge.
+
+```bash
+aiflow memory save "payment-flow" "Payment flow description..."
+aiflow memory search "payment"
+aiflow memory list
+```
+
+---
+
+## Available Skills
+
+### Custom skills (team-specific)
+
+| Skill | Trigger | Description |
+|-------|---------|-------|
+| `investigate-bug` | "fix bug", "error", "crash" | Investigate bugs via data flow, inherits `systematic-debugging` |
+| `impact-analysis` | "impact scope", "breaking change" | Analyze the impact when changing code |
+| `generate-spec` | "new feature", "spec", "design" | Write technical specs, integrates `brainstorming` |
+| `report-customer` | "customer report", "incident" | Write incident reports for Customer Service |
+| `figma-to-component` | "figma", "design", "generate component" | Read Figma design → generate React/Next.js App Router/Vue/Angular component. [Workflow guide](docs/common/workflows/figma.md) |
+
+### Superpowers skills (upstream, inherited from obra/superpowers)
+
+| Skill | Description |
+|-------|-------|
+| `systematic-debugging` | Core debugging methodology — NO FIX WITHOUT ROOT CAUSE |
+| `brainstorming` | Explore requirements before coding |
+| `writing-plans` | Create bite-sized implementation plans |
+| `executing-plans` | Execute plans with review checkpoints |
+| `test-driven-development` | RED→GREEN→REFACTOR |
+| `subagent-driven-development` | Dispatch subagents for independent tasks |
+| `requesting-code-review` | Review code before merging |
+| `verification-before-completion` | Verify before claiming done |
+| `using-git-worktrees` | Isolated workspace for feature work |
+| `finishing-a-development-branch` | Complete branch and merge options |
+
+---
+
+## Framework Templates
+
+| Framework | Language | Rules applied |
+|-----------|---------|--------------|
+| `spring-boot` | Java 17+ | `rules/java/` |
+| `laravel` | PHP 8.1+ | `rules/php/` |
+| `php` | PHP 8.1+ (no framework) | `rules/php/` |
+| `nestjs` | TypeScript | `rules/javascript/` |
+| `reactjs` | TypeScript | `rules/javascript/` |
+| `nextjs` | TypeScript | `rules/javascript/` |
+| `vue-nuxt` | TypeScript | `rules/javascript/` |
+| `nodejs-express` | JavaScript/TypeScript | `rules/javascript/` |
+| `python` | Python (no framework) | — |
+| `python-django` | Python | — |
+| `python-fastapi` | Python | — |
+
+---
+
+## Project Structure
+
+```
+ai-flow-kit/
+├── README.md                        # Main documentation
+├── bin/aiflow.js                    # CLI entry
+├── docs/
+│   ├── common/                      # Published with package
+│   │   ├── QUICK_START.md           # Quick start guide
+│   │   ├── AIFLOW.md                # Workflow (5 Gates) detail
+│   │   ├── CHANGELOG.md             # Version history
+│   │   ├── cli-reference.md         # Full CLI reference
+│   │   └── workflows/               # Per-task workflow guides
+│   └── project/                     # Project template files
+│       └── ARCHITECTURE.md          # Architecture doc template
+├── scripts/
+│   ├── init.js                      # Project initialization
+│   ├── update.js                    # Version management
+│   ├── doctor.js                    # Health check
+│   ├── use.js                       # Context loading (Backlog/Jira)
+│   ├── config.js                    # Config system
+│   ├── detect.js                    # Task type detection
+│   ├── validate.js                  # Code validation
+│   ├── memory.js                    # Knowledge management
+│   └── hooks/session-start.js       # SessionStart hook (Node.js)
+├── custom/
+│   ├── skills/                      # Team-specific AI skills
+│   ├── rules/java/                  # Java/Spring Boot rules
+│   ├── rules/php/                   # PHP/Laravel rules
+│   ├── rules/javascript/            # JS/TS rules
+│   ├── templates/                   # Framework tool templates
+│   ├── prompts/                     # Task prompt templates
+│   └── mcp-presets/                 # Backlog/Jira/Sheets config
+└── upstream/                        # obra/superpowers (inherited)
+```
+
+---
+
+## Adding new frameworks / adapters
+
+**New Framework:** create `custom/templates/<name>.md` + `custom/rules/<lang>/`
+
+**New Adapter:** create `custom/mcp-presets/<name>.json`
+
+**Custom skill:** create `custom/skills/<name>/SKILL.md`
+
+Then run `aiflow update` or `aiflow sync-skills` to apply.
+
+---
+
+## Usage Environments
+
+| Environment | Experience | Notes |
+|-----------|------------|---------|
+| Claude Code CLI (`claude`) | ⭐⭐⭐⭐⭐ | Full auto — skills, hook, automatically loaded context |
+| Claude Extension (VS Code) | ⭐⭐⭐ | `aiflow prompt <type>` → copy paste |
+| Antigravity / Cursor | ⭐⭐⭐ | `aiflow prompt <type>` → copy paste |
+
+---
+
+## 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:**
+```bash
+npm install -g @relipa/ai-flow-kit
+```
+
+**Backlog load fails:**
+```bash
+aiflow doctor
+# Re-setup credentials
+aiflow init --adapter backlog
+```
+
+**Skills not loading in Claude:**
+```bash
+# Ensure init was run outside Claude terminal (session-start hook needs restart)
+aiflow doctor
+```
+
+See more: [docs/common/troubleshooting.md](./docs/common/troubleshooting.md)