@relipa/ai-flow-kit 0.0.6 → 0.0.7-beta.1

package/scripts/init.js

@@ -8,14 +8,28 @@ const PKG_DIR = path.join(__dirname, '..');
 const GLOBAL_AIFLOW_DIR = path.join(os.homedir(), '.aiflow');
 const GLOBAL_CREDENTIALS_PATH = path.join(GLOBAL_AIFLOW_DIR, 'credentials.json');
 const PKG_VERSION = require('../package.json').version;
+const { execSync, spawn } = require('child_process');
+
+function commandExists(cmd) {
+    try {
+        const isWin = process.platform === 'win32';
+        const checkCmd = isWin ? `where ${cmd}` : `which ${cmd}`;
+        execSync(checkCmd, { stdio: 'ignore' });
+        return true;
+    } catch (_) {
+        return false;
+    }
+}
 
 // Map framework → language family for picking the right rules
 const FRAMEWORK_LANGUAGE = {
     'laravel':      'php',
+    'php-plain':    'php',
     'spring-boot':  'java',
     'reactjs':      'javascript',
     'nextjs':       'javascript',
     'vue-nuxt':     'javascript',
+    'nestjs':       'javascript',
 };
 
 const AI_TOOL_FILES = {
@@ -53,7 +67,7 @@ async function detectFramework(projectDir) {
         if (deps['next'])          return 'nextjs';
         if (deps['nuxt'])          return 'vue-nuxt';
         if (deps['vue'])           return 'vue-nuxt';
-        if (deps['@nestjs/core'])  return 'nodejs-express';
+        if (deps['@nestjs/core'])  return 'nestjs';
         if (deps['react'])         return 'reactjs';
         if (deps['express'] || deps['fastify']) return 'nodejs-express';
     }
@@ -66,6 +80,7 @@ async function detectFramework(projectDir) {
     if (await fs.pathExists(composerPath)) {
         const composer = await fs.readJson(composerPath).catch(() => ({}));
         if ((composer.require || {})['laravel/framework']) return 'laravel';
+        return 'php-plain';
     }
     // Python
     if (await fs.pathExists(path.join(projectDir, 'manage.py'))) return 'python-django';
@@ -84,6 +99,8 @@ const FRAMEWORK_CHOICES = [
     { name: 'Next.js',            value: 'nextjs' },
     { name: 'Vue / Nuxt',         value: 'vue-nuxt' },
     { name: 'Laravel (PHP)',      value: 'laravel' },
+    { name: 'PHP (no framework)',        value: 'php-plain' },
+    { name: 'NestJS',             value: 'nestjs' },
     { name: 'Node.js / Express',  value: 'nodejs-express' },
     { name: 'Python Django',      value: 'python-django' },
     { name: 'Python FastAPI',     value: 'python-fastapi' },
@@ -157,9 +174,13 @@ async function setupSuperpowersHook(_projectDir, claudeDir) {
     const hooksDir = path.join(claudeDir, 'hooks');
     await fs.ensureDir(hooksDir);
 
-    const hookSrc  = path.join(PKG_DIR, 'scripts', 'hooks', 'session-start.js');
-    const hookDest = path.join(hooksDir, 'session-start.js');
-    await fs.copy(hookSrc, hookDest, { overwrite: true });
+    const hookStartSrc  = path.join(PKG_DIR, 'scripts', 'hooks', 'session-start.js');
+    const hookStartDest = path.join(hooksDir, 'session-start.js');
+    await fs.copy(hookStartSrc, hookStartDest, { overwrite: true });
+
+    const hookStopSrc  = path.join(PKG_DIR, 'scripts', 'hooks', 'session-stop.js');
+    const hookStopDest = path.join(hooksDir, 'session-stop.js');
+    await fs.copy(hookStopSrc, hookStopDest, { overwrite: true });
 
     const settingsFile = path.join(claudeDir, 'settings.json');
     let settings = {};
@@ -169,6 +190,7 @@ async function setupSuperpowersHook(_projectDir, claudeDir) {
 
     if (!settings.hooks) settings.hooks = {};
     if (!settings.hooks.SessionStart) settings.hooks.SessionStart = [];
+    if (!settings.hooks.SessionStop) settings.hooks.SessionStop = [];
 
     settings.hooks.SessionStart = settings.hooks.SessionStart.filter(
         h => !(h._aiflowKit)
@@ -178,13 +200,26 @@ async function setupSuperpowersHook(_projectDir, claudeDir) {
         hooks: [
             {
                 type: 'command',
-                command: `node "${hookDest.replace(/\\/g, '/')}"`,
+                command: `node "${hookStartDest.replace(/\\/g, '/')}"`,
+            }
+        ]
+    });
+
+    settings.hooks.SessionStop = settings.hooks.SessionStop.filter(
+        h => !(h._aiflowKit)
+    );
+    settings.hooks.SessionStop.push({
+        _aiflowKit: true,
+        hooks: [
+            {
+                type: 'command',
+                command: `node "${hookStopDest.replace(/\\/g, '/')}"`,
             }
         ]
     });
 
     await fs.writeJson(settingsFile, settings, { spaces: 2 });
-    console.log(chalk.green(`✓ Superpowers SessionStart hook configured`));
+    console.log(chalk.green(`✓ Superpowers hooks (SessionStart, SessionStop) configured`));
 }
 
 async function verifySuperpowersSkills(versionDir) {
@@ -273,24 +308,66 @@ async function setupFramework(projectDir, framework, multi = false, selectedTool
             finalContent += workflowContent + '\n\n';
         }
 
-        finalContent += frameworkContent;
+        const markerStart = '<!-- aiflow-kit-start -->';
+        const markerEnd   = '<!-- aiflow-kit-end -->';
+        
+        finalContent = `${markerStart}\n${finalContent.trim()}\n${markerEnd}`;
 
         const fileExists = await fs.pathExists(targetPath);
 
         if (!multi) {
             const relPath = path.relative(projectDir, targetPath).replace(/\\/g, '/');
             if (fileExists) {
-                // File already exists — save aiflow template to .aiflow/reference/ for comparison.
-                // Developer owns the file in root; we never overwrite without explicit action.
-                const refPath = path.join(projectDir, '.aiflow', 'reference', path.basename(targetPath));
-                await fs.ensureDir(path.dirname(refPath));
-                await fs.writeFile(refPath, finalContent);
-                const refRel = path.relative(projectDir, refPath).replace(/\\/g, '/');
-                console.log(chalk.gray(`  ✓ ${relPath} exists — aiflow template saved to ${refRel}`));
-                skipped.push(relPath);
+                const existingContent = await fs.readFile(targetPath, 'utf-8');
+                const hasStart = existingContent.includes(markerStart);
+                const hasEnd = existingContent.includes(markerEnd);
+
+                if (hasStart && hasEnd) {
+                    const doUpdate = await confirm({ 
+                        message: `File ${relPath} already contains an AI Flow block. Do you want to update this block? (Your custom rules will not be affected)`,
+                        default: true
+                    });
+                    if (doUpdate) {
+                        const regex = new RegExp(`${markerStart}[\\s\\S]*?${markerEnd}`, 'g');
+                        const updatedContent = existingContent.replace(regex, finalContent);
+                        await fs.writeFile(targetPath, updatedContent);
+                        console.log(chalk.green(`  ✓ Updated AI Flow block in ${relPath}`));
+                        written.push(AI_TOOL_FILES[tool]);
+                    } else {
+                        const refPath = path.join(projectDir, '.aiflow', 'reference', path.basename(targetPath));
+                        await fs.ensureDir(path.dirname(refPath));
+                        await fs.writeFile(refPath, finalContent);
+                        const refRel = path.relative(projectDir, refPath).replace(/\\/g, '/');
+                        console.log(chalk.gray(`  ✓ Skipped ${relPath} — aiflow template saved to ${refRel}`));
+                        skipped.push(relPath);
+                    }
+                } else {
+                    const doOverwrite = await confirm({ 
+                        message: `File ${relPath} is missing the new AI Flow marker block. Do you want to OVERWRITE it completely with the latest template?`,
+                        default: true
+                    });
+                    if (doOverwrite) {
+                        await fs.writeFile(targetPath, finalContent);
+                        console.log(chalk.green(`  ✓ Overwrote ${relPath} with latest AI Flow template`));
+                        written.push(AI_TOOL_FILES[tool]);
+                    } else {
+                        const refPath = path.join(projectDir, '.aiflow', 'reference', path.basename(targetPath));
+                        await fs.ensureDir(path.dirname(refPath));
+                        await fs.writeFile(refPath, finalContent);
+                        const refRel = path.relative(projectDir, refPath).replace(/\\/g, '/');
+                        console.log(chalk.gray(`  ✓ Skipped ${relPath} — aiflow template saved to ${refRel}`));
+                        skipped.push(relPath);
+                    }
+                }
             } else {
-                await fs.writeFile(targetPath, finalContent);
-                written.push(AI_TOOL_FILES[tool]);
+                const doCreate = await confirm({ 
+                    message: `File ${relPath} does not exist. Do you want to create it using the latest AI Flow template?`,
+                    default: true
+                });
+                if (doCreate) {
+                    await fs.writeFile(targetPath, finalContent);
+                    written.push(AI_TOOL_FILES[tool]);
+                }
             }
         } else {
             if (fileExists) {
@@ -494,9 +571,19 @@ function verifyFigma(credentials) {
     });
 }
 
-async function ensureCredentialsGitignored(projectDir) {
+async function ensureAiflowGitignored(projectDir) {
     const gitignorePath = path.join(projectDir, '.gitignore');
-    const entries = ['.aiflow/no-telemetry'];
+    const entries = [
+        '.aiflow/',
+        'plan/',
+        '.claude/',
+        '.rules/',
+        '.mcp.json',
+        'CLAUDE.md',
+        'GEMINI.md',
+        '.cursorrules',
+        '.github/copilot-instructions.md'
+    ];
     let content = '';
     if (await fs.pathExists(gitignorePath)) {
         content = await fs.readFile(gitignorePath, 'utf-8');
@@ -523,6 +610,190 @@ function maskSecret(value) {
     return `${value.slice(0, 4)}***${value.slice(-4)}`;
 }
 
+// ── GitNexus (code intelligence) helpers ─────────────────────────
+
+const IGNORE_DIRS = new Set([
+    '.git', 'node_modules', 'target', 'build', '.aiflow',
+    'dist', 'out', '.next', '.nuxt', 'vendor', 'coverage', '.gradle',
+]);
+const SOURCE_EXT = /\.(java|kt|groovy|js|ts|jsx|tsx|mjs|cjs|php|py|go|rb|cs|cpp|c|h|rs|vue|svelte|xml|yml|yaml|sql|properties)$/i;
+async function countSourceFiles(dir) {
+    let count = 0;
+    const scan = async (d) => {
+        let entries;
+        try { entries = await fs.readdir(d, { withFileTypes: true }); } catch (_) { return; }
+        for (const e of entries) {
+            if (e.isDirectory()) {
+                if (!IGNORE_DIRS.has(e.name) && !e.name.startsWith('.')) await scan(path.join(d, e.name));
+            } else if (SOURCE_EXT.test(e.name)) {
+                count++;
+            }
+        }
+    };
+    await scan(dir);
+    return count;
+}
+
+async function isGitNexusConfigured(projectDir) {
+    const mcpPath = path.join(projectDir, '.mcp.json');
+    if (!(await fs.pathExists(mcpPath))) return false;
+    const mcp = await fs.readJson(mcpPath).catch(() => ({}));
+    return !!(mcp.mcpServers && mcp.mcpServers.gitnexus);
+}
+
+async function setupGitNexus(projectDir, wait = false) {
+    const { spawn } = require('child_process');
+    // On Windows, use shell:true so npm scripts (.cmd) resolve correctly — avoids EINVAL
+    const isWin   = process.platform === 'win32';
+    const npxCmd  = 'npx';
+    const spawnOpts = (extra = {}) => ({ shell: isWin, windowsHide: true, ...extra });
+
+    // 1. Inject MCP server config into .mcp.json (merge, don't overwrite)
+    const mcpPath = path.join(projectDir, '.mcp.json');
+    let existing = {};
+    if (await fs.pathExists(mcpPath)) {
+        existing = await fs.readJson(mcpPath).catch(() => ({}));
+    }
+    if (!existing.mcpServers) existing.mcpServers = {};
+    const mcpAlreadyPresent = !!(existing.mcpServers.gitnexus);
+    
+    // 3. Detect if gitnexus is already available in PATH (preferred over npx)
+    const hasGlobalGitNexus = commandExists('gitnexus');
+    if (hasGlobalGitNexus) {
+        existing.mcpServers.gitnexus = { command: 'gitnexus', args: ['mcp'] };
+        console.log(chalk.gray('  ✓ Global gitnexus found — using it for MCP and indexing.'));
+    } else {
+        existing.mcpServers.gitnexus = { command: 'npx', args: ['-y', 'gitnexus@latest', 'mcp'] };
+    }
+    await fs.writeJson(mcpPath, existing, { spaces: 2 });
+    if (!mcpAlreadyPresent) {
+        console.log(chalk.green('✓ GitNexus MCP server configured (.mcp.json)'));
+    }
+
+    const nodeMajor = parseInt(process.version.slice(1).split('.')[0], 10);
+    if (nodeMajor < 20) {
+        console.log(chalk.yellow(`⚠ GitNexus indexing skipped — requires Node.js >=20.0.0 (current: ${process.version}).`));
+        console.log(chalk.gray('  MCP config saved. After upgrading Node.js, run: npx gitnexus analyze'));
+        return;
+    }
+
+    const aiflowDir = path.join(projectDir, '.aiflow');
+    await fs.ensureDir(aiflowDir);
+    const statusPath  = path.join(aiflowDir, 'gitnexus-status.json');
+    const startedAt   = new Date().toISOString();
+    await fs.writeJson(statusPath, { status: 'running', startedAt });
+
+    if (!wait) {
+        const workerPath = path.join(__dirname, 'gitnexus-worker.js');
+        const child = spawn(process.execPath, [workerPath, projectDir],
+            spawnOpts({ detached: true, stdio: 'ignore' }));
+        child.unref();
+        console.log(chalk.cyan('⟳ GitNexus: indexing codebase in background...'));
+        console.log(chalk.gray('  Notification will appear when you run `aiflow use <TICKET>` next time.'));
+        return;
+    }
+
+    const fileCount = await countSourceFiles(projectDir);
+    console.log(chalk.cyan(`⟳ GitNexus: indexing ${fileCount} source files (this may take 10–30 min on first run)...`));
+    console.log(chalk.gray('  Remove --wait to index in background instead.'));
+
+    await new Promise((resolve) => {
+        const runIndexing = (withMoreRam = false) => {
+            const currentCmd = hasGlobalGitNexus ? 'gitnexus' : 'npx';
+            const currentArgs = hasGlobalGitNexus ? ['analyze'] : ['-y', 'gitnexus@latest', 'analyze'];
+            const env = { ...process.env };
+            if (withMoreRam) {
+                const ramSize = withMoreRam === '8g' ? '8192' : '4096';
+                env.NODE_OPTIONS = `--max-old-space-size=${ramSize}`;
+            }
+
+            const child = spawn(currentCmd, currentArgs,
+                spawnOpts({ cwd: projectDir, stdio: ['ignore', 'inherit', 'inherit'], env }));
+
+            child.on('close', async (code) => {
+                const completedAt = new Date().toISOString();
+                if (code === 0) {
+                    await fs.writeJson(statusPath, { status: 'done', startedAt, completedAt, notified: true });
+                    console.log(chalk.green(`✓ GitNexus: indexed ${fileCount} files — code intelligence is ready.`));
+                    resolve();
+                } else {
+                    console.log(chalk.red(`✗ GitNexus: indexing failed (exit ${code}).`));
+
+                    // Detection of Segmentation Fault / Crash (139 on Linux/Mac, 3221225477 on Windows)
+                    const isCrash = (code === 139 || code === 3221225477);
+                    if (isCrash) {
+                        console.log(chalk.yellow(`\n⚠ Indexing crashed (Segmentation Fault) at ${withMoreRam ? (withMoreRam === '8g' ? '8GB' : '4GB') : 'default'} RAM.`));
+                        
+                        const nextRam = !withMoreRam ? '4g' : (withMoreRam === '4g' ? '8g' : null);
+                        if (nextRam) {
+                            const retry = await confirm({ 
+                                message: `Would you like to retry indexing with increased memory (${nextRam.toUpperCase()})?`, 
+                                default: true 
+                            });
+                            if (retry) {
+                                return runIndexing(nextRam); // Recursion, don't resolve yet
+                            }
+                        } else {
+                            console.log(chalk.red('⚠ Already tried with 8GB RAM. Please check if there are any extremely large files or corrupted database.'));
+                            console.log(chalk.gray('  Try: rm -rf .aiflow/ladybug.db (if exists) or check your .gitignore'));
+                        }
+                    }
+
+                    // If npx failed and gitnexus isn't global, offer to install it global (only if not a crash or if retry was rejected)
+                    if (!hasGlobalGitNexus && !isCrash) {
+                        console.log(chalk.yellow('\nTip: npx failed. Installing gitnexus globally often fixes environment issues.'));
+                        const install = await confirm({ message: 'Would you like me to try installing gitnexus globally for you?', default: true });
+                        if (install) {
+                            try {
+                                console.log(chalk.blue('Running: npm install -g gitnexus ...'));
+                                execSync('npm install -g gitnexus', { stdio: 'inherit' });
+                                console.log(chalk.green('✓ GitNexus installed globally. Please run `aiflow init` again to retry indexing.'));
+                            } catch (err) {
+                                console.log(chalk.red('Failed to install globally. Please try manually: npm install -g gitnexus'));
+                            }
+                        }
+                    }
+
+                    await fs.writeJson(statusPath, { status: 'error', startedAt, completedAt, exitCode: code, notified: true });
+                    resolve();
+                }
+            });
+
+            child.on('error', async (err) => {
+                await fs.writeJson(statusPath, {
+                    status: 'error', startedAt, completedAt: new Date().toISOString(),
+                    exitCode: null, error: err.message, notified: true,
+                });
+                console.log(chalk.red(`✗ GitNexus: failed to start — ${err.message}`));
+                resolve();
+            });
+        };
+
+        runIndexing();
+    });
+}
+
+async function maybeSetupGitNexus(projectDir, withGitNexus, wait = false) {
+    if (!withGitNexus) return;
+
+    // Check if indexing has already completed successfully (not stale)
+    const STALE_MS   = 3 * 60 * 60 * 1000;
+    const statusPath = path.join(projectDir, '.aiflow', 'gitnexus-status.json');
+    let indexDone = false;
+    try {
+        const gn  = await fs.readJson(statusPath);
+        const age = gn.startedAt ? Date.now() - new Date(gn.startedAt).getTime() : Infinity;
+        const staleRunning = gn.status === 'running' && age > STALE_MS;
+        indexDone = gn.status === 'done' && !staleRunning;
+    } catch (_) {}
+
+    if ((await isGitNexusConfigured(projectDir)) && indexDone) {
+        console.log(chalk.gray('  GitNexus already configured and indexed — skipping.'));
+        return;
+    }
+    await setupGitNexus(projectDir, wait);
+}
+
 // ── RTK (token compression) helpers ──────────────────────────────
 
 async function detectRtk() {
@@ -657,6 +928,12 @@ async function init(options) {
             await maybeSetupRtk(projectDir, options.withRtk || false);
         }
 
+        // ── Optional: GitNexus code intelligence ─────────────────────
+        await maybeSetupGitNexus(projectDir, options.withGitnexus || false, options.wait || false);
+
+        // ── Ensure all aiflow files are gitignored ───────────────────
+        await ensureAiflowGitignored(projectDir);
+
         console.log(chalk.green('\n✨ Initialized AI Flow Kit successfully!'));
         console.log(chalk.blue('\n' + '─'.repeat(62)));
         console.log(chalk.bold.white('  Next steps:'));
@@ -682,3 +959,6 @@ module.exports = init;
 module.exports.AI_TOOL_FILES = AI_TOOL_FILES;
 module.exports.detectRtk = detectRtk;
 module.exports.isRtkHookConfigured = isRtkHookConfigured;
+module.exports.isGitNexusConfigured = isGitNexusConfigured;
+module.exports.setupFramework = setupFramework;
+module.exports.ensureAiflowGitignored = ensureAiflowGitignored;

package/scripts/prompt.js

@@ -96,7 +96,7 @@ AI must:
 Only runs after Gate 2 APPROVED.
 1. Complex feature (3+ files): **INVOKE:** \`superpowers:subagent-driven-development\`
 2. **INVOKE:** \`superpowers:test-driven-development\` — write failing test first
-3. Implement to make tests pass — commit each small step
+3. Implement to make tests pass — verify each small step
 
 ### GATE 4 — AI Self-Review (wait for APPROVED)
 **INVOKE:** \`review-plan\` skill
@@ -174,7 +174,7 @@ AI must:
 Only runs after Gate 2 APPROVED.
 1. **INVOKE:** \`superpowers:test-driven-development\` — ensure tests cover CURRENT behavior
 2. Refactor incrementally — keep tests green at each step
-3. Commit each step
+3. Commit after manual verification
 
 ### GATE 4 — AI Self-Review (wait for APPROVED)
 **INVOKE:** \`review-plan\` skill

package/scripts/remove.js

@@ -89,6 +89,60 @@ async function removeFromProject() {
         console.log(chalk.green('✓ Removed .rules/'));
     }
 
+    // Clean up AI Tool files (CLAUDE.md, .cursorrules, etc.)
+    const { AI_TOOL_FILES } = require('./init');
+    const markerStart = '<!-- aiflow-kit-start -->';
+    const markerEnd   = '<!-- aiflow-kit-end -->';
+
+    for (const tool in AI_TOOL_FILES) {
+        const filePath = path.join(PROJECT_DIR, AI_TOOL_FILES[tool]);
+        if (!(await fs.pathExists(filePath))) continue;
+
+        let content = await fs.readFile(filePath, 'utf-8');
+        let cleaned = false;
+
+        if (content.includes(markerStart) && content.includes(markerEnd)) {
+            // Precise removal using markers
+            const startIndex = content.indexOf(markerStart);
+            const endIndex   = content.indexOf(markerEnd) + markerEnd.length;
+            content = content.slice(0, startIndex).trim() + '\n' + content.slice(endIndex).trim();
+            content = content.trim();
+            cleaned = true;
+        } else if (content.includes('## AI Skill Registry (Superpowers)')) {
+            // Fallback for legacy installs: remove sections by headers
+            console.log(chalk.yellow(`  ⚠ Found legacy aiflow sections in ${AI_TOOL_FILES[tool]}`));
+            const ok = await confirm({ message: `Remove ai-flow-kit sections from ${AI_TOOL_FILES[tool]}?`, default: true });
+            if (ok) {
+                // Heuristic: remove from "## AI Skill Registry" or "# Claude AI System Instructions"
+                // This is simple and covers most cases. For complex cases, user should manual clean.
+                const headers = [
+                    '# Claude AI System Instructions',
+                    '## AI Skill Registry (Superpowers)',
+                    '## MANDATORY: Strict Gate Workflow'
+                ];
+                let minIndex = content.length;
+                for (const h of headers) {
+                    const idx = content.indexOf(h);
+                    if (idx !== -1 && idx < minIndex) minIndex = idx;
+                }
+                if (minIndex < content.length) {
+                    content = content.slice(0, minIndex).trim();
+                    cleaned = true;
+                }
+            }
+        }
+
+        if (cleaned) {
+            if (content.length === 0) {
+                await fs.remove(filePath);
+                console.log(chalk.green(`✓ Deleted ${AI_TOOL_FILES[tool]} (it was aiflow-only)`));
+            } else {
+                await fs.writeFile(filePath, content);
+                console.log(chalk.green(`✓ Cleaned up ai-flow-kit instructions from ${AI_TOOL_FILES[tool]}`));
+            }
+        }
+    }
+
     console.log(chalk.green('\n✨ ai-flow-kit removed from project.'));
     console.log(chalk.gray('To reinstall: aiflow init'));
 }

package/scripts/task.js

@@ -22,6 +22,7 @@ module.exports = async function task(action, options = {}) {
         if (action === 'resume' && options.taskId) return await resumeTask(options.taskId);
         if (action === 'reset'  && options.taskId) return await resetTask(options.taskId);
         if (action === 'remove' && options.taskId) return await removeTask(options.taskId);
+        if (action === 'next')                return await nextGate(options.taskId);
 
         console.log(chalk.yellow('Usage:'));
         console.log(chalk.gray('  aiflow task status              — show active task and pending list'));
@@ -32,6 +33,8 @@ module.exports = async function task(action, options = {}) {
         console.log(chalk.gray('  aiflow task resume <ticket-id>  — resume a paused task'));
         console.log(chalk.gray('  aiflow task reset  <ticket-id>  — reset task to Gate 1 (keeps context)'));
         console.log(chalk.gray('  aiflow task remove <ticket-id>  — permanently delete all task data'));
+        console.log(chalk.gray('  aiflow task next                — approve current gate + prep next session'));
+        console.log(chalk.gray('  aiflow task next --ticket <id>  — same, specify ticket explicitly'));
     } catch (err) {
         console.error(chalk.red(`Error: ${err.message}`));
     }
@@ -293,6 +296,75 @@ async function removeTask(taskId) {
     console.log(chalk.green(`✓ Task ${taskId} removed.`));
 }
 
+async function nextGate(taskId) {
+    // Resolve ticket ID
+    let resolvedId = taskId;
+    if (!resolvedId) {
+        const ctx = await fs.readJson(CURRENT_FILE).catch(() => null);
+        resolvedId = ctx && ctx.taskId ? ctx.taskId : null;
+    }
+    if (!resolvedId) {
+        console.log(chalk.yellow('No ticket ID provided and no active task found.'));
+        console.log(chalk.gray('  Usage: aiflow task next --ticket PROJ-123'));
+        return;
+    }
+
+    const taskDir   = path.join(TASKS_DIR, resolvedId);
+    const statePath = path.join(taskDir, 'task-state.json');
+    await fs.ensureDir(taskDir);
+
+    // Load or create task state
+    const existing  = (await fs.pathExists(statePath)) ? await fs.readJson(statePath).catch(() => ({})) : {};
+    const currentGate = existing.currentGate || await detectCurrentGate(resolvedId);
+    const now = new Date().toISOString();
+
+    // Record gate approval
+    const gateApprovals = existing.gateApprovals || {};
+    gateApprovals[String(currentGate)] = now;
+    const nextGateNum = currentGate + 1;
+
+    // Save context snapshot if current task is active
+    if (await fs.pathExists(CURRENT_FILE)) {
+        const ctx = await fs.readJson(CURRENT_FILE).catch(() => null);
+        if (ctx && ctx.taskId === resolvedId) {
+            await fs.writeJson(path.join(taskDir, 'context.json'), ctx, { spaces: 2 });
+        }
+    }
+
+    const taskState = {
+        ...existing,
+        taskId:        resolvedId,
+        status:        'pending',
+        updatedAt:     now,
+        pausedAt:      now,
+        currentGate:   nextGateNum,
+        gateApprovals,
+    };
+    await fs.writeJson(statePath, taskState, { spaces: 2 });
+
+    // Clear current context so no task is "active"
+    await fs.remove(CURRENT_FILE);
+
+    // Generate cumulative task-summary.md
+    const planDir = path.join(PROJECT_DIR, 'plan', resolvedId);
+    await fs.ensureDir(planDir);
+    const summaryPath = path.join(planDir, 'task-summary.md');
+    const summaryContent = await generateMarkdownSummary(taskState);
+    await fs.writeFile(summaryPath, summaryContent, 'utf-8');
+
+    const gateLabels = { 1: 'Analyze', 2: 'Plan', 3: 'Code', 4: 'Review', 5: 'PR' };
+    console.log(chalk.green(`✓ Gate ${currentGate} approved for ${resolvedId}.`));
+    console.log(chalk.gray(`  Summary saved to: plan/${resolvedId}/task-summary.md`));
+    console.log(chalk.white(`\n  Next: Gate ${nextGateNum} — ${gateLabels[nextGateNum] || 'Done'}`));
+    console.log(chalk.cyan(`\n  To continue in a fresh session (Recommended to avoid context pollution):`));
+    console.log(chalk.gray(`    1. Open a NEW chatbox or terminal session.`));
+    console.log(chalk.gray(`    2. Run: aiflow task resume ${resolvedId} (to load context).`));
+    console.log(chalk.gray(`    3. Type "start" or "continue from the current plan".`));
+    console.log(chalk.yellow(`       (Note: Gate 3 progress is saved via [x] checkboxes in plan.md.`));
+    console.log(chalk.yellow(`        The AI will automatically resume the exact task you left off.)`));
+    console.log();
+}
+
 // ──────────────────────────────────────────────────────────────
 // Internal helpers
 // ──────────────────────────────────────────────────────────────
@@ -313,6 +385,12 @@ async function loadAllTaskStates() {
 }
 
 async function detectCurrentGate(taskId) {
+    const statePath = path.join(TASKS_DIR, taskId, 'task-state.json');
+    if (await fs.pathExists(statePath)) {
+        const state = await fs.readJson(statePath).catch(() => ({}));
+        if (state.currentGate) return state.currentGate;
+    }
+
     const planDir = path.join(PROJECT_DIR, 'plan', taskId);
     if (!(await fs.pathExists(planDir))) return 1;
     if (await fs.pathExists(path.join(planDir, 'summary.md')))     return 5;
@@ -321,6 +399,29 @@ async function detectCurrentGate(taskId) {
     return 1;
 }
 
+async function generateMarkdownSummary(taskState) {
+    const lines = [];
+    lines.push(`# Task Summary: ${taskState.taskId}`);
+    lines.push(`**Title:** ${taskState.title}`);
+    lines.push(`**Status:** ${taskState.status}`);
+    lines.push(`**Current Gate:** ${taskState.currentGate} (${gateLabel(taskState.currentGate)})`);
+    lines.push(`**Updated At:** ${new Date().toLocaleString()}`);
+    lines.push(``);
+    lines.push(`## Gate History`);
+    lines.push(`| Gate | Status | Approved At |`);
+    lines.push(`|------|--------|-------------|`);
+    for (let i = 1; i <= 5; i++) {
+        const approvedAt = taskState.gateApprovals && taskState.gateApprovals[String(i)];
+        const status = approvedAt ? '✅ Approved' : (i === taskState.currentGate ? '⏳ In Progress' : '⚪ Pending');
+        const timeStr = approvedAt ? new Date(approvedAt).toLocaleString() : '-';
+        lines.push(`| Gate ${i} (${gateLabel(i)}) | ${status} | ${timeStr} |`);
+    }
+    lines.push(``);
+    lines.push(`---`);
+    lines.push(`*Auto-generated by aiflow task next*`);
+    return lines.join('\n');
+}
+
 function gateLabel(n) {
     const labels = {
         1: 'AI Analyze Requirement',

package/scripts/update.js

@@ -29,12 +29,11 @@ module.exports = async function update(options = {}) {
     const currentVersion = state.current_version;
 
     if (currentVersion === PKG_VERSION && !options.force) {
-        console.log(chalk.green(`Already on v${PKG_VERSION}. Use --force to re-copy assets anyway.`));
-        return;
+        console.log(chalk.cyan(`You are already on v${PKG_VERSION}. Syncing latest assets and instruction files...`));
+    } else {
+        console.log(chalk.blue(`Updating from v${currentVersion} to v${PKG_VERSION}...`));
     }
 
-    console.log(chalk.blue(`Updating from v${currentVersion} to v${PKG_VERSION}...`));
-
     const newVersionDir = path.join(aiflowDir, 'versions', PKG_VERSION);
     await fs.ensureDir(newVersionDir);
 
@@ -107,5 +106,16 @@ module.exports = async function update(options = {}) {
     state.current_version = PKG_VERSION;
     await fs.writeJson(stateFile, state);
 
+    // Sync instruction files with the updated skills
+    const { setupFramework, AI_TOOL_FILES, ensureAiflowGitignored } = require('./init');
+    const frameworks = state.frameworks || [];
+    const selectedTools = state.aiTools || Object.keys(AI_TOOL_FILES);
+    for (const fw of frameworks) {
+        await setupFramework(projectDir, fw, frameworks.length > 1, selectedTools);
+    }
+
+    // Ensure all aiflow files are gitignored (especially for projects upgrading from older versions)
+    await ensureAiflowGitignored(projectDir);
+
     console.log(chalk.green(`\n✨ Update completed! Your project is now on v${PKG_VERSION}.`));
 };