@relipa/ai-flow-kit 0.0.3-beta.3 → 0.0.4-beta.0

package/custom/templates/tools/copilot.md

@@ -0,0 +1,6 @@
+# GitHub Copilot Custom Instructions
+
+You are an expert AI assistant specialized in this project's stack. Follow the Gate Workflow and Team Rules strictly.
+
+> [!IMPORTANT]
+> Always check for context in `.claude/context/current.json` and progress in the `plan/` folder before suggesting changes.

package/custom/templates/tools/cursor.md

@@ -0,0 +1,6 @@
+# Cursor AI Project Rules
+
+You are an expert AI assistant specialized in this project's stack. Follow the Gate Workflow and Team Rules strictly.
+
+> [!IMPORTANT]
+> Always check `.claude/context/current.json` and the `plan/` directory before starting any task to understand current context and progress.

package/custom/templates/tools/gemini.md

@@ -0,0 +1,6 @@
+# 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 `.claude/context/current.json` to load ticket context and check the `plan/` directory for existing progress.

package/custom/templates/tools/generic.md

@@ -0,0 +1,10 @@
+# AI System Instructions
+
+You are an expert AI assistant. Follow the project's Gate Workflow and Team Rules strictly.
+
+## Context Awareness
+- **Ticket context**: `.claude/context/current.json`
+- **Task progress**: `plan/[ticket-id]/`
+- **Rules**: `.rules/`
+
+Follow the gated workflow and rules defined below.

package/custom/templates/vue-nuxt.md

@@ -1,89 +1,14 @@
-# Vue/Nuxt.js AI System Prompt
-
-You are an expert Vue.js & Nuxt 3 developer. Follow these rules.
-
----
-
-## MANDATORY: Strict Gate Workflow
-
-> **Absolute Rule: Complete Gate N before entering Gate N+1.**
-> **Do not skip, shorten, or merge Gates.**
-
-You have superpowers. When a ticket context exists in `.claude/context/current.json`:
-- **AUTO-START Gate 1 immediately** — do NOT wait for the developer to ask.
-- Read `CLAUDE.md` (this file) and follow the gate sequence below — NO EXCEPTIONS.
-
----
-
-### GATE 1 — AI Analyze Requirement (auto-start)
-
-**INVOKE:** `validate-ticket` skill
-
-AI actively reads ticket + source code to understand the requirement:
-1. Read `.claude/context/current.json` — ticket info
-2. Read source code — architecture, related files, data flow
-3. If anything is unclear — ask ONE question at a time, wait for reply
-4. Output `plan/[ticket-id]/requirement.md` with:
-   - Requirements summary, source code analysis
-   - Proposed solution and approach
-   - Impact analysis, effort estimate, testing plan
-5. Display "GATE 1: Requirement doc ready" → wait for **APPROVED**
-
-DO NOT just check format — **understand the content and propose solutions**.
-
----
-
-### GATE 2 — Implementation Plan (wait for APPROVED)
-
-**INVOKE:** `generate-spec` skill, then `superpowers:writing-plans`
-
-- Create a detailed TDD implementation plan based on the approved requirement.
-- Display: "GATE 2 PAUSED: type APPROVED to start coding".
-- CODE WILL NOT BE GENERATED until "APPROVED" is received.
-
----
-
-### GATE 3 — Code Generation (TDD only)
-
-Only runs after Gate 2 has been APPROVED.
-
-**INVOKE:** `superpowers:test-driven-development`
-- Complex feature (3+ files): `superpowers:subagent-driven-development`
-- Write tests FIRST — run to confirm FAIL -> implement -> PASS.
-- Bug fix EXTRA: `superpowers:systematic-debugging` + `investigate-bug` skill first.
-
----
-
-### GATE 4 — AI Self-Review (wait for APPROVED)
-
-**INVOKE:** `review-plan` skill
-
-Mandatory order:
-1. `superpowers:verification-before-completion` — all tests must PASS
-2. `impact-analysis` skill — check for breaking changes
-3. `custom/rules/review-checklist.md` — tick each item
-4. Create `plan/[ticket-id]/summary.md`
-
-Then: "GATE 4 PAUSED: type APPROVED or BUG: [description]"
-- Coding bug -> fix -> repeat Gate 4.
-- Requirement bug -> return to Gate 1.
-
----
-
-### GATE 5 — Peer Review and Done
-
-Only runs after Gate 4 has been APPROVED.
-
-**INVOKE:** `superpowers:requesting-code-review`
-Guide on creating a Pull Request with the ticket link.
-
----
-
-- Use `<script setup lang="ts">` with Composition API exclusively. Do not use the Options API.
-- Use explicit Nuxt auto-imports where appropriate, but maintain clarity on complex utilities.
-- For state management, prefer Pinia or native `useState` bindings in Nuxt.
-- Use `useFetch` or `useAsyncData` for server-side data fetching. Use `$fetch` for client-side API requests outside component initialization.
-- Keep components small and specialized.
-- Adhere to the official Vue Style Guide (Priority A and B).
-
-Ensure code is strictly typed with TypeScript.
+# Vue/Nuxt.js AI System Prompt
+
+You are an expert Vue.js & Nuxt 3 developer. Follow these rules.
+
+---
+
+- Use `<script setup lang="ts">` with Composition API exclusively. Do not use the Options API.
+- Use explicit Nuxt auto-imports where appropriate, but maintain clarity on complex utilities.
+- For state management, prefer Pinia or native `useState` bindings in Nuxt.
+- Use `useFetch` or `useAsyncData` for server-side data fetching. Use `$fetch` for client-side API requests outside component initialization.
+- Keep components small and specialized.
+- Adhere to the official Vue Style Guide (Priority A and B).
+
+Ensure code is strictly typed with TypeScript.

package/docs/ai-integration.md

@@ -0,0 +1,53 @@
+# Multi-AI Environment Integration
+
+`ai-flow-kit` is designed to be tool-agnostic. While it works best with Claude Code CLI due to deep MCP integration, you can use it with any AI tool.
+
+## Supported Environments
+
+| Tool | Instruction File | Support Level | Key Features |
+|------|------------------|---------------|--------------|
+| **Claude Code** | `CLAUDE.md` | Native (Best) | Auto-triggers, full MCP access, session hooks. |
+| **Cursor** | `.cursorrules` | High | Project-wide rules, `@Codebase` context. |
+| **Gemini CLI** | `GEMINI.md` | Medium | System instructions support. |
+| **GitHub Copilot** | `.github/copilot-instructions.md` | Medium | Inline suggestions, custom instructions. |
+| **OpenCode / Generic** | `AI_INSTRUCTIONS.md` | General | Manual context loading. |
+
+---
+
+## Tool-Specific Setup
+
+### 1. Cursor AI
+When you run `aiflow init`, it generates a `.cursorrules` file. 
+- Cursor will automatically read this file to understand the **Gate Workflow**.
+- Use `@Codebase` when you need the AI to search across your whole project.
+- **Resumption**: If you start a task in Claude Code and switch to Cursor, Cursor will see the generated `plan/` files and resume from where you left off.
+
+### 2. Gemini CLI
+Pass `GEMINI.md` as system instructions to your Gemini session.
+- **Tip**: Always ensure the AI reads `.claude/context/current.json` first to load the ticket context.
+- Gemini is excellent for large context analysis during Gate 1.
+
+### 3. GitHub Copilot / Codex
+Copilot uses `.github/copilot-instructions.md` to guide its suggestions.
+- This ensures that Copilot's inline completions follow your project's architecture and team rules.
+
+---
+
+## Cross-Tool State Resumption
+The "Secret Sauce" of `ai-flow-kit` is its file-based state management:
+
+1. **Context**: Saved in `.claude/context/current.json`.
+2. **Progress**: Saved as Markdown docs in `plan/[ticket-id]/`.
+3. **Rules**: Saved in `.rules/`.
+
+Because these are standard files, any AI tool can read them. You can:
+1. Start **Gate 1** (Analysis) in Claude Code.
+2. Review and **Approve** the requirement doc.
+3. Switch to **Cursor** for **Gate 3** (Coding) because you prefer the IDE integrations.
+4. Switch back to **Claude Code** for **Gate 4** (Self-Review) to use its automated testing power.
+
+---
+
+## Best Practices
+- **Always Approve Docs**: Ensure `requirement.md` and `plan.md` are approved (you can just type "APPROVED" in the chat or edit the file to say so).
+- **Update Status**: If you make progress in a tool that doesn't have hooks, manually update the `summary.md` or the ticket status.

package/docs/developer-overview.md

@@ -0,0 +1,122 @@
+# AI Flow Kit — Developer Rollout Guide
+
+Welcome to the **AI Flow Kit**! This guide is designed to get you up and running with our standardized AI development workflow.
+
+## 1. What is AI Flow Kit?
+
+It's a "Zero-Config" framework for AI-assisted development. It automatically:
+- Pulls ticket context (requirements, comments) from Backlog/Jira.
+- Orchestrates a **5-Gate Workflow** (Analyze → Plan → Code → Review → PR).
+- Enforces team coding standards and architecture rules.
+- Synchronizes state across different AI tools (Claude, Cursor, Gemini).
+
+---
+
+## 2. Prerequisites
+
+Before starting, ensure you have:
+1. **Node.js** (v18 or higher).
+2. **AI Tool(s)**:
+   - **Claude Code CLI** (Recommended for analysis and heavy tasks).
+   - **Cursor AI** (Recommended for coding and UI work).
+   - **Gemini CLI** or **GitHub Copilot** (Alternative options).
+
+---
+
+## 3. Installation
+
+Run this command to install the CLI tool globally:
+
+```bash
+npm install -g @relipa/ai-flow-kit
+```
+
+Verify installation:
+```bash
+aiflow --version
+```
+
+---
+
+## 4. First-time Setup
+
+In your project root, run:
+
+```bash
+aiflow init --framework [your-framework] --adapter [backlog/jira]
+```
+*Example: `aiflow init --framework nestjs --adapter backlog`*
+
+**What this does:**
+1. Verifies your API keys.
+2. Creates instruction files: `CLAUDE.md`, `.cursorrules`, `GEMINI.md`.
+3. Installs "Superpowers" skills.
+
+---
+
+## 5. Daily Task Workflow (The 5 Gates)
+
+### Step 1: Start a Task
+Load the ticket context from your issue tracker:
+```bash
+aiflow use PROJ-33
+```
+
+### Step 2: Open your AI Tool
+- **Claude Code**: Type `claude`. The AI will automatically start **Gate 1**.
+- **Cursor**: Just start chatting with Cursor. It will detect the active ticket and start analyzing.
+
+### Step 3: Follow the Gates
+The AI *must* pass each gate in order. You act as the **Reviewer**.
+
+1. **⛩️ Gate 1: Requirement Analysis**
+   - AI reads code + ticket.
+   - AI outputs `plan/PROJ-33/requirement.md`.
+   - **Your Action**: Read the doc. If OK, type `APPROVED`.
+
+2. **⛩️ Gate 2: Implementation Plan**
+   - AI creates a step-by-step TDD plan.
+   - **Your Action**: Type `APPROVED` to start coding.
+
+3. **⛩️ Gate 3: Coding (TDD)**
+   - AI writes tests first, then code.
+   - **Your Action**: Monitor.
+
+4. **⛩️ Gate 4: Self-Review**
+   - AI verifies tests and checks a review-checklist.
+   - **Your Action**: Review the final diff. If OK, type `APPROVED`.
+
+5. **⛩️ Gate 5: Pull Request**
+   - AI helps you write a detailed PR description.
+   - **Your Action**: Create the PR and ask for a peer review.
+
+---
+
+## 6. Switching AI Tools Mid-Task
+
+You can switch tools at any time because the "brain" (the State) is stored in your project files.
+
+**Example Scenario:**
+1. Use **Claude Code CLI** for **Gate 1** (Analysis) because it's great at exploring many files.
+2. Once you type `APPROVED`, close Claude.
+3. Open **Cursor** for **Gate 3** (Coding) to take advantage of its excellent editor integration. Cursor will see you've already finished the analysis and will continue from the plan.
+
+---
+
+## 7. Best Practices
+
+- **One question at a time**: If the AI asks 5 questions, answer them one by one or ignore the irrelevant ones.
+- **Small commits**: Let the AI commit frequently (default behavior).
+- **Be the Pilot**: The AI is your co-pilot. If its solution looks over-engineered, tell it: *"Simplify this by using [X] pattern"*.
+
+---
+
+## 8. Troubleshooting
+
+- **AI is stuck**: Type `reset context` or use `aiflow doctor` to check setup.
+- **Credentials fail**: Re-run `aiflow init --adapter backlog` to update keys.
+- **Rules not followed**: Remind the AI: *"Follow the rules in CLAUDE.md"*.
+
+---
+
+**Happy Coding!** สำหรับรายละเอียดเชิงลึก โปรดดู [AIFLOW.md](../AIFLOW.md).

package/package.json

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

package/scripts/init.js

@@ -15,6 +15,14 @@ const FRAMEWORK_LANGUAGE = {
     'vue-nuxt':     'javascript',
 };
 
+const AI_TOOL_FILES = {
+    'claude':   'CLAUDE.md',
+    'cursor':   '.cursorrules',
+    'gemini':   'GEMINI.md',
+    'copilot':  '.github/copilot-instructions.md',
+    'generic':  'AI_INSTRUCTIONS.md'
+};
+
 async function copyAssetsToVersion(versionDir, framework) {
     // ── Skills: merge upstream + custom ──────────────────────────────
     const upstreamSkills = path.join(PKG_DIR, 'upstream', 'skills');
@@ -135,34 +143,62 @@ async function verifySuperpowersSkills(versionDir) {
 }
 
 /**
- * Setup CLAUDE.md for a framework.
+ * Setup AI instruction files (CLAUDE.md, .cursorrules, etc.) for a framework.
  * If multi=true (multiple frameworks), append instead of overwrite.
  */
-async function setupFramework(projectDir, framework, multi = false) {
+async function setupFramework(projectDir, framework, multi = false, selectedTools = Object.keys(AI_TOOL_FILES)) {
     if (!framework) return;
-    const templatePath = path.join(PKG_DIR, 'custom', 'templates', `${framework}.md`);
-    if (!(await fs.pathExists(templatePath))) {
+    const frameworkTemplatePath = path.join(PKG_DIR, 'custom', 'templates', `${framework}.md`);
+    if (!(await fs.pathExists(frameworkTemplatePath))) {
         console.log(chalk.yellow(`! No template found for framework: ${framework}`));
         return;
     }
 
-    const claudeMdPath = path.join(projectDir, 'CLAUDE.md');
+    const frameworkContent = await fs.readFile(frameworkTemplatePath, 'utf-8');
+    const workflowPath = path.join(PKG_DIR, 'custom', 'templates', 'shared', 'gate-workflow.md');
+    const workflowContent = (await fs.pathExists(workflowPath))
+        ? await fs.readFile(workflowPath, 'utf-8')
+        : '';
 
-    if (!multi) {
-        // Single framework → overwrite
-        await fs.copy(templatePath, claudeMdPath);
-    } else {
-        // Multiple frameworks → append with separator
-        const content = await fs.readFile(templatePath, 'utf-8');
-        const separator = `\n\n---\n\n`;
-        if (await fs.pathExists(claudeMdPath)) {
-            await fs.appendFile(claudeMdPath, separator + content);
+    const separator = `\n\n---\n\n`;
+
+    for (const tool of selectedTools) {
+        const targetPath = path.join(projectDir, AI_TOOL_FILES[tool]);
+        if (!targetPath) continue;
+
+        // Ensure subdirectories exist (e.g. .github/)
+        await fs.ensureDir(path.dirname(targetPath));
+
+        let finalContent = '';
+
+        // 1. Tool Header (e.g. Cursor AI Instructions)
+        const toolTemplatePath = path.join(PKG_DIR, 'custom', 'templates', 'tools', `${tool}.md`);
+        if (await fs.pathExists(toolTemplatePath)) {
+            finalContent += await fs.readFile(toolTemplatePath, 'utf-8') + '\n\n';
+        }
+
+        // 2. Shared Gate Workflow (MANDATORY)
+        if (workflowContent) {
+            finalContent += workflowContent + '\n\n';
+        }
+
+        // 3. Framework Rules
+        finalContent += frameworkContent;
+
+        if (!multi) {
+            // Single framework → overwrite
+            await fs.writeFile(targetPath, finalContent);
         } else {
-            await fs.writeFile(claudeMdPath, content);
+            // Multiple frameworks → append
+            if (await fs.pathExists(targetPath)) {
+                await fs.appendFile(targetPath, separator + frameworkContent);
+            } else {
+                await fs.writeFile(targetPath, finalContent);
+            }
         }
     }
 
-    console.log(chalk.green(`✓ CLAUDE.md updated for framework: ${framework}`));
+    console.log(chalk.green(`✓ AI instruction files updated for framework: ${framework} (${selectedTools.join(', ')})`));
 }
 
 async function setupAdapter(projectDir, adapter) {
@@ -420,9 +456,10 @@ module.exports = async function init(options) {
         await verifySuperpowersSkills(versionDir);
         await updateSymlinks(projectDir, versionDir);
 
-        // Setup each framework (CLAUDE.md = last one wins, or merged)
+        // Setup each framework
+        const selectedTools = options.aiTools || Object.keys(AI_TOOL_FILES);
         for (const fw of frameworks) {
-            await setupFramework(projectDir, fw, frameworks.length > 1);
+            await setupFramework(projectDir, fw, frameworks.length > 1, selectedTools);
         }
 
         // Setup each adapter
@@ -443,7 +480,8 @@ module.exports = async function init(options) {
         console.log(chalk.blue('\n' + '─'.repeat(62)));
         console.log(chalk.bold.white('  Next steps:'));
         console.log(`  ${chalk.green('aiflow use PROJ-33')}    ${chalk.gray('← load ticket context')}`);
-        console.log(`  ${chalk.green('claude')}                ${chalk.gray('← AI auto-starts analyzing requirement')}`);
+        console.log(`  ${chalk.green('claude')}                ${chalk.gray('← Use Claude Code CLI (recommended)')}`);
+        console.log(`  ${chalk.green('Cursor / Gemini')}       ${chalk.gray('← Instructions loaded in .cursorrules / GEMINI.md')}`);
         console.log(chalk.blue('─'.repeat(62)));
         console.log(chalk.gray(`  Full guide: ${chalk.green('aiflow guide')} | Command list: ${chalk.green('aiflow guide --commands')}`));
         console.log(chalk.blue('─'.repeat(62)) + '\n');

package/scripts/prompt.js

@@ -278,7 +278,8 @@ module.exports = async function generatePrompt(type, options = {}) {
     const template = PROMPT_TEMPLATES[resolvedType];
     const rules    = await loadRules();
 
-    const prompt = buildPrompt(template, ctx, rules, options);
+    const env = options.env || 'claude';
+    const prompt = buildPrompt(template, ctx, rules, options, env);
 
     if (options.output) {
         await fs.writeFile(options.output, prompt, 'utf-8');
@@ -309,7 +310,7 @@ async function loadRules() {
     return parts.join('\n\n');
 }
 
-function buildPrompt(template, ctx, rules, options) {
+function buildPrompt(template, ctx, rules, options, env = 'claude') {
     const lang   = options.lang   || 'english';
     const detail = options.detail || 'standard';
 
@@ -388,5 +389,14 @@ function buildPrompt(template, ctx, rules, options) {
         lines.push('');
     }
 
+    // ── Tool-specific instructions ───────────────────────────────
+    if (env === 'cursor') {
+        lines.push('---');
+        lines.push('> **Cursor Tip:** You can use `@Codebase` to search for more context if needed.');
+    } else if (env === 'gemini') {
+        lines.push('---');
+        lines.push('> **Gemini Tip:** Use the "Upload Files" or "Attach File" feature to provide source code context.');
+    }
+
     return lines.join('\n');
 }