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

package/bin/aiflow.js

@@ -1,409 +1,475 @@
 #!/usr/bin/env node
-
-const { program } = require('commander');
-const chalk = require('chalk');
-const packageJson = require('../package.json');
-const initCommand     = require('../scripts/init');
-const updateCommand   = require('../scripts/update');
-const doctorCommand   = require('../scripts/doctor');
-const useCommand      = require('../scripts/use');
-const TaskDetector    = require('../scripts/detect');
-const validateCommand = require('../scripts/validate');
-const memoryCommand   = require('../scripts/memory');
-const contextCommand  = require('../scripts/context');
-const promptCommand   = require('../scripts/prompt');
-const removeCommand   = require('../scripts/remove');
-const guideCommand    = require('../scripts/guide');
-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) {
-    console.warn(chalk.yellow('\n⚠ Warning: "aiflow" command is deprecated and will be removed in future versions.'));
-    console.warn(chalk.yellow('Please use the shorter "ak" command instead.\n'));
-}
-
-program
-    .version(packageJson.version)
-    .description('AI Flow Kit CLI - AI-powered development workflows for teams');
-
-// ── GLOBAL TELEMETRY HOOK ────────────────────────────────────
-// We intercept raw argv here so we can catch --version, --help,
-// and invalid commands *before* Commander exits the process.
-// Also alias `-v` to commander's `-V` at the root only — subcommands still
-// keep `-v` as `--verbose`. And alias `--fw` to `--framework`.
-(() => {
-    if (process.argv[2] === '-v') process.argv[2] = '-V';
-    for (let i = 3; i < process.argv.length; i++) {
-        if (process.argv[i] === '--fw') process.argv[i] = '--framework';
-    }
-    const args = process.argv.slice(2);
-    let cmd = 'help';
-    if (args.length > 0) {
-        const first = args[0];
-        if (['-V', '-v', '--version'].includes(first)) {
-            cmd = 'version';
-        } else if (['-h', '--help'].includes(first)) {
-            cmd = 'help';
-        } else if (first.startsWith('-')) {
-            cmd = 'unknown_flag';
-            if (args.includes('--help') || args.includes('-h')) cmd = 'help';
-        } else if (first === 'memory') {
-            const sec = args[1];
-            cmd = (sec && !sec.startsWith('-')) ? `memory.${sec}` : 'memory';
-        } else {
-            cmd = first;
-            if (args.includes('--help') || args.includes('-h')) {
-                cmd = `${first}.help`;
-            }
-        }
-    }
-    // Record everything except telemetry and gate actions (gate records its own rich event)
-    if (cmd !== 'telemetry' && !cmd.startsWith('telemetry.') && cmd !== 'gate') {
-        record('command.invoked', { command: cmd });
-    }
-})();
-
-
-// ── init ──────────────────────────────────────────────────────
-program
-    .command('init')
-    .alias('i')
-    .description('Initialize AI Flow Kit in your project')
-    .option('-f, --framework <types>', 'framework(s), comma-separated (e.g. spring-boot,reactjs)')
-    .option('-a, --adapter <types>', 'adapter(s), comma-separated (e.g. backlog,jira)')
-    .option('-e, --env <types>', 'AI environment(s)/tool(s), comma-separated (e.g. cursor,gemini,copilot)')
-    .option('--with-rtk', 'force enable RTK token compression hook')
-    .option('--no-rtk', 'skip RTK setup even if RTK is detected')
-    .action((options) => {
-        options.frameworks = options.framework
-            ? options.framework.split(',').map(s => s.trim()).filter(Boolean)
-            : [];
-        options.adapters = options.adapter
-            ? options.adapter.split(',').map(s => s.trim()).filter(Boolean)
-            : [];
-        options.aiTools = options.env
-            ? 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);
-    });
-
-// ── use ───────────────────────────────────────────────────────
-program
-    .command('use [target]')
-    .alias('u')
-    .description('Load context from ticket, version, or file')
-    .option('-m, --manual', 'manual context entry')
-    .option('-f, --file <path>', 'load from file')
-    .option('-s, --save <name>', 'save as named context')
-    .option('-c, --coms', 'load all comments (alias for --with-comments)')
-    .option('--with-comments', 'load all comments')
-    .option('--cid <id>', 'load a specific comment by ID')
-    .option('--clast <n>', 'load the last N comments', parseInt)
-    .option('--cfrom <id>', 'load comments from ID N onward', parseInt)
-    .option('--cto <id>', 'load comments up to ID N', parseInt)
-    .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);
-    });
-
-// ── prompt ────────────────────────────────────────────────────
-program
-    .command('prompt [type]')
-    .alias('p')
-    .description('Generate AI prompt with context and rules')
-    .option('-l, --list', 'list available prompt types')
-    .option('-o, --output <file>', 'save to file')
-    .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);
-    });
-
-// ── detect ────────────────────────────────────────────────────
-program
-    .command('detect [description]')
-    .alias('d')
-    .description('Auto-detect task type from description')
-    .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);
-        console.log(chalk.cyan('\nTask Detection Results:\n'));
-        console.log(detector.formatOutput(result, options.verbose));
-    });
-
-// ── task ─────────────────────────────────────────────────────
-const taskCmd = program.command('task').alias('t').description('Manage multiple tasks — pause, switch, resume');
-
-taskCmd
-    .command('status')
-    .alias('st')
-    .description('Show active task and pending tasks')
-    .action(() => { record('command.invoked', { command: 'task.status' }); taskCommand('status'); });
-
-taskCmd
-    .command('list')
-    .alias('ls')
-    .description('List all saved tasks')
-    .action(() => { record('command.invoked', { command: 'task.list' }); 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 }); });
-
-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 }); });
-
-taskCmd
-    .command('resume <ticket-id>')
-    .alias('r')
-    .description('Resume a paused task')
-    .action((ticketId) => { record('command.invoked', { command: 'task.resume' }); 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 }); });
-
-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 }); });
-
-taskCmd
-    .command('next')
-    .alias('n')
-    .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 });
-    });
-
-// ── context ───────────────────────────────────────────────────
-program
-    .command('context [action]')
-    .alias('ctx')
-    .description('Manage task contexts (list|show|save <name>|clear)')
-    .option('-s, --save <name>', 'save current context with name')
-    .option('-l, --load <name>', 'load saved context by name')
-    .option('-d, --delete <name>', 'delete saved context')
-    .option('--clear', 'clear all saved contexts')
-    .option('--show', 'show current context')
-    .action((action, options) => {
-        record('command.invoked', { command: 'context' });
-        contextCommand(action, options);
-    });
-
-// ── checkpoint ────────────────────────────────────────────────
-program
-    .command('checkpoint')
-    .alias('cp')
-    .description('Record token usage checkpoint (called by AI during gate work)')
-    .requiredOption('-g, --gate <n>', 'gate number (1–5)', parseInt)
-    .requiredOption('-s, --step <name>', 'step name (e.g. "tests-written")')
-    .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 });
-    });
-
-// ── validate ──────────────────────────────────────────────────
-program
-    .command('validate <file>')
-    .alias('vl')
-    .description('Validate output against team rules')
-    .option('-r, --ruleset <set>', 'rule set: default | strict | lenient', 'default')
-    .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,
-            fix: options.fix
-        });
-    });
-
-// ── memory ────────────────────────────────────────────────────
-// Sub-commands to avoid the ambiguous "memory <action> --save key" pattern
-const memCmd = program.command('memory').alias('mem').description('Manage team knowledge and memory');
-
-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 }); });
-
-memCmd
-    .command('get <key>')
-    .alias('g')
-    .description('Retrieve a memory entry')
-    .action((key) => { record('command.invoked', { command: 'memory.get' }); memoryCommand('get', { key }); });
-
-memCmd
-    .command('list')
-    .alias('ls')
-    .description('List all memories')
-    .action(() => { record('command.invoked', { command: 'memory.list' }); memoryCommand('list'); });
-
-memCmd
-    .command('search <query>')
-    .alias('sr')
-    .description('Search memories by keyword')
-    .action((query) => { record('command.invoked', { command: 'memory.search' }); 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 }); });
-
-memCmd
-    .command('clear')
-    .alias('cl')
-    .description('Clear all memories')
-    .action(() => { record('command.invoked', { command: 'memory.clear' }); memoryCommand('clear'); });
-
-// ── guide ─────────────────────────────────────────────────────
-program
-    .command('guide')
-    .alias('g')
-    .description('Show quickstart guide, architecture, and command reference')
-    .option('-f, --flow', 'show architecture & flow diagram only')
-    .option('-c, --commands', 'show command reference only')
-    .action((options) => {
-        record('command.invoked', { command: 'guide' });
-        guideCommand(options);
-    });
-
-// ── gate (telemetry for gate workflow events) ─────────────────
-program
-    .command('gate <number> <action>')
-    .description('Log a gate workflow event (start|approved) — called by AI during gate workflow')
-    .option('--ticket <id>', 'ticket ID')
-    .option('--ai-tool <tool>', 'AI tool name')
-    .action((number, action, options) => {
-        const gateNum = parseInt(number);
-        if (isNaN(gateNum) || gateNum < 1 || gateNum > 5) return;
-        if (!['start', 'approved'].includes(action)) return;
-
-        const ticketId = options.ticket || '';
-
-        record(`gate.${action}`, {
-            gate: gateNum,
-            ticket_id: ticketId,
-            command: `gate${gateNum}.${action}`,
-            ai_tool: options.aiTool || ''
-        });
-
-        // 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${ticketId ? ` --ticket ${ticketId}` : ''} to save progress,`));
-            console.log(chalk.gray(`  then open a NEW chatbox and type "continue".\n`));
-        }
-    });
-
-// ── remove ────────────────────────────────────────────────────
-program
-    .command('remove')
-    .alias('rm')
-    .description('Remove ai-flow-kit from project, a cached version, or uninstall globally')
-    .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);
-    });
-
-// ── update ────────────────────────────────────────────────────
-program
-    .command('update')
-    .alias('up')
-    .description('Update to latest version')
-    .option('-f, --force', 'force update even if already on latest')
-    .action((options) => {
-        record('command.invoked', { command: 'update' });
-        updateCommand(options);
-    });
-
-// ── sync-skills ───────────────────────────────────────────────
-program
-    .command('sync-skills')
-    .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');
-        const path = require('path');
-        const chalk = require('chalk');
-
-        const stateFile = path.join(projectDir, '.aiflow', 'state.json');
-        if (!(await fs.pathExists(stateFile))) {
-            console.log(chalk.red('Project is not initialized. Please run `aiflow init` first.'));
-            return;
-        }
-
-        const state = await fs.readJson(stateFile);
-        const frameworks = state.frameworks || [];
-        const selectedTools = state.aiTools || Object.keys(AI_TOOL_FILES);
-
-        console.log(chalk.cyan('⟳ Syncing AI Instruction files...'));
-        for (const fw of frameworks) {
-            await setupFramework(projectDir, fw, frameworks.length > 1, selectedTools);
-        }
-        await ensureAiflowGitignored(projectDir);
-        console.log(chalk.green('✨ Sync completed!'));
-    });
-
-// ── doctor ────────────────────────────────────────────────────
-program
-    .command('doctor')
-    .alias('dr')
-    .description('Health check of AI Flow Kit setup')
-    .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 });
-    });
-
-// ── telemetry ──────────────────────────────────────────────────
-program
-    .command('telemetry [action]')
-    .alias('tel')
-    .description('Manage telemetry logging (enable|disable|status)')
-    .action((action) => {
-        telemetryCommand(action || 'status');
-    });
-
-program.parse(process.argv);
+
+const { program } = require('commander');
+const chalk = require('chalk');
+const packageJson = require('../package.json');
+const initCommand     = require('../scripts/init');
+const updateCommand   = require('../scripts/update');
+const doctorCommand   = require('../scripts/doctor');
+const useCommand      = require('../scripts/use');
+const TaskDetector    = require('../scripts/detect');
+const validateCommand = require('../scripts/validate');
+const memoryCommand   = require('../scripts/memory');
+const contextCommand  = require('../scripts/context');
+const promptCommand   = require('../scripts/prompt');
+const removeCommand   = require('../scripts/remove');
+const guideCommand    = require('../scripts/guide');
+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) {
+    console.warn(chalk.yellow('\n⚠ Warning: "aiflow" command is deprecated and will be removed in future versions.'));
+    console.warn(chalk.yellow('Please use the shorter "ak" command instead.\n'));
+}
+
+program
+    .version(packageJson.version)
+    .description('AI Flow Kit CLI - AI-powered development workflows for teams');
+
+// ── GLOBAL TELEMETRY HOOK ────────────────────────────────────
+// We intercept raw argv here so we can catch --version, --help,
+// and invalid commands *before* Commander exits the process.
+// Also alias `-v` to commander's `-V` at the root only — subcommands still
+// keep `-v` as `--verbose`. And alias `--fw` to `--framework`.
+(() => {
+    if (process.argv[2] === '-v') process.argv[2] = '-V';
+    for (let i = 3; i < process.argv.length; i++) {
+        if (process.argv[i] === '--fw') process.argv[i] = '--framework';
+    }
+    const args = process.argv.slice(2);
+    let cmd = 'help';
+    if (args.length > 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)) {
+            cmd = 'help';
+        } else if (first.startsWith('-')) {
+            cmd = 'unknown_flag';
+            if (args.includes('--help') || args.includes('-h')) cmd = 'help';
+        } else if (first === 'memory') {
+            const sec = args[1];
+            // 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')) {
+                cmd = `${first}.help`;
+            }
+        }
+    }
+    // Record everything except telemetry and gate actions (gate records its own rich event)
+    if (cmd !== 'telemetry' && !cmd.startsWith('telemetry.') && cmd !== 'gate') {
+        record('command.invoked', { command: cmd });
+    }
+})();
+
+
+// ── init ──────────────────────────────────────────────────────
+program
+    .command('init')
+    .alias('i')
+    .description('Initialize AI Flow Kit in your project')
+    .option('-f, --framework <types>', 'framework(s), comma-separated (e.g. spring-boot,reactjs)')
+    .option('-a, --adapter <types>', 'adapter(s), comma-separated (e.g. backlog,jira)')
+    .option('-e, --env <types>', 'AI environment(s)/tool(s), comma-separated (e.g. cursor,gemini,copilot)')
+    .option('--with-rtk', 'force enable RTK token compression hook')
+    .option('--no-rtk', 'skip RTK setup even if RTK is detected')
+    .action((options) => {
+        options.frameworks = options.framework
+            ? options.framework.split(',').map(s => s.trim()).filter(Boolean)
+            : [];
+        options.adapters = options.adapter
+            ? options.adapter.split(',').map(s => s.trim()).filter(Boolean)
+            : [];
+        options.aiTools = options.env
+            ? options.env.split(',').map(s => s.trim()).filter(Boolean)
+            : Object.keys(require('../scripts/init').AI_TOOL_FILES || {}).filter(t => t !== 'generic');
+
+        initCommand(options);
+    });
+
+// ── use ───────────────────────────────────────────────────────
+program
+    .command('use [target]')
+    .alias('u')
+    .description('Load context from ticket, version, or file')
+    .option('-m, --manual', 'manual context entry')
+    .option('-f, --file <path>', 'load from file')
+    .option('-s, --save <name>', 'save as named context')
+    .option('-c, --coms', 'load all comments (alias for --with-comments)')
+    .option('--with-comments', 'load all comments')
+    .option('--cid <id>', 'load a specific comment by ID')
+    .option('--clast <n>', 'load the last N comments', parseInt)
+    .option('--cfrom <id>', 'load comments from ID N onward', parseInt)
+    .option('--cto <id>', 'load comments up to ID N', parseInt)
+    .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) => {
+        useCommand(target, options);
+    });
+
+// ── prompt ────────────────────────────────────────────────────
+program
+    .command('prompt [type]')
+    .alias('p')
+    .description('Generate AI prompt with context and rules')
+    .option('-l, --list', 'list available prompt types')
+    .option('-o, --output <file>', 'save to file')
+    .option('-L, --lang <lang>', 'language: english (default) or vietnamese')
+    .option('-d, --detail <level>', 'detail level: minimal | standard (default) | comprehensive')
+    .action((type, options) => {
+        promptCommand(type, options);
+    });
+
+// ── detect ────────────────────────────────────────────────────
+program
+    .command('detect [description]')
+    .alias('d')
+    .description('Auto-detect task type from description')
+    .option('-v, --verbose', 'show detection details')
+    .option('-t, --threshold <number>', 'confidence threshold (0-100)')
+    .action((description, options) => {
+        const detector = new TaskDetector();
+        const threshold = options.threshold ? parseInt(options.threshold) / 100 : 0.8;
+        const result = detector.detect(description, threshold);
+        console.log(chalk.cyan('\nTask Detection Results:\n'));
+        console.log(detector.formatOutput(result, options.verbose));
+    });
+
+// ── task ─────────────────────────────────────────────────────
+const taskCmd = program.command('task').alias('t').description('Manage multiple tasks — pause, switch, resume');
+
+taskCmd
+    .command('status')
+    .alias('st')
+    .description('Show active task and pending tasks')
+    .action(() => { taskCommand('status'); });
+
+taskCmd
+    .command('list')
+    .alias('ls')
+    .description('List all saved tasks')
+    .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) => { taskCommand('pause', { note: opts.note }); });
+
+taskCmd
+    .command('switch <ticket-id>')
+    .alias('sw')
+    .description('Pause current task and switch to another')
+    .action((ticketId) => { taskCommand('switch', { taskId: ticketId }); });
+
+taskCmd
+    .command('resume <ticket-id>')
+    .alias('r')
+    .description('Resume a paused task')
+    .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) => { taskCommand('reset', { taskId: ticketId }); });
+
+taskCmd
+    .command('remove <ticket-id>')
+    .alias('rm')
+    .description('Permanently delete all saved data for a task')
+    .action((ticketId) => { taskCommand('remove', { taskId: ticketId }); });
+
+taskCmd
+    .command('next')
+    .alias('n')
+    .description('Approve current gate and prepare next session (saves state for resume)')
+    .option('-t, --ticket <id>', 'ticket ID (defaults to active task)')
+    .action((opts) => {
+        taskCommand('next', { taskId: opts.ticket });
+    });
+
+// ── context ───────────────────────────────────────────────────
+program
+    .command('context [action]')
+    .alias('ctx')
+    .description('Manage task contexts (list|show|save <name>|clear)')
+    .option('-s, --save <name>', 'save current context with name')
+    .option('-l, --load <name>', 'load saved context by name')
+    .option('-d, --delete <name>', 'delete saved context')
+    .option('--clear', 'clear all saved contexts')
+    .option('--show', 'show current context')
+    .action((action, options) => {
+        contextCommand(action, options);
+    });
+
+// ── checkpoint ────────────────────────────────────────────────
+program
+    .command('checkpoint')
+    .alias('cp')
+    .description('Record token usage checkpoint (called by AI during gate work)')
+    .requiredOption('-g, --gate <n>', 'gate number (1–5)', parseInt)
+    .requiredOption('-s, --step <name>', 'step name (e.g. "tests-written")')
+    .requiredOption('-n, --tokens <n>', 'estimated token count', parseInt)
+    .option('-t, --ticket <id>', 'ticket ID (defaults to active task)')
+    .action((opts) => {
+        checkpointCommand({ gate: opts.gate, step: opts.step, tokens: opts.tokens, ticket: opts.ticket });
+    });
+
+// ── validate ──────────────────────────────────────────────────
+program
+    .command('validate <file>')
+    .alias('vl')
+    .description('Validate output against team rules')
+    .option('-r, --ruleset <set>', 'rule set: default | strict | lenient', 'default')
+    .option('-v, --verbose', 'detailed report')
+    .option('-x, --fix', 'auto-fix trailing whitespace')
+    .action((file, options) => {
+        validateCommand(file, {
+            ruleset: options.ruleset,
+            verbose: options.verbose,
+            fix: options.fix
+        });
+    });
+
+// ── memory ────────────────────────────────────────────────────
+// Sub-commands to avoid the ambiguous "memory <action> --save key" pattern
+const memCmd = program.command('memory').alias('mem').description('Manage team knowledge and memory');
+
+memCmd
+    .command('save <key> <value>')
+    .alias('s')
+    .description('Save a memory entry')
+    .action((key, value) => { memoryCommand('save', { key, value }); });
+
+memCmd
+    .command('get <key>')
+    .alias('g')
+    .description('Retrieve a memory entry')
+    .action((key) => { memoryCommand('get', { key }); });
+
+memCmd
+    .command('list')
+    .alias('ls')
+    .description('List all memories')
+    .action(() => { memoryCommand('list'); });
+
+memCmd
+    .command('search <query>')
+    .alias('sr')
+    .description('Search memories by keyword')
+    .action((query) => { memoryCommand('search', { query }); });
+
+memCmd
+    .command('delete <key>')
+    .alias('d')
+    .description('Delete a memory entry')
+    .action((key) => { memoryCommand('delete', { key }); });
+
+memCmd
+    .command('clear')
+    .alias('cl')
+    .description('Clear all memories')
+    .action(() => { memoryCommand('clear'); });
+
+// ── guide ─────────────────────────────────────────────────────
+program
+    .command('guide')
+    .alias('g')
+    .description('Show quickstart guide, architecture, and command reference')
+    .option('-f, --flow', 'show architecture & flow diagram only')
+    .option('-c, --commands', 'show command reference only')
+    .action((options) => {
+        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>')
+    .description('Log a gate workflow event (start|approved) — called by AI during gate workflow')
+    .option('--ticket <id>', 'ticket ID')
+    .option('--ai-tool <tool>', 'AI tool name')
+    .action((number, action, options) => {
+        const gateNum = parseInt(number);
+        if (isNaN(gateNum) || gateNum < 1 || gateNum > 5) return;
+        if (!['start', 'approved'].includes(action)) return;
+
+        const ticketId = options.ticket || '';
+
+        const telResult = record(`gate.${action}`, {
+            gate: gateNum,
+            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${ticketId ? ` --ticket ${ticketId}` : ''} to save progress,`));
+            console.log(chalk.gray(`  then open a NEW chatbox and type "continue".\n`));
+        }
+    });
+
+// ── remove ────────────────────────────────────────────────────
+program
+    .command('remove')
+    .alias('rm')
+    .description('Remove ai-flow-kit from project, a cached version, or uninstall globally')
+    .option('--version <ver>', 'remove a specific cached version from .aiflow/versions/')
+    .option('-g, --global', 'uninstall the global npm package (removes `aiflow` command)')
+    .action((options) => {
+        removeCommand(options);
+    });
+
+// ── update ────────────────────────────────────────────────────
+program
+    .command('update')
+    .alias('up')
+    .description('Update to latest version')
+    .option('-f, --force', 'force update even if already on latest')
+    .action((options) => {
+        updateCommand(options);
+    });
+
+// ── sync-skills ───────────────────────────────────────────────
+program
+    .command('sync-skills')
+    .alias('sync')
+    .description('Manually synchronize AI Instruction files with local custom skills')
+    .action(async () => {
+        const projectDir = process.cwd();
+        const { setupFramework, AI_TOOL_FILES, ensureAiflowGitignored } = require('../scripts/init');
+        const fs = require('fs-extra');
+        const path = require('path');
+        const chalk = require('chalk');
+
+        const stateFile = path.join(projectDir, '.aiflow', 'state.json');
+        if (!(await fs.pathExists(stateFile))) {
+            console.log(chalk.red('Project is not initialized. Please run `aiflow init` first.'));
+            return;
+        }
+
+        const state = await fs.readJson(stateFile);
+        const frameworks = state.frameworks || [];
+        const selectedTools = state.aiTools || Object.keys(AI_TOOL_FILES);
+
+        console.log(chalk.cyan('⟳ Syncing AI Instruction files...'));
+        for (const fw of frameworks) {
+            await setupFramework(projectDir, fw, frameworks.length > 1, selectedTools);
+        }
+        await ensureAiflowGitignored(projectDir);
+        console.log(chalk.green('✨ Sync completed!'));
+    });
+
+// ── doctor ────────────────────────────────────────────────────
+program
+    .command('doctor')
+    .alias('dr')
+    .description('Health check of AI Flow Kit setup')
+    .option('-t, --ticket <id>', 'show token breakdown for specific ticket')
+    .option('-v, --verbose', 'detailed output')
+    .action((opts) => {
+        doctorCommand({ ticket: opts.ticket, verbose: opts.verbose });
+    });
+
+// ── telemetry ──────────────────────────────────────────────────
+program
+    .command('telemetry [action]')
+    .alias('tel')
+    .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/custom/templates/shared/gate-workflow.md

@@ -29,8 +29,8 @@ AI actively reads ticket + source code to understand the requirement:
 
 DO NOT just check format — **understand the content and propose solutions**.
 
-> **Telemetry:** Run `aiflow gate 1 start --ticket [ticket-id]` when starting this gate (auto-start or when developer types "start"/"Gate 1").
-> Run `aiflow 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 `ak gate 1 approved --ticket [ticket-id]` immediately when APPROVED is received.
 
 ---
 
@@ -43,8 +43,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 `aiflow gate 2 start --ticket [ticket-id]` when starting this gate.
-> Run `aiflow 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 `ak gate 2 approved --ticket [ticket-id]` immediately when APPROVED is received.
 
 ---
 
@@ -57,7 +57,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 `aiflow gate 3 start --ticket [ticket-id]` when starting this gate.
+> **Telemetry:** Run `ak gate 3 start --ticket [ticket-id]` when starting this gate.
 
 ---
 
@@ -75,8 +75,8 @@ Then: "GATE 4 PAUSED: type APPROVED or BUG: [description]"
 - Coding bug -> fix -> repeat Gate 4.
 - Requirement bug -> return to Gate 1.
 
-> **Telemetry:** Run `aiflow gate 4 start --ticket [ticket-id]` when starting this gate.
-> Run `aiflow 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 `ak gate 4 approved --ticket [ticket-id]` immediately when APPROVED is received.
 
 ---
 
@@ -87,4 +87,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 `aiflow gate 5 start --ticket [ticket-id]` when starting this gate.
+> **Telemetry:** Run `ak gate 5 start --ticket [ticket-id]` when starting this gate.

package/custom/templates/tools/gemini.md

@@ -1,12 +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".
+# 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relipa/ai-flow-kit",
-  "version": "0.0.9-beta.0",
+  "version": "0.0.9-beta.1",
   "description": "All-in-one AI Flow Kit for team development with Claude AI - skills, templates, and MCP adapters",
   "author": "Example Team",
   "publishConfig": {

package/scripts/prompt.js

@@ -335,6 +335,12 @@ function buildPrompt(template, ctx, rules, options, env = 'claude') {
         lines.push('');
     }
 
+    // ── Telemetry instructions ─────────────────────────────────
+    const ticketArg = ctx?.taskId ? ` --ticket ${ctx.taskId}` : '';
+    const akCmd = isWSL() ? 'ak.cmd' : 'ak';
+    lines.push(`> **Telemetry (required):** When **starting** each gate run \`${akCmd} gate N start${ticketArg}\`. When **APPROVED** run \`${akCmd} gate N approved${ticketArg}\`. Replace N with the gate number (1–5).`);
+    lines.push('');
+
     // ── Context section ────────────────────────────────────────
     if (ctx) {
         lines.push('## Context');
@@ -409,6 +415,14 @@ function buildPrompt(template, ctx, rules, options, env = 'claude') {
     return lines.join('\n');
 }
 
+function isWSL() {
+    if (process.platform !== 'linux') return false;
+    try {
+        const version = require('fs').readFileSync('/proc/version', 'utf-8');
+        return /microsoft|wsl/i.test(version);
+    } catch (_) { return false; }
+}
+
 function copyToClipboard(text) {
     try {
         if (process.platform === 'win32') {
@@ -420,6 +434,13 @@ function copyToClipboard(text) {
             );
         } else if (process.platform === 'darwin') {
             spawnSync('pbcopy', [], { input: text, encoding: 'utf8', stdio: ['pipe', 'ignore', 'ignore'] });
+        } else if (isWSL()) {
+            spawnSync(
+                'powershell.exe',
+                ['-NoProfile', '-NonInteractive', '-Command',
+                 '[Console]::InputEncoding = [System.Text.Encoding]::UTF8; Set-Clipboard -Value ([Console]::In.ReadToEnd())'],
+                { input: text, encoding: 'utf8', stdio: ['pipe', 'ignore', 'ignore'] }
+            );
         } else {
             const r = spawnSync('xclip', ['-selection', 'clipboard'], { input: text, encoding: 'utf8', stdio: ['pipe', 'ignore', 'ignore'] });
             if (r.error) spawnSync('xsel', ['--clipboard', '--input'], { input: text, encoding: 'utf8', stdio: ['pipe', 'ignore', 'ignore'] });

package/scripts/telemetry/cli.js

@@ -232,12 +232,23 @@ module.exports = function telemetryCommand(action, options) {
 };
 
 function logEvent(options) {
-  const { record } = require('./record');
-  const event = options.event || 'custom_event';
-  const detail = options.detail || '';
-  if (!detail) {
-    record(event);
-  } else {
-    record(event, { detail });
-  }
+  try {
+    const { record } = require('./record');
+    const event = (options && options.event) || 'custom_event';
+    const detail = (options && options.detail) || '';
+    const result = detail ? record(event, { detail }) : record(event);
+
+    if (!result) return;
+    if (result.ok) {
+      console.log(chalk.green(`  [tel] ✓ '${event}' 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 '${event}': ${result.error}`));
+    }
+  } catch (e) { /* never block main flow */ }
 }

package/scripts/telemetry/record.js

@@ -61,8 +61,9 @@ function logInternalError(err) {
 function record(eventType, payload = {}) {
   try {
     const cfg = loadConfig();
-    if (!cfg.enabled) return;
-    if (isRepoOptedOut()) return;
+    if (!cfg.enabled) return { ok: false, reason: 'disabled' };
+    if (isRepoOptedOut()) return { ok: false, reason: 'opted-out' };
+    if (!cfg.apps_script_url) return { ok: false, reason: 'no-url' };
 
     ensureDirectories();
 
@@ -90,7 +91,7 @@ function record(eventType, payload = {}) {
 
     const lineStr = signEvent(event, cfg.team_secret);
     fs.appendFileSync(BUFFER_PATH, lineStr + '\n');
-    
+
     // Check if buffer is getting huge (> 10MB cap). Simple clear
     try {
       if (fs.statSync(BUFFER_PATH).size > 10 * 1024 * 1024) {
@@ -99,8 +100,10 @@ function record(eventType, payload = {}) {
     } catch (e) {}
 
     maybeSpawnFlusher(cfg);
+    return { ok: true };
   } catch (err) {
     logInternalError(err);
+    return { ok: false, error: err.message };
   }
 }