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

package/docs/{CHANGELOG.md → common/CHANGELOG.md}

@@ -1,100 +1,132 @@
-# Changelog
-
-All notable changes to **@relipa/ai-flow-kit** will be documented in this file.
-
-Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
-Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
----
-
-## [0.0.4-beta.5] - 2026-04-21
-
-### Added
-- Created a dedicated `docs/` folder to house all developer-facing documentation.
-- Integrated AI Skill Registry into all tool templates (Claude, Cursor, Gemini, Copilot) for better skill discovery.
-
-### Changed
-- Moved `README.md`, `QUICK_START.md`, `AIFLOW.md`, `CHANGELOG.md`, and `IMPLEMENTATION_SUMMARY.md` into the `docs/` directory.
-- Updated `package.json` to exclude internal-only files (`CONTRIBUTING.md`, `plan.md`) from the NPM package distribution.
-- Updated `scripts/init.js` to source documentation from the new `docs/` location.
-- Updated all internal documentation links to reflect the new directory structure.
-
----
-
-## [Unreleased]
-
----
-
-## [0.0.3-beta.0] - 2026-04-13
-### Security
-- Removed internal GitLab repository links and tracking information.
-- Cleaned `.npmrc` configuration.
-- Added helper scripts for beta and stable releases.
-
-## [0.0.2] - 2026-04-13
-### Changed
-- Updated package to scoped name `@relipa/ai-flow-kit` in documentation and configuration.
-- Fixed installation guides in README and QUICK_START.
-
-## [0.0.1] - 2026-04-13 — Initial Release
-
-### Added
-
-#### CLI (`aiflow`)
-- `aiflow init` — scaffold AI workflow config into any project
-  (supports `--framework` spring-boot/reactjs, `--adapter` jira/backlog)
-- `aiflow use <skill>` — activate a custom skill in the current project
-- `aiflow remove` — cleanly remove `ai-flow-kit` scaffolding from a project
-- `aiflow guide` — interactive onboarding guide
-- `aiflow update` — sync upstream skill/hook updates
-- `aiflow doctor` — validate config, detect missing keys, report issues
-- `aiflow --version` — print installed version
-
-#### 5-Gate AI Workflow
-- **Gate 1 — AI Analyze Requirement**: Auto-starts when a ticket context exists
-  in `.claude/context/current.json`; outputs `plan/[ticket-id]/requirement.md`
-- **Gate 2 — Implementation Plan**: TDD plan generation, gated by `APPROVED`
-- **Gate 3 — Code Generation**: TDD-only, test-first discipline enforced
-- **Gate 4 — AI Self-Review**: Verification + impact analysis + checklist, gated by `APPROVED`
-- **Gate 5 — Peer Review & PR**: Guided PR creation via `requesting-code-review` skill
-
-#### Custom Skills (7 skills)
-- `validate-ticket` — Gate 1 requirement analysis with clarifying Q&A loop
-- `generate-spec` — Gate 2 TDD implementation spec generator
-- `impact-analysis` — breaking-change and dependency impact assessment
-- `investigate-bug` — systematic bug investigation (reproduce → root cause → fix)
-- `report-customer` — customer-facing incident report generator
-- `review-plan` — Gate 4 self-review orchestrator
-- `figma-to-component` — Figma design → UI component code generator
-
-#### Multi-AI Support
-- **Claude Code** integration via `CLAUDE.md` + `.claude/` directory structure
-- **Gemini CLI** integration via `GEMINI.md`
-- **GitHub Copilot** integration via agents config
-- Superpowers skill library bundled as `upstream/` (pinned to v5.0.5)
-
-#### Project Templates
-- `AIFLOW.md` — team workflow reference document
-- `QUICK_START.md` — 5-minute setup guide
-- `.aiflowrc.json.example` — configuration file reference
-
-### Architecture Notes
-- Stateless per-ticket design — no persistent memory across sessions (planned: v0.1.x)
-- Manual skill sync model via `aiflow use` (managed `aiflow skill` CLI planned: v0.1.x)
-- Spring Boot (Java 17+) used as the reference framework in `CLAUDE.md` coding rules
-
----
-
-## How to upgrade
-
-```bash
-npm install -g @relipa/ai-flow-kit@latest
-aiflow --version
-```
-
-After upgrading, run `aiflow update` inside your project to sync the latest skills and hooks:
-
-```bash
-cd your-project
-aiflow update
-```
+# Changelog
+
+All notable changes to **@relipa/ai-flow-kit** will be documented in this file.
+
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [0.0.4-beta.5] - 2026-04-21
+
+### Added
+- Created a dedicated `docs/` folder to house all developer-facing documentation.
+- Integrated AI Skill Registry into all tool templates (Claude, Cursor, Gemini, Copilot) for better skill discovery.
+
+### Changed
+- Moved `README.md`, `QUICK_START.md`, `AIFLOW.md`, `CHANGELOG.md`, and `IMPLEMENTATION_SUMMARY.md` into the `docs/` directory.
+- Updated `package.json` to exclude internal-only files (`CONTRIBUTING.md`, `plan.md`) from the NPM package distribution.
+- Updated `scripts/init.js` to source documentation from the new `docs/` location.
+- Updated all internal documentation links to reflect the new directory structure.
+
+---
+
+## [0.0.5-beta.0] - 2026-04-23
+
+### Added
+- **`aiflow gate <n> <action>` command** — Called automatically by AI during gate transitions. Supports `start` and `approved` actions for gates 1-5. Options: `--ticket <id>`, `--ai-tool <tool>`.
+- **Telemetry gate logging** — Gate workflow templates now emit `aiflow gate N start/approved --ticket [id]` telemetry calls at each gate transition for usage metrics.
+- **`aiflow telemetry flush` command** — Force-sends buffered telemetry events immediately.
+
+### Changed
+- **`aiflow init` safe overwrite flow** — When a project already has `CLAUDE.md`, `GEMINI.md`, `.cursorrules`, etc., `aiflow init` now prompts before overwriting:
+  - **No (default):** keeps existing file untouched; saves the aiflow template to `.aiflow/reference/<file>` for manual comparison/merge.
+  - **Yes:** backs up the existing file to `.aiflow/backup/<file>` before overwriting — nothing is permanently lost.
+- **`aiflow use --manual` pre-fill (Edit mode)** — Re-running `aiflow use --manual` when context already exists now pre-fills all fields (Ticket ID, Title, Description, Task type) with the current values; press Enter on any field to keep it unchanged.
+- **Fix TEAM_SECRET input** — Replaced `password()` prompt with `input()` using a masked hint `[Reli***!@#]`; pressing Enter retains the existing value.
+- **Fix Apps Script URL input** — Same pattern as TEAM_SECRET: masked hint `[https://script.google.com/macros/s/AKfy***xxxx/exec]`; pressing Enter retains the existing value.
+- **Downgrade dependencies for Node >=16 compatibility** — `@inquirer/prompts` downgraded from `^8.3.2` to `^3.0.0`; `commander` downgraded from `^14.0.3` to `^11.0.0`.
+- **`engines.node`** updated from `>=14.0.0` to `>=16.0.0`.
+
+---
+
+## [0.0.5] - 2026-04-23
+
+### Added
+- **Telemetry System (MVP)**: Added anonymous usage tracking to measure command metrics and user adoption. 
+  - `aiflow telemetry enable/disable/status` commands to easily opt-in or opt-out.
+  - Automatically captures environment metadata and Git email via `git config --global user.email`.
+  - Secure payload signing natively using Node `crypto` HMAC-SHA256 to ensure data authenticity.
+  - Asynchronous payload flusher to ensure zero impact on command execution time (`< 5ms` overhead).
+- Support tracking for multiple AI platforms including Cursor and Gemini via Command Execution events and the new Telemetry SDK.
+
+### Security
+- **Strict Privacy**: Explicitly removed all prompt content and chat history tracking to ensure 100% confidentiality of company code and PII.
+
+---
+
+## [Unreleased]
+
+## [0.0.3-beta.0] - 2026-04-13
+### Security
+- Removed internal GitLab repository links and tracking information.
+- Cleaned `.npmrc` configuration.
+- Added helper scripts for beta and stable releases.
+
+## [0.0.2] - 2026-04-13
+### Changed
+- Updated package to scoped name `@relipa/ai-flow-kit` in documentation and configuration.
+- Fixed installation guides in README and QUICK_START.
+
+## [0.0.1] - 2026-04-13 — Initial Release
+
+### Added
+
+#### CLI (`aiflow`)
+- `aiflow init` — scaffold AI workflow config into any project
+  (supports `--framework` spring-boot/reactjs, `--adapter` jira/backlog)
+- `aiflow use <skill>` — activate a custom skill in the current project
+- `aiflow remove` — cleanly remove `ai-flow-kit` scaffolding from a project
+- `aiflow guide` — interactive onboarding guide
+- `aiflow update` — sync upstream skill/hook updates
+- `aiflow doctor` — validate config, detect missing keys, report issues
+- `aiflow --version` — print installed version
+
+#### 5-Gate AI Workflow
+- **Gate 1 — AI Analyze Requirement**: Auto-starts when a ticket context exists
+  in `.aiflow/context/current.json`; outputs `plan/[ticket-id]/requirement.md`
+- **Gate 2 — Implementation Plan**: TDD plan generation, gated by `APPROVED`
+- **Gate 3 — Code Generation**: TDD-only, test-first discipline enforced
+- **Gate 4 — AI Self-Review**: Verification + impact analysis + checklist, gated by `APPROVED`
+- **Gate 5 — Peer Review & PR**: Guided PR creation via `requesting-code-review` skill
+
+#### Custom Skills (7 skills)
+- `read-study-requirement` — Gate 1 requirement analysis with clarifying Q&A loop
+- `generate-spec` — Gate 2 TDD implementation spec generator
+- `impact-analysis` — breaking-change and dependency impact assessment
+- `investigate-bug` — systematic bug investigation (reproduce → root cause → fix)
+- `report-customer` — customer-facing incident report generator
+- `review-plan` — Gate 4 self-review orchestrator
+- `figma-to-component` — Figma design → UI component code generator
+
+#### Multi-AI Support
+- **Claude Code** integration via `CLAUDE.md` + `.claude/` directory structure
+- **Gemini CLI** integration via `GEMINI.md`
+- **GitHub Copilot** integration via agents config
+- Superpowers skill library bundled as `upstream/` (pinned to v5.0.5)
+
+#### Project Templates
+- `AIFLOW.md` — team workflow reference document
+- `QUICK_START.md` — 5-minute setup guide
+- `.aiflowrc.json.example` — configuration file reference
+
+### Architecture Notes
+- Stateless per-ticket design — no persistent memory across sessions (planned: v0.1.x)
+- Manual skill sync model via `aiflow use` (managed `aiflow skill` CLI planned: v0.1.x)
+- Spring Boot (Java 17+) used as the reference framework in `CLAUDE.md` coding rules
+
+---
+
+## How to upgrade
+
+```bash
+npm install -g @relipa/ai-flow-kit@latest
+aiflow --version
+```
+
+After upgrading, run `aiflow update` inside your project to sync the latest skills and hooks:
+
+```bash
+cd your-project
+aiflow update
+```

package/docs/{cli-reference.md → common/cli-reference.md}

@@ -30,6 +30,7 @@ aiflow init --framework laravel --adapter jira
 **Options:**
 - `-f, --framework <type>` — Framework template (laravel, nextjs, vue-nuxt)
 - `-a, --adapter <type>` — MCP adapter (jira, backlog, google-sheets)
+- `-e, --env <types>` — AI tools to configure (cursor, gemini, copilot)
 
 **What it does:**
 1. Creates `.claude/skills/` with all available skills
@@ -76,6 +77,9 @@ aiflow use 1.0.0
 - `-m, --manual` — Manual context entry
 - `-f, --file <path>` — Load from JSON file
 - `-s, --save <name>` — Save as named context
+- `--with-comments` — Include all ticket comments
+- `--comments-last <n>` — Only fetch last N comments
+- `--comments-from <n>` — Fetch comments starting from comment N
 
 **What it does:**
 1. Fetches context from MCP adapter (if applicable)
@@ -123,7 +127,6 @@ aiflow prompt --list
 - `<type>` — Prompt type (bug-fix, feature, investigation, refactor, impact, docs)
 - `-l, --list` — List available prompt types
 - `-o, --output <file>` — Save to file instead of printing
-- `-c, --copy` — Copy to clipboard
 - `--lang <lang>` — Language (english, vietnamese)
 - `--detail <level>` — Detail level (minimal, standard, comprehensive)
 
@@ -234,7 +237,7 @@ aiflow context --show
 
 **What it does:**
 1. Lists, saves, loads, or deletes contexts
-2. Manages context history in `.claude/context/history/`
+2. Manages context history in `.aiflow/context/history/`
 3. Makes it easy to switch between tasks
 
 **Example:**
@@ -258,12 +261,11 @@ Update to the latest version.
 # Update to latest
 aiflow update
 
-# Keep old version
-aiflow update --keep-old
+# Force update even if already latest
+aiflow update --force
 ```
 
 **Options:**
-- `--keep-old` — Don't delete previous version
 - `--force` — Force update even if already latest
 
 **What it does:**
@@ -296,12 +298,11 @@ Health check for your setup.
 # Run health check
 aiflow doctor
 
-# Fix issues automatically
-aiflow doctor --fix
+# Run with verbose output
+aiflow doctor --verbose
 ```
 
 **Options:**
-- `--fix` — Attempt to fix found issues
 - `-v, --verbose` — Show detailed checks
 
 **What it does:**
@@ -367,61 +368,130 @@ Issues found: 2 warnings, 1 error
 Suggestions: Add test case, rename variable
 ```
 
+## telemetry
+
+Manage usage telemetry.
+
+```bash
+# View current status, buffer size, last flush
+aiflow telemetry status
+
+# Interactive setup (URL, secret, email)
+aiflow telemetry enable
+
+# Disable tracking (config retained)
+aiflow telemetry disable
+
+# Force-send buffered events now
+aiflow telemetry flush
+```
+
+**Sub-commands:**
+- `status` — View current status, buffer size, last flush time
+- `enable` — Interactive setup (Apps Script URL, team secret, email)
+- `disable` — Disable tracking; configuration is retained
+- `flush` — Force-send all buffered events immediately
+
+---
+
 ## memory
 
 Manage team knowledge and context memory.
 
 ```bash
 # Save knowledge
-aiflow memory --save "Laravel validation pattern" "Use FormRequest..."
+aiflow memory save "payment-flow" "Process: 1. Validate amount, 2. Call Stripe API, 3. Update DB"
 
 # Retrieve knowledge
-aiflow memory --get "Laravel validation pattern"
+aiflow memory get "payment-flow"
 
 # List all memories
-aiflow memory --list
+aiflow memory list
 
 # Delete memory
-aiflow memory --delete "old-memory"
+aiflow memory delete "old-memory"
 
 # Search memories
-aiflow memory --search "validation"
+aiflow memory search "validation"
+
+# Clear all memories
+aiflow memory clear
 ```
 
-**Options:**
-- `-s, --save <key> <value>` — Save memory
-- `-g, --get <key>` — Retrieve memory
-- `-l, --list` — List all memories
-- `-d, --delete <key>` — Delete memory
-- `--search <query>` — Search memories
-- `--auto-load` — Auto-load relevant memories
+**Sub-commands:**
+- `save <key> <value>` — Save a note
+- `get <key>` — Read a note
+- `list` — List all notes
+- `search <query>` — Search notes
+- `delete <key>` — Delete a note
+- `clear` — Clear all notes
 
 **What it does:**
 1. Stores team knowledge in `.aiflow/memory/`
-2. Auto-loads relevant memory for current task
-3. Makes knowledge discoverable across team
+2. Makes knowledge discoverable across the team
 
 **Example:**
 ```bash
-$ aiflow memory --save "payment-flow" "Process: 1. Validate amount, 2. Call Stripe API, 3. Update DB"
+$ aiflow memory save "payment-flow" "Process: 1. Validate amount, 2. Call Stripe API, 3. Update DB"
 ✓ Saved: payment-flow
 
-$ aiflow memory --search "payment"
+$ aiflow memory search "payment"
 Found 3 memories matching "payment":
   1. payment-flow
   2. payment-error-handling
   3. payment-tests
 ```
 
+## guide
+
+Show quickstart guide.
+
+```bash
+# Full guide
+aiflow guide
+
+# Architecture & flow only
+aiflow guide --flow
+
+# Command reference only
+aiflow guide --commands
+```
+
+**Options:**
+- `--flow` — Show architecture & flow diagram only
+- `--commands` — Show command reference only
+
+---
+
+## gate (AI workflow logging)
+
+Called automatically by AI during gate workflow — not intended for manual use.
+
+```bash
+# Log gate N started
+aiflow gate <n> start --ticket <id>
+
+# Log gate N approved
+aiflow gate <n> approved --ticket <id>
+```
+
+**Arguments:**
+- `<n>` — Gate number (1-5)
+- `<action>` — `start` or `approved`
+
+**Options:**
+- `--ticket <id>` — Ticket ID associated with the gate transition
+- `--ai-tool <tool>` — AI tool that triggered the gate (e.g. claude, cursor, gemini)
+
+---
+
 ## Global Options
 
 These work with any command:
 
 ```bash
-aiflow <command> --version       # Show version
-aiflow <command> --verbose       # Verbose output
-aiflow <command> --debug         # Debug mode
-aiflow <command> --config <file> # Use custom config file
+aiflow --version                 # Show installed version
+aiflow <command> --help          # Show help for a command
 ```
 
 ## Exit Codes

package/docs/{troubleshooting.md → common/troubleshooting.md}

@@ -545,6 +545,21 @@ cat CLAUDE.md | grep -i "rule"
 - Close and reopen
 - Run `aiflow doctor` to verify setup
 
+## Telemetry Tracking
+
+### "Telemetry connection test failed"
+
+**Verify Apps Script settings:**
+- Ensure the Apps Script Web App is deployed and accessible.
+- Ensure the `TEAM_SECRET` is exactly correct without trailing spaces.
+
+**Bypass / Opt-out locally:**
+If you don't want telemetry tracked on a specific repo, or the upload is failing constantly:
+```bash
+touch .aiflow/no-telemetry
+# CLI will automatically ignore logging for this repo.
+```
+
 ---
 
 ## Getting More Help

package/docs/project/ARCHITECTURE.md

@@ -0,0 +1,28 @@
+# Architecture Overview
+
+> **Template file** — Replace this with your project's actual architecture.
+
+## System Architecture
+
+```
+[Describe your system layers here]
+```
+
+## Tech Stack
+
+| Layer | Technology |
+|-------|-----------|
+| Backend | |
+| Frontend | |
+| Database | |
+| Infrastructure | |
+
+## Key Components
+
+- 
+
+## Data Flow
+
+```
+[Describe main data flows]
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relipa/ai-flow-kit",
-  "version": "0.0.4",
+  "version": "0.0.5-beta.1",
   "description": "All-in-one AI Flow Kit for team development with Claude AI - skills, templates, and MCP adapters",
   "author": "Relipa AI Team",
   "publishConfig": {
@@ -14,11 +14,13 @@
     "aiflow": "./bin/aiflow.js"
   },
   "files": [
+    "README.md",
     "bin",
     "custom",
     "scripts",
     "upstream",
-    "docs",
+    "docs/common",
+    "docs/project",
     "package.json",
     "index.js"
   ],
@@ -33,7 +35,7 @@
     "productivity"
   ],
   "engines": {
-    "node": ">=14.0.0",
+    "node": ">=16.0.0",
     "npm": ">=6.0.0"
   },
   "scripts": {
@@ -45,9 +47,9 @@
     "publish:stable": "npm publish"
   },
   "dependencies": {
-    "@inquirer/prompts": "^8.3.2",
+    "@inquirer/prompts": "^3.0.0",
     "chalk": "^4.1.2",
-    "commander": "^14.0.3",
+    "commander": "^11.0.0",
     "fs-extra": "^11.3.4",
     "semver": "^7.7.4"
   },

package/scripts/context.js

@@ -3,7 +3,7 @@ const path = require('path');
 const chalk = require('chalk');
 
 const PROJECT_DIR  = process.cwd();
-const CONTEXT_DIR  = path.join(PROJECT_DIR, '.claude', 'context');
+const CONTEXT_DIR  = path.join(PROJECT_DIR, '.aiflow', 'context');
 const HISTORY_DIR  = path.join(CONTEXT_DIR, 'history');
 const CURRENT_FILE = path.join(CONTEXT_DIR, 'current.json');
 

package/scripts/guide.js

@@ -210,6 +210,22 @@ function showCommands() {
                 ['aiflow validate <file>', '-r strict', 'Report all warnings'],
             ]
         },
+        {
+            group: 'Telemetry',
+            items: [
+                ['aiflow telemetry status', '', 'View telemetry status'],
+                ['aiflow telemetry enable', '', 'Enable usage tracking'],
+                ['aiflow telemetry disable', '', 'Disable usage tracking'],
+                ['aiflow telemetry flush', '', 'Force-send buffered events now'],
+            ]
+        },
+        {
+            group: 'AI Workflow Integration',
+            items: [
+                ['aiflow gate <n> start', '--ticket <id>', 'Log gate N started (AI calls this)'],
+                ['aiflow gate <n> approved', '--ticket <id>', 'Log gate N approved (AI calls this)'],
+            ]
+        },
         {
             group: 'Help',
             items: [