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

package/README.md

@@ -23,10 +23,9 @@ Developers only need a single command to load ticket context → AI automaticall
 > [!TIP]
 > After running `aiflow init`, all documentation files are automatically copied to your project root and `.aiflow/docs/` for easy access.
 
-- **[Quick Start Guide](./QUICK_START.md)** — Step-by-step instructions for developers.
-- **[Full Workflow (5 Gates)](./AIFLOW.md)** — In-depth look at the Gate process.
+- **[Quick Start Guide](./docs/QUICK_START.md)** — Step-by-step instructions for developers.
+- **[Full Workflow (5 Gates)](./docs/AIFLOW.md)** — In-depth look at the Gate process.
 - **[Developer Onboarding](./docs/developer-overview.md)** — Presentation-ready guide for new team members.
-- **[Contributing Guide](./CONTRIBUTING.md)** — How to extend with new skills/templates.
 - **[Troubleshooting](./docs/troubleshooting.md)** — Common issues and fixes.
 - **[Integration Guide](./docs/ai-integration.md)** — Advanced tool setup (Claude, Cursor, Gemini).
 
@@ -123,6 +122,7 @@ npm uninstall -g @relipa/ai-flow-kit
 | `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 telemetry` | Manage telemetry tracking (enable/disable/status). |
 | `aiflow guide` | View integrated multi-AI integration guide. |
 
 ### `aiflow init`
@@ -281,7 +281,13 @@ aiflow memory --list
 
 ```
 ai-flow-kit/
+├── README.md                        # Main documentation
 ├── bin/aiflow.js                    # CLI entry
+├── docs/                            # Documentation and Guides
+│   ├── QUICK_START.md               # Quick start guide
+│   ├── AIFLOW.md                    # Workflow (5 Gates) detail
+│   ├── CHANGELOG.md                 # Version history
+│   └── ...                          # Other guides
 ├── scripts/
 │   ├── init.js                      # Project initialization
 │   ├── update.js                    # Version management
@@ -297,7 +303,7 @@ ai-flow-kit/
 │   ├── rules/java/                  # Java/Spring Boot rules
 │   ├── rules/php/                   # PHP/Laravel rules
 │   ├── rules/javascript/            # JS/TS rules
-│   ├── templates/                   # Framework CLAUDE.md templates
+│   ├── templates/                   # Framework tool templates
 │   ├── prompts/                     # Task prompt templates
 │   └── mcp-presets/                 # Backlog/Jira/Sheets config
 └── upstream/                        # obra/superpowers (inherited)

package/bin/aiflow.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 const { program } = require('commander');
 const chalk = require('chalk');
@@ -14,11 +14,45 @@ const contextCommand  = require('../scripts/context');
 const promptCommand   = require('../scripts/prompt');
 const removeCommand   = require('../scripts/remove');
 const guideCommand    = require('../scripts/guide');
+const telemetryCommand= require('../scripts/telemetry/cli');
+const { record }      = require('../scripts/telemetry/record');
 
 program
     .version(packageJson.version)
     .description('AI Flow Kit CLI - AI-powered development workflows for teams');
 
+// ── GLOBAL TELEMETRY HOOK ────────────────────────────────────
+// We intercept raw argv here so we can catch --version, --help, 
+// and invalid commands *before* Commander exits the process.
+(() => {
+    const args = process.argv.slice(2);
+    let cmd = 'help';
+    if (args.length > 0) {
+        const first = args[0];
+        if (['-V', '-v', '--version'].includes(first)) {
+            cmd = 'version';
+        } else if (['-h', '--help'].includes(first)) {
+            cmd = 'help';
+        } else if (first.startsWith('-')) {
+            cmd = 'unknown_flag';
+            if (args.includes('--help') || args.includes('-h')) cmd = 'help';
+        } else if (first === 'memory') {
+            const sec = args[1];
+            cmd = (sec && !sec.startsWith('-')) ? `memory.${sec}` : 'memory';
+        } else {
+            cmd = first;
+            if (args.includes('--help') || args.includes('-h')) {
+                cmd = `${first}.help`;
+            }
+        }
+    }
+    // Record everything except telemetry and gate actions (gate records its own rich event)
+    if (cmd !== 'telemetry' && !cmd.startsWith('telemetry.') && cmd !== 'gate') {
+        record('command.invoked', { command: cmd });
+    }
+})();
+
+
 // ── init ──────────────────────────────────────────────────────
 program
     .command('init')
@@ -37,6 +71,7 @@ program
             ? options.env.split(',').map(s => s.trim()).filter(Boolean)
             : Object.keys(require('../scripts/init').AI_TOOL_FILES || {});
 
+        record('command.invoked', { command: 'init' });
         initCommand(options);
     });
 
@@ -51,6 +86,7 @@ program
     .option('--comments-last <n>', 'load only the last N comments', parseInt)
     .option('--comments-from <n>', 'load comments from index N onward (0-based)', parseInt)
     .action((target, options) => {
+        record('command.invoked', { command: 'use' });
         useCommand(target, options);
     });
 
@@ -63,6 +99,7 @@ program
     .option('--lang <lang>', 'language: english (default) or vietnamese')
     .option('--detail <level>', 'detail level: minimal | standard (default) | comprehensive')
     .action((type, options) => {
+        record('command.invoked', { command: 'prompt' });
         promptCommand(type, options);
     });
 
@@ -73,6 +110,7 @@ program
     .option('-v, --verbose', 'show detection details')
     .option('-t, --threshold <number>', 'confidence threshold (0-100)')
     .action((description, options) => {
+        record('command.invoked', { command: 'detect' });
         const detector = new TaskDetector();
         const threshold = options.threshold ? parseInt(options.threshold) / 100 : 0.8;
         const result = detector.detect(description, threshold);
@@ -90,6 +128,7 @@ program
     .option('--clear', 'clear all saved contexts')
     .option('--show', 'show current context')
     .action((action, options) => {
+        record('command.invoked', { command: 'context' });
         contextCommand(action, options);
     });
 
@@ -101,6 +140,7 @@ program
     .option('-v, --verbose', 'detailed report')
     .option('--fix', 'auto-fix trailing whitespace')
     .action((file, options) => {
+        record('command.invoked', { command: 'validate' });
         validateCommand(file, {
             ruleset: options.ruleset,
             verbose: options.verbose,
@@ -115,32 +155,32 @@ const memCmd = program.command('memory').description('Manage team knowledge and
 memCmd
     .command('save <key> <value>')
     .description('Save a memory entry')
-    .action((key, value) => memoryCommand('save', { key, value }));
+    .action((key, value) => { record('command.invoked', { command: 'memory.save' }); memoryCommand('save', { key, value }); });
 
 memCmd
     .command('get <key>')
     .description('Retrieve a memory entry')
-    .action((key) => memoryCommand('get', { key }));
+    .action((key) => { record('command.invoked', { command: 'memory.get' }); memoryCommand('get', { key }); });
 
 memCmd
     .command('list')
     .description('List all memories')
-    .action(() => memoryCommand('list'));
+    .action(() => { record('command.invoked', { command: 'memory.list' }); memoryCommand('list'); });
 
 memCmd
     .command('search <query>')
     .description('Search memories by keyword')
-    .action((query) => memoryCommand('search', { query }));
+    .action((query) => { record('command.invoked', { command: 'memory.search' }); memoryCommand('search', { query }); });
 
 memCmd
     .command('delete <key>')
     .description('Delete a memory entry')
-    .action((key) => memoryCommand('delete', { key }));
+    .action((key) => { record('command.invoked', { command: 'memory.delete' }); memoryCommand('delete', { key }); });
 
 memCmd
     .command('clear')
     .description('Clear all memories')
-    .action(() => memoryCommand('clear'));
+    .action(() => { record('command.invoked', { command: 'memory.clear' }); memoryCommand('clear'); });
 
 // ── guide ─────────────────────────────────────────────────────
 program
@@ -149,9 +189,28 @@ program
     .option('--flow', 'show architecture & flow diagram only')
     .option('--commands', 'show command reference only')
     .action((options) => {
+        record('command.invoked', { command: 'guide' });
         guideCommand(options);
     });
 
+// ── gate (telemetry for gate workflow events) ─────────────────
+program
+    .command('gate <number> <action>')
+    .description('Log a gate workflow event (start|approved) — called by AI during gate workflow')
+    .option('--ticket <id>', 'ticket ID')
+    .option('--ai-tool <tool>', 'AI tool name')
+    .action((number, action, options) => {
+        const gateNum = parseInt(number);
+        if (isNaN(gateNum) || gateNum < 1 || gateNum > 5) return;
+        if (!['start', 'approved'].includes(action)) return;
+        record(`gate.${action}`, {
+            gate: gateNum,
+            ticket_id: options.ticket || '',
+            command: `gate${gateNum}.${action}`,
+            ai_tool: options.aiTool || ''
+        });
+    });
+
 // ── remove ────────────────────────────────────────────────────
 program
     .command('remove')
@@ -159,6 +218,7 @@ program
     .option('--version <ver>', 'remove a specific cached version from .aiflow/versions/')
     .option('--global', 'uninstall the global npm package (removes `aiflow` command)')
     .action((options) => {
+        record('command.invoked', { command: 'remove' });
         removeCommand(options);
     });
 
@@ -168,6 +228,7 @@ program
     .description('Update to latest version')
     .option('--force', 'force update even if already on latest')
     .action((options) => {
+        record('command.invoked', { command: 'update' });
         updateCommand(options);
     });
 
@@ -177,7 +238,16 @@ program
     .description('Health check of AI Flow Kit setup')
     .option('-v, --verbose', 'detailed output')
     .action(() => {
+        record('command.invoked', { command: 'doctor' });
         doctorCommand();
     });
 
+// ── telemetry ──────────────────────────────────────────────────
+program
+    .command('telemetry [action]')
+    .description('Manage telemetry logging (enable|disable|status)')
+    .action((action) => {
+        telemetryCommand(action || 'status');
+    });
+
 program.parse(process.argv);

package/custom/templates/laravel.md

@@ -1,15 +1,15 @@
-# 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.
+# 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

@@ -1,72 +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();
-  });
-});
-```
+# 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,14 +1,14 @@
-# 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.
+# 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

@@ -1,73 +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);
-    });
-});
-```
+# 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);
+    });
+});
+```