@relipa/ai-flow-kit 0.0.1

package/scripts/detect.js

@@ -0,0 +1,239 @@
+const chalk = require('chalk');
+
+class TaskDetector {
+    constructor() {
+        this.taskTypes = {
+            'bug-fix': {
+                keywords: [
+                    'bug', 'error', 'broken', 'crash', 'fail', 'failed', 'failure',
+                    'issue', 'problem', 'wrong', 'not working', 'doesn\'t work',
+                    'can\'t', 'cannot', 'regression', 'fixing', 'fix',
+                    'exception', 'bug report'
+                ],
+                antiKeywords: ['add', 'create', 'new feature', 'build'],
+                icon: '🐛',
+                description: 'Fixing production issues'
+            },
+            'feature': {
+                keywords: [
+                    'add', 'create', 'build', 'new', 'implement', 'feature',
+                    'new feature', 'feature request', 'capability', 'support for',
+                    'enable', 'make it possible', 'allow', 'user story'
+                ],
+                antiKeywords: ['fix', 'bug', 'broken', 'error'],
+                icon: '✨',
+                description: 'Building new features'
+            },
+            'refactor': {
+                keywords: [
+                    'refactor', 'improve', 'optimize', 'clean up', 'cleanup',
+                    'simplify', 'reorganize', 'reorganise', 'redesign', 'restructure',
+                    'modernize', 'upgrade', 'update', 'rework', 'rewrite',
+                    'performance', 'efficient', 'better', 'enhancement'
+                ],
+                antiKeywords: ['bug', 'broken', 'feature'],
+                icon: '♻️',
+                description: 'Improving existing code'
+            },
+            'investigation': {
+                keywords: [
+                    'investigate', 'analyze', 'analysis', 'understand', 'how does',
+                    'why', 'trace', 'explore', 'research', 'find out', 'examine',
+                    'check', 'review', 'audit', 'assessment'
+                ],
+                antiKeywords: ['fix', 'build', 'create'],
+                icon: '🔍',
+                description: 'Analyzing code and systems'
+            },
+            'impact-analysis': {
+                keywords: [
+                    'impact', 'affect', 'affected', 'breaking', 'breaking change',
+                    'scope', 'scope of change', 'side effect', 'consequence',
+                    'dependent', 'dependency', 'risk', 'assess'
+                ],
+                antiKeywords: [],
+                icon: '📊',
+                description: 'Assessing change impact'
+            },
+            'documentation': {
+                keywords: [
+                    'document', 'readme', 'guide', 'tutorial',
+                    'documentation', 'write doc', 'comment', 'docstring',
+                    'explain', 'api doc', 'reference'
+                ],
+                antiKeywords: ['code'],
+                icon: '📖',
+                description: 'Writing documentation'
+            }
+        };
+    }
+
+    /**
+     * Detect task type from description
+     * Returns: { type, confidence, keywords, suggestions }
+     */
+    detect(description, confidenceThreshold = 0.8) {
+        if (!description || typeof description !== 'string') {
+            return this.getDefaultResult();
+        }
+
+        const lowerDesc = description.toLowerCase();
+        const scores = {};
+
+        // Score each task type
+        for (const [type, config] of Object.entries(this.taskTypes)) {
+            scores[type] = this.scoreType(lowerDesc, config);
+        }
+
+        // Find best match
+        const sorted = Object.entries(scores)
+            .sort(([, scoreA], [, scoreB]) => scoreB - scoreA);
+
+        if (!sorted.length || sorted[0][1] === 0) {
+            return this.getDefaultResult();
+        }
+
+        const [bestType, score] = sorted[0];
+        const confidence = Math.min(score, 1.0);
+
+        return {
+            type: bestType,
+            confidence: Math.round(confidence * 100) / 100,
+            confidence_percent: Math.round(confidence * 100),
+            icon: this.taskTypes[bestType].icon,
+            description: this.taskTypes[bestType].description,
+            keywords: this.findMatchingKeywords(lowerDesc, this.taskTypes[bestType]),
+            suggestions: sorted.slice(1, 3).map(([t, s]) => ({
+                type: t,
+                confidence: Math.round(s * 100) / 100
+            })),
+            isConfident: confidence >= confidenceThreshold,
+            detectedKeywords: this.findAllMatchedKeywords(lowerDesc)
+        };
+    }
+
+    /**
+     * Score a task type based on description
+     */
+    scoreType(description, config) {
+        let score = 0;
+
+        // Count matching keywords
+        for (const keyword of config.keywords) {
+            if (description.includes(keyword)) {
+                score += 0.5;
+            }
+        }
+
+        // Penalize anti-keywords
+        for (const antiKeyword of config.antiKeywords) {
+            if (description.includes(antiKeyword)) {
+                score -= 0.3;
+            }
+        }
+
+        // Normalize score
+        return Math.max(0, Math.min(1, score / Math.max(1, config.keywords.length / 3)));
+    }
+
+    /**
+     * Find which keywords matched in description
+     */
+    findMatchingKeywords(description, config) {
+        const matches = [];
+        for (const keyword of config.keywords) {
+            if (description.includes(keyword)) {
+                matches.push(keyword);
+            }
+        }
+        return matches.slice(0, 5); // Top 5 matches
+    }
+
+    /**
+     * Find all matched keywords across all types
+     */
+    findAllMatchedKeywords(description) {
+        const allKeywords = {};
+        for (const [type, config] of Object.entries(this.taskTypes)) {
+            const matched = this.findMatchingKeywords(description, config);
+            if (matched.length > 0) {
+                allKeywords[type] = matched;
+            }
+        }
+        return allKeywords;
+    }
+
+    /**
+     * Default result when detection fails
+     */
+    getDefaultResult() {
+        return {
+            type: 'unknown',
+            confidence: 0,
+            confidence_percent: 0,
+            icon: '❓',
+            description: 'Unknown task type',
+            keywords: [],
+            suggestions: [],
+            isConfident: false,
+            detectedKeywords: {}
+        };
+    }
+
+    /**
+     * Get formatted output for CLI
+     */
+    formatOutput(result, verbose = false) {
+        if (result.type === 'unknown') {
+            return `${result.icon} Could not detect task type\n\nPlease provide more details or specify task type explicitly:\n  aiflow prompt bug-fix\n  aiflow prompt feature\n  aiflow prompt investigation`;
+        }
+
+        let output = `${result.icon} ${result.type.toUpperCase()} (${result.confidence_percent}% confidence)\n\n`;
+
+        if (verbose) {
+            output += `Description: ${result.description}\n`;
+            output += `Detected keywords:\n`;
+            for (const keyword of result.keywords.slice(0, 5)) {
+                output += `  - ${keyword}\n`;
+            }
+
+            if (result.suggestions.length > 0) {
+                output += `\nOther possibilities:\n`;
+                for (const sugg of result.suggestions) {
+                    output += `  - ${sugg.type} (${Math.round(sugg.confidence * 100)}%)\n`;
+                }
+            }
+        }
+
+        output += `\nSuggested skill: ${result.type}\n`;
+        output += `\nNext: aiflow prompt ${result.type}`;
+
+        return output;
+    }
+
+    /**
+     * Export all task types for reference
+     */
+    getTaskTypes() {
+        return this.taskTypes;
+    }
+
+    /**
+     * Get task type by name
+     */
+    getTaskType(name) {
+        return this.taskTypes[name] || null;
+    }
+
+    /**
+     * Get available task types
+     */
+    getAvailableTypes() {
+        return Object.keys(this.taskTypes).map(type => ({
+            name: type,
+            ...this.taskTypes[type]
+        }));
+    }
+}
+
+module.exports = TaskDetector;

package/scripts/doctor.js

@@ -0,0 +1,48 @@
+const fs = require('fs-extra');
+const path = require('path');
+const chalk = require('chalk');
+
+module.exports = async function doctor() {
+    const projectDir = process.cwd();
+    const errors = [];
+
+    console.log(chalk.blue('Running health check for AI Flow Kit...\n'));
+
+    // Check .claude directory
+    if (!(await fs.pathExists(path.join(projectDir, '.claude', 'skills')))) {
+        errors.push("Missing `.claude/skills` directory. Did you run `aiflow init`?");
+    } else {
+        console.log(chalk.green('✓ .claude/skills exists'));
+    }
+
+    // Check .rules directory
+    if (!(await fs.pathExists(path.join(projectDir, '.rules')))) {
+        errors.push("Missing `.rules` directory.");
+    } else {
+        console.log(chalk.green('✓ .rules exists'));
+    }
+
+    // Check CLAUDE.md template
+    if (!(await fs.pathExists(path.join(projectDir, 'CLAUDE.md')))) {
+        errors.push("Missing CLAUDE.md. Prompt AI Context is not set up.");
+    } else {
+        console.log(chalk.green('✓ CLAUDE.md exists'));
+    }
+
+    // Check .aiflow hidden state
+    const stateFile = path.join(projectDir, '.aiflow', 'state.json');
+    if (!(await fs.pathExists(stateFile))) {
+        errors.push("Missing `.aiflow/state.json`. Version tracking is broken.");
+    } else {
+        const state = await fs.readJson(stateFile);
+        console.log(chalk.green(`✓ Version tracking active (v${state.current_version})`));
+    }
+
+    if (errors.length > 0) {
+        console.log(chalk.red('\nIssues found:'));
+        errors.forEach(e => console.log(chalk.red(` - ${e}`)));
+        console.log(chalk.yellow('\nTry running `aiflow init` or `aiflow update` to fix these files.'));
+    } else {
+        console.log(chalk.green('\n✨ Everything looks healthy! You are ready to fly.'));
+    }
+};

package/scripts/guide.js

@@ -0,0 +1,282 @@
+const chalk = require('chalk');
+
+// ──────────────────────────────────────────────────────────────
+// Entry point
+// ──────────────────────────────────────────────────────────────
+
+module.exports = function guide(options = {}) {
+    if (options.flow)     return showFlow();
+    if (options.commands) return showCommands();
+    showFull();
+};
+
+// ──────────────────────────────────────────────────────────────
+// Full guide
+// ──────────────────────────────────────────────────────────────
+
+function showFull() {
+    showHeader();
+    showFlow();
+    showWorkflow();
+    showCommands();
+    showPromptGuide();
+    showFooter();
+}
+
+// ──────────────────────────────────────────────────────────────
+// Header
+// ──────────────────────────────────────────────────────────────
+
+function showHeader() {
+    console.log('\n' + chalk.bold.blue('═'.repeat(62)));
+    console.log(chalk.bold.white('  AI Flow Kit — Quickstart Guide'));
+    console.log(chalk.blue('═'.repeat(62)) + '\n');
+    console.log(chalk.gray('  All-in-one AI workflow for development teams using Claude AI.'));
+    console.log(chalk.gray('  Developers only need 3 steps for AI to understand the task and start working.\n'));
+}
+
+// ──────────────────────────────────────────────────────────────
+// Architecture / Flow diagram
+// ──────────────────────────────────────────────────────────────
+
+function showFlow() {
+    console.log(chalk.bold.cyan('  📐 ARCHITECTURE & FLOW\n'));
+
+    console.log(chalk.gray('  ┌──────────────────────────────────────────────────────┐'));
+    console.log(chalk.gray('  │') + chalk.bold.yellow('  TECH LEAD (One-time setup)') + chalk.gray('                         │'));
+    console.log(chalk.gray('  │') + chalk.white('  1. Configure custom/rules/, custom/templates/') + chalk.gray('        │'));
+    console.log(chalk.gray('  │') + chalk.white('  2. npm publish  →  developer: npm install -g pkg') + chalk.gray('    │'));
+    console.log(chalk.gray('  └─────────────────────────┬────────────────────────────┘'));
+    console.log(chalk.gray('                            │'));
+    console.log(chalk.gray('              ┌─────────────▼──────────────┐'));
+    console.log(chalk.gray('              │') + chalk.bold.green('    aiflow init') + chalk.gray('                │'));
+    console.log(chalk.gray('              │') + chalk.white('  --framework spring-boot') + chalk.gray('      │'));
+    console.log(chalk.gray('              │') + chalk.white('  --adapter backlog') + chalk.gray('            │'));
+    console.log(chalk.gray('              └─────────────┬──────────────┘'));
+    console.log(chalk.gray('                            │ generates'));
+    console.log(chalk.gray('              ┌─────────────▼──────────────────────────┐'));
+    console.log(chalk.gray('              │') + chalk.white('  .claude/skills/    ← superpowers + custom') + chalk.gray(' │'));
+    console.log(chalk.gray('              │') + chalk.white('  .claude/hooks/     ← SessionStart hook') + chalk.gray('    │'));
+    console.log(chalk.gray('              │') + chalk.white('  .rules/            ← team coding rules') + chalk.gray('    │'));
+    console.log(chalk.gray('              │') + chalk.white('  CLAUDE.md          ← framework AI prompt') + chalk.gray('  │'));
+    console.log(chalk.gray('              │') + chalk.white('  .mcp.json          ← MCP adapter config') + chalk.gray('   │'));
+    console.log(chalk.gray('              └─────────────┬──────────────────────────┘'));
+    console.log(chalk.gray('                            │'));
+    console.log(chalk.gray('         ┌──────────────────▼───────────────────┐'));
+    console.log(chalk.gray('         │') + chalk.bold.green('  Developer Workflow (per task)') + chalk.gray('         │'));
+    console.log(chalk.gray('         │') + chalk.white('                                        │'));
+    console.log(chalk.gray('         │') + chalk.cyan('  1. aiflow use PROJ-33') + chalk.gray('                 │'));
+    console.log(chalk.gray('         │') + chalk.gray('     └─ pull title, desc, comments from  │'));
+    console.log(chalk.gray('         │') + chalk.gray('        Backlog/Jira → current.json      │'));
+    console.log(chalk.gray('         │') + chalk.white('                                        │'));
+    console.log(chalk.gray('         │') + chalk.cyan('  2. aiflow prompt bug-fix') + chalk.gray('              │'));
+    console.log(chalk.gray('         │') + chalk.gray('     └─ generate AI prompt from context  │'));
+    console.log(chalk.gray('         │') + chalk.gray('        + team rules → paste into Claude │'));
+    console.log(chalk.gray('         │') + chalk.white('                                        │'));
+    console.log(chalk.gray('         │') + chalk.cyan('  3. claude (open Claude terminal)') + chalk.gray('       │'));
+    console.log(chalk.gray('         │') + chalk.gray('     └─ "Fix bug PROJ-33" (1 line)       │'));
+    console.log(chalk.gray('         └──────────────────┬───────────────────┘'));
+    console.log(chalk.gray('                            │'));
+    console.log(chalk.gray('         ┌──────────────────▼───────────────────┐'));
+    console.log(chalk.gray('         │') + chalk.bold.magenta('  Claude AI (automatic)') + chalk.gray('                │'));
+    console.log(chalk.gray('         │') + chalk.white('                                        │'));
+    console.log(chalk.gray('         │') + chalk.gray('  SessionStart hook injected superpowers  │'));
+    console.log(chalk.gray('         │') + chalk.gray('       ↓                                 │'));
+    console.log(chalk.gray('         │') + chalk.gray('  Read CLAUDE.md (framework rules)       │'));
+    console.log(chalk.gray('         │') + chalk.gray('       ↓                                 │'));
+    console.log(chalk.gray('         │') + chalk.gray('  Read context/current.json (ticket)     │'));
+    console.log(chalk.gray('         │') + chalk.gray('       ↓                                 │'));
+    console.log(chalk.gray('         │') + chalk.gray('  Auto-detect task type → select skill   │'));
+    console.log(chalk.gray('         │') + chalk.gray('       ↓                                 │'));
+    console.log(chalk.gray('         │') + chalk.gray('  Implement with team rules              │'));
+    console.log(chalk.gray('         └────────────────────────────────────────┘'));
+    console.log();
+}
+
+// ──────────────────────────────────────────────────────────────
+// Step-by-step workflow
+// ──────────────────────────────────────────────────────────────
+
+function showWorkflow() {
+    console.log(chalk.bold.cyan('  🚀 WORKFLOW STEP-BY-STEP\n'));
+
+    // Step 0: Install
+    console.log(chalk.bold.white('  Step 0 — Installation (One-time)'));
+    console.log(chalk.green('    npm install -g ai-flow-kit'));
+    console.log();
+
+    // Step 1: Init
+    console.log(chalk.bold.white('  Step 1 — Initialize project (Once per project)'));
+    console.log(chalk.green('    aiflow init --framework spring-boot --adapter backlog'));
+    console.log(chalk.gray('    → Creates .claude/, .rules/, CLAUDE.md, .mcp.json'));
+    console.log();
+
+    // Step 2: Load context
+    console.log(chalk.bold.white('  Step 2 — Load context from ticket (per task)'));
+    console.log(chalk.green('    aiflow use PROJ-33 --with-comments'));
+    console.log(chalk.green('    aiflow prompt bug-fix'));
+    console.log(chalk.green('    claude'));
+    console.log();
+
+    // Gate workflow
+    console.log(chalk.bold.white('  Step 3 — AI runs Strict Gate Workflow automatically'));
+    console.log();
+    console.log(chalk.yellow('    ⛩️  GATE 1') + chalk.gray(' — AI checks ticket for all 4 required components'));
+    console.log(chalk.gray('                  If missing → ask one by one until complete'));
+    console.log(chalk.gray('                  Developer types "continue" → move to Gate 2'));
+    console.log();
+    console.log(chalk.yellow('    ⛩️  GATE 2') + chalk.gray(' — AI generates detailed spec + plan'));
+    console.log(chalk.gray('                  Developer reviews each section'));
+    console.log(chalk.gray('                  Developer types "APPROVED" → move to Gate 3'));
+    console.log();
+    console.log(chalk.yellow('    ⛩️  GATE 3') + chalk.gray(' — AI generates code (TDD: tests first)'));
+    console.log(chalk.gray('                  Automatic, developer only monitors'));
+    console.log();
+    console.log(chalk.yellow('    ⛩️  GATE 4') + chalk.gray(' — AI self-reviews + generates summary'));
+    console.log(chalk.gray('                  Developer review → "APPROVED" or "BUG: ..."'));
+    console.log();
+    console.log(chalk.yellow('    ⛩️  GATE 5') + chalk.gray(' — Peer review → create PR → merge'));
+    console.log();
+    console.log(chalk.gray('    Full details: ') + chalk.green('cat AIFLOW.md'));
+    console.log();
+
+    // Frameworks supported
+    console.log(chalk.bold.white('  Frameworks: ') + chalk.gray('spring-boot │ reactjs │ nextjs │ vue-nuxt │ laravel'));
+    console.log(chalk.bold.white('  Adapters:   ') + chalk.gray('backlog │ jira │ figma'));
+    console.log();
+}
+
+// ──────────────────────────────────────────────────────────────
+// Command reference
+// ──────────────────────────────────────────────────────────────
+
+function showCommands() {
+    console.log(chalk.bold.cyan('  📋 COMMAND REFERENCE\n'));
+
+    const commands = [
+        {
+            group: 'Setup',
+            items: [
+                ['aiflow init', '--framework <fw> --adapter <ad>', 'Initialize project'],
+                ['aiflow doctor', '', 'Check setup health'],
+                ['aiflow update', '', 'Update to the latest version'],
+                ['aiflow remove', '', 'Remove ai-flow-kit from project'],
+                ['aiflow remove', '--version <ver>', 'Remove a cached version'],
+                ['aiflow remove', '--global', 'Uninstall global package'],
+            ]
+        },
+        {
+            group: 'Workflow (use per task)',
+            items: [
+                ['aiflow use <TICKET-ID>', '', 'Load context from Backlog/Jira'],
+                ['aiflow use', '--manual', 'Enter context manually'],
+                ['aiflow use', '--with-comments', 'Include all comments'],
+                ['aiflow use', '--comments-last <n>', 'Only get last N comments'],
+                ['aiflow prompt <type>', '', 'Generate AI prompt'],
+                ['aiflow prompt', '--list', 'View all prompt types'],
+                ['aiflow prompt', '--output <file>', 'Save prompt to file'],
+                ['aiflow prompt', '--lang vietnamese', 'Prompt in Vietnamese'],
+                ['aiflow detect "<description>"', '', 'Auto-detect task type'],
+            ]
+        },
+        {
+            group: 'Context management',
+            items: [
+                ['aiflow context show', '', 'View active context'],
+                ['aiflow context list', '', 'List saved contexts'],
+                ['aiflow context save <name>', '', 'Save current context'],
+                ['aiflow context --load <name>', '', 'Load saved context'],
+                ['aiflow context --delete <name>', '', 'Delete saved context'],
+                ['aiflow context clear', '', 'Clear all contexts'],
+            ]
+        },
+        {
+            group: 'Memory (team knowledge)',
+            items: [
+                ['aiflow memory save <key> <value>', '', 'Save a note'],
+                ['aiflow memory get <key>', '', 'Read a note'],
+                ['aiflow memory list', '', 'List all notes'],
+                ['aiflow memory search <query>', '', 'Search notes'],
+                ['aiflow memory delete <key>', '', 'Delete a note'],
+                ['aiflow memory clear', '', 'Clear all notes'],
+            ]
+        },
+        {
+            group: 'Validation',
+            items: [
+                ['aiflow validate <file>', '', 'Validate code against team rules'],
+                ['aiflow validate <file>', '--fix', 'Auto-fix trailing whitespace'],
+                ['aiflow validate <file>', '-r lenient', 'Only report critical errors'],
+                ['aiflow validate <file>', '-r strict', 'Report all warnings'],
+            ]
+        },
+        {
+            group: 'Help',
+            items: [
+                ['aiflow guide', '', 'View this guide again'],
+                ['aiflow guide', '--flow', 'Only view architecture & flow'],
+                ['aiflow guide', '--commands', 'Only view command reference'],
+                ['aiflow <command>', '--help', 'Help for each command'],
+            ]
+        },
+    ];
+
+    for (const { group, items } of commands) {
+        console.log(chalk.bold.white(`  ${group}`));
+        for (const [cmd, opts, desc] of items) {
+            const cmdStr  = chalk.green(cmd.padEnd(34));
+            const optStr  = chalk.gray((opts || '').padEnd(22));
+            const descStr = chalk.white(desc);
+            console.log(`    ${cmdStr}${optStr}${descStr}`);
+        }
+        console.log();
+    }
+}
+
+// ──────────────────────────────────────────────────────────────
+// Prompt type guide
+// ──────────────────────────────────────────────────────────────
+
+function showPromptGuide() {
+    console.log(chalk.bold.cyan('  🤖 PROMPT TYPES — WHEN TO USE?\n'));
+
+    const types = [
+        ['bug-fix',          'Fixing bugs, crashes, regressions'],
+        ['feature',          'Implementing new features (user stories)'],
+        ['investigation',    'Investigating, analyzing root cause'],
+        ['refactor',         'Improving code without changing behavior'],
+        ['impact-analysis',  'Analyzing the impact of changes'],
+        ['documentation',    'Writing docs, README, API reference'],
+    ];
+
+    for (const [type, when] of types) {
+        console.log(`    ${chalk.green(('aiflow prompt ' + type).padEnd(34))} ${chalk.gray(when)}`);
+    }
+    console.log();
+
+    console.log(chalk.bold.white('  Example complete workflow for a bug:\n'));
+    console.log(chalk.gray('    $ ') + chalk.green('aiflow use PROJ-33 --with-comments'));
+    console.log(chalk.gray('      ✓ Context loaded: PROJ-33 — Login button crash on iOS\n'));
+    console.log(chalk.gray('    $ ') + chalk.green('aiflow prompt bug-fix'));
+    console.log(chalk.gray('      ─────────────────────────────────────────────────────'));
+    console.log(chalk.gray('      # Fix Bug'));
+    console.log(chalk.gray('      **Task:** Investigate and fix the bug...'));
+    console.log(chalk.gray('      **Ticket:** PROJ-33'));
+    console.log(chalk.gray('      **Title:** Login button crash on iOS'));
+    console.log(chalk.gray('      ...team rules...'));
+    console.log(chalk.gray('      ─────────────────────────────────────────────────────\n'));
+    console.log(chalk.gray('    $ ') + chalk.green('claude'));
+    console.log(chalk.gray('      > Fix bug PROJ-33'));
+    console.log(chalk.gray('      → Claude automatically reads context, applies rules, invokes systematic-debugging skill\n'));
+}
+
+// ──────────────────────────────────────────────────────────────
+// Footer
+// ──────────────────────────────────────────────────────────────
+
+function showFooter() {
+    console.log(chalk.blue('─'.repeat(62)));
+    console.log(chalk.gray('  View the guide anytime: ') + chalk.green('aiflow guide'));
+    console.log(chalk.gray('  Check setup health:     ') + chalk.green('aiflow doctor'));
+    console.log(chalk.blue('─'.repeat(62)) + '\n');
+}