hero-vibe-kit 0.1.0

package/src/integrations.cjs

@@ -0,0 +1,89 @@
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { log, exists, ensureDir, readJSON, writeJSON } = require('./util.cjs');
+
+function uniqueSources(group) {
+  return Array.from(new Set((group && group.skills || []).map((s) => s.source)));
+}
+
+function runCmd(cmd, args, cwd) {
+  try {
+    const r = spawnSync(cmd, args, { cwd, stdio: 'inherit', shell: process.platform === 'win32' });
+    return r.status === 0;
+  } catch (_) { return false; }
+}
+
+const SERENA_MEMOS = {
+  'agency_workflow.md':
+    'Canonical development process (single source of truth): **docs/AGENCY_WORKFLOW.md**.\n\n' +
+    'Summary: classify every request via the router table → pick a path (Read-only / Fast / Standard / Full). ' +
+    'Do NOT run the full 5-phase process for small tasks. A "Gate" means real Plan Mode (ExitPlanMode), not a promise.\n\n' +
+    'Details (always read the source files, do not duplicate here): docs/AGENCY_WORKFLOW.md, docs/DEFINITION_OF_DONE.md, ' +
+    'docs/BRANCHING.md, docs/TEAM_ROSTER.md, docs/ACTIVE_STATE.md, docs/COMMUNICATION_PROTOCOL.md, ' +
+    'docs/SECURITY_STANDARDS.md, docs/PERFORMANCE_STANDARDS.md.\n',
+  'delegation_rules.md':
+    'Sub-agent delegation rules (canonical): **docs/TEAM_ROSTER.md**.\n\n' +
+    'Summary: large work (Standard/Full path) → the Main Agent delegates via the Agent tool. Sub-agents do NOT inherit the ' +
+    'conversation/skills/context → prompts must be SELF-CONTAINED (PRD/TDD links, skills to invoke, Done criteria, relevant files). ' +
+    'Parallelize FE/BE only after the API contract is locked in Phase 2; use isolation: "worktree" for overlapping edits.\n',
+};
+
+async function run(ctx) {
+  const { target, cfg, detect, ask, pkgRoot } = ctx;
+  const manifest = readJSON(path.join(pkgRoot, 'skills.manifest.json'), { groups: {} });
+  cfg.integrations = cfg.integrations || {};
+
+  log.title('Integrations (optional — Enter to accept default)');
+
+  // ---- Skills (process — recommended) ----
+  const procSources = uniqueSources(manifest.groups && manifest.groups.process);
+  if (procSources.length && await ask.yesno(`Install recommended process skills via the \`skills\` CLI? (${procSources.join(', ')})`, true)) {
+    let ok = true;
+    for (const src of procSources) {
+      log.step(`npx skills add ${src}`);
+      if (!runCmd('npx', ['--yes', 'skills', 'add', src, '--yes'], target)) ok = false;
+    }
+    cfg.integrations.skills = ok ? 'installed' : 'partial';
+    if (!ok) log.warn('Some skills did not install. Install manually: ' + procSources.map((s) => `npx skills add ${s}`).join(' ; '));
+    else log.ok('Process skills installed.');
+  } else {
+    cfg.integrations.skills = 'skipped';
+    log.warn('Skills skipped. Later: ' + procSources.map((s) => `npx skills add ${s}`).join(' ; '));
+  }
+
+  // ---- Skills (design — optional, pick one) ----
+  const designSources = uniqueSources(manifest.groups && manifest.groups.design);
+  if (designSources.length && await ask.yesno('Install a design/UI skill pack? (pick your ONE direction afterwards)', false)) {
+    for (const src of designSources) runCmd('npx', ['--yes', 'skills', 'add', src, '--yes'], target);
+    cfg.integrations.design = 'installed';
+    log.ok('Design pack installed — set ONE direction in docs/TEAM_ROSTER.md §3.');
+  }
+
+  // ---- GitNexus (optional) ----
+  if (await ask.yesno('Index this repo with GitNexus now? (npx gitnexus analyze — enables impact analysis)', detect.hasGitnexus)) {
+    log.step('npx gitnexus analyze');
+    cfg.integrations.gitnexus = runCmd('npx', ['--yes', 'gitnexus', 'analyze'], target) ? 'indexed' : 'failed';
+    if (cfg.integrations.gitnexus === 'failed') log.warn('GitNexus not run. Install/retry later: npx gitnexus analyze');
+  } else {
+    cfg.integrations.gitnexus = 'skipped';
+  }
+
+  // ---- Serena (optional — seed pointer memories) ----
+  if (detect.hasSerena || await ask.yesno('Seed Serena pointer-memories? (only if you use the Serena MCP server)', detect.hasSerena)) {
+    const memDir = path.join(target, '.serena', 'memories', 'project');
+    ensureDir(memDir);
+    for (const [name, content] of Object.entries(SERENA_MEMOS)) {
+      fs.writeFileSync(path.join(memDir, name), content);
+    }
+    cfg.integrations.serena = 'seeded';
+    log.ok('Serena pointer-memories seeded (.serena/memories/project/).');
+  } else {
+    cfg.integrations.serena = 'skipped';
+  }
+
+  writeJSON(path.join(target, '.hero-vibe-kit', 'config.json'), cfg);
+}
+
+module.exports = { run };

package/src/links.cjs

@@ -0,0 +1,37 @@
+'use strict';
+const fs = require('fs');
+const path = require('path');
+
+function walk(dir) {
+  let out = [];
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    const p = path.join(dir, e.name);
+    if (e.isDirectory()) out = out.concat(walk(p));
+    else out.push(p);
+  }
+  return out;
+}
+
+// Check relative .md links resolve. roots = list of files or dirs.
+function checkLinks(roots) {
+  const broken = [];
+  let checked = 0;
+  for (const root of roots) {
+    if (!fs.existsSync(root)) continue;
+    const files = fs.statSync(root).isDirectory() ? walk(root).filter((f) => f.endsWith('.md')) : [root];
+    for (const f of files) {
+      const dir = path.dirname(f);
+      const txt = fs.readFileSync(f, 'utf8');
+      const re = /\]\((\.{1,2}\/[^)#? ]+\.md)/g;
+      let m;
+      while ((m = re.exec(txt))) {
+        checked++;
+        const t = path.normalize(path.join(dir, m[1]));
+        if (!fs.existsSync(t)) broken.push({ file: f, link: m[1] });
+      }
+    }
+  }
+  return { broken, checked };
+}
+
+module.exports = { checkLinks, walk };

package/src/merge.cjs

@@ -0,0 +1,61 @@
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const { ensureDir, exists, backup } = require('./util.cjs');
+
+const START = '<!-- hero-vibe-kit:start -->';
+const END = '<!-- hero-vibe-kit:end -->';
+
+function escapeRe(s) { return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); }
+
+function block(inner) {
+  return `${START}\n<!-- Managed by hero-vibe-kit. Update via the framework; edits inside this block are overwritten on \`update\`. -->\n${inner.trim()}\n${END}`;
+}
+
+// Insert/replace the hero-vibe-kit managed block. Preserves everything outside the markers.
+function mergeManagedBlock(file, inner, titleIfNew) {
+  const b = block(inner);
+  if (!exists(file)) {
+    ensureDir(path.dirname(file));
+    const head = titleIfNew ? `# ${titleIfNew}\n\n` : '';
+    fs.writeFileSync(file, head + b + '\n');
+    return 'created';
+  }
+  let txt = fs.readFileSync(file, 'utf8');
+  backup(file);
+  if (txt.includes(START) && txt.includes(END)) {
+    txt = txt.replace(new RegExp(escapeRe(START) + '[\\s\\S]*?' + escapeRe(END)), b);
+  } else {
+    txt = txt.replace(/\s*$/, '') + '\n\n' + b + '\n';
+  }
+  fs.writeFileSync(file, txt);
+  return 'merged';
+}
+
+// Deep-merge our hooks + permissions into an existing settings.json without clobbering the user's.
+function mergeSettings(file, templateFile) {
+  const tpl = JSON.parse(fs.readFileSync(templateFile, 'utf8'));
+  let cur = {};
+  if (exists(file)) { cur = JSON.parse(fs.readFileSync(file, 'utf8')); backup(file); }
+  else ensureDir(path.dirname(file));
+
+  cur.hooks = cur.hooks || {};
+  for (const ev of Object.keys(tpl.hooks || {})) {
+    cur.hooks[ev] = cur.hooks[ev] || [];
+    const existingCmds = new Set();
+    for (const m of cur.hooks[ev]) for (const h of (m.hooks || [])) existingCmds.add(h.command);
+    for (const matcher of tpl.hooks[ev]) {
+      const newHooks = (matcher.hooks || []).filter((h) => !existingCmds.has(h.command));
+      if (newHooks.length) cur.hooks[ev].push(Object.assign({}, matcher, { hooks: newHooks }));
+    }
+  }
+
+  if (tpl.permissions && tpl.permissions.allow) {
+    cur.permissions = cur.permissions || {};
+    cur.permissions.allow = Array.from(new Set([...(cur.permissions.allow || []), ...tpl.permissions.allow]));
+  }
+
+  fs.writeFileSync(file, JSON.stringify(cur, null, 2) + '\n');
+}
+
+module.exports = { mergeManagedBlock, mergeSettings, START, END };

package/src/render.cjs

@@ -0,0 +1,27 @@
+'use strict';
+const fs = require('fs');
+const path = require('path');
+
+function renderString(s, vars) {
+  return s.replace(/\{\{(\w+)\}\}/g, (m, k) => (k in vars ? vars[k] : m));
+}
+
+function walk(dir) {
+  let out = [];
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    const p = path.join(dir, e.name);
+    if (e.isDirectory()) out = out.concat(walk(p));
+    else out.push(p);
+  }
+  return out;
+}
+
+// Returns [{ rel, content }] with placeholders substituted.
+function renderTree(srcDir, vars) {
+  return walk(srcDir).map((abs) => ({
+    rel: path.relative(srcDir, abs),
+    content: renderString(fs.readFileSync(abs, 'utf8'), vars),
+  }));
+}
+
+module.exports = { renderString, renderTree, walk };

package/src/update.cjs

@@ -0,0 +1,59 @@
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const { log, exists, backup, readJSON, writeJSON, ensureDir } = require('./util.cjs');
+const { renderTree, renderString } = require('./render.cjs');
+const { mergeManagedBlock, mergeSettings } = require('./merge.cjs');
+
+const TEAM_LABELS = { solo: 'solo (you + AI)', 'small-team': 'small team (2–5)', enterprise: 'larger team (6+)' };
+const BRANCH_LABELS = { 'gitlab-flow': 'GitLab flow', 'github-flow': 'GitHub flow', trunk: 'trunk-based' };
+
+async function update(opts) {
+  const { pkgRoot, target } = opts;
+  const templates = path.join(pkgRoot, 'templates');
+  log.title('hero-vibe-kit · update');
+
+  const cfg = readJSON(path.join(target, '.hero-vibe-kit', 'config.json'), null);
+  if (!cfg) { log.err('Not initialized (.hero-vibe-kit/config.json missing). Run `hero-vibe-kit init`.'); process.exit(1); }
+
+  const vars = {
+    PROJECT_NAME: cfg.projectName,
+    DATE: new Date().toISOString().slice(0, 10),
+    TEAM_SIZE: TEAM_LABELS[cfg.teamSize] || cfg.teamSize,
+    BRANCHING_MODEL: BRANCH_LABELS[cfg.branchingModel] || cfg.branchingModel,
+  };
+
+  // Re-render managed docs; NEVER touch ACTIVE_STATE (working state).
+  const srcDocs = path.join(templates, 'docs', cfg.lang);
+  let n = 0;
+  for (const f of renderTree(srcDocs, vars)) {
+    if (path.basename(f.rel) === 'ACTIVE_STATE.md') continue;
+    const dest = path.join(target, 'docs', f.rel);
+    ensureDir(path.dirname(dest));
+    if (exists(dest)) backup(dest);
+    fs.writeFileSync(dest, f.content);
+    n++;
+  }
+  log.ok(`Docs re-rendered: ${n} (ACTIVE_STATE.md preserved)`);
+
+  // Managed blocks (content outside markers preserved)
+  const claudeInner = renderString(fs.readFileSync(path.join(templates, 'CLAUDE.md.tmpl'), 'utf8'), vars);
+  const agentsInner = renderString(fs.readFileSync(path.join(templates, 'AGENTS.md.tmpl'), 'utf8'), vars);
+  log.ok(`CLAUDE.md: ${mergeManagedBlock(path.join(target, 'CLAUDE.md'), claudeInner, cfg.projectName)}`);
+  log.ok(`AGENTS.md: ${mergeManagedBlock(path.join(target, 'AGENTS.md'), agentsInner, null)}`);
+
+  // Refresh hooks + settings
+  ensureDir(path.join(target, '.claude', 'hooks'));
+  for (const h of ['git-guard.cjs', 'stop-reminder.cjs']) {
+    fs.copyFileSync(path.join(templates, 'common', '.claude', 'hooks', h), path.join(target, '.claude', 'hooks', h));
+  }
+  mergeSettings(path.join(target, '.claude', 'settings.json'), path.join(templates, 'common', '.claude', 'settings.json'));
+  log.ok('Hooks + settings.json refreshed');
+
+  const newVer = JSON.parse(fs.readFileSync(path.join(pkgRoot, 'package.json'), 'utf8')).version;
+  cfg.version = newVer;
+  writeJSON(path.join(target, '.hero-vibe-kit', 'config.json'), cfg);
+  log.ok(`Now at v${newVer}`);
+}
+
+module.exports = { update };

package/src/util.cjs

@@ -0,0 +1,56 @@
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+
+const C = { reset: '\x1b[0m', dim: '\x1b[2m', red: '\x1b[31m', green: '\x1b[32m', yellow: '\x1b[33m', cyan: '\x1b[36m', bold: '\x1b[1m' };
+const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
+function c(col, s) { return useColor ? col + s + C.reset : s; }
+
+const log = {
+  info: (m) => console.log(m),
+  step: (m) => console.log(c(C.cyan, '» ') + m),
+  ok: (m) => console.log(c(C.green, '✓ ') + m),
+  warn: (m) => console.log(c(C.yellow, '⚠ ') + m),
+  err: (m) => console.error(c(C.red, '✗ ') + m),
+  title: (m) => console.log('\n' + c(C.bold, m)),
+};
+
+function ensureDir(d) { fs.mkdirSync(d, { recursive: true }); }
+function exists(p) { try { fs.accessSync(p); return true; } catch (_) { return false; } }
+function readJSON(p, fallback) { try { return JSON.parse(fs.readFileSync(p, 'utf8')); } catch (_) { return fallback; } }
+function writeJSON(p, obj) { ensureDir(path.dirname(p)); fs.writeFileSync(p, JSON.stringify(obj, null, 2) + '\n'); }
+function backup(p) { if (exists(p)) { const b = p + '.bak'; fs.copyFileSync(p, b); return b; } return null; }
+
+// Interactive asker. When `auto` is true (--yes / non-interactive), never prompts: returns defaults.
+function makeAsker(auto) {
+  let rl = null;
+  function q(question) {
+    if (auto) return Promise.resolve('');
+    if (!rl) rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((res) => rl.question(question, (a) => res(a)));
+  }
+  async function text(label, def) {
+    const a = (await q(`${label}${def ? ` [${def}]` : ''}: `)).trim();
+    return a || def || '';
+  }
+  async function yesno(label, defYes) {
+    if (auto) return defYes;
+    const a = (await q(`${label} ${defYes ? '[Y/n]' : '[y/N]'}: `)).trim().toLowerCase();
+    if (!a) return defYes;
+    return a === 'y' || a === 'yes';
+  }
+  async function choice(label, opts, defIdx) {
+    defIdx = defIdx || 0;
+    if (auto) return opts[defIdx];
+    console.log(label);
+    opts.forEach((o, i) => console.log(`  ${i + 1}) ${o}`));
+    const a = (await q(`Choose [${defIdx + 1}]: `)).trim();
+    const i = parseInt(a, 10);
+    return (i >= 1 && i <= opts.length) ? opts[i - 1] : opts[defIdx];
+  }
+  function close() { if (rl) rl.close(); }
+  return { text, yesno, choice, close };
+}
+
+module.exports = { C, c, log, ensureDir, exists, readJSON, writeJSON, backup, makeAsker };

package/templates/AGENTS.md.tmpl

@@ -0,0 +1,9 @@
+# Agent Instructions — {{PROJECT_NAME}}
+
+> Canonical development process: **[docs/AGENCY_WORKFLOW.md](docs/AGENCY_WORKFLOW.md)** (single source of truth). Applies to any AI agent working in this repo.
+>
+> 1. **Classify the request** via the router table → Read-only / Fast / Standard / Full. Don't run the heavy process for small tasks.
+> 2. **Gate paths** require plan/approval before writing code (Claude Code: Plan Mode).
+> 3. Follow [DEFINITION_OF_DONE](docs/DEFINITION_OF_DONE.md), [BRANCHING](docs/BRANCHING.md), [SECURITY_STANDARDS](docs/SECURITY_STANDARDS.md), [PERFORMANCE_STANDARDS](docs/PERFORMANCE_STANDARDS.md); keep [ACTIVE_STATE](docs/ACTIVE_STATE.md) updated.
+> 4. Clarify requirements per [COMMUNICATION_PROTOCOL](docs/COMMUNICATION_PROTOCOL.md); for AI features use the [PRD_AI_FEATURE template](docs/templates/PRD_AI_FEATURE.md) and [INTERACTION_PATTERNS](docs/INTERACTION_PATTERNS.md).
+> 5. Delegate sub-agents with **self-contained** prompts ([TEAM_ROSTER](docs/TEAM_ROSTER.md)).

package/templates/CLAUDE.md.tmpl

@@ -0,0 +1,11 @@
+## 🧭 hero-vibe-kit workflow
+
+> **READ BEFORE DOING ANYTHING:** [`docs/AGENCY_WORKFLOW.md`](docs/AGENCY_WORKFLOW.md) is the **single source of truth** for the {{PROJECT_NAME}} development process. Classify every request via the router table → pick a path (Read-only / Fast / Standard / Full). Don't run the heavy process for small tasks.
+
+Docs: [AGENCY_WORKFLOW](docs/AGENCY_WORKFLOW.md) · [DEFINITION_OF_DONE](docs/DEFINITION_OF_DONE.md) · [BRANCHING](docs/BRANCHING.md) · [TEAM_ROSTER](docs/TEAM_ROSTER.md) · [ACTIVE_STATE](docs/ACTIVE_STATE.md) · [COMMUNICATION_PROTOCOL](docs/COMMUNICATION_PROTOCOL.md) · [INTERACTION_PATTERNS](docs/INTERACTION_PATTERNS.md) · [SECURITY_STANDARDS](docs/SECURITY_STANDARDS.md) · [PERFORMANCE_STANDARDS](docs/PERFORMANCE_STANDARDS.md) · [PRD_AI_FEATURE template](docs/templates/PRD_AI_FEATURE.md).
+
+- **Workflow state:** read `docs/ACTIVE_STATE.md` at the start of every session and keep it updated.
+- **Gates:** when a path requires a Gate, use Plan Mode (`EnterPlanMode` → `ExitPlanMode`) for real sign-off — not a prose promise.
+- **Enforcement:** `git-guard` (PreToolUse) + `stop-reminder` (Stop) hooks are installed under `.claude/`. Don't bypass them.
+- **GitNexus (if installed):** impact analysis is **conditional** — skip on an empty repo; apply once real code exists (Standard/Full paths) or per the escalation rule. If the index is stale, run `npx gitnexus analyze`.
+- **Skills (if installed):** the workflow references process skills (brainstorming, writing-plans, test-driven-development, systematic-debugging, verification-before-completion, …). Invoke them via the `Skill` tool when relevant.

package/templates/common/.claude/hooks/git-guard.cjs

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+'use strict';
+/*
+ * PreToolUse hook (matcher: Bash) — enforcement "hỗn hợp".
+ * CHẶN (exit 2, stderr -> Claude) các lệnh git nguy hiểm.
+ * NHẮC (exit 0, stderr -> user) khi commit.
+ * Đọc JSON từ stdin theo schema hook của Claude Code: { tool_name, tool_input:{command} }.
+ * Tham chiếu quy trình: docs/AGENCY_WORKFLOW.md, docs/BRANCHING.md, docs/DEFINITION_OF_DONE.md
+ */
+let raw = '';
+process.stdin.on('data', (d) => { raw += d; });
+process.stdin.on('end', () => {
+  let payload = {};
+  try { payload = JSON.parse(raw || '{}'); } catch (_) { process.exit(0); }
+
+  if (payload.tool_name !== 'Bash') process.exit(0);
+  const cmd = String((payload.tool_input && payload.tool_input.command) || '');
+  if (!/\bgit\b/.test(cmd)) process.exit(0);
+
+  const block = (msg) => { console.error('⛔ [git-guard] ' + msg); process.exit(2); };
+
+  const isPush = /\bpush\b/.test(cmd);
+  const isCommit = /\bcommit\b/.test(cmd);
+
+  // 1) Force push (cho phép --force-with-lease)
+  if (isPush && /(--force(?!-with-lease)|(^|\s)-f(\s|$))/.test(cmd)) {
+    block('Chặn force-push (--force/-f). Nếu thực sự cần, dùng --force-with-lease và xác nhận thủ công. ' +
+          '`main` được bảo vệ — đẩy thay đổi qua Merge Request (docs/BRANCHING.md).');
+  }
+
+  // 2) commit --no-verify / -n  (bỏ qua hook/CI)
+  if (isCommit && /(--no-verify|(^|\s)-n(\s|$))/.test(cmd)) {
+    block('Chặn `git commit --no-verify`: không bỏ qua hook/kiểm tra trừ khi User yêu cầu rõ ràng.');
+  }
+
+  // 3) reset --hard (mất thay đổi)
+  if (/\breset\b[\s\S]*--hard/.test(cmd)) {
+    block('Chặn `git reset --hard` (có thể mất thay đổi). Cân nhắc `git stash`, hoặc chạy thủ công nếu thực sự muốn.');
+  }
+
+  // 4) push thẳng lên main (token "main" độc lập hoặc refspec :main)
+  if (isPush && /(^|\s|:)main(\s|$)/.test(cmd) && !/--dry-run/.test(cmd)) {
+    block('Chặn push thẳng lên `main` (được bảo vệ). Tạo nhánh + Merge Request (docs/BRANCHING.md).');
+  }
+
+  // NHẮC (không chặn) khi commit
+  if (isCommit) {
+    console.error('🔔 [git-guard] Trước khi commit, kiểm tra: ' +
+      '(1) docs/ACTIVE_STATE.md đã cập nhật? ' +
+      '(2) đã chạy gitnexus_detect_changes (khi đã có code)? ' +
+      '(3) message theo Conventional Commits? — xem docs/DEFINITION_OF_DONE.md');
+  }
+
+  process.exit(0);
+});

package/templates/common/.claude/hooks/stop-reminder.cjs

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+'use strict';
+/*
+ * Stop hook — nhắc mềm (non-blocking, exit 0).
+ * Nếu có thay đổi chưa commit mà docs/ACTIVE_STATE.md chưa được động tới,
+ * in nhắc nhở (hiển thị cho user). KHÔNG chặn việc dừng (không exit 2 -> tránh vòng lặp).
+ */
+const { execSync } = require('child_process');
+
+let raw = '';
+process.stdin.on('data', (d) => { raw += d; });
+process.stdin.on('end', () => {
+  let payload = {};
+  try { payload = JSON.parse(raw || '{}'); } catch (_) { /* ignore */ }
+  if (payload.stop_hook_active) process.exit(0); // tránh kích hoạt lặp
+
+  const cwd = payload.cwd || process.cwd();
+  let status = '';
+  try {
+    status = execSync('git status --porcelain', { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+  } catch (_) { process.exit(0); }
+
+  const lines = status.split('\n').map((l) => l.trim()).filter(Boolean);
+  if (lines.length === 0) process.exit(0); // không có gì thay đổi
+
+  const stateTouched = lines.some((l) => /ACTIVE_STATE\.md$/.test(l));
+  const otherChanged = lines.some((l) => !/ACTIVE_STATE\.md$/.test(l));
+
+  if (otherChanged && !stateTouched) {
+    console.error('🔔 [stop-reminder] Có thay đổi chưa commit nhưng docs/ACTIVE_STATE.md chưa được cập nhật. ' +
+      'Nếu trạng thái công việc đã đổi, hãy cập nhật bảng pipeline + resume protocol (docs/AGENCY_WORKFLOW.md §0).');
+  }
+  process.exit(0);
+});

package/templates/common/.claude/settings.json

@@ -0,0 +1,25 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/git-guard.cjs"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/stop-reminder.cjs"
+          }
+        ]
+      }
+    ]
+  }
+}

package/templates/docs/en/ACTIVE_STATE.md

@@ -0,0 +1,28 @@
+# Project Active State
+
+**Last Updated:** {{DATE}}
+**Current Global Phase:** 0 — Initialization & Setup
+
+> 📌 **The "Active Features" table below IS the durable cross-session backlog.** It is the primary source of state when resuming.
+> `TaskCreate`/`TaskList` only live **within the current session** (in-memory, lost when the session closes) — use them to track current work, NOT as a long-term backlog. Whenever a feature's status changes → update this table and the corresponding MR/issue (if any).
+
+## Active Features in Pipeline
+
+| Feature / Epic | Path | Current phase | Branch / MR | Status | PRD | TDD |
+| :--- | :--- | :--- | :--- | :--- | :--- | :--- |
+| N/A | N/A | N/A | - | Idle | - | - |
+
+## Blockers / Pending Actions
+- Waiting for the Product Owner to propose the first feature/idea.
+- Decide the tech stack → fill the placeholders in [DEFINITION_OF_DONE.md](./DEFINITION_OF_DONE.md).
+- Decide the design direction → update [TEAM_ROSTER.md](./TEAM_ROSTER.md) §3.
+
+## Session Resume Protocol
+*An AI starting a new session READS this section:*
+1. Read [AGENCY_WORKFLOW.md](./AGENCY_WORKFLOW.md) (SSOT) for the router & paths.
+2. Look at the "Active Features" table above + any **open MRs** (`git branch`, MR list) — do NOT rely on the previous session's TaskList (it's gone).
+3. By each feature's path & phase:
+   - **Read-only/Fast**: continue/finish then open the MR.
+   - **Standard/Full at Phase 1–2**: continue brainstorming/planning with the user (via the Plan Mode gate).
+   - **Standard/Full at Phase 3–4**: open the linked PRD/TDD, check code & branch status, recreate tasks with `TaskCreate` for this session, ask the user before resuming code/test.
+4. Update this table when you start working.

package/templates/docs/en/AGENCY_WORKFLOW.md

@@ -0,0 +1,126 @@
+# Agency Workflow — Single Source of Truth
+
+> **This is the ONLY canonical process document.** Every other file (CLAUDE.md, AGENTS.md, TEAM_ROSTER.md, Serena memories) only **links** here — it must NOT copy the content. To change the process, edit only this file.
+
+The AI acts as a lean software agency. Operating scale: **{{TEAM_SIZE}} + AI**, following **{{BRANCHING_MODEL}}** (see [BRANCHING.md](./BRANCHING.md)). Completion criteria: see [DEFINITION_OF_DONE.md](./DEFINITION_OF_DONE.md).
+
+The personas (BA / Architect / Developer / QA / Scrum Master) are **thinking lenses**, not mandatory ceremony for every task — details in [TEAM_ROSTER.md](./TEAM_ROSTER.md).
+
+---
+
+## 0. Golden rules
+
+1. **Start every request by CLASSIFYING the task** (table §1) → pick the right *path*. Don't default to the full 5-phase process for everything.
+2. **Don't jump into code while the request is unclear.** For Standard/Full paths, clarify scope first.
+3. **A gate is real Plan Mode, not a promise.** When a path requires a "Gate", use `EnterPlanMode` → present the plan → `ExitPlanMode` for the user to approve. This is a harness-enforced block, replacing the prose "wait for sign-off".
+4. **Update [ACTIVE_STATE.md](./ACTIVE_STATE.md)** when starting / finishing a unit of work. It is the durable cross-session backlog (TaskCreate only lives within the current session).
+5. **Follow [COMMUNICATION_PROTOCOL.md](./COMMUNICATION_PROTOCOL.md) in every interaction** — especially when clarifying requirements: no silent assumptions, layered certainty, blocking/non-blocking question classification, close the loop on misunderstandings.
+
+---
+
+## 1. Task classification → workflow (ROUTER)
+
+When a request arrives, consult this table first to pick path, branch, required steps, and DoD.
+
+| # | Task type | Trigger / example | Path | Gate | Branch | Required steps | Skills / Tools | DoD (short) |
+|---|---|---|---|---|---|---|---|---|
+| 1 | **Q&A / Explain / Find code** | "Explain X", "find where Y is handled", "what does this code do" | Read-only | No | — | Answer directly, **don't edit files** | `gitnexus_query`, `gitnexus_context`, serena `find_symbol` | Correct answer + `file:line` citations; no branch/commit |
+| 2 | **Chore / Docs / Config** | edit README, change config, bump version, format | Fast | No | `chore/` `docs/` | edit → MR | — | build/lint green; no runtime behavior change |
+| 3 | **Small bugfix (localized)** | clear root cause, ≤ ~2 files, not a shared symbol | Fast | No (but **repro test required**) | `fix/` | `systematic-debugging` → write a RED test reproducing the bug → fix → GREEN → MR | systematic-debugging, test-driven-development, verification-before-completion | bug repro test (red→green); regression green; root cause noted in MR |
+| 4 | **Hotfix (urgent prod)** | production incident needs an urgent patch | Fast (expedited) | No | `hotfix/` (off `main`) | minimal fix + test → fast MR → backport to the development branch | systematic-debugging, verify | incident patched + test; backported; logged for post-mortem |
+| 5 | **Change logic of an existing feature** | "change how X is computed", "add a condition to Y", "change behavior Z" | Standard | **YES** | `change/` | **impact analysis REQUIRED** → ensure/add regression tests → implement → QA review | `gitnexus_impact` (upstream), test-driven-development, code-review | impact reported; regression + new tests green; `detect_changes` scope correct |
+| 6 | **Refactor (NO behavior change)** | "split this module", "rename", "clean up" | Standard | **YES** | `refactor/` | tests GREEN before → impact analysis → change (use `gitnexus_rename`) → tests GREEN after (unchanged) | gitnexus_rename, gitnexus_impact, simplify | same test suite passes before & after; NO manual find-replace |
+| 7 | **New feature** | "build feature Z" | Full (5-phase) | **YES (2 gates: PRD + TDD)** | `feat/` | full §3 | brainstorming, writing-plans, test-driven-development, design system, code-review, security-review | full [DEFINITION_OF_DONE.md](./DEFINITION_OF_DONE.md) |
+| 8 | **Spike / Research / POC** | "feasibility study", "try an approach" | Timeboxed | No (timebox instead of gate) | `spike/` (throwaway) | clear timebox → output a **recommendation doc**; **do NOT merge POC code** into main | deep-research, gitnexus_exploring | conclusion + recommendation doc; POC code stays out of main |
+
+### Escalation rule
+A task on the **Fast path** that turns out to:
+- touch a symbol with many callers / `gitnexus_impact` returns **MEDIUM or higher**, OR
+- spread across **> 5 files**,
+
+→ **stop and escalate to the Standard path**: open Plan Mode (gate), run and report impact analysis before continuing.
+
+---
+
+## 2. The four paths (definitions)
+
+### Read-only
+Answer questions, read/explain code. No branch, no gate, no commit. Prefer `gitnexus_query`/`gitnexus_context` over blind grep. Always cite `file:line`.
+
+### Fast path
+For small, low-risk work (chore/docs/localized bugfix/hotfix).
+1. Create a branch with the right prefix (see [BRANCHING.md](./BRANCHING.md)).
+2. Make the change. For a **bugfix**: write a failing (red) test that reproduces the bug BEFORE fixing.
+3. Quick self-review (`code-review` if you want) + run tests/lint.
+4. Open an MR against the "Fast" DoD in [DEFINITION_OF_DONE.md](./DEFINITION_OF_DONE.md).
+> No plan sign-off needed. But if you hit the escalation rule → move to Standard.
+
+### Standard path
+For changing existing feature logic & refactors.
+1. **Gate**: `EnterPlanMode` → investigate + run `gitnexus_impact` (upstream) → present a plan stating **blast radius + risk level** → `ExitPlanMode` and wait for approval.
+2. Warn the user if risk is **HIGH/CRITICAL** before continuing.
+3. Implement with TDD; for refactors keep tests unchanged.
+4. QA: spawn a review sub-agent (`code-review` + `security-review` if touching a sensitive surface) + `gitnexus_detect_changes`.
+5. MR against the "Standard" DoD.
+
+### Full path (5-phase) — new features only
+See §3.
+
+---
+
+## 3. Full path: 5 phases for a new feature
+
+> Applies only to task type **#7 (Feature)**. Small tasks do NOT run these phases.
+
+### Phase 1 — Discovery & Scoping (lens: Business Analyst)
+1. Trigger the `brainstorming` skill. **Apply [COMMUNICATION_PROTOCOL.md](./COMMUNICATION_PROTOCOL.md)** throughout (how to ask, label assumptions, close each round with a summary + open questions + assumptions).
+2. Clarify: User Personas, Business Flows, Edge Cases, goals, acceptance criteria.
+3. **If it's an AI/assistant feature:** use the **[PRD_AI_FEATURE.md template](./templates/PRD_AI_FEATURE.md)** — it forces the AI-specific dimensions (behavior under ambiguity, guardrails/refusal, definition of "correct" + golden examples, eval strategy, fallback/HITL), and references [INTERACTION_PATTERNS.md](./INTERACTION_PATTERNS.md) for how the assistant talks to end-users.
+4. Output: **PRD / Scope Document** (copy to `docs/specs/YYYY-MM-DD-<feature>.md`, link in ACTIVE_STATE) — including a Decision Log + Assumptions Register.
+5. **GATE 1 (Plan Mode):** present the PRD → `ExitPlanMode` → wait for the user (Product Owner) to approve.
+
+### Phase 2 — Architecture & Planning (lens: System Architect)
+1. `gitnexus_exploring` to understand the current architecture (skip if the relevant area is empty).
+2. `gitnexus_impact` for any change to existing code.
+3. **Lightweight threat modeling (shift-left):** list attack surface / sensitive data / permissions right here, per [SECURITY_STANDARDS.md](./SECURITY_STANDARDS.md) — don't push it all to QA.
+4. **Set the performance budget:** decide target latency/throughput/token-cost per [PERFORMANCE_STANDARDS.md](./PERFORMANCE_STANDARDS.md) (fill the `<TBD>`s).
+5. **Lock the API/interface contract** between components (FE↔BE, module↔module). *This is a prerequisite for parallelizing in Phase 3.*
+6. Trigger `writing-plans` to break down the work → create tasks with `TaskCreate` (session-scoped) + record in ACTIVE_STATE (durable).
+7. Output: **Technical Design Document (TDD)** + task list.
+8. **GATE 2 (Plan Mode):** present the TDD → `ExitPlanMode` → wait for approval of the technical approach.
+
+### Phase 3 — Implementation (lens: Developer, possibly a sub-agent)
+1. Mark tasks `in_progress` (`TaskUpdate`) + update ACTIVE_STATE.
+2. Large work → **delegate to sub-agents** via the `Agent` tool. **Sub-agent prompts must be self-contained** (sub-agents do NOT inherit the conversation/skills): embed PRD/TDD links, name the skills to invoke, the Done criteria, and the relevant files. Details: [TEAM_ROSTER.md](./TEAM_ROSTER.md).
+3. **Conditional parallelization:** only spawn FE & BE in parallel **after the API contract (Phase 2.5) is locked**. When multiple agents edit overlapping files → `isolation: "worktree"`.
+4. Developers apply `test-driven-development`.
+5. Frontend follows **one** locked design direction (don't invoke multiple design skills at once — see TEAM_ROSTER §design).
+
+### Phase 4 — Quality Assurance (lens: QA, sub-agent)
+1. Spawn a Code Reviewer / QA sub-agent (self-contained prompt).
+2. QA runs `verification-before-completion`, `security-review`, `systematic-debugging` as needed. Check against [SECURITY_STANDARDS.md](./SECURITY_STANDARDS.md) + [PERFORMANCE_STANDARDS.md](./PERFORMANCE_STANDARDS.md) (incl. OWASP LLM Top 10 for AI features, and performance budgets).
+3. `gitnexus_detect_changes` to confirm no unexpected execution flows broke.
+4. Must meet [DEFINITION_OF_DONE.md](./DEFINITION_OF_DONE.md) (Full level) before merging.
+
+### Phase 5 — Handover & Retro (lens: DevOps / Scrum Master)
+1. Trigger `finishing-a-development-branch` → open/merge the MR per [BRANCHING.md](./BRANCHING.md).
+2. Update **CLAUDE.md** if there are new architectural decisions (record only what's new, don't duplicate).
+3. **Light retro (3 lines):** what went well / what was painful / one improvement for next time — record in ACTIVE_STATE or the MR.
+4. Save project context to Serena memory (pointers, no content duplication).
+5. Mark tasks `completed` + update ACTIVE_STATE.
+
+---
+
+## 4. Related documents
+| File | Content |
+|------|---------|
+| [TASK router §1](#1-task-classification--workflow-router) | Pick a path by task type |
+| [DEFINITION_OF_DONE.md](./DEFINITION_OF_DONE.md) | Measurable completion criteria (per path) |
+| [BRANCHING.md](./BRANCHING.md) | Branching model, branch naming, Conventional Commits |
+| [TEAM_ROSTER.md](./TEAM_ROSTER.md) | Personas + sub-agent delegation rules + design direction |
+| [ACTIVE_STATE.md](./ACTIVE_STATE.md) | Pipeline state + resume protocol |
+| [COMMUNICATION_PROTOCOL.md](./COMMUNICATION_PROTOCOL.md) | Human↔AI communication protocol (requirements clarification) |
+| [templates/PRD_AI_FEATURE.md](./templates/PRD_AI_FEATURE.md) | PRD template for AI features (dimensions to clarify) |
+| [INTERACTION_PATTERNS.md](./INTERACTION_PATTERNS.md) | How the product (assistant) talks to end-users |
+| [SECURITY_STANDARDS.md](./SECURITY_STANDARDS.md) | Security baseline + OWASP LLM Top 10 |
+| [PERFORMANCE_STANDARDS.md](./PERFORMANCE_STANDARDS.md) | Performance budgets + AI standards (prompt caching…) |