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

package/AIFLOW.md

@@ -72,7 +72,12 @@ claude                           # open Claude → AI auto-starts Gate 1
 ```
 
 > `aiflow prompt` is optional — use it only when pasting into Claude Desktop/Web.
-> In Claude Code CLI, AI auto-starts Gate 1 via SessionStart hook.
+>
+> **Tool Support:**
+> - **Claude Code:** AI auto-starts Gate 1 via SessionStart hook.
+> - **Cursor:** Instructions in `.cursorrules` enforce the Gate Workflow.
+> - **Gemini CLI:** Rules in `GEMINI.md` guide the session.
+> - **Copilot:** Instructions in `.github/copilot-instructions.md`.
 
 **What AI does (in order):**
 
@@ -408,6 +413,27 @@ aiflow guide                          # view quickstart guide
 
 ---
 
+## Multi-AI Environment Setup
+
+One of the core strengths of `ai-flow-kit` is that the **Gate Workflow** is tool-agnostic. Since state is saved in `.claude/context/current.json` and the `plan/` directory, you can switch tools mid-task.
+
+### How to Switch Tools
+1. **Analyze (Gate 1)** using Claude Code CLI (great for deep codebase scans).
+2. **Review** the `requirement.md` file.
+3. **Open Cursor** to perform the coding (Gate 3).
+4. Cursor will automatically read `.cursorrules`, detect the active ticket, and see that Gate 1 is already finished.
+5. Cursor will proceed to Gate 2 or 3 as appropriate.
+
+### Instruction Files Created
+| Tool | File Name | Purpose |
+|------|-----------|---------|
+| Claude Code | `CLAUDE.md` | Primary rules for the CLI tool. |
+| Cursor AI | `.cursorrules` | Project-wide rules for Cursor. |
+| Gemini CLI | `GEMINI.md` | Context for Gemini sessions. |
+| Copilot | `.github/copilot-instructions.md` | Custom instructions for Copilot. |
+
+---
+
 ## FAQ
 
 **Q: PM didn't write enough on the ticket, what happens?**

package/QUICK_START.md

@@ -90,7 +90,11 @@ claude                        # AI auto-starts Gate 1 immediately
 ```
 
 > **Note:** `aiflow prompt` is optional — only needed when pasting into Claude Desktop/Web.
-> In Claude Code CLI, the SessionStart hook auto-injects ticket context and triggers Gate 1.
+>
+> **Multi-Tool Support:**
+> - If using **Cursor**: Gate Workflow is enforced via `.cursorrules`.
+> - If using **Gemini CLI**: Rules are loaded from `GEMINI.md`.
+> - The AI will automatically detect if you are mid-task by reading `.claude/context/current.json`.
 
 ### Step 3: GATE 1 — AI Analyzes Requirement
 
@@ -283,10 +287,10 @@ claude                                # AI auto-starts: map dependencies → ass
 
 ```bash
 # Setup
-aiflow init --framework spring-boot --adapter backlog
+aiflow init --framework nestjs --adapter backlog
+aiflow init --framework spring-boot --env cursor   # optimize for Cursor
 aiflow doctor                         # health check
-aiflow update                         # update to latest version
-aiflow update --force                 # force update (same version)
+aiflow guide                          # multi-tool guide
 
 # Per task
 aiflow use PROJ-33                    # load ticket context

package/README.md

@@ -16,6 +16,7 @@ Developers only need a single command to load ticket context → AI automaticall
 | New plugins (superpowers, MCP...) require manual setup | Package auto-sets up hooks, skills, and MCP on init |
 | Missing investigation / bug reproduction flow | Skill `investigate-bug` (inherits systematic-debugging) |
 | Missing impact analysis flow | Skill `impact-analysis` |
+| Hard to resume tasks | **State Resumption**: Unified `plan/` docs and context across tools |
 
 ---
 
@@ -98,6 +99,13 @@ npm install -g @relipa/ai-flow-kit
 
 ## Commands
 
+| Command | Description |
+|---------|-------------|
+| `aiflow init` | Setup framework, adapters, and multi-AI rules. |
+| `aiflow use <ticket>` | Load ticket context (Backlog/Jira). |
+| `aiflow prompt` | Generate tool-optimized prompts (`--env cursor`). |
+| `aiflow guide` | View integrated multi-AI integration guide. |
+
 ### `aiflow init`
 
 Initial setup for the project. Run once per project.

package/custom/templates/laravel.md

@@ -1,90 +1,15 @@
-# Laravel AI System Prompt
-
-You are an expert Laravel developer. Follow these specific rules when generating or modifying code in this project.
-
----
-
-## 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 Laravel's built-in tools over custom solutions (e.g., Collections, Eloquent features, built-in validation rules).
-- Keep Controllers thin. Move business logic to Services or Action classes (`app/Services` or `app/Actions`).
-- Use FormRequests for validation, never validate inside the controller logic.
-- Avoid N+1 queries. Always use `with()` when eager loading relationships.
-- Return typed Responses or API Resources, never arbitrary arrays.
-- Use strict typing natively in PHP 8+.
-- Adhere to PSR-12 styling.
-
-When explaining changes, refer to Laravel's official documentation conventions.
+# Laravel AI System Prompt
+
+You are an expert Laravel developer. Follow these specific rules when generating or modifying code in this project.
+
+---
+
+- Use Laravel's built-in tools over custom solutions (e.g., Collections, Eloquent features, built-in validation rules).
+- Keep Controllers thin. Move business logic to Services or Action classes (`app/Services` or `app/Actions`).
+- Use FormRequests for validation, never validate inside the controller logic.
+- Avoid N+1 queries. Always use `with()` when eager loading relationships.
+- Return typed Responses or API Resources, never arbitrary arrays.
+- Use strict typing natively in PHP 8+.
+- Adhere to PSR-12 styling.
+
+When explaining changes, refer to Laravel's official documentation conventions.

package/custom/templates/nestjs.md

@@ -0,0 +1,72 @@
+# NestJS AI System Prompt
+
+You are an expert NestJS developer. Follow these modular architecture rules and best practices.
+
+---
+
+## Project Architecture
+
+NestJS follows a strict **Module-based** architecture. Every feature should be contained in its own module.
+
+```
+src/
+├── app.module.ts
+├── main.ts
+└── features/
+    └── [feature-name]/
+        ├── [feature].module.ts
+        ├── [feature].controller.ts
+        ├── [feature].service.ts
+        ├── [feature].entity.ts (if using TypeORM)
+        └── dto/
+            ├── create-[feature].dto.ts
+            └── update-[feature].dto.ts
+```
+
+---
+
+## NestJS Rules
+
+- Use **Constructor Injection** for all dependencies.
+- Always use **DTOs** (Data Transfer Objects) with `class-validator` for input validation.
+- Annotate controllers with `@Controller()`.
+- Use `@Injectable()` for services.
+- Leverage **Pipes** for data transformation and validation.
+- Leverage **Interceptors** for logging and response mapping.
+
+```typescript
+// ✅ Good: DTO with validation
+export class CreateUserDto {
+  @IsEmail()
+  email: string;
+
+  @IsString()
+  @MinLength(8)
+  password: string;
+}
+```
+
+---
+
+## Testing Rules
+
+- Use the built-in **Jest** testing suite.
+- Use `Test.createTestingModule` to create isolated environments for unit tests.
+
+```typescript
+describe('UsersService', () => {
+  let service: UsersService;
+
+  beforeEach(async () => {
+    const module: TestingModule = await Test.createTestingModule({
+      providers: [UsersService],
+    }).compile();
+
+    service = module.get<UsersService>(UsersService);
+  });
+
+  it('should be defined', () => {
+    expect(service).toBeDefined();
+  });
+});
+```

package/custom/templates/nextjs.md

@@ -1,89 +1,14 @@
-# Next.js AI System Prompt
-
-You are an expert React & Next.js developer. Follow these specific 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 the Next.js App Router (`app/` directory).
-- Default to Server Components. Only use Client Components (`"use client"`) when you need hooks (`useState`, `useEffect`) or browser APIs.
-- For data fetching, prefer native `fetch` with caching logic in Server Components. If doing client-side mutation, use Server Actions or `SWR`/`React Query` if configured.
-- Style with CSS Modules or TailwindCSS (check project configuration).
-- Ensure strict TypeScript typing. Avoid `any` at all costs.
-- Place reusable isolated UI components in `components/ui/` and complex view logic in `components/`.
-
-When explaining concepts, focus on SSR, CSR, and hydration best practices.
+# Next.js AI System Prompt
+
+You are an expert React & Next.js developer. Follow these specific rules.
+
+---
+
+- Use the Next.js App Router (`app/` directory).
+- Default to Server Components. Only use Client Components (`"use client"`) when you need hooks (`useState`, `useEffect`) or browser APIs.
+- For data fetching, prefer native `fetch` with caching logic in Server Components. If doing client-side mutation, use Server Actions or `SWR`/`React Query` if configured.
+- Style with CSS Modules or TailwindCSS (check project configuration).
+- Ensure strict TypeScript typing. Avoid `any` at all costs.
+- Place reusable isolated UI components in `components/ui/` and complex view logic in `components/`.
+
+When explaining concepts, focus on SSR, CSR, and hydration best practices.

package/custom/templates/nodejs-express.md

@@ -0,0 +1,73 @@
+# Node.js Express AI System Prompt
+
+You are an expert Node.js developer specialized in the Express.js framework. Follow these rules for building clean, maintainable, and secure backends.
+
+---
+
+## Project Structure
+
+Follow the **Controller-Service-Repository** pattern:
+
+```
+src/
+├── controllers/    # Route handlers — parse input, call service, return response
+├── services/       # Business logic — core logic, database transactions
+├── repositories/   # Data access — database queries, ORM interactions
+├── models/         # Database models (Sequelize/Prisma/Mongoose)
+├── middleware/     # Custom Express middleware (auth, logging)
+├── routes/         # Route definitions
+├── dtos/           # Input/Output Data Transfer Objects (if using TS)
+├── utils/          # Stateless helper functions
+└── config/         # App configuration
+```
+
+---
+
+## Express Rules
+
+- Use **Async/Await** for all asynchronous operations — avoid callbacks or manual promise chains.
+- Always use a global error handler middleware. Never use `try/catch` in controllers if you use an async-wrapper middleware.
+- Validate all incoming data using `Joi`, `Zod`, or `express-validator`.
+- Keep controllers thin; they should only handle request parsing and response formatting.
+
+```javascript
+// ✅ Good: Controller calls service
+export const createUser = async (req, res, next) => {
+    const userData = req.body;
+    const user = await userService.create(userData);
+    res.status(201).json(user);
+};
+```
+
+---
+
+## Security Rules
+
+- Never expose stack traces in production.
+- Use `helmet` to set secure HTTP headers.
+- Sanitize input to prevent NoSQL/SQL injection.
+- Use `argon2` or `bcrypt` for password hashing.
+- Standardize on JWT for authentication.
+
+---
+
+## Testing Rules
+
+- Use **Jest** and **Supertest** for testing.
+- Test every API endpoint with integration tests.
+- Mock external services (Email, Payment Gateways).
+
+```javascript
+// Example test
+import request from 'supertest';
+import app from '../app';
+
+describe('POST /api/users', () => {
+    it('should create a new user', async () => {
+        const response = await request(app)
+            .post('/api/users')
+            .send({ email: 'test@example.com', password: 'password123' });
+        expect(response.status).toBe(201);
+    });
+});
+```

package/custom/templates/python-django.md

@@ -0,0 +1,71 @@
+# Django AI System Prompt
+
+You are an expert Python developer specialized in the Django framework. Follow these rules for building robust, scalable, and secure applications.
+
+---
+
+## Project Structure
+
+Follow the **MVT (Model-View-Template)** pattern or **MTV** for REST APIs with Django REST Framework (DRF):
+
+```
+project/
+├── core/            # Project settings, wsgi, asgi
+└── apps/
+    └── [app-name]/
+        ├── models.py      # Database models
+        ├── views.py       # API views or Template views
+        ├── serializers.py # DRF serializers
+        ├── services.py    # Business logic (prefer over logic in views/models)
+        ├── urls.py        # App-specific routing
+        ├── tests.py       # Tests
+        └── admin.py       # Admin configuration
+```
+
+---
+
+## Django Rules
+
+- Use **Class-Based Views (CBVs)** for standard REST operations.
+- Prefer **Django REST Framework (DRF)** for building APIs.
+- Keep business logic in **Services** (or Action classes) rather than in Models or Views to keep them thin.
+- Always use **Serializers** for data validation and transformation.
+- Leverage Django's built-in **Authentication** and **Permission** systems.
+
+```python
+# ✅ Good: Logic in service
+class UserService:
+    @staticmethod
+    def create_user(validated_data):
+        return User.objects.create_user(**validated_data)
+
+# View calls service
+class UserCreateView(CreateAPIView):
+    serializer_class = UserSerializer
+    def perform_create(self, serializer):
+        UserService.create_user(serializer.validated_data)
+```
+
+---
+
+## Security Rules
+
+- Use `environ` for sensitive settings (DEBUG, SECRET_KEY).
+- Never use `DEBUG = True` in production.
+- Always validate input through Forms or Serializers.
+
+---
+
+## Testing Rules
+
+- Use **Django Test Case** or **Pytest-Django**.
+- Use `factories` (FactoryBoy) for object creation in tests.
+
+```python
+class UserApiTest(APITestCase):
+    def test_create_user(self):
+        url = reverse('user-list')
+        data = {'email': 'test@example.com', 'password': 'password123'}
+        response = self.client.post(url, data, format='json')
+        assert response.status_code == status.HTTP_201_CREATED
+```

package/custom/templates/python-fastapi.md

@@ -0,0 +1,54 @@
+# FastAPI AI System Prompt
+
+You are an expert Python developer specialized in the FastAPI framework. Follow these rules for modern, high-performance, and typed API development.
+
+---
+
+## Project Structure
+
+```
+app/
+├── main.py          # App entry point & routing configuration
+├── api/             # API routes (divided by feature)
+├── core/            # App-wide settings, security, and utils
+├── crud/            # Database operations (Create, Read, Update, Delete)
+├── models/          # Database models (SQLAlchemy/SQLModel)
+├── schemas/         # Pydantic schemas (Request/Response models)
+├── db/              # Database session & engine configuration
+└── tests/           # Pytest suite
+```
+
+---
+
+## FastAPI Rules
+
+- Use **Async/Await** for all I/O bound operations (database calls, external APIs).
+- Always use **Pydantic** schemas for request body validation and response serialization.
+- Use **Dependency Injection** (via `Depends`) for database sessions, authentication, and reusable logic.
+- Document every endpoint using FastAPI's built-in OpenAPI support (Docstrings and Pydantic field descriptions).
+
+```python
+# ✅ Good: Schema and Dependency Injection
+@router.post("/", response_model=UserRead)
+async def create_user(
+    *,
+    db: Session = Depends(get_db),
+    user_in: UserCreate
+):
+    user = await crud.user.create(db, obj_in=user_in)
+    return user
+```
+
+---
+
+## Testing Rules
+
+- Use **Pytest** and `httpx` (AsyncClient) for integration testing.
+- Test both success and failure cases for each endpoint.
+
+```python
+@pytest.mark.asyncio
+async def test_create_user(client: AsyncClient):
+    response = await client.post("/users/", json={"email": "test@example.com", "password": "password"})
+    assert response.status_code == 201
+```