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

package/README.md

@@ -126,7 +126,7 @@ aiflow init --framework spring-boot,reactjs --adapter backlog,jira
 
 **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`
+**Supported Adapters:** `backlog`, `jira`, `google-sheets`, `figma`, `figma-desktop`
 
 ---
 
@@ -281,7 +281,7 @@ aiflow memory list
 | `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/Vue component |
+| `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)
 

package/bin/aiflow.js

@@ -18,6 +18,7 @@ const telemetryCommand= require('../scripts/telemetry/cli');
 const taskCommand     = require('../scripts/task');
 const checkpointCommand = require('../scripts/checkpoint');
 const { record }      = require('../scripts/telemetry/record');
+const { updateTaskGateState } = require('../scripts/task');
 
 // ── DEPRECATION WARNING ───────────────────────────────────────
 if (!process.env.AIFLOW_IS_AK) {
@@ -42,7 +43,30 @@ program
     const args = process.argv.slice(2);
     let cmd = 'help';
     if (args.length > 0) {
-        const first = args[0];
+        let first = args[0];
+
+        // 1. Phân giải alias cho root commands
+        const aliases = {
+            'i': 'init',
+            'u': 'use',
+            'p': 'prompt',
+            'd': 'detect',
+            't': 'task',
+            'ctx': 'context',
+            'cp': 'checkpoint',
+            'vl': 'validate',
+            'mem': 'memory',
+            'g': 'guide',
+            'rm': 'remove',
+            'up': 'update',
+            'sync': 'sync-skills',
+            'dr': 'doctor',
+            'tel': 'telemetry'
+        };
+        if (aliases[first]) {
+            first = aliases[first];
+        }
+
         if (['-V', '-v', '--version'].includes(first)) {
             cmd = 'version';
         } else if (['-h', '--help'].includes(first)) {
@@ -52,7 +76,42 @@ program
             if (args.includes('--help') || args.includes('-h')) cmd = 'help';
         } else if (first === 'memory') {
             const sec = args[1];
-            cmd = (sec && !sec.startsWith('-')) ? `memory.${sec}` : 'memory';
+            // Phân giải alias cho memory subcommands
+            let sub = sec;
+            if (sec && !sec.startsWith('-')) {
+                const memAliases = {
+                    's': 'save',
+                    'g': 'get',
+                    'ls': 'list',
+                    'sr': 'search',
+                    'd': 'delete',
+                    'cl': 'clear'
+                };
+                if (memAliases[sec]) sub = memAliases[sec];
+                cmd = `memory.${sub}`;
+            } else {
+                cmd = 'memory';
+            }
+        } else if (first === 'task') {
+            const sec = args[1];
+            // Phân giải alias subcommand của task
+            let sub = sec;
+            if (sec && !sec.startsWith('-')) {
+                const subAliases = {
+                    'st': 'status',
+                    'ls': 'list',
+                    'p': 'pause',
+                    'sw': 'switch',
+                    'r': 'resume',
+                    'rst': 'reset',
+                    'rm': 'remove',
+                    'n': 'next'
+                };
+                if (subAliases[sec]) sub = subAliases[sec];
+                cmd = `task.${sub}`;
+            } else {
+                cmd = 'task';
+            }
         } else {
             cmd = first;
             if (args.includes('--help') || args.includes('-h')) {
@@ -88,7 +147,6 @@ program
             ? options.env.split(',').map(s => s.trim()).filter(Boolean)
             : Object.keys(require('../scripts/init').AI_TOOL_FILES || {}).filter(t => t !== 'generic');
 
-        record('command.invoked', { command: 'init' });
         initCommand(options);
     });
 
@@ -109,7 +167,6 @@ program
     .option('-F, --fast', 'fast mode: minimal Q&A, concise requirement doc (Default)')
     .option('-U, --full', 'full mode: force complete analysis with Q&A (default)')
     .action((target, options) => {
-        record('command.invoked', { command: 'use' });
         useCommand(target, options);
     });
 
@@ -123,7 +180,6 @@ program
     .option('-L, --lang <lang>', 'language: english (default) or vietnamese')
     .option('-d, --detail <level>', 'detail level: minimal | standard (default) | comprehensive')
     .action((type, options) => {
-        record('command.invoked', { command: 'prompt' });
         promptCommand(type, options);
     });
 
@@ -135,7 +191,6 @@ program
     .option('-v, --verbose', 'show detection details')
     .option('-t, --threshold <number>', 'confidence threshold (0-100)')
     .action((description, options) => {
-        record('command.invoked', { command: 'detect' });
         const detector = new TaskDetector();
         const threshold = options.threshold ? parseInt(options.threshold) / 100 : 0.8;
         const result = detector.detect(description, threshold);
@@ -150,44 +205,44 @@ taskCmd
     .command('status')
     .alias('st')
     .description('Show active task and pending tasks')
-    .action(() => { record('command.invoked', { command: 'task.status' }); taskCommand('status'); });
+    .action(() => { taskCommand('status'); });
 
 taskCmd
     .command('list')
     .alias('ls')
     .description('List all saved tasks')
-    .action(() => { record('command.invoked', { command: 'task.list' }); taskCommand('list'); });
+    .action(() => { taskCommand('list'); });
 
 taskCmd
     .command('pause')
     .alias('p')
     .description('Pause current task and save progress')
     .option('-n, --note <text>', 'note about why you are pausing')
-    .action((opts) => { record('command.invoked', { command: 'task.pause' }); taskCommand('pause', { note: opts.note }); });
+    .action((opts) => { taskCommand('pause', { note: opts.note }); });
 
 taskCmd
     .command('switch <ticket-id>')
     .alias('sw')
     .description('Pause current task and switch to another')
-    .action((ticketId) => { record('command.invoked', { command: 'task.switch' }); taskCommand('switch', { taskId: ticketId }); });
+    .action((ticketId) => { taskCommand('switch', { taskId: ticketId }); });
 
 taskCmd
     .command('resume <ticket-id>')
     .alias('r')
     .description('Resume a paused task')
-    .action((ticketId) => { record('command.invoked', { command: 'task.resume' }); taskCommand('resume', { taskId: ticketId }); });
+    .action((ticketId) => { taskCommand('resume', { taskId: ticketId }); });
 
 taskCmd
     .command('reset <ticket-id>')
     .alias('rst')
     .description('Reset task to Gate 1 (keeps ticket context, clears gate progress)')
-    .action((ticketId) => { record('command.invoked', { command: 'task.reset' }); taskCommand('reset', { taskId: ticketId }); });
+    .action((ticketId) => { taskCommand('reset', { taskId: ticketId }); });
 
 taskCmd
     .command('remove <ticket-id>')
     .alias('rm')
     .description('Permanently delete all saved data for a task')
-    .action((ticketId) => { record('command.invoked', { command: 'task.remove' }); taskCommand('remove', { taskId: ticketId }); });
+    .action((ticketId) => { taskCommand('remove', { taskId: ticketId }); });
 
 taskCmd
     .command('next')
@@ -195,7 +250,6 @@ taskCmd
     .description('Approve current gate and prepare next session (saves state for resume)')
     .option('-t, --ticket <id>', 'ticket ID (defaults to active task)')
     .action((opts) => {
-        record('command.invoked', { command: 'task.next' });
         taskCommand('next', { taskId: opts.ticket });
     });
 
@@ -210,7 +264,6 @@ program
     .option('--clear', 'clear all saved contexts')
     .option('--show', 'show current context')
     .action((action, options) => {
-        record('command.invoked', { command: 'context' });
         contextCommand(action, options);
     });
 
@@ -224,7 +277,6 @@ program
     .requiredOption('-n, --tokens <n>', 'estimated token count', parseInt)
     .option('-t, --ticket <id>', 'ticket ID (defaults to active task)')
     .action((opts) => {
-        record('command.invoked', { command: 'checkpoint' });
         checkpointCommand({ gate: opts.gate, step: opts.step, tokens: opts.tokens, ticket: opts.ticket });
     });
 
@@ -237,7 +289,6 @@ program
     .option('-v, --verbose', 'detailed report')
     .option('-x, --fix', 'auto-fix trailing whitespace')
     .action((file, options) => {
-        record('command.invoked', { command: 'validate' });
         validateCommand(file, {
             ruleset: options.ruleset,
             verbose: options.verbose,
@@ -253,37 +304,37 @@ memCmd
     .command('save <key> <value>')
     .alias('s')
     .description('Save a memory entry')
-    .action((key, value) => { record('command.invoked', { command: 'memory.save' }); memoryCommand('save', { key, value }); });
+    .action((key, value) => { memoryCommand('save', { key, value }); });
 
 memCmd
     .command('get <key>')
     .alias('g')
     .description('Retrieve a memory entry')
-    .action((key) => { record('command.invoked', { command: 'memory.get' }); memoryCommand('get', { key }); });
+    .action((key) => { memoryCommand('get', { key }); });
 
 memCmd
     .command('list')
     .alias('ls')
     .description('List all memories')
-    .action(() => { record('command.invoked', { command: 'memory.list' }); memoryCommand('list'); });
+    .action(() => { memoryCommand('list'); });
 
 memCmd
     .command('search <query>')
     .alias('sr')
     .description('Search memories by keyword')
-    .action((query) => { record('command.invoked', { command: 'memory.search' }); memoryCommand('search', { query }); });
+    .action((query) => { memoryCommand('search', { query }); });
 
 memCmd
     .command('delete <key>')
     .alias('d')
     .description('Delete a memory entry')
-    .action((key) => { record('command.invoked', { command: 'memory.delete' }); memoryCommand('delete', { key }); });
+    .action((key) => { memoryCommand('delete', { key }); });
 
 memCmd
     .command('clear')
     .alias('cl')
     .description('Clear all memories')
-    .action(() => { record('command.invoked', { command: 'memory.clear' }); memoryCommand('clear'); });
+    .action(() => { memoryCommand('clear'); });
 
 // ── guide ─────────────────────────────────────────────────────
 program
@@ -293,10 +344,27 @@ program
     .option('-f, --flow', 'show architecture & flow diagram only')
     .option('-c, --commands', 'show command reference only')
     .action((options) => {
-        record('command.invoked', { command: 'guide' });
         guideCommand(options);
     });
 
+// ── telemetry feedback helper ─────────────────────────────────
+function showTelResult(result, label) {
+    try {
+        if (!result) return;
+        if (result.ok) {
+            console.log(chalk.green(`  [tel] ✓ ${label} logged`));
+        } else if (result.reason === 'disabled') {
+            console.log(chalk.yellow(`  [tel] ⚠ skipped — telemetry is disabled (run 'aiflow telemetry enable')`));
+        } else if (result.reason === 'opted-out') {
+            console.log(chalk.yellow(`  [tel] ⚠ skipped — repo has .aiflow/no-telemetry opt-out`));
+        } else if (result.reason === 'no-url') {
+            console.log(chalk.yellow(`  [tel] ⚠ skipped — no server URL configured (run 'aiflow telemetry enable')`));
+        } else if (result.error) {
+            console.log(chalk.yellow(`  [tel] ⚠ error logging '${label}': ${result.error}`));
+        }
+    } catch (e) { /* never block main flow */ }
+}
+
 // ── gate (telemetry for gate workflow events) ─────────────────
 program
     .command('gate <number> <action>')
@@ -307,17 +375,26 @@ program
         const gateNum = parseInt(number);
         if (isNaN(gateNum) || gateNum < 1 || gateNum > 5) return;
         if (!['start', 'approved'].includes(action)) return;
-        record(`gate.${action}`, {
+
+        const ticketId = options.ticket || '';
+
+        const telResult = record(`gate.${action}`, {
             gate: gateNum,
-            ticket_id: options.ticket || '',
+            ticket_id: ticketId,
             command: `gate${gateNum}.${action}`,
             ai_tool: options.aiTool || ''
         });
+        showTelResult(telResult, `gate${gateNum}.${action}`);
+
+        // Keep task-state.json currentGate in sync (silent — never blocks the AI)
+        if (ticketId) {
+            updateTaskGateState(ticketId, gateNum, action).catch(() => {});
+        }
 
         if (action === 'approved') {
             console.log(chalk.cyan(`\n  Gate ${gateNum} approved!`));
             console.log(chalk.yellow(`  Pro-Tip: To avoid context pollution, it's recommended to start a fresh chat session.`));
-            console.log(chalk.gray(`  Run: aiflow task next${options.ticket ? ` --ticket ${options.ticket}` : ''} to save progress,`));
+            console.log(chalk.gray(`  Run: aiflow task next${ticketId ? ` --ticket ${ticketId}` : ''} to save progress,`));
             console.log(chalk.gray(`  then open a NEW chatbox and type "continue".\n`));
         }
     });
@@ -330,7 +407,6 @@ program
     .option('--version <ver>', 'remove a specific cached version from .aiflow/versions/')
     .option('-g, --global', 'uninstall the global npm package (removes `aiflow` command)')
     .action((options) => {
-        record('command.invoked', { command: 'remove' });
         removeCommand(options);
     });
 
@@ -341,7 +417,6 @@ program
     .description('Update to latest version')
     .option('-f, --force', 'force update even if already on latest')
     .action((options) => {
-        record('command.invoked', { command: 'update' });
         updateCommand(options);
     });
 
@@ -351,7 +426,6 @@ program
     .alias('sync')
     .description('Manually synchronize AI Instruction files with local custom skills')
     .action(async () => {
-        record('command.invoked', { command: 'sync-skills' });
         const projectDir = process.cwd();
         const { setupFramework, AI_TOOL_FILES, ensureAiflowGitignored } = require('../scripts/init');
         const fs = require('fs-extra');
@@ -384,7 +458,6 @@ program
     .option('-t, --ticket <id>', 'show token breakdown for specific ticket')
     .option('-v, --verbose', 'detailed output')
     .action((opts) => {
-        record('command.invoked', { command: 'doctor' });
         doctorCommand({ ticket: opts.ticket, verbose: opts.verbose });
     });
 
@@ -392,9 +465,11 @@ program
 program
     .command('telemetry [action]')
     .alias('tel')
-    .description('Manage telemetry logging (enable|disable|status)')
-    .action((action) => {
-        telemetryCommand(action || 'status');
+    .description('Manage telemetry logging (enable|disable|status|log)')
+    .option('--event <event>', 'event name (for log action)')
+    .option('--detail <detail>', 'detail string (for log action)')
+    .action((action, options) => {
+        telemetryCommand(action || 'status', options);
     });
 
 program.parse(process.argv);

package/bin/ak.js

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

package/custom/mcp-presets/README.md

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

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

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

package/custom/rules/project-conventions.md

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

package/custom/templates/python.md

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