hero-vibe-kit 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to hero-vibe-kit are documented here. Format based on
+[Keep a Changelog](https://keepachangelog.com/); versioning follows [SemVer](https://semver.org/).
+
+## [0.1.0] - Unreleased
+### Added
+- `npx hero-vibe-kit init` — installs the workflow into a project (new or brownfield), idempotent, with backups.
+- `update` — re-renders framework-managed regions while preserving user edits and working files (ACTIVE_STATE).
+- `doctor` — validates settings.json, hook self-tests, doc-link integrity, and tool presence.
+- Bilingual docs (EN + VI): AGENCY_WORKFLOW (task-type router + 5 phases), DEFINITION_OF_DONE, BRANCHING,
+  TEAM_ROSTER, ACTIVE_STATE, COMMUNICATION_PROTOCOL, INTERACTION_PATTERNS, SECURITY_STANDARDS,
+  PERFORMANCE_STANDARDS, and a PRD_AI_FEATURE template.
+- Enforcement hooks for Claude Code: `git-guard` (blocks force-push / `--no-verify` / `reset --hard` /
+  direct push to main; reminds on commit) and `stop-reminder`.
+- Managed-region markers (`<!-- hero-vibe-kit:start/end -->`) for safe updates.
+- Presets: solo, small-team, enterprise.
+- Optional integrations (reference & auto-install, never bundled): superpowers/taste skills via the `skills`
+  CLI, GitNexus indexing, Serena pointer-memories. All degrade gracefully when absent.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hung Vi Manh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,165 @@
+# hero-vibe-kit
+
+> An opinionated, AI-assisted software-development workflow for **Claude Code** — a task-type router, real gates, enforcement hooks, a human↔AI communication protocol, and security/performance standards. Works for **new** and **existing (brownfield)** projects.
+
+*(English below · [Tiếng Việt ở dưới](#tiếng-việt))*
+
+---
+
+## What it is
+
+`hero-vibe-kit` drops a complete, lightweight development process into your repo so any AI agent (Claude Code first) works the way a disciplined team would:
+
+- **Task-type router** — every request is classified (Q&A · chore · bugfix · hotfix · change · refactor · feature · spike) and routed to the right *path* (Read-only / Fast / Standard / Full). No heavy ceremony for small tasks.
+- **Real gates** — "wait for approval" is enforced via Claude Code **Plan Mode**, not prose.
+- **Enforcement hooks** — `git-guard` blocks force-push, `--no-verify`, `reset --hard`, and direct pushes to `main`; `stop-reminder` nudges you to keep state updated.
+- **Human↔AI communication protocol** — no silent assumptions, blocking vs non-blocking questions, decision/assumption logs — tuned for building AI products.
+- **Standards** — a measurable Definition of Done, branching model, and **Security** (incl. OWASP LLM Top 10) + **Performance** (incl. prompt caching) baselines.
+- **AI-feature PRD template** + **interaction patterns** for how your product talks to its end-users.
+
+It is **documentation + hooks + a CLI** — it does not bundle third-party tools; it integrates with them and degrades gracefully when they're absent.
+
+## Quick start
+
+```bash
+# In your project root (new or existing):
+npx hero-vibe-kit init
+
+# Then restart Claude Code (or run /hooks) to activate the hooks, and:
+npx hero-vibe-kit doctor
+```
+
+Non-interactive / CI:
+
+```bash
+npx hero-vibe-kit init --yes --preset small-team --lang en --skip-integrations
+```
+
+## What `init` installs
+
+```
+your-project/
+  CLAUDE.md          # hero-vibe-kit managed block (your other content preserved)
+  AGENTS.md          # cross-agent entry pointer
+  docs/              # AGENCY_WORKFLOW (SSOT) + DEFINITION_OF_DONE, BRANCHING, TEAM_ROSTER,
+                     # ACTIVE_STATE, COMMUNICATION_PROTOCOL, INTERACTION_PATTERNS,
+                     # SECURITY_STANDARDS, PERFORMANCE_STANDARDS, templates/PRD_AI_FEATURE
+  .claude/
+    settings.json    # hooks merged into your existing settings (not clobbered)
+    hooks/           # git-guard.cjs, stop-reminder.cjs
+  .hero-vibe-kit/
+    config.json      # your choices (team size, branching, language, integrations)
+```
+
+- **New project**: scaffolds everything.
+- **Brownfield**: never overwrites your `CLAUDE.md`/`AGENTS.md`/`settings.json` — it inserts a marked managed block and deep-merges hooks. Your `docs/ACTIVE_STATE.md` is never overwritten. Re-running is idempotent; touched files are backed up to `*.bak`.
+
+## The task router (heart of it)
+
+| Task | Path | Gate | Branch |
+|------|------|------|--------|
+| Q&A / explain / find code | Read-only | — | — |
+| chore / docs / config | Fast | — | `chore/` `docs/` |
+| small bugfix | Fast | — (repro test) | `fix/` |
+| hotfix | Fast | — | `hotfix/` |
+| change existing logic | Standard | ✅ | `change/` |
+| refactor | Standard | ✅ | `refactor/` |
+| new feature | Full (5-phase) | ✅✅ | `feat/` |
+| spike / research | Timeboxed | — | `spike/` |
+
+Full details in `docs/AGENCY_WORKFLOW.md` (the single source of truth).
+
+## Integrations (optional — reference & auto-install)
+
+hero-vibe-kit **does not redistribute** third-party tools. `init` offers to set them up from their original sources and degrades gracefully if they're missing.
+
+| Tool | What it is | What init does | Tier |
+|------|-----------|----------------|------|
+| **superpowers** | process skills (brainstorming, TDD, debugging…) from `obra/superpowers` | offers `npx skills add obra/superpowers` | recommended |
+| **taste-skill** | UI/design skills from `Leonxlnx/taste-skill` | offers to install; pick ONE direction | optional |
+| **GitNexus** | code-intelligence CLI/MCP | offers `npx gitnexus analyze` | optional |
+| **Serena** | MCP memory server | seeds pointer-memories if present | optional |
+
+**Required:** Node ≥ 18 and Claude Code. Everything else is optional.
+
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `init` | Install into the current project |
+| `update` | Re-render managed regions, preserving your edits & working files |
+| `doctor` | Validate hooks, settings.json, doc links, tool presence |
+| `version` | Print version |
+
+Flags: `--dir <path>` · `--preset solo|small-team|enterprise` · `--lang en|vi` · `--name <name>` · `--yes` · `--skip-integrations`.
+
+## Update & customize
+
+- Edit anything **outside** the `<!-- hero-vibe-kit:start/end -->` markers freely — `update` won't touch it.
+- Fill the `<TBD>` placeholders in DEFINITION_OF_DONE / SECURITY / PERFORMANCE once you pick a stack.
+- `npx hero-vibe-kit update` refreshes the managed docs/hooks to the latest version, backing up changes.
+
+## Uninstall
+
+Remove `docs/` framework files, the `.claude/hooks/*` + the hooks block in `settings.json`, the
+`<!-- hero-vibe-kit:* -->` block in `CLAUDE.md`/`AGENTS.md`, and `.hero-vibe-kit/`.
+
+## License & attribution
+
+MIT (see [LICENSE](./LICENSE)). hero-vibe-kit references but does not redistribute
+[obra/superpowers](https://github.com/obra/superpowers) and [Leonxlnx/taste-skill](https://github.com/Leonxlnx/taste-skill);
+they are installed from source via the `skills` CLI under their own licenses.
+
+---
+
+# Tiếng Việt
+
+> Một quy trình phát triển phần mềm có AI hỗ trợ, dùng cho **Claude Code** — bảng phân loại task, gate thật, hook cưỡng chế, giao thức giao tiếp Human↔AI, và chuẩn bảo mật/hiệu năng. Chạy tốt cho **project mới** lẫn **code cũ (brownfield)**.
+
+## Là gì
+
+`hero-vibe-kit` cài một quy trình phát triển hoàn chỉnh, tinh gọn vào repo của bạn để mọi AI agent (Claude Code trước) làm việc kỷ luật như một team thực thụ:
+
+- **Bảng phân loại task** → chọn đúng *path* (Read-only / Fast / Standard / Full). Việc nhỏ không phải chạy quy trình nặng.
+- **Gate thật** qua **Plan Mode** của Claude Code, không phải lời hứa văn xuôi.
+- **Hook cưỡng chế** — `git-guard` chặn force-push, `--no-verify`, `reset --hard`, push thẳng `main`; `stop-reminder` nhắc cập nhật trạng thái.
+- **Giao thức giao tiếp Human↔AI** — no silent assumptions, câu hỏi blocking/non-blocking, decision/assumption log — thiết kế cho việc xây sản phẩm AI.
+- **Chuẩn** — Definition of Done đo được, branching model, và baseline **Security** (gồm OWASP LLM Top 10) + **Performance** (gồm prompt caching).
+- **Template PRD cho feature AI** + **interaction patterns** cho cách sản phẩm giao tiếp với end-user.
+
+Đây là **tài liệu + hook + CLI** — không đóng gói tool bên thứ ba; chỉ tích hợp và degrade mượt khi thiếu.
+
+## Bắt đầu nhanh
+
+```bash
+# Ở thư mục gốc project (mới hoặc đã có code):
+npx hero-vibe-kit init
+
+# Khởi động lại Claude Code (hoặc /hooks) để bật hook, rồi:
+npx hero-vibe-kit doctor
+```
+
+Không tương tác / CI:
+
+```bash
+npx hero-vibe-kit init --yes --preset small-team --lang vi --skip-integrations
+```
+
+## init cài gì
+
+Như sơ đồ ở phần English: `docs/` (AGENCY_WORKFLOW là single source of truth + các chuẩn), `CLAUDE.md`/`AGENTS.md` (chèn **block có marker**, giữ nguyên nội dung của bạn), `.claude/` (hook + settings deep-merge), `.hero-vibe-kit/config.json`.
+
+- **Project mới**: scaffold đầy đủ.
+- **Brownfield**: KHÔNG đè `CLAUDE.md`/`AGENTS.md`/`settings.json` — chỉ chèn block + merge hook. `docs/ACTIVE_STATE.md` không bị ghi đè. Chạy lại idempotent; file bị đụng được sao lưu `*.bak`.
+
+## Tích hợp (tùy chọn — reference & auto-install)
+
+hero-vibe-kit **không redistribute** tool bên thứ ba. `init` mời cài từ nguồn gốc và degrade nếu thiếu: **superpowers** (`npx skills add obra/superpowers`, khuyến nghị), **taste-skill** (tùy chọn, chọn 1 hướng), **GitNexus** (`npx gitnexus analyze`, tùy chọn), **Serena** (seed pointer-memories, tùy chọn). **Bắt buộc:** Node ≥ 18 + Claude Code.
+
+## Lệnh & cập nhật
+
+`init` · `update` (giữ chỉnh sửa ngoài marker + file làm việc) · `doctor` · `version`. Sửa thoải mái phần **ngoài** marker `<!-- hero-vibe-kit:start/end -->`. Điền `<TBD>` khi chốt tech stack.
+
+## Giấy phép
+
+MIT (xem [LICENSE](./LICENSE)). Tham chiếu chứ không redistribute `obra/superpowers` và `Leonxlnx/taste-skill` — cài từ nguồn qua `skills` CLI theo license riêng của chúng.

package/bin/hero-vibe-kit.js

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+'use strict';
+const path = require('path');
+const PKG_ROOT = path.resolve(__dirname, '..');
+
+function parseArgs(argv) {
+  const flags = {};
+  const pos = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith('--')) {
+      const key = a.slice(2);
+      if (argv[i + 1] !== undefined && !argv[i + 1].startsWith('--')) flags[key] = argv[++i];
+      else flags[key] = true;
+    } else if (a.startsWith('-') && a.length === 2) {
+      flags[a.slice(1)] = true;
+    } else pos.push(a);
+  }
+  return { cmd: pos[0], pos, flags };
+}
+
+function printHelp() {
+  console.log(`hero-vibe-kit — AI-assisted development workflow for Claude Code
+
+Usage: npx hero-vibe-kit <command> [flags]
+
+Commands:
+  init      Install the workflow into the current project (new or brownfield)
+  update    Re-render managed regions, preserving your edits
+  doctor    Validate the install (hooks, settings.json, doc links, tools)
+  version   Print the version
+  help      Show this help
+
+Flags:
+  --dir <path>          Target project dir (default: current dir)
+  --preset <name>       solo | small-team | enterprise
+  --lang <en|vi>        Docs language (default: en)
+  --name <name>         Project name (default: dir name)
+  --yes                 Non-interactive; accept defaults
+  --skip-integrations   Skip skills / gitnexus / serena prompts`);
+}
+
+async function main() {
+  const { cmd, flags } = parseArgs(process.argv.slice(2));
+  const target = flags.dir ? path.resolve(String(flags.dir)) : process.cwd();
+  const opts = { pkgRoot: PKG_ROOT, target, flags };
+  const version = () => console.log(require('../package.json').version);
+
+  if (flags.version || flags.v) { version(); return; }
+
+  switch (cmd) {
+    case 'init': await require('../src/init.cjs').init(opts); break;
+    case 'update': await require('../src/update.cjs').update(opts); break;
+    case 'doctor': await require('../src/doctor.cjs').doctor(opts); break;
+    case 'version': version(); break;
+    case 'help': case undefined: printHelp(); break;
+    default:
+      console.error('Unknown command: ' + cmd); printHelp(); process.exit(1);
+  }
+}
+
+main().catch((e) => { console.error((e && e.stack) || e); process.exit(1); });

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "hero-vibe-kit",
+  "version": "0.1.0",
+  "description": "An opinionated, AI-assisted software development workflow for Claude Code — task-type router, gates, enforcement hooks, human↔AI communication protocol, and security/performance standards. Works for new and existing (brownfield) projects.",
+  "keywords": [
+    "claude-code",
+    "ai-workflow",
+    "agentic-development",
+    "scaffolding",
+    "developer-workflow",
+    "ai-assistant"
+  ],
+  "license": "MIT",
+  "type": "commonjs",
+  "bin": {
+    "hero-vibe-kit": "bin/hero-vibe-kit.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "templates",
+    "presets",
+    "skills.manifest.json",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {}
+}

package/presets/enterprise.json

@@ -0,0 +1,6 @@
+{
+  "teamSize": "enterprise",
+  "branchingModel": "gitlab-flow",
+  "enforceLevel": "hard",
+  "lang": "en"
+}

package/presets/small-team.json

@@ -0,0 +1,6 @@
+{
+  "teamSize": "small-team",
+  "branchingModel": "github-flow",
+  "enforceLevel": "mixed",
+  "lang": "en"
+}

package/presets/solo.json

@@ -0,0 +1,6 @@
+{
+  "teamSize": "solo",
+  "branchingModel": "trunk",
+  "enforceLevel": "soft",
+  "lang": "en"
+}

package/skills.manifest.json

@@ -0,0 +1,39 @@
+{
+  "$comment": "Skills the hero-vibe-kit workflow references. hero-vibe-kit does NOT bundle these — it records them here and (optionally, with consent) installs them via the `skills` CLI from their ORIGINAL sources. This avoids redistribution and keeps skills up to date. See docs: TEAM_ROSTER / AGENCY_WORKFLOW.",
+  "schema": 1,
+  "installer": "skills",
+  "groups": {
+    "process": {
+      "tier": "recommended",
+      "description": "Core process skills the workflow invokes by name. Without them the workflow still runs (gates/hooks/router intact) but loses skill-guided depth.",
+      "skills": [
+        { "name": "using-superpowers", "source": "obra/superpowers" },
+        { "name": "brainstorming", "source": "obra/superpowers" },
+        { "name": "writing-plans", "source": "obra/superpowers" },
+        { "name": "executing-plans", "source": "obra/superpowers" },
+        { "name": "test-driven-development", "source": "obra/superpowers" },
+        { "name": "systematic-debugging", "source": "obra/superpowers" },
+        { "name": "verification-before-completion", "source": "obra/superpowers" },
+        { "name": "requesting-code-review", "source": "obra/superpowers" },
+        { "name": "receiving-code-review", "source": "obra/superpowers" },
+        { "name": "dispatching-parallel-agents", "source": "obra/superpowers" },
+        { "name": "subagent-driven-development", "source": "obra/superpowers" },
+        { "name": "using-git-worktrees", "source": "obra/superpowers" },
+        { "name": "finishing-a-development-branch", "source": "obra/superpowers" },
+        { "name": "writing-skills", "source": "obra/superpowers" }
+      ]
+    },
+    "design": {
+      "tier": "optional",
+      "description": "Design/UI skills. Pick ONE design direction per project (see TEAM_ROSTER §design). init asks which to install; it does NOT install the whole set.",
+      "pickOne": true,
+      "skills": [
+        { "name": "design-taste-frontend", "source": "Leonxlnx/taste-skill" },
+        { "name": "minimalist-ui", "source": "Leonxlnx/taste-skill" },
+        { "name": "industrial-brutalist-ui", "source": "Leonxlnx/taste-skill" },
+        { "name": "high-end-visual-design", "source": "Leonxlnx/taste-skill" },
+        { "name": "brandkit", "source": "Leonxlnx/taste-skill" }
+      ]
+    }
+  }
+}

package/src/detect.cjs

@@ -0,0 +1,42 @@
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const { exists } = require('./util.cjs');
+
+const CODE_EXT = new Set(['.js', '.mjs', '.cjs', '.ts', '.jsx', '.tsx', '.py', '.go', '.rs', '.java', '.rb', '.php', '.cs', '.cpp', '.c', '.h', '.vue', '.svelte', '.kt', '.swift', '.scala', '.dart']);
+const SKIP = new Set(['.git', 'node_modules', '.gitnexus', '.agents', '.hero-vibe-kit', 'templates', 'dist', 'build', '.next', 'out', 'vendor', '__pycache__', '.serena', '.claude', 'coverage']);
+
+function findCode(dir, depth) {
+  if (depth > 3) return false;
+  let entries;
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch (_) { return false; }
+  for (const e of entries) {
+    if (e.isDirectory()) {
+      if (SKIP.has(e.name) || e.name.startsWith('.')) continue;
+      if (findCode(path.join(dir, e.name), depth + 1)) return true;
+    } else if (CODE_EXT.has(path.extname(e.name))) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function detect(target) {
+  const r = {
+    target,
+    isGitRepo: exists(path.join(target, '.git')),
+    existingClaudeMd: exists(path.join(target, 'CLAUDE.md')),
+    existingAgentsMd: exists(path.join(target, 'AGENTS.md')),
+    existingSettings: exists(path.join(target, '.claude', 'settings.json')),
+    existingActiveState: exists(path.join(target, 'docs', 'ACTIVE_STATE.md')),
+    existingConfig: exists(path.join(target, '.hero-vibe-kit', 'config.json')),
+    hasSkillsLock: exists(path.join(target, 'skills-lock.json')),
+    hasSerena: exists(path.join(target, '.serena')),
+    hasGitnexus: exists(path.join(target, '.gitnexus')),
+    hasCode: findCode(target, 0),
+  };
+  r.brownfield = r.hasCode || r.existingClaudeMd || r.existingAgentsMd;
+  return r;
+}
+
+module.exports = { detect };

package/src/doctor.cjs

@@ -0,0 +1,74 @@
+'use strict';
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { log, exists, readJSON } = require('./util.cjs');
+const { checkLinks } = require('./links.cjs');
+
+function hookCheck(hookFile, payload) {
+  const r = spawnSync('node', [hookFile], { input: JSON.stringify(payload), encoding: 'utf8' });
+  return { code: r.status, err: (r.stderr || '').trim() };
+}
+function which(cmd) {
+  const r = spawnSync(process.platform === 'win32' ? 'where' : 'which', [cmd], { encoding: 'utf8' });
+  return r.status === 0;
+}
+
+async function doctor(opts) {
+  const { target } = opts;
+  log.title('hero-vibe-kit · doctor');
+  let pass = 0, warn = 0, fail = 0;
+  const ok = (m) => { log.ok(m); pass++; };
+  const wn = (m) => { log.warn(m); warn++; };
+  const er = (m) => { log.err(m); fail++; };
+
+  // config
+  const cfg = readJSON(path.join(target, '.hero-vibe-kit', 'config.json'), null);
+  if (cfg) ok(`config: v${cfg.version} · ${cfg.projectName} · lang=${cfg.lang} · ${cfg.brownfield ? 'brownfield' : 'new'}`);
+  else er('config missing (.hero-vibe-kit/config.json) — run `hero-vibe-kit init`');
+
+  // settings.json
+  const sp = path.join(target, '.claude', 'settings.json');
+  const settings = readJSON(sp, null);
+  if (!exists(sp)) er('.claude/settings.json missing');
+  else if (!settings) er('.claude/settings.json is invalid JSON');
+  else {
+    const cmds = JSON.stringify(settings.hooks || {});
+    cmds.includes('git-guard.cjs') ? ok('settings.json: git-guard hook wired') : wn('git-guard hook not wired in settings.json');
+    cmds.includes('stop-reminder.cjs') ? ok('settings.json: stop-reminder hook wired') : wn('stop-reminder hook not wired');
+  }
+
+  // hook self-tests
+  const gg = path.join(target, '.claude', 'hooks', 'git-guard.cjs');
+  if (exists(gg)) {
+    const block = hookCheck(gg, { tool_name: 'Bash', tool_input: { command: 'git push -f origin main' } });
+    const allow = hookCheck(gg, { tool_name: 'Bash', tool_input: { command: 'git status' } });
+    if (block.code === 2 && allow.code === 0) ok('git-guard self-test: blocks force-push, allows safe git');
+    else er(`git-guard self-test failed (force-push exit=${block.code}, status exit=${allow.code})`);
+  } else er('.claude/hooks/git-guard.cjs missing');
+
+  const sr = path.join(target, '.claude', 'hooks', 'stop-reminder.cjs');
+  if (exists(sr)) {
+    const r = hookCheck(sr, { hook_event_name: 'Stop', stop_hook_active: true, cwd: target });
+    r.code === 0 ? ok('stop-reminder self-test: ok') : er('stop-reminder self-test failed');
+  } else er('.claude/hooks/stop-reminder.cjs missing');
+
+  // doc links
+  const { broken, checked } = checkLinks([path.join(target, 'docs'), path.join(target, 'CLAUDE.md'), path.join(target, 'AGENTS.md')]);
+  if (broken.length === 0) ok(`doc links: ${checked} checked, 0 broken`);
+  else { er(`doc links: ${broken.length} broken`); broken.slice(0, 8).forEach((b) => console.log('    - ' + path.relative(target, b.file) + ' -> ' + b.link)); }
+
+  // tools
+  log.title('Tools');
+  ok(`node: ${process.version} (required)`);
+  status('git', which('git'), 'recommended');
+  status('superpowers skills (skills-lock.json)', exists(path.join(target, 'skills-lock.json')), 'recommended');
+  status('GitNexus index (.gitnexus)', exists(path.join(target, '.gitnexus')), 'optional');
+  status('Serena (.serena)', exists(path.join(target, '.serena')), 'optional');
+
+  function status(name, present, tier) { present ? ok(`${name}: present (${tier})`) : wn(`${name}: absent (${tier})`); }
+
+  log.title(`Result: ${pass} ok · ${warn} warn · ${fail} fail`);
+  process.exit(fail > 0 ? 1 : 0);
+}
+
+module.exports = { doctor };

package/src/init.cjs

@@ -0,0 +1,95 @@
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const { log, ensureDir, exists, backup, writeJSON, makeAsker } = require('./util.cjs');
+const { detect } = require('./detect.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 init(opts) {
+  const { pkgRoot, target, flags } = opts;
+  const templates = path.join(pkgRoot, 'templates');
+  const auto = !!flags.yes;
+  const ask = makeAsker(auto);
+
+  log.title('hero-vibe-kit · init');
+  const d = detect(target);
+  log.step(`Target : ${target}`);
+  log.step(`Mode   : ${d.brownfield ? 'brownfield (existing project)' : 'new project'}`);
+
+  // ---- config ----
+  let cfg = {};
+  if (flags.preset) {
+    const pf = path.join(pkgRoot, 'presets', String(flags.preset) + '.json');
+    if (!exists(pf)) { log.err(`Unknown preset: ${flags.preset}`); ask.close(); process.exit(1); }
+    cfg = JSON.parse(fs.readFileSync(pf, 'utf8'));
+    log.ok(`Preset : ${flags.preset}`);
+  }
+  cfg.projectName = flags.name || cfg.projectName || (auto ? path.basename(target) : await ask.text('Project name', path.basename(target)));
+  cfg.lang = flags.lang || cfg.lang || (auto ? 'en' : await ask.choice('Docs language:', ['en', 'vi'], 0));
+  if (!cfg.teamSize) cfg.teamSize = auto ? 'small-team' : await ask.choice('Team size:', ['solo', 'small-team', 'enterprise'], 1);
+  if (!cfg.branchingModel) cfg.branchingModel = auto ? 'github-flow' : await ask.choice('Branching model:', ['github-flow', 'gitlab-flow', 'trunk'], 0);
+  if (!cfg.enforceLevel) cfg.enforceLevel = 'mixed';
+  cfg.version = JSON.parse(fs.readFileSync(path.join(pkgRoot, 'package.json'), 'utf8')).version;
+  cfg.brownfield = d.brownfield;
+
+  if (cfg.lang !== 'en' && cfg.lang !== 'vi') { log.err(`Unsupported lang: ${cfg.lang} (use en|vi)`); ask.close(); 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,
+  };
+
+  // ---- 1. docs ----
+  const srcDocs = path.join(templates, 'docs', cfg.lang);
+  let docCount = 0, keptActiveState = false;
+  for (const f of renderTree(srcDocs, vars)) {
+    const dest = path.join(target, 'docs', f.rel);
+    if (path.basename(f.rel) === 'ACTIVE_STATE.md' && exists(dest)) { keptActiveState = true; continue; }
+    ensureDir(path.dirname(dest));
+    if (exists(dest)) backup(dest);
+    fs.writeFileSync(dest, f.content);
+    docCount++;
+  }
+  log.ok(`Docs    : ${docCount} file(s) [${cfg.lang}]` + (keptActiveState ? ' · kept existing ACTIVE_STATE.md' : ''));
+
+  // ---- 2. CLAUDE.md / AGENTS.md managed block ----
+  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)}`);
+
+  // ---- 3. 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   : git-guard + stop-reminder installed; settings.json merged');
+
+  // ---- 4. config ----
+  writeJSON(path.join(target, '.hero-vibe-kit', 'config.json'), cfg);
+  log.ok('Config  : .hero-vibe-kit/config.json');
+
+  // ---- 5. optional integrations ----
+  if (!flags['skip-integrations']) {
+    await require('./integrations.cjs').run({ target, cfg, detect: d, ask, pkgRoot });
+  } else {
+    log.warn('Skipped integrations (skills / gitnexus / serena).');
+  }
+
+  ask.close();
+
+  log.title('Next steps');
+  console.log('  1. Review docs/AGENCY_WORKFLOW.md (single source of truth).');
+  console.log('  2. Restart Claude Code (or run /hooks) to activate the git-guard + stop-reminder hooks.');
+  console.log('  3. Fill <TBD> in DEFINITION_OF_DONE / SECURITY_STANDARDS / PERFORMANCE_STANDARDS when you pick a stack.');
+  console.log('  4. Run: npx hero-vibe-kit doctor');
+}
+
+module.exports = { init };