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

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.

package/package.json

@@ -1,13 +1,8 @@
 {
   "name": "@relipa/ai-flow-kit",
-  "version": "0.0.6-beta.0",
+  "version": "0.0.7-beta.0",
   "description": "All-in-one AI Flow Kit for team development with Claude AI - skills, templates, and MCP adapters",
-  "author": "Relipa AI Team",
-  "repository": {
-    "type": "git",
-    "url": "https://gitlab.relipa.vn/ai/ai-flow-kit.git"
-  },
-  "homepage": "https://gitlab.relipa.vn/ai/ai-flow-kit#readme",
+  "author": "Example Team",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.com/"

package/scripts/checkpoint.js

@@ -0,0 +1,46 @@
+const fs = require('fs-extra');
+const path = require('path');
+const chalk = require('chalk');
+
+const PROJECT_DIR  = process.cwd();
+const AIFLOW_DIR   = path.join(PROJECT_DIR, '.aiflow');
+const CONTEXT_FILE = path.join(AIFLOW_DIR, 'context', 'current.json');
+
+const GATE_LABELS = { 1: 'Analyze', 2: 'Plan', 3: 'Code', 4: 'Review', 5: 'PR' };
+
+module.exports = async function checkpoint(options = {}) {
+    const { gate, step, tokens, ticket: ticketOpt } = options;
+
+    if (!gate || !step || tokens === undefined) {
+        console.log(chalk.yellow('Usage: aiflow checkpoint --gate <N> --step <name> --tokens <N>'));
+        console.log(chalk.gray('  Example: aiflow checkpoint --gate 3 --step "tests-written" --tokens 3200'));
+        return;
+    }
+
+    // Resolve ticket ID
+    let ticketId = ticketOpt;
+    if (!ticketId) {
+        const ctx = await fs.readJson(CONTEXT_FILE).catch(() => null);
+        ticketId = ctx && ctx.taskId ? ctx.taskId : 'unknown';
+    }
+
+    const taskDir = path.join(AIFLOW_DIR, 'tasks', ticketId);
+    await fs.ensureDir(taskDir);
+
+    const checkpointPath = path.join(taskDir, 'checkpoints.json');
+    const existing = (await fs.pathExists(checkpointPath))
+        ? await fs.readJson(checkpointPath).catch(() => ({ checkpoints: [] }))
+        : { checkpoints: [] };
+
+    const entry = {
+        gate:      parseInt(gate),
+        step,
+        tokens:    parseInt(tokens),
+        timestamp: new Date().toISOString(),
+    };
+    existing.checkpoints.push(entry);
+    await fs.writeJson(checkpointPath, existing, { spaces: 2 });
+
+    const label = GATE_LABELS[parseInt(gate)] || `Gate ${gate}`;
+    console.log(chalk.green(`✓ Checkpoint: Gate ${gate} (${label}) — ${step} — ~${parseInt(tokens).toLocaleString()} tokens`));
+};

package/scripts/doctor.js

@@ -1,89 +1,192 @@
-const fs = require('fs-extra');
-const path = require('path');
-const chalk = require('chalk');
-const { detectRtk, isRtkHookConfigured } = require('./init');
-
-module.exports = async function doctor() {
-    const projectDir = process.cwd();
-    const errors = [];
-    const warnings = [];
-
-    console.log(chalk.blue('Running health check for AI Flow Kit...\n'));
-
-    // ── Core setup ─────────────────────────────────────────────
-    if (!(await fs.pathExists(path.join(projectDir, '.claude', 'skills')))) {
-        errors.push('Missing `.claude/skills` directory. Did you run `aiflow init`?');
-    } else {
-        console.log(chalk.green('✓ .claude/skills exists'));
-    }
-
-    if (!(await fs.pathExists(path.join(projectDir, '.rules')))) {
-        errors.push('Missing `.rules` directory.');
-    } else {
-        console.log(chalk.green('✓ .rules exists'));
-    }
-
-    if (!(await fs.pathExists(path.join(projectDir, 'CLAUDE.md')))) {
-        errors.push('Missing CLAUDE.md. AI context prompt is not set up.');
-    } else {
-        console.log(chalk.green('✓ CLAUDE.md exists'));
-    }
-
-    // ── Version tracking ───────────────────────────────────────
-    const stateFile = path.join(projectDir, '.aiflow', 'state.json');
-    if (!(await fs.pathExists(stateFile))) {
-        errors.push('Missing `.aiflow/state.json`. Version tracking is broken.');
-    } else {
-        const state = await fs.readJson(stateFile);
-        console.log(chalk.green(`✓ Version tracking active (v${state.current_version})`));
-    }
-
-    // ── SessionStart hook ──────────────────────────────────────
-    const settingsPath = path.join(projectDir, '.claude', 'settings.json');
-    if (await fs.pathExists(settingsPath)) {
-        const settings = await fs.readJson(settingsPath).catch(() => ({}));
-        const hookList = settings?.hooks?.SessionStart || [];
-        const hasSessionHook = hookList.some(h =>
-            (h.hooks || []).some(e => typeof e.command === 'string' && e.command.includes('session-start'))
-        );
-        if (hasSessionHook) {
-            console.log(chalk.green('✓ SessionStart hook configured'));
-        } else {
-            warnings.push('SessionStart hook not found in .claude/settings.json — run `aiflow init` to set it up.');
-        }
-    } else {
-        warnings.push('Missing .claude/settings.json — run `aiflow init`.');
-    }
-
-    // ── RTK token compression ──────────────────────────────────
-    console.log('');
-    const rtk = await detectRtk();
-    if (rtk.installed) {
-        const hookOk = await isRtkHookConfigured(projectDir);
-        if (hookOk) {
-            console.log(chalk.green(`✓ RTK installed (${rtk.version}) — token compression active`));
-        } else {
-            console.log(chalk.green(`✓ RTK installed (${rtk.version})`));
-            warnings.push('RTK is installed but hook not configured. Run `aiflow init` to enable token compression.');
-        }
-    } else {
-        console.log(chalk.gray('○ RTK not installed (optional) — token compression inactive'));
-        console.log(chalk.gray('  Install: cargo install rtk  |  More: https://github.com/rtk-ai/rtk'));
-    }
-
-    // ── Summary ────────────────────────────────────────────────
-    console.log('');
-    if (warnings.length > 0) {
-        console.log(chalk.yellow('Warnings:'));
-        warnings.forEach(w => console.log(chalk.yellow(`  ⚠ ${w}`)));
-        console.log('');
-    }
-
-    if (errors.length > 0) {
-        console.log(chalk.red('Issues found:'));
-        errors.forEach(e => console.log(chalk.red(`  ✗ ${e}`)));
-        console.log(chalk.yellow('\nTry running `aiflow init` or `aiflow update` to fix these files.'));
-    } else {
-        console.log(chalk.green('✨ Everything looks healthy! You are ready to fly.'));
-    }
-};
+const fs = require('fs-extra');
+const path = require('path');
+const chalk = require('chalk');
+const { detectRtk, isRtkHookConfigured, isGitNexusConfigured } = require('./init');
+
+function formatAgo(isoString) {
+    const ms = Date.now() - new Date(isoString).getTime();
+    const mins = Math.floor(ms / 60000);
+    if (mins < 1)   return 'just now';
+    if (mins < 60)  return `${mins}m ago`;
+    const hrs = Math.floor(mins / 60);
+    if (hrs < 24)   return `${hrs}h ago`;
+    return `${Math.floor(hrs / 24)}d ago`;
+}
+
+async function showTokenBreakdown(ticketId) {
+    const tasksDir = path.join(process.cwd(), '.aiflow', 'tasks');
+    const checkpointsFile = path.join(tasksDir, ticketId, 'checkpoints.json');
+    if (!(await fs.pathExists(checkpointsFile))) return;
+
+    const data = await fs.readJson(checkpointsFile).catch(() => ({ checkpoints: [] }));
+    if (!data.checkpoints || data.checkpoints.length === 0) return;
+
+    // Aggregate tokens per gate (taking the max/latest)
+    const gateTokens = {};
+    for (const cp of data.checkpoints) {
+        if (!gateTokens[cp.gate] || cp.tokens > gateTokens[cp.gate]) {
+            gateTokens[cp.gate] = cp.tokens;
+        }
+    }
+
+    const GATE_LABELS = { 1: 'Analyze', 2: 'Plan', 3: 'Code', 4: 'Review', 5: 'PR' };
+    const gates = Object.keys(gateTokens).sort();
+    const total = gates.reduce((sum, g) => sum + gateTokens[g], 0);
+
+    console.log('');
+    console.log(chalk.bold(`Token usage for task ${ticketId}:`));
+    for (const g of gates) {
+        const label = GATE_LABELS[parseInt(g)] || `Gate ${g}`;
+        const t = gateTokens[g];
+        const bar = '█'.repeat(Math.round((t / total) * 20)).padEnd(20, '░');
+        const pct = Math.round((t / total) * 100);
+        console.log(`  Gate ${g}  ${label.padEnd(8)}  ~${t.toLocaleString().padStart(6)}  ${chalk.gray(bar)}  ${pct}%`);
+    }
+    console.log(`  Total estimated: ~${total.toLocaleString()} tokens`);
+}
+
+module.exports = async function doctor(options = {}) {
+    const projectDir = process.cwd();
+    const errors = [];
+    const warnings = [];
+
+    console.log(chalk.blue('Running health check for AI Flow Kit...\n'));
+
+    // ── Token breakdown ────────────────────────────────────────
+    let ticketId = options.ticket;
+    if (!ticketId) {
+        const contextFile = path.join(projectDir, '.aiflow', 'context', 'current.json');
+        if (await fs.pathExists(contextFile)) {
+            const ctx = await fs.readJson(contextFile).catch(() => ({}));
+            ticketId = ctx.taskId;
+        }
+    }
+
+    if (ticketId) {
+        await showTokenBreakdown(ticketId);
+    }
+
+    // ── Core setup ─────────────────────────────────────────────
+    if (!(await fs.pathExists(path.join(projectDir, '.claude', 'skills')))) {
+        errors.push('Missing `.claude/skills` directory. Did you run `aiflow init`?');
+    } else {
+        console.log(chalk.green('✓ .claude/skills exists'));
+    }
+
+    if (!(await fs.pathExists(path.join(projectDir, '.rules')))) {
+        errors.push('Missing `.rules` directory.');
+    } else {
+        console.log(chalk.green('✓ .rules exists'));
+    }
+
+    if (!(await fs.pathExists(path.join(projectDir, 'CLAUDE.md')))) {
+        errors.push('Missing CLAUDE.md. AI context prompt is not set up.');
+    } else {
+        console.log(chalk.green('✓ CLAUDE.md exists'));
+    }
+
+    // ── Version tracking ───────────────────────────────────────
+    const stateFile = path.join(projectDir, '.aiflow', 'state.json');
+    if (!(await fs.pathExists(stateFile))) {
+        errors.push('Missing `.aiflow/state.json`. Version tracking is broken.');
+    } else {
+        const state = await fs.readJson(stateFile);
+        console.log(chalk.green(`✓ Version tracking active (v${state.current_version})`));
+    }
+
+    // ── SessionStart hook ──────────────────────────────────────
+    const settingsPath = path.join(projectDir, '.claude', 'settings.json');
+    if (await fs.pathExists(settingsPath)) {
+        const settings = await fs.readJson(settingsPath).catch(() => ({}));
+        const hookList = settings?.hooks?.SessionStart || [];
+        const hasSessionHook = hookList.some(h =>
+            (h.hooks || []).some(e => typeof e.command === 'string' && e.command.includes('session-start'))
+        );
+        if (hasSessionHook) {
+            console.log(chalk.green('✓ SessionStart hook configured'));
+        } else {
+            warnings.push('SessionStart hook not found in .claude/settings.json — run `aiflow init` to set it up.');
+        }
+    } else {
+        warnings.push('Missing .claude/settings.json — run `aiflow init`.');
+    }
+
+    // ── Token savings tools ────────────────────────────────────
+    console.log('');
+    console.log(chalk.bold('Token savings:'));
+
+    // RTK
+    const rtk = await detectRtk();
+    if (rtk.installed) {
+        const hookOk = await isRtkHookConfigured(projectDir);
+        if (hookOk) {
+            console.log(chalk.green(`  ✓ RTK (${rtk.version}) — bash output compression active`));
+            console.log(chalk.gray('    Estimated: 60–90% reduction on bash command outputs (test runs, git, npm...)'));
+        } else {
+            console.log(chalk.yellow(`  ⚠ RTK installed (${rtk.version}) but hook not configured`));
+            warnings.push('RTK hook not configured. Run `aiflow init` to enable token compression.');
+        }
+    } else {
+        console.log(chalk.gray('  ○ RTK not installed — bash output compression inactive'));
+        console.log(chalk.gray('    Install: cargo install rtk  |  Enable: aiflow init --with-rtk'));
+    }
+
+    // GitNexus
+    const gnConfigured = await isGitNexusConfigured(projectDir);
+    const gnStatusPath = path.join(projectDir, '.aiflow', 'gitnexus-status.json');
+    if (gnConfigured) {
+        let statusLine = chalk.green('  ✓ GitNexus MCP configured');
+        try {
+            if (await fs.pathExists(gnStatusPath)) {
+                const gn = await fs.readJson(gnStatusPath);
+                const GITNEXUS_STALE_MS = 3 * 60 * 60 * 1000; // 3 hours
+                if (gn.status === 'done') {
+                    const ago = gn.completedAt
+                        ? chalk.gray(` — indexed ${formatAgo(gn.completedAt)}`)
+                        : '';
+                    statusLine = chalk.green(`  ✓ GitNexus MCP configured — index ready${ago}`);
+                    console.log(statusLine);
+                    console.log(chalk.gray('    Estimated: ~50% fewer tokens at Gate 1 (context queries vs file reads)'));
+                    console.log(chalk.gray('    Estimated: ~70% fewer tokens at Gate 4 (impact() vs grep codebase)'));
+                } else if (gn.status === 'running') {
+                    const age = Date.now() - new Date(gn.startedAt).getTime();
+                    if (age > GITNEXUS_STALE_MS) {
+                        console.log(chalk.red('  ✗ GitNexus MCP configured — indexing timed out (stale)'));
+                        console.log(chalk.gray(`    Started ${formatAgo(gn.startedAt)} but never finished. Process may have crashed.`));
+                        // console.log(chalk.gray('    Retry: aiflow init --with-gitnexus --wait  |  Log: .aiflow/gitnexus-analyze.log'));
+                    } else {
+                        console.log(chalk.yellow('  ⟳ GitNexus MCP configured — indexing in progress...'));
+                        console.log(chalk.gray('    Log: .aiflow/gitnexus-analyze.log'));
+                    }
+                } else if (gn.status === 'error') {
+                    console.log(chalk.red('  ✗ GitNexus MCP configured — last index failed'));
+                    console.log(chalk.gray('    Retry: npx gitnexus analyze  |  Log: .aiflow/gitnexus-analyze.log'));
+                }
+            } else {
+                console.log(chalk.yellow('  ⚠ GitNexus MCP configured but not yet indexed'));
+                console.log(chalk.gray('    Run: npx gitnexus analyze'));
+            }
+        } catch (_) {
+            console.log(statusLine);
+        }
+    } else {
+        console.log(chalk.gray('  ○ GitNexus not configured — code intelligence inactive'));
+        // console.log(chalk.gray('    Enable: aiflow init --with-gitnexus'));
+    }
+
+    // ── Summary ────────────────────────────────────────────────
+    console.log('');
+    if (warnings.length > 0) {
+        console.log(chalk.yellow('Warnings:'));
+        warnings.forEach(w => console.log(chalk.yellow(`  ⚠ ${w}`)));
+        console.log('');
+    }
+
+    if (errors.length > 0) {
+        console.log(chalk.red('Issues found:'));
+        errors.forEach(e => console.log(chalk.red(`  ✗ ${e}`)));
+        console.log(chalk.yellow('\nTry running `aiflow init` or `aiflow update` to fix these files.'));
+    } else {
+        console.log(chalk.green('✨ Everything looks healthy! You are ready to fly.'));
+    }
+};