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

package/custom/templates/tools/copilot.md

@@ -0,0 +1,8 @@
+# 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.
+
+If the Gate Workflow hasn't started, wait for the developer to type **"start"** or **"Gate 1"**.

package/custom/templates/tools/cursor.md

@@ -0,0 +1,8 @@
+# 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.
+
+If Gate 1 doesn't auto-start, wait for the developer to type **"start"**, **"Gate 1"** or **"Analyze ticket"**.

package/custom/templates/tools/gemini.md

@@ -0,0 +1,8 @@
+# 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.
+
+If no instructions are automatically followed, wait for the developer to type **"start"** or **"Gate 1"** to start the analysis.

package/custom/templates/tools/generic.md

@@ -0,0 +1,12 @@
+# 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.
+
+If Gate 1 does not start automatically, please start it when the developer types **"Gate 1"**.

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,126 @@
+# 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
+# Stable version
+npm install -g @relipa/ai-flow-kit
+
+# Beta version (recommend for newest features)
+npm install -g @relipa/ai-flow-kit@beta
+
+# Verification
+aiflow --version
+
+# Uninstall
+npm uninstall -g @relipa/ai-flow-kit
+
+---
+
+## 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",
+  "version": "0.0.4-beta.2",
   "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/hooks/session-start.js

@@ -134,7 +134,8 @@ function buildContextPrompt(ctx) {
     lines.push('6. Display GATE 1 prompt and wait for APPROVED');
     lines.push('');
     lines.push('DO NOT wait for the developer to ask. START NOW.');
+    lines.push('If you have not started automatically, begin as soon as the developer types **"start"**.');
     lines.push('</ACTIVE_TASK>');
 
     return lines.join('\n');
-}
+}