@relipa/ai-flow-kit 0.0.6 → 0.0.7-beta.0

package/README.md

@@ -23,11 +23,11 @@ Developers only need a single command to load ticket context → AI automaticall
 > [!TIP]
 > After running `aiflow init`, documentation files are automatically copied to `.aiflow/docs/` in your project for easy access.
 
-- **[Quick Start Guide](https://gitlab.relipa.vn/ai/ai-flow-kit/-/blob/main/docs/common/QUICK_START.md)** — Step-by-step instructions for developers.
-- **[Full Workflow (5 Gates)](https://gitlab.relipa.vn/ai/ai-flow-kit/-/blob/main/docs/common/AIFLOW.md)** — In-depth look at the Gate process.
-- **[Troubleshooting](https://gitlab.relipa.vn/ai/ai-flow-kit/-/blob/main/docs/common/troubleshooting.md)** — Common issues and fixes.
-- **[Integration Guide](https://gitlab.relipa.vn/ai/ai-flow-kit/-/blob/main/docs/common/ai-integration.md)** — Advanced tool setup (Claude, Cursor, Gemini).
-- **[Changelog](https://gitlab.relipa.vn/ai/ai-flow-kit/-/blob/main/docs/common/CHANGELOG.md)** — Version history and release notes.
+- **[Quick Start Guide](https://github.com/example/ai-flow-kit/blob/main/docs/common/QUICK_START.md)** — Step-by-step instructions for developers.
+- **[Full Workflow (5 Gates)](https://github.com/example/ai-flow-kit/blob/main/docs/common/AIFLOW.md)** — In-depth look at the Gate process.
+- **[Troubleshooting](https://github.com/example/ai-flow-kit/blob/main/docs/common/troubleshooting.md)** — Common issues and fixes.
+- **[Integration Guide](https://github.com/example/ai-flow-kit/blob/main/docs/common/ai-integration.md)** — Advanced tool setup (Claude, Cursor, Gemini).
+- **[Changelog](https://github.com/example/ai-flow-kit/blob/main/docs/common/CHANGELOG.md)** — Version history and release notes.
 
 ---
 
@@ -52,7 +52,7 @@ PM writes ticket on Backlog/Jira
         ▼
 ⛩️ GATE 3 — Code Generation (TDD)           [AI]
   AI writes tests first → implement → tests pass
-  Commit each small step
+  Verify implementation works
         │ Code done
         ▼
 ⛩️ GATE 4 — AI Self-Review                  [AI + DEV]
@@ -74,13 +74,13 @@ PM writes ticket on Backlog/Jira
 
 ```bash
 # Stable version
-npm install -g @relipa/ai-flow-kit
+npm install -g ai-flow-kit
 
 # Beta version (recommend for newest features)
-npm install -g @relipa/ai-flow-kit@beta
+npm install -g ai-flow-kit@beta
 
 # Uninstall
-npm uninstall -g @relipa/ai-flow-kit
+npm uninstall -g ai-flow-kit
 ```
 
 ---
@@ -93,6 +93,7 @@ npm uninstall -g @relipa/ai-flow-kit
 | `aiflow use <ticket>` | Load ticket context (Backlog/Jira). |
 | `aiflow task` | Manage multiple tasks — pause, switch, resume. |
 | `aiflow prompt` | Generate tool-optimized prompts (`--env cursor`). |
+| `aiflow sync-skills` | Manually synchronize AI Instruction files with local custom skills. |
 | `aiflow telemetry` | Manage telemetry tracking (enable/disable/status). |
 | `aiflow guide` | View integrated multi-AI integration guide. |
 
@@ -104,8 +105,10 @@ Initial setup for the project. Run once per project.
 # Single framework + adapter
 aiflow init --framework spring-boot --adapter backlog
 
-# Force enable RTK token compression
-aiflow init --with-rtk
+# Enable token savings tools
+aiflow init --with-rtk                     # RTK: compress bash outputs (60–90% reduction)
+# aiflow init --with-gitnexus               # GitNexus: code intelligence (waits for index)
+# aiflow init --with-gitnexus --no-wait     # GitNexus: index in background
 
 # Multiple frameworks and adapters
 aiflow init --framework spring-boot,reactjs --adapter backlog,jira
@@ -126,6 +129,21 @@ aiflow init --framework spring-boot,reactjs --adapter backlog,jira
 
 ---
 
+### `aiflow sync-skills`
+
+Synchronize AI instruction files (`CLAUDE.md`, `GEMINI.md`, etc.) and Skills without upgrading the package version. 
+
+```bash
+aiflow sync-skills
+```
+
+**Features:**
+- Intelligent marker-based updates (`<!-- aiflow-kit-start -->`)
+- Confirmation prompts before overwriting custom rules
+- English notifications and status reports
+
+---
+
 ### `aiflow use <ticket>`
 
 Load ticket context into `.aiflow/context/current.json`.
@@ -179,6 +197,8 @@ aiflow task switch PROJ-99          # pause current + switch to another task
 aiflow task resume PROJ-33          # resume a paused task (restores context + gate state)
 aiflow task reset  PROJ-33          # reset to Gate 1 (keeps ticket context, clears progress)
 aiflow task remove PROJ-33          # permanently delete all saved data for the task
+aiflow task next                    # approve current gate + prepare for fresh session
+aiflow task next --ticket PROJ-33   # same, but specify ticket explicitly
 ```
 
 **Use case — switching tasks mid-flow:**
@@ -337,7 +357,7 @@ ai-flow-kit/
 
 **Custom skill:** create `custom/skills/<name>/SKILL.md`
 
-Then run `aiflow update` to apply.
+Then run `aiflow update` or `aiflow sync-skills` to apply.
 
 ---
 
@@ -355,7 +375,7 @@ Then run `aiflow update` to apply.
 
 **`aiflow` not found:**
 ```bash
-npm install -g @relipa/ai-flow-kit
+npm install -g ai-flow-kit
 ```
 
 **Backlog load fails:**

package/bin/aiflow.js

@@ -16,6 +16,7 @@ const removeCommand   = require('../scripts/remove');
 const guideCommand    = require('../scripts/guide');
 const telemetryCommand= require('../scripts/telemetry/cli');
 const taskCommand     = require('../scripts/task');
+const checkpointCommand = require('../scripts/checkpoint');
 const { record }      = require('../scripts/telemetry/record');
 
 program
@@ -63,6 +64,8 @@ program
     .option('-e, --env <types>', 'AI environment(s)/tool(s), comma-separated (e.g. cursor,gemini,copilot)')
     .option('--with-rtk', 'force enable RTK token compression hook')
     .option('--no-rtk', 'skip RTK setup even if RTK is detected')
+    // .option('--with-gitnexus', 'enable GitNexus code intelligence (indexes in background)')
+    // .option('--wait', 'wait for GitNexus indexing to complete before exiting')
     .action((options) => {
         options.frameworks = options.framework
             ? options.framework.split(',').map(s => s.trim()).filter(Boolean)
@@ -162,6 +165,15 @@ taskCmd
     .description('Permanently delete all saved data for a task')
     .action((ticketId) => { record('command.invoked', { command: 'task.remove' }); taskCommand('remove', { taskId: ticketId }); });
 
+taskCmd
+    .command('next')
+    .description('Approve current gate and prepare next session (saves state for resume)')
+    .option('-t, --ticket <id>', 'ticket ID (defaults to active task)')
+    .action((opts) => {
+        record('command.invoked', { command: 'task.next' });
+        taskCommand('next', { taskId: opts.ticket });
+    });
+
 // ── context ───────────────────────────────────────────────────
 program
     .command('context [action]')
@@ -176,6 +188,19 @@ program
         contextCommand(action, options);
     });
 
+// ── checkpoint ────────────────────────────────────────────────
+program
+    .command('checkpoint')
+    .description('Record token usage checkpoint (called by AI during gate work)')
+    .requiredOption('--gate <n>', 'gate number (1–5)', parseInt)
+    .requiredOption('--step <name>', 'step name (e.g. "tests-written")')
+    .requiredOption('--tokens <n>', 'estimated token count', parseInt)
+    .option('-t, --ticket <id>', 'ticket ID (defaults to active task)')
+    .action((opts) => {
+        record('command.invoked', { command: 'checkpoint' });
+        checkpointCommand({ gate: opts.gate, step: opts.step, tokens: opts.tokens, ticket: opts.ticket });
+    });
+
 // ── validate ──────────────────────────────────────────────────
 program
     .command('validate <file>')
@@ -276,14 +301,45 @@ program
         updateCommand(options);
     });
 
+// ── sync-skills ───────────────────────────────────────────────
+program
+    .command('sync-skills')
+    .description('Manually synchronize AI Instruction files with local custom skills')
+    .action(async () => {
+        record('command.invoked', { command: 'sync-skills' });
+        const projectDir = process.cwd();
+        const { setupFramework, AI_TOOL_FILES, ensureAiflowGitignored } = require('../scripts/init');
+        const fs = require('fs-extra');
+        const path = require('path');
+        const chalk = require('chalk');
+
+        const stateFile = path.join(projectDir, '.aiflow', 'state.json');
+        if (!(await fs.pathExists(stateFile))) {
+            console.log(chalk.red('Project is not initialized. Please run `aiflow init` first.'));
+            return;
+        }
+
+        const state = await fs.readJson(stateFile);
+        const frameworks = state.frameworks || [];
+        const selectedTools = state.aiTools || Object.keys(AI_TOOL_FILES);
+
+        console.log(chalk.cyan('⟳ Syncing AI Instruction files...'));
+        for (const fw of frameworks) {
+            await setupFramework(projectDir, fw, frameworks.length > 1, selectedTools);
+        }
+        await ensureAiflowGitignored(projectDir);
+        console.log(chalk.green('✨ Sync completed!'));
+    });
+
 // ── doctor ────────────────────────────────────────────────────
 program
     .command('doctor')
     .description('Health check of AI Flow Kit setup')
+    .option('-t, --ticket <id>', 'show token breakdown for specific ticket')
     .option('-v, --verbose', 'detailed output')
-    .action(() => {
+    .action((opts) => {
         record('command.invoked', { command: 'doctor' });
-        doctorCommand();
+        doctorCommand({ ticket: opts.ticket, verbose: opts.verbose });
     });
 
 // ── telemetry ──────────────────────────────────────────────────

package/custom/mcp-presets/gitnexus.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "gitnexus": {
+      "command": "npx",
+      "args": ["-y", "gitnexus@latest", "mcp"]
+    }
+  }
+}

package/custom/skills/generate-spec/SKILL.md

@@ -17,6 +17,13 @@ keywords: spec, plan, implementation, tdd, coding plan
 - ✅ Gate 1 APPROVED — `plan/[ticket-id]/requirement.md` reviewed and approved by DEV
 - ✅ Requirement document includes: requirements, solution, impact analysis, estimate
 
+## Fast Mode Output Rules (CRITICAL)
+
+When updating `plan/[ticket-id]/summary.md` in **fast mode**:
+- **Keep it extremely short.**
+- Add a bullet point indicating Gate 2 plan is ready.
+- **DO NOT copy the entire plan.md into summary.md.**
+
 ---
 
 ## Process

package/custom/skills/impact-analysis/SKILL.md

@@ -20,6 +20,16 @@ keywords: impact, refactor, breaking change, scope
 
 ### Step 1: Find all usage (Dependency Map)
 
+**Preferred — If GitNexus MCP is available** (`.mcp.json` has `gitnexus` entry):
+```
+impact("ClassName")    → structured blast radius: callers, dependents, risk score
+detect_changes()       → reads current git diff, maps changed lines → affected symbols
+```
+- Use `impact()` when you know the class/function name being modified.
+- Use `detect_changes()` when starting Gate 4 review — it auto-detects what changed from git diff without needing to specify names.
+- One call replaces all grep commands below. Proceed directly to Step 2 with the result.
+
+**Fallback — grep manually** (if GitNexus not configured):
 ```bash
 # Find all files importing/calling the class/function being modified
 grep -r "ClassName\|functionName\|methodName" --include="*.php" .

package/custom/skills/read-study-requirement/SKILL.md

@@ -28,6 +28,13 @@ Check `mode` in `.aiflow/context/current.json` before starting:
 
 > Target: Gate 1 complete in **< 5 minutes**, minimum token usage.
 
+## Fast Mode Output Rules (CRITICAL)
+
+When creating `plan/[ticket-id]/summary.md` during Gate 1:
+- You must create the `summary.md` file after Gate 1 is APPROVED, to track session progress.
+- Keep `summary.md` concise. Only include short bullet points tracking Gates.
+- Do not write verbose implementation details in `summary.md` at Gate 1.
+
 1. Read `.aiflow/context/current.json` — ticket title, description, acceptance criteria
 2. Identify **directly affected files** from ticket text and file names only.
    DO NOT trace data flow or read unrelated source files.
@@ -73,6 +80,10 @@ Check `mode` in `.aiflow/context/current.json` before starting:
 1. Read `.aiflow/context/current.json` — ticket info from Backlog/Jira
 2. Read `CLAUDE.md` — understand project architecture, tech stack, conventions
 3. Read related source files — trace data flow, identify patterns, dependencies
+   - **If GitNexus MCP is available** (`.mcp.json` has `gitnexus` entry): invoke GitNexus MCP tools instead of reading files directly — one call returns full context without multi-file exploration:
+     - `gitnexus: context("ClassName")` → 360° view of a symbol (dependencies, callers, methods)
+     - `gitnexus: query("keyword or description")` → hybrid search across codebase
+     - Saves ~50% of token cost at this step vs reading files manually
    - **If task is a Bug Fix:** Invoke `superpowers:systematic-debugging` to trace root cause before proposing fixes.
 4. Read ticket comments — additional context from PM/team
 

package/custom/skills/review-plan/SKILL.md

@@ -41,6 +41,21 @@ Assess impact by reasoning about the changed files only:
 - [ ] No hardcoded credentials or secrets
 - [ ] No SQL injection risk in new queries
 
+## Fast Mode Output Rules (CRITICAL)
+
+When creating `plan/[ticket-id]/summary.md` in **fast mode**:
+- **Do not write long explanations or descriptions.**
+- **List format only:** Bullet points with `[NEW]`, `[MODIFIED]`, `[DELETED]`.
+- **Purpose:** Next to each file, write exactly 1 sentence explaining the *purpose* (the "why"), not the implementation details.
+
+**Example summary.md block:**
+```markdown
+### Gate 3 — Code
+- ✅ **Implemented batch endpoints**
+  - \`[NEW] src/controllers/BatchController.ts\`: Handle bulk export requests
+  - \`[MODIFIED] src/services/ExportService.ts\`: Added S3 upload integration
+```
+
 ---
 
 ## Process

package/docs/common/AIFLOW.md

@@ -28,7 +28,7 @@ PM writes ticket on Backlog/Jira
         ▼
 ⛩️ GATE 3 — Code Generation (TDD)           [AI]
   AI writes tests first → implement → tests pass
-  Commit each small step
+  Verify implementation works
         │ Code done
         ▼
 ⛩️ GATE 4 — AI Self-Review                  [AI + DEV]
@@ -65,6 +65,7 @@ AI Flow Kit allows you to manage multiple tasks in the same repository without l
 - **`aiflow task pause`**: Save current context and gate progress to `.aiflow/tasks/<taskId>/`.
 - **`aiflow task switch <id>`**: Pause current task and switch to another.
 - **`aiflow task resume <id>`**: Restore context and gate state. AI auto-resumes from the correct gate.
+- **`aiflow task next`**: Approve the current gate, clear context, and prepare the task for a fresh session (saves tokens).
 
 ---
 
@@ -182,7 +183,7 @@ Summary:
 1. Read the approved requirement document
 2. **Invoke** `superpowers:writing-plans` → create detailed implementation plan
 3. Break down into TDD tasks: test first → implement → verify
-4. Define commit strategy (small, focused commits)
+4. Define verification strategy (evidence before claims)
 5. Present plan and wait for APPROVED
 
 **Implementation Plan Structure:**
@@ -193,7 +194,6 @@ Summary:
 │   ├── Task 2: Implement [component]
 │   ├── Task 3: Write test for [next scenario]
 │   └── ...
-├── Commit Strategy
 └── Test Commands
 ```
 
@@ -202,7 +202,7 @@ Summary:
 ```
 ⏸️ GATE 2: IMPLEMENTATION PLAN READY
 
-Tasks: [N] | Commits: [N] | Test-first tasks: [N]
+Tasks: [N] | Verification: [N] | Test-first tasks: [N]
 
 → Type APPROVED to start coding
 → Or provide feedback to adjust
@@ -227,7 +227,7 @@ Tasks: [N] | Commits: [N] | Test-first tasks: [N]
 2. `superpowers:test-driven-development` — write tests FIRST
 3. Run tests → confirm FAIL
 4. Implement code → tests PASS
-5. Commit each small step
+5. Verify implementation works
 
 #### Bug fix task (extra):
 1. `superpowers:systematic-debugging` — trace root cause, NO guessing
@@ -238,10 +238,16 @@ Tasks: [N] | Commits: [N] | Test-first tasks: [N]
 1. Ensure tests cover current behavior
 2. Refactor in small steps — keep tests green continuously
 
+**Fast Mode (tdd-lean):**
+In fast mode, AI uses the `tdd-lean` skill instead of per-test TDD to save massive token costs:
+1. **Batch Red:** Write ALL tests at once. Run once. (Confirm all fail).
+2. **Batch Green:** Implement ALL code at once. Run once. (Confirm all pass).
+3. **Discipline:** After every run, discard full stack traces and keep ONLY the summary line.
+
 **Gate 3 Output:**
 - Code implementation finished
 - All tests PASS
-- Committed
+- Verified (evidence provided)
 
 ---
 

package/docs/common/CHANGELOG.md

@@ -1,15 +1,42 @@
 # Changelog
 
-All notable changes to **@relipa/ai-flow-kit** will be documented in this file.
+All notable changes to **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.7] - 2026-05-07
+
+### Added
+
+- **Intelligent AI Instruction Synchronization** — Marker-based (`<!-- aiflow-kit-start -->`) block updates for `CLAUDE.md`, `GEMINI.md`, and `.cursorrules`.
+- **Interactive Instruction Safety** — Granular confirmation prompts for all instruction file modifications (update block, overwrite, or create new).
+- **Automated Repository Hygiene** — Generated files and folders (`.aiflow/`, `plan/`, `.claude/`, `.rules/`, `.mcp.json`, and instruction files) are now automatically managed in `.gitignore`.
+- **`aiflow sync-skills` command** — Lightweight command to synchronize Skill Registry and Instruction files without a full version upgrade.
+- **Enhanced `aiflow guide --flow`** — Now dynamically displays the `## Workflow Overview` section directly from `AIFLOW.md` for up-to-date documentation.
+- **Token savings dashboard in `aiflow doctor`** — new "Token savings" section shows RTK status and estimated 60–90% reduction on bash outputs.
+
+### Changed
+
+- **`aiflow update` efficiency** — Now automatically performs skill and instruction synchronization even if the version is unchanged (removes the need for `--force`).
+- **Safety First Development** — Removed all automatic `git commit` instructions from AI skills (`subagent-driven-development`, `using-git-worktrees`, `writing-plans`) to ensure developer-led commit management.
+- **Localized CLI** — All interactive prompts and confirmation messages translated to English for consistency.
+- **`aiflow init` RTK entry** — flag description updated to clarify RTK saves bash output tokens (60–90%).
+- **`aiflow doctor`** — RTK section merged into new "Token savings" section.
+- **README.md / QUICK_START.md** — Updated to reflect `sync-skills` and improved update flow.
+
+### Fixed
+
+- Fixed `.github/copilot-instructions.md` not being included in automated `.gitignore` rules.
+
+---
+
 ## [0.0.6] - 2026-04-29
 
 ### Added
+
 - **Global Fast Mode (Default)** — Optimize AI efficiency by prioritizing speed and minimizing token usage.
   - Gate 1: Fast track scan with max 1 clarifying question.
   - Gate 3: Disable subagents by default; implement all tasks in a single session.
@@ -25,6 +52,7 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 - **Spring Boot code examples extracted** — Java code examples moved to separate files to reduce `CLAUDE.md` size.
 
 ### Changed
+
 - **Default mode** for all new tasks is now `fast` instead of `auto`.
 - **`aiflow init` improvements** — Supports multi-select framework and protects existing instruction files from being overwritten.
 - **CLAUDE.md Optimization** — Reduced Spring Boot template size by ~70%, saving ~3-5k tokens per session.
@@ -32,18 +60,20 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 - **Automatic Task Pausing** — When loading a new ticket, the current task is automatically paused and its state is saved.
 
 ### Fixed
-- Broken 404 documentation links on the npmjs.com page.
 
+- Broken 404 documentation links on the npmjs.com page.
 
 ---
 
 ## [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.
@@ -54,11 +84,13 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 ## [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.
@@ -73,7 +105,8 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 ## [0.0.5] - 2026-04-23
 
 ### Added
-- **Telemetry System (MVP)**: Added anonymous usage tracking to measure command metrics and user adoption. 
+
+- **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.
@@ -81,6 +114,7 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 - 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.
 
 ---
@@ -88,14 +122,18 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 ## [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.
+
+- Updated package name in documentation and configuration.
 - Fixed installation guides in README and QUICK_START.
 
 ## [0.0.1] - 2026-04-13 — Initial Release
@@ -103,6 +141,7 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 ### 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
@@ -113,6 +152,7 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 - `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`
@@ -121,6 +161,7 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 - **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
@@ -130,17 +171,20 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 - `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
@@ -150,7 +194,7 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 ## How to upgrade
 
 ```bash
-npm install -g @relipa/ai-flow-kit@latest
+npm install -g ai-flow-kit@latest
 aiflow --version
 ```
 

package/docs/common/QUICK_START.md

@@ -7,17 +7,16 @@
 ## Installation
 
 ```bash
-# Stable version
-npm install -g @relipa/ai-flow-kit
+npm install -g ai-flow-kit
 
 # Beta version (recommend for newest features)
-npm install -g @relipa/ai-flow-kit@beta
+npm install -g ai-flow-kit@beta
 
 # Verification
 aiflow --version
 
 # Uninstall
-npm uninstall -g @relipa/ai-flow-kit
+npm uninstall -g ai-flow-kit
 ```
 
 ---
@@ -146,7 +145,7 @@ APPROVED
 
 AI outputs:
 - TDD task breakdown (test first → implement → verify)
-- Commit strategy (small, focused commits)
+- Verification strategy (evidence before claims)
 - Test commands
 
 **Your action:**
@@ -166,7 +165,7 @@ APPROVED
 
 - Writes tests FIRST → runs → confirms FAIL
 - Implements code → tests PASS
-- Commits each small step
+- Verifies implementation works
 
 **Your action:** Monitor. No action needed unless AI asks a question.
 
@@ -256,7 +255,7 @@ Developer                          AI                              Peer
    │  "APPROVED" ──────────────────►│                                │
    │                                │                                │
    │        GATE 3                  │  Write tests → implement       │
-   │        (monitor)               │  Commit each step              │
+   │        (monitor)               │  Verify implementation works   │
    │                                │                                │
    │  ─── GATE 4 ──────────────────►│                                │
    │                                │  Self-review + summary         │
@@ -317,10 +316,13 @@ claude                                # AI auto-starts: map dependencies → ass
 ```bash
 # Setup
 aiflow init --framework nestjs --adapter backlog
-aiflow init --framework spring-boot --with-rtk   # force enable RTK compression
-aiflow init --no-rtk                            # skip RTK setup
+aiflow init --framework spring-boot --with-rtk        # RTK: bash output compression (60–90%)
+# aiflow init --framework spring-boot --with-gitnexus          # GitNexus: waits for index to complete
+# aiflow init --framework spring-boot --with-gitnexus --no-wait # GitNexus: index in background
+aiflow init --no-rtk                                 # skip RTK setup
 aiflow doctor                                   # health check
 aiflow guide                                    # multi-tool guide
+aiflow sync-skills                              # manually sync AI instruction files
 
 # Per task
 aiflow use PROJ-33                              # load context (Fast Mode, default)
@@ -366,7 +368,7 @@ aiflow guide --commands               # command reference
 aiflow remove                         # remove from project
 aiflow remove --global                # uninstall globally (npm uninstall -g)
 aiflow remove --version 1.0.0         # remove cached version from .aiflow/
-npm uninstall -g @relipa/ai-flow-kit  # standard npm uninstall
+npm uninstall -g ai-flow-kit  # standard npm uninstall
 ```
 
 ---
@@ -405,7 +407,7 @@ aiflow guide
 
 **`aiflow` not found:**
 ```bash
-npm install -g @relipa/ai-flow-kit
+npm install -g ai-flow-kit
 ```
 
 **Incorrect credentials:**

package/docs/common/cli-reference.md

@@ -399,6 +399,29 @@ You can switch back with: aiflow use 1.0.0
 ✨ Update completed!
 ```
 
+## sync-skills
+
+Manually synchronize AI Instruction files with local custom skills.
+
+```bash
+# Sync AI Instruction files
+aiflow sync-skills
+```
+
+**What it does:**
+1. Reads all active local skills and upstream skills
+2. Generates the updated AI Skill Registry table
+3. Safely updates the AI Instruction blocks (`<!-- aiflow-kit-start -->`) in your project's `CLAUDE.md`, `GEMINI.md`, or `.cursorrules` without wiping your custom rules
+4. If no marker blocks are found, it asks for confirmation to overwrite with the correct structure
+
+**Example:**
+```bash
+$ aiflow sync-skills
+⟳ Syncing AI Instruction files...
+  ✓ Updated AI Flow block in CLAUDE.md
+✨ Sync completed!
+```
+
 ## doctor
 
 Health check for your setup.